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
feat(generation): the overview counts its packages instead of describing them (#1246)
Raghav Chamadiyae1217b8765be
diff --git a/packages/core/src/repowise/core/generation/context/assembler.py b/packages/core/src/repowise/core/generation/context/assembler.pyindex a5ae20e83..33c54f5f3 100644--- a/packages/core/src/repowise/core/generation/context/assembler.py+++ b/packages/core/src/repowise/core/generation/context/assembler.py@@ -3,6 +3,7 @@from __future__ import annotationsimport re+from collections import Counterfrom pathlib import PurePosixPathfrom typing import Any@@ -68,6 +69,72 @@ _MAX_CONCEPT_ROWS = 40# usually the word a reader would actually say._IDENTIFIER_SPLIT = re.compile(r"_+|(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")+# A language has to reach this share of a package's files to be named as one of+# its languages. Below it the mention is noise: nearly every TypeScript package+# holds a JSON fixture and a shell script, and listing them makes the column+# longer without making it more true.+_PACKAGE_LANGUAGE_FLOOR = 0.10+++def _package_stats(repo_structure: RepoStructure, parsed_files: list[ParsedFile]) -> list[dict]:+ """Count files and observe languages per package, largest package first.++ ``PackageInfo.language`` is a single tag chosen when the package was+ detected, so it calls a package with a hundred TypeScript files and one+ build script "typescript" and says nothing about the mix. These counts come+ from the files the run actually parsed.++ A package with no parsed files still gets a row: the walker skipping a+ directory is a fact about the run, and dropping the row would shorten the+ table with no way to tell that from the package not existing.+ """+ packages = getattr(repo_structure, "packages", None) or []+ if not packages:+ return []++ # Longest path first so a nested package claims its files before its parent+ # does — ``packages/ui/src/foo`` is not one of ``packages/ui``'s files if a+ # package sits in between.+ by_path = sorted(packages, key=lambda p: len(p.path), reverse=True)+ counts: dict[str, int] = {p.path: 0 for p in packages}+ langs: dict[str, Counter[str]] = {p.path: Counter() for p in packages}++ for parsed in parsed_files:+ path = getattr(getattr(parsed, "file_info", None), "path", "")+ if not path:+ continue+ for pkg in by_path:+ if path.startswith(f"{pkg.path}/"):+ counts[pkg.path] += 1+ language = getattr(parsed.file_info, "language", "") or ""+ if language:+ langs[pkg.path][language] += 1+ break++ stats: list[dict] = []+ for pkg in packages:+ total = counts[pkg.path]+ observed = [+ lang+ for lang, n in langs[pkg.path].most_common()+ if total and n / total >= _PACKAGE_LANGUAGE_FLOOR+ ]+ stats.append(+ {+ "name": pkg.name,+ "path": pkg.path,+ "files": total,+ # Falls back to the detected tag when nothing was parsed, so a+ # skipped package still names a language rather than a dash.+ "languages": observed or ([pkg.language] if not total and pkg.language else []),+ }+ )+ # Biggest first: the table doubles as a reading order. Name breaks ties so+ # a repository whose packages are all the same size does not reorder its+ # own overview between runs.+ stats.sort(key=lambda s: (-s["files"], s["name"]))+ return stats+def concept_wording(identifier: str) -> str:"""Spell an identifier the way prose would say it.@@ -647,6 +714,7 @@ class ContextAssembler:repo_name: str | None = None,external_systems: list[dict] | None = None,decision_records: list[dict] | None = None,+ parsed_files: list[ParsedFile] | None = None,) -> RepoOverviewContext:"""Assemble context for the repo_overview template."""# Top files sorted by PageRank descending, path breaking ties. Leaf@@ -661,6 +729,8 @@ class ContextAssembler:# SCCs with len > 1 are true circular depscircular_count = sum(1 for scc in sccs if len(scc) > 1)+ package_stats = _package_stats(repo_structure, parsed_files or [])+# Community metadata from graph buildercommunities_list: list[dict] = []execution_flows_list: list[dict] = []@@ -736,6 +806,7 @@ class ContextAssembler:execution_flows=execution_flows_list,external_systems=external_systems or [],decision_records=decision_records or [],+ package_stats=package_stats,)# ------------------------------------------------------------------diff --git a/packages/core/src/repowise/core/generation/context/contexts.py b/packages/core/src/repowise/core/generation/context/contexts.pyindex 0a85be3af..5835b3785 100644--- a/packages/core/src/repowise/core/generation/context/contexts.py+++ b/packages/core/src/repowise/core/generation/context/contexts.py@@ -176,6 +176,11 @@ class RepoOverviewContext:# Phase 2: third-party dependencies + headline architectural decisionsexternal_systems: list[dict] = field(default_factory=list)decision_records: list[dict] = field(default_factory=list)+ # Per-package file counts and observed languages, largest first. Counted+ # from the run's own parsed files rather than written by the model, so the+ # table they feed reads the same on every render. Empty when the repository+ # has no packages to tabulate.+ package_stats: list[dict] = field(default_factory=list)@dataclassdiff --git a/packages/core/src/repowise/core/generation/overview_tables.py b/packages/core/src/repowise/core/generation/overview_tables.pynew file mode 100644index 000000000..8054d12e8--- /dev/null+++ b/packages/core/src/repowise/core/generation/overview_tables.py@@ -0,0 +1,74 @@+"""Deterministic tables embedded into the repository overview.++The overview is written by a model, and enumerable facts written by a model are+resampled on every render: two calls with the same prompt, the same model and+the same temperature produced pages that disagreed on their row count and on+which paths they cited. Facts the run already holds — which packages exist,+where they are, how big they are — are built here instead and embedded after+the page comes back, the same way the architecture map already is.++That makes them identical on the model-written page and on the structure-only+page, stable across updates that changed no code, and assertable in a test.+"""++from __future__ import annotations++import re++import structlog++log = structlog.get_logger(__name__)++PACKAGE_TABLE_HEADING = "## Packages"++# The heading plus everything up to the next heading of the same or higher+# level. Anchored at a line start so a mention inside prose is not a match.+_PACKAGE_SECTION_RE = re.compile(+ r"^##[ \t]+Packages[ \t]*\n(?:.*?)(?=^#{1,2}[ \t]|\Z)",+ re.MULTILINE | re.DOTALL,+)+++def build_package_table(package_stats: list[dict]) -> str | None:+ """Render ``Package | Path | Files | Languages`` as a markdown table.++ Returns ``None`` when the repository has no packages to tabulate — a+ single-package repository is the common case and a header with no rows+ under it is worse than no section.+ """+ if not package_stats:+ # Not an error: most repositories are not monorepos. Logged because a+ # table that silently stops appearing is a failure this page has+ # already shipped once.+ log.info("overview_package_table_empty")+ return None++ lines = [+ "| Package | Path | Files | Languages |",+ "|---|---|---|---|",+ ]+ for pkg in package_stats:+ langs = ", ".join(pkg.get("languages") or []) or "—"+ lines.append(f"| {pkg['name']} | `{pkg['path']}` | {pkg.get('files', 0)} | {langs} |")+ log.debug("overview_package_table_built", packages=len(package_stats))+ return "\n".join(lines)+++def embed_package_table(content: str, table: str | None) -> str:+ """Return *content* with *table* under ``## Packages``, idempotently.++ Replaces an existing ``## Packages`` section wholesale, whether it is one+ this function wrote on a previous update or one the model wrote itself —+ the model writes that heading unprompted, and leaving both would give the+ reader the package list twice, once counted and once sampled.+ """+ if not table:+ return content++ section = f"{PACKAGE_TABLE_HEADING}\n\n{table}\n\n"+ if _PACKAGE_SECTION_RE.search(content):+ # Function replacement: table cells carry backslashes and backticks+ # that re.sub would otherwise read as group references.+ return _PACKAGE_SECTION_RE.sub(lambda _m: section, content, count=1)+ sep = "" if content.endswith("\n") else "\n"+ return f"{content}{sep}\n{section}"diff --git a/packages/core/src/repowise/core/generation/page_generator/levels.py b/packages/core/src/repowise/core/generation/page_generator/levels.pyindex 58ab024fb..025815148 100644--- a/packages/core/src/repowise/core/generation/page_generator/levels.py+++ b/packages/core/src/repowise/core/generation/page_generator/levels.py@@ -313,6 +313,11 @@ def build_level6_coros(run: _GenerationRun) -> list[tuple[str, Any]]:decision_records=run.decisions_all[:10],overview_mermaid=overview_mermaid,source_map=run.source_map,+ # Per-package file counts come from the files this run+ # actually parsed, not from the package manifests, so a+ # directory the walker skipped reads as zero rather than+ # going unmentioned.+ parsed_files=run.parsed_files,),))diff --git a/packages/core/src/repowise/core/generation/page_generator/pertype.py b/packages/core/src/repowise/core/generation/page_generator/pertype.pyindex 7a3e19264..98231e74f 100644--- a/packages/core/src/repowise/core/generation/page_generator/pertype.py+++ b/packages/core/src/repowise/core/generation/page_generator/pertype.py@@ -26,6 +26,7 @@ from ..models import (GeneratedPage,compute_source_hash,)+from ..overview_tables import build_package_table, embed_package_tablelog = structlog.get_logger(__name__)@@ -69,6 +70,25 @@ def _with_architecture_map(page: GeneratedPage, overview_mermaid: str | None) ->return page+def _with_package_table(page: GeneratedPage, package_stats: list[dict]) -> GeneratedPage:+ """Embed the package table into an already-built page.++ Same reasoning as the architecture map, and the same three paths: the model+ page, the deterministic page and the provider-outage fallback all carry it,+ because which packages exist is a fact the run already holds. Writing it+ through the model instead meant it was resampled on every render — two+ calls with the same prompt disagreed on the row count.++ Embedding is idempotent and replaces the model's own ``## Packages``+ section, so a reused or cached page picks up the current counts rather than+ accumulating a second list.+ """+ if not package_stats:+ return page+ page.content = embed_package_table(page.content, build_package_table(package_stats))+ return page++class PerTypeGenerationMixin:"""Per-type ``generate_*`` methods. Requires the host to provide``_assembler``, ``_render``, ``_call_provider`` and@@ -302,6 +322,7 @@ class PerTypeGenerationMixin:decision_records: list[dict] | None = None,overview_mermaid: str | None = None,source_map: dict[str, bytes] | None = None,+ parsed_files: list[ParsedFile] | None = None,) -> GeneratedPage:ctx = self._assembler.assemble_repo_overview(repo_structure,@@ -312,6 +333,7 @@ class PerTypeGenerationMixin:repo_name=repo_name,external_systems=external_systems,decision_records=decision_records,+ parsed_files=parsed_files,)repo_git_summary = Noneif git_meta_map:@@ -335,7 +357,9 @@ class PerTypeGenerationMixin:stub = self._stub_repo_overview(ctx, repo_name, f"Repository Overview: {repo_name}", repo_git_summary)- page = _with_architecture_map(stub, overview_mermaid)+ page = _with_architecture_map(+ _with_package_table(stub, ctx.package_stats), overview_mermaid+ )selection = self._disabled_source_evidence("repo_overview", "deterministic_generation")return self._attach_source_evidence(page, "repo_overview", selection)user_prompt = self._render("repo_overview.j2", ctx=ctx, repo_git_summary=repo_git_summary)@@ -351,12 +375,23 @@ class PerTypeGenerationMixin:ctx, repo_name, f"Repository Overview: {repo_name}", repo_git_summary)page = _with_architecture_map(- _stub_fallback(stub, "repo_overview", exc), overview_mermaid+ _with_package_table(+ _stub_fallback(stub, "repo_overview", exc), ctx.package_stats+ ),+ overview_mermaid,)return self._attach_source_evidence(page, "repo_overview", evidence)- # The overview carries the architecture map itself. It is the- # deterministic KG-derived diagram, not one the model drew, and- # embedding is idempotent so a reused page picks it up too.+ # The overview carries its own enumerable facts: the package table and+ # the KG-derived architecture map are built from the run, not drawn by+ # the model, and both embeds are idempotent so a reused page picks them+ # up too. The table goes in first so it lands above the diagram.+ if ctx.package_stats:+ response = replace(+ response,+ content=embed_package_table(+ response.content, build_package_table(ctx.package_stats)+ ),+ )if overview_mermaid:response = replace(response,diff --git a/packages/core/src/repowise/core/generation/templates/repo_overview.j2 b/packages/core/src/repowise/core/generation/templates/repo_overview.j2index 81f820fb5..975dd1dd3 100644--- a/packages/core/src/repowise/core/generation/templates/repo_overview.j2+++ b/packages/core/src/repowise/core/generation/templates/repo_overview.j2@@ -11,14 +11,24 @@ inputs the repo consumes, the transformation stages, and the artifacts produced.Do NOT open with stats or package counts; those belong further down.## Packages+{% for pkg in ctx.package_stats %}+- **{{ pkg.name }}** (`{{ pkg.path }}`, {{ pkg.files }} files{% if pkg.languages %}, {{ pkg.languages | join(", ") }}{% endif %})+{% else %}{% for pkg in ctx.packages %}- **{{ pkg.name }}** (`{{ pkg.path }}`, {{ pkg.language }}){% endfor %}--## Language Distribution-{% for lang, pct in ctx.language_distribution.items() %}-- {{ lang }}: {{ "%.1f"|format(pct * 100) }}%{% endfor %}+{% if ctx.package_stats %}+A `Package | Path | Files | Languages` table carrying exactly the rows above is+**already** on the page — it is inserted after you write, from these counts. Do+not repeat it and do not write a package list of your own.++What that table cannot state is what each package is *for*, which is a+judgement about the code rather than a count. Give each package one clause of+role inside the Architecture section, in the vocabulary this repository uses:+what it owns and who calls it. "The engine." "The bridge to the editor." Not+"holds TypeScript files."+{% endif %}## Entry Points{% for ep in ctx.entry_points %}diff --git a/packages/core/src/repowise/core/generation/templates/stub/repo_overview.j2 b/packages/core/src/repowise/core/generation/templates/stub/repo_overview.j2index 6c1c614ec..73604b6de 100644--- a/packages/core/src/repowise/core/generation/templates/stub/repo_overview.j2+++ b/packages/core/src/repowise/core/generation/templates/stub/repo_overview.j2@@ -25,6 +25,10 @@{%- if ctx.external_systems %} It builds on {{ ctx.external_systems | length }} external {{ "dependency" if ctx.external_systems | length == 1 else "dependencies" }}, including {% for s in ctx.external_systems[:5] %}`{{ s.name }}`{% if not loop.last %}, {% endif %}{% endfor %}.{% endif %}{% if ctx.packages %}+{# Replaced wholesale by the Package | Path | Files | Languages table, which is+ embedded after this renders. The list stays as what a reader gets when there+ are no per-package counts to tabulate — the heading has to exist here or the+ table would be appended after the footer. #}## Packages{% for pkg in ctx.packages %}- **{{ pkg.name }}** (`{{ pkg.path }}`, {{ pkg.language }})@@ -67,18 +71,10 @@ Ranked by PageRank over the import graph: the files most of the codebase ultimat{% endfor %}{% endif %}-{% if ctx.language_distribution %}-{# Same ordering and cap as the summary sentence above, or the two disagree. #}-{% set langs = ctx.language_distribution.items() | sort(attribute='1', reverse=true) %}-## Languages-{% for lang, pct in langs[:8] %}-- {{ lang }}: {{ "%.1f"|format(pct * 100) }}%-{% endfor %}-{%- if langs | length > 8 %}-- ...and {{ langs | length - 8 }} more.-{% endif %}-{% endif %}-+{# A repository-wide percentage breakdown of languages told the reader nothing+ they could act on — "python 57.2%" is not a fact anyone navigates by. The+ package table names the languages per package, which is, and the summary+ sentence above still names the dominant one. #}{% if ctx.external_systems %}## External Systems{% for sys in ctx.external_systems[:25] %}diff --git a/tests/unit/generation/test_overview_package_table.py b/tests/unit/generation/test_overview_package_table.pynew file mode 100644index 000000000..07271f378--- /dev/null+++ b/tests/unit/generation/test_overview_package_table.py@@ -0,0 +1,343 @@+"""The overview's package table.++The table is built from the run's own facts and embedded after the page is+written, on both the model-written and the structure-only page. That is+deliberate: the page's other enumerable facts came back from the model, so they+were resampled on every render — two calls to the same model with the same+prompt and the same temperature disagreed on how many rows the page had and on+which paths it cited. A reader comparing two updates could not tell a code+change from a re-roll. Facts that the run already knows do not go through a+sampler.+"""++from __future__ import annotations++import pytest+from structlog.testing import capture_logs++from repowise.core.generation.context_assembler import ContextAssembler+from repowise.core.generation.overview_tables import build_package_table, embed_package_table+from repowise.core.ingestion.models import PackageInfo, RepoStructure++from .conftest import _make_file_info+++def _count_path_citations(text: str) -> int:+ """Backticked tokens containing a path separator.++ The same count the retrieval side reads: a page's citations are what an+ answer can quote, so a content change that trades them away is a+ regression no prose metric would catch.+ """+ import re++ return len(re.findall(r"`[^`\n]*/[^`\n]*`", text))+++def _pkg(name: str, language: str = "python") -> PackageInfo:+ return PackageInfo(+ name=name,+ path=f"packages/{name}",+ language=language,+ entry_points=[],+ manifest_file="pyproject.toml" if language == "python" else "package.json",+ )+++def _parsed(path: str, language: str):+ """A ParsedFile carrying only what the table reads."""+ from repowise.core.ingestion.models import ParsedFile++ return ParsedFile(+ file_info=_make_file_info(path, language=language),+ symbols=[],+ imports=[],+ exports=[],+ )+++def structure():+ return RepoStructure(+ is_monorepo=True,+ packages=[_pkg("core"), _pkg("ui", "typescript"), _pkg("cli")],+ root_language_distribution={"python": 0.6, "typescript": 0.4},+ total_files=6,+ total_loc=600,+ entry_points=[],+ )+++def parsed_files():+ return [+ _parsed("packages/core/a.py", "python"),+ _parsed("packages/core/b.py", "python"),+ _parsed("packages/core/c.pyi", "python"),+ _parsed("packages/ui/x.tsx", "typescript"),+ _parsed("packages/ui/y.ts", "typescript"),+ _parsed("packages/cli/m.py", "python"),+ ]+++# ---------------------------------------------------------------------------+# context+# ---------------------------------------------------------------------------+++def test_context_counts_files_per_package(sample_config, structure, parsed_files):+ assembler = ContextAssembler(sample_config)+ ctx = assembler.assemble_repo_overview(structure, {}, [], {}, parsed_files=parsed_files)+ by_name = {p["name"]: p for p in ctx.package_stats}+ assert by_name["core"]["files"] == 3+ assert by_name["ui"]["files"] == 2+ assert by_name["cli"]["files"] == 1+++def test_context_ranks_packages_by_size(sample_config, structure, parsed_files):+ """The table is a reading order, so the biggest package leads."""+ assembler = ContextAssembler(sample_config)+ ctx = assembler.assemble_repo_overview(structure, {}, [], {}, parsed_files=parsed_files)+ assert [p["name"] for p in ctx.package_stats] == ["core", "ui", "cli"]+++def test_context_languages_are_observed_not_declared(sample_config, structure, parsed_files):+ """PackageInfo.language is one tag chosen at detection time. The column+ reports what is actually in the directory."""+ assembler = ContextAssembler(sample_config)+ ctx = assembler.assemble_repo_overview(structure, {}, [], {}, parsed_files=parsed_files)+ by_name = {p["name"]: p for p in ctx.package_stats}+ assert by_name["ui"]["languages"] == ["typescript"]+ assert by_name["core"]["languages"] == ["python"]+++def test_context_package_with_no_parsed_files_still_appears(sample_config, structure):+ """A package the walker skipped is still a package. Dropping the row would+ silently shorten the table."""+ assembler = ContextAssembler(sample_config)+ ctx = assembler.assemble_repo_overview(structure, {}, [], {}, parsed_files=[])+ assert [p["name"] for p in ctx.package_stats] == ["cli", "core", "ui"]+ assert all(p["files"] == 0 for p in ctx.package_stats)+++# ---------------------------------------------------------------------------+# the table+# ---------------------------------------------------------------------------+++def test_table_has_the_expected_headers(sample_config, structure, parsed_files):+ assembler = ContextAssembler(sample_config)+ ctx = assembler.assemble_repo_overview(structure, {}, [], {}, parsed_files=parsed_files)+ table = build_package_table(ctx.package_stats)+ assert "| Package | Path | Files | Languages |" in table+ assert "| `packages/core` |" in table+ assert len(table.splitlines()) == 1 + 1 + 3 # header, separator rule, three rows+++def test_table_cites_every_package_path(sample_config, structure, parsed_files):+ """Path citations are what an answer quotes. The table may not cost the+ page any of the ones the old bullet list carried."""+ assembler = ContextAssembler(sample_config)+ ctx = assembler.assemble_repo_overview(structure, {}, [], {}, parsed_files=parsed_files)+ table = build_package_table(ctx.package_stats)+ for pkg in structure.packages:+ assert f"`{pkg.path}`" in table+++def test_single_package_repo_renders_a_one_row_table(sample_config):+ """Not an empty table and not a missing section."""+ one = RepoStructure(+ is_monorepo=False,+ packages=[_pkg("only")],+ root_language_distribution={"python": 1.0},+ total_files=1,+ total_loc=10,+ entry_points=[],+ )+ stats = [{"name": "only", "path": "packages/only", "files": 1, "languages": ["python"]}]+ table = build_package_table(stats)+ assert table is not None+ assert len(table.splitlines()) == 3+ assert "| only | `packages/only` | 1 | python |" in table+ del one+++def test_no_packages_builds_no_table():+ """A single-package repository has nothing to tabulate. Say nothing rather+ than print a header with no rows under it."""+ assert build_package_table([]) is None+++# ---------------------------------------------------------------------------+# embedding+# ---------------------------------------------------------------------------+++def test_embed_appends_under_its_own_heading():+ out = embed_package_table("# Page\n\nSome prose.\n", "| Package |\n|---|\n| a |")+ assert "## Packages" in out+ assert "| Package |" in out+++def test_embed_is_idempotent():+ """Reused and cached pages get embedded again on every update."""+ once = embed_package_table("# Page\n", "| Package |\n|---|\n| a |")+ twice = embed_package_table(once, "| Package |\n|---|\n| a |")+ assert once == twice+++def test_embed_replaces_a_stale_table():+ """The count changes as the repository does; the page must not accumulate+ one table per update."""+ first = embed_package_table("# Page\n", "| Package |\n|---|\n| a |")+ second = embed_package_table(first, "| Package |\n|---|\n| b |")+ assert "| b |" in second+ assert "| a |" not in second+ assert second.count("## Packages") == 1+++def test_embed_replaces_the_models_own_packages_section():+ """The model writes a Packages section unprompted. Left alone the reader+ gets the same list twice, once sampled and once counted."""+ page = "# Page\n\n## Packages\n\n- **core** (`packages/core`, python)\n\n## Next\n\ntext\n"+ out = embed_package_table(page, "| Package |\n|---|\n| a |")+ assert out.count("## Packages") == 1+ assert "- **core**" not in out+ assert "## Next" in out+ assert "text" in out+++def test_embed_without_a_table_leaves_the_page_alone():+ page = "# Page\n\nprose\n"+ assert embed_package_table(page, None) == page+++# ---------------------------------------------------------------------------+# rendered output, both templates+# ---------------------------------------------------------------------------++[email protected]("template", ["repo_overview.j2", "stub/repo_overview.j2"])+def test_language_distribution_table_is_gone(sample_config, structure, parsed_files, template):+ """Step one: a percentage breakdown of the repository's languages told the+ reader nothing they could act on, and the package table carries languages+ per package, which they can."""+ from repowise.core.generation.page_generator import PageGenerator+ from repowise.core.providers.llm.mock import MockProvider++ assembler = ContextAssembler(sample_config)+ gen = PageGenerator(MockProvider(), assembler, sample_config)+ ctx = assembler.assemble_repo_overview(structure, {}, [], {}, parsed_files=parsed_files)+ out = gen._render(template, ctx=ctx, repo_git_summary=None)++ assert "Language Distribution" not in out+ assert "## Languages" not in out+ assert "60.0%" not in out+++def test_deterministic_page_carries_the_table(sample_config, structure, parsed_files):+ """The structure-only reader has no prose paragraph to carry this, so the+ table is the whole of what they learn about the package layout."""+ from repowise.core.generation.page_generator import PageGenerator+ from repowise.core.providers.llm.mock import MockProvider++ assembler = ContextAssembler(sample_config)+ gen = PageGenerator(MockProvider(), assembler, sample_config)+ ctx = assembler.assemble_repo_overview(structure, {}, [], {}, parsed_files=parsed_files)+ page = gen._stub_repo_overview(ctx, "testrepo", "Repository Overview: testrepo", None)+ out = embed_package_table(page.content, build_package_table(ctx.package_stats))++ assert "| Package | Path | Files | Languages |" in out+ assert "`packages/core`" in out+++def test_prompt_asks_for_a_role_clause_per_package(sample_config, structure, parsed_files):+ """The role is the one thing on this page no template can derive: it is a+ judgement about what a directory is for. The model is asked for it in+ prose, and the table stays a table of facts."""+ from repowise.core.generation.page_generator import PageGenerator+ from repowise.core.providers.llm.mock import MockProvider++ assembler = ContextAssembler(sample_config)+ gen = PageGenerator(MockProvider(), assembler, sample_config)+ ctx = assembler.assemble_repo_overview(structure, {}, [], {}, parsed_files=parsed_files)+ prompt = gen._render("repo_overview.j2", ctx=ctx, repo_git_summary=None)++ assert "role" in prompt.lower()+ # and it must tell the model the table is already there, or it writes a+ # second one and the reader gets the packages twice.+ assert "already" in prompt.lower()+++async def test_generator_embeds_the_table_on_the_deterministic_page(structure, parsed_files):+ """Through `generate_repo_overview`, not the helpers. The helpers were+ right before this was wired up and the page still had no table."""+ from repowise.core.generation.models import GenerationConfig+ from repowise.core.generation.page_generator import PageGenerator+ from repowise.core.providers.llm.mock import MockProvider++ config = GenerationConfig(deterministic=True)+ gen = PageGenerator(MockProvider(), ContextAssembler(config), config)+ page = await gen.generate_repo_overview(+ structure, {}, [], {}, repo_name="testrepo", parsed_files=parsed_files+ )++ assert "| Package | Path | Files | Languages |" in page.content+ assert "| core | `packages/core` | 3 | python |" in page.content+ # and the bullet list it replaced is gone, not sitting above it+ assert "- **core** (`packages/core`" not in page.content+ assert page.content.count("## Packages") == 1+++async def test_generator_embed_is_stable_across_two_runs(structure, parsed_files):+ """The point of building this outside the model: same input, same bytes."""+ from repowise.core.generation.models import GenerationConfig+ from repowise.core.generation.page_generator import PageGenerator+ from repowise.core.providers.llm.mock import MockProvider++ config = GenerationConfig(deterministic=True)+ gen = PageGenerator(MockProvider(), ContextAssembler(config), config)+ first = await gen.generate_repo_overview(+ structure, {}, [], {}, repo_name="testrepo", parsed_files=parsed_files+ )+ second = await gen.generate_repo_overview(+ structure, {}, [], {}, repo_name="testrepo", parsed_files=parsed_files+ )+ assert first.content == second.content+++async def test_deterministic_page_cites_no_fewer_paths_than_before(structure, parsed_files):+ """The floor this change is most likely to breach.++ Replacing a bullet list of paths with a table is a trade of citations for+ layout, and a page that reads better while citing less is a worse answer+ source: a backticked path is what an answer quotes. Counted here rather+ than argued about — the table must carry at least the paths the list did.+ """+ from repowise.core.generation.models import GenerationConfig+ from repowise.core.generation.page_generator import PageGenerator+ from repowise.core.providers.llm.mock import MockProvider++ config = GenerationConfig(deterministic=True)+ gen = PageGenerator(MockProvider(), ContextAssembler(config), config)+ ctx = gen._assembler.assemble_repo_overview(structure, {}, [], {}, parsed_files=parsed_files)+ before = gen._stub_repo_overview(ctx, "testrepo", "Repository Overview: testrepo", None)+ after = await gen.generate_repo_overview(+ structure, {}, [], {}, repo_name="testrepo", parsed_files=parsed_files+ )++ assert _count_path_citations(after.content) >= _count_path_citations(before.content)+ for pkg in structure.packages:+ assert f"`{pkg.path}`" in after.content+++def test_table_build_is_logged(sample_config, structure, parsed_files):+ """Every code path here reports. A table that silently stops appearing is+ the failure this page has already shipped once."""+ assembler = ContextAssembler(sample_config)+ ctx = assembler.assemble_repo_overview(structure, {}, [], {}, parsed_files=parsed_files)+ with capture_logs() as logs:+ build_package_table(ctx.package_stats)+ build_package_table([])+ events = {e["event"] for e in logs}+ assert "overview_package_table_empty" in events