Skip to content

Apply the comment-voice rules and check them in the gate - #1425

Merged
Kevinjohn merged 16 commits into
mainfrom
feature/comment-voice-sweep
Oct 1, 2026
Merged

Kevinjohn merged 16 commits into
mainfrom
feature/comment-voice-sweep

Conversation

@Kevinjohn

@Kevinjohn Kevinjohn commented Oct 1, 2026 •

Copy link
Copy Markdown
Owner

Part of #1409 (T13). Merge predecessors: #1424 (this PR's base branch, feature/route-handlers) and #1415, which states the comment rules this applies (DEFENSIVE-CODING.md §7).

  • New scripts/check-comment-voice.mjs (pnpm run policy:comment-voice, run by both gates). It reads comments through the TypeScript parser, so strings, template literals and JSX text are never checked. It fails on ticket and plan labels, em-dashes, section banners, hanging TSDoc indentation and a TODO without an issue URL. Its test plants each violation plus negative cases.
  • Sweep of src/, shared/ and server/src/ (about 590 files), comment tokens only:
    • plan and ticket labels and banners removed;
    • TSDoc continuation indentation flattened;
    • em-dashes replaced;
    • capitals used for emphasis lowered (acronyms kept).
  • A token comparison with comments stripped shows no non-comment change in any swept file. String literals, including released migration definitions and test titles, are untouched.

Validation: Integrated Batch 4 tip (all five Batch 4 branches): pnpm run gate:all and pnpm run e2e (290 passed) on Node 24.16.0. Later changes on the stack touch only comments, the comment checker and two reference pages; on the final tip typecheck, lint, format, the comment-voice check and its test, ui:check, docs:build and pnpm run gate:server pass. Independently reviewed; findings applied. A token comparison with comments stripped confirms no non-comment change.

Merge order

  1. Route support to Discussions and remove PR screenshots #1411, Add project status, comparison, testing and philosophy pages #1412, Archive changelog sections before 0.41.0-alpha.3 #1414 (independent)
  2. Add a first-change path for contributors #1413 (after Archive changelog sections before 0.41.0-alpha.3 #1414), Restate the comment standard as numbered voice rules #1415, Reduce configuration and hide password MFA #1416
  3. Rename SMALLSASS_ACCOUNT_ settings to CAPACITYLENS_ #1417 → Add an init command that writes the environment file #1418
  4. Retire unused settings and derive engagement grouping #1419 → Move diagnostics to an Owner and Admin page #1420 → Reshape the documentation into four role guides #1421 → Use @/ for app imports that leave their folder #1422 → Consolidate server test scaffolding #1423 → Normalise server route handlers and reply messages #1424 → Apply the comment-voice rules and check them in the gate #1425 (Apply the comment-voice rules and check them in the gate #1425 also after Restate the comment standard as numbered voice rules #1415) → Name the tenant boundary account in code #1426

Merge predecessor for this PR: #1424 and #1415.

Scans comments in src, shared and server/src with the TypeScript scanner and reports ticket
references, em-dashes, section banners, hanging TSDoc indents and TODOs without an issue URL.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Comments now explain the code without plan task labels, issue numbers or divider banners.
The checker's phase pattern no longer matches identifiers such as phase1.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Continuation lines start with a single space after the asterisk. Fenced code, examples and
Markdown list continuations keep their indentation.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Paired dashes become commas or parentheses, a term followed by a dash becomes a colon, and
a dash before an independent clause becomes a full stop. Only comment tokens change.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Emphasis comes from wording. Acronyms, SQL keywords, HTTP methods, code identifiers and
document names keep their capitals.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Adds policy:comment-voice and its test to the structural checks and documents the check.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Flags Stage and plan-exception labels, short box-drawing banners and indented TSDoc tag lines,
and pins the URL, JSX text, JSDoc and doc-comment boundaries with fixtures.

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
… references in comments

Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
@Kevinjohn

Copy link
Copy Markdown
Owner Author

Polish review: no P1/P2 findings.

  • Mechanical check: each changed TypeScript or JavaScript file was printed with comments stripped, before and after this PR's own range. Every file is identical except:
    • the new check-comment-voice script and its test;
    • its two gateCommands entries;
    • the updated tooltip.tsx checksum in check-ui-primitives.mjs.
  • policy:comment-voice and its test pass. The docs build shows no drift.
  • Ladder passes on Node 24: format, lint, typecheck, file sizes and server tsc.
  • No conflict with Restate the comment standard as numbered voice rules #1415.
  • None of the earlier independent PRs adds source comments that the new check would reject.

Merge order for this batch: #1411, #1412, #1414 → #1413, #1415, #1416 → #1417 → #1418, #1419 → #1420 → #1421 → #1422 → #1423 → #1424 → #1425 → #1426. Predecessor: #1424 and #1415.

@Kevinjohn Kevinjohn added polish-done Polish review complete and removed polish-in-progress Polish review running labels Oct 1, 2026
…-sweep

# Conflicts:
#	docs/reference/development.html
Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
Signed-off-by: Kevinjohn Gallagher <kevinjohngallagher@hotmail.com>
@Kevinjohn
Kevinjohn merged commit a2b20ae into main Oct 1, 2026
5 checks passed
@Kevinjohn
Kevinjohn deleted the feature/comment-voice-sweep branch October 1, 2026 21:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

polish-done Polish review complete

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant