Repository navigation
refactor(scripts): Trim comment sprawl in scripts - #1726
Merged
Merged
Conversation
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.
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.
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.
Soft review on #1726: most ax-window commands require -Title, and two header lines read as jargon or repeated a printed string.
Owner
Author
|
Addressed both Soft reviews on tip
The diff from — OpenCode agent, on @omesser's behalf. |
omesser
commented
Oct 20, 2026
omesser
left a comment
Owner
Author
There was a problem hiding this comment.
Soft CLEARED
Tip: 39e39fde
What changed
-Titleclaim: Theax-window-win.ps1header now says every command butclickandmenuneeds -ProcessId and -Title, which matches the guard on line 24. That clears the last Soft-FIX.- Plainer headers:
bench-rss-macos.shreplaces the Performance Tool Data line with "inflates footprint". It andperch-window.swiftdrop 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.
4 tasks done
This was referenced Oct 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Comment sprawl is back per #1597. Section 7 (
scripts/**,packaging/**) held 2,642 full-line comment lines across 127 commented files at today'smain, 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-commentsposture over section 7 of #1597 and lands only the comment edits.docs/agents/vendored-skills.mdsays not to run/no-commentsin this repository, so Comment Sicko was the candidate list and every edit is held todocs/agents/comments.md, the bar #1604 names.The counts below are measured on today's
main, not on83733db9, 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.rsparses and prints it, and each script's ownsed/$headerdoes 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 readsdocs/agents/comments.mdas 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.ps1now namesclickandmenuas the only commands that skip-ProcessId/-Title;bench-rss-macos.shdrops its stub usage line and says plainly that MallocStackLogging inflates footprint;perch-window.swiftno longer repeats the usage string it prints on a bad argument..sh).ps1).py).swift).mjs).cmd)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 killon a stale WebView2, TextEdit's unsaved work (chat-close-pill-type.sh), the Harness process group outliving Fidget (wait-helpers.sh),-Afor development only (dev-sign.sh), the placeholder sizes GDK leaves (lib/x11.sh), the icon and character art bounds, the 10 Hz poll coupling onperch-window.swift, andreassertIntervalsitting 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
ax-window-win.ps1(the dump contract, then whyFromHandle),scenarios/pixel-stats.swift(the metric, how to read it, the usage line), andscenarios/fixture-harness.cmd(preflight,%*, the libtest filters). Trimming any of them means dropping a fact, not a restatement.ponytail:blocks:refuse-no-verify.shkeeps its five-line marker (ceiling, cost, when to port the node tokenizer).docs/agents/comments.mdallows that block past the ceiling.@paramblocks:scripts/frame-cadence.mjskeeps two. The parenthetical onwindowis the only place the "Unix ms, inclusive" unit is written down; the type names alone do not carry it.# shellcheck,#requires, PowerShell comment-based help thatGet-Helpreads, 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
.ps1,.cmd, and.tomlare not covered by the ast-grep comment-block ceiling, asdocs/agents/comments.mdalready records. This section is mostly.ps1and.sh, so the ceiling saw less of it than the counts suggest.crates/verify/src/scenario.rsdrops blank lines when it builds a header while each script'ssedprints them. No scenario has an interior blank line today, so nothing differs; the two readers are still not the same one.tests/verify-chat-perch-win.test.jsandtests/ax-settings-win-finder.test.jsstill 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.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.shreadiness 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" andpoke-mid-climb.sh"Resting and not walking": the referent is not in the file.Get-Help(verify-settings-webview-phase2-win.ps1),# shellcheckand#requiresdirectives, 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--gois absent.Follow-up issues
Sub-issues of #1604, each with V1,
ready-for-agentand a priority label.How to verify
origin/main(comments dropped, trailing comments stripped, blank lines ignored). All 86 match, so no code line moved.scripts/**orpackaging/**.bash -non the 47 shell files, the PowerShell parser on the 19.ps1,python3 -m py_compileon 8,node --checkon 2,swiftc -parseon 9.cargo test -p fidget --all-targetsreports 924 passed, 7 ignored.cargo test -p fidget-verifyreports 11 passed, which covers the scenario index that parses these headers.node --test tests/*.test.jsruns 783 tests with 3 failures. All three reproduce onorigin/mainon this macOS host: twobench-gpu-compositing-linuxprocess-detection tests that need a Linux display, and one timing flake inverify-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 tomainunchanged. The Homebrew cask workflow triggers on any of those paths and is red onmainbecause 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.