@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +312 -3
  3. package/README.vi.md +281 -0
  4. package/audit/audit.mjs +3035 -0
  5. package/package.json +26 -5
  6. package/templates/README.md +257 -0
  7. package/templates/adr-README.md +57 -0
  8. package/templates/branch-name.yml +51 -0
  9. package/templates/ci-laravel.yml +540 -0
  10. package/templates/ci-node.yml +291 -0
  11. package/templates/ci-python.yml +281 -0
  12. package/templates/deploy-xserver.yml +531 -0
  13. package/templates/dist-refs.yml +177 -0
  14. package/templates/docs-lint.mjs +993 -0
  15. package/templates/docs-lint.yml +55 -0
  16. package/templates/gotchas-d-README.md +41 -0
  17. package/templates/identity-vocabulary.example +58 -0
  18. package/templates/npx-launcher.mjs +213 -0
  19. package/templates/pre-commit-dispatch +88 -0
  20. package/templates/pre-commit-identity +267 -0
  21. package/templates/pre-push-guard +137 -0
  22. package/templates/release-auto.yml +475 -0
  23. package/templates/release-tag.yml +245 -0
  24. package/templates/repo-CLAUDE-block.md +21 -0
  25. package/tools/colab +13806 -0
  26. package/tools/lib/adopt.js +882 -0
  27. package/tools/lib/axis-authority.js +96 -0
  28. package/tools/lib/base-ci-verdict.js +93 -0
  29. package/tools/lib/blocked-by.js +262 -0
  30. package/tools/lib/branch-name.js +137 -0
  31. package/tools/lib/checklist.js +143 -0
  32. package/tools/lib/ci-cure.js +512 -0
  33. package/tools/lib/ci-grant.js +307 -0
  34. package/tools/lib/ci-verdict.js +113 -0
  35. package/tools/lib/claim-comments.js +212 -0
  36. package/tools/lib/claim-identity.js +195 -0
  37. package/tools/lib/codeowners.js +208 -0
  38. package/tools/lib/consumer-evidence.js +74 -0
  39. package/tools/lib/container-close.js +141 -0
  40. package/tools/lib/cure-diff.js +267 -0
  41. package/tools/lib/decision-record.js +335 -0
  42. package/tools/lib/dirty-owner.js +150 -0
  43. package/tools/lib/disposition.js +378 -0
  44. package/tools/lib/docs-only.js +156 -0
  45. package/tools/lib/exposure-shape.js +207 -0
  46. package/tools/lib/gate.js +80 -0
  47. package/tools/lib/git.js +1059 -0
  48. package/tools/lib/group-labels.js +120 -0
  49. package/tools/lib/hermetic.js +193 -0
  50. package/tools/lib/identity.js +187 -0
  51. package/tools/lib/install-check.js +278 -0
  52. package/tools/lib/instruction-file.js +302 -0
  53. package/tools/lib/journal.js +430 -0
  54. package/tools/lib/labels.js +653 -0
  55. package/tools/lib/landed.js +230 -0
  56. package/tools/lib/local-adopt.js +133 -0
  57. package/tools/lib/lockfile-drift.js +119 -0
  58. package/tools/lib/machine-trailer.js +83 -0
  59. package/tools/lib/machine.js +238 -0
  60. package/tools/lib/migration-grant.js +641 -0
  61. package/tools/lib/migration-paths.js +135 -0
  62. package/tools/lib/notify-endpoint.js +170 -0
  63. package/tools/lib/notify.js +188 -0
  64. package/tools/lib/npm-publish-guard.js +242 -0
  65. package/tools/lib/orphan-worktree.js +127 -0
  66. package/tools/lib/owner-branch.js +182 -0
  67. package/tools/lib/place.js +782 -0
  68. package/tools/lib/ports.js +167 -0
  69. package/tools/lib/procs.js +185 -0
  70. package/tools/lib/readiness.js +240 -0
  71. package/tools/lib/records.js +185 -0
  72. package/tools/lib/refs-brake.js +95 -0
  73. package/tools/lib/release-channel.js +99 -0
  74. package/tools/lib/release-cut.js +822 -0
  75. package/tools/lib/release-finalize.js +521 -0
  76. package/tools/lib/release-policy.js +358 -0
  77. package/tools/lib/release-tag.js +225 -0
  78. package/tools/lib/ship-batch.js +277 -0
  79. package/tools/lib/ship-roles.js +71 -0
  80. package/tools/lib/ship-target-sync.js +181 -0
  81. package/tools/lib/shipguard.js +317 -0
  82. package/tools/lib/shipped-branch.js +56 -0
  83. package/tools/lib/solo.js +213 -0
  84. package/tools/lib/squash.js +515 -0
  85. package/tools/lib/stale-base.js +70 -0
  86. package/tools/lib/stamp.js +740 -0
  87. package/tools/lib/state.js +262 -0
  88. package/tools/lib/teardown.js +83 -0
  89. package/tools/lib/trust-humans.js +104 -0
  90. package/tools/lib/util.js +98 -0
  91. package/tools/lib/wake.js +188 -0
  92. package/tools/lib/workflow-triggers.js +273 -0
  93. package/tools/lib/writes-authority.js +237 -0
  94. package/tools/lib/yaml.js +101 -0
  95. package/bin/cli.js +0 -3
@@ -0,0 +1,993 @@
1
+ #!/usr/bin/env node
2
+ // docs-lint — TEMPLATE. Copy me into your repo (e.g. `tools/docs-lint.mjs`) and
3
+ // OWN it, exactly like the CI workflow templates in this directory (see
4
+ // templates/README.md — "these are NOT called remotely"). Nothing here calls
5
+ // back to the handbook, and nothing here updates itself.
6
+ //
7
+ // WHAT THIS CHECKS: the STRUCTURE of a repo's doc graph — the conventions this
8
+ // handbook already defines (CLAUDE.md as router, `docs/` as current truth,
9
+ // `log/` as dated archive, `docs/gotchas.d/` as the append-only one-file-per-
10
+ // gotcha registry, `templates/gotchas-d-README.md`) — so human attention goes
11
+ // to whether docs are TRUE, not whether their references resolve. It cannot
12
+ // know whether a gotcha is still true; that stays with `code-wrap`'s stale-docs
13
+ // step and a human hygiene pass. This split is deliberate (colab-handbook #249).
14
+ //
15
+ // ZERO DEPENDENCIES. Plain Node (>= 18), no npm install, no package.json needed
16
+ // to run it — only `node:fs`, `node:path`, (for the receipt hashes below) the
17
+ // builtin `node:crypto`, and `node:child_process` to shell out to `git
18
+ // check-ignore` once per run (see the git-ignore false-positive rule below).
19
+ // It never calls the network, and a repo with no git — or no `git` binary —
20
+ // still lints, it just filters nothing.
21
+ //
22
+ // Usage:
23
+ // node docs-lint.mjs lint the current directory as repo root
24
+ // node docs-lint.mjs --repo <path> lint a different repo root
25
+ // node docs-lint.mjs --json machine-readable output (same findings)
26
+ //
27
+ // Exit code: 1 if any FAIL-severity finding fired, 0 otherwise. WARN never
28
+ // fails the process by itself — this script is advisory by design (see the
29
+ // Rollout note in #249); a repo that wants to promote a specific check to a
30
+ // hard gate does so in its OWN copy, by changing that check's severity, never
31
+ // by editing this header's contract silently.
32
+ //
33
+ // Config (all optional — .github/project.yml):
34
+ // docs_lint:
35
+ // router: CLAUDE.md # default: the in-repo file CLAUDE.md @-imports when it is a
36
+ // # thin shell (e.g. AGENTS.md), else CLAUDE.md, else AGENTS.md,
37
+ // # else README.md
38
+ // docs_dir: docs
39
+ // log_dir: log
40
+ // gotchas_dir: docs/gotchas.d
41
+ // gotchas_file: docs/gotchas.md # the curated, hand-maintained guide (optional)
42
+ // router_max_bytes: 40960 # 40 KB — same advisory ceiling audit.mjs uses (#64)
43
+ // Omitting the whole `docs_lint:` block is the common case; every default above
44
+ // mirrors the plain-prose convention this handbook already states elsewhere.
45
+ //
46
+ // HARD-WON FALSE-POSITIVE RULES (baked in from day one — colab-handbook #249,
47
+ // carried over from a memory-home pilot that needed 6 fixes in its first day):
48
+ // - `.sync/`-style mirror copies (Resilio Sync, etc.) are never enumerated —
49
+ // a synced duplicate of a real doc is not an "orphan" or a "dead path".
50
+ // - a repo may use README.md as its router instead of CLAUDE.md.
51
+ // - a CLAUDE.md that is a thin shell (`@AGENTS.md` plus tool blocks — colab-handbook
52
+ // #417) is not the router; the file it imports is, so checks 1/2/4 read the prose
53
+ // a human actually maintains, not the shell.
54
+ // - `*-log.md`-named files are not "dated files" by name alone — only a
55
+ // literal `YYYY-MM-DD` substring in the filename counts (see check 5).
56
+ // - a link target containing `...`, `<...>`, or `{...}` is a template
57
+ // placeholder, not a dead path, and is never flagged (check 1).
58
+ // - a line whose text contains the word "historical" is read as self-marking
59
+ // that its own links may point at things that no longer exist on purpose,
60
+ // and is skipped (check 1).
61
+ // - §-numbers are per-DOCUMENT, and even within one document the same number
62
+ // may legitimately label more than one heading (this handbook's own
63
+ // docs/rule-inventory.md repeats "## §5 — …" a dozen times as a topic
64
+ // grouping) — so a citation check is existence ("does N appear at all"),
65
+ // never uniqueness (check 6).
66
+ // - a `§N` immediately preceded by a backtick-wrapped, non-`.md` token (e.g.
67
+ // `` `code-triage` §5.1 ``) names an external artifact this script cannot
68
+ // generically resolve (a skill directory, a command) — it is reported as
69
+ // SKIPPED, never guessed at and never silently miscounted as broken
70
+ // (check 6; see the long comment at CITATION_CONTEXT below for why).
71
+ // - a git-IGNORED markdown file is not part of the doc graph and is never
72
+ // enumerated by any check. Scratch that never ships must not be able to
73
+ // fail a structural check on the repo — and it was: `.claude/plans/
74
+ // issue-<N>.md`, the git-excluded, `code-ship`-deleted plan file that
75
+ // `code-start` writes, contributed 7 of one control run's 10 check-6
76
+ // failures purely by quoting `§4` in prose, which made the repo lint clean
77
+ // or dirty depending on who happened to have a session open
78
+ // (colab-handbook #310, #313). The filter asks `git check-ignore`, not a
79
+ // hard-coded `.claude/` path, so every adopter's own scratch convention is
80
+ // covered by the same rule. Untracked-but-NOT-ignored files are still
81
+ // linted on purpose: a doc you are about to commit is exactly when you
82
+ // want the feedback. Tracked files are never treated as ignored, even when
83
+ // they match a pattern — that is `git check-ignore`'s own default.
84
+ // - every check reports how much it actually read (files, bytes) alongside
85
+ // its verdict — an all-clear on zero bytes read (a missing directory, a
86
+ // misconfigured path) must never print identically to an all-clear that
87
+ // inspected real content. See `receipt()` below.
88
+
89
+ import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
90
+ import { join, dirname, relative, sep } from "node:path";
91
+ import { createHash } from "node:crypto";
92
+ import { spawnSync } from "node:child_process";
93
+
94
+ // ---------------------------------------------------------------------------
95
+ // CLI + config
96
+ // ---------------------------------------------------------------------------
97
+
98
+ function parseArgs(argv) {
99
+ const out = { repo: ".", json: false };
100
+ for (let i = 0; i < argv.length; i++) {
101
+ const a = argv[i];
102
+ if (a === "--repo") out.repo = argv[++i] ?? ".";
103
+ else if (a.startsWith("--repo=")) out.repo = a.slice("--repo=".length);
104
+ else if (a === "--json") out.json = true;
105
+ else if (a === "--help" || a === "-h") out.help = true;
106
+ }
107
+ return out;
108
+ }
109
+
110
+ const HELP = `docs-lint — structural lint for a repo's doc graph (colab-handbook copy-and-own template)
111
+
112
+ Usage:
113
+ node docs-lint.mjs [--repo <path>] [--json]
114
+
115
+ Exit code 1 iff any FAIL-severity finding fired; WARN never fails the process.`;
116
+
117
+ // Minimal, deliberately narrow reader for the OPTIONAL `docs_lint:` block in
118
+ // .github/project.yml. This is NOT a general YAML parser — it reads exactly
119
+ // one flat block of `key: value` scalar pairs, indented under `docs_lint:`,
120
+ // which is all this script's config ever needs. A repo whose project.yml uses
121
+ // anything richer than that under this key gets those extra keys ignored, not
122
+ // misparsed — the parser only ever looks for a run of two-space-or-more
123
+ // indented `key: value` lines directly under the block header.
124
+ function readDocsLintConfigBlock(repoRoot) {
125
+ const text = readFileSafeText(join(repoRoot, ".github/project.yml"));
126
+ if (text === null) return {};
127
+ const lines = text.split(/\r?\n/);
128
+ const start = lines.findIndex((l) => /^docs_lint:\s*(#.*)?$/.test(l));
129
+ if (start === -1) return {};
130
+ const cfg = {};
131
+ for (let i = start + 1; i < lines.length; i++) {
132
+ const line = lines[i];
133
+ if (line.trim() === "" || /^\s*#/.test(line)) continue; // blank / full-line comment
134
+ if (!/^\s{2,}\S/.test(line)) break; // dedented back to column 0/1 — block ended
135
+ const m = line.match(/^\s+([A-Za-z_]+):\s*(.+?)\s*(#.*)?$/);
136
+ if (!m) continue;
137
+ let val = m[2].trim();
138
+ val = val.replace(/^["']|["']$/g, ""); // strip a wrapping quote pair, if any
139
+ cfg[m[1]] = val;
140
+ }
141
+ return cfg;
142
+ }
143
+
144
+ // #417 — CLAUDE.md as a thin shell over AGENTS.md. One-level, inline copy of the import
145
+ // parser in colab-handbook's tools/lib/instruction-file.js (this template is copy-and-own and
146
+ // imports nothing): an `@<path>` token at line start or after whitespace, outside fenced
147
+ // blocks and inline code spans, trailing punctuation stripped, resolved relative to the repo
148
+ // root, in-repo only. Keep the two in step; both are tested on the same cases.
149
+ function claudeImports(text) {
150
+ const out = [];
151
+ for (const line of blankFences(text)) {
152
+ const bare = line.replace(/(`+)[\s\S]*?\1/g, (m) => " ".repeat(m.length));
153
+ for (const m of bare.matchAll(/(^|\s)@([^\s]+)/g)) {
154
+ const raw = m[2].replace(/[),;:!?]+$/, "").replace(/\.$/, "");
155
+ if (!raw || raw.startsWith("~") || raw.startsWith("/") || raw.startsWith("\\") || /^[A-Za-z]:[\\/]/.test(raw)) continue;
156
+ const parts = [];
157
+ let escapes = false;
158
+ for (const seg of raw.replace(/\\/g, "/").split("/")) {
159
+ if (seg === "" || seg === ".") continue;
160
+ if (seg === "..") { if (!parts.length) { escapes = true; break; } parts.pop(); continue; }
161
+ parts.push(seg);
162
+ }
163
+ if (!escapes && parts.length) out.push(parts.join("/"));
164
+ }
165
+ }
166
+ return out;
167
+ }
168
+
169
+ function buildConfig(repoRoot) {
170
+ const block = readDocsLintConfigBlock(repoRoot);
171
+ const hasClaude = existsSync(join(repoRoot, "CLAUDE.md"));
172
+ const hasAgents = existsSync(join(repoRoot, "AGENTS.md"));
173
+ const hasReadme = existsSync(join(repoRoot, "README.md"));
174
+ const shellTarget = hasClaude
175
+ ? claudeImports(readFileSafeText(join(repoRoot, "CLAUDE.md")) ?? "").find((p) => existsSync(join(repoRoot, p))) ?? null
176
+ : null;
177
+ const defaultRouter = block.router ??
178
+ (shellTarget ?? (hasClaude ? "CLAUDE.md" : hasAgents ? "AGENTS.md" : hasReadme ? "README.md" : null));
179
+ return {
180
+ router: defaultRouter,
181
+ docsDir: block.docs_dir ?? "docs",
182
+ logDir: block.log_dir ?? "log",
183
+ gotchasDir: block.gotchas_dir ?? "docs/gotchas.d",
184
+ gotchasFile: block.gotchas_file ?? "docs/gotchas.md",
185
+ routerMaxBytes: Number(block.router_max_bytes ?? 40 * 1024) || 40 * 1024,
186
+ };
187
+ }
188
+
189
+ // ---------------------------------------------------------------------------
190
+ // Filesystem helpers
191
+ // ---------------------------------------------------------------------------
192
+
193
+ // Directory-name substrings that mean "not a real doc I should enumerate" —
194
+ // the ".sync/" false-positive rule generalised to every mirror-sync tool this
195
+ // fleet has actually used, plus the ordinary VCS/dependency noise.
196
+ const SKIP_DIR_RE = /(^|[\\/])(\.git|\.sync|node_modules|\.worktrees|vendor)([\\/]|$)/;
197
+
198
+ function readFileSafeText(absPath) {
199
+ try {
200
+ return readFileSync(absPath, "utf8");
201
+ } catch {
202
+ return null;
203
+ }
204
+ }
205
+
206
+ // Walks `root` for every `*.md` file, returning paths relative to `root` with
207
+ // forward slashes (so messages read the same on every OS). Skips SKIP_DIR_RE.
208
+ function walkMarkdownFiles(root) {
209
+ const out = [];
210
+ const stack = [""];
211
+ while (stack.length) {
212
+ const rel = stack.pop();
213
+ const abs = rel === "" ? root : join(root, rel);
214
+ let entries;
215
+ try {
216
+ entries = readdirSync(abs, { withFileTypes: true });
217
+ } catch {
218
+ continue;
219
+ }
220
+ for (const entry of entries) {
221
+ const childRel = rel === "" ? entry.name : `${rel}/${entry.name}`;
222
+ const childAbs = join(root, childRel);
223
+ if (SKIP_DIR_RE.test(`/${childRel}/`)) continue;
224
+ if (entry.isDirectory()) {
225
+ stack.push(childRel);
226
+ } else if (entry.isFile() && /\.md$/i.test(entry.name)) {
227
+ out.push(childRel.split(sep).join("/"));
228
+ }
229
+ }
230
+ }
231
+ return out.sort();
232
+ }
233
+
234
+ // Git-ignore filter. A file git ignores is not part of the repo's doc graph:
235
+ // it is scratch, it never ships, and `code-ship` may delete it mid-run — so no
236
+ // check may enumerate it (colab-handbook #310). Answered by `git check-ignore`
237
+ // in ONE batched call per enumeration, cached across checks, because asking per
238
+ // file is a process spawn per file.
239
+ //
240
+ // Two properties of `check-ignore` this relies on, both its documented default:
241
+ // a TRACKED file is never reported as ignored (even if a pattern matches it —
242
+ // that needs `--no-index`), and exit 1 means "nothing matched", which is a
243
+ // successful answer, not an error. Anything else — no `git` on PATH, or "not a
244
+ // git repository" (128) — means this filter cannot answer at all, and it then
245
+ // filters NOTHING and every check behaves exactly as it did before this
246
+ // existed. Degrading to the old behaviour is the only safe direction: silently
247
+ // skipping files because git was unavailable would turn a lint into a lie.
248
+ function makeIgnoreFilter(repoRoot) {
249
+ const cache = new Map(); // repo-relative path -> true when git ignores it
250
+ let available = true;
251
+
252
+ const learn = (paths) => {
253
+ const unknown = paths.filter((p) => !cache.has(p));
254
+ if (!available || unknown.length === 0) return;
255
+ const res = spawnSync("git", ["-C", repoRoot, "check-ignore", "--stdin", "-z"], {
256
+ input: unknown.join("\0"),
257
+ encoding: "utf8",
258
+ maxBuffer: 64 * 1024 * 1024,
259
+ });
260
+ if (res.error || (res.status !== 0 && res.status !== 1)) {
261
+ available = false;
262
+ return;
263
+ }
264
+ const ignored = new Set((res.stdout ?? "").split("\0").filter(Boolean));
265
+ for (const p of unknown) cache.set(p, ignored.has(p));
266
+ };
267
+
268
+ return (paths) => {
269
+ learn(paths);
270
+ const kept = [];
271
+ let ignored = 0;
272
+ for (const p of paths) {
273
+ if (cache.get(p) === true) ignored++;
274
+ else kept.push(p);
275
+ }
276
+ return { files: kept, ignored };
277
+ };
278
+ }
279
+
280
+ // Repo-relative markdown enumeration with the git-ignore filter applied. Every
281
+ // check goes through this rather than calling walkMarkdownFiles directly, so
282
+ // one rule about what belongs to the doc graph holds across all of them.
283
+ // `relDir` scopes the walk (e.g. `docs`) while the returned paths stay
284
+ // repo-relative, which is what findings, receipts and link resolution all use.
285
+ function walkRepoMarkdown(ctx, relDir = "") {
286
+ const root = relDir === "" ? ctx.repoRoot : join(ctx.repoRoot, relDir);
287
+ const found = walkMarkdownFiles(root).map((f) => (relDir === "" ? f : `${relDir}/${f}`));
288
+ return ctx.ignoreFilter(found);
289
+ }
290
+
291
+ function listDirFiles(root, relDir) {
292
+ const abs = join(root, relDir);
293
+ try {
294
+ return readdirSync(abs, { withFileTypes: true })
295
+ .filter((e) => e.isFile())
296
+ .map((e) => `${relDir}/${e.name}`);
297
+ } catch {
298
+ return null; // directory does not exist — distinct from "exists but empty"
299
+ }
300
+ }
301
+
302
+ // ---------------------------------------------------------------------------
303
+ // Receipts — "an empty read digests to a stable hash": every check states how
304
+ // much it actually inspected, so a clean verdict on nothing (a misconfigured
305
+ // path, a directory that silently doesn't exist) never prints identically to
306
+ // a clean verdict earned by reading real content. `digest` is a short, stable
307
+ // fingerprint of what was read — not cryptographic, just enough that a report
308
+ // diffed across two runs shows whether the INPUT changed, not only the verdict.
309
+ // ---------------------------------------------------------------------------
310
+
311
+ function makeReceipt() {
312
+ const hash = createHash("sha256");
313
+ let files = 0;
314
+ let bytes = 0;
315
+ return {
316
+ add(path, text) {
317
+ files += 1;
318
+ bytes += Buffer.byteLength(text ?? "", "utf8");
319
+ hash.update(path);
320
+ hash.update("\0");
321
+ hash.update(text ?? "");
322
+ hash.update("\0");
323
+ },
324
+ summary() {
325
+ return { files, bytes, digest: hash.copy().digest("hex").slice(0, 12) };
326
+ },
327
+ };
328
+ }
329
+
330
+ function formatReceipt(r) {
331
+ const { files, bytes, digest } = r.summary();
332
+ return `${files} file${files === 1 ? "" : "s"}, ${bytes} bytes, digest ${digest}`;
333
+ }
334
+
335
+ // ---------------------------------------------------------------------------
336
+ // Markdown structural helpers (heading slugs, link scanning) — adapted from
337
+ // this handbook's own audit/audit.mjs (#158, #64), which calibrated the
338
+ // slugifier against every real anchor link this repo carries. Copied rather
339
+ // than imported: this file is a copy-and-own template that must run standalone
340
+ // in an adopting repo with no access to this handbook's tools/lib.
341
+ // ---------------------------------------------------------------------------
342
+
343
+ function slugifyHeading(text) {
344
+ return text
345
+ .replace(/`([^`]*)`/g, "$1")
346
+ .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
347
+ .trim()
348
+ .replace(/#+$/, "")
349
+ .toLowerCase()
350
+ // `\w` is ASCII-only; GitHub keeps Unicode letters when it slugifies a heading, so
351
+ // this widens to `\p{L}`/`\p{N}` (Unicode letter/digit) while keeping `_` as its own
352
+ // explicit class member -- the next line folds `_` into `-` and needs it to survive
353
+ // this step to do that. Kept in sync with audit/audit.mjs's slugifyHeading (#280).
354
+ .replace(/[^\p{L}\p{N}_\- ]+/gu, "")
355
+ .trim()
356
+ .replace(/[ _]/g, "-");
357
+ }
358
+
359
+ // Blanks fenced code blocks (```/~~~) to whole-line-length spaces, so a `#`
360
+ // or `§` inside a code sample is never read as a heading or a citation, while
361
+ // line numbers stay accurate for messages.
362
+ function blankFences(text) {
363
+ let inFence = false;
364
+ return text.split("\n").map((line) => {
365
+ if (/^\s*(```|~~~)/.test(line)) {
366
+ inFence = !inFence;
367
+ return "";
368
+ }
369
+ return inFence ? "" : line;
370
+ });
371
+ }
372
+
373
+ // Every heading in `text`, in document order, mapped to its GitHub-compatible
374
+ // resolved slug (including duplicate-slug suffixing).
375
+ function collectHeadingSlugs(text) {
376
+ const slugs = new Set();
377
+ const seen = new Map();
378
+ for (const line of blankFences(text)) {
379
+ const m = /^#{1,6}\s+(.+?)\s*$/.exec(line);
380
+ if (!m) continue;
381
+ const base = slugifyHeading(m[1]);
382
+ if (!base) continue;
383
+ const n = seen.get(base) ?? 0;
384
+ seen.set(base, n + 1);
385
+ slugs.add(n === 0 ? base : `${base}-${n}`);
386
+ }
387
+ return slugs;
388
+ }
389
+
390
+ // Every "N" or "N.M" that leads a heading (`## 5. Foo`, `### 5.1 Bar`, or this
391
+ // repo's own `## §5 — Foo` shape), as a Set of exact strings. Existence-only,
392
+ // deliberately — see the per-document/non-unique §-numbering note above.
393
+ function collectNumberedHeadings(text) {
394
+ const nums = new Set();
395
+ for (const line of blankFences(text)) {
396
+ const m = /^#{1,6}\s+(?:§\s*)?(\d+(?:\.\d+)?)(?:[.\s:—–-]|$)/.exec(line);
397
+ if (m) nums.add(m[1]);
398
+ }
399
+ return nums;
400
+ }
401
+
402
+ function levenshtein(a, b) {
403
+ const m = a.length, n = b.length;
404
+ let prev = new Array(n + 1), curr = new Array(n + 1);
405
+ for (let j = 0; j <= n; j++) prev[j] = j;
406
+ for (let i = 1; i <= m; i++) {
407
+ curr[0] = i;
408
+ for (let j = 1; j <= n; j++) {
409
+ const cost = a[i - 1] === b[j - 1] ? 0 : 1;
410
+ curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
411
+ }
412
+ [prev, curr] = [curr, prev];
413
+ }
414
+ return prev[n];
415
+ }
416
+
417
+ function nearest(target, candidates, n = 5) {
418
+ return [...candidates]
419
+ .map((c) => ({ c, d: levenshtein(String(target), String(c)) }))
420
+ .sort((a, b) => a.d - b.d)
421
+ .slice(0, n)
422
+ .map((x) => x.c);
423
+ }
424
+
425
+ // Repo-relative markdown links: `](target#fragment)`, target empty for a
426
+ // same-file link. Skips external (scheme:// or //host) targets.
427
+ const LINK_RE = /\]\(([^)#\s]*\.md)?#?([^)\s]*)\)/g;
428
+ // A simpler "does this file link anywhere" scanner for the orphan check
429
+ // (check 2), which only needs the TARGET path, not the fragment.
430
+ const ANY_MD_LINK_RE = /\]\(([^)#\s]+\.md)(#[^)\s]*)?\)/g;
431
+
432
+ function isExternalTarget(t) {
433
+ return /^[a-z][a-z0-9+.-]*:/i.test(t) || t.startsWith("//");
434
+ }
435
+
436
+ function resolveRepoPath(dir, target) {
437
+ const p = target.startsWith("/") ? target.slice(1) : join(dir, target);
438
+ return p.split(sep).join("/").split("/").filter((seg) => seg !== ".").join("/");
439
+ }
440
+
441
+ // Placeholder-aware: a link target containing `...`, an angle-bracket span,
442
+ // or a brace span is a template example, not a real path. A line self-marked
443
+ // "historical" is read as declaring its own links may be intentionally dead.
444
+ const PLACEHOLDER_TARGET_RE = /\.\.\.|<[^>]*>|\{[^}]*\}/;
445
+ function isHistoricalLine(line) {
446
+ return /historical/i.test(line);
447
+ }
448
+
449
+ // ---------------------------------------------------------------------------
450
+ // Findings collector
451
+ // ---------------------------------------------------------------------------
452
+
453
+ function makeFindings() {
454
+ const items = [];
455
+ return {
456
+ fail(check, message) { items.push({ severity: "fail", check, message }); },
457
+ warn(check, message) { items.push({ severity: "warn", check, message }); },
458
+ all: items,
459
+ };
460
+ }
461
+
462
+ // ===========================================================================
463
+ // Check 1 — Router integrity: every path/link in the router resolves.
464
+ // ===========================================================================
465
+ function checkRouterIntegrity(ctx) {
466
+ const { repoRoot, config, findings } = ctx;
467
+ const receipt = makeReceipt();
468
+ const check = "1 router-integrity";
469
+
470
+ if (!config.router) {
471
+ findings.warn(check, "no router found — none of CLAUDE.md, AGENTS.md or README.md exists at the repo root");
472
+ return { receipt };
473
+ }
474
+ const routerPath = config.router;
475
+ const text = readFileSafeText(join(repoRoot, routerPath));
476
+ if (text === null) {
477
+ findings.fail(check, `configured router "${routerPath}" does not exist`);
478
+ return { receipt };
479
+ }
480
+ receipt.add(routerPath, text);
481
+
482
+ const dir = dirname(routerPath) === "." ? "" : dirname(routerPath);
483
+ const lines = blankFences(text).length ? text.split("\n") : text.split("\n"); // keep original text for line lookup
484
+ let checked = 0, skippedPlaceholder = 0, skippedHistorical = 0;
485
+
486
+ for (let ln = 0; ln < lines.length; ln++) {
487
+ const line = lines[ln];
488
+ if (isHistoricalLine(line)) { skippedHistorical++; continue; }
489
+ ANY_MD_LINK_RE.lastIndex = 0;
490
+ let m;
491
+ while ((m = ANY_MD_LINK_RE.exec(line))) {
492
+ const raw = m[1];
493
+ if (isExternalTarget(raw)) continue;
494
+ if (PLACEHOLDER_TARGET_RE.test(raw)) { skippedPlaceholder++; continue; }
495
+ const target = resolveRepoPath(dir, raw);
496
+ checked++;
497
+ if (readFileSafeText(join(repoRoot, target)) === null) {
498
+ findings.fail(check, `${routerPath}:${ln + 1}: links to ${target}, which does not exist`);
499
+ }
500
+ }
501
+ }
502
+ receipt.note = `${checked} link(s) checked, ${skippedPlaceholder} placeholder(s) skipped, ${skippedHistorical} historical line(s) skipped`;
503
+ return { receipt };
504
+ }
505
+
506
+ // ===========================================================================
507
+ // Check 2 — Orphans: docs/*.md referenced by neither the router nor any doc.
508
+ // ===========================================================================
509
+ function checkOrphans(ctx) {
510
+ const { repoRoot, config, findings } = ctx;
511
+ const receipt = makeReceipt();
512
+ const check = "2 orphans";
513
+
514
+ const { files: allMd } = walkRepoMarkdown(ctx);
515
+ if (allMd.length === 0) {
516
+ findings.warn(check, "no markdown files found in the repo at all — nothing to check");
517
+ return { receipt };
518
+ }
519
+
520
+ const referenced = new Set();
521
+ for (const file of allMd) {
522
+ const text = readFileSafeText(join(repoRoot, file));
523
+ if (text === null) continue;
524
+ receipt.add(file, text);
525
+ const dir = dirname(file) === "." ? "" : dirname(file);
526
+ for (const line of blankFences(text)) {
527
+ ANY_MD_LINK_RE.lastIndex = 0;
528
+ let m;
529
+ while ((m = ANY_MD_LINK_RE.exec(line))) {
530
+ const raw = m[1];
531
+ if (isExternalTarget(raw) || PLACEHOLDER_TARGET_RE.test(raw)) continue;
532
+ referenced.add(resolveRepoPath(dir, raw));
533
+ }
534
+ }
535
+ }
536
+
537
+ const { files: docsFiles } = walkRepoMarkdown(ctx, config.docsDir);
538
+ const gotchasPrefix = `${config.gotchasDir}/`;
539
+ const candidates = docsFiles.filter((f) => !f.startsWith(gotchasPrefix) && !/\/README\.md$/i.test(f));
540
+
541
+ let orphanCount = 0;
542
+ for (const f of candidates) {
543
+ if (!referenced.has(f)) {
544
+ orphanCount++;
545
+ findings.warn(check, `${f} is never linked from ${config.router ?? "the router"} or any other doc — an orphan, or a dead-end nobody will find`);
546
+ }
547
+ }
548
+ receipt.note = `${candidates.length} ${config.docsDir}/ file(s) checked (excluding ${config.gotchasDir}/ and README.md), ${orphanCount} orphan(s)`;
549
+ return { receipt };
550
+ }
551
+
552
+ // ===========================================================================
553
+ // Check 3 — Drafts in docs/: the convention says drafts live in log/.
554
+ // ===========================================================================
555
+ // Conservative on purpose (advisory-first, false-positive-averse): a doc is
556
+ // flagged only when it carries an EXPLICIT self-description, not merely
557
+ // because the word "draft" appears somewhere in its prose (that alone was the
558
+ // naive version this handbook's own pilot rejected as noisy).
559
+ const DRAFT_MARKER_RE = /^\s*(>\s*)?\**\s*(status|state)\s*\**\s*:\s*\**\s*draft\b/i;
560
+ const DRAFT_TITLE_RE = /^#{1,6}\s+.*\((?:draft|wip)\)/i;
561
+
562
+ function checkDraftsInDocs(ctx) {
563
+ const { repoRoot, config, findings } = ctx;
564
+ const receipt = makeReceipt();
565
+ const check = "3 drafts-in-docs";
566
+
567
+ const { files: docsFiles } = walkRepoMarkdown(ctx, config.docsDir);
568
+ const gotchasPrefix = `${config.gotchasDir}/`;
569
+ const candidates = docsFiles.filter((f) => !f.startsWith(gotchasPrefix));
570
+
571
+ let flagged = 0;
572
+ for (const f of candidates) {
573
+ const text = readFileSafeText(join(repoRoot, f));
574
+ if (text === null) continue;
575
+ receipt.add(f, text);
576
+ const head = text.split("\n").slice(0, 15);
577
+ const hit = head.find((l) => DRAFT_MARKER_RE.test(l) || DRAFT_TITLE_RE.test(l));
578
+ if (hit) {
579
+ flagged++;
580
+ findings.warn(check, `${f} self-describes as a draft ("${hit.trim()}") but lives in ${config.docsDir}/ — the convention is drafts live in ${config.logDir}/`);
581
+ }
582
+ }
583
+ receipt.note = `${candidates.length} file(s) checked, ${flagged} self-marked draft(s)`;
584
+ return { receipt };
585
+ }
586
+
587
+ // ===========================================================================
588
+ // Check 4 — Router size budget.
589
+ // ===========================================================================
590
+ function checkRouterSizeBudget(ctx) {
591
+ const { repoRoot, config, findings } = ctx;
592
+ const receipt = makeReceipt();
593
+ const check = "4 router-size-budget";
594
+
595
+ if (!config.router) return { receipt }; // check 1 already reported this
596
+ const text = readFileSafeText(join(repoRoot, config.router));
597
+ if (text === null) return { receipt }; // check 1 already reported this
598
+ receipt.add(config.router, text);
599
+
600
+ const bytes = Buffer.byteLength(text, "utf8");
601
+ if (bytes > config.routerMaxBytes) {
602
+ findings.warn(
603
+ check,
604
+ `${config.router} is ${bytes} bytes (~${(bytes / 1024).toFixed(1)} KB) — over the ` +
605
+ `${(config.routerMaxBytes / 1024).toFixed(0)} KB advisory ceiling. It is loaded in full before any work ` +
606
+ `starts; if depth belongs in ${config.docsDir}/, the router line should be a pointer, not a copy`,
607
+ );
608
+ }
609
+ receipt.note = `${bytes} bytes vs ${config.routerMaxBytes} byte ceiling`;
610
+ return { receipt };
611
+ }
612
+
613
+ // ===========================================================================
614
+ // Check 5 — Dated-name files inside docs/ (belong in log/).
615
+ // ===========================================================================
616
+ // Strictly an ISO date substring — the false-positive rule this check exists
617
+ // to satisfy ("exclude -log.md/dated files from content budgets") is already
618
+ // structural here: a file merely named `*-log.md` (an ongoing, non-dated
619
+ // running log) has no YYYY-MM-DD substring and never matches.
620
+ const DATED_NAME_RE = /(^|[-_/])(\d{4}-\d{2}-\d{2})([-_.]|$)/;
621
+
622
+ function checkDatedFilesInDocs(ctx) {
623
+ const { repoRoot, config, findings } = ctx;
624
+ const receipt = makeReceipt();
625
+ const check = "5 dated-files-in-docs";
626
+
627
+ const { files: docsFiles } = walkRepoMarkdown(ctx, config.docsDir);
628
+ const gotchasPrefix = `${config.gotchasDir}/`;
629
+ const candidates = docsFiles.filter((f) => !f.startsWith(gotchasPrefix));
630
+
631
+ let flagged = 0;
632
+ for (const f of candidates) {
633
+ receipt.add(f, ""); // filename check only — no content read needed
634
+ if (DATED_NAME_RE.test(f)) {
635
+ flagged++;
636
+ findings.warn(check, `${f} has a dated filename but lives in ${config.docsDir}/ (current truth) — dated archives belong in ${config.logDir}/`);
637
+ }
638
+ }
639
+ receipt.note = `${candidates.length} filename(s) checked, ${flagged} dated`;
640
+ return { receipt };
641
+ }
642
+
643
+ // ===========================================================================
644
+ // Check 6 — §/section citations resolve, WITH CONTEXT.
645
+ // ===========================================================================
646
+ // Three patterns, exactly as scoped by colab-handbook #249:
647
+ // (a) "gotchas §N" -> resolved against config.gotchasFile's own headings
648
+ // (b) "<file>.md §N" -> resolved against that named file's headings
649
+ // (c) bare "§N" -> resolved against the CURRENT file's own headings
650
+ //
651
+ // Pattern (b) has TWO shapes, and colab-handbook #300 measured that conflating
652
+ // them is what broke this check on the handbook's own trunk. A token carrying a
653
+ // separator ("../CONVENTIONS.md", "docs/adr/288-x.md") is a PATH claim: resolve
654
+ // it against the citing file's directory and nowhere else. A token that is a
655
+ // BARE NAME ("CONVENTIONS.md") is a NAME, and a reader resolves a name the
656
+ // obvious way — the copy sitting next to this file if there is one, otherwise
657
+ // the repo's own copy at the root. Resolving a bare name against the citing
658
+ // directory ALONE made every unlinked `CONVENTIONS.md §N` inside a nested skill
659
+ // file a FAIL against a sibling that was never meant to exist. Measured on this
660
+ // handbook: all 10 filename-qualified citations in the repo name CONVENTIONS.md
661
+ // by bare name and not one is path-shaped; 8 sit in root-level files (where the
662
+ // two resolutions coincide), which is the only reason the bug stayed invisible
663
+ // until two skill files used the same style two levels down.
664
+ //
665
+ // A fifth outcome, SKIPPED, exists deliberately: a `§N` immediately preceded
666
+ // by a BACKTICK-WRAPPED token that is neither "gotchas" nor `*.md` (e.g.
667
+ // `` `code-triage` §5.1 ``, a real citation style in this very handbook,
668
+ // pointing at another skill's own SKILL.md by name) names an external
669
+ // artifact this generic script has no way to resolve — reported as skipped,
670
+ // counted in the receipt, never silently treated as broken OR silently
671
+ // dropped. This was measured against this handbook's own docs before shipping
672
+ // this check: `the §3`, `and §1`, `per §7` (ordinary prose words, not
673
+ // backtick-wrapped) all resolve correctly as bare self-citations under this
674
+ // rule, while `` `code-triage` §5.1 `` correctly reports as skipped rather
675
+ // than failing against a file that was never meant to hold that heading.
676
+ //
677
+ // A §N wrapped ENTIRELY in its own backticks (`` `§5` ``, as opposed to a
678
+ // backtick-wrapped FILENAME sitting next to a bare §N) is read as a LITERAL
679
+ // CODE-SPAN EXAMPLE — a doc illustrating the old citation style, exactly as
680
+ // this handbook's own audit/README.md does while describing the bug this
681
+ // check exists to catch — and is skipped, not resolved, the same posture
682
+ // audit.mjs's own anchor-link check takes toward inline code spans.
683
+ //
684
+ // Both link-stripping and the whole-text preceding-token lookup operate on
685
+ // the FULL FILE, not per physical line: this repo hard-wraps prose at ~90
686
+ // columns, so a markdown link's `[label](target)` — or a citation's
687
+ // qualifying filename — routinely lands on the line BEFORE its own `§N`.
688
+ // Scanning per line silently missed both of those and produced two false
689
+ // FAILs against this handbook's own docs before this fix (measured 2026-08-21).
690
+ function stripLinksForCitationScan(text) {
691
+ // A §N that is the visible TEXT of a real markdown link (`[§9](...)`, or
692
+ // `` [`code-triage` §0](...) ``) is already covered by check 1 / the link's
693
+ // own href — remove the whole `[...](...)` span, replacing every non-newline
694
+ // character with a space so line numbers computed from the result stay correct.
695
+ return text.replace(/\[[^\]]*\]\([^)]*\)/g, (m) => m.replace(/[^\n]/g, " "));
696
+ }
697
+
698
+ const CITATION_RE = /§\s*(\d+(?:\.\d+)?)/g;
699
+ // Captures the token immediately before a match position, keeping a trailing
700
+ // backtick/quote (so we can tell "was this backtick-wrapped") separately.
701
+ function precedingToken(text, index) {
702
+ const pre = text.slice(0, index);
703
+ const m = /([`'"]?)([\w./-]+)([`'"]?)\s*$/.exec(pre);
704
+ if (!m) return null;
705
+ return { token: m[2], backticked: Boolean(m[1] || m[3]) };
706
+ }
707
+
708
+ // Candidate target(s) for a filename-qualified citation, in the order a reader
709
+ // would try them. Path-shaped token (any separator) -> exactly one candidate,
710
+ // resolved against the citing directory. Bare name -> the sibling first, then
711
+ // the repo root; the FIRST candidate that EXISTS wins, so a repo that really
712
+ // does keep a same-named file next to the citing doc still resolves there, and
713
+ // a missing heading number in it is still a genuine break rather than something
714
+ // the root copy silently papers over.
715
+ function citationCandidates(dir, token) {
716
+ if (token.includes("/")) return [resolveRepoPath(dir, token)];
717
+ const sibling = resolveRepoPath(dir, token);
718
+ const atRoot = resolveRepoPath("", token);
719
+ return sibling === atRoot ? [sibling] : [sibling, atRoot];
720
+ }
721
+
722
+ function lineNumberAt(text, index) {
723
+ let line = 0;
724
+ for (let i = 0; i < index && i < text.length; i++) if (text.charCodeAt(i) === 10) line++;
725
+ return line; // 0-based
726
+ }
727
+
728
+ function checkGotchaCitations(ctx) {
729
+ const { repoRoot, config, findings } = ctx;
730
+ const receipt = makeReceipt();
731
+ const check = "6 section-citations";
732
+
733
+ const { files: allMd, ignored: ignoredCount } = walkRepoMarkdown(ctx);
734
+ const files = allMd.filter((f) => !f.startsWith(`${config.gotchasDir}/`));
735
+ const headingCache = new Map(); // repo-relative path -> Set<numberString> | null
736
+
737
+ const numsFor = (path) => {
738
+ if (headingCache.has(path)) return headingCache.get(path);
739
+ const text = readFileSafeText(join(repoRoot, path));
740
+ const result = text === null ? null : collectNumberedHeadings(text);
741
+ headingCache.set(path, result);
742
+ return result;
743
+ };
744
+
745
+ let resolved = 0, broken = 0, skipped = 0, literalExamples = 0, viaRoot = 0;
746
+ for (const file of files) {
747
+ const rawText = readFileSafeText(join(repoRoot, file));
748
+ if (rawText === null) continue;
749
+ receipt.add(file, rawText);
750
+ const dir = dirname(file) === "." ? "" : dirname(file);
751
+ const fenceBlanked = blankFences(rawText).join("\n");
752
+ const scanText = stripLinksForCitationScan(fenceBlanked);
753
+
754
+ CITATION_RE.lastIndex = 0;
755
+ let m;
756
+ while ((m = CITATION_RE.exec(scanText))) {
757
+ const num = m[1];
758
+ const ln = lineNumberAt(scanText, m.index);
759
+
760
+ // Entirely backtick-wrapped (`` `§5` ``) — a literal example, not a citation.
761
+ const charBefore = scanText[m.index - 1];
762
+ const charAfter = scanText[m.index + m[0].length];
763
+ if (charBefore === "`" && charAfter === "`") {
764
+ literalExamples++;
765
+ continue;
766
+ }
767
+
768
+ const pre = precedingToken(scanText, m.index);
769
+ let candidates = [file]; // default: bare -> current file
770
+ let label = `bare §${num}`;
771
+
772
+ if (pre && pre.token.toLowerCase() === "gotchas" && !pre.backticked) {
773
+ candidates = [config.gotchasFile];
774
+ label = `gotchas §${num}`;
775
+ } else if (pre && /\.md$/i.test(pre.token)) {
776
+ candidates = citationCandidates(dir, pre.token);
777
+ label = `${pre.token} §${num}`;
778
+ } else if (pre && pre.backticked) {
779
+ // A named, non-.md, backtick-wrapped artifact — cannot resolve generically.
780
+ skipped++;
781
+ continue;
782
+ }
783
+ // else: ordinary prose word or nothing before it -> bare, current file.
784
+
785
+ const targetFile = candidates.find((c) => numsFor(c) !== null);
786
+ if (targetFile === undefined) {
787
+ broken++;
788
+ const where =
789
+ candidates.length > 1
790
+ ? `neither ${candidates[0]} nor ${candidates[1]} exists`
791
+ : `${candidates[0]} does not exist`;
792
+ findings.fail(check, `${file}:${ln + 1}: "${label}" — ${where}`);
793
+ continue;
794
+ }
795
+ if (targetFile !== candidates[0]) viaRoot++;
796
+
797
+ const nums = numsFor(targetFile);
798
+ if (!nums.has(num)) {
799
+ broken++;
800
+ const suggestion = nearest(num, nums, 5);
801
+ findings.fail(
802
+ check,
803
+ `${file}:${ln + 1}: "${label}" does not resolve — ${targetFile} has no heading numbered ${num}` +
804
+ (suggestion.length ? ` (nearest: ${suggestion.join(", ")})` : " (it has no numbered headings at all)"),
805
+ );
806
+ continue;
807
+ }
808
+ resolved++;
809
+ }
810
+ }
811
+ receipt.note =
812
+ `${resolved} citation(s) resolved` +
813
+ (viaRoot ? ` (${viaRoot} by bare name at the repo root, no sibling copy)` : "") +
814
+ `, ${broken} broken, ${skipped} skipped (unresolvable external artifact), ${literalExamples} literal code-span example(s) ignored` +
815
+ (ignoredCount ? `, ${ignoredCount} git-ignored file(s) not enumerated` : "");
816
+ return { receipt };
817
+ }
818
+
819
+ // ===========================================================================
820
+ // Check 7 — gotchas.d/ registry discipline.
821
+ // ===========================================================================
822
+ const GOTCHA_FILENAME_RE = /^(\d+)-[a-z0-9-]+\.md$/i;
823
+
824
+ function checkGotchasDRegistry(ctx) {
825
+ const { repoRoot, config, findings } = ctx;
826
+ const receipt = makeReceipt();
827
+ const check = "7 gotchas-d-registry";
828
+
829
+ const files = listDirFiles(repoRoot, config.gotchasDir);
830
+ if (files === null) {
831
+ findings.warn(check, `${config.gotchasDir}/ does not exist — nothing to check (a repo may not have adopted it yet)`);
832
+ return { receipt };
833
+ }
834
+ const entries = files.filter((f) => !/\/README\.md$/i.test(f));
835
+ const seen = new Map(); // issue number -> [files]
836
+ let malformed = 0;
837
+
838
+ for (const f of entries) {
839
+ receipt.add(f, ""); // filename discipline only
840
+ const base = f.split("/").pop();
841
+ const m = GOTCHA_FILENAME_RE.exec(base);
842
+ if (!m) {
843
+ malformed++;
844
+ findings.warn(check, `${f} does not match "<issue-number>-<slug>.md" (templates/gotchas-d-README.md's naming rule)`);
845
+ continue;
846
+ }
847
+ const num = m[1];
848
+ if (!seen.has(num)) seen.set(num, []);
849
+ seen.get(num).push(f);
850
+ }
851
+ let duplicates = 0;
852
+ for (const [num, list] of seen) {
853
+ if (list.length > 1) {
854
+ duplicates++;
855
+ findings.fail(check, `issue #${num} has ${list.length} gotchas.d entries — one file per gotcha, never two: ${list.join(", ")}`);
856
+ }
857
+ }
858
+ receipt.note = `${entries.length} entr(y/ies) checked, ${malformed} malformed name(s), ${duplicates} duplicate issue number(s)`;
859
+ return { receipt };
860
+ }
861
+
862
+ // ===========================================================================
863
+ // Check 8 — Two-surface linkage: the curated guide must point INTO the
864
+ // registry, and the same issue number must never appear as a heading in both
865
+ // (that would mean the entry was copied, not linked — the "don't copy back
866
+ // and forth" rule, machine-checked).
867
+ // ===========================================================================
868
+ function checkTwoSurfaceLinkage(ctx) {
869
+ const { repoRoot, config, findings } = ctx;
870
+ const receipt = makeReceipt();
871
+ const check = "8 two-surface-linkage";
872
+
873
+ const guideText = readFileSafeText(join(repoRoot, config.gotchasFile));
874
+ const registryFiles = listDirFiles(repoRoot, config.gotchasDir);
875
+
876
+ if (guideText === null) {
877
+ findings.warn(check, `${config.gotchasFile} does not exist — nothing to check (optional surface, per templates/gotchas-d-README.md)`);
878
+ return { receipt };
879
+ }
880
+ receipt.add(config.gotchasFile, guideText);
881
+ if (registryFiles === null) {
882
+ findings.warn(check, `${config.gotchasFile} exists but ${config.gotchasDir}/ does not — a curated guide with no registry to point into`);
883
+ return { receipt };
884
+ }
885
+
886
+ const registryNums = new Set(
887
+ registryFiles
888
+ .map((f) => GOTCHA_FILENAME_RE.exec(f.split("/").pop()))
889
+ .filter(Boolean)
890
+ .map((m) => m[1]),
891
+ );
892
+
893
+ // Headings in the guide of the shape "... #N ..." or "... (#N) ..." are read
894
+ // as this guide claiming to COVER issue N's gotcha, not merely mentioning
895
+ // the number in prose — deliberately narrow, matching how the two surfaces
896
+ // are documented to cross-reference in templates/gotchas-d-README.md.
897
+ const guideHeadingIssues = new Set();
898
+ for (const line of blankFences(guideText)) {
899
+ const h = /^#{1,6}\s+.*$/.exec(line);
900
+ if (!h) continue;
901
+ const m = /#(\d+)\b/.exec(h[0]);
902
+ if (m) guideHeadingIssues.add(m[1]);
903
+ }
904
+
905
+ let copyDrift = 0, unlinked = 0;
906
+ for (const num of guideHeadingIssues) {
907
+ if (registryNums.has(num)) {
908
+ // The same issue is a HEADING in the guide AND a file in the registry.
909
+ // That is fine when the heading merely LINKS into the entry — flag it
910
+ // only when the guide's own body for that heading contains no link to
911
+ // the matching gotchas.d/ file, which is the actual copy-drift signal.
912
+ const sectionRe = new RegExp(`^#{1,6}\\s+.*#${num}\\b.*$([\\s\\S]*?)(?=^#{1,6}\\s|\\Z)`, "m");
913
+ const m = sectionRe.exec(guideText + "\n");
914
+ const body = m ? m[1] : "";
915
+ if (!new RegExp(`gotchas\\.d/${num}-`, "i").test(body) && !body.includes(`${config.gotchasDir}/${num}-`)) {
916
+ copyDrift++;
917
+ findings.warn(
918
+ check,
919
+ `${config.gotchasFile}: the #${num} section is also a gotchas.d/ entry but its body never links into ${config.gotchasDir}/${num}-*.md — looks copied, not linked`,
920
+ );
921
+ }
922
+ }
923
+ }
924
+ receipt.note = `${guideHeadingIssues.size} guide heading(s) with an issue number, ${registryNums.size} registry entries, ${copyDrift} copy-drift flag(s)`;
925
+ return { receipt };
926
+ }
927
+
928
+ // ---------------------------------------------------------------------------
929
+ // Main
930
+ // ---------------------------------------------------------------------------
931
+
932
+ const CHECKS = [
933
+ ["1 router-integrity", checkRouterIntegrity],
934
+ ["2 orphans", checkOrphans],
935
+ ["3 drafts-in-docs", checkDraftsInDocs],
936
+ ["4 router-size-budget", checkRouterSizeBudget],
937
+ ["5 dated-files-in-docs", checkDatedFilesInDocs],
938
+ ["6 section-citations", checkGotchaCitations],
939
+ ["7 gotchas-d-registry", checkGotchasDRegistry],
940
+ ["8 two-surface-linkage", checkTwoSurfaceLinkage],
941
+ ];
942
+
943
+ function main() {
944
+ const args = parseArgs(process.argv.slice(2));
945
+ if (args.help) {
946
+ console.log(HELP);
947
+ process.exit(0);
948
+ }
949
+ const repoRoot = args.repo;
950
+ if (!existsSync(repoRoot)) {
951
+ console.error(`docs-lint: --repo ${repoRoot} does not exist`);
952
+ process.exit(2);
953
+ }
954
+ const config = buildConfig(repoRoot);
955
+ const findings = makeFindings();
956
+ const ctx = { repoRoot, config, findings, ignoreFilter: makeIgnoreFilter(repoRoot) };
957
+
958
+ const results = [];
959
+ for (const [name, fn] of CHECKS) {
960
+ const before = findings.all.length;
961
+ const { receipt } = fn(ctx);
962
+ const produced = findings.all.slice(before);
963
+ results.push({ name, receipt: receipt.summary(), note: receipt.note ?? null, findings: produced });
964
+ }
965
+
966
+ const hasFail = findings.all.some((f) => f.severity === "fail");
967
+
968
+ if (args.json) {
969
+ console.log(JSON.stringify({ repoRoot, config, results, hasFail }, null, 2));
970
+ } else {
971
+ console.log(`docs-lint — ${repoRoot}`);
972
+ console.log(`router: ${config.router ?? "(none found)"}`);
973
+ console.log("");
974
+ for (const r of results) {
975
+ const failCount = r.findings.filter((f) => f.severity === "fail").length;
976
+ const warnCount = r.findings.filter((f) => f.severity === "warn").length;
977
+ const verdict = failCount > 0 ? "FAIL" : warnCount > 0 ? "WARN" : "ok";
978
+ console.log(`[${r.name}] ${verdict} (${formatReceipt({ summary: () => r.receipt })}${r.note ? ` — ${r.note}` : ""})`);
979
+ for (const f of r.findings) {
980
+ console.log(` ${f.severity === "fail" ? "FAIL" : "warn"}: ${f.message}`);
981
+ }
982
+ }
983
+ console.log("");
984
+ console.log(
985
+ hasFail
986
+ ? "docs-lint: FAIL — at least one structural break found (see above)"
987
+ : "docs-lint: clean (advisory warnings, if any, are printed above)",
988
+ );
989
+ }
990
+ process.exit(hasFail ? 1 : 0);
991
+ }
992
+
993
+ main();