Fix: lint doesn't validate raw/ source: paths or body links - #88
Conversation
check_source_provenance validates the sources: frontmatter list for wiki/
and inventory/ documents, but silently skips raw/ -- even though raw/*.md
has a required source: field per the documented schema (wiki-structure.md
"Source File Format (raw/)") that can be a local filepath, not just a URL.
check_links (the generic body markdown-link checker) has the same gap,
scoped to {"wiki", "inventory"} only.
Net effect: nothing in raw/ was ever checked for broken source references,
in frontmatter or in body prose. This surfaced downstream in a downstream wiki instance where a script generated 144 raw/notes and raw/data pointer
records with a source: path one directory level too shallow -- lint stayed
green (0 critical, 0 warnings) the whole time because raw/ simply wasn't in
scope for either check.
Fix:
- check_source_provenance: add a raw/ branch that resolves the source:
scalar the same way inventory/ resolves its sources: list entries (skip
http(s):// URLs and the literal MANUAL, since raw/ sources are documented
as "URL or filepath or MANUAL").
- check_links: add "raw" to the directory scope so body markdown links
inside raw/*.md are checked like they already are in wiki/ and
inventory/.
- Applied identically to scripts/llm-wiki and its three bundled bin/
mirrors (claude-plugin/bin/llm-wiki, plugins/llm-wiki/bin/llm-wiki,
plugins/llm-wiki-opencode/bin/llm-wiki) via the project's own
sync-codex-plugin.sh / sync-opencode-plugin.sh scripts (their `cp
"$LOCAL_HELPER" ...` steps only; the rsync-dependent skill-asset sync was
skipped since this change touches no skill content and rsync isn't
available on this machine).
Adds tests/fixtures/defects/raw-source-unresolved/ (golden-wiki with one
raw/papers source: pointed at a nonexistent local path) and wires it into
test-local-cli-lint.sh next to the existing missing-index/bad-frontmatter
cases, asserting the new "Raw source reference does not resolve" warning.
Verified against current upstream/master (d78e119):
- golden-wiki lint output is unchanged by this patch (same 2 pre-existing
staleness warnings, none new -- confirms no false positives on existing
raw/ pointer records).
- Full test suite: 37/42 pass before this patch, 38/43 pass after (the one
new test, passing; the same 5 pre-existing failures before and after,
which look environment-specific -- Windows/Git-Bash temp-dir and
chmod-permission-simulation cases -- rather than caused by this change).
This branch is rebased directly onto the current upstream/master rather
than an out-of-date fork branch, so the diff is scoped to just this fix
(this supersedes PR nvk#87, which was opened from a branch 273 commits behind
master and unrelated to it by 189 commits, producing an unreviewable
787-file diff that was closed unmerged).
1a2ad10 to
0420c0b
Compare
|
Thanks @emercons — your detailed report and the 144-file reproduction made the underlying gap very clear. I opened a clean replacement at #89. It keeps the useful explicit-local-path validation while avoiding false positives for If you have a chance, would you please test #89 against the downstream corpus that originally exposed this? You can check it out with: gh pr checkout 89 --repo nvk/llm-wiki
./scripts/llm-wiki lint /path/to/your/.wikiThe expected result is that the 144 genuinely broken relative |
The bug
check_source_provenancevalidates thesources:frontmatter list forwiki/andinventory/documents, but has no branch forraw/— even though everyraw/*.mdfile has a requiredsource:field per the documented schema (references/wiki-structure.md, "Source File Format (raw/)":source: "URL or filepath or MANUAL"), and that field is frequently a local filepath, not just a URL.check_links(the generic body markdown-link checker) has the identical gap: it's scoped toif rel.parts[0] not in {"wiki", "inventory"}: continue, so body links insideraw/*.mdare never checked either.Net effect: nothing under
raw/is ever checked for a broken source reference, neither in frontmatter nor in body prose, even thoughcheck_frontmatter_schemaalready requires thesourcefield to be present.How I found it
A downstream wiki instance (local
.wiki/init over an existing research corpus) had a generator script produce 144raw/notes/andraw/data/pointer records whosesource:field was one directory level too shallow (../../research/...instead of../../../research/..., sinceraw/notes/is three levels deep from the wiki root). None of those 144 broken references ever resolved to a real file.lintstayed green the entire time — 0 critical, 0 warnings — becauseraw/simply isn't in scope for either check that would have caught it.The fix
check_source_provenance: add araw/branch that resolves thesource:scalar the same wayinventory/resolves itssources:list entries — skiphttp(s)://URLs and the literalMANUAL(per the documented"URL or filepath or MANUAL"contract), otherwise resolve via the existingresolve_source_refhelper and warn if it doesn't resolve.check_links: add"raw"to the directory scope so body markdown links insideraw/*.mdget the same broken-link check thatwiki/andinventory/already have.scripts/llm-wikiand its three bundledbin/mirrors (claude-plugin/bin/llm-wiki,plugins/llm-wiki/bin/llm-wiki,plugins/llm-wiki-opencode/bin/llm-wiki), matching whatsync-codex-plugin.sh/sync-opencode-plugin.shwould produce.Tests
Added
tests/fixtures/defects/raw-source-unresolved/— a copy ofgolden-wikiwith oneraw/papers/*.md'ssource:pointed at a nonexistent local path — and wired it intotest-local-cli-lint.shright after the existingmissing-index/bad-frontmattercases, asserting the new"Raw source reference does not resolve"warning.Verified against current
upstream/master(d78e119):golden-wikilint output is unchanged by this patch (same 2 pre-existing staleness warnings, none new — confirms no false positives on existingraw/pointer records).chmod-based permission simulation — rather than caused by this change).Note on supersession
This supersedes #87, which I opened from a branch that had drifted 273 commits behind
master(and carried 189 unrelated commits of its own), producing an unreviewable 787-file/+29862-line diff that GitHub reported asDIRTYand that I closed unmerged without ever actually landing the fix. This branch is cut fresh from currentupstream/masterand contains only the one commit above.