@nurix/etna 0.20.15 → 0.20.17

package/data/harnesses/delivery/skills/documentation/scripts/comment-strip.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+// skills/documentation/scripts/comment-strip.mjs - Proves a comment sweep changed no executable code.
+// Strips comments from a git revision of each file and from the working copy, then compares the two
+// stripped forms; a difference is a code change hiding inside a comments-only pass. String and
+// template literals, character literals, regex literals, and raw strings are honoured, so a `//`
+// inside a string is code and stays.
+
+import { execFileSync } from "node:child_process";
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { readdirSync } from "node:fs";
+import { join, extname } from "node:path";
+
+// Comment syntax per extension. `block` is null where the language has none.
+const DIALECTS = {
+    ".ts": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: true , sameLineQuotes: true },
+    ".tsx": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: true , sameLineQuotes: true },
+    ".mts": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: true , sameLineQuotes: true },
+    ".js": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: true , sameLineQuotes: true },
+    ".jsx": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: true , sameLineQuotes: true },
+    ".mjs": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: true , sameLineQuotes: true },
+    ".cjs": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: true , sameLineQuotes: true },
+    ".css": { line: null, block: ["/*", "*/"], strings: `'"`, regex: false , sameLineQuotes: true },
+    ".rs": { line: "//", block: ["/*", "*/"], strings: `"`, regex: false, rustRaw: true , sameLineQuotes: true },
+    ".go": { line: "//", block: ["/*", "*/"], strings: `'"\``, regex: false , sameLineQuotes: true },
+    ".java": { line: "//", block: ["/*", "*/"], strings: `'"`, regex: false , sameLineQuotes: true },
+    ".swift": { line: "//", block: ["/*", "*/"], strings: `"`, regex: false , sameLineQuotes: true },
+    ".kt": { line: "//", block: ["/*", "*/"], strings: `"`, regex: false , sameLineQuotes: true },
+    ".sql": { line: "--", block: ["/*", "*/"], strings: `'"`, regex: false },
+    ".py": { line: "#", block: null, strings: `'"`, regex: false },
+    ".sh": { line: "#", block: null, strings: `'"`, regex: false },
+    ".zsh": { line: "#", block: null, strings: `'"`, regex: false },
+    ".yml": { line: "#", block: null, strings: `'"`, regex: false },
+    ".yaml": { line: "#", block: null, strings: `'"`, regex: false },
+    ".toml": { line: "#", block: null, strings: `'"`, regex: false },
+};
+
+// Whether a `/` at this position opens a regex literal rather than dividing — decided by the last
+// significant character, the same way a JavaScript tokenizer decides it.
+function regexCanStart(prev) {
+    if (prev === "") return true;
+    return !/[\w$)\]]/.test(prev);
+}
+
+// The index just past a template literal starting at `i`, following `${…}` interpolations and the
+// templates and quotes nested inside them. A scan that stops at the first backtick it meets closes the
+// OUTER template on an INNER one — `${x ? `<b>${y}</b>` : ""}` — and every quote and comment downstream
+// is then read in the wrong context, which reports a whole file as changed code.
+function templateEnd(source, i) {
+    const n = source.length;
+    let j = i + 1;
+    while (j < n) {
+        const c = source[j];
+        if (c === "\\") {
+            j += 2;
+            continue;
+        }
+        if (c === "`") return j + 1;
+        if (c === "$" && source[j + 1] === "{") {
+            let depth = 1;
+            j += 2;
+            while (j < n && depth > 0) {
+                const d = source[j];
+                if (d === "\\") {
+                    j += 2;
+                    continue;
+                }
+                if (d === "`") {
+                    j = templateEnd(source, j);
+                    continue;
+                }
+                if (d === "'" || d === '"') {
+                    const quote = d;
+                    j++;
+                    while (j < n && source[j] !== quote && source[j] !== "\n") {
+                        if (source[j] === "\\") j++;
+                        j++;
+                    }
+                    j++;
+                    continue;
+                }
+                if (d === "{") depth++;
+                else if (d === "}") depth--;
+                j++;
+            }
+            continue;
+        }
+        j++;
+    }
+    return n;
+}
+
+// Remove every comment from `source`, preserving all other bytes including newlines.
+export function stripComments(source, dialect) {
+    const { line, block, strings, regex, rustRaw } = dialect;
+    const out = [];
+    let i = 0;
+    let lastSignificant = "";
+    const n = source.length;
+    while (i < n) {
+        const ch = source[i];
+        const two = source.slice(i, i + 2);
+
+        if (rustRaw && ch === "r" && (source[i + 1] === "#" || source[i + 1] === '"')) {
+            let j = i + 1;
+            let hashes = 0;
+            while (source[j] === "#") {
+                hashes++;
+                j++;
+            }
+            if (source[j] === '"') {
+                const close = '"' + "#".repeat(hashes);
+                const end = source.indexOf(close, j + 1);
+                const stop = end === -1 ? n : end + close.length;
+                out.push(source.slice(i, stop));
+                lastSignificant = '"';
+                i = stop;
+                continue;
+            }
+        }
+
+        if (line && two.slice(0, line.length) === line) {
+            const nl = source.indexOf("\n", i);
+            i = nl === -1 ? n : nl;
+            continue;
+        }
+
+        if (block && two === block[0]) {
+            const end = source.indexOf(block[1], i + 2);
+            const stop = end === -1 ? n : end + block[1].length;
+            // A JSX expression container holding only a comment — `{/* … */}` — is comment syntax
+            // whole: the braces exist to carry it, so they leave with it. Left behind, a multi-line
+            // container collapses to `{}` and reads as a code change.
+            let after = stop;
+            while (after < n && /\s/.test(source[after])) after++;
+            let brace = out.length - 1;
+            while (brace >= 0 && out[brace].trim() === "") brace--;
+            if (regex && source[after] === "}" && brace >= 0 && out[brace] === "{") {
+                out.splice(brace, 1);
+                for (const c of source.slice(i, after + 1)) if (c === "\n") out.push("\n");
+                i = after + 1;
+                continue;
+            }
+            for (const c of source.slice(i, stop)) if (c === "\n") out.push("\n");
+            i = stop;
+            continue;
+        }
+
+        if (ch === "`" && regex) {
+            const stop = templateEnd(source, i);
+            out.push(source.slice(i, stop));
+            lastSignificant = "`";
+            i = stop;
+            continue;
+        }
+
+        if (strings.includes(ch)) {
+            // A quote opens a literal only where one can actually close. In the C family and in Rust a
+            // `'` or `"` literal may not contain a raw newline, so requiring the partner on the same
+            // line is not a heuristic — it is the grammar, and it is what keeps an apostrophe in JSX
+            // text (`Couldn't load`) and a Rust char literal holding a quote (`trim_matches('"')`) from
+            // opening a string that swallows the rest of the file. Backticks span lines by design.
+            if (ch !== "`" && dialect.sameLineQuotes) {
+                let j = i + 1;
+                let closed = false;
+                while (j < n && source[j] !== "\n") {
+                    if (source[j] === "\\") {
+                        j += 2;
+                        continue;
+                    }
+                    if (source[j] === ch) {
+                        closed = true;
+                        break;
+                    }
+                    j++;
+                }
+                if (!closed) {
+                    out.push(ch);
+                    lastSignificant = ch;
+                    i++;
+                    continue;
+                }
+                out.push(source.slice(i, j + 1));
+                lastSignificant = ch;
+                i = j + 1;
+                continue;
+            }
+            out.push(ch);
+            i++;
+            while (i < n) {
+                if (source[i] === "\\") {
+                    out.push(source.slice(i, i + 2));
+                    i += 2;
+                    continue;
+                }
+                out.push(source[i]);
+                if (source[i] === ch) {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            lastSignificant = ch;
+            continue;
+        }
+
+        if (regex && ch === "/" && regexCanStart(lastSignificant)) {
+            let j = i + 1;
+            let inClass = false;
+            let closed = false;
+            while (j < n) {
+                const c = source[j];
+                if (c === "\\") {
+                    j += 2;
+                    continue;
+                }
+                if (c === "\n") break;
+                if (c === "[") inClass = true;
+                else if (c === "]") inClass = false;
+                else if (c === "/" && !inClass) {
+                    closed = true;
+                    j++;
+                    break;
+                }
+                j++;
+            }
+            if (closed) {
+                out.push(source.slice(i, j));
+                lastSignificant = "/";
+                i = j;
+                continue;
+            }
+        }
+
+        out.push(ch);
+        if (!/\s/.test(ch)) lastSignificant = ch;
+        i++;
+    }
+    // Collapse whitespace so a re-indent left behind by a removed block comment is not a finding.
+    return out
+        .join("")
+        .split("\n")
+        .map((l) => l.replace(/\s+/g, " ").trim())
+        .filter((l) => l !== "")
+        .join("\n");
+}
+
+// Comment-only lines in a source: the non-blank lines it has, less the lines that survive stripping.
+// Both sides exclude blanks, so the difference is comments alone; a trailing comment on a code line is
+// correctly not counted, because the line itself survives.
+function countCommentLines(source, dialect) {
+    const nonBlank = source.split("\n").filter((l) => l.trim() !== "").length;
+    const stripped = stripComments(source, dialect);
+    return nonBlank - (stripped === "" ? 0 : stripped.split("\n").length);
+}
+
+function gitShow(rev, path) {
+    try {
+        return execFileSync("git", ["show", `${rev}:${path}`], { encoding: "utf8", maxBuffer: 1 << 28 });
+    } catch {
+        return null;
+    }
+}
+
+function walk(dir, acc = []) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "dist") continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) walk(full, acc);
+        else if (DIALECTS[extname(entry.name)]) acc.push(full);
+    }
+    return acc;
+}
+
+function main(argv) {
+    let rev = "HEAD";
+    // With `--to`, both sides come from git and the working tree is not read — the mode that
+    // audits a sweep somebody already committed.
+    let to = null;
+    const paths = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--rev") rev = argv[++i];
+        else if (argv[i] === "--to") to = argv[++i];
+        else if (argv[i] === "--changed") {
+            const out = execFileSync("git", ["diff", "--name-only", rev], { encoding: "utf8" });
+            paths.push(...out.split("\n").filter(Boolean));
+        } else paths.push(argv[i]);
+    }
+    if (paths.length === 0) {
+        const out = execFileSync("git", ["diff", "--name-only", rev], { encoding: "utf8" });
+        paths.push(...out.split("\n").filter(Boolean));
+    }
+
+    const files = [];
+    for (const p of paths) {
+        // A revision-to-revision run names paths that need not exist in the checkout.
+        if (to !== null) {
+            if (DIALECTS[extname(p)]) files.push(p);
+            continue;
+        }
+        if (!existsSync(p)) continue;
+        if (statSync(p).isDirectory()) files.push(...walk(p));
+        else if (DIALECTS[extname(p)]) files.push(p);
+    }
+
+    let changed = 0;
+    let checked = 0;
+    let commentDelta = 0;
+    for (const file of [...new Set(files)]) {
+        const dialect = DIALECTS[extname(file)];
+        const before = gitShow(rev, file);
+        if (before === null) continue;
+        const after = to === null ? readFileSync(file, "utf8") : gitShow(to, file);
+        if (after === null) continue;
+        const a = stripComments(before, dialect);
+        const b = stripComments(after, dialect);
+        checked++;
+        // Count comment lines directly. Differencing raw length against stripped length would fold in the
+        // blank lines the strip also drops, and report a comment+blank delta under a comment label.
+        const cb = countCommentLines(before, dialect);
+        const ca = countCommentLines(after, dialect);
+        commentDelta += ca - cb;
+        if (a !== b) {
+            changed++;
+            const al = a.split("\n");
+            const bl = b.split("\n");
+            let k = 0;
+            while (k < al.length && k < bl.length && al[k] === bl[k]) k++;
+            console.log(`CODE CHANGED  ${file}`);
+            console.log(`  ${rev}: ${al[k] === undefined ? "(end of file)" : al[k].slice(0, 120)}`);
+            console.log(`  now:  ${bl[k] === undefined ? "(end of file)" : bl[k].slice(0, 120)}`);
+        }
+    }
+
+    const verdict = changed === 0 ? "no executable code changed" : `${changed} file(s) changed code`;
+    console.log(`\n${checked} file(s) compared against ${rev} — ${verdict}; comment lines ${commentDelta >= 0 ? "+" : ""}${commentDelta}.`);
+    process.exit(changed === 0 ? 0 : 1);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main(process.argv.slice(2));

