@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.
- package/LICENSE +21 -0
- package/README.md +312 -3
- package/README.vi.md +281 -0
- package/audit/audit.mjs +3035 -0
- package/package.json +26 -5
- package/templates/README.md +257 -0
- package/templates/adr-README.md +57 -0
- package/templates/branch-name.yml +51 -0
- package/templates/ci-laravel.yml +540 -0
- package/templates/ci-node.yml +291 -0
- package/templates/ci-python.yml +281 -0
- package/templates/deploy-xserver.yml +531 -0
- package/templates/dist-refs.yml +177 -0
- package/templates/docs-lint.mjs +993 -0
- package/templates/docs-lint.yml +55 -0
- package/templates/gotchas-d-README.md +41 -0
- package/templates/identity-vocabulary.example +58 -0
- package/templates/npx-launcher.mjs +213 -0
- package/templates/pre-commit-dispatch +88 -0
- package/templates/pre-commit-identity +267 -0
- package/templates/pre-push-guard +137 -0
- package/templates/release-auto.yml +475 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13806 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +278 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify-endpoint.js +170 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +521 -0
- package/tools/lib/release-policy.js +358 -0
- package/tools/lib/release-tag.js +225 -0
- package/tools/lib/ship-batch.js +277 -0
- package/tools/lib/ship-roles.js +71 -0
- package/tools/lib/ship-target-sync.js +181 -0
- package/tools/lib/shipguard.js +317 -0
- package/tools/lib/shipped-branch.js +56 -0
- package/tools/lib/solo.js +213 -0
- package/tools/lib/squash.js +515 -0
- package/tools/lib/stale-base.js +70 -0
- package/tools/lib/stamp.js +740 -0
- package/tools/lib/state.js +262 -0
- package/tools/lib/teardown.js +83 -0
- package/tools/lib/trust-humans.js +104 -0
- package/tools/lib/util.js +98 -0
- package/tools/lib/wake.js +188 -0
- package/tools/lib/workflow-triggers.js +273 -0
- package/tools/lib/writes-authority.js +237 -0
- package/tools/lib/yaml.js +101 -0
- 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();
|