fix(docs): resolve wiki links repo-wide on updates and drop dotted-ref false positives

Dogfooding the self-repair loop exposed two gaps. Interlinking resolved
refs only against the run page set, so on an incremental update a
regenerated page lost every link to unchanged pages (433 prose refs
resolved to 17 links); LinkIndex.add_prior_page_ids now widens
resolution with the persisted page ids, the same pattern related_pages
already used, and both passes share it. The symbol validator flagged
dotted member accesses (GeneratedPage.updated_at, Page.id) that the
symbol table cannot verify since dataclass fields and ORM columns are
not AST symbols; 13 of 14 surviving warnings in the dogfood run were
such false positives, each able to trigger a pointless repair retry.
Dotted refs are now skipped; single-name hallucinations still flag.

Author: RaghavChamadiya

packages/core/src/repowise/core/generation/interlinking.py

@@ -34,6 +34,10 @@
 # Markdown code fence — content inside is verbatim source, not refs.
 _FENCE_RE = re.compile(r"```.*?```", re.DOTALL)
 
+# Page types whose target_path is a real file path. Shared with
+# related_pages, which widens the same index the same way.
+FILE_BACKED_PAGE_TYPES = frozenset({"file_page", "api_contract", "infra_page"})
+
 
 # ---------------------------------------------------------------------------
 # Link index
