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): one instruction, one 'Questions this page answers' heading (#1073)
Raghav Chamadiya08a94151bc5c
diff --git a/packages/core/src/repowise/core/generation/page_generator/core.py b/packages/core/src/repowise/core/generation/page_generator/core.pyindex 6470437e5..362cea72b 100644--- a/packages/core/src/repowise/core/generation/page_generator/core.py+++ b/packages/core/src/repowise/core/generation/page_generator/core.py@@ -33,7 +33,7 @@ from ..models import (compute_source_hash,)from ..styles import ONBOARDING_PAGE_TYPE, resolve_style-from .helpers import _extract_summary, _now_iso+from .helpers import _extract_summary, _now_iso, collapse_empty_duplicate_headingsfrom .pertype import PerTypeGenerationMixinfrom .prompts import SUPPORTED_LANGUAGES, SYSTEM_PROMPTSfrom .structural import (@@ -412,12 +412,15 @@ class PageGenerator(PerTypeGenerationMixin, StructuralRenderMixin):) -> GeneratedPage:"""Wrap a GeneratedResponse in a GeneratedPage."""now = _now_iso()+ # One pass over every model-written page: a heading the model emitted+ # twice with an empty section between the copies is one heading.+ content = collapse_empty_duplicate_headings(response.content)page = GeneratedPage(page_id=compute_page_id(page_type, target_path),page_type=page_type,title=title,- content=response.content,- summary=_extract_summary(response.content),+ content=content,+ summary=_extract_summary(content),source_hash=source_hash,model_name=self._provider.model_name,provider_name=self._provider.provider_name,diff --git a/packages/core/src/repowise/core/generation/page_generator/helpers.py b/packages/core/src/repowise/core/generation/page_generator/helpers.pyindex 83da30f63..915a8c7f5 100644--- a/packages/core/src/repowise/core/generation/page_generator/helpers.py+++ b/packages/core/src/repowise/core/generation/page_generator/helpers.py@@ -8,6 +8,7 @@ docs and call sites reference them.from __future__ import annotations+import refrom collections import defaultdictfrom datetime import UTC, datetimefrom pathlib import Path@@ -91,6 +92,31 @@ def overview_summary(content: str) -> str:return content[:400]+_EMPTY_DUPLICATE_HEADING = re.compile(+ r"^(?P<hashes>\#{2,6})[ \t]*(?P<text>\S.*?)[ \t]*\r?\n" # a heading …+ r"(?:[ \t]*\r?\n)*" # … whose section is empty …+ r"(?=(?P=hashes)[ \t]*(?P=text)[ \t]*(?:\r?\n|$))", # … and repeats verbatim+ re.MULTILINE,+)+++def collapse_empty_duplicate_headings(content: str) -> str:+ """Drop a heading that is immediately repeated with nothing in between.++ Models emit this when a required section is asked for emphatically: the+ heading lands once bare and once with the body under it, which renders as an+ empty section followed by the real one. A prompt change makes it rarer but+ cannot make it impossible, so the heading is deduplicated here as well,+ where the outcome does not depend on the model. Only the empty copy goes;+ two headings with content between them are two real sections.+ """+ prior = None+ while prior != content:+ prior = content+ content = _EMPTY_DUPLICATE_HEADING.sub("", content)+ return content++def _is_infra_file(parsed: ParsedFile) -> bool:"""Return True if the file is an infrastructure file."""lang = parsed.file_info.languagediff --git a/packages/core/src/repowise/core/generation/page_generator/prompts.py b/packages/core/src/repowise/core/generation/page_generator/prompts.pyindex 010e3e9c1..6cf114c09 100644--- a/packages/core/src/repowise/core/generation/page_generator/prompts.py+++ b/packages/core/src/repowise/core/generation/page_generator/prompts.py@@ -47,12 +47,12 @@ SYSTEM_PROMPTS: dict[str, str] = {"time. A page that walks through files one by one has failed even if every ""sentence is true. Synthesise. ""\n"- "REQUIRED SECTION: end the page with a section '## Questions this page "- "answers' listing 3 to 6 questions a developer or agent would ask that this "- "page answers, phrased the way they would actually be asked (for example "- "'How is the dependency graph built?' or 'Where do I add a new X?'). This "- "section is mandatory. "- "\n"+ # The mandatory '## Questions this page answers' section is asked for once,+ # in module_page.j2, where the rest of the module-page contract lives.+ # Stating it here as well made the model stutter the heading: it emitted the+ # 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."),diff --git a/tests/unit/generation/test_duplicate_heading_collapse.py b/tests/unit/generation/test_duplicate_heading_collapse.pynew file mode 100644index 000000000..79757e35a--- /dev/null+++ b/tests/unit/generation/test_duplicate_heading_collapse.py@@ -0,0 +1,124 @@+"""The mandatory module-page section is asked for once, and emitted once.++Background: the '## Questions this page answers' requirement used to be stated+in both the module_page system prompt and module_page.j2. Measured across local+indexes, 86 of 92 module pages written under the doubled instruction emitted the+heading twice — once bare, once with the questions under it. Pages written+before the instruction was doubled show none of it.++Two guards, because a prompt change is probabilistic and a code path is not:+the instruction lives in one place, and an empty duplicate heading is collapsed+on the way into the page.+"""++from __future__ import annotations++from pathlib import Path++import repowise.core.generation as _generation+from repowise.core.generation.context_assembler import ContextAssembler+from repowise.core.generation.page_generator import SYSTEM_PROMPTS, PageGenerator+from repowise.core.generation.page_generator.helpers import (+ collapse_empty_duplicate_headings,+)+from repowise.core.providers.llm.base import GeneratedResponse+from repowise.core.providers.llm.mock import MockProvider++_SECTION = "Questions this page answers"+_TEMPLATE_DIR = Path(_generation.__file__).parent / "templates"+++# ---------------------------------------------------------------------------+# One instruction, one place+# ---------------------------------------------------------------------------+++def test_module_page_system_prompt_does_not_repeat_the_required_section():+ """The contract lives in module_page.j2 with the rest of the requirements."""+ assert _SECTION not in SYSTEM_PROMPTS["module_page"]+++def test_module_page_template_still_asks_for_the_required_section():+ """Deleting the duplicate must not delete the requirement."""+ template = (_TEMPLATE_DIR / "module_page.j2").read_text(encoding="utf-8")+ assert template.count(_SECTION) == 1+++# ---------------------------------------------------------------------------+# collapse_empty_duplicate_headings+# ---------------------------------------------------------------------------+++def test_collapses_the_observed_failure():+ """The exact shape seen in production: bare heading, then the real one."""+ content = (+ "Some prose about the subsystem.\n\n"+ f"## {_SECTION}\n\n"+ f"## {_SECTION}\n"+ "1. What does this do?\n"+ "2. Where do I add a new one?\n"+ )+ out = collapse_empty_duplicate_headings(content)+ assert out.count(f"## {_SECTION}") == 1+ assert "1. What does this do?" in out+ assert out.startswith("Some prose about the subsystem.")+++def test_collapses_three_copies():+ content = f"## {_SECTION}\n\n## {_SECTION}\n\n## {_SECTION}\n1. Why?\n"+ out = collapse_empty_duplicate_headings(content)+ assert out.count(f"## {_SECTION}") == 1+ assert "1. Why?" in out+++def test_collapses_crlf_line_endings():+ content = f"## {_SECTION}\r\n\r\n## {_SECTION}\r\n1. Why?\r\n"+ assert collapse_empty_duplicate_headings(content).count(f"## {_SECTION}") == 1+++def test_keeps_two_headings_that_both_have_content():+ """Two real sections with the same name are the model's call, not a stutter."""+ content = "## Notes\nFirst point.\n\n## Notes\nSecond point.\n"+ out = collapse_empty_duplicate_headings(content)+ assert out.count("## Notes") == 2+ assert "First point." in out+++def test_keeps_an_empty_section_followed_by_a_different_heading():+ content = "## Empty\n\n## Different\nBody.\n"+ assert collapse_empty_duplicate_headings(content) == content+++def test_leaves_a_clean_page_untouched():+ content = f"## Overview\nProse.\n\n## {_SECTION}\n1. Why?\n"+ assert collapse_empty_duplicate_headings(content) == content+++def test_does_not_touch_repeated_headings_at_different_levels():+ """``## X`` then ``### X`` is a section and its subsection, not a stutter."""+ content = "## Design\n\n### Design\nBody.\n"+ assert collapse_empty_duplicate_headings(content) == content+++# ---------------------------------------------------------------------------+# The guard runs on every model-written page+# ---------------------------------------------------------------------------+++def test_built_page_collapses_the_duplicate(sample_config):+ """Whatever the model returns, the stored page has one heading."""+ duplicated = f"Prose.\n\n## {_SECTION}\n\n## {_SECTION}\n1. Why?\n"+ provider = MockProvider()+ gen = PageGenerator(provider, ContextAssembler(sample_config), sample_config)++ page = gen._build_generated_page(+ "module_page",+ "packages/core",+ "Core",+ GeneratedResponse(duplicated, 10, 5),+ "source-hash",+ 1,+ )++ assert page.content.count(f"## {_SECTION}") == 1+ assert _SECTION not in page.summary or page.summary.count(_SECTION) == 1