chore(router): regenerate per-module route type files and gate them in CI - #1127

devcorner: dc-t21

Per-module <module>.gen.ts files were committed but never kept current: only the rango generate CLI writes them, and nothing in CI or the hooks ran it. At 8a843aa, 16 of 60 files were stale (test-app type-stress-test.gen.ts had 214 lines against 1,114 generated; pages/articles.gen.ts lacked a route) and 131 modules had no file. A second problem hid underneath: the route names in *.gen.ts were sorted with a bare localeCompare, so the order followed the machine's locale (Czech sorts "ch" after "h"). Two machines wrote different files from the same routes, so a freshness check on one would report the other's files as stale.

Before and after

# before: nothing noticed a stale per-module file
git push                  # CI green with urls/blog.gen.ts out of date

# after: the same push
pnpm check:route-gen      # exit 1: "stale: apps/.../urls/blog.gen.ts"
node tools/generate-route-types.mjs   # rewrites it; commit the result

Consumers of @rangojs/router see one change: generated route files list names in the same order on every machine. Nothing to change in app code.

End-to-end example

A contributor adds path("/archive", ..., { name: "archive" }) to src/urls/blog.tsx and forgets the gen file.

1. Pre-commit (lefthook route-gen job, gated on app sources, src/build/route-types/** and the tool) runs node tools/generate-route-types.mjs --check and fails, listing blog.gen.ts as stale.
2. They run node tools/generate-route-types.mjs, commit the rewritten file, and the check passes.
3. CI lint runs pnpm check:route-gen as well, so --no-verify does not get around it.

Semantics

Code changes

• tools/generate-route-types.mjs (new): bundles the router's per-module writer from src with esbuild (in memory, packages: "external", no router build), runs it over every app that depends on @rangojs/router. --check takes about 0.45 s.
• src/build/route-types/per-module-writer.ts: split into a pure planPerModuleRouteTypesForFile and the unchanged write wrapper (placeholder only if missing, diff-before-write, catch-and-warn), so the tool needs no fs shim. Not a package export.
• src/build/route-types/codegen.ts: generatePerModuleTypesSource and generateRouteTypesSource sort with localeCompare(b, "en"). Why here: both generators feed every writer, so the pin covers the CLI, Vite and the tool.
• apps/docs/scripts/gen-content.mjs: --check flag, "en" sort.
• Wiring: package.json (check:route-gen, generate:route-types), .github/workflows/e2e.yml lint job, lefthook.yml pre-commit job, AGENTS.md Hard rule 2 clause.
• 167 files: 139 new and 18 refreshed *.gen.ts, plus the above.

Locale fix, key lines:

// codegen.ts
names.sort((a, b) => a.localeCompare(b, "en"));

Test plan

• packages/rangojs-router/src/build/__tests__/generate-route-types.test.ts (new): stubs localeCompare to default to Czech; ["hat", "charts"] comes out hat, charts without the pin and charts, hat with it. Red before the pin, green after.
• pnpm check:route-gen on the rebased tree: 198 per-module files, 198 current, 0 stale, 0 missing, 0 orphan (16 apps, 1,028 source files).
• Red-before-green for the gate (dc-c150): a stale file makes --check exit 1; a broken writer exits non-zero without deleting anything; write mode on a clean tree gives zero diff.
• pnpm run typecheck 16/16
• pnpm run test:unit:all: router 8,716 passed (5 skipped, 6 todo), rsc 830 passed (2 expected fail), plus consumer suites 1, 3, 20, 25, 26, 27, 85 passed
• pnpm run lint: 0 warnings, 0 errors
• pnpm run format: clean
• pnpm check:e2e-bucketing: OK
• Route-types e2e, dev and production, 12/12, and route-types HMR 21 (run on the pre-rebase tree, dc-c158); CI runs e2e for this tree.

Notes

• After this lands, a branch that adds routes must run node tools/generate-route-types.mjs and commit the result (Nested unnamed include() never matches: its routes answer 404 with no warning #1104/testing: after serveShellRequest serves a router, dispatch on the same router stops 308-redirecting a trailing-slash URL #1107 and the intercept redesign are the next ones). Branches opened before this lands do not have the files.
• The CHANGELOG "Fixed" entry covers the sort order. The tool and the check are repo tooling, not consumer-visible.
• Rebased onto 0.24.1; the only conflict was CHANGELOG (new ## Unreleased above ## 0.24.1).