Skip to content

Fix: lint doesn't validate raw/ source: paths or body links - #88

Closed
emercons wants to merge 1 commit into
nvk:masterfrom
emercons:fix/raw-source-provenance-check-v2
Closed

Fix: lint doesn't validate raw/ source: paths or body links#88
emercons wants to merge 1 commit into
nvk:masterfrom
emercons:fix/raw-source-provenance-check-v2

Conversation

@emercons

@emercons emercons commented Aug 24, 2026

Copy link
Copy Markdown
Contributor

The bug

check_source_provenance validates the sources: frontmatter list for wiki/ and inventory/ documents, but has no branch for raw/ — even though every raw/*.md file has a required source: 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 to if rel.parts[0] not in {"wiki", "inventory"}: continue, so body links inside raw/*.md are never checked either.

Net effect: nothing under raw/ is ever checked for a broken source reference, neither in frontmatter nor in body prose, even though check_frontmatter_schema already requires the source field to be present.

How I found it

A downstream wiki instance (local .wiki/ init over an existing research corpus) had a generator script produce 144 raw/notes/ and raw/data/ pointer records whose source: field was one directory level too shallow (../../research/... instead of ../../../research/..., since raw/notes/ is three levels deep from the wiki root). None of those 144 broken references ever resolved to a real file. lint stayed green the entire time — 0 critical, 0 warnings — because raw/ simply isn't in scope for either check that would have caught it.

The 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 (per the documented "URL or filepath or MANUAL" contract), otherwise resolve via the existing resolve_source_ref helper and warn if it doesn't resolve.
  • check_links: add "raw" to the directory scope so body markdown links inside raw/*.md get the same broken-link check that wiki/ and inventory/ already have.
  • 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), matching what sync-codex-plugin.sh/sync-opencode-plugin.sh would produce.

Tests

Added tests/fixtures/defects/raw-source-unresolved/ — a copy of golden-wiki with one raw/papers/*.md's source: pointed at a nonexistent local path — and wired it into test-local-cli-lint.sh right after 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 passes, and the same 5 pre-existing failures occur both before and after (they look environment-specific to this Windows/Git-Bash setup — temp-dir path handling, 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 as DIRTY and that I closed unmerged without ever actually landing the fix. This branch is cut fresh from current upstream/master and contains only the one commit above.

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).
@nvk

nvk commented Aug 24, 2026

Copy link
Copy Markdown
Owner

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 source: session, other provenance labels/URI schemes, local source directories, and relative links preserved inside imported raw Markdown.

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/.wiki

The expected result is that the 144 genuinely broken relative source: paths are reported without unrelated raw provenance or upstream-body-link warnings. Closing this PR in favor of #89, with credit to you there for finding and reproducing the issue. Thank you.

@nvk nvk closed this Aug 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants