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.

25.1 KB
Raw Blame
"""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