Repository navigation
ReferenceCheck: opt-in --content check of path:line citations (#2221) - #2688
drpaulobernardy wants to merge 2 commits into
Conversation
…miessler#2221) lib/CitationCheck.ts holds the check, checkCitation(root, path, line, snippet) -> state, with the states ok, moved, ambiguous, changed, gone, dir and outside. Paths resolve through realpathSync and must stay inside the checked tree. ReferenceCheck --content reads the citations in each scanned .md, reports moved and rotten ones, counts path:line pointers with no snippet, and exits 1 on a rotten citation. The default run and --stale are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014YTdW6sTViEVVK8c3DeQVC
isihussain
left a comment
There was a problem hiding this comment.
Architectural & Quality Review
Thank you @drpaulobernardy. Adding content-aware validation to ReferenceCheck via CitationCheck is a huge improvement over simple mtime or line-existence checks. Distinguishing between ok, moved (single unambiguous relocation), and truly rotten citations (ambiguous, changed, gone) gives actionable feedback to doc maintainers.
Here is a review across correctness, performance, and markdown fence parsing:
1. Performance: File Content Caching
In checkCitation():
const lines = readFileSync(real, 'utf-8').split('\n');When documentation files contain multiple citations targeting the same source file (e.g., citing several functions in Boundary.ts or MemoryRetriever.ts), checkCitation performs a synchronous disk read and string split for each citation individually.
Recommendation: Passing an optional line cache (cache?: Map<string, string[]>) across the audit run will eliminate redundant disk reads and memory allocations when verifying documents with clustered citations:
const lines = cache?.get(real) ?? readFileSync(real, 'utf-8').split('\n');
cache?.set(real, lines);2. Markdown Parsing: Code Fence Matching
In findCitations():
if (lineText.trimStart().startsWith('```')) { fenced = !fenced; return; }Two edge cases in markdown code fences:
- Tilde fences (
~~~): CommonMark supports code fences using tildes. If a doc uses~~~markdown, the citations inside it won't be recognized as fenced. - Nested fences: If a 4-backtick block (`````) encloses a 3-backtick example block (````), the boolean toggle
fenced = !fencedflips prematurely in the middle of the block.
Matching with a regex or recording fence character/length (like in `IsaSections`) handles nested examples robustly:
const fenceMatch = /^\s*(`{3,}|~{3,})/.exec(lineText);3. Path Security: Boundary Containment
The check:
const inside = relative(rootReal, real);
if (inside === '..' || inside.startsWith('..' + sep) || isAbsolute(inside)) return { state: 'outside' };correctly follows symlinks with realpathSync and enforces that citations cannot be used to probe files outside the repository root.
The test suite in CitationCheck.test.ts covers all 7 citation states thoroughly. Solid addition to the ReferenceCheck toolset!
… fences findCitations toggled on every line starting with three backticks, so a ~~~ fence was read as prose and a 4-backtick fence holding a 3-backtick example closed at the first inner fence. A fence now follows CommonMark: three or more backticks or tildes, closed only by the same character, at least as long, with nothing after it. New test, red before the change. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014YTdW6sTViEVVK8c3DeQVC
|
Note 🤖 Paulino (AI assistant) responding on behalf of Dr. Paulo Thanks @isihussain, the fence point was right.
|
Note
🤖 Paulino (AI assistant) responding on behalf of Dr. Paulo
Carries #2221 as the opt-in
--contentmode you described there.What changes
LIFEOS/TOOLS/lib/CitationCheck.tsholds the check:checkCitation(root, path, line, snippet) -> { state, foundAt? }, plusfindCitations(text), which reads the citations in a markdown text and counts thepath:linepointers with no snippet. It has no state of its own, so other tools can call it without the CLI.ok,moved(the snippet is on exactly one other line),ambiguous(on several),changed,gone,dir, andoutside. Onlyokandmovedare not rotten.realpathSyncand must stay inside the checked tree. A path that leaves it, through../, an absolute path or a symlink, comes backoutside. That state is new: your condition needed a name for it, and it counts as rotten.ReferenceCheck.ts --contentreads the citations in every scanned.md. Fenced blocks are skipped, as the rest of the tool skips them, and so are files markedreferences: historical. It lists moved and rotten citations, prints a count line, and in--jsonadds acontentkey. A rotten citation exits 1; a citation that cannot be read is a scan error and exits 2.path:linepointers with no snippet keep today's behavior and are counted separately (withoutSnippet). The snippet may sit in double backticks when it holds a backtick.--staleare unchanged: without--contentno citation is read, and thecontentkey never appears.--changeddoes not narrow--content, because the useful case is a citation whose target changed, and that is not the referring file. The help text says so.Tests
LIFEOS/TOOLS/lib/CitationCheck.test.tshas 13 tests:../path and an absolute path.~/.claude/prefix reads as the checked root.findCitationshandles single and double backticks, skips fenced blocks, and counts pointers.--root: the default run and--staleshow nocontentkey and exit 0 even with a rotten citation present, while--contentreports it and exits 1.All 13 pass. On
main, the module does not exist, so the file fails to load. With onlyReferenceCheck.tsreverted, the--contentCLI test fails.Checked on a real install
--jsonand--stale --jsonwere run with the tool frommainand with this branch. The output is byte-identical exceptelapsedMs.--contentfound only one citation there. I also rancheckCitationdirectly over 726 notes that use the convention: 7,738 ok, 9 moved and 294 gone. The 9 moved match what the install's own citation checker reports; the gone ones are paths written relative to another checkout, which this check rightly does not follow.One limit, the same as in the issue: this checks that a citation still points at the same code, not that the sentence next to it is true.
🤖 Generated with Claude Code