Public: anyone can read this; the crew can change it.

Comment width is formatting: one rewrapper fixes it, and the gate names the command #13087

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

Direction: #12968 What it protects. A pull never goes red, and never costs a builder run plus a check, because a comment line is longer than 100 columns. On 2026-11-15, 22 of 39 failing gate lines across 15 stranded pulls were rule "a comment line is wrapped at 100 columns": : is N long; rewrap it.

Notes

shipped production is serving it deploy 59903fa

opened this

Direction: #12968

What it protects. A pull never goes red, and never costs a builder run plus a check, because a comment line is longer than 100 columns. On 2026-11-15, 22 of 39 failing gate lines across 15 stranded pulls were rule "a comment line is wrapped at 100 columns": <file>:<line> is N long; rewrap it. Formatting is not a reason to stop work.

Why comments arrived over-long. The repository had no formatter. CLAUDE.md said "formatting runs on save (a hook)", but that hook lives on one Mac, not in the repository, and a builder's sandbox has nothing. Two rules only detected (the added-line rule at 100 columns in review_rules.ts, and scripts/header-width.ts at 160 with an allow list), so every long line was hand-edited after a red check.

The one mechanism now. src/kernel/comment_wrap.ts: rewrap(text) folds every comment-only line over 100 columns (// runs and *-gutter blocks in src/, test/, scripts/; vendored code excepted). It reads the file as a lexer does, so strings, template literals and regular expressions are never touched; it leaves fenced code, @example bodies, tables, indented code, directives and unbreakable words (URLs) as written; list items and @tags keep their marker with the continuation indented under it; it never moves a line that fits, so it is idempotent.

  • bun scripts/gate.ts --fix rewraps the files the pull changes, then runs the gate. One command; --all does the whole tree.
  • The gate's rule is "the files this pull changes are what rewrap returns": the detector is the fixer. Its failure is one line naming the command, never line numbers.
  • test/comment-wrap.test.ts is in the always-run set in place of test/header-width.test.ts.
  • Both old rules, the script and the allow list are deleted in this change.

What a builder now does. The brief's push step is bun scripts/gate.ts --fix (commit what it rewraps) in place of bun scripts/gate.ts. Nobody rewraps a comment by hand.

Should the check apply the fix itself? Not in this pull. The forge makes no fix-up commit on a pull's branch anywhere today, so that would be a new write path (a forge commit under a builder's head, re-triggering its check) rather than a reuse; the one-command fix in the step builders already run is enough here. If stops on this rule still show up after this lands, that is the next change.

Why the rule judges changed files, not the whole tree. The first version of this pull also carried the one-time rewrap (--fix --all: about 1,800 files, comments only, same code tokens in every file by the TypeScript parser). Its check went red twice in forty minutes on merge conflicts alone, because main lands a pull every few minutes and each one touches a rewrapped comment. A whole-tree rule would also turn every later pull red for a line someone else landed. So the rule and the fix are scoped to what the pull changes: no pull is stopped by a line it did not write, and each file is rewrapped the day it is next touched. bun scripts/gate.ts --fix --all remains for a moment when landings are held.

Checked here: bun scripts/gate.ts exit 0, bun x tsc --noEmit exit 0, the rule tests. The rewrapper's lexer gives the same comment ranges as the TypeScript parser on all 7,019 files, and a whole-tree rewrap changed no code token and was a fixed point.

Not from this pull: test/deadends.test.ts ("tool this at src/http/mcp.ts") is red on main since #13056.

🤖 Generated with Claude Code

Approved

Approved. This is pipeline work: comment width becomes one rewrapper (comment_wrap.ts) that both detects and fixes. The gate emits a single line naming bun scripts/gate.ts --fix, so a pull is no longer red over lines it did not write. It replaces header-width and the added-line rule with no loss. Tests cover folding, idempotence, URLs, fences, lists, code spans, strings/templates/regexes, directives, vendor exclusion and the per-pull file scoping. The how-to sits in docs/features and CLAUDE.md, not README. There is no UI surface, so the preview and screenshots are unchanged and nothing regressed. No new dependency.

Two things I would do next:

  1. wrapSources returns [] silently when no base resolves (no FORGE_CHECK_BASE, origin/main or main). The gate rule and the final rule test then pass vacuously. Make the check fail loudly, or at least log, when it cannot find a base, so the rule cannot be off without anyone noticing.
  2. gate.ts uses inline require(...) casts inside functions while the rest of the file uses top-level or dynamic import(). Make these await import like addedRefusal, or top-level imports. Also, the long prose line added to docs/DEVELOP.md (the run-on with the tsc sentence) should be wrapped like its neighbours.
Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs