Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 47 additions & 6 deletions LifeOS/install/LIFEOS/TOOLS/ReferenceCheck.ts
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -24,21 +24,23 @@
* 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 <dir> # scan an install root other than ~/.claude (a staged release)
* bun ReferenceCheck.ts --shipped-paths # also resolve quoted install paths + spawn/dynamic-import specifiers
* bun ReferenceCheck.ts --help # usage
*
* 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)
*/

import { readFileSync, statSync, lstatSync, existsSync, readdirSync, realpathSync } from 'fs';
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) ──

Expand All @@ -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 <dir> Scan <dir> as the install root instead of ~/.claude (a staged release tree)
--shipped-paths
Expand All @@ -61,14 +66,16 @@ 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);
}

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
Expand Down Expand Up @@ -807,7 +814,9 @@ const findings: Finding[] = [];
const referenced = new Set<string>(); // 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 {
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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,
Expand All @@ -1011,6 +1040,7 @@ const summary = {
stale: stale.length,
orphan: orphan.length,
},
...(content ? { content } : {}),
};

if (jsonOutput) {
Expand Down Expand Up @@ -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.');
}
}
Expand All @@ -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);
116 changes: 116 additions & 0 deletions LifeOS/install/LIFEOS/TOOLS/lib/CitationCheck.test.ts
Original file line number Diff line number Diff line change
@@ -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);
});
});
76 changes: 76 additions & 0 deletions LifeOS/install/LIFEOS/TOOLS/lib/CitationCheck.ts
Original file line number Diff line number Diff line change
@@ -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 };
}