Skip to content

refactor(scripts): Trim comment sprawl in scripts - #1726

Merged
omesser merged 4 commits into
mainfrom
chore/1604-no-comments
Oct 20, 2026
Merged

omesser merged 4 commits into
mainfrom
chore/1604-no-comments

Conversation

@omesser

@omesser omesser commented Oct 20, 2026 •

Copy link
Copy Markdown
Owner

Why

Comment sprawl is back per #1597. Section 7 (scripts/**, packaging/**) held 2,642 full-line comment lines across 127 commented files at today's main, a comment/code ratio of 0.121. Much of it narrated how the code came to be, restated the function name on the line below, drew section banners, or cited an issue number whose sentence already stated the fact.

This PR applies pstack's /no-comments posture over section 7 of #1597 and lands only the comment edits. docs/agents/vendored-skills.md says not to run /no-comments in this repository, so Comment Sicko was the candidate list and every edit is held to docs/agents/comments.md, the bar #1604 names.

The counts below are measured on today's main, not on 83733db9, the commit #1597 measured. That is why they differ from the 2,356 comment lines and 119 files section 7 quotes.

What changed

Comments only. No code, strings, here-docs, docstrings, attributes, or behavior changed.

  • Size: 230 lines added, 498 deleted, net 268 fewer.

  • Scope: 86 of the 149 files under the two globs changed. Fixtures, the ast-grep rule tests, files whose comments already earned their lines, and the four Homebrew files described under Notes are untouched.

  • Comment lines: 2,642 to 2,400 across the 127 commented files, ratio 0.121 to 0.110. Non-comment lines are 21,755 in both trees, which is the same audit the diff check below reports from another angle.

  • Removed: section banners, history ("used to", run 114714, "the hand-kept copy this replaces"), docs that repeat a function's name, and issue numbers whose fact the sentence states.

  • Compressed, not dropped: platform and tool facts (Win32 and UI Automation, WebView2 profile locking, WindowServer, X11 root coordinates, ffmpeg, powermetrics), bounds that look arbitrary, cleanup ordering, and rejected alternatives.

  • Printed scenario headers: the 36 scripts under scripts/scenarios/ print their top comment block as the takeover prompt. crates/verify/src/scenario.rs parses and prints it, and each script's own sed/$header does the same. Those 666 lines are operator-facing runtime output, not comments a reader of the source meets. This pass left them byte-identical and treats the 3-line bar as not reaching them. That reading is a decision for the gate, not a finding this PR can settle on its own: if the gate reads docs/agents/comments.md as covering printed text too, the fix is a separate change to those prompts and the parser together, not a trim hidden in this diff.

  • Soft review fixes: ax-window-win.ps1 now names click and menu as the only commands that skip -ProcessId/-Title; bench-rss-macos.sh drops its stub usage line and says plainly that MallocStackLogging inflates footprint; perch-window.swift no longer repeats the usage string it prints on a bad argument.

Language Files Added Deleted
Bash (.sh) 47 131 218
PowerShell (.ps1) 19 56 141
Python (.py) 8 6 68
Swift (.swift) 9 33 62
JavaScript (.mjs) 2 1 5
Batch (.cmd) 1 3 4
Total 86 230 498

The pass's report

Deletion count

498 lines deleted, 230 added across 86 files. Comment lines in scope: 2,642 to 2,400.

Restores

No comment was deleted and then restored. Three delegates briefly removed a code line (lib/x11.sh, hero-gif.sh, test-trace-formats.ps1) and restored it byte-for-byte before finishing. The skeleton check under How to verify covers the final tree, not their interim state.

Constraints kept as comments, compressed rather than dropped: the restart-manager pids and the fullscreen app that are never killed (chat-close-pill-type.win.ps1), Never kill on a stale WebView2, TextEdit's unsaved work (chat-close-pill-type.sh), the Harness process group outliving Fidget (wait-helpers.sh), -A for development only (dev-sign.sh), the placeholder sizes GDK leaves (lib/x11.sh), the icon and character art bounds, the 10 Hz poll coupling on perch-window.swift, and reassertInterval sitting under the app's poll interval.