package/data/harnesses/delivery/skills/documentation/scripts/doc-lint.mjs

@@ -17,19 +17,36 @@ const RULES = [
   { id: 'status-glyph', severity: 'warn', scope: 'truth', exempt: /(^|\/)docs\/(tests|operations)\//, pattern: /(^|\s)(✅|⏳|- \[[ x]\])/u, message: 'status glyph / checklist in a truth doc — tracking belongs in a record' },
   // Truth docs are supposed to cite records, and record filenames are dated — so a date inside a link
   // target or a code span is a path, not narration. Strip those before matching.
-  { id: 'date-in-truth-doc', severity: 'warn', scope: 'truth', strip: /\[[^\]]*\]\([^)]*\)|`[^`]*`/g, pattern: /\b20\d{2}-\d{2}-\d{2}\b/, message: 'date in a truth doc — only the AD Decision Changelog and structure.md Health Log tails carry dates' },
+  { id: 'date-in-truth-doc', severity: 'block', scope: 'truth', strip: /\[[^\]]*\]\([^)]*\)|`[^`]*`|^(last-reviewed|last-updated|rev|harness-version):.*$/gm, pattern: /\b20\d{2}-\d{2}-\d{2}\b/, message: 'date in a truth doc — cite the record by name and link; the closed exceptions are the frontmatter tooling keys, an AD Decision Changelog tail and structure.md\'s Health Log tail' },
 ];
 
 // Sections inside a truth doc where dated history is sanctioned (the two bridges).
 const BRIDGE_HEADINGS = /^#{1,4}\s+(decision changelog|health log)\b/i;
