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
"""The overview's capability table, and the rule that decides its rows.
The selection rule is the whole of this feature. Mined vocabulary ranked by
document frequency alone is not front-page material: on this repository the
top of that list holds "DONE", "Architecture" and "Files changed" alongside
the real capabilities, and half the rows would be junk.
So a term reaches the page only with corroboration from a second,
independently-derived artifact — a module page, grouped from the dependency
graph and written from the code, has to name it. Nothing here is a stopword
list, and nothing here is tuned per repository.
Like the package table, the result is embedded after the page is written, so
the model page, the ``--no-prose`` page and the provider-outage fallback carry
identical bytes.
"""
from __future__ import annotations
import pytest
from structlog.testing import capture_logs
from repowise.core.generation.concept_tree.vocabulary import HouseTerm
from repowise.core.generation.context_assembler import ContextAssembler
from repowise.core.generation.house_vocabulary import select_terms
from repowise.core.generation.overview_tables import (
CAPABILITY_TABLE_HEADING,
build_capability_table,
embed_capability_table,
select_capabilities,
)
from repowise.core.ingestion.models import PackageInfo, RepoStructure
from .conftest import _make_file_info
_DEFINED = object()
def _term(
term: str,
*,
definition: str | None | object = _DEFINED,
definition_source: str | None = None,
source_paths: tuple[str, ...] = ("README.md",),
doc_frequency: int = 1,
code_frequency: int = 5,
) -> HouseTerm:
if definition is _DEFINED:
definition = f"{term} is a capability the documents describe."
return HouseTerm(
term=term,
definition=definition,
definition_source=definition_source,
source_paths=source_paths,
doc_frequency=doc_frequency,
code_frequency=code_frequency,
is_indexed_symbol=False,
)
#: What the structural side calls the parts of the system: module group
#: titles, their community labels, and their paths. Cut from the dependency
#: graph and named from the code, with no knowledge of the documents.
MODULES = [
"Dead Code and Reachability Analysis",
"Blast Radius UI",
"Ledger Postings",
"src/analysis/dead_code",
]
# ---------------------------------------------------------------------------
# The selection rule
# ---------------------------------------------------------------------------
def test_a_term_no_module_page_names_does_not_reach_the_page():
"""The gate. "DONE" is a real heading in this repository's own documents
and leads the frequency ranking; no module page has ever mentioned it."""
picked = select_capabilities([_term("DONE"), _term("Dead code")], MODULES)
assert [c.term for c in picked] == ["Dead code"]
def test_corroboration_may_come_from_a_title_or_from_a_path():
"""Both are what the structure calls a part of the system."""
by_title = select_capabilities([_term("Blast radius")], MODULES)
by_path = select_capabilities([_term("Dead code")], ["src/analysis/dead_code"])
assert [c.term for c in by_title] == ["Blast radius"]
assert [c.term for c in by_path] == ["Dead code"]
def test_multi_word_terms_come_before_single_word_ones():
"""A subsystem is nearly always named with two words and an ordinary
English word with one. "Analysis" is corroborated — it is in a module
title — and it is still not what the front page should lead with."""
picked = select_capabilities([_term("Analysis"), _term("Dead code")], MODULES, limit=2)
assert [c.term for c in picked] == ["Dead code", "Analysis"]
def test_a_single_word_still_reaches_the_table_when_there_is_room():
"""Ordering, not a filter. A repository whose vocabulary is single words
-- django's is Models, Middleware, Migrations -- must still get a table."""
picked = select_capabilities([_term("Analysis")], MODULES)
assert [c.term for c in picked] == ["Analysis"]
def test_the_table_is_capped():
terms = [_term(f"Term number {n}") for n in range(20)]
modules = [" ".join(t.term for t in terms)]
assert len(select_capabilities(terms, modules)) == 6
def test_selection_does_not_depend_on_the_order_of_the_corroboration_corpus():
"""The selection is a function of the inputs, not of how they arrived."""
terms = [_term("Dead code"), _term("Blast radius"), _term("Postings")]
forwards = select_capabilities(terms, MODULES)
backwards = select_capabilities(terms, list(reversed(MODULES)))
assert forwards == backwards
def test_a_term_with_no_path_anywhere_is_not_offered():
"""Every row cites where it was read. A row that cannot is a claim this
wiki does not make."""
assert select_capabilities([_term("Dead code", source_paths=())], MODULES) == []
def test_selection_is_logged_with_what_it_kept_and_what_it_dropped():
with capture_logs() as logs:
select_capabilities([_term("DONE"), _term("Dead code")], MODULES)
event = next(e for e in logs if e["event"] == "house_vocabulary.selected")
assert event["mined"] == 2
assert event["corroborated"] == 1
assert event["terms"] == ["Dead code"]
def test_mining_terms_that_no_module_page_corroborates_is_a_warning():
"""Distinct from mining nothing: the documents name things the structure
does not. A real answer about a repository, and also what an empty
corroboration corpus looks like, so the counts that separate them go out."""
with capture_logs() as logs:
select_capabilities([_term("DONE")], MODULES)
assert any(e["event"] == "house_vocabulary.uncorroborated" for e in logs)
# ---------------------------------------------------------------------------
# Rendering
# ---------------------------------------------------------------------------
def test_the_table_carries_the_term_its_sentence_and_its_source():
picked = select_capabilities(
[
_term(
"Dead code",
definition="Dead code is code no import path reaches.",
definition_source="src/analysis/dead_code.py",
)
],
MODULES,
)
table = build_capability_table(picked)
assert "| Capability | What it is | Where it is written |" in table
assert "| Dead code | Dead code is code no import path reaches. |" in table
assert "`src/analysis/dead_code.py`" in table
@pytest.mark.parametrize(
"text",
[
# Both real, both from this repository's own front page.
"repowise init [PATH] # index a codebase (one-time; asks, or --no-prose -y needs no LLM)",
"`repowise distill <cmd>` compresses command output *before* the agent reads it:",
"$ repowise update --all",
"Run it with --no-prose to skip the model",
"cat wiki.db | sqlite3 .dump",
"Two parts,",
"See below",
],
)
def test_prose_that_is_not_a_statement_is_not_offered_as_a_definition(text):
"""A mined definition is whatever prose sat nearest the term, and near a
term in a README that is often a command line or a lead-in. An em dash is
a better answer: the reader learns the capability exists and is not
misinformed about what it does."""
picked = select_terms([_term("Dead code", definition=text)], MODULES)
assert picked[0].definition is None
@pytest.mark.parametrize(
"term,text",
[
("Dead code", "Dead code is code no import path reaches."),
(
"Blast radius",
"Blast radius is the set of files a change can reach through the import graph.",
),
("Middleware", "Middleware for utilizing Web-server-provided authentication."),
# Terse, and still the repository's own answer. Both of these were
# rejected by a first cut of the test that was tuned too strict.
("Blast radius", "Blast-radius request/response models."),
(
"Decisions",
"Decisions are co-located in the page vector store under the "
"``decision:<record_id>`` namespace (no separate table).",
),
],
)
def test_a_real_sentence_survives(term, text):
"""Each sentence is paired with the term it names, because a definition
that never mentions its term is rejected as prose that merely sat nearby."""
picked = select_capabilities([_term(term, definition=text)], [*MODULES, term])
assert picked[0].definition == text
def test_a_rejected_definition_does_not_leave_its_source_behind():
"""Citing where prose the table declined to quote lives would point the
reader at a line that is not on the page."""
picked = select_terms(
[
_term(
"Dead code",
definition="$ repowise dead-code --json",
definition_source="README.md#usage",
source_paths=("docs/guide.md",),
)
],
MODULES,
)
assert picked[0].definition is None
assert picked[0].source_path == "docs/guide.md"
def test_a_rejected_definition_is_logged():
with capture_logs() as logs:
select_capabilities([_term("Dead code", definition="$ repowise dead-code")], MODULES)
assert any(e["event"] == "house_vocabulary.definition_rejected" for e in logs)
def test_capability_table_omits_undefined():
"""A row reading "—" tells the reader nothing, so undefined terms stay off
the front page and defined ones take their slots; none defined, no table."""
terms = [_term("Blast radius", definition=None), _term("Dead code")]
picked = select_capabilities(terms, MODULES, limit=1)
assert [c.term for c in picked] == ["Dead code"]
table = build_capability_table(picked)
assert "—" not in table
assert "Blast radius" not in table
undefined = select_terms([_term("Dead code", definition=None)], MODULES)
assert build_capability_table(undefined) is None
assert select_capabilities([_term("Dead code", definition=None)], MODULES) == []
def test_the_source_falls_back_to_the_document_that_named_the_term():
picked = select_capabilities(
[_term("Dead code", source_paths=("docs/guide.md", "src/sweep.py"))], MODULES
)
assert picked[0].source_path == "docs/guide.md"
def test_a_pipe_in_mined_prose_does_not_break_the_table():
"""Definitions are the repository's text, not ours. One that quotes a
shell pipeline or a reStructuredText grid row would otherwise shift every
column to its right."""
table = build_capability_table(
select_capabilities(
[_term("Dead code", definition="Dead code is what a `grep|sort` pass over the tree never finds.")],
MODULES,
)
)
row = next(line for line in table.splitlines() if line.startswith("| Dead code"))
assert row.count("|") - row.count("\\|") == 4
def test_a_long_definition_is_cut_rather_than_wrapping_the_row():
long_sentence = "Dead code is " + "unreachable " * 60 + "code."
table = build_capability_table(
select_capabilities([_term("Dead code", definition=long_sentence)], MODULES)
)
row = next(line for line in table.splitlines() if line.startswith("| Dead code"))
assert "…" in row
assert len(row) < 260
def test_no_capabilities_means_no_table_and_no_heading():
"""A header over an empty table says less than no section at all."""
assert build_capability_table([]) is None
assert embed_capability_table("# Overview\n", None) == "# Overview\n"
def test_the_empty_case_is_logged():
with capture_logs() as logs:
build_capability_table([])
assert any(e["event"] == "overview_capability_table_empty" for e in logs)
def test_embedding_is_idempotent():
"""A reused or cached page picks up the current selection rather than
accumulating a second one -- including over a section the model wrote."""
table = build_capability_table(select_capabilities([_term("Dead code")], MODULES))
once = embed_capability_table("# Overview\n\nSome prose.\n", table)
twice = embed_capability_table(once, table)
assert once == twice
assert twice.count(CAPABILITY_TABLE_HEADING) == 1
def test_embedding_replaces_a_section_the_model_wrote_itself():
model_page = "# Overview\n\n## What it does\n\nIt does several things.\n\n## Packages\n\nrows\n"
table = build_capability_table(select_capabilities([_term("Dead code")], MODULES))
out = embed_capability_table(model_page, table)
assert "It does several things." not in out
assert out.count(CAPABILITY_TABLE_HEADING) == 1
# and the section after it survives
assert "## Packages" in out
# ---------------------------------------------------------------------------
# Through the generator, on every path
# ---------------------------------------------------------------------------
def _pkg(name: str, language: str = "python") -> PackageInfo:
return PackageInfo(
name=name,
path=f"packages/{name}",
language=language,
entry_points=[],
manifest_file="pyproject.toml",
)
def _parsed(path: str, language: str = "python"):
from repowise.core.ingestion.models import ParsedFile
return ParsedFile(
file_info=_make_file_info(path, language=language), symbols=[], imports=[], exports=[]
)
@pytest.fixture
def structure():
return RepoStructure(
is_monorepo=True,
packages=[_pkg("core")],
root_language_distribution={"python": 1.0},
total_files=2,
total_loc=200,
entry_points=[],
)
@pytest.fixture
def parsed_files():
return [_parsed("packages/core/a.py"), _parsed("packages/core/b.py")]
@pytest.fixture
def capabilities():
return select_capabilities(
[
_term(
"Dead code",
definition="Dead code is code no import path reaches.",
definition_source="src/analysis/dead_code.py",
)
],
MODULES,
)
async def test_the_deterministic_page_carries_the_table(structure, parsed_files, capabilities):
"""`repo_overview.j2` is a prompt, not a page. Asserting a table on it
asserts nothing about what ships, so this goes through the generator."""
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,
capabilities=capabilities,
)
assert "| Capability | What it is | Where it is written |" in page.content
assert "Dead code is code no import path reaches." in page.content
assert page.content.count(CAPABILITY_TABLE_HEADING) == 1
async def test_the_model_written_page_carries_the_same_bytes(structure, parsed_files, capabilities):
from repowise.core.generation.models import GenerationConfig
from repowise.core.generation.page_generator import PageGenerator
from repowise.core.providers.llm.mock import MockProvider
deterministic = GenerationConfig(deterministic=True)
prose = GenerationConfig()
args = dict(repo_name="testrepo", parsed_files=parsed_files, capabilities=capabilities)
stub_page = await PageGenerator(
MockProvider(), ContextAssembler(deterministic), deterministic
).generate_repo_overview(structure, {}, [], {}, **args)
model_page = await PageGenerator(
MockProvider(), ContextAssembler(prose), prose
).generate_repo_overview(structure, {}, [], {}, **args)
table = build_capability_table(capabilities)
assert table in stub_page.content
assert table in model_page.content
async def test_a_provider_outage_costs_the_prose_not_the_table(
structure, parsed_files, capabilities
):
"""The same reasoning as the architecture map: a fact the run already holds
should survive the provider that was not needed to produce it."""
from repowise.core.generation.models import GenerationConfig
from repowise.core.generation.page_generator import PageGenerator
from repowise.core.providers.llm.mock import MockProvider
class Failing(MockProvider):
async def generate(self, *a, **kw):
raise RuntimeError("upstream 529 overloaded")
config = GenerationConfig()
gen = PageGenerator(Failing(), ContextAssembler(config), config)
page = await gen.generate_repo_overview(
structure,
{},
[],
{},
repo_name="testrepo",
parsed_files=parsed_files,
capabilities=capabilities,
)
from repowise.core.generation.models import STUB_FALLBACK_ERROR
# The fallback path really was taken, rather than the assertion below
# passing because the provider was never reached.
assert "529 overloaded" in page.metadata[STUB_FALLBACK_ERROR]
assert "| Capability | What it is | Where it is written |" in page.content
async def test_the_page_is_byte_identical_across_two_runs(structure, parsed_files, capabilities):
"""The point of building this outside the model."""
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)
args = dict(repo_name="testrepo", parsed_files=parsed_files, capabilities=capabilities)
first = await gen.generate_repo_overview(structure, {}, [], {}, **args)
second = await gen.generate_repo_overview(structure, {}, [], {}, **args)
assert first.content == second.content
async def test_the_table_only_adds_path_citations(structure, parsed_files, capabilities):
"""A page that reads better while citing less is a worse answer source.
The third column is a real path, so this can only go up."""
import re
from repowise.core.generation.models import GenerationConfig
from repowise.core.generation.page_generator import PageGenerator
from repowise.core.providers.llm.mock import MockProvider
def cites(text: str) -> int:
return len(re.findall(r"`[^`\n]*/[^`\n]*`", text))
config = GenerationConfig(deterministic=True)
gen = PageGenerator(MockProvider(), ContextAssembler(config), config)
args = dict(repo_name="testrepo", parsed_files=parsed_files)
without = await gen.generate_repo_overview(structure, {}, [], {}, **args)
with_table = await gen.generate_repo_overview(
structure, {}, [], {}, capabilities=capabilities, **args
)
assert cites(with_table.content) > cites(without.content)
async def test_no_capabilities_leaves_the_page_as_it_was(structure, parsed_files):
"""A repository whose documents name nothing its code also spells is a
supported and common outcome."""
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 CAPABILITY_TABLE_HEADING not in page.content
def test_embedding_nothing_removes_a_section_an_earlier_run_left():
"""A model page is reused verbatim while its prompt is unchanged, and the
table is not part of the prompt. Rows an earlier selection embedded stay
on that page unless an empty selection takes them off."""
reused = "# Overview\n\nProse.\n\n## What it does\n\n| a | b |\n\n## Packages\n\nrows\n"
out = embed_capability_table(reused, None)
assert CAPABILITY_TABLE_HEADING not in out
assert out.startswith("# Overview\n\nProse.\n\n## Packages")
async def test_a_reused_model_page_loses_rows_the_selection_no_longer_has(
structure, parsed_files
):
from repowise.core.generation.models import GenerationConfig
from repowise.core.generation.page_generator import PageGenerator
from repowise.core.providers.llm.base import GeneratedResponse
from repowise.core.providers.llm.mock import MockProvider
earlier = (
"## Project Summary\n\nProse.\n\n## What it does\n\n"
"| Capability | What it is | Where it is written |\n|---|---|---|\n"
"| Dead code | — | `README.md` |\n"
)
provider = MockProvider(
responses=[GeneratedResponse(content=earlier, input_tokens=0, output_tokens=0)]
)
config = GenerationConfig()
page = await PageGenerator(provider, ContextAssembler(config), config).generate_repo_overview(
structure, {}, [], {}, repo_name="testrepo", parsed_files=parsed_files
)
assert CAPABILITY_TABLE_HEADING not in page.content
assert "| Dead code | — |" not in page.content