Fixes

None applied here, by #1604's comments-only rule. Each one found on the way is filed below.

Encoding offers

Four constraint families survive as comments with their encoding filed as an issue: scenario cleanup never kills a user's app (#1722), no Harness process group is left behind (#1723), the art generators' pixel bounds (#1724), and the Settings overlay placeholder sizes (#1725).

Exceptions kept on purpose

  • Four-line headers: three survive at four lines, each line a distinct fact: ax-window-win.ps1 (the dump contract, then why FromHandle), scenarios/pixel-stats.swift (the metric, how to read it, the usage line), and scenarios/fixture-harness.cmd (preflight, %*, the libtest filters). Trimming any of them means dropping a fact, not a restatement.
  • ponytail: blocks: refuse-no-verify.sh keeps its five-line marker (ceiling, cost, when to port the node tokenizer). docs/agents/comments.md allows that block past the ceiling.
  • JSDoc @param blocks: scripts/frame-cadence.mjs keeps two. The parenthetical on window is the only place the "Unix ms, inclusive" unit is written down; the type names alone do not carry it.
  • Directives and HERE-doc payloads: # shellcheck, #requires, PowerShell comment-based help that Get-Help reads, Python docstrings, and the Swift/Python payloads inside shell here-docs are code or runtime text, not comments.

The rest of the changed files are at or under three lines per block, apart from the printed scenario headers above.

Open work

  • Printed scenario headers, described above. They are the one place in this section where a 40-line block stays on purpose, and the reading behind that is the gate's to confirm.
  • .ps1, .cmd, and .toml are not covered by the ast-grep comment-block ceiling, as docs/agents/comments.md already records. This section is mostly .ps1 and .sh, so the ceiling saw less of it than the counts suggest.
  • crates/verify/src/scenario.rs drops blank lines when it builds a header while each script's sed prints them. No scenario has an interior blank line today, so nothing differs; the two readers are still not the same one.
  • Outside this section: tests/verify-chat-perch-win.test.js and tests/ax-settings-win-finder.test.js still narrate Verify Chat-as-Perch (#1499) live on Windows and macOS #1502 and fix(verify): Find webview Settings window on Windows UIA #805. Those paths belong to section 6.
  • The Homebrew cask pins v0.2.0 while livecheck's latest is v0.6.1, so its workflow fails on main. That is why the four cask files are unchanged here. fix(ci): Bump the Homebrew cask so its verification passes #1727.

Skips

Left alone under "stop when you do not understand", or because the text is not a comment:

  • chat-close-pill-type.x11.sh readiness note: the issue it links (X11: a click on the sprite right after launch can leave the keyboard with Fidget #1578) is the only trace of a suspected flake.
  • wait-helpers.win.ps1 "A pipe since Windows reports writes" and poke-mid-climb.sh "Resting and not walking": the referent is not in the file.
  • Here-doc payloads (the Swift and Python blocks inside shell scripts), Python docstrings, PowerShell comment-based help consumed by Get-Help (verify-settings-webview-phase2-win.ps1), # shellcheck and #requires directives, and the ast-grep test fixtures. These are code or runtime output in this pass.
  • verify-chat-perch-win.ps1's header, which the script prints verbatim when --go is absent.

Follow-up issues

Sub-issues of #1604, each with V1, ready-for-agent and a priority label.

How to verify

  • Comments only: a script compares each changed file's non-comment skeleton against origin/main (comments dropped, trailing comments stripped, blank lines ignored). All 86 match, so no code line moved.
  • Scope: every changed path matches scripts/** or packaging/**.
  • Pre-commit: green over all 86 files, including the ast-grep comment-block ceiling, codespell, shfmt, shellcheck, PSScriptAnalyzer, the PowerShell ASCII check, and the swiftc typecheck.
  • Syntax: bash -n on the 47 shell files, the PowerShell parser on the 19 .ps1, python3 -m py_compile on 8, node --check on 2, swiftc -parse on 9.
  • Rust: cargo test -p fidget --all-targets reports 924 passed, 7 ignored. cargo test -p fidget-verify reports 11 passed, which covers the scenario index that parses these headers.
  • Node: node --test tests/*.test.js runs 783 tests with 3 failures. All three reproduce on origin/main on this macOS host: two bench-gpu-compositing-linux process-detection tests that need a Linux display, and one timing flake in verify-fidget-helpers.

Notes

Windows and X11 leaves do not run here. Their edits are comment-only, and the parser, shellcheck, and CI cover them.

The four Homebrew files (packaging/homebrew/Casks/fidget.rb, scripts/homebrew-cask.rb, scripts/verify-homebrew-cask.sh, scripts/bump-homebrew-cask.sh) went back to main unchanged. The Homebrew cask workflow triggers on any of those paths and is red on main because the cask pins v0.2.0 while livecheck's latest is v0.6.1. Those comments wait for a pass that lands after the bump, filed as #1727.

Closes #1604

— OpenCode agent, on @omesser's behalf.

Comment-only pass over scripts/** and packaging/** for #1604. 509 lines deleted, 232 added; printed scenario takeover headers left alone because the scripts print them at runtime.
@omesser omesser added refactoring windows Run the Windows compile job on this pull request linux Linux platform lane: X11, GTK, portals, packaging macos macos / OSX specific labels Oct 20, 2026
The cask verification workflow triggers on these four paths and is red on main: the cask pins v0.2.0 while livecheck's latest is v0.6.1. Their comment edits wait for a pass that can land after the bump.
omesser

This comment was marked as outdated.

Applies the review findings: state each comment's reason plainly, drop
restated code and stale issue numbers, and keep the printed scenario
headers byte-identical.

Part of #1604.
omesser

This comment was marked as outdated.

@omesser omesser changed the title refactor: Trim comment sprawl in scripts and packaging refactor(scripts): Trim comment sprawl in scripts Oct 20, 2026
Soft review on #1726: most ax-window commands require -Title, and two
header lines read as jargon or repeated a printed string.
@omesser

omesser commented Oct 20, 2026

Copy link
Copy Markdown
Owner Author

Addressed both Soft reviews on tip 39e39fde.

  • ax-window-win.ps1 header (Soft-FIX): the -Title clause was false for dump, size, press, link and tray. The block now says every command but click and menu wants -ProcessId and -Title, which matches the guard on line 24. Still four lines, still comment-only.
  • bench-rss-macos.sh jargon (non-blocking): "Logging adds Performance Tool Data" is now "That logging inflates footprint, so take RSS from a plain run", the same wording the run echoes at line 97.
  • bench-rss-macos.sh usage line (non-blocking): dropped. The case block lists the flags and the script rejects an unknown one.
  • perch-window.swift header (non-blocking): the usage sentence is gone; the script prints the same string on a bad argument, and the block is now three lines.

The diff from 64dfee4f touches comment lines only. Pre-commit is green on all 86 changed files and the comment-stripped skeleton still matches origin/main. Counts in the description are updated: 230 added, 498 deleted, comment lines 2,642 to 2,400.

— OpenCode agent, on @omesser's behalf.

@omesser omesser left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Soft CLEARED

Tip: 39e39fde

What changed

  • -Title claim: The ax-window-win.ps1 header now says every command but click and menu needs -ProcessId and -Title, which matches the guard on line 24. That clears the last Soft-FIX.
  • Plainer headers: bench-rss-macos.sh replaces the Performance Tool Data line with "inflates footprint". It and perch-window.swift drop their usage lines.

What is wrong
Nothing blocking.

Soft-FIX
None.

Checked each new comment against the code at the tip, that perch-window.swift still prints its usage line from code, and that the diff from 64dfee4f changes only comment lines.

— Cursor agent (Architect), on @omesser's behalf.

@omesser
omesser merged commit bed8b92 into main Oct 20, 2026
6 checks passed
@omesser omesser mentioned this pull request Oct 20, 2026
4 tasks done
@omesser
omesser deleted the chore/1604-no-comments branch October 21, 2026 06:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

linux Linux platform lane: X11, GTK, portals, packaging macos macos / OSX specific refactoring windows Run the Windows compile job on this pull request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

No comments: Scripts and scenarios

1 participant