-// Instruction files and generated trees are a different genre — out of this linter's scope.
-const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$|\.bkp\./;
-const RECORD = /(^|\/)docs\/(history|research|memory)\//;
+// Instruction files, the three harness-installed mirrors and generated trees are out of scope; the authoring
+// roots are anchored to the repo root.
+const SKIP = /^(\.claude|\.agents|\.codex|skills|rules|agents|harness)\/|(^|\/)(node_modules|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$|\.bkp\./;
+// `operations/issues/YYYY-MM-DD-{slug}.md` is a sanctioned record genre (`type: issue`, the
+// `issue-bridge` skill's local pack) living outside the record folders, so it is named here too —
+// graded as a truth document it fails the date rule for carrying the date its filename already does.
+const RECORD = /(^|\/)docs\/(history|research|memory)\/|(^|\/)docs\/operations\/issues\//;
 
-// Classify a path: skipped genre, record, or truth.
-function scopeOf(path) {
+const RECORD_TYPES = /^(changelog-entry|plan|migration|migration-runbook|research|brainstorm|journal|record|ledger|issue|triage|project-memory|agent-memory)$/;
+const TRUTH_LOCATIONS = /(^|\/)docs\/(features|architecture|tests|acceptance)\//;
+
+// The genre a document declares for itself, from its own frontmatter `type:` key, or null.
+function declaredType(text) {
+  if (!text.startsWith('---')) return null;
+  const end = text.indexOf('\n---', 3);
+  const m = /^type:\s*(\S+)\s*$/m.exec(end === -1 ? text : text.slice(0, end));
+  return m ? m[1] : null;
+}
+
+// Classify a document: record or truth, the declared genre outranking the path.
+function scopeOf(path, text) {
   if (SKIP.test(path)) return 'skip';
-  return RECORD.test(path) ? 'record' : 'truth';
+  if (RECORD.test(path)) return 'record';
+  const declared = text === undefined ? null : declaredType(text);
+  return declared && RECORD_TYPES.test(declared) ? 'record' : 'truth';
 }
 
 // Yield prose lines only: frontmatter, fenced code blocks, and bridge sections drop out.
@@ -37,13 +54,21 @@ function proseLines(text) {
   const lines = text.split('\n');
   const out = [];
   let inFence = false;
+  let fenceMarker = '';
   let inFrontmatter = lines[0] === '---';
   let inBridge = false;
   let bridgeLevel = 0;
   for (let i = inFrontmatter ? 1 : 0; i < lines.length; i++) {
     const line = lines[i];
     if (inFrontmatter) { if (line === '---') inFrontmatter = false; continue; }
-    if (/^\s*(```|~~~|````)/.test(line)) { inFence = !inFence; continue; }
+    // A fence closes only on a marker at least as long as the one that opened it, so a nested ```yaml
+    // inside a ```markdown block does not invert the state and expose the outer block as prose.
+    const fence = /^\s*(`{3,}|~{3,})/.exec(line);
+    if (fence) {
+      if (!inFence) { inFence = true; fenceMarker = fence[1]; }
+      else if (fence[1][0] === fenceMarker[0] && fence[1].length >= fenceMarker.length) inFence = false;
+      continue;
+    }
     if (inFence) continue;
     const heading = line.match(/^(#{1,4})\s/);
     if (heading) {
@@ -64,9 +89,9 @@ function fileDisables(text) {
 }
 
 function lintFile(path, findings) {
-  const scope = scopeOf(path);
-  if (scope === 'skip' || !existsSync(path)) return;
+  if (SKIP.test(path) || !existsSync(path)) return;
   const text = readFileSync(path, 'utf8');
+  const scope = scopeOf(path, text);
   const disabled = fileDisables(text);
   const lines = proseLines(text);
 
@@ -85,6 +110,13 @@ function lintFile(path, findings) {
     }
   }
 
+  // A record genre declared in a settled truth location is a contradiction, not a classification.
+  if (TRUTH_LOCATIONS.test(path)) {
+    const declared = declaredType(text);
+    if (declared && RECORD_TYPES.test(declared) && !disabled.has('record-type-in-truth-location'))
+      findings.push({ path, n: 1, severity: 'block', id: 'record-type-in-truth-location', message: `\`type: ${declared}\` is a record genre declared in a truth location — move the file to \`docs/history/\` if it is a record, or give it its location's genre` });
+  }
+
   // A folder index (Readme.md/README.md) is a browse page, not a feature doc — it owns no code.
   const isFolderIndex = /(^|\/)(readme)\.md$/i.test(path);
   if (scope === 'truth' && !isFolderIndex && /(^|\/)docs\/features\/[^/]+\.md$/.test(path)) {

package/data/harnesses/delivery/skills/documentation/scripts/source-lint.mjs

@@ -0,0 +1,222 @@
+// skills/documentation/scripts/source-lint.mjs - mechanical checks over source comments (header path, density, tense, shouting)
+// Usage: node source-lint.mjs <file | dir ...> | node source-lint.mjs --changed   (git-changed + untracked source files)
+// Exit 1 when any block-severity finding survives. Escape hatch: a `source-lint-disable: id[, id]` comment,
+// file-wide in the first 20 lines or on the offending line; the reason goes in a second comment beside it.
+// The convention itself is the harness `CLAUDE.md` § File Structure; this checks only what is mechanical.
+
+import { readFileSync, existsSync, statSync, readdirSync } from 'node:fs';
+import { execSync, spawnSync } from 'node:child_process';
+import { basename, extname } from 'node:path';
+
+// Comment syntax per extension, and whether a leading `#!` shebang may precede the header.
+const DIALECTS = {
+  '.ts': '//', '.tsx': '//', '.mts': '//', '.cts': '//',
+  '.js': '//', '.jsx': '//', '.mjs': '//', '.cjs': '//',
+  '.rs': '//', '.go': '//', '.java': '//', '.kt': '//', '.swift': '//', '.c': '//', '.h': '//', '.cpp': '//',
+  '.css': '/*', '.scss': '//',
+  '.sql': '--',
+  '.py': '#', '.sh': '#', '.zsh': '#', '.bash': '#', '.rb': '#',
+};
+
+// Generated trees, vendored copies, and formats with no comment syntax are a different genre. `.claude/`,
+// `.agents/` and `.codex/` are harness-owned in every consumer — overwritten on the next roll, so a finding
+// there names work nobody in that repo can land. The forge lints its own copies at `harness/`, not here.
+const SKIP = /(^|\/)(node_modules|dist|build|target|\.git|\.claude|\.agents|\.codex|coverage|__screenshots__|data\/harnesses)\/|\.min\.|\.d\.ts$|(^|\/)(pnpm-lock|package-lock)\./;
+// A generated file says so in its own first lines; the convention exempts it.
+const GENERATED = /@generated|DO NOT EDIT|AUTO-GENERATED|This file was generated/i;
+// Below this a file is too small for a density ratio to mean anything.
+const RATIO_MIN_LINES = 40;
+// A file-level ceiling, not a target. The house style sits near 14%; a file past this is carrying prose.
+// It grades INHERITED density, so it only warns: a file somebody else wrote at 42% is not this session's
+// debt, and a wall that blocks on it stops every commit in the repo until a rewrite pass lands.
+const RATIO_CEILING = 0.35;
+// The ceiling that actually holds the line, because it grades only the lines THIS change adds. The measured
+// regression that prompted the rule ran at 28% on new files while the tree sat at 14% — a file-level 35%
+// ceiling passes that cleanly, so the file-level rule cannot be what stops it. You own what you add.
+const ADDED_RATIO_CEILING = 0.25;
+// Below this an added-line ratio is noise — a two-line fix with one comment is not a prose problem.
+const ADDED_MIN_LINES = 20;
+// The header's own ceiling in wrapped lines, from the measured p99 of the convention's own sweep.
+const HEADER_MAX_LINES = 6;
+// A comment block longer than this is a document living in a source file.
+const BLOCK_MAX_LINES = 12;
+
+const RULES = {
+  'header-missing': { severity: 'block', message: 'no file-path header comment — add one naming this file\'s repo-relative path' },
+  'header-path-stale': { severity: 'block', message: 'the header names another path — a header a move left behind reads as current' },
+  'header-too-long': { severity: 'warn', message: `header past ${HEADER_MAX_LINES} lines — two or three sentences, and the fuller account goes in its doc` },
+  'comment-ratio': { severity: 'warn', message: `comment lines over ${Math.round(RATIO_CEILING * 100)}% of the file — the rationale belongs in the owning doc` },
+  'comment-ratio-added': { severity: 'block', message: `over ${Math.round(ADDED_RATIO_CEILING * 100)}% of the lines this change adds are comments — one sentence per symbol, and the rationale goes in the owning doc` },
+  'comment-block-long': { severity: 'warn', message: `a comment block past ${BLOCK_MAX_LINES} lines — one sentence per symbol; a paragraph is a doc, unless it names a booby trap` },
+  'comment-narration': { severity: 'warn', message: 'history, a ticket or decision-record reference, or a dated note in a comment — the journey belongs in a record' },
+  'comment-shouting': { severity: 'warn', message: 'an ALL-CAPS clause opener — comments are third-person present tense, not emphasis' },
+};
+
+const NARRATION = /\bused to\b|\bno longer\b|\bpreviously\b(?!-)|\bwas (renamed|removed|extracted|folded|migrated|replaced|ported)\b|\bported from\b|\bfor now\b|\bnot yet implemented\b|\b(AD|ADR)-\d+\b|\b20\d{2}-\d{2}-\d{2}\b/i;
+const SHOUTING = /(?:^|[.:;]\s+)([A-Z][A-Z0-9 ,'`\-]{14,})(?=[.,:]|\s+[a-z])/;
+
+// The comment token for a path, or null when the format has none.
+function tokenFor(path) {
+  return DIALECTS[extname(path)] ?? null;
+}
+
+// True when the line is a comment line in this dialect (an open block, a continuation, or a line comment).
+function isCommentLine(line, token) {
+  const t = line.trim();
+  if (t === '') return false;
+  if (token === '//') return t.startsWith('//') || t.startsWith('/*') || t.startsWith('*') || t.startsWith('*/');
+  if (token === '/*') return t.startsWith('/*') || t.startsWith('*') || t.startsWith('*/');
+  if (token === '--') return t.startsWith('--') || t.startsWith('/*') || t.startsWith('*');
+  return t.startsWith(token);
+}
+
+// The leading comment block: its lines, skipping a shebang and any blank lines above it.
+function leadingBlock(lines, token) {
+  let i = 0;
+  if (lines[0]?.startsWith('#!')) i = 1;
+  while (i < lines.length && lines[i].trim() === '') i++;
+  const block = [];
+  while (i < lines.length && isCommentLine(lines[i], token)) {
+    block.push(lines[i]);
+    i++;
+  }
+  return block;
+}
+
+// Rule ids disabled file-wide (first 20 lines) or on one line.
+function disabledIds(text) {
+  const head = text.split('\n').slice(0, 20).join('\n');
+  const ids = new Set();
+  for (const m of head.matchAll(/source-lint-disable:\s*([a-z0-9,\s-]+)/g))
+    for (const id of m[1].split(',')) ids.add(id.trim());
+  return ids;
+}
+
+// The comment ratio of the lines this change ADDS, or null where there is nothing to grade. An untracked
+// file is added whole; a tracked one is graded on its `+` lines against HEAD. Reading the diff rather than
+// the file is what makes the rule fair: inherited prose is somebody else's row, and a session that adds
+// twenty clean lines to a 60%-comment file passes.
+function addedRatio(path, token) {
+  let added;
+  try {
+    const tracked = spawnSync('git', ['ls-files', '--error-unmatch', path], { encoding: 'utf8' }).status === 0;
+    if (!tracked) added = readFileSync(path, 'utf8').split('\n');
+    else {
+      const out = spawnSync('git', ['diff', '-U0', '--no-color', 'HEAD', '--', path], { encoding: 'utf8' });
+      if (out.status !== 0) return null;
+      added = out.stdout.split('\n').filter((l) => l.startsWith('+') && !l.startsWith('+++')).map((l) => l.slice(1));
+    }
+  } catch {
+    return null;
+  }
+  const nonBlank = added.filter((l) => l.trim() !== '');
+  if (nonBlank.length < ADDED_MIN_LINES) return null;
+  const comments = nonBlank.filter((l) => isCommentLine(l, token)).length;
+  return { ratio: comments / nonBlank.length, comments, lines: nonBlank.length };
+}
+
+function lintFile(path, findings) {
+  if (SKIP.test(path)) return false;
+  const token = tokenFor(path);
+  if (!token) return false;
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch {
+    return false;
+  }
+  if (GENERATED.test(text.split('\n').slice(0, 5).join('\n'))) return false;
+
+  const lines = text.split('\n');
+  const disabled = disabledIds(text);
+  const add = (id, n, excerpt) => {
+    if (disabled.has(id)) return;
+    const lineDisable = /source-lint-disable:\s*([a-z0-9,\s-]+)/.exec(lines[n - 1] ?? '');
+    if (lineDisable && lineDisable[1].split(',').some((x) => x.trim() === id)) return;
+    findings.push({ path, n, id, ...RULES[id], excerpt });
+  };
+
+  // --- the header ---------------------------------------------------------------------------------
+  const block = leadingBlock(lines, token);
+  if (block.length === 0) add('header-missing', 1);
+  else {
+    const head = block.join('\n');
+    // The FIRST path-shaped token, compared exactly — containment would pass a header reading
+    // `packages/old-name/src/app.ts` for a file at `src/app.ts`, which is the rename this catches.
+    const named = /([\w.@-]+(?:\/[\w.@-]+)*\.[A-Za-z]{1,5})\b/.exec(head);
+    if (!named) add('header-missing', 1);
+    else if (named[1] !== path) {
+      if (basename(named[1]) === basename(path)) add('header-path-stale', 1, named[1]);
+      else add('header-missing', 1, `names ${named[1]}`);
+    }
+    if (block.length > HEADER_MAX_LINES) add('header-too-long', 1, `${block.length} lines`);
+  }
+
+  // --- density, block length, and comment prose --------------------------------------------------
+  let commentLines = 0;
+  let nonBlank = 0;
+  let runStart = 0;
+  let run = 0;
+  lines.forEach((line, i) => {
+    if (line.trim() !== '') nonBlank++;
+    if (isCommentLine(line, token)) {
+      commentLines++;
+      if (run === 0) runStart = i + 1;
+      run++;
+      const body = line.replace(/^\s*(\/\/+|\/\*+|\*+\/?|--+|#+)\s?/, '');
+      if (NARRATION.test(body)) add('comment-narration', i + 1, body.slice(0, 90));
+      const shout = SHOUTING.exec(body);
+      if (shout) add('comment-shouting', i + 1, shout[1].slice(0, 60));
+      return;
+    }
+    if (run > BLOCK_MAX_LINES) add('comment-block-long', runStart, `${run} lines`);
+    run = 0;
+  });
+  if (run > BLOCK_MAX_LINES) add('comment-block-long', runStart, `${run} lines`);
+  if (nonBlank >= RATIO_MIN_LINES) {
+    const ratio = commentLines / nonBlank;
+    if (ratio > RATIO_CEILING) add('comment-ratio', 1, `${Math.round(ratio * 100)}% of ${nonBlank} lines`);
+  }
+  const grown = addedRatio(path, token);
+  if (grown && grown.ratio > ADDED_RATIO_CEILING)
+    add('comment-ratio-added', 1, `${grown.comments} of ${grown.lines} added lines`);
+  return true;
+}
+
+function expandDirs(paths) {
+  const out = [];
+  for (const p of paths) {
+    if (!existsSync(p)) continue;
+    if (!statSync(p).isDirectory()) {
+      out.push(p);
+      continue;
+    }
+    for (const e of readdirSync(p, { withFileTypes: true })) {
+      if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+      out.push(...expandDirs([`${p.replace(/\/$/, '')}/${e.name}`]));
+    }
+  }
+  return out;
+}
+
+const args = process.argv.slice(2);
+let files = args.filter((a) => a !== '--changed');
+if (args.includes('--changed')) {
+  const out = execSync('git diff --name-only HEAD; git ls-files --others --exclude-standard', { encoding: 'utf8', shell: '/bin/bash' });
+  files = [...new Set([...files, ...out.split('\n').filter(Boolean)])];
+}
+files = expandDirs(files);
+if (!files.length) {
+  console.error('usage: node source-lint.mjs <file | dir ...> | --changed');
+  process.exit(2);
+}
+
+const findings = [];
+let checked = 0;
+for (const f of files) if (lintFile(f, findings)) checked++;
+
+for (const f of findings.sort((a, b) => (a.severity === b.severity ? 0 : a.severity === 'block' ? -1 : 1)))
+  console.log(`${f.path}:${f.n} [${f.severity}] ${f.id} — ${f.message}${f.excerpt ? `: "${f.excerpt}"` : ''}`);
+const blocks = findings.filter((f) => f.severity === 'block').length;
+console.log(`\n${findings.length} finding(s), ${blocks} blocking, ${checked} file(s) checked.`);
+process.exit(blocks ? 1 : 0);