@@ -67,17 +71,15 @@ def build(
             if not page.target_path:
                 continue
             idx.by_target[page.target_path] = page.page_id
-            if page.page_type in {"file_page", "api_contract", "infra_page"}:
+            if page.page_type in FILE_BACKED_PAGE_TYPES:
                 idx.by_path[page.target_path] = page.page_id
                 base = Path(page.target_path).name
                 # Don't overwrite — first wins to avoid ambiguous basename collisions.
                 idx.by_basename.setdefault(base, page.page_id)
             elif page.page_type == "symbol_spotlight":
                 # target_path is "file::name" — map the qualified form
                 if "::" in page.target_path:
-                    idx.by_symbol_qname.setdefault(
-                        page.target_path, page.page_id
-                    )
+                    idx.by_symbol_qname.setdefault(page.target_path, page.page_id)
 
         # Augment with symbol qualified_names from the parser even when
         # the symbol itself didn't get a spotlight — the link resolves
@@ -92,12 +94,33 @@ def build(
                     idx.by_symbol_qname.setdefault(qname, host_page)
                     # Last-segment match for `Foo.bar` → `bar`
                     if "." in qname:
-                        idx.by_symbol_qname.setdefault(
-                            qname.rsplit(".", 1)[-1], host_page
-                        )
+                        idx.by_symbol_qname.setdefault(qname.rsplit(".", 1)[-1], host_page)
 
         return idx
 
+    def add_prior_page_ids(self, prior_page_ids: Any) -> None:
+        """Widen resolution with page ids persisted from prior runs.
+
+        On an incremental update only the affected pages are in the run's
+        page set, so a ref to any unchanged file would fail to resolve and
+        the regenerated pages would lose their cross-page links. A page_id
+        is ``"{page_type}:{target_path}"``, so the persisted ids carry
+        enough to rebuild the path tables. Current-run pages always win
+        (``setdefault``); the reader drops links whose target no longer
+        exists, so stale prior ids are harmless. Only file-backed and
+        symbol pages are added — other page types are not path-shaped.
+        """
+        for pid in prior_page_ids or ():
+            ptype, _, tpath = str(pid).partition(":")
+            if not tpath:
+                continue
+            if ptype in FILE_BACKED_PAGE_TYPES:
+                self.by_target.setdefault(tpath, str(pid))
+                self.by_path.setdefault(tpath, str(pid))
+                self.by_basename.setdefault(Path(tpath).name, str(pid))
+            elif ptype == "symbol_spotlight" and "::" in tpath:
+                self.by_symbol_qname.setdefault(tpath, str(pid))
+
     def resolve(self, ref: str) -> str | None:
         """Resolve a single ref to a ``page_id``; ``None`` if unmatched."""
         if not ref:
@@ -156,9 +179,12 @@ def resolve_wiki_links(
         if target in seen_targets:
             continue
         seen_targets.add(target)
-        kind = "file" if "/" in ref or ref.endswith(
-            (".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs", ".java")
-        ) else "symbol"
+        kind = (
+            "file"
+            if "/" in ref
+            or ref.endswith((".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs", ".java"))
+            else "symbol"
+        )
         links.append(WikiLink(anchor=ref, target_page_id=target, kind=kind))
         if len(links) >= max_links_per_page:
             break
@@ -173,17 +199,26 @@ def resolve_wiki_links(
 def attach_wiki_links_and_backlinks(
     pages: list[GeneratedPage],
     parsed_files: list[Any] | None = None,
+    prior_page_ids: Any = None,
 ) -> None:
     """Populate ``metadata['wiki_links']`` and ``metadata['backlinks']``.
 
     Mutates each :class:`GeneratedPage` in place. Idempotent and safe
     to call on a partially-populated page set — pages with no resolved
     refs simply get empty lists.
+
+    ``prior_page_ids`` widens forward-link resolution to pages persisted
+    from earlier runs (see :meth:`LinkIndex.add_prior_page_ids`); without
+    it an incremental update can only link within its own diff. Backlinks
+    are still built for current-run pages only — a prior page's stored
+    backlinks are not reachable from here and refresh on its next
+    regeneration.
     """
     if not pages:
         return
 
     index = LinkIndex.build(pages, parsed_files)
+    index.add_prior_page_ids(prior_page_ids)
     by_id: dict[str, GeneratedPage] = {p.page_id: p for p in pages}
 
     # First pass — resolve forward links per page.
@@ -235,12 +270,8 @@ def attach_wiki_links_and_backlinks(
     log.info(
         "wiki_links.resolved",
         pages=len(pages),
-        total_forward_links=sum(
-            len(p.metadata.get("wiki_links") or []) for p in pages
-        ),
-        pages_with_backlinks=sum(
-            1 for p in pages if p.metadata.get("backlinks")
-        ),
+        total_forward_links=sum(len(p.metadata.get("wiki_links") or []) for p in pages),
+        pages_with_backlinks=sum(1 for p in pages if p.metadata.get("backlinks")),
     )
 
 

packages/core/src/repowise/core/generation/page_generator/orchestrate.py

@@ -542,7 +542,13 @@ async def execute(self) -> list[GeneratedPage]:
         try:
             from ..interlinking import attach_wiki_links_and_backlinks
 
-            attach_wiki_links_and_backlinks(all_pages, self.parsed_files)
+            attach_wiki_links_and_backlinks(
+                all_pages,
+                self.parsed_files,
+                # On incremental updates only the affected pages are in
+                # all_pages; the persisted ids keep resolution repo-wide.
+                prior_page_ids=list(self.gen._prior_pages or {}),
+            )
         except Exception as exc:
             log.debug("interlinking.failed", error=str(exc))
 

packages/core/src/repowise/core/generation/page_generator/validation.py

@@ -201,11 +201,7 @@ def _validate_symbol_references(
     # (catches Click command names, decorator arguments, dict keys, etc.)
     # The source is in the context, but we only have the parsed file here.
     # Use docstring and symbol names as a cheap approximation.
-    if (
-        hasattr(parsed, "file_info")
-        and hasattr(parsed.file_info, "path")
-        and parsed.docstring
-    ):
+    if hasattr(parsed, "file_info") and hasattr(parsed.file_info, "path") and parsed.docstring:
         known.update(w for w in parsed.docstring.split() if w.isidentifier())
 
     warnings: list[str] = []
@@ -221,9 +217,17 @@ def _validate_symbol_references(
         # Skip all-uppercase (likely constants from other files: `MAX_RETRIES`)
         if ref.isupper():
             continue
+        # Skip dotted refs entirely: they are member/attribute accesses
+        # (`GeneratedPage.updated_at`, `config.coverage_pct`) or qualified
+        # module paths. Dataclass fields, ORM columns, and cross-file
+        # attribute chains are not AST symbols, so they cannot be verified
+        # here and were the dominant false-positive source in dogfooding.
+        # Whole-name hallucinations — the high-signal case — are
+        # single-segment and still flagged below.
+        if "." in ref:
+            continue
         # Check against known names
-        base = ref.split(".")[-1]
-        if ref in known or base in known:
+        if ref in known:
             continue
         # Skip if the ref is a substring of any known symbol (covers partial
         # references like `parse` when `parse_file` exists)

packages/core/src/repowise/core/generation/related_pages.py

@@ -18,6 +18,7 @@
 
 import structlog
 
+from .interlinking import FILE_BACKED_PAGE_TYPES as _FILE_BACKED
 from .interlinking import LinkIndex
 from .models import GeneratedPage
 
@@ -30,9 +31,6 @@
 _PER_REASON_CAP = 5
 _TOTAL_CAP = 12
 
-# Page types whose target_path is a real file path.
-_FILE_BACKED = frozenset({"file_page", "api_contract", "infra_page"})
-
 
 def _co_change_partners(git_meta: dict | None) -> list[tuple[str, float]]:
     """``(partner_path, co_change_count)`` pairs, strongest first."""
@@ -93,12 +91,12 @@ def attach_related_pages(
         return
 
     index = LinkIndex.build(pages)
+    index.add_prior_page_ids(prior_page_ids)
     titles = {p.page_id: p.title for p in pages}
     for pid in prior_page_ids or ():
-        ptype, _, tpath = str(pid).partition(":")
-        if ptype in _FILE_BACKED and tpath:
-            index.by_path.setdefault(tpath, pid)
-            titles.setdefault(pid, tpath)
+        _, _, tpath = str(pid).partition(":")
+        if tpath:
+            titles.setdefault(str(pid), tpath)
     pr = pagerank or {}
 
     # Adjacency from the import graph: src imports dst.

tests/unit/generation/test_interlinking.py

@@ -122,6 +122,46 @@ def test_index_resolves_basename_when_unique():
     )
 
 
+def test_prior_page_ids_widen_forward_resolution():
+    """On an incremental update, refs to pages outside the run's subset
+    resolve via the persisted prior ids; backlinks stay run-local."""
+    pages = [
+        _make_page(
+            "file_page",
+            "src/app/main.py",
+            content="Delegates to `src/lib/utils.py` and reuses `helpers.py`.",
+        ),
+    ]
+
+    attach_wiki_links_and_backlinks(
+        pages,
+        prior_page_ids=[
+            "file_page:src/lib/utils.py",
+            "file_page:src/lib/helpers.py",
+            "module_page:community-3",  # not path-shaped, ignored
+        ],
+    )
+
+    targets = {link["target_page_id"] for link in pages[0].metadata["wiki_links"]}
+    assert targets == {"file_page:src/lib/utils.py", "file_page:src/lib/helpers.py"}
+
+
+def test_current_run_pages_win_over_prior_ids():
+    """A page regenerated this run resolves to itself, not a stale prior id."""
+    pages = [
+        _make_page("file_page", "a.py", content="Uses `b.py`."),
+        _make_page("file_page", "b.py", content=""),
+    ]
+
+    attach_wiki_links_and_backlinks(pages, prior_page_ids=["file_page:b.py"])
+
+    assert pages[0].metadata["wiki_links"] == [
+        {"anchor": "b.py", "target_page_id": "file_page:b.py", "kind": "file"}
+    ]
+    # b.py is in the run, so its backlink from a.py is materialized.
+    assert pages[1].metadata["backlinks"][0]["source_page_id"] == "file_page:a.py"
+
+
 def test_link_index_build_returns_expected_keys():
     pages = [
         _make_page("file_page", "src/x.py"),

tests/unit/generation/test_symbol_validation.py

@@ -0,0 +1,42 @@
+"""Unit tests for the symbol-reference hallucination validator."""
+
+from __future__ import annotations
+
+from repowise.core.generation.page_generator.validation import _validate_symbol_references
+from repowise.core.ingestion.models import ParsedFile
+
+from .conftest import _make_file_info, _make_symbol
+
+
+def _parsed() -> ParsedFile:
+    return ParsedFile(
+        file_info=_make_file_info(path="pkg/mod.py"),
+        symbols=[_make_symbol(name="Thing", file_path="pkg/mod.py")],
+        imports=[],
+        exports=["Thing"],
+        docstring="mod",
+        parse_errors=[],
+        content_hash="h",
+    )
+
+
+def test_flags_unknown_single_name() -> None:
+    warns = _validate_symbol_references("Uses `PhantomThing` heavily.", _parsed())
+    assert warns == ["PhantomThing"]
+
+
+def test_known_symbol_and_export_pass() -> None:
+    assert _validate_symbol_references("`Thing` is exported.", _parsed()) == []
+
+
+def test_dotted_member_access_is_never_flagged() -> None:
+    """Attribute chains can't be verified from the symbol table (dataclass
+    fields and ORM columns are not symbols), so dotted refs are skipped even
+    when no segment is known."""
+    content = "`Thing.updated_at` and `config.coverage_pct` and `Fake.member` too."
+    assert _validate_symbol_references(content, _parsed()) == []
+
+
+def test_paths_commands_and_short_refs_pass() -> None:
+    content = "See `pkg/mod.py`, run `repowise-update`, index `db` by `x`."
+    assert _validate_symbol_references(content, _parsed()) == []