Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(generation): stop the module_page prompt tripping its own validator, and bound the spotlight importer list (#1606)
Raghav Chamadiya28c861f72577
diff --git a/packages/core/src/repowise/core/generation/page_generator/core.py b/packages/core/src/repowise/core/generation/page_generator/core.pyindex a66607c4c..0f273d73f 100644--- a/packages/core/src/repowise/core/generation/page_generator/core.py+++ b/packages/core/src/repowise/core/generation/page_generator/core.py@@ -15,7 +15,7 @@ from __future__ import annotationsimport hashlibfrom collections.abc import Callable, Sequence-from dataclasses import dataclass+from dataclasses import dataclass, replacefrom pathlib import Pathfrom typing import TYPE_CHECKING, Any@@ -46,14 +46,18 @@ from ..structural_labels import resolve_structural_labels, structural_page_titlefrom ..styles import ONBOARDING_PAGE_TYPE, resolve_stylefrom .helpers import _extract_summary, _now_iso, collapse_empty_duplicate_headingsfrom .pertype import PerTypeGenerationMixin-from .prompts import SUPPORTED_LANGUAGES, SYSTEM_PROMPTS+from .prompts import CORRECTIVE_RETRY_DIRECTIVE, SUPPORTED_LANGUAGES, SYSTEM_PROMPTSfrom .structural import (StructuralRenderMixin,as_markdown,oneline,signature,)-from .validation import reset_artifact_check_counts, validate_generated_response+from .validation import (+ InvalidGeneratedContentError,+ reset_artifact_check_counts,+ validate_generated_response,+)if TYPE_CHECKING:from pathlib import Path as _Path # noqa: F401@@ -398,13 +402,60 @@ class PageGenerator(PerTypeGenerationMixin, StructuralRenderMixin):reasoning=self._config.reasoning,cache_hints=cache_hints,)- validate_generated_response(response)+ try:+ validate_generated_response(response)+ except InvalidGeneratedContentError as first_failure:+ # One corrective re-ask. Without it a single banned phrase anywhere+ # in a finished page discards the whole thing with the tokens+ # already spent, and the only recovery is --resume regenerating it+ # from scratch. The re-ask names the rule that was broken, because+ # a blind retry at the same temperature tends to reproduce the+ # sentence that failed.+ if not first_failure.retryable:+ raise+ log.warning(+ "page_generation.retrying_after_validation_failure",+ page_type=page_type,+ target_path=target_path,+ reason=str(first_failure),+ )+ discarded = response+ response = await self._provider.generate(+ system_prompt,+ self._corrective_prompt(user_prompt, first_failure),+ max_tokens=self._config.max_tokens,+ temperature=self._config.temperature,+ request_id=request_id,+ reasoning=self._config.reasoning,+ cache_hints=cache_hints,+ )+ # A second failure raises, so the caller's stub-fallback path is+ # reached exactly as it was before the retry existed.+ validate_generated_response(response)+ # The discarded attempt was billed. Carrying its tokens forward is+ # what keeps the run report's totals equal to what the provider+ # actually charged for; the page itself is the retry's content.+ # ``self_repair`` fills the report row of the same name, which+ # distinguishes a page that needed a second attempt from one that+ # was lost — the artifact tallies alone cannot tell them apart.+ response = replace(+ response,+ input_tokens=response.input_tokens + discarded.input_tokens,+ output_tokens=response.output_tokens + discarded.output_tokens,+ cached_tokens=response.cached_tokens + discarded.cached_tokens,+ usage={**response.usage, "self_repair": True},+ )if self._config.cache_enabled:self._cache[key] = responsereturn response+ @staticmethod+ def _corrective_prompt(user_prompt: str, failure: InvalidGeneratedContentError) -> str:+ """The original request plus a note naming what the last attempt broke."""+ return f"{user_prompt}\n\n{CORRECTIVE_RETRY_DIRECTIVE.format(reason=failure.retry_hint)}"+def _build_system_prompt(self, page_type: str) -> str:base_system = SYSTEM_PROMPTS[page_type]# Wiki style: append the style's framing note. Constant per run (per page@@ -498,6 +549,11 @@ class PageGenerator(PerTypeGenerationMixin, StructuralRenderMixin):# exists byte-identically.if response.usage.get("reused_from_prior_run"):page.metadata["reused_from_prior_run"] = True+ # A first attempt was rejected and the re-ask produced this page. Feeds+ # the report's "Self-repaired pages" row, so a run says how often the+ # backstop was load-bearing instead of only how often it failed.+ if response.usage.get("self_repair"):+ page.metadata["self_repair"] = Truereturn pagedef _render(self, template_name: str, *, style_prefix: bool = True, **kwargs: Any) -> str:diff --git a/packages/core/src/repowise/core/generation/page_generator/prompts.py b/packages/core/src/repowise/core/generation/page_generator/prompts.pyindex f5bdab52b..2691d05ed 100644--- a/packages/core/src/repowise/core/generation/page_generator/prompts.py+++ b/packages/core/src/repowise/core/generation/page_generator/prompts.py@@ -28,7 +28,7 @@ SYSTEM_PROMPTS: dict[str, str] = {"\n""FORM: Open with one or two paragraphs that state the subsystem's job in ""the larger system and situate it against its neighbours (what it does and, "- "using the supplied scope line, what it deliberately leaves to other pages). "+ "using the scope line below, what it deliberately leaves to other pages). ""Lead the first sentence with the role, in architectural vocabulary (entry ""stage, orchestration layer, persistence boundary, transport adapter, and so ""on), naming the inputs it consumes and the outputs it produces. "@@ -53,8 +53,14 @@ SYSTEM_PROMPTS: dict[str, str] = {# heading bare, then again with the questions under it, on 86 of 92 pages# measured across local indexes (gpt-5.4-nano). Pages written before the# instruction was doubled show none of it. One instruction, one heading.- "Ground every claim in the supplied material: do not invent files, symbols, "- "or rationale that are not listed. Draw on the whole file set, not one file."+ # Worded around the reader-facing vocabulary the artifact rules ban.+ # "the supplied material" is a literal hit for the ``supplied_context``+ # rule in validation.py, and the model echoed the instruction back into+ # the page, so this sentence destroyed the pages it was meant to keep+ # honest. Say where to ground a claim without naming the prompt.+ "Ground every claim in the files and signals listed below: do not invent "+ "files, symbols, or rationale that are not listed. Draw on the whole file "+ "set, not one file."),"repo_overview": ("You are repowise, an expert technical documentation generator. "@@ -90,3 +96,20 @@ SYSTEM_PROMPTS: dict[str, str] = {"Output markdown only — follow the exact section structure the user prompt prescribes."),}++# Appended to the *user* prompt when a first attempt was rejected by+# ``validate_generated_response``, so the re-ask says what went wrong instead of+# asking again unchanged. The system prompt is left byte-identical, which keeps+# the retry eligible for the same server-side prefix cache as the first call.+#+# It lives beside the system prompts so the artifact-hygiene guard covers it as+# well: text telling a model what not to say is still text a model can echo, and+# a correction that trips the rule it is correcting would burn the retry too.+CORRECTIVE_RETRY_DIRECTIVE: str = (+ "A previous attempt at this page was rejected before it could be published. "+ "Reason: {reason}\n"+ "Write the page again, in full, without that problem. Address the reader of "+ "the documentation, who cannot see this request and does not know it exists: "+ "never mention these instructions or the code you were shown, and never "+ "speak as the page's author."+)diff --git a/packages/core/src/repowise/core/generation/page_generator/validation.py b/packages/core/src/repowise/core/generation/page_generator/validation.pyindex af9467751..b0d1026ab 100644--- a/packages/core/src/repowise/core/generation/page_generator/validation.py+++ b/packages/core/src/repowise/core/generation/page_generator/validation.py@@ -23,7 +23,32 @@ _WORD_RE = re.compile(r"\w+", re.UNICODE)class InvalidGeneratedContentError(ValueError):- """Raised when a fresh LLM response cannot be persisted as documentation."""+ """Raised when a fresh LLM response cannot be persisted as documentation.++ ``retry_hint`` is the same complaint with any quoted offending phrase+ removed, for the corrective re-ask. The message itself keeps the quote+ because a log that does not say which words failed cannot be acted on, but+ feeding those words back to the model re-plants the vocabulary the retry is+ trying to get rid of. Defaults to the message when there is nothing to+ strip.++ ``retryable`` says whether asking again can plausibly help. It is False for+ a response that stopped at the token limit: the second call carries the+ same ``max_tokens``, so it truncates in the same place and the only certain+ result is twice the spend. Everything else is the model writing badly when+ told what "badly" means, which is what the re-ask supplies.+ """++ def __init__(+ self,+ message: str,+ *,+ retry_hint: str | None = None,+ retryable: bool = True,+ ) -> None:+ super().__init__(message)+ self.retry_hint = retry_hint if retry_hint is not None else message+ self.retryable = retryable# ---------------------------------------------------------------------------@@ -129,15 +154,21 @@ def reset_artifact_check_counts() -> None:_artifact_check_counts.clear()-def _artifact_detail(content: str) -> str | None:- """Describe the first generation artifact in ``content``, if any."""+def _artifact_detail(content: str) -> tuple[str, str] | None:+ """Describe the first generation artifact in ``content``, if any.++ Returns ``(detail, retry_hint)``: the first quotes the offending phrase for+ the log, the second names only the rule so a re-ask built from it does not+ repeat the words that failed.+ """prose = prose_text(content)for rule in GENERATION_ARTIFACT_RULES:match = rule.pattern.search(prose)if match is not None:_artifact_check_counts["rejected"] += 1_artifact_check_counts[f"rejected:{rule.name}"] += 1- return f"{rule.name}: {rule.explanation} ({match.group(0).strip()!r})"+ detail = f"{rule.name}: {rule.explanation} ({match.group(0).strip()!r})"+ return detail, f"{rule.name}: {rule.explanation}"return None@@ -182,7 +213,8 @@ def validate_generated_response(response: GeneratedResponse) -> None:else "")raise InvalidGeneratedContentError(- f"generation reached a token limit before the documentation was complete{detail}"+ f"generation reached a token limit before the documentation was complete{detail}",+ retryable=False,)if not response.content.strip():raise InvalidGeneratedContentError("provider returned empty documentation")@@ -193,10 +225,12 @@ def validate_generated_response(response: GeneratedResponse) -> None:f"provider returned pathologically repetitive documentation: {repetition_detail}")- artifact_detail = _artifact_detail(response.content)- if artifact_detail is not None:+ artifact = _artifact_detail(response.content)+ if artifact is not None:+ detail, retry_hint = artifact+ preamble = "provider returned text addressed to the prompter, not the reader — "raise InvalidGeneratedContentError(- f"provider returned text addressed to the prompter, not the reader — {artifact_detail}"+ f"{preamble}{detail}", retry_hint=f"{preamble}{retry_hint}")diff --git a/packages/core/src/repowise/core/generation/templates/symbol_spotlight.j2 b/packages/core/src/repowise/core/generation/templates/symbol_spotlight.j2index e3d3d1053..cdf21c43a 100644--- a/packages/core/src/repowise/core/generation/templates/symbol_spotlight.j2+++ b/packages/core/src/repowise/core/generation/templates/symbol_spotlight.j2@@ -5,6 +5,12 @@the same way; a template that claimed otherwise would over-state what thegraph actually knows.+ The rendered list stops at 25, the same bound ``file_page.j2`` puts on its+ "Used by" section over the same data, while the summary line above it keeps+ the true total. Unbounded, a fixture imported across a whole test suite+ rendered 939 bullets and a 46k-char page, which is past the 30k the+ embedder accepts, so the tail was dropped from the vector.+Every section but the Overview is conditional: a heading with nothingunder it costs a reader a stop and repeats a stock sentence acrossthousands of pages, where it matches every query and distinguishes none.@@ -40,9 +46,13 @@## {{ labels.where_used }}{{ labels.importers_summary.format(count=ctx.callers | length, file_word=labels.file_plural if ctx.callers | length != 1 else labels.file_singular, import_verb=labels.import_verb_plural if ctx.callers | length != 1 else labels.import_verb_singular) }}-{% for c in ctx.callers %}+{% for c in ctx.callers[:25] %}- `{{ c }}`{%- endfor %}+{%- if ctx.callers | length > 25 %}++_{{ labels.and_more.format(count=ctx.callers | length - 25) }}_+{%- endif %}{%- endif %}{%- if ctx.source_body %}diff --git a/tests/unit/generation/test_page_generator.py b/tests/unit/generation/test_page_generator.pyindex cf08b18e2..27ac3ef89 100644--- a/tests/unit/generation/test_page_generator.py+++ b/tests/unit/generation/test_page_generator.py@@ -219,6 +219,142 @@ async def test_invalid_provider_output_raises_and_is_not_cached(sample_config):assert provider.call_count == 2+# ---------------------------------------------------------------------------+# The corrective retry+#+# A rejected page is a page already paid for, so one re-ask is cheaper than+# losing it. The bound matters as much as the retry: a page that fails twice+# must fall through to the caller's stub path rather than loop.+# ---------------------------------------------------------------------------++_BANNED_PHRASING = "# Queue status\n\nThe supplied material describes a queue reader."+_CLEAN_PAGE = "# Queue status\n\n`QueueStatus` reports the active queue."+++def _page(content: str) -> GeneratedResponse:+ return GeneratedResponse(content=content, input_tokens=10, output_tokens=20)+++async def test_artifact_violation_is_retried_once_and_recovers(sample_config):+ provider = MockProvider(responses=[_page(_BANNED_PHRASING), _page(_CLEAN_PAGE)])+ generator = PageGenerator(provider, ContextAssembler(sample_config), sample_config)++ response = await generator._call_provider(+ "module_page", "Document this module.", "request-id"+ )++ assert response.content == _CLEAN_PAGE+ assert provider.call_count == 2+++async def test_corrective_retry_names_the_broken_rule_and_keeps_the_request(sample_config):+ provider = MockProvider(responses=[_page(_BANNED_PHRASING), _page(_CLEAN_PAGE)])+ generator = PageGenerator(provider, ContextAssembler(sample_config), sample_config)++ await generator._call_provider("module_page", "Document this module.", "request-id")++ retry_prompt = provider.calls[1]["user_prompt"]+ assert "supplied_context" in retry_prompt+ # The whole page is being rewritten, so the original request has to survive.+ assert "Document this module." in retry_prompt+ # The offending words must not be handed back: quoting them re-plants the+ # vocabulary the retry exists to remove.+ assert "supplied material" not in retry_prompt+ # A byte-identical system prompt is what keeps the retry eligible for the+ # provider's prefix cache.+ assert provider.calls[1]["system_prompt"] == provider.calls[0]["system_prompt"]+++async def test_retry_carries_the_discarded_attempt_s_tokens(sample_config):+ """The rejected attempt was billed, so the run report has to count it.++ Only the retry's content survives, but dropping the first attempt's tokens+ would make the reported total smaller than what the provider charged for.+ """+ first = GeneratedResponse(+ content=_BANNED_PHRASING, input_tokens=100, output_tokens=200, cached_tokens=10+ )+ second = GeneratedResponse(+ content=_CLEAN_PAGE, input_tokens=7, output_tokens=11, cached_tokens=3+ )+ provider = MockProvider(responses=[first, second])+ generator = PageGenerator(provider, ContextAssembler(sample_config), sample_config)++ response = await generator._call_provider(+ "module_page", "Document this module.", "request-id"+ )++ assert response.content == _CLEAN_PAGE+ assert response.input_tokens == 107+ assert response.output_tokens == 211+ assert response.cached_tokens == 13+++async def test_a_repaired_page_is_marked_as_self_repaired(sample_config):+ """Fills the report's "Self-repaired pages" row.++ The artifact tallies count rejections, which a recovered page and a lost+ page both produce. This is what tells them apart.+ """+ provider = MockProvider(responses=[_page(_BANNED_PHRASING), _page(_CLEAN_PAGE)])+ generator = PageGenerator(provider, ContextAssembler(sample_config), sample_config)++ response = await generator._call_provider(+ "module_page", "Document this module.", "request-id"+ )+ page = generator._build_generated_page(+ "module_page", "pkg/mod.py", "Mod", response, "source-hash", 3+ )++ assert page.metadata.get("self_repair") is True+++async def test_a_first_time_page_is_not_marked_as_self_repaired(sample_config):+ provider = MockProvider(responses=[_page(_CLEAN_PAGE)])+ generator = PageGenerator(provider, ContextAssembler(sample_config), sample_config)++ response = await generator._call_provider(+ "module_page", "Document this module.", "request-id"+ )+ page = generator._build_generated_page(+ "module_page", "pkg/mod.py", "Mod", response, "source-hash", 3+ )++ assert "self_repair" not in page.metadata+++async def test_second_violation_gives_up_rather_than_looping(sample_config):+ # MockProvider repeats its last response, so every attempt violates.+ provider = MockProvider(responses=[_page(_BANNED_PHRASING)])+ generator = PageGenerator(provider, ContextAssembler(sample_config), sample_config)++ with pytest.raises(InvalidGeneratedContentError, match="supplied_context"):+ await generator._call_provider("module_page", "Document this module.", "request-id")++ assert provider.call_count == 2+++async def test_token_limit_is_not_retried(sample_config):+ """Re-asking with the same ``max_tokens`` truncates again and bills twice."""+ provider = MockProvider(+ responses=[+ GeneratedResponse(+ content="# Queue status\n\nIncomplete",+ input_tokens=10,+ output_tokens=20,+ stop_reason="max_tokens",+ provider_stop_reason="length",+ )+ ]+ )+ generator = PageGenerator(provider, ContextAssembler(sample_config), sample_config)++ with pytest.raises(InvalidGeneratedContentError, match="token limit"):+ await generator._call_provider("module_page", "Document this module.", "request-id")++ assert provider.call_count == 1++def test_generated_page_retains_completion_stop_metadata(sample_config):generator = PageGenerator(MockProvider(), ContextAssembler(sample_config), sample_config)page = generator._build_generated_page(diff --git a/tests/unit/generation/test_prompt_artifact_hygiene.py b/tests/unit/generation/test_prompt_artifact_hygiene.pynew file mode 100644index 000000000..67e2d5514--- /dev/null+++ b/tests/unit/generation/test_prompt_artifact_hygiene.py@@ -0,0 +1,100 @@+"""The prompts must not use the vocabulary the artifact rules reject.++A model echoes the phrasing it is instructed in. When a system prompt or a+template contains a phrase that :mod:`validation` bans, the model reproduces it+and the finished page is thrown away for saying what it was told to say —+tokens spent, page lost, and the only clue is a validator complaining about the+model rather than about the prompt.++This has now happened twice. ``prompts.py`` carried "the supplied material",+which is a literal hit for the ``supplied_context`` rule, and every+``module_page`` that echoed it was destroyed. The comment at the same site+records an earlier instance of the same shape. These tests make the class of+bug fail at collection time instead of after a paid run.+"""++from __future__ import annotations++from pathlib import Path++import pytest++from repowise.core.generation import page_generator+from repowise.core.generation.page_generator.prompts import (+ CORRECTIVE_RETRY_DIRECTIVE,+ SYSTEM_PROMPTS,+)+from repowise.core.generation.page_generator.validation import (+ GENERATION_ARTIFACT_RULES,+ ArtifactRule,+)++_GENERATION_DIR = Path(page_generator.__file__).resolve().parent.parent+_TEMPLATE_FILES = sorted(_GENERATION_DIR.rglob("*.j2"))+++def _offenders(text: str) -> list[tuple[ArtifactRule, str]]:+ """Every artifact rule ``text`` trips, with the phrase that tripped it."""+ hits = []+ for rule in GENERATION_ARTIFACT_RULES:+ match = rule.pattern.search(text)+ if match is not None:+ hits.append((rule, match.group(0).strip()))+ return hits++[email protected]("page_type", sorted(SYSTEM_PROMPTS))+def test_system_prompt_avoids_banned_vocabulary(page_type: str) -> None:+ hits = _offenders(SYSTEM_PROMPTS[page_type])+ assert not hits, (+ f"the {page_type} system prompt uses phrasing that "+ f"validate_generated_response rejects, so a model that echoes the "+ f"instruction loses the page: "+ + "; ".join(f"{rule.name} ({phrase!r}) — {rule.explanation}" for rule, phrase in hits)+ )+++def test_corrective_retry_directive_avoids_banned_vocabulary() -> None:+ """The correction must not trip the rule it exists to correct.++ This directive is only ever sent after a page was already rejected once. A+ banned phrase here would fail the retry as well and turn the backstop into+ a second guaranteed loss.++ Filled with a real ``retry_hint`` rather than a placeholder, because the+ reason is interpolated into the prompt and is therefore part of what the+ model reads. ``retry_hint`` is the phrase-free form for exactly this+ reason; the quoted form goes to the log instead.+ """+ for rule in GENERATION_ARTIFACT_RULES:+ reason = (+ "provider returned text addressed to the prompter, not the reader — "+ f"{rule.name}: {rule.explanation}"+ )+ hits = _offenders(CORRECTIVE_RETRY_DIRECTIVE.format(reason=reason))+ assert not hits, (+ f"the corrective retry directive, filled with the {rule.name} reason, "+ f"uses phrasing that validate_generated_response rejects: "+ + "; ".join(f"{hit.name} ({phrase!r})" for hit, phrase in hits)+ )+++def test_templates_are_discovered() -> None:+ """The template sweep needs a non-zero denominator to mean anything.++ A glob that silently resolves to nothing passes every assertion below it,+ which reads identically to a clean sweep.+ """+ assert _TEMPLATE_FILES, f"no .j2 templates found under {_GENERATION_DIR}"+++ "template_path", _TEMPLATE_FILES, ids=[p.name for p in _TEMPLATE_FILES]+)+def test_template_avoids_banned_vocabulary(template_path: Path) -> None:+ hits = _offenders(template_path.read_text(encoding="utf-8"))+ assert not hits, (+ f"{template_path.relative_to(_GENERATION_DIR)} uses phrasing that "+ f"validate_generated_response rejects: "+ + "; ".join(f"{rule.name} ({phrase!r}) — {rule.explanation}" for rule, phrase in hits)+ )diff --git a/tests/unit/generation/test_templates.py b/tests/unit/generation/test_templates.pyindex a5dd6aa70..7fa759e76 100644--- a/tests/unit/generation/test_templates.py+++ b/tests/unit/generation/test_templates.py@@ -2,6 +2,7 @@from __future__ import annotations+import refrom pathlib import Pathimport jinja2@@ -432,6 +433,55 @@ def test_spotlight_keeps_the_importers_section_when_it_has_importers(assert "1 file imports the module" in result[email protected](scope="module")+def widely_imported_spotlight_ctx() -> SymbolSpotlightContext:+ """A fixture-shaped symbol: imported across a whole test suite.++ 939 importers is what ``tests/conftest.py`` actually measured on this+ repository, which is the case that produced a 46k-char page.+ """+ return SymbolSpotlightContext(+ symbol_name="fixtures_dir",+ qualified_name="tests.conftest.fixtures_dir",+ kind="function",+ signature="def fixtures_dir() -> Path:",+ docstring="Path to the fixtures directory.",+ file_path="tests/conftest.py",+ decorators=[],+ is_async=False,+ complexity_estimate=1,+ callers=[f"tests/unit/test_{index}.py" for index in range(939)],+ )+++def test_spotlight_caps_the_importer_list(jinja_env, widely_imported_spotlight_ctx):+ """An unbounded list pushed the page past what the embedder accepts.++ ``EMBED_TEXT_MAX_CHARS`` is 30,000 and the tail past it is dropped from the+ vector, so the page stayed searchable only by its first few hundred+ importers. The bound is the one ``file_page.j2`` already applies to the+ same data.+ """+ result = render(jinja_env, "symbol_spotlight.j2", widely_imported_spotlight_ctx)++ listed = re.findall(r"^- `tests/unit/test_\d+\.py`$", result, re.M)+ assert len(listed) == 25+ assert "and 914 more." in result+ assert len(result) < 30_000+++def test_spotlight_reports_the_true_importer_count_above_the_capped_list(+ jinja_env, widely_imported_spotlight_ctx+):+ """Truncating the list must not truncate the fact.++ The summary sentence is the only place the real number survives, so it+ counts every importer even though 25 are shown.+ """+ result = render(jinja_env, "symbol_spotlight.j2", widely_imported_spotlight_ctx)+ assert "939 files import the module" in result++def test_spotlight_still_describes_a_symbol_that_has_no_docstring(jinja_env, unimported_spotlight_ctx):