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): 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.py
index 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 annotations
import re
+from collections import Counter
from pathlib import PurePosixPath
from 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 deps
circular_count = sum(1 for scc in sccs if len(scc) > 1)
+ package_stats = _package_stats(repo_structure, parsed_files or [])
+
# Community metadata from graph builder
communities_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.py
index 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 decisions
external_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)
@dataclass
diff --git a/packages/core/src/repowise/core/generation/overview_tables.py b/packages/core/src/repowise/core/generation/overview_tables.py
new file mode 100644
index 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.py
index 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.py
index 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_table
log = 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 = None
if 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.j2
index 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.j2
index 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.py
new file mode 100644
index 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