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
"""Render tests for deterministic templates the sample repo cannot reach.
``tests/integration/test_deterministic_generation.py`` covers the page types
the fixture repo actually produces. The rest are unreachable there: the layer
page needs a knowledge graph, and the onboarding slots below gate themselves
off on a fixture with no git history and no dependency manifest. Rendering
them here keeps a Jinja typo from shipping unnoticed.
"""
from __future__ import annotations
import pytest
from repowise.core.generation.context_assembler import (
ApiContractContext,
ContextAssembler,
FilePageContext,
InfraPageContext,
SccPageContext,
SymbolSpotlightContext,
)
from repowise.core.generation.models import GenerationConfig
from repowise.core.generation.onboarding.subkinds.active_landscape import (
ActiveLandscapeContext,
HotDir,
HotFile,
)
from repowise.core.generation.onboarding.subkinds.getting_started import (
GettingStartedContext,
ReadmeSection,
)
from repowise.core.generation.page_generator import PageGenerator
from repowise.core.generation.structural_labels import structural_page_title
from repowise.core.providers.llm.template import TemplateProvider
@pytest.fixture
def generator() -> PageGenerator:
config = GenerationConfig(deterministic=True)
return PageGenerator(TemplateProvider(), ContextAssembler(config), config)
@pytest.fixture
def german_generator() -> PageGenerator:
config = GenerationConfig(deterministic=True, language="de")
return PageGenerator(TemplateProvider(), ContextAssembler(config), config)
@pytest.fixture
def klingon_generator() -> PageGenerator:
"""A configured language with no label catalog of its own."""
config = GenerationConfig(deterministic=True, language="tlh")
return PageGenerator(TemplateProvider(), ContextAssembler(config), config)
def _onboarding_spec(slot: str, template: str):
from repowise.core.generation.onboarding.registry import SubkindSpec
return SubkindSpec(
slot=slot,
title=slot.replace("_", " ").title(),
template=template,
build_context=lambda _s: None,
)
def test_getting_started_renders(generator):
ctx = GettingStartedContext(
repo_name="demo",
package_managers=["uv"],
runtime_dependencies=[{"name": "httpx", "version": "0.27"}],
dev_dependencies=[{"name": "pytest", "version": "9.0"}],
readme_sections=[ReadmeSection(heading="Install", body="Run `uv sync`.")],
entry_points=["src/main.py"],
)
page = generator._stub_onboarding_page(
_onboarding_spec("getting_started", "getting_started.j2"), ctx, "onboarding/getting_started"
)
assert page.metadata["onboarding_slot"] == "getting_started"
assert "**uv**" in page.content
assert "Run `uv sync`." in page.content
assert "`httpx`" in page.content
def test_active_landscape_renders(generator):
ctx = ActiveLandscapeContext(
repo_name="demo",
total_commits_90d=120,
files_touched_90d=45,
hot_files=[
HotFile(
path="src/core.py",
commit_count_90d=30,
primary_owner="Ada",
is_hotspot=True,
age_days=400,
)
],
hot_dirs=[HotDir(path="src", total_commits_90d=90, hotspot_count=2, file_count=20)],
dead_code_in_hot_files=[{"symbol_name": "old_fn", "file_path": "src/core.py"}],
stable_file_count=8,
)
page = generator._stub_onboarding_page(
_onboarding_spec("active_landscape", "active_landscape.j2"),
ctx,
"onboarding/active_landscape",
)
assert "120 commits touched 45 files" in page.content
assert "`src/core.py`" in page.content
assert "Ada" in page.content
assert "old_fn" in page.content
def test_symbol_spotlight_renders(generator):
"""The only renderer for this page type, so it always runs."""
from repowise.core.generation.context_assembler import SymbolSpotlightContext
ctx = SymbolSpotlightContext(
symbol_name="parse_file",
qualified_name="parser.ASTParser.parse_file",
kind="method",
signature="def parse_file(self, fi, src) -> ParsedFile",
docstring="Parse one file into an AST.",
file_path="src/parser.py",
decorators=["@lru_cache"],
is_async=False,
complexity_estimate=7,
callers=["src/pipeline.py"],
source_body="def parse_file(self, fi, src):\n return ...",
)
page = generator._structural_symbol_spotlight(
ctx, "src/parser.py::parse_file", "Symbol: parser.ASTParser.parse_file"
)
assert page.page_type == "symbol_spotlight"
assert page.provider_name == "template"
assert "Parse one file into an AST." in page.content
assert "@lru_cache" in page.content
# Callers are module importers, not verified call sites. The page must
# not claim more than the graph knows.
assert "not confirmed call sites" in page.content
def test_symbol_spotlight_tolerates_missing_kind(generator):
from repowise.core.generation.context_assembler import SymbolSpotlightContext
ctx = SymbolSpotlightContext(
symbol_name="x",
qualified_name="x",
kind="",
signature="",
docstring=None,
file_path="a.py",
decorators=[],
is_async=False,
complexity_estimate=0,
callers=[],
)
page = generator._structural_symbol_spotlight(ctx, "a.py::x", "Symbol: x")
assert "is a symbol defined in" in page.content
def test_multiline_summaries_stay_inside_their_list_item(generator):
"""A raw newline in a bullet ends the markdown list, dumping the rest as
body text. Parsed signatures routinely carry newlines, so every text field
folded into a list item runs through the oneline filter."""
ctx = ApiContractContext(
file_path="api/routes.py",
language="python",
raw_content="",
endpoints=[
"def create(\n self,\n payload: dict,\n) -> Response",
"def delete(self, id: str) -> None",
],
schemas=[],
)
page = generator._structural_api_contract(ctx, "api/routes.py", "API Contract: api/routes.py")
body = page.content.split("## Operations", 1)[1]
bullets = [ln for ln in body.splitlines() if ln.startswith("- ")]
assert len(bullets) == 2, f"list broke apart: {bullets}"
assert "def create( self, payload: dict, ) -> Response" in bullets[0]
def test_summary_skips_the_stats_line():
"""Several templates open with a bold field line under the H1.
The persisted summary is what the wiki list, search results and
get_context show, so a summary of "**Files:** 412 | **Lines:** 90210"
displaces the sentence that would have told the reader what the page is.
"""
from repowise.core.generation.page_generator.helpers import _extract_summary
content = (
"# Module: core/ingestion\n\n"
"**Files:** 412 | **Lines:** 90210\n\n"
"## Overview\n\n"
"Walks the repository and parses every source file it recognises.\n"
)
assert _extract_summary(content, skip_metadata=True).startswith("Walks the repository")
# Off by default: a model that opens with **Purpose:** means it as prose.
assert _extract_summary(content).startswith("**Files:**")
# ---------------------------------------------------------------------------
# Docstring and signature rendering
# ---------------------------------------------------------------------------
def test_as_markdown_converts_sphinx_roles_to_code_spans():
from repowise.core.generation.page_generator.structural import as_markdown
out = as_markdown("See :meth:`Store.get` and :class:`~pkg.Thing`.")
assert out == "See `Store.get` and `pkg.Thing`."
def test_as_markdown_converts_double_backtick_literals():
from repowise.core.generation.page_generator.structural import as_markdown
assert as_markdown("Pass ``None`` to skip.") == "Pass `None` to skip."
def test_as_markdown_drops_rest_directives():
from repowise.core.generation.page_generator.structural import as_markdown
out = as_markdown("Body text.\n\n.. note:: internal only\n")
assert ".. note::" not in out
assert "Body text." in out
def test_as_markdown_turns_a_rest_title_into_a_heading():
"""Left as text, the underline renders and the title becomes the summary."""
from repowise.core.generation.page_generator.structural import as_markdown
out = as_markdown("Tagged JSON\n~~~~~~~~~~~\n\nA compact representation.\n")
assert out == "### Tagged JSON\n\nA compact representation."
def test_as_markdown_drops_the_overline_of_a_rest_title():
from repowise.core.generation.page_generator.structural import as_markdown
out = as_markdown("=========\nBig Title\n=========\n\nSome prose.")
assert out == "### Big Title\n\nSome prose."
def test_as_markdown_leaves_a_short_rule_under_prose_alone():
"""reST requires the underline to be at least as long as the title."""
from repowise.core.generation.page_generator.structural import as_markdown
assert as_markdown("A longer line of prose.\n---\n") == "A longer line of prose.\n---"
def test_as_markdown_dedents_so_the_body_is_not_a_code_block():
"""Four leading spaces would make markdown render the body as code."""
from repowise.core.generation.page_generator.structural import as_markdown
out = as_markdown("Summary line.\n\n Indented continuation.\n")
assert "\n Indented" not in out
assert "Indented continuation." in out
def test_as_markdown_leaves_plain_text_alone():
from repowise.core.generation.page_generator.structural import as_markdown
assert as_markdown("Just a sentence.") == "Just a sentence."
assert as_markdown(None) == ""
def test_signature_reads_as_a_declaration_not_as_source():
"""Signatures span source lines, so raw text carries the author's layout."""
from repowise.core.generation.page_generator.structural import signature
raw = "def go(\n a: int,\n b: str,\n ) -> None"
assert signature(raw) == "def go(a: int, b: str) -> None"
def test_signature_closes_a_capture_that_stopped_mid_expression():
"""A constant whose value opens a bracket is stored without its tail.
Closed rather than cut back to the declaration: the page is also the index
entry, so ``= re.compile(`` must not take ``re`` and ``compile`` with it.
"""
from repowise.core.generation.page_generator.structural import signature
assert signature("PRUNED_DIRS: frozenset[str] = frozenset(") == (
"PRUNED_DIRS: frozenset[str] = frozenset(…)"
)
assert signature("ReasoningMode = Literal[") == "ReasoningMode = Literal[…]"
assert signature("ROW_ACTIVE =") == "ROW_ACTIVE"
# A value that closes is the declaration's meaning, and is kept.
assert signature("MAX = 64") == "MAX = 64"
def test_signature_never_rewrites_a_declaration_that_already_fits():
"""Under the limit, the only change may be the collapsed whitespace.
Every pass reshapes source punctuation, and a signature routinely carries
a regex or a path in a string literal. Rewriting inside one puts a value
on the page that the source does not have, and the page is what the index
embeds. These are real declarations from this repository.
"""
from repowise.core.generation.page_generator.structural import signature
for raw in (
'IDENTIFIER_RE = re.compile(rb"[A-Za-z_][A-Za-z0-9_]{2,}")',
'filenames: tuple[str, ...] = ("Cargo.toml",)',
'_SPRING_CTOR_PARAM_RE = re.compile(r"([A-Z]w*)s+w+s*[,)]")',
'def _doc_paths(root: Path, *, patterns: tuple[str, ...] = ("*.md",)) -> list[Path]',
):
assert signature(raw) == raw, raw
def test_signature_reduces_a_parameter_to_its_name_not_to_a_string_it_contained():
"""A default value holding a comma must not split into two parameters."""
from repowise.core.generation.page_generator.structural import signature
raw = (
'def render(self, template: str, sep: str = ", ", prefix: str = "(", '
'suffix: str = ")", indent: int = 4, width: int = 88) -> str'
)
assert signature(raw) == "def render(self, template, sep, prefix, suffix, indent, width) -> str"
def test_signature_does_not_count_a_bracket_inside_a_string_literal():
"""A character class is not an unclosed bracket."""
from repowise.core.generation.page_generator.structural import signature
raw = '_META_RE = re.compile(r"[|&;<>]")'
assert signature(raw) == raw
def test_signature_sheds_parameter_detail_before_it_sheds_the_return_type():
from repowise.core.generation.page_generator.structural import signature
raw = "def go(" + ", ".join(f"argument_number_{i}: int = 0" for i in range(3)) + ") -> None"
out = signature(raw, limit=80)
# What a function returns is the half a reader is looking for, so the
# annotations and defaults go first and the return type survives.
assert out.endswith(") -> None")
assert "argument_number_0" in out
assert "int = 0" not in out
def test_signature_falls_back_to_an_ellipsis_when_even_the_names_are_too_long():
from repowise.core.generation.page_generator.structural import signature
raw = "def go(" + ", ".join(f"argument_number_{i}" for i in range(40)) + ") -> None"
out = signature(raw, limit=60)
assert out == "def go(…) -> None"
def test_signature_leaves_short_signatures_untouched():
from repowise.core.generation.page_generator.structural import signature
assert signature("def go(x: int) -> None") == "def go(x: int) -> None"
def test_as_markdown_leaves_fenced_code_blocks_intact():
"""The double-backtick rule must not chew the fence delimiters."""
from repowise.core.generation.page_generator.structural import as_markdown
src = "Run it.\n\nExample:\n\n```python\nx = 1\n```\n"
assert "```python\nx = 1\n```" in as_markdown(src)
def test_as_markdown_leaves_triple_backtick_spans_intact():
from repowise.core.generation.page_generator.structural import as_markdown
assert as_markdown("Use ```code``` here.") == "Use ```code``` here."
def test_as_markdown_does_not_eat_ordinary_colon_text():
"""A permissive role pattern deletes any word:word: before a backtick."""
from repowise.core.generation.page_generator.structural import as_markdown
assert as_markdown("Time complexity: O(n:m:`k`)") == "Time complexity: O(n:m:`k`)"
assert as_markdown("See http://x.io/a:b:`c`") == "See http://x.io/a:b:`c`"
def test_as_markdown_removes_a_directive_body_not_just_its_head():
"""A dangling indented body renders as a code block, the thing we avoid."""
from repowise.core.generation.page_generator.structural import as_markdown
out = as_markdown(
"Summary line.\n\n Longer prose.\n\n .. note::\n\n Internal only.\n\n More prose.\n"
)
assert "Internal only." not in out
assert "Longer prose." in out and "More prose." in out
def test_as_markdown_is_idempotent():
from repowise.core.generation.page_generator.structural import as_markdown
for src in (
"See :meth:`Store.get`.",
"Pass ``None``.",
"Fence:\n\n```py\nx=1\n```\n",
"Body.\n\n.. note:: hi\n",
):
once = as_markdown(src)
assert as_markdown(once) == once
# ---------------------------------------------------------------------------
# The concept page's own header
# ---------------------------------------------------------------------------
def _module_ctx(assembler, files):
from repowise.core.generation.context_assembler import FilePageContext
contexts = [
FilePageContext(
file_path=f,
language="python",
symbols=[],
docstring=None,
imports=[],
exports=[],
dependencies=[],
dependents=[],
pagerank_score=0.1,
betweenness_score=0.0,
is_entry_point=False,
community_id=None,
is_api_contract=False,
is_test=False,
parse_errors=[],
estimated_tokens=10,
)
for f in files
]
return assembler.assemble_module_page("Ingestion Pipeline", "python", contexts, None)
def test_module_page_leads_with_the_concept_title(generator):
"""The H1 is the group's name, and the directories sit under it.
A concept page covers several directories, so the old ``# Module: <path>``
heading had nothing honest to put after the colon. The title says what the
group is; the line beneath says where to go and look.
"""
ctx = _module_ctx(generator._assembler, ["src/ingest/read.py", "src/parse/ast.py"])
page = generator._stub_module_page(ctx, "src/ingest", "Ingestion Pipeline")
assert page.title == "Ingestion Pipeline"
assert page.content.startswith("# Ingestion Pipeline\n")
assert "Module:" not in page.content
assert "`src/ingest`" in page.content and "`src/parse`" in page.content
def test_module_page_of_root_files_says_so(generator):
"""Files at the repository root have no directory to name.
``PurePosixPath("setup.py").parent`` is ``"."``, and printing a bare dot
where a path belongs reads as a bug. Root-level files are a real case:
the grouper anchors a group there whenever a repository keeps code at the
top level.
"""
ctx = _module_ctx(generator._assembler, ["setup.py", "main.py"])
page = generator._stub_module_page(ctx, "root", "Project Entry Points")
assert "Repository root" in page.content
assert "`.`" not in page.content
# ---------------------------------------------------------------------------
# Localization (#1092). These pages are rendered from a template with no model
# in the loop, so the ``language`` setting reaches them through the label
# catalog or not at all.
# ---------------------------------------------------------------------------
def _file_ctx() -> FilePageContext:
return FilePageContext(
file_path="src/service/parser.py",
language="python",
docstring=None,
symbols=[
{
"name": "parse_file",
"kind": "function",
"visibility": "public",
"signature": "def parse_file(p: str) -> Parsed",
}
],
imports=[],
exports=[],
pagerank_score=0.0,
betweenness_score=0.0,
community_id=0,
dependents=["src/pipeline.py"],
dependencies=["src/models.py"],
is_api_contract=False,
is_entry_point=True,
is_test=False,
parse_errors=[],
estimated_tokens=0,
community_label="parsing",
kg_layer_name="ingestion",
kg_layer_role="parses source",
file_vocabulary="tokenizer visitor",
)
def _symbol_ctx() -> SymbolSpotlightContext:
return SymbolSpotlightContext(
symbol_name="parse_file",
qualified_name="parser.ASTParser.parse_file",
kind="method",
signature="def parse_file(self, fi, src) -> ParsedFile",
docstring=None,
file_path="src/parser.py",
decorators=["@lru_cache"],
is_async=True,
complexity_estimate=7,
callers=["src/pipeline.py"],
source_body="def parse_file(self):\n return ...",
)
def _scc_ctx() -> SccPageContext:
return SccPageContext(
scc_id="scc-001",
files=["src/a.py", "src/b.py"],
cycle_description="",
total_symbols=2,
member_symbols=[{"file_path": "src/a.py", "symbols": [{"name": "f", "signature": ""}]}],
cross_imports=[{"from": "src/a.py", "to": "src/b.py"}],
)
def test_file_page_renders_german_headings_and_prose(german_generator):
ctx = _file_ctx()
page = german_generator._structural_page(
page_type="file_page",
target_path=ctx.file_path,
title=structural_page_title("de", "file_page", ctx.file_path),
template="file_page.j2",
ctx=ctx,
)
assert page.title == "Datei: src/service/parser.py"
for heading in (
"## Überblick",
"## Öffentliche API",
"## Abhängigkeiten",
"## Wird verwendet von",
"## Fragen, die diese Seite beantwortet",
):
assert heading in page.content, heading
# The file vocabulary is embedded from metadata, never rendered.
assert "## Im Code" not in page.content
assert "`parser.py` definiert `parse_file`." in page.content
assert "Die Datei wird von `src/pipeline.py` importiert." in page.content
assert "Die Datei gehört zur Schicht ingestion." in page.content
assert "Die Datei ist ein Einstiegspunkt." in page.content
# Identifiers are never translated, in any language.
assert "`src/service/parser.py`" in page.content
assert "`parse_file`" in page.content
assert "| `src/models.py`" not in page.content and "- `src/models.py`" in page.content
def test_symbol_spotlight_renders_german(german_generator):
page = german_generator._structural_symbol_spotlight(
_symbol_ctx(),
"src/parser.py::parse_file",
structural_page_title("de", "symbol_spotlight", "parser.ASTParser.parse_file"),
)
assert page.title == "Symbol: parser.ASTParser.parse_file"
assert "**Art:** method (asynchron)" in page.content
assert "## Wo es verwendet wird" in page.content
assert "## Implementierung" in page.content
assert "keine bestätigten Aufrufstellen" in page.content
def test_infra_and_api_contract_pages_render_german(german_generator):
infra = german_generator._structural_infra_page(
InfraPageContext(
file_path="Dockerfile", language="dockerfile", raw_content="FROM x\n", targets=["build"]
),
"Dockerfile",
structural_page_title("de", "infra_page", "Dockerfile"),
)
assert infra.title == "Infrastruktur: Dockerfile"
assert infra.content.startswith("# Infrastruktur: Dockerfile")
assert "## Deklarierte Ziele" in infra.content
assert "Sie deklariert 1 benanntes Ziel, unten aufgeführt." in infra.content
assert "## Quelltext" in infra.content
api = german_generator._structural_api_contract(
ApiContractContext(
file_path="api/routes.py",
language="python",
raw_content="",
endpoints=["def create() -> Response"],
schemas=["Payload"],
),
"api/routes.py",
structural_page_title("de", "api_contract", "api/routes.py"),
)
assert api.title == "API-Vertrag: api/routes.py"
assert "## Operationen" in api.content
assert "## Typen" in api.content
assert "1 aufrufbare Operation und 1 Typ" in api.content
def test_scc_page_renders_german(german_generator):
page = german_generator._structural_scc_page(
_scc_ctx(), "scc-001", structural_page_title("de", "scc_page", "scc-001")
)
assert page.title == "Zyklische Abhängigkeit: scc-001"
assert "**Zyklus-ID:** `scc-001`" in page.content
assert "## Dateien im Zyklus" in page.content
assert "## Die Schleife" in page.content
assert "**Symbole insgesamt im Zyklus:** 2" in page.content
def test_scc_page_starts_at_its_heading(generator):
"""A stray newline ahead of the heading is stripped after the page was
already streamed to the store, so every SCC page was written twice and
archived a version nobody made."""
from repowise.core.generation.mermaid_safety import sanitize_pages
page = generator._structural_scc_page(
_scc_ctx(), "scc-001", structural_page_title("en", "scc_page", "scc-001")
)
assert page.content.startswith("# ")
assert sanitize_pages([page]) == 0
def test_the_footer_is_localized_on_every_structural_page(german_generator):
ctx = _file_ctx()
page = german_generator._structural_page(
page_type="file_page",
target_path=ctx.file_path,
title="x",
template="file_page.j2",
ctx=ctx,
)
assert "Erstellt aus geparstem Code" in page.content
assert "Generated from parsed code" not in page.content
def test_an_unsupported_language_renders_exactly_what_english_does(generator, klingon_generator):
"""The acceptance criterion from #1092: never a partial mix, never a raise."""
ctx = _file_ctx()
english = generator._structural_page(
page_type="file_page",
target_path=ctx.file_path,
title="x",
template="file_page.j2",
ctx=ctx,
)
klingon = klingon_generator._structural_page(
page_type="file_page",
target_path=ctx.file_path,
title="x",
template="file_page.j2",
ctx=ctx,
)
assert klingon.content == english.content
assert structural_page_title("tlh", "file_page", "src/a.py") == structural_page_title(
None, "file_page", "src/a.py"
)
def test_a_template_change_re_renders_structural_pages_for_the_right_reason(
generator, german_generator
):
"""Language is folded into the structural fingerprint, so switching it
marks the page as rendered by an older configuration and ``update``
redoes it. Asserted here so a future reuse-hash change cannot quietly make
a German repository keep its English pages."""
english_key = generator._structural_content_hash("file_page.j2", "subject-hash")
german_key = german_generator._structural_content_hash("file_page.j2", "subject-hash")
assert english_key and german_key
assert english_key != german_key