diff --git a/LifeOS/install/LIFEOS/TOOLS/ReferenceCheck.ts b/LifeOS/install/LIFEOS/TOOLS/ReferenceCheck.ts index b515f7b4f0..3d8ce0b2d3 100755 --- a/LifeOS/install/LIFEOS/TOOLS/ReferenceCheck.ts +++ b/LifeOS/install/LIFEOS/TOOLS/ReferenceCheck.ts @@ -1,6 +1,6 @@ #!/usr/bin/env bun /** - * @version 1.7.0 + * @version 1.8.0 * ReferenceCheck.ts — Full-surface reference validator for the LifeOS system. * * Walks every file under ~/.claude (excluding noise dirs), extracts every @@ -24,6 +24,7 @@ * bun ReferenceCheck.ts --quiet # issues only * bun ReferenceCheck.ts --changed # git-dirty files + dependents * bun ReferenceCheck.ts --stale # include stale findings + * bun ReferenceCheck.ts --content # also check `path:line` — `snippet` citations by content (lib/CitationCheck.ts) * bun ReferenceCheck.ts --orphans # include orphan findings * bun ReferenceCheck.ts --root # scan an install root other than ~/.claude (a staged release) * bun ReferenceCheck.ts --shipped-paths # also resolve quoted install paths + spawn/dynamic-import specifiers @@ -31,7 +32,7 @@ * * Exit codes: * 0 — no missing refs (stale/orphan do not fail) - * 1 — missing refs found + * 1 — missing refs found (with --content, also rotten citations) * 2 — scan error (unreadable root, etc) */ @@ -39,6 +40,7 @@ import { readFileSync, statSync, lstatSync, existsSync, readdirSync, realpathSyn import { join, resolve, dirname, relative, extname, sep, basename } from 'path'; import { execFileSync } from 'child_process'; import { getClaudeDir } from './Paths'; +import { checkCitation, findCitations, isRotten, type CitationState } from './lib/CitationCheck'; // ── Arg parsing (manual, zero deps) ── @@ -53,6 +55,9 @@ Flags: --quiet Suppress OK lines; issues only --changed Only scan git-dirty files + their dependents --stale Include stale findings (ref mtime > referrer mtime) + --content Also check "path:line" — "snippet" citations in .md files by content: + ok, moved, ambiguous, changed, gone, dir, outside. Pointers with no + snippet are counted, not checked. Not narrowed by --changed. --orphans Include orphan findings (file exists, nothing refs it) --root Scan as the install root instead of ~/.claude (a staged release tree) --shipped-paths @@ -61,7 +66,7 @@ Flags: dynamic import() specifiers — in code files too. The staged G7 lane. --help This message -Exit codes: 0 clean, 1 missing refs, 2 scan error`); +Exit codes: 0 clean, 1 missing refs (or rotten citations under --content), 2 scan error`); process.exit(0); } @@ -69,6 +74,8 @@ const jsonOutput = args.includes('--json'); const quiet = args.includes('--quiet'); const changedOnly = args.includes('--changed'); const includeStale = args.includes('--stale'); +// --content: the opt-in content check of `path:line` — `snippet` citations. public issue #2221, @drpaulobernardy +const contentMode = args.includes('--content'); const includeOrphans = args.includes('--orphans'); // --shipped-paths / --root: the staged-install lane. G7 used to run only against // the live tree, so a shipped file naming a path that the release scrub removes @@ -807,7 +814,9 @@ const findings: Finding[] = []; const referenced = new Set(); // absolute paths of files that are referenced let scannedFiles = 0; let scannedRefs = 0; -const historicalSkipped: string[] = []; // files whose own frontmatter says `references: historical` +const historicalSkipped: string[] = []; +const citationResults: { file: string; line: number; cited: string; snippet: string; state: CitationState; foundAt?: number[] }[] = []; +let citationsWithoutSnippet = 0; // files whose own frontmatter says `references: historical` let allFiles: string[]; try { @@ -842,6 +851,17 @@ for (const file of allFiles) { historicalSkipped.push(relative(CLAUDE_DIR, file)); continue; } + if (contentMode && file.endsWith('.md')) { + const found = findCitations(content); + citationsWithoutSnippet += found.withoutSnippet; + for (const c of found.citations) { + try { + citationResults.push({ file: relative(CLAUDE_DIR, file), line: c.line, cited: `${c.path}:${c.citedLine}`, snippet: c.snippet, ...checkCitation(CLAUDE_DIR, c.path, c.citedLine, c.snippet) }); + } catch (e) { + scanFailed(`cannot check citation ${c.path}:${c.citedLine}`, file, e); + } + } + } const refs = extractRefs(content, file); if (refs.length > 0) fileRefs.set(file, refs); for (const r of refs) { @@ -998,6 +1018,15 @@ const elapsedMs = Date.now() - startedAt; const missing = uniqueFindings.filter(f => f.type === 'missing'); const stale = uniqueFindings.filter(f => f.type === 'stale'); const orphan = uniqueFindings.filter(f => f.type === 'orphan'); +const movedCitations = citationResults.filter(c => c.state === 'moved'); +const rottenCitations = citationResults.filter(c => isRotten(c.state)); +const content = contentMode ? { + citations: citationResults.length, + ok: citationResults.filter(c => c.state === 'ok').length, + moved: movedCitations, + rotten: rottenCitations, + withoutSnippet: citationsWithoutSnippet, +} : null; const summary = { scannedFiles, @@ -1011,6 +1040,7 @@ const summary = { stale: stale.length, orphan: orphan.length, }, + ...(content ? { content } : {}), }; if (jsonOutput) { @@ -1039,7 +1069,18 @@ if (jsonOutput) { `\nReferenceCheck: ${scannedFiles} files, ${scannedRefs} refs, ${missing.length} missing, ${stale.length} stale, ${orphan.length} orphan, ${historicalSkipped.length} historical (skipped by their own frontmatter) — ${elapsedMs}ms` ); } - if (uniqueFindings.length === 0 && !quiet) { + if (content && movedCitations.length > 0) { + console.error(`\n📍 MOVED CITATIONS (${movedCitations.length}) — the claim holds, the line number is old:`); + for (const c of movedCitations) console.error(` ${c.file}:${c.line} → ${c.cited} now at line ${c.foundAt![0]}`); + } + if (content && rottenCitations.length > 0) { + console.error(`\n❌ ROTTEN CITATIONS (${rottenCitations.length}) — re-read the cited code:`); + for (const c of rottenCitations) console.error(` ${c.file}:${c.line} → ${c.cited} (${c.state}${c.foundAt ? ` at lines ${c.foundAt.join(', ')}` : ''})`); + } + if (content && (!quiet || movedCitations.length + rottenCitations.length > 0)) { + console.error(`Citations: ${content.citations} checked, ${content.ok} ok, ${movedCitations.length} moved, ${rottenCitations.length} rotten; ${content.withoutSnippet} path:line without a snippet (not checked)`); + } + if (uniqueFindings.length === 0 && rottenCitations.length === 0 && !quiet) { console.error('✅ All references valid.'); } } @@ -1051,4 +1092,4 @@ if (scanErrors.length > 0) { if (scanErrors.length > 20) console.error(` … and ${scanErrors.length - 20} more`); process.exit(2); } -process.exit(missing.length > 0 ? 1 : 0); +process.exit(missing.length > 0 || rottenCitations.length > 0 ? 1 : 0); diff --git a/LifeOS/install/LIFEOS/TOOLS/lib/CitationCheck.test.ts b/LifeOS/install/LIFEOS/TOOLS/lib/CitationCheck.test.ts new file mode 100644 index 0000000000..6fc122ce07 --- /dev/null +++ b/LifeOS/install/LIFEOS/TOOLS/lib/CitationCheck.test.ts @@ -0,0 +1,116 @@ +// CitationCheck and ReferenceCheck --content (public issue #2221). +import { afterAll, beforeAll, describe, expect, test } from "bun:test"; +import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { checkCitation, findCitations, isRotten } from "./CitationCheck"; + +let root = "", outsideDir = ""; +beforeAll(() => { + root = mkdtempSync(join(tmpdir(), "citation-root-")); + outsideDir = mkdtempSync(join(tmpdir(), "citation-outside-")); + mkdirSync(join(root, "hooks")); + writeFileSync(join(root, "hooks/Foo.ts"), ["const a = 1;", "if (!session) return;", "log('x');", "log('x');", "use `tick` here"].join("\n")); + writeFileSync(join(outsideDir, "Secret.ts"), "if (!session) return;\n"); + symlinkSync(join(outsideDir, "Secret.ts"), join(root, "hooks/Link.ts")); +}); +afterAll(() => { rmSync(root, { recursive: true, force: true }); rmSync(outsideDir, { recursive: true, force: true }); }); + +describe("checkCitation", () => { + test("ok: the cited line holds the snippet", () => { + expect(checkCitation(root, "hooks/Foo.ts", 2, "if (!session)")).toEqual({ state: "ok" }); + }); + test("moved: the snippet is on exactly one other line", () => { + expect(checkCitation(root, "hooks/Foo.ts", 1, "if (!session)")).toEqual({ state: "moved", foundAt: [2] }); + }); + test("ambiguous: the snippet is on several other lines", () => { + expect(checkCitation(root, "hooks/Foo.ts", 1, "log('x')")).toEqual({ state: "ambiguous", foundAt: [3, 4] }); + }); + test("changed: the snippet is nowhere in the file", () => { + expect(checkCitation(root, "hooks/Foo.ts", 2, "if (!user)")).toEqual({ state: "changed" }); + }); + test("gone: the file does not exist", () => { + expect(checkCitation(root, "hooks/Bar.ts", 2, "if (!session)")).toEqual({ state: "gone" }); + }); + test("dir: the path is a directory", () => { + expect(checkCitation(root, "hooks", 2, "if (!session)")).toEqual({ state: "dir" }); + }); + test("outside: a symlink or a ../ path that leaves the checked tree", () => { + expect(checkCitation(root, "hooks/Link.ts", 1, "if (!session)")).toEqual({ state: "outside" }); + const rel = join("..", outsideDir.split("/").pop()!, "Secret.ts"); + expect(checkCitation(root, rel, 1, "if (!session)")).toEqual({ state: "outside" }); + expect(checkCitation(root, join(outsideDir, "Secret.ts"), 1, "if (!session)")).toEqual({ state: "outside" }); + }); + test("~/.claude/ reads as the checked root", () => { + expect(checkCitation(root, "~/.claude/hooks/Foo.ts", 2, "if (!session)")).toEqual({ state: "ok" }); + }); + test("only ok and moved are not rotten", () => { + expect(["ok", "moved", "ambiguous", "changed", "gone", "dir", "outside"].filter(s => !isRotten(s as any))).toEqual(["ok", "moved"]); + }); +}); + +describe("findCitations", () => { + test("single and double backtick snippets, pointers without a snippet counted, fences skipped", () => { + const text = [ + "See `hooks/Foo.ts:2` — `if (!session)` and `hooks/Foo.ts:5` — `` use `tick` here ``.", + "Also `hooks/Foo.ts:3` with no snippet, and `step:2`, which is not a path.", + "```", + "`hooks/Foo.ts:9` — `example only`", + "```", + ].join("\n"); + const { citations, withoutSnippet } = findCitations(text); + expect(citations).toEqual([ + { line: 1, path: "hooks/Foo.ts", citedLine: 2, snippet: "if (!session)" }, + { line: 1, path: "hooks/Foo.ts", citedLine: 5, snippet: "use `tick` here" }, + ]); + expect(withoutSnippet).toBe(1); + expect(checkCitation(root, "hooks/Foo.ts", 5, citations[1].snippet).state).toBe("ok"); + }); + test("tilde fences and a 4-backtick fence holding a 3-backtick example are skipped; text after the close is read", () => { + const text = [ + "~~~markdown", + "`hooks/Foo.ts:9` — `inside tildes`", + "~~~", + "````markdown", + "```", + "inner example", + "```", + "`hooks/Foo.ts:9` — `between the fences`", + "````", + "```ts", + "~~~ does not close a backtick fence", + "`hooks/Foo.ts:9` — `after the tildes`", + "```", + "After: `hooks/Foo.ts:2` — `if (!session)`.", + ].join("\n"); + expect(findCitations(text).citations).toEqual([{ line: 14, path: "hooks/Foo.ts", citedLine: 2, snippet: "if (!session)" }]); + }); +}); + +describe("ReferenceCheck --content", () => { + const tool = join(import.meta.dir, "..", "ReferenceCheck.ts"); + const run = (...args: string[]) => { + const p = Bun.spawnSync(["bun", tool, "--root", root, "--json", ...args], { stdout: "pipe", stderr: "pipe" }); + return { code: p.exitCode, json: JSON.parse(p.stdout.toString()) }; + }; + beforeAll(() => { + writeFileSync(join(root, "NOTES.md"), "Holds: `hooks/Foo.ts:2` — `if (!session)`.\nMoved: `hooks/Foo.ts:1` — `if (!session)`.\nRotten: `hooks/Foo.ts:2` — `if (!user)`.\nBare: `hooks/Foo.ts:3`.\n"); + }); + test("the default run does not read citations and its output has no content key", () => { + const { code, json } = run(); + expect(json.content).toBeUndefined(); + expect(code).toBe(0); + }); + test("--stale alone does not read citations either", () => { + expect(run("--stale").json.content).toBeUndefined(); + }); + test("--content reports moved and rotten citations, counts pointers without a snippet, and exits 1", () => { + const { code, json } = run("--content"); + expect(json.content.citations).toBe(3); + expect(json.content.ok).toBe(1); + expect(json.content.moved.map((c: any) => [c.line, c.foundAt])).toEqual([[2, [2]]]); + expect(json.content.rotten.map((c: any) => [c.line, c.state])).toEqual([[3, "changed"]]); + expect(json.content.withoutSnippet).toBe(1); + expect(code).toBe(1); + }); +}); diff --git a/LifeOS/install/LIFEOS/TOOLS/lib/CitationCheck.ts b/LifeOS/install/LIFEOS/TOOLS/lib/CitationCheck.ts new file mode 100644 index 0000000000..7d969e49f7 --- /dev/null +++ b/LifeOS/install/LIFEOS/TOOLS/lib/CitationCheck.ts @@ -0,0 +1,76 @@ +/** + * CitationCheck — checks a `path:line` — `snippet` citation by content, never by date (public issue #2221). + * + * A doc that says "see `hooks/Foo.hook.ts:128` — `if (!session)`" makes a claim about code. The snippet is what makes the + * claim checkable: with a line number alone, nothing tells "the code moved" from "the code is gone", and a file's mtime + * changes whenever anything in it is touched. The states: + * ok — line N contains the snippet. + * moved — it does not, but the snippet is on exactly one other line: the claim holds, only the number is old. + * ambiguous — the snippet is on several other lines: the citation cannot be re-pointed. → rotten + * changed — the snippet is nowhere in the file. → rotten + * gone — the cited path does not exist. → rotten + * dir — the cited path is a directory, which has no lines. → rotten + * outside — the cited path resolves (symlinks followed) outside the checked tree. → rotten + * + * It checks that the citation still points at the same code, not that the sentence next to it is true. + * The snippet convention is optional: a `path:line` pointer with no snippet is not checked here, only counted. + */ + +import { readFileSync, realpathSync, statSync } from 'fs'; +import { isAbsolute, join, relative, sep } from 'path'; + +export type CitationState = 'ok' | 'moved' | 'ambiguous' | 'changed' | 'gone' | 'dir' | 'outside'; +export interface CitationResult { state: CitationState; foundAt?: number[] } +export const isRotten = (s: CitationState): boolean => s !== 'ok' && s !== 'moved'; + +/** `path:line` — `snippet`, with the snippet in single backticks, or in double ones when it holds a backtick. */ +export const CITATION_RE = /`([^`\s]+?):(\d+)`\s*[—–-]\s*(?:``\s?(.+?)\s?``|`([^`]+)`)/g; +/** A `path:line` pointer with no snippet after it. The path has a dot or a slash, so `step:2` is not one. */ +export const POINTER_RE = /`([^`\s]*[./][^`\s]*?):(\d+)`(?!\s*[—–-]\s*`)/g; + +/** + * The state of one citation. `path` is relative to `root`, absolute, or starts with `~/.claude/` (read as `root`). + * It resolves through `realpathSync` and must stay inside `root`. An unreadable root or file throws: a citation that + * could not be read is never reported as fine. + */ +export function checkCitation(root: string, path: string, line: number, snippet: string): CitationResult { + const rootReal = realpathSync(root); + const rel = path.startsWith('~/.claude/') ? path.slice('~/.claude/'.length) : path; + let real: string; + try { + real = realpathSync(isAbsolute(rel) ? rel : join(rootReal, rel)); + } catch (e: any) { + if (e?.code === 'ENOENT' || e?.code === 'ENOTDIR') return { state: 'gone' }; + throw e; + } + const inside = relative(rootReal, real); + if (inside === '..' || inside.startsWith('..' + sep) || isAbsolute(inside)) return { state: 'outside' }; + if (statSync(real).isDirectory()) return { state: 'dir' }; + const lines = readFileSync(real, 'utf-8').split('\n'); + if (lines[line - 1]?.includes(snippet)) return { state: 'ok' }; + const foundAt = lines.flatMap((l, i) => (l.includes(snippet) ? [i + 1] : [])); + if (foundAt.length > 1) return { state: 'ambiguous', foundAt }; + return foundAt.length === 1 ? { state: 'moved', foundAt } : { state: 'changed' }; +} + +export interface Citation { line: number; path: string; citedLine: number; snippet: string } + +/** The citations in a markdown text, and how many `path:line` pointers in it have no snippet. Fenced blocks are examples + * and are skipped. A fence is three or more backticks or tildes, as in CommonMark: it closes only on the same + * character, at least as long and with nothing after it, so a 4-backtick fence can hold a 3-backtick example. */ +export function findCitations(text: string): { citations: Citation[]; withoutSnippet: number } { + const citations: Citation[] = []; + let withoutSnippet = 0; + let fence: { char: string; size: number } | null = null; + text.split('\n').forEach((lineText, i) => { + const f = /^\s*(`{3,}|~{3,})(.*)$/.exec(lineText); + if (!fence && f && !(f[1][0] === '`' && f[2].includes('`'))) { fence = { char: f[1][0], size: f[1].length }; return; } + if (fence && f && f[1][0] === fence.char && f[1].length >= fence.size && !f[2].trim()) { fence = null; return; } + if (fence) return; + for (const m of lineText.matchAll(CITATION_RE)) { + citations.push({ line: i + 1, path: m[1], citedLine: Number(m[2]), snippet: (m[3] ?? m[4]) }); + } + withoutSnippet += [...lineText.matchAll(POINTER_RE)].length; + }); + return { citations, withoutSnippet }; +}