#443 Replace dashed separator comments with headings or region folds

[williamthorsen]

What

Removes the noisy boxed and rulered comment separators that had accumulated across the codebase and replaces every occurrence with one of two canonical forms — a single-line // -- Label -- inline heading or a // region | Label / // endregion | Label fold — producing the same visual structure in roughly a third of the vertical space and without the awkward wrapping that full-width bars caused in narrow viewports.

Introduces a reusable sweep script (scripts/replace-separator-comments.ts) that recognises five separator variants (3-line dash box, 3-line equals box, 3-line block-comment box, single-line symmetric, and single-line asymmetric rulered) and rewrites each to its canonical form, with a small regex classifier that promotes supporting-code labels (Helpers, Test helpers, Sub-function X, Types, Styles, Getters, Type guards) to region folds. A file can opt out of the sweep with a // separator-sweep: skip marker.

Documents the convention in the code-patterns skill so future agent-generated TypeScript follows the same rule.

Why

Over many PRs, contributors (human and agent) had accumulated 3-line ASCII-art boxed separators throughout the codebase — around 350 across nearly 40 files. They wrapped awkwardly in narrow viewports and added visual noise without communicating anything a single-line heading does not already convey. Establishing the canonical forms, codifying them in the code-patterns skill, and providing a script that can be rerun make it easy to keep the convention in place as the codebase grows.

Details

Refactoring

Applies the canonical form across every TypeScript source file in packages/** and config/** (plus the one scripts/ file introduced in this branch). Manual follow-ups fix two multi-line-label boxes in moderately-complex-run.ts that the script leaves alone by design, two false-positive region folds where the label happened to contain the word type (optional field type validation, executeTransitions — dispatch by type), and one over-extended region in event-folder.ts where the heuristic placed the endregion at EOF instead of at the end of the helper block.

Tooling

The sweep script lives at scripts/replace-separator-comments.ts. It accepts --dry-run (prints a positional diff) and --glob <pattern> (overrides the default packages/**, config/**, and scripts/** set). Every exported and internal function carries a one-line description, and the complexity of findReplacements is kept under the project's cyclomatic-complexity limit by extracting each recognizer (matchLineBox, matchBlockBox, matchSingleLine) into its own matcher. Region termination is detected by scanning forward for the next separator at the same indent, falling back to EOF — a heuristic that worked for every file in the codebase and is cheap to correct manually in the rare case it overshoots.

Tests

Adds 37 unit tests in scripts/__tests__/replace-separator-comments.test.ts covering each recognizer, the foldable/non-foldable classifier (including word-boundary behavior so Typescript config and Stylesheet loader do not match), region termination (next-separator and EOF cases), indent-aware nesting (a separator inside a describe block is treated independently of outer separators), idempotency (the sweep is a no-op on its own canonical output), and the file-level opt-out marker.

Dependencies

No new runtime or dev dependencies. The script uses only the existing glob dev dependency and Node built-ins, and runs via tsx.

Closes #443

[github-actions]

Dependency audit

Production dependency audit passed.