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(generation): reuse unchanged pages across runs via file content hash (#757)

Swati Ahuja570ca8433127
diff --git a/packages/core/src/repowise/core/generation/models.py b/packages/core/src/repowise/core/generation/models.py
index f166b06cd..28e9bc625 100644
--- a/packages/core/src/repowise/core/generation/models.py
+++ b/packages/core/src/repowise/core/generation/models.py
@@ -216,6 +216,15 @@ class GeneratedPage:
confidence: float = 1.0
freshness_status: str = "fresh" # FreshnessStatus literal
metadata: dict[str, object] = field(default_factory=dict)
+ # Cross-run reuse KEY (not a plain file hash): SHA256 of the documented
+ # file's raw-bytes hash folded with the generation fingerprint (template,
+ # system prompt, language, style, harvest flag — see
+ # PageGenerator._reuse_content_hash). Empty for pages not built from a
+ # single file (module/overview/architecture). Unlike source_hash it is
+ # stable across runs for an unchanged file + unchanged settings, so
+ # cross-run reuse can key on it even when the rendered prompt (RAG
+ # context) drifts.
+ content_hash: str = ""
# 1-3 sentence purpose blurb extracted from the rendered content. Used by
# MCP get_context as the default narrative payload (content is gated behind
# include=["full_doc"]).
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 a972d3a34..66ec63a65 100644
--- a/packages/core/src/repowise/core/generation/page_generator/core.py
+++ b/packages/core/src/repowise/core/generation/page_generator/core.py
@@ -103,6 +103,12 @@ class PriorPage:
Lives in :class:`PageGenerator` keyed by ``page_id``. When the freshly
rendered prompt produces a matching ``source_hash`` under the same
``model_name``, the LLM call is skipped and ``content`` is reused.
+
+ ``content_hash`` (see :meth:`PageGenerator._reuse_content_hash`) is the
+ preferred reuse key when both sides have one: it stays stable across
+ runs even when the rendered prompt drifts (RAG context is rebuilt and
+ populated concurrently each run, so ``source_hash`` alone almost never
+ matches on a reindex).
"""
source_hash: str
@@ -111,6 +117,7 @@ class PriorPage:
input_tokens: int = 0
output_tokens: int = 0
cached_tokens: int = 0
+ content_hash: str = ""
class PageGenerator(PerTypeGenerationMixin):
@@ -153,6 +160,9 @@ class PageGenerator(PerTypeGenerationMixin):
# table.
self._prior_pages: dict[str, PriorPage] = prior_pages or {}
self._reuse_count: int = 0
+ # Lazily computed by _generation_fingerprint(); every input it folds
+ # is fixed for the generator's lifetime.
+ self._gen_fingerprint: str | None = None
if jinja_env is None:
templates_dir = Path(__file__).parent.parent / "templates"
@@ -285,8 +295,13 @@ class PageGenerator(PerTypeGenerationMixin):
except Exception as e:
log.debug("rag.search_failed", path=parsed.file_info.path, error=str(e))
user_prompt = self._render("file_page.j2", ctx=ctx)
+ content_hash = self._reuse_content_hash(parsed)
response = await self._call_provider(
- "file_page", user_prompt, str(uuid.uuid4()), target_path=parsed.file_info.path
+ "file_page",
+ user_prompt,
+ str(uuid.uuid4()),
+ 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
@@ -308,6 +323,7 @@ class PageGenerator(PerTypeGenerationMixin):
response,
compute_source_hash(user_prompt),
GENERATION_LEVELS["file_page"],
+ content_hash=content_hash,
)
if harvested:
page.metadata["harvested_decisions"] = harvested
@@ -339,6 +355,10 @@ class PageGenerator(PerTypeGenerationMixin):
"""
content = self._render("file_page_tier2.j2", style_prefix=False, ctx=ctx)
now = _now_iso()
+ # content_hash deliberately stays empty: the cross-run reuse gate keys
+ # on model_name (not provider_name), so stamping it here would let a
+ # later tier-1 (LLM) run reuse this deterministic template content as
+ # if the LLM had written it. Tier-2 pages are free to rebuild anyway.
page = GeneratedPage(
page_id=compute_page_id("file_page", parsed.file_info.path),
page_type="file_page",
@@ -370,17 +390,23 @@ class PageGenerator(PerTypeGenerationMixin):
user_prompt: str,
request_id: str,
target_path: str | None = None,
+ content_hash: str = "",
) -> GeneratedResponse:
"""Call the provider with caching, optionally prefixing a language instruction."""
# Persistent cross-run cache: if the page exists from a prior run, was
- # produced by the same model, and the prompt's source_hash matches,
- # reuse the stored content without an LLM call.
+ # produced by the same model, and either the documented file's bytes
+ # (content_hash) or the prompt's source_hash matches, reuse the stored
+ # content without an LLM call. content_hash is checked first: the
+ # rendered prompt embeds RAG context rebuilt fresh each run, so the
+ # prompt hash alone misses on unchanged files.
if self._config.cache_enabled and target_path is not None:
page_id = compute_page_id(page_type, target_path)
prior = self._prior_pages.get(page_id)
if prior is not None and prior.model_name == self._provider.model_name:
- current_hash = compute_source_hash(user_prompt)
- if prior.source_hash == current_hash:
+ reuse = bool(content_hash) and prior.content_hash == content_hash
+ if not reuse:
+ reuse = prior.source_hash == compute_source_hash(user_prompt)
+ if reuse:
self._reuse_count += 1
log.debug(
"page_cache.persistent_hit",
@@ -469,6 +495,58 @@ class PageGenerator(PerTypeGenerationMixin):
)
return hashlib.sha256(raw.encode()).hexdigest()
+ def _generation_fingerprint(self) -> str:
+ """Hash of every fixed input (besides the file itself) that shapes a
+ file page's content.
+
+ The prompt-hash reuse path caught changes to any of these for free —
+ they all end up in the rendered prompt or system prompt. The
+ content-hash path deliberately ignores the prompt, so it must fold
+ them explicitly or a template upgrade / language switch / style
+ switch / harvest toggle would silently keep serving old pages for
+ unchanged files:
+
+ * the file_page prompt template source (a repowise upgrade that
+ improves the template must regenerate),
+ * the file_page system prompt constant (same reason),
+ * the output language,
+ * the wiki-style fingerprint (empty for the default style),
+ * the decision-harvest flag (its directive changes what pages carry).
+
+ Graph/RAG/neighbor context is deliberately NOT folded — drifting on
+ every run is exactly what made prompt-hash reuse never fire.
+ """
+ if self._gen_fingerprint is None:
+ try:
+ template_src = self._jinja_env.loader.get_source( # type: ignore[union-attr]
+ self._jinja_env, "file_page.j2"
+ )[0]
+ except Exception:
+ template_src = ""
+ raw = "\x00".join(
+ [
+ template_src,
+ SYSTEM_PROMPTS.get("file_page", ""),
+ self._language or "en",
+ self._style.fingerprint,
+ "harvest" if self._config.harvest_decisions else "",
+ ]
+ )
+ self._gen_fingerprint = hashlib.sha256(raw.encode()).hexdigest()
+ return self._gen_fingerprint
+
+ def _reuse_content_hash(self, parsed: ParsedFile) -> str:
+ """Return the cross-run reuse key for a page built from *parsed*:
+ SHA256 of the file's raw-bytes hash folded with the generation
+ fingerprint. Stable across runs while the file and the generation
+ settings are unchanged; changes when either does. Empty when the
+ parse didn't produce a content hash (never matches — always
+ regenerates)."""
+ if not parsed.content_hash:
+ return ""
+ raw = f"{parsed.content_hash}:{self._generation_fingerprint()}"
+ return hashlib.sha256(raw.encode()).hexdigest()
+
def _build_generated_page(
self,
page_type: str,
@@ -477,6 +555,7 @@ class PageGenerator(PerTypeGenerationMixin):
response: GeneratedResponse,
source_hash: str,
level: int,
+ content_hash: str = "",
) -> GeneratedPage:
"""Wrap a GeneratedResponse in a GeneratedPage."""
now = _now_iso()
@@ -496,6 +575,7 @@ class PageGenerator(PerTypeGenerationMixin):
target_path=target_path,
created_at=now,
updated_at=now,
+ content_hash=content_hash,
)
# Record the effective style as page provenance (D10). Only for active
# styles, so default ("comprehensive") pages keep byte-identical metadata.
diff --git a/packages/core/src/repowise/core/generation/page_generator/pertype.py b/packages/core/src/repowise/core/generation/page_generator/pertype.py
index 0211d1daf..5e1cb88f2 100644
--- a/packages/core/src/repowise/core/generation/page_generator/pertype.py
+++ b/packages/core/src/repowise/core/generation/page_generator/pertype.py
@@ -41,8 +41,13 @@ class PerTypeGenerationMixin:
parsed, graph, pagerank, betweenness, community, source_bytes
)
user_prompt = self._render("file_page.j2", ctx=ctx)
+ content_hash = self._reuse_content_hash(parsed)
response = await self._call_provider(
- "file_page", user_prompt, str(uuid.uuid4()), target_path=parsed.file_info.path
+ "file_page",
+ user_prompt,
+ str(uuid.uuid4()),
+ target_path=parsed.file_info.path,
+ content_hash=content_hash,
)
return self._build_generated_page(
"file_page",
@@ -51,6 +56,7 @@ class PerTypeGenerationMixin:
response,
compute_source_hash(user_prompt),
GENERATION_LEVELS["file_page"],
+ content_hash=content_hash,
)
async def generate_symbol_spotlight(
diff --git a/packages/core/src/repowise/core/ingestion/parse_cache.py b/packages/core/src/repowise/core/ingestion/parse_cache.py
index 0423986d4..21c53a923 100644
--- a/packages/core/src/repowise/core/ingestion/parse_cache.py
+++ b/packages/core/src/repowise/core/ingestion/parse_cache.py
@@ -188,6 +188,9 @@ class ParseCache:
self.hits += 1
self._fresh[key] = blob
parsed.file_info = file_info
+ # Pickles written before ParsedFile carried content_hash deserialize
+ # with the field empty; the cache key already proves the bytes match.
+ parsed.content_hash = content_hash
return parsed
def put(self, parsed: ParsedFile, content_hash: str) -> None:
diff --git a/packages/core/src/repowise/core/ingestion/parser.py b/packages/core/src/repowise/core/ingestion/parser.py
index 77b82dea4..599cbfb10 100644
--- a/packages/core/src/repowise/core/ingestion/parser.py
+++ b/packages/core/src/repowise/core/ingestion/parser.py
@@ -54,6 +54,7 @@ from .models import (
ParsedFile,
Symbol,
TypeReference,
+ compute_content_hash,
)
from .parser_helpers import (
TYPE_HEAD_EXTRACTORS,
@@ -227,13 +228,16 @@ class ASTParser:
def parse_file(self, file_info: FileInfo, source: bytes) -> ParsedFile:
"""Parse *source* bytes and return a fully populated ParsedFile."""
lang = file_info.language
+ content_hash = compute_content_hash(source)
# Non-tree-sitter formats (OpenAPI, Dockerfile, Makefile, SQL) parse
# via dedicated handlers. Checked before the grammar lookup: none of
# these tags carry a LanguageConfig, so the no-grammar fallback below
# would otherwise swallow them.
if lang in SPECIAL_HANDLER_LANGUAGES:
- return parse_special(file_info, source, lang)
+ parsed = parse_special(file_info, source, lang)
+ parsed.content_hash = content_hash
+ return parsed
config = LANGUAGE_CONFIGS.get(lang)
# .tsx files need the JSX-aware grammar; tree-sitter-typescript's
@@ -262,6 +266,7 @@ class ASTParser:
exports=[],
docstring=None,
parse_errors=[],
+ content_hash=content_hash,
)
parser = Parser(language)
@@ -322,6 +327,7 @@ class ASTParser:
heritage=heritage,
docstring=docstring,
parse_errors=parse_errors,
+ content_hash=content_hash,
type_refs=type_refs,
local_refs=local_refs,
)
diff --git a/tests/unit/generation/test_content_hash_reuse.py b/tests/unit/generation/test_content_hash_reuse.py
new file mode 100644
index 000000000..1f6e06391
--- /dev/null
+++ b/tests/unit/generation/test_content_hash_reuse.py
@@ -0,0 +1,336 @@
+"""Cross-run page reuse keyed on file content + generation settings.
+
+The persistent cross-run cache historically keyed on ``source_hash`` —
+SHA256 of the entire rendered prompt. The prompt embeds RAG context that is
+rebuilt fresh (and populated concurrently) every run, so on a reindex even
+unchanged files rendered a different prompt and every page hit the LLM.
+
+The reuse key is ``sha256(file-bytes hash : generation fingerprint)`` where
+the fingerprint folds every fixed input that shapes page content (template,
+system prompt, language, style, harvest flag). Two invariants pinned here:
+
+* an unchanged file with unchanged settings reuses even when the prompt
+ drifts (``test_reuse_fires_when_prompt_drifts_but_file_unchanged``);
+* any settings change that would alter page content busts reuse, exactly
+ as the prompt-hash path used to guarantee.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+
+import jinja2
+import pytest
+
+from repowise.core.generation.context_assembler import ContextAssembler
+from repowise.core.generation.models import GenerationConfig
+from repowise.core.generation.page_generator import PageGenerator, PriorPage
+from repowise.core.providers.llm.mock import MockProvider
+
+DRIFTED_PROMPT_HASH = "0" * 64 # never equals a real SHA256 of the prompt
+
+
+def _make_gen(config, prior=None, language="en", jinja_env=None):
+ provider = MockProvider()
+ gen = PageGenerator(
+ provider,
+ ContextAssembler(config),
+ config,
+ prior_pages=prior,
+ language=language,
+ jinja_env=jinja_env,
+ )
+ return provider, gen
+
+
+async def _generate(gen, parsed, graph, metrics, source_bytes):
+ return await gen.generate_file_page(
+ parsed,
+ graph,
+ metrics["pagerank"],
+ metrics["betweenness"],
+ metrics["community"],
+ source_bytes,
+ )
+
+
+def _prior_from(page, *, model_name=None, content_hash=None, content=None):
+ """PriorPage as the next run would reload it, with a deliberately drifted
+ prompt hash so only the content-hash gate can fire."""
+ return {
+ page.page_id: PriorPage(
+ source_hash=DRIFTED_PROMPT_HASH,
+ model_name=model_name if model_name is not None else page.model_name,
+ content=content if content is not None else page.content,
+ content_hash=content_hash if content_hash is not None else page.content_hash,
+ )
+ }
+
+
+async def _first_run_page(parsed, graph, metrics, source_bytes, config=None, **gen_kw):
+ _, gen = _make_gen(config or GenerationConfig(), **gen_kw)
+ return await _generate(gen, parsed, graph, metrics, source_bytes)
+
+
+async def test_reuse_fires_when_prompt_drifts_but_file_unchanged(
+ sample_parsed_file, sample_graph, graph_metrics, sample_source_bytes
+):
+ """Unchanged file + same settings → reuse, even when the prompt differs."""
+ parsed = dataclasses.replace(sample_parsed_file, content_hash="a" * 64)
+ page = await _first_run_page(parsed, sample_graph, graph_metrics, sample_source_bytes)
+ assert page.content_hash # stamped for the next run
+
+ provider2, gen2 = _make_gen(GenerationConfig(), prior=_prior_from(page))
+ page2 = await _generate(gen2, parsed, sample_graph, graph_metrics, sample_source_bytes)
+
+ assert provider2.call_count == 0 # reused — no LLM call
+ assert gen2._reuse_count == 1
+ assert page2.content == page.content
+ assert page2.content_hash == page.content_hash # key stays alive across persists
+
+
+async def test_changed_file_regenerates(
+ sample_parsed_file, sample_graph, graph_metrics, sample_source_bytes
+):
+ """Different file bytes → no reuse; the page is regenerated fresh."""
+ parsed_v1 = dataclasses.replace(sample_parsed_file, content_hash="a" * 64)
+ page = await _first_run_page(parsed_v1, sample_graph, graph_metrics, sample_source_bytes)
+
+ parsed_v2 = dataclasses.replace(sample_parsed_file, content_hash="b" * 64)
+ prior = _prior_from(page, content="STALE PRIOR CONTENT")
+ provider2, gen2 = _make_gen(GenerationConfig(), prior=prior)
+ page2 = await _generate(gen2, parsed_v2, sample_graph, graph_metrics, sample_source_bytes)
+
+ assert provider2.call_count == 1
+ assert gen2._reuse_count == 0
+ assert page2.content != "STALE PRIOR CONTENT" # not stale-reused
+
+
+async def test_model_change_busts_reuse(
+ sample_parsed_file, sample_graph, graph_metrics, sample_source_bytes
+):
+ parsed = dataclasses.replace(sample_parsed_file, content_hash="a" * 64)
+ page = await _first_run_page(parsed, sample_graph, graph_metrics, sample_source_bytes)
+
+ prior = _prior_from(page, model_name="some-other-model")
+ provider2, gen2 = _make_gen(GenerationConfig(), prior=prior)
+ await _generate(gen2, parsed, sample_graph, graph_metrics, sample_source_bytes)
+
+ assert provider2.call_count == 1
+ assert gen2._reuse_count == 0
+
+
+async def test_language_change_busts_reuse(
+ sample_parsed_file, sample_graph, graph_metrics, sample_source_bytes
+):
+ """The language instruction lives in the SYSTEM prompt, so neither the
+ prompt hash nor the raw file hash sees it — the generation fingerprint
+ must. en → fr on an unchanged file regenerates in French."""
+ parsed = dataclasses.replace(sample_parsed_file, content_hash="a" * 64)
+ page = await _first_run_page(parsed, sample_graph, graph_metrics, sample_source_bytes)
+
+ provider2, gen2 = _make_gen(GenerationConfig(), prior=_prior_from(page), language="fr")
+ await _generate(gen2, parsed, sample_graph, graph_metrics, sample_source_bytes)
+
+ assert provider2.call_count == 1
+ assert gen2._reuse_count == 0
+
+
+async def test_harvest_toggle_busts_reuse(
+ sample_parsed_file, sample_graph, graph_metrics, sample_source_bytes
+):
+ """Turning decision harvesting on changes what pages carry (the harvest
+ directive is system-prompt-only) — unchanged files must regenerate."""
+ parsed = dataclasses.replace(sample_parsed_file, content_hash="a" * 64)
+ cfg_off = GenerationConfig(harvest_decisions=False)
+ page = await _first_run_page(
+ parsed, sample_graph, graph_metrics, sample_source_bytes, config=cfg_off
+ )
+
+ cfg_on = GenerationConfig(harvest_decisions=True)
+ provider2, gen2 = _make_gen(cfg_on, prior=_prior_from(page))
+ await _generate(gen2, parsed, sample_graph, graph_metrics, sample_source_bytes)
+
+ assert provider2.call_count == 1
+ assert gen2._reuse_count == 0
+
+
+async def test_template_change_busts_reuse(
+ sample_parsed_file, sample_graph, graph_metrics, sample_source_bytes
+):
+ """A repowise upgrade that changes file_page.j2 must regenerate unchanged
+ files — otherwise old-format pages persist until the file itself changes."""
+ parsed = dataclasses.replace(sample_parsed_file, content_hash="a" * 64)
+ env_v1 = jinja2.Environment(
+ loader=jinja2.DictLoader({"file_page.j2": "V1 {{ ctx.file_path }}"}),
+ undefined=jinja2.Undefined,
+ autoescape=False,
+ )
+ page = await _first_run_page(
+ parsed, sample_graph, graph_metrics, sample_source_bytes, jinja_env=env_v1
+ )
+
+ env_v2 = jinja2.Environment(
+ loader=jinja2.DictLoader({"file_page.j2": "V2 improved {{ ctx.file_path }}"}),
+ undefined=jinja2.Undefined,
+ autoescape=False,
+ )
+ provider2, gen2 = _make_gen(GenerationConfig(), prior=_prior_from(page), jinja_env=env_v2)
+ await _generate(gen2, parsed, sample_graph, graph_metrics, sample_source_bytes)
+
+ assert provider2.call_count == 1
+ assert gen2._reuse_count == 0
+
+ # Control: identical template env → reuse fires.
+ env_v1_again = jinja2.Environment(
+ loader=jinja2.DictLoader({"file_page.j2": "V1 {{ ctx.file_path }}"}),
+ undefined=jinja2.Undefined,
+ autoescape=False,
+ )
+ provider3, gen3 = _make_gen(GenerationConfig(), prior=_prior_from(page), jinja_env=env_v1_again)
+ await _generate(gen3, parsed, sample_graph, graph_metrics, sample_source_bytes)
+ assert provider3.call_count == 0
+ assert gen3._reuse_count == 1
+
+
+async def test_prior_without_content_hash_falls_back_to_prompt_hash(
+ sample_parsed_file, sample_graph, graph_metrics, sample_source_bytes
+):
+ """Back-compat: a prior page from an old pages.json (no content_hash)
+ still reuses via the prompt-hash path when the prompt is identical."""
+ parsed = dataclasses.replace(sample_parsed_file, content_hash="a" * 64)
+ page = await _first_run_page(parsed, sample_graph, graph_metrics, sample_source_bytes)
+
+ prior = {
+ page.page_id: PriorPage(
+ source_hash=page.source_hash,
+ model_name=page.model_name,
+ content=page.content,
+ )
+ }
+ provider2, gen2 = _make_gen(GenerationConfig(), prior=prior)
+ await _generate(gen2, parsed, sample_graph, graph_metrics, sample_source_bytes)
+
+ assert provider2.call_count == 0
+ assert gen2._reuse_count == 1
+
+
+async def test_prior_without_content_hash_and_drifted_prompt_regenerates(
+ sample_parsed_file, sample_graph, graph_metrics, sample_source_bytes
+):
+ """Back-compat priors get no content-hash shortcut: drifted prompt → regen."""
+ parsed = dataclasses.replace(sample_parsed_file, content_hash="a" * 64)
+ page = await _first_run_page(parsed, sample_graph, graph_metrics, sample_source_bytes)
+
+ prior = _prior_from(page, content_hash="")
+ provider2, gen2 = _make_gen(GenerationConfig(), prior=prior)
+ await _generate(gen2, parsed, sample_graph, graph_metrics, sample_source_bytes)
+
+ assert provider2.call_count == 1
+ assert gen2._reuse_count == 0
+
+
+# ---------------------------------------------------------------------------
+# Wiki styles
+# ---------------------------------------------------------------------------
+
+
+async def test_style_change_busts_content_hash_reuse(
+ sample_parsed_file, sample_graph, graph_metrics, sample_source_bytes
+):
+ parsed = dataclasses.replace(sample_parsed_file, content_hash="a" * 64)
+ page = await _first_run_page(
+ parsed,
+ sample_graph,
+ graph_metrics,
+ sample_source_bytes,
+ config=GenerationConfig(wiki_style="comprehensive"),
+ )
+
+ provider2, gen2 = _make_gen(GenerationConfig(wiki_style="caveman"), prior=_prior_from(page))
+ await _generate(gen2, parsed, sample_graph, graph_metrics, sample_source_bytes)
+
+ assert provider2.call_count == 1
+ assert gen2._reuse_count == 0
+
+
+async def test_style_change_busts_reuse_both_directions(
+ sample_parsed_file, sample_graph, graph_metrics, sample_source_bytes
+):
+ """Asymmetric case: prior generated under an ACTIVE style, current run
+ default — must regenerate too (the fingerprint differs both ways)."""
+ parsed = dataclasses.replace(sample_parsed_file, content_hash="a" * 64)
+ page = await _first_run_page(
+ parsed,
+ sample_graph,
+ graph_metrics,
+ sample_source_bytes,
+ config=GenerationConfig(wiki_style="caveman"),
+ )
+
+ provider2, gen2 = _make_gen(GenerationConfig(), prior=_prior_from(page))
+ await _generate(gen2, parsed, sample_graph, graph_metrics, sample_source_bytes)
+
+ assert provider2.call_count == 1
+ assert gen2._reuse_count == 0
+
+
+async def test_active_style_reuse_key_is_stable_across_runs(
+ sample_parsed_file, sample_graph, graph_metrics, sample_source_bytes
+):
+ """Same active style + unchanged file → same reuse key → reuse fires."""
+ parsed = dataclasses.replace(sample_parsed_file, content_hash="a" * 64)
+ config = GenerationConfig(wiki_style="caveman")
+ page = await _first_run_page(
+ parsed, sample_graph, graph_metrics, sample_source_bytes, config=config
+ )
+
+ provider2, gen2 = _make_gen(config, prior=_prior_from(page))
+ await _generate(gen2, parsed, sample_graph, graph_metrics, sample_source_bytes)
+
+ assert provider2.call_count == 0
+ assert gen2._reuse_count == 1
+
+
+# ---------------------------------------------------------------------------
+# Key shape / non-file pages
+# ---------------------------------------------------------------------------
+
+
+async def test_generated_page_carries_reuse_key_not_raw_file_hash(
+ sample_parsed_file, sample_graph, graph_metrics, sample_source_bytes
+):
+ """The persisted key must be the settings-folded composite, never the
+ bare file hash — a bare hash would survive template/language changes."""
+ parsed = dataclasses.replace(sample_parsed_file, content_hash="c" * 64)
+ page = await _first_run_page(parsed, sample_graph, graph_metrics, sample_source_bytes)
+ assert page.content_hash
+ assert page.content_hash != "c" * 64
+ assert len(page.content_hash) == 64 # sha256 hex
+
+
+async def test_page_without_content_hash_unaffected(
+ sample_parsed_file, sample_graph, graph_metrics, sample_source_bytes
+):
+ """Pages whose ParsedFile has no content hash keep prompt-hash semantics."""
+ no_hash = dataclasses.replace(sample_parsed_file, content_hash="")
+ page = await _first_run_page(no_hash, sample_graph, graph_metrics, sample_source_bytes)
+ assert page.content_hash == ""
+
+ # A prior with a content_hash must NOT match a current empty key.
+ prior = _prior_from(page, content_hash="a" * 64)
+ provider2, gen2 = _make_gen(GenerationConfig(), prior=prior)
+ await _generate(gen2, no_hash, sample_graph, graph_metrics, sample_source_bytes)
+ assert provider2.call_count == 1
+ assert gen2._reuse_count == 0
+
+
[email protected]("style", [None, "caveman"])
+def test_reuse_key_deterministic_across_generator_instances(sample_parsed_file, style):
+ """Two independently constructed generators with identical settings must
+ compute the same key — that's what makes cross-run reuse possible."""
+ parsed = dataclasses.replace(sample_parsed_file, content_hash="d" * 64)
+ cfg = GenerationConfig(wiki_style=style) if style else GenerationConfig()
+ _, gen_a = _make_gen(cfg)
+ _, gen_b = _make_gen(GenerationConfig(wiki_style=style) if style else GenerationConfig())
+ assert gen_a._reuse_content_hash(parsed) == gen_b._reuse_content_hash(parsed)
diff --git a/tests/unit/ingestion/parser/test_misc.py b/tests/unit/ingestion/parser/test_misc.py
index c45e42044..7b9b310db 100644
--- a/tests/unit/ingestion/parser/test_misc.py
+++ b/tests/unit/ingestion/parser/test_misc.py
@@ -22,6 +22,44 @@ class TestUnsupportedLanguage:
assert result.parse_errors == []
+class TestContentHash:
+ def test_parse_file_stamps_content_hash(self, parser: ASTParser) -> None:
+ """Every parse path stamps SHA256(raw bytes) — the cross-run page-reuse key."""
+ import hashlib
+
+ source = b"def add(a, b):\n return a + b\n"
+ fi = _make_file_info("pkg/math.py", "python")
+ result = parser.parse_file(fi, source)
+ assert result.content_hash == hashlib.sha256(source).hexdigest()
+
+ def test_no_grammar_fallback_stamps_content_hash(self, parser: ASTParser) -> None:
+ import hashlib
+
+ source = b"some content here"
+ fi = _make_file_info("file.xyz", "unknown")
+ fi.language = "unknown"
+ result = parser.parse_file(fi, source)
+ assert result.content_hash == hashlib.sha256(source).hexdigest()
+
+ def test_special_handler_stamps_content_hash(self, parser: ASTParser) -> None:
+ """Non-tree-sitter formats (Dockerfile & co) go through parse_special —
+ they must be stamped too."""
+ import hashlib
+
+ source = b"FROM python:3.12\nRUN pip install repowise\n"
+ fi = _make_file_info("Dockerfile", "dockerfile")
+ result = parser.parse_file(fi, source)
+ assert result.content_hash == hashlib.sha256(source).hexdigest()
+
+ def test_empty_file_stamps_content_hash(self, parser: ASTParser) -> None:
+ """sha256(b\"\") is a real, stable hash — empty files reuse like any other."""
+ import hashlib
+
+ fi = _make_file_info("pkg/__init__.py", "python")
+ result = parser.parse_file(fi, b"")
+ assert result.content_hash == hashlib.sha256(b"").hexdigest()
+
+
class TestLanguageConfigs:
def test_all_supported_languages_have_config(self) -> None:
expected = {
diff --git a/tests/unit/ingestion/test_parse_cache.py b/tests/unit/ingestion/test_parse_cache.py
index 9a298afd6..9b513ce99 100644
--- a/tests/unit/ingestion/test_parse_cache.py
+++ b/tests/unit/ingestion/test_parse_cache.py
@@ -232,3 +232,24 @@ def test_deleted_files_age_out_of_cache(repo):
cached_paths = {path for path, _hash in payload["files"]}
assert "other.py" not in cached_paths
assert "main.py" in cached_paths
+
+
+def test_cache_hit_stamps_content_hash(repo):
+ """A hit must carry the raw-bytes hash even for entries pickled before
+ ParsedFile had the field — the cache key already proves byte identity,
+ and the cross-run page-reuse key is derived from this attribute."""
+ from repowise.core.ingestion.parser import ASTParser
+
+ fi = _make_file_info(repo / "main.py", "main.py")
+ source = (repo / "main.py").read_bytes()
+ parsed = ASTParser().parse_file(fi, source)
+ parsed.content_hash = "" # simulate an old pickle without the field
+
+ cache = ParseCache(repo / ".repowise")
+ cache.load()
+ content_hash = compute_content_hash(source)
+ cache.put(parsed, content_hash)
+
+ hit = cache.get(fi, content_hash)
+ assert hit is not None
+ assert hit.content_hash == content_hash