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): module pages stop opening with the same sentence (#1212)

Swati Ahuja496dc88fcfed
diff --git a/packages/core/src/repowise/core/generation/report.py b/packages/core/src/repowise/core/generation/report.py
index f13c8a33a..4c5cee792 100644
--- a/packages/core/src/repowise/core/generation/report.py
+++ b/packages/core/src/repowise/core/generation/report.py
@@ -5,6 +5,7 @@ Provides token accounting, page breakdown by type, and cost estimation.
from __future__ import annotations
+import re
from collections import Counter
from dataclasses import dataclass, field
@@ -29,6 +30,97 @@ QUESTIONS_HEADING = "## Questions this page answers"
# ones that carry a deterministic questions block.
_QUESTION_PAGE_TYPES = ("file_page", "symbol_spotlight")
+# How many leading words of a module page's opening count as its frame. Five is
+# where the observed repetition sits: "the presentation layer is the" opened ten
+# of eighty-nine pages in one run, and the words after it were the only ones
+# doing any work.
+_OPENING_FRAME_WORDS = 5
+
+# Share of module pages that may open with a frame another page also uses
+# before the run is worth flagging.
+OPENING_FRAME_REPEAT_BUDGET = 0.20
+
+_WORD = re.compile(r"[a-z0-9]+")
+
+
+def _opening_frame(content: str) -> str:
+ """The first few words of a page's opening sentence, normalised.
+
+ The opening is the page's summary — it is what ``_extract_summary`` stores,
+ what listings show, and what a module's description becomes wherever the
+ wiki is summarised for a reader. So a frame shared across pages is not a
+ style complaint: it is the same sentence being shown as the description of
+ several different subsystems.
+
+ Headings, tables and bullets are skipped: the opening is the first thing
+ written as prose.
+ """
+ for line in content.split("\n"):
+ stripped = line.strip()
+ if not stripped or stripped.startswith(("#", "|", "-", "*", ">", "`", "_")):
+ continue
+ words = _WORD.findall(stripped.lower())
+ return " ".join(words[:_OPENING_FRAME_WORDS])
+ return ""
+
+
+@dataclass
+class OpeningFrameReport:
+ """How many module pages this run opened with a sentence frame it reused.
+
+ Warn-only and reported with its denominator. Nothing raises when the model
+ settles into a template — the pages are individually well-formed and every
+ other check passes — so without this number the only symptom is a wiki
+ whose module descriptions all read the same.
+ """
+
+ eligible_pages: int = 0
+ repeated_pages: int = 0
+ #: The frame the most pages shared, and how many shared it. Named rather
+ #: than counted alone: a ratio says a problem exists, the frame says which
+ #: sentence to ban next.
+ top_frame: str = ""
+ top_frame_count: int = 0
+
+ @property
+ def measured(self) -> bool:
+ """Whether this run wrote enough module pages to compare at all.
+
+ One page cannot repeat itself, so a zero on a single-page run is not a
+ clean result — it is no result, and reads identically without this.
+ """
+ return self.eligible_pages > 1
+
+ @property
+ def repeat_ratio(self) -> float:
+ return self.repeated_pages / self.eligible_pages if self.eligible_pages else 0.0
+
+ @property
+ def over_budget(self) -> bool:
+ return self.measured and self.repeat_ratio > OPENING_FRAME_REPEAT_BUDGET
+
+ def summary_line(self) -> str:
+ if not self.measured:
+ return f"not measured ({self.eligible_pages} module page(s))"
+ line = f"{self.repeated_pages} of {self.eligible_pages} pages ({self.repeat_ratio:.0%})"
+ if self.top_frame_count > 1:
+ line = f'{line} — "{self.top_frame}" ×{self.top_frame_count}'
+ return line
+
+
+def measure_opening_frames(pages: list[GeneratedPage]) -> OpeningFrameReport:
+ """Count the module pages whose opening frame another module page also uses."""
+ frames = [_opening_frame(p.content or "") for p in pages if p.page_type == "module_page"]
+ present = [f for f in frames if f]
+ counts = Counter(present)
+ top_frame, top_count = counts.most_common(1)[0] if counts else ("", 0)
+ return OpeningFrameReport(
+ eligible_pages=len(frames),
+ repeated_pages=sum(1 for f in present if counts[f] > 1),
+ top_frame=top_frame if top_count > 1 else "",
+ top_frame_count=top_count,
+ )
+
def _count_question_blocks(pages: list[GeneratedPage]) -> dict[str, int]:
"""How many template pages carry question-shaped text, out of how many.
@@ -88,6 +180,11 @@ class GenerationReport:
# denominator a silent template regression is indistinguishable from a run
# that generated no file pages, and neither one raises.
question_blocks: dict[str, int] = field(default_factory=dict)
+ # Whether this run's module pages opened with sentence frames they reused.
+ # Their opening is their summary, so a shared frame is the same sentence
+ # standing as the description of several different subsystems. Read
+ # ``measured`` before reading the counts.
+ opening_frames: OpeningFrameReport = field(default_factory=OpeningFrameReport)
@classmethod
def from_pages(
@@ -123,6 +220,7 @@ class GenerationReport:
artifact_checks=artifact_check_counts(),
pages_denied_a_vector=pages_denied_a_vector(),
question_blocks=_count_question_blocks(pages),
+ opening_frames=measure_opening_frames(pages),
overview_prose_words=next(
(
prose_word_count(p.content or "")
@@ -269,6 +367,12 @@ def render_generation_checks(report: GenerationReport, console: object) -> None:
questions_text = f"[yellow]{questions_text}[/yellow]"
table.add_row("Question-shaped text", questions_text)
+ frames = report.opening_frames
+ frames_text = frames.summary_line()
+ if frames.over_budget:
+ frames_text = f"[yellow]{frames_text}[/yellow]"
+ table.add_row("Module page openings", frames_text)
+
console.print(table) # type: ignore[union-attr]
for pair in overlap.flagged:
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 1175a3586..2d19fd59d 100644
--- a/packages/core/src/repowise/core/generation/templates/module_page.j2
+++ b/packages/core/src/repowise/core/generation/templates/module_page.j2
@@ -125,7 +125,9 @@ Most active file: `{{ module_git_summary.most_active_file }}` ({{ module_git_sum
Write the page now from the material above. Requirements:
-- Open with the role-leading opener described, situating this page against its siblings using the scope line. Do not begin with "This module contains N files".
+- Open with one sentence that could only have been written about THIS subsystem, situating it against its siblings using the scope line. The opening sentence is stored as this page's summary and is shown as the module's description wherever the wiki is listed, so it has to carry information on its own.
+ - Do not open with a frame. Every one of these is banned as an opening: "The X layer is the Y of Z", "The X layer serves as the ...", "The X layer acts as the ...", "X is the entry stage of ...", "it consumes ... and produces ...", and "This module contains N files".
+ - Two module pages that open with the same first five words is the failure this rule exists to prevent. Name what this subsystem is responsible for, in words the material above forced on you.
- Choose H2/H3 headings that name this subsystem's real concerns. There is no fixed heading list — do not emit generic "Overview / Public API / Architecture Notes" headings unless they are genuinely the right names here.
- Synthesise across the whole file set. Draw on the material as a body of evidence; a file-by-file walkthrough is a failure even when accurate. Draw on many files, not one.
- Put any enumerable list (key files, dependencies, decisions) in a markdown table where it reads better than prose.
diff --git a/tests/unit/generation/test_module_page_openings.py b/tests/unit/generation/test_module_page_openings.py
new file mode 100644
index 000000000..40fa0402e
--- /dev/null
+++ b/tests/unit/generation/test_module_page_openings.py
@@ -0,0 +1,191 @@
+"""The run reports how often its module pages opened the same way.
+
+A module page's opening sentence is its summary: ``_extract_summary`` stores it,
+listings show it, and it is what stands as the module's description wherever the
+wiki is summarised for a reader. When the model settles into one sentence frame,
+the result is the same sentence presented as the description of a dozen
+different subsystems — and nothing raises, because each page is individually
+well-formed and every other check passes.
+
+One run produced this, unflagged: "the presentation layer is the" opened ten of
+eighty-nine module pages, "the transport adapter layer serves" another three,
+and nineteen pages in total shared their first five words with another page.
+
+The prompt now bans the frames, and this counter is what says whether the ban
+held. Warn-only and reported with its denominator, because a run with one
+module page cannot repeat itself and its zero means nothing.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import jinja2
+import pytest
+
+from repowise.core.generation.context.contexts import ModulePageContext
+from repowise.core.generation.models import GeneratedPage
+from repowise.core.generation.report import (
+ GenerationReport,
+ measure_opening_frames,
+)
+
+
+def _page(page_id: str, content: str, page_type: str = "module_page") -> GeneratedPage:
+ return GeneratedPage(
+ page_id=page_id,
+ page_type=page_type,
+ title=page_id,
+ content=content,
+ source_hash="",
+ model_name="mock",
+ provider_name="mock",
+ input_tokens=0,
+ output_tokens=0,
+ cached_tokens=0,
+ generation_level=3,
+ target_path="",
+ created_at="2026-08-01T00:00:00Z",
+ updated_at="2026-08-01T00:00:00Z",
+ )
+
+
+_FRAMED = [
+ "# Ingestion\n\nThe presentation layer is the surface every request crosses.\n",
+ "# Resolution\n\nThe presentation layer is the boundary that resolves references.\n",
+ "# Storage\n\nThe presentation layer is the place rows are written.\n",
+]
+
+_VARIED = [
+ "# Ingestion\n\nParsing turns a checkout into symbols the graph can hold.\n",
+ "# Resolution\n\nCross-file references become edges here, or they become nothing.\n",
+ "# Storage\n\nRows land in SQLite and vectors in LanceDB, on two schedules.\n",
+]
+
+
+def test_a_set_of_same_opening_pages_is_flagged():
+ """The failure the check exists for: one sentence, three subsystems."""
+ report = measure_opening_frames([_page(f"m{i}", c) for i, c in enumerate(_FRAMED)])
+
+ assert report.eligible_pages == 3
+ assert report.repeated_pages == 3
+ assert report.top_frame == "the presentation layer is the"
+ assert report.top_frame_count == 3
+ assert report.over_budget is True
+
+
+def test_a_varied_set_passes():
+ report = measure_opening_frames([_page(f"m{i}", c) for i, c in enumerate(_VARIED)])
+
+ assert report.repeated_pages == 0
+ assert report.repeat_ratio == 0.0
+ assert report.top_frame == ""
+ assert report.over_budget is False
+
+
+def test_only_module_pages_are_compared():
+ """File pages and spotlights are template-rendered and open identically on
+ purpose; counting them would swamp the number this check is about."""
+ pages = [
+ _page("f1", "# A\n\nThis page documents `a.py`.\n", page_type="file_page"),
+ _page("f2", "# B\n\nThis page documents `b.py`.\n", page_type="file_page"),
+ *[_page(f"m{i}", c) for i, c in enumerate(_VARIED)],
+ ]
+
+ report = measure_opening_frames(pages)
+
+ assert report.eligible_pages == 3
+ assert report.repeated_pages == 0
+
+
+def test_a_single_module_page_reports_not_measured():
+ """A page cannot repeat itself, so its zero is no result rather than a
+ clean one — and the two read identically without ``measured``."""
+ report = measure_opening_frames([_page("m0", _FRAMED[0])])
+
+ assert report.measured is False
+ assert report.over_budget is False
+ assert "not measured" in report.summary_line()
+
+
+def test_headings_and_tables_are_not_the_opening():
+ """The opening is the first prose. A page whose first lines are a heading
+ and a table must be compared on the sentence, not on the table row."""
+ content = (
+ "# Ingestion\n\n"
+ "| Concept | Symbol | File |\n| --- | --- | --- |\n| A | `A` | `a.py` |\n\n"
+ "Parsing turns a checkout into symbols the graph can hold.\n"
+ )
+
+ report = measure_opening_frames([_page("m0", content), _page("m1", content)])
+
+ assert report.top_frame == "parsing turns a checkout into"
+
+
+def test_the_report_carries_the_measurement_and_the_check_prints():
+ from io import StringIO
+
+ from rich.console import Console
+
+ from repowise.core.generation.report import render_generation_checks
+
+ report = GenerationReport.from_pages([_page(f"m{i}", c) for i, c in enumerate(_FRAMED)])
+ assert report.opening_frames.repeated_pages == 3
+
+ buffer = StringIO()
+ render_generation_checks(report, Console(file=buffer, width=120))
+ output = buffer.getvalue()
+
+ assert "Module page openings" in output
+ # Every check prints at zero too: a hidden row makes "did not run" and
+ # "passed" the same thing on screen.
+ empty = StringIO()
+ render_generation_checks(GenerationReport.from_pages([]), Console(file=empty, width=120))
+ assert "Module page openings" in empty.getvalue()
+
+
+def module_prompt() -> str:
+ templates = (
+ Path(__file__).parents[3]
+ / "packages"
+ / "core"
+ / "src"
+ / "repowise"
+ / "core"
+ / "generation"
+ / "templates"
+ )
+ env = jinja2.Environment(
+ loader=jinja2.FileSystemLoader(str(templates)),
+ undefined=jinja2.StrictUndefined,
+ autoescape=False,
+ )
+ ctx = ModulePageContext(
+ title="Resolution Layer",
+ language="python",
+ total_symbols=4,
+ public_symbols=3,
+ entry_points=[],
+ dependencies=[],
+ dependents=[],
+ pagerank_mean=0.001,
+ files=["core/resolvers/context.py"],
+ scope="Covers reference resolution; leaves parsing to its sibling.",
+ )
+ return env.get_template("module_page.j2").render(ctx=ctx, module_git_summary=None)
+
+
+def test_the_prompt_bans_the_frames_the_corpus_settled_into(module_prompt):
+ """Asserted on the rendered prompt, which is this template's output."""
+ assert "serves as the" in module_prompt
+ assert "entry stage" in module_prompt
+ assert "it consumes" in module_prompt
+ assert "same first five words" in module_prompt
+
+
+def test_the_prompt_no_longer_points_at_an_opener_it_never_describes(module_prompt):
+ """The instruction used to read "the role-leading opener described" — and
+ nothing in the prompt described one. An opener the model has to invent is
+ how a run ends up with eighty-nine pages sharing three sentences."""
+ assert "role-leading opener described" not in module_prompt