Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(docs): self-repair for hallucinated symbol refs, cross-reference prompt discipline, repo-wide link resolution on updates (#872)

Raghav Chamadiya466afd8613db
diff --git a/packages/core/src/repowise/core/generation/interlinking.py b/packages/core/src/repowise/core/generation/interlinking.py
index 41f9fd077..2f52ccae3 100644
--- a/packages/core/src/repowise/core/generation/interlinking.py
+++ b/packages/core/src/repowise/core/generation/interlinking.py
@@ -34,6 +34,10 @@ _BACKTICK_REF_RE = re.compile(r"(?<!`)` *([A-Za-z_/.][\w./\-]*?) *`(?!`)")
# 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,7 +71,7 @@ class LinkIndex:
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.
@@ -75,9 +79,7 @@ class LinkIndex:
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 @@ class LinkIndex:
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")),
)
diff --git a/packages/core/src/repowise/core/generation/models.py b/packages/core/src/repowise/core/generation/models.py
index 8879cce69..98144e173 100644
--- a/packages/core/src/repowise/core/generation/models.py
+++ b/packages/core/src/repowise/core/generation/models.py
@@ -145,6 +145,13 @@ class GenerationConfig:
# that carry a decision; harvested candidates pass the same substring gate
# as every other source before storage.
harvest_decisions: bool = True
+ # ---- In-loop self-repair (hallucinated symbol refs) ----------------
+ # When the post-generation validator flags at least this many backtick
+ # identifiers that do not exist in the documented file, the tier-1 file
+ # page is re-generated ONCE with the invalid refs named in a corrective
+ # note, and the cleaner of the two drafts is kept. 0 disables the retry.
+ # Pages reused from a prior run are never retried (validated back then).
+ repair_warning_threshold: int = 2
jobs_dir: str = ".repowise/jobs"
large_file_source_pct: float = 0.4 # use structural summary when source tokens > budget * this
language: str = "en"
diff --git a/packages/core/src/repowise/core/generation/page_generator/core.py b/packages/core/src/repowise/core/generation/page_generator/core.py
index ba2494ae5..9b97b4821 100644
--- a/packages/core/src/repowise/core/generation/page_generator/core.py
+++ b/packages/core/src/repowise/core/generation/page_generator/core.py
@@ -16,7 +16,7 @@ from __future__ import annotations
import hashlib
import uuid
from collections.abc import Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
from pathlib import Path
from typing import TYPE_CHECKING, Any
@@ -307,19 +307,19 @@ class PageGenerator(PerTypeGenerationMixin):
target_path=parsed.file_info.path,
content_hash=content_hash,
)
- # Phase-2 harvest: pull any trailing decision block out of the page
- # before it is wrapped + stored. The gate verifies each quote against
- # ``file_source_snippet`` — exactly what the model was shown — so a
- # quote it can't have seen is dropped. Stored on page.metadata for the
- # persistence layer to fold into the evidence pipeline.
- harvested: list[dict] = []
- if self._config.harvest_decisions:
- clean_content, harvested = harvest_decisions(
- response.content,
- source_text=ctx.file_source_snippet or "",
- evidence_file=parsed.file_info.path,
+ harvested = self._strip_harvested_decisions(response, ctx, parsed.file_info.path)
+ # Cross-check LLM output against actual symbols
+ hal_warnings = _validate_symbol_references(response.content, parsed)
+ repair_outcome: str | None = None
+ threshold = self._config.repair_warning_threshold
+ if (
+ threshold > 0
+ and len(hal_warnings) >= threshold
+ and not response.usage.get("reused_from_prior_run")
+ ):
+ response, harvested, hal_warnings, repair_outcome = await self._repair_file_page(
+ parsed, ctx, user_prompt, response, harvested, hal_warnings
)
- response.content = clean_content
page = self._build_generated_page(
"file_page",
parsed.file_info.path,
@@ -331,8 +331,6 @@ class PageGenerator(PerTypeGenerationMixin):
)
if harvested:
page.metadata["harvested_decisions"] = harvested
- # Cross-check LLM output against actual symbols
- hal_warnings = _validate_symbol_references(response.content, parsed)
if hal_warnings:
log.warning(
"hallucination_check",
@@ -341,9 +339,85 @@ class PageGenerator(PerTypeGenerationMixin):
refs=hal_warnings[:5],
)
page.metadata["hallucination_warnings"] = hal_warnings
+ if repair_outcome:
+ page.metadata["self_repair"] = repair_outcome
_attach_file_provenance(page, ctx)
return page
+ def _strip_harvested_decisions(
+ self,
+ response: GeneratedResponse,
+ ctx: FilePageContext,
+ evidence_file: str,
+ ) -> list[dict]:
+ """Phase-2 harvest: pull any trailing decision block out of the page
+ before it is wrapped + stored. The gate verifies each quote against
+ ``file_source_snippet`` — exactly what the model was shown — so a
+ quote it can't have seen is dropped. Returned for page.metadata so the
+ persistence layer can fold it into the evidence pipeline.
+ """
+ if not self._config.harvest_decisions:
+ return []
+ clean_content, harvested = harvest_decisions(
+ response.content,
+ source_text=ctx.file_source_snippet or "",
+ evidence_file=evidence_file,
+ )
+ response.content = clean_content
+ return harvested
+
+ async def _repair_file_page(
+ self,
+ parsed: ParsedFile,
+ ctx: FilePageContext,
+ user_prompt: str,
+ response: GeneratedResponse,
+ harvested: list[dict],
+ hal_warnings: list[str],
+ ) -> tuple[GeneratedResponse, list[dict], list[str], str]:
+ """Bounded self-repair for hallucinated symbol references.
+
+ Re-calls the provider once with the invalid refs named in a corrective
+ note, re-validates, and keeps whichever draft validates cleaner. Both
+ calls' tokens are folded into the kept response so page-level token
+ accounting (and cost) reflects the real spend. One retry per page,
+ never recursive; the caller has already excluded reused prior pages.
+ """
+ path = parsed.file_info.path
+ correction = (
+ "\n\nIMPORTANT CORRECTION: a previous draft of this page referenced "
+ "identifiers that do not exist in this file: "
+ + ", ".join(f"`{r}`" for r in sorted(hal_warnings)[:15])
+ + ". Do not mention these names. Only reference symbols, imports, "
+ "exports, and files that appear in the context above."
+ )
+ # No target_path/content_hash here: the retry must reach the provider,
+ # since the cross-run reuse gate would hand back the draft that failed.
+ retry = await self._call_provider("file_page", user_prompt + correction, str(uuid.uuid4()))
+ retry_harvested = self._strip_harvested_decisions(retry, ctx, path)
+ retry_warnings = _validate_symbol_references(retry.content, parsed)
+ improved = len(retry_warnings) < len(hal_warnings)
+ log.info(
+ "hallucination_repair",
+ path=path,
+ warnings_before=len(hal_warnings),
+ warnings_after=len(retry_warnings),
+ kept="retry" if improved else "original",
+ )
+ if improved:
+ kept, kept_harvested, kept_warnings = retry, retry_harvested, retry_warnings
+ else:
+ kept, kept_harvested, kept_warnings = response, harvested, hal_warnings
+ # replace() rather than mutating: either draft may also live in the
+ # in-memory prompt cache, which must keep its per-call token counts.
+ kept = replace(
+ kept,
+ input_tokens=response.input_tokens + retry.input_tokens,
+ output_tokens=response.output_tokens + retry.output_tokens,
+ cached_tokens=response.cached_tokens + retry.cached_tokens,
+ )
+ return kept, kept_harvested, kept_warnings, "improved" if improved else "kept_original"
+
async def _generate_file_page_tier2(
self,
parsed: ParsedFile,
diff --git a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
index ea16a0a51..793a0d72e 100644
--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
@@ -542,7 +542,13 @@ class _GenerationRun:
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))
diff --git a/packages/core/src/repowise/core/generation/page_generator/validation.py b/packages/core/src/repowise/core/generation/page_generator/validation.py
index ffa27b461..defa9727c 100644
--- a/packages/core/src/repowise/core/generation/page_generator/validation.py
+++ b/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)
diff --git a/packages/core/src/repowise/core/generation/related_pages.py b/packages/core/src/repowise/core/generation/related_pages.py
index cc7bed178..209544637 100644
--- a/packages/core/src/repowise/core/generation/related_pages.py
+++ b/packages/core/src/repowise/core/generation/related_pages.py
@@ -18,6 +18,7 @@ from typing import Any
import structlog
+from .interlinking import FILE_BACKED_PAGE_TYPES as _FILE_BACKED
from .interlinking import LinkIndex
from .models import GeneratedPage
@@ -30,9 +31,6 @@ _REASON_PRIORITY = ("imports", "imported-by", "co-changes-with", "same-module")
_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.
diff --git a/packages/core/src/repowise/core/generation/report.py b/packages/core/src/repowise/core/generation/report.py
index 1bda65051..d5d59895a 100644
--- a/packages/core/src/repowise/core/generation/report.py
+++ b/packages/core/src/repowise/core/generation/report.py
@@ -24,6 +24,7 @@ class GenerationReport:
decisions_extracted: int = 0
elapsed_seconds: float = 0.0
hallucination_warning_count: int = 0
+ self_repaired_page_count: int = 0
@classmethod
def from_pages(
@@ -37,6 +38,7 @@ class GenerationReport:
) -> GenerationReport:
by_type = dict(Counter(p.page_type for p in pages))
hal_count = sum(1 for p in pages if p.metadata.get("hallucination_warnings"))
+ repair_count = sum(1 for p in pages if p.metadata.get("self_repair"))
return cls(
pages_by_type=by_type,
total_input_tokens=sum(p.input_tokens for p in pages),
@@ -47,6 +49,7 @@ class GenerationReport:
decisions_extracted=decisions_count,
elapsed_seconds=elapsed,
hallucination_warning_count=hal_count,
+ self_repaired_page_count=repair_count,
)
@property
@@ -92,5 +95,7 @@ def render_report(report: GenerationReport, console: object) -> None:
"Hallucination warnings",
f"[yellow]{report.hallucination_warning_count}[/yellow]",
)
+ if report.self_repaired_page_count:
+ table.add_row("Self-repaired pages", str(report.self_repaired_page_count))
console.print(table) # type: ignore[union-attr]
diff --git a/packages/core/src/repowise/core/generation/templates/file_page.j2 b/packages/core/src/repowise/core/generation/templates/file_page.j2
index 517b3ca01..d27abdd1e 100644
--- a/packages/core/src/repowise/core/generation/templates/file_page.j2
+++ b/packages/core/src/repowise/core/generation/templates/file_page.j2
@@ -234,4 +234,11 @@ examples where helpful.
This file is stable and low-centrality. Provide a concise overview focused on the
public API only. Skip implementation details.
{% endif %}
+Cross-references: when a dependency, dependent, or co-change partner listed
+above genuinely explains this file's behavior, name it in backticks exactly as
+listed (e.g. `path/to/file.py` or `SymbolName`) so the reference resolves to a
+wiki link. Do not add references purely for link density, do not mention a file
+just because it imports this one, and never name a file or symbol that is not
+listed in the context above.
+
Generate a complete wiki page following the sections above.
diff --git a/packages/core/src/repowise/core/generation/templates/module_page.j2 b/packages/core/src/repowise/core/generation/templates/module_page.j2
index 23b9de2d1..b05f554fd 100644
--- a/packages/core/src/repowise/core/generation/templates/module_page.j2
+++ b/packages/core/src/repowise/core/generation/templates/module_page.j2
@@ -88,6 +88,11 @@ Most active file: `{{ module_git_summary.most_active_file }}`
({{ module_git_summary.most_active_commits_90d }} commits in 90 days)
{% endif %}
+Cross-references: name the module's key files and the neighboring modules it consumes
+or serves in backticks exactly as listed above so they resolve to wiki links. Mention
+a neighbor only where it explains this module's role: no references added purely for
+link density, and no reciprocal mentions out of symmetry.
+
Generate a complete wiki page following the sections above. Required sections in the
output: ## Overview, ## Public API Summary, ## Architecture Notes. Use the supplied
key files, decisions, and external systems to ground the narrative; do not fabricate
diff --git a/tests/unit/generation/test_interlinking.py b/tests/unit/generation/test_interlinking.py
index 29ca3bd81..5aa6c7565 100644
--- a/tests/unit/generation/test_interlinking.py
+++ b/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"),
diff --git a/tests/unit/generation/test_self_repair.py b/tests/unit/generation/test_self_repair.py
new file mode 100644
index 000000000..f25773a3d
--- /dev/null
+++ b/tests/unit/generation/test_self_repair.py
@@ -0,0 +1,145 @@
+"""Bounded self-repair for hallucinated symbol references.
+
+When ``_validate_symbol_references`` flags >= ``repair_warning_threshold``
+invalid backtick refs on a tier-1 file page, the generator re-calls the
+provider exactly once with a corrective note naming the bad refs and keeps
+whichever draft validates cleaner. Reused prior-run pages are never retried.
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+
+from repowise.core.generation.context_assembler import ContextAssembler
+from repowise.core.generation.models import GenerationConfig, compute_page_id
+from repowise.core.generation.page_generator import PageGenerator, PriorPage
+from repowise.core.ingestion.models import ParsedFile
+from repowise.core.providers.llm.base import GeneratedResponse
+from repowise.core.providers.llm.mock import MockProvider
+
+from .conftest import _make_file_info, _make_symbol
+
+# `PhantomThing` / `GhostHelper` match no symbol, import, or export of the
+# parsed file below, are >2 chars, mixed-case, and path-free, so the
+# validator flags them. `Thing` is the file's real (and only) symbol.
+BAD_CONTENT = "## Overview\n\nUses `PhantomThing` and `GhostHelper` for math."
+CLEAN_CONTENT = "## Overview\n\nUses `Thing` for math."
+
+
+def _parsed(path: str = "pkg/mod.py") -> ParsedFile:
+ return ParsedFile(
+ file_info=_make_file_info(path=path),
+ symbols=[_make_symbol(name="Thing", file_path=path)],
+ imports=[],
+ exports=["Thing"],
+ docstring="mod",
+ parse_errors=[],
+ content_hash="h",
+ )
+
+
+def _gen_and_ctx(responses: list[GeneratedResponse], **config_overrides):
+ config = GenerationConfig(**config_overrides)
+ provider = MockProvider(responses=responses)
+ gen = PageGenerator(provider, ContextAssembler(config), config)
+ parsed = _parsed()
+ g = nx.DiGraph()
+ g.add_node(parsed.file_info.path)
+ ctx = gen._assembler.assemble_file_page(parsed, g, {}, {}, {}, b"x = 1\n")
+ return gen, provider, parsed, ctx
+
+
+async def test_retry_adopts_cleaner_draft_and_sums_tokens() -> None:
+ gen, provider, parsed, ctx = _gen_and_ctx(
+ [
+ GeneratedResponse(BAD_CONTENT, 100, 50),
+ GeneratedResponse(CLEAN_CONTENT, 200, 80),
+ ]
+ )
+
+ page = await gen._generate_file_page_from_ctx(parsed, ctx)
+
+ assert provider.call_count == 2
+ assert page.content == CLEAN_CONTENT
+ assert page.metadata["self_repair"] == "improved"
+ assert "hallucination_warnings" not in page.metadata
+ # Both calls' tokens land on the page so cost accounting is honest.
+ assert page.input_tokens == 300
+ assert page.output_tokens == 130
+
+
+async def test_retry_prompt_names_bad_refs_on_top_of_original() -> None:
+ gen, provider, parsed, ctx = _gen_and_ctx(
+ [
+ GeneratedResponse(BAD_CONTENT, 100, 50),
+ GeneratedResponse(CLEAN_CONTENT, 200, 80),
+ ]
+ )
+
+ await gen._generate_file_page_from_ctx(parsed, ctx)
+
+ original = provider.calls[0]["user_prompt"]
+ retry = provider.calls[1]["user_prompt"]
+ assert retry.startswith(original)
+ assert "`PhantomThing`" in retry
+ assert "`GhostHelper`" in retry
+
+
+async def test_retry_keeps_original_when_not_improved() -> None:
+ gen, provider, parsed, ctx = _gen_and_ctx(
+ [
+ GeneratedResponse(BAD_CONTENT, 100, 50),
+ GeneratedResponse(BAD_CONTENT, 200, 80), # retry just as bad
+ ]
+ )
+
+ page = await gen._generate_file_page_from_ctx(parsed, ctx)
+
+ assert provider.call_count == 2
+ assert page.content == BAD_CONTENT
+ assert page.metadata["self_repair"] == "kept_original"
+ assert sorted(page.metadata["hallucination_warnings"]) == ["GhostHelper", "PhantomThing"]
+ assert page.input_tokens == 300 # retry cost still counted
+
+
+async def test_no_retry_below_threshold() -> None:
+ one_warning = "Uses `PhantomThing` and `Thing`."
+ gen, provider, parsed, ctx = _gen_and_ctx([GeneratedResponse(one_warning, 100, 50)])
+
+ page = await gen._generate_file_page_from_ctx(parsed, ctx)
+
+ assert provider.call_count == 1
+ assert "self_repair" not in page.metadata
+ assert page.metadata["hallucination_warnings"] == ["PhantomThing"]
+
+
+async def test_zero_threshold_disables_retry() -> None:
+ gen, provider, parsed, ctx = _gen_and_ctx(
+ [GeneratedResponse(BAD_CONTENT, 100, 50)],
+ repair_warning_threshold=0,
+ )
+
+ page = await gen._generate_file_page_from_ctx(parsed, ctx)
+
+ assert provider.call_count == 1
+ assert "self_repair" not in page.metadata
+ assert len(page.metadata["hallucination_warnings"]) == 2
+
+
+async def test_reused_prior_page_is_never_retried() -> None:
+ gen, provider, parsed, ctx = _gen_and_ctx([GeneratedResponse(CLEAN_CONTENT, 100, 50)])
+ gen._prior_pages = {
+ compute_page_id("file_page", parsed.file_info.path): PriorPage(
+ source_hash="unused",
+ model_name=provider.model_name,
+ content=BAD_CONTENT,
+ content_hash=gen._reuse_content_hash(parsed),
+ )
+ }
+
+ page = await gen._generate_file_page_from_ctx(parsed, ctx)
+
+ assert provider.call_count == 0 # reuse gate hit, no LLM call at all
+ assert page.content == BAD_CONTENT
+ assert "self_repair" not in page.metadata
+ assert len(page.metadata["hallucination_warnings"]) == 2
diff --git a/tests/unit/generation/test_symbol_validation.py b/tests/unit/generation/test_symbol_validation.py
new file mode 100644
index 000000000..41e86c230
--- /dev/null
+++ b/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()) == []