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.

19.6 KB
Raw Blame
"""Unit tests for BaseEditorFileGenerator marker-merge logic."""

from __future__ import annotations

import pytest

from repowise.core.generation.editor_files.base import BaseEditorFileGenerator
from repowise.core.generation.editor_files.data import (
    CodeHealthBlock,
    EditorFileData,
    HotspotFile,
)
from repowise.core.persistence.crud.analysis.performance import PerformanceHeadline

# ---------------------------------------------------------------------------
# Minimal concrete subclass for testing
# ---------------------------------------------------------------------------


class _TestGenerator(BaseEditorFileGenerator):
    filename = "TEST.md"
    marker_tag = "REPOWISE"
    template_name = "claude_md.j2"
    user_placeholder = "# TEST.md\n\n<!-- user content here -->\n"


def _minimal_data() -> EditorFileData:
    return EditorFileData(
        repo_name="test-repo",
        indexed_at="2026-03-28",
        indexed_commit="a1b2c3d",
        architecture_summary="A test repo.",
    )


# ---------------------------------------------------------------------------
# Tests
# ---------------------------------------------------------------------------


@pytest.fixture
def gen():
    return _TestGenerator()


def test_render_returns_non_empty_string(gen):
    data = _minimal_data()
    result = gen.render(data)
    assert isinstance(result, str)
    assert len(result) > 0


def test_render_never_references_repowise_repo_paths(gen):
    # The generated file lands in USERS' repos — a `docs/layers/CODE_HEALTH.md`-style
    # reference points at a file that only exists in the repowise repo itself.

    data = _full_health(_health_block(6.4))
    result = gen.render(data)
    for repo_relative in ("docs/layers/CODE_HEALTH.md", "docs/agent/MCP_TOOLS.md", "docs/agent/DISTILL.md"):
        assert repo_relative not in result


def test_render_contains_repo_name(gen):
    data = _minimal_data()
    result = gen.render(data)
    assert "test-repo" in result


def test_render_names_only_what_a_degraded_index_lacks(gen):
    import dataclasses

    data = dataclasses.replace(
        _minimal_data(),
        index_scope={
            "run_mode": "fast",
            "content_provenance": "model",
            "git_tier": "essential",
            "file_pages": {"eligible": 5, "generated": 0, "omitted": 5},
            "analysis": {"unavailable": [], "skipped": ["generation"]},
            "upgrade": {"status": "pending"},
        },
    )
    result = gen.render(data)
    assert "Scope: essential Git history only · model upgrade pending." in result
    # MCP serves the full scope in `_meta` and on get_overview; this file is
    # read into every session, so it names the gaps only.
    assert "eligible file pages omitted" not in result
    assert "fast index" not in result
    assert '"eligible": 5' not in result
    assert "repowise update --full" in result


def test_a_complete_index_has_no_scope_line(gen):
    import dataclasses

    data = dataclasses.replace(
        _minimal_data(),
        index_scope={
            "run_mode": "standard",
            "content_provenance": "model",
            "git_tier": "full",
            "file_pages": {"eligible": 300, "generated": 48, "omitted": 252},
            "upgrade": {"status": "complete"},
            "search": {"full_text": "available", "semantic": "available"},
        },
    )
    result = gen.render(data)
    assert "Scope:" not in result
    assert "Last indexed: 2026-03-28 (commit a1b2c3d).\n" in result


_KEYLESS_SCOPE = {
    "run_mode": "standard",
    "content_provenance": "template",
    "git_tier": "full",
    "file_pages": {"eligible": 28, "generated": 25, "omitted": 3},
    "upgrade": {"status": "pending"},
    "provider": {"embedder": "mock", "model_cost_possible": False},
    "search": {"full_text": "available", "semantic": "unavailable"},
}
_KEYED_SCOPE = {
    **_KEYLESS_SCOPE,
    "content_provenance": "model",
    "upgrade": {"status": "resumable"},
    "provider": {"embedder": "openai", "model_cost_possible": True},
    "search": {"full_text": "available", "semantic": "available"},
}
_KEYLESS_BULLET = "**No model on this index.**"


@pytest.fixture(params=["claude_md.j2", "agents_md.j2"])
def any_gen(request):
    class _Gen(_TestGenerator):
        template_name = request.param

    return _Gen()


def _scoped(scope: dict) -> EditorFileData:
    import dataclasses

    return dataclasses.replace(_minimal_data(), avg_confidence=1.0, index_scope=scope)


def test_keyless_index_gets_keyless_steering(any_gen):
    result = any_gen.render(_scoped(_KEYLESS_SCOPE))
    assert _KEYLESS_BULLET in result
    # Template pages store confidence 1.0, so the figure would read as 100%.
    assert "Confidence:" not in result
    assert "(commit a1b2c3d).\nScope: Built from code (no model, full-text search)." in result
    # A built-from-code index is already full: `--full` has nothing to add.
    assert "repowise update --full" not in result
    assert "[fts]` only has no semantic agreement" not in result
    assert 'Cite `confidence: "high"`' not in result
    assert "`degraded` means no prose; `confidence` rates the evidence" in result
    assert "provider key and `repowise generate`" in result


def test_index_only_keyless_names_the_fast_to_full_command(any_gen):
    result = any_gen.render(_scoped({**_KEYLESS_SCOPE, "content_provenance": "none"}))
    assert "provider key and `repowise update --full`" in result
    assert "Scope: Index only (no documentation, full-text search)." in result


def test_keyed_index_keeps_model_guidance(any_gen):
    result = any_gen.render(_scoped(_KEYED_SCOPE))
    assert _KEYLESS_BULLET not in result
    # The header carries the date and commit only.
    assert "Confidence:" not in result
    assert "Scope: model upgrade resumable." in result
    assert "repowise update --full" in result
    assert "[fts]` only has no semantic agreement" in result
    assert 'Cite `confidence: "high"`' in result


@pytest.mark.parametrize("scope", [_KEYLESS_SCOPE, _KEYED_SCOPE], ids=["keyless", "keyed"])
@pytest.mark.parametrize("upgrade", ["pending", "complete"])
def test_render_has_no_trailing_whitespace_or_double_blank_lines(any_gen, scope, upgrade):
    result = any_gen.render(_scoped({**scope, "upgrade": {"status": upgrade}}))
    assert not [line for line in result.splitlines() if line != line.rstrip()]
    assert "\n\n\n" not in result


def test_legacy_empty_scope_renders_keyed_text_and_no_scope_block(any_gen):
    data = _scoped({})
    assert data.keyless is False
    result = any_gen.render(data)
    assert "Scope:" not in result
    assert _KEYLESS_BULLET not in result
    assert "[fts]` only has no semantic agreement" in result
    assert 'Cite `confidence: "high"`' in result


def test_stale_warning_guidance_points_at_served_files(any_gen):
    import dataclasses

    # In-response warnings carry this guidance, so only the full section repeats it.
    lean = any_gen.render(_minimal_data())
    assert "_meta.stale_warning" not in lean
    full = any_gen.render(
        dataclasses.replace(_minimal_data(), sections=frozenset({"how_to_work_full"}))
    )
    assert "When `_meta.stale_warning` is set, Read the files that response served." in full
    assert "`repowise update --working-tree`" in full


def _health_block(
    maintainability_average: float | None,
    performance_average: float | None = None,
    performance_causes: PerformanceHeadline | None = None,
    performance_coverage_pct: float | None = None,
    band: str = "Good",
) -> CodeHealthBlock:
    return CodeHealthBlock(
        hotspot_health=5.0,
        average_health=7.5,
        band=band,
        worst_score=2.0,
        worst_path="src/bad.py",
        maintainability_average=maintainability_average,
        performance_average=performance_average,
        performance_causes=performance_causes,
        performance_coverage_pct=performance_coverage_pct,
    )


_FULL_HEALTH = frozenset({"code_health"})


def _full_health(block: CodeHealthBlock) -> EditorFileData:
    import dataclasses

    return dataclasses.replace(_minimal_data(), code_health=block, sections=_FULL_HEALTH)


def test_the_default_health_line_is_the_headline_and_worst_file(gen):
    import dataclasses

    block = dataclasses.replace(
        _health_block(
            6.4,
            performance_average=9.2,
            performance_causes=PerformanceHeadline(1, 7, 12, 2.5),
        ),
        fix_first=[{"title": "Split f", "where": "src/bad.py:3", "why": "long"}],
    )
    result = gen.render(dataclasses.replace(_minimal_data(), code_health=block))
    assert "### Code health\n7.5/10 avg (Good), worst `src/bad.py` at 2.0/10." in result
    for detail in ("hotspot health", "maintainability", "worth fixing now", "Fix first"):
        assert detail not in result.split("### Tools")[0]


def test_fix_first_is_opt_in(gen):
    import dataclasses

    block = dataclasses.replace(
        _health_block(6.4), fix_first=[{"title": "Split f", "where": "src/bad.py:3", "why": "long"}]
    )
    data = dataclasses.replace(
        _minimal_data(), code_health=block, sections=frozenset({"health", "fix_first"})
    )
    assert "- Split f (`src/bad.py:3`): long" in gen.render(data)


def test_the_headline_reads_the_same_direction_as_every_other_surface(gen):
    """A score out of ten beside a risk-shaped label reads inverted.

    The CLI prints "Code health: 7.5/10 [Good]". The generated file is the one
    an agent reads without a page around it, so it carries the same label and
    the same band word rather than a bare number.
    """

    data = _full_health(_health_block(6.4))
    result = gen.render(data)
    assert "code health 7.5/10 avg (Good)" in result
    assert "defect risk 7.5" not in result


def test_the_headline_drops_the_band_when_it_is_unknown(gen):

    data = _full_health(_health_block(6.4, band=""))
    result = gen.render(data)
    assert "code health 7.5/10 avg," in result
    assert "avg ()" not in result


def test_the_headline_states_the_analysed_share(gen):
    import dataclasses

    block = dataclasses.replace(
        _health_block(6.4, band=""), analysed_note="analysed 4 of 435 code files"
    )
    result = gen.render(_full_health(block))
    assert "code health 7.5/10 avg (analysed 4 of 435 code files)," in result
    block = dataclasses.replace(block, band="Good")
    result = gen.render(_full_health(block))
    assert "avg (Good, analysed 4 of 435 code files)," in result


def test_render_surfaces_maintainability_when_present(gen):

    data = _full_health(_health_block(6.4))
    result = gen.render(data)
    assert "maintainability 6.4/10" in result


def test_render_omits_maintainability_when_unmeasured(gen):

    data = _full_health(_health_block(None))
    result = gen.render(data)
    # Defect-risk headline still renders; the maintainability clause is
    # suppressed (the word still appears in the static tool table, so match
    # the clause shape, not the bare word).
    assert "hotspot health" in result
    assert "· maintainability" not in result


def test_render_surfaces_performance_when_present(gen):
    import dataclasses

    data = dataclasses.replace(
        _minimal_data(),
        code_health=_health_block(
            6.4,
            performance_average=9.2,
            performance_causes=PerformanceHeadline(1, 7, 12, 2.5),
            performance_coverage_pct=88.0,
        ),
        sections=_FULL_HEALTH,
    )
    result = gen.render(data)
    # Leads with the causes worth fixing now, production and overall as context;
    # the bounded [9,10] average and coverage % are deliberately not rendered.
    assert (
        "performance 1 cause worth fixing now (7 open in production code, 12 overall)" in result
    )
    assert "N+1" not in result


def test_render_omits_performance_when_unmeasured(gen):

    data = _full_health(_health_block(6.4))
    result = gen.render(data)
    # Maintainability still renders; the performance clause is suppressed.
    assert "maintainability 6.4/10" in result
    assert "worth fixing now" not in result


def test_write_creates_new_file(gen, tmp_path):
    data = _minimal_data()
    written = gen.write(tmp_path, data)
    assert written.exists()
    content = written.read_text(encoding="utf-8")
    assert "<!-- REPOWISE:START" in content
    assert "<!-- REPOWISE:END -->" in content
    assert "<!-- user content here -->" in content  # placeholder present


def test_write_new_file_has_correct_structure(gen, tmp_path):
    data = _minimal_data()
    gen.write(tmp_path, data)
    content = (tmp_path / "TEST.md").read_text(encoding="utf-8")
    start_idx = content.index("<!-- REPOWISE:START")
    end_idx = content.index("<!-- REPOWISE:END -->")
    assert start_idx < end_idx
    # User placeholder is BEFORE the markers
    placeholder_idx = content.index("<!-- user content here -->")
    assert placeholder_idx < start_idx


def test_write_preserves_user_content_when_no_markers(gen, tmp_path):
    target = tmp_path / "TEST.md"
    user_content = "# My Project\n\nDo not touch this content!\n"
    target.write_text(user_content, encoding="utf-8")

    data = _minimal_data()
    gen.write(tmp_path, data)

    content = target.read_text(encoding="utf-8")
    assert "Do not touch this content!" in content
    assert "<!-- REPOWISE:START" in content


def test_write_appends_when_no_markers(gen, tmp_path):
    target = tmp_path / "TEST.md"
    target.write_text("# Existing\n\nsome content", encoding="utf-8")

    gen.write(tmp_path, _minimal_data())
    content = target.read_text(encoding="utf-8")

    # Existing content is BEFORE the markers
    existing_idx = content.index("# Existing")
    marker_idx = content.index("<!-- REPOWISE:START")
    assert existing_idx < marker_idx


def test_write_replaces_between_markers(gen, tmp_path):
    marker_start = gen.MARKER_START_FMT.format(tag=gen.marker_tag)
    marker_end = gen.MARKER_END_FMT.format(tag=gen.marker_tag)
    target = tmp_path / "TEST.md"
    old_content = (
        "# My notes\n\nUser section.\n\n"
        f"{marker_start}\n## Old Content\nOld managed content.\n{marker_end}\n"
    )
    target.write_text(old_content, encoding="utf-8")

    gen.write(tmp_path, _minimal_data())
    new_content = target.read_text(encoding="utf-8")

    assert "User section." in new_content
    assert "Old managed content." not in new_content
    assert "test-repo" in new_content  # new managed content present


@pytest.mark.parametrize("title", [r"C:\Users\x", r"C:\new\tools", r"\1", r"\g<0>"])
@pytest.mark.parametrize("existing_kind", ["marked", "unmarked", "absent"])
@pytest.mark.parametrize("method", ["write", "render_full"])
def test_managed_rewrite_preserves_literal_backslashes(
    any_gen, tmp_path, title, existing_kind, method
):
    from dataclasses import replace

    from repowise.core.generation.editor_files.data import DecisionSummary

    data = replace(
        _minimal_data(),
        decisions=[DecisionSummary(title=title, status="active", rationale="Keep literal text.")],
    )
    start = any_gen.MARKER_START_FMT.format(tag=any_gen.marker_tag)
    end = any_gen.MARKER_END_FMT.format(tag=any_gen.marker_tag)
    prefix = "# User notes\nKeep this.\n\n"
    suffix = "\n\nUser footer.\n"
    target = tmp_path / any_gen.filename
    rendered = any_gen.render(data)
    assert title in rendered
    wrapped = f"{start}\n{rendered}\n{end}"
    if existing_kind == "marked":
        target.write_text(f"{prefix}{start}\nold managed text\n{end}{suffix}", encoding="utf-8")
        expected = prefix + wrapped + suffix
    elif existing_kind == "unmarked":
        target.write_text(prefix, encoding="utf-8")
        expected = prefix.rstrip() + "\n\n" + wrapped + "\n"
    else:
        expected = any_gen.user_placeholder + "\n" + wrapped + "\n"

    result = getattr(any_gen, method)(tmp_path, data)
    actual = result.read_text(encoding="utf-8") if method == "write" else result
    assert actual == expected
    any_gen.write(tmp_path, data)
    assert target.read_text(encoding="utf-8") == expected
    assert any_gen.render_full(tmp_path, data) == expected
    any_gen.write(tmp_path, data)
    assert target.read_text(encoding="utf-8") == expected


def test_write_replaces_only_managed_section(gen, tmp_path):
    marker_start = gen.MARKER_START_FMT.format(tag=gen.marker_tag)
    marker_end = gen.MARKER_END_FMT.format(tag=gen.marker_tag)
    target = tmp_path / "TEST.md"
    target.write_text(
        f"# User notes\n\nKeep this.\n\n{marker_start}\nold\n{marker_end}\n",
        encoding="utf-8",
    )

    gen.write(tmp_path, _minimal_data())
    content = target.read_text(encoding="utf-8")

    assert "Keep this." in content
    assert content.count("<!-- REPOWISE:START") == 1
    assert content.count("<!-- REPOWISE:END -->") == 1


def test_write_is_idempotent(gen, tmp_path):
    data = _minimal_data()
    gen.write(tmp_path, data)
    first = (tmp_path / "TEST.md").read_text(encoding="utf-8")

    gen.write(tmp_path, data)
    second = (tmp_path / "TEST.md").read_text(encoding="utf-8")

    assert first == second


def test_write_returns_path(gen, tmp_path):
    result = gen.write(tmp_path, _minimal_data())
    assert result == tmp_path / "TEST.md"


def test_render_full_matches_write_output(gen, tmp_path):
    data = _minimal_data()
    preview = gen.render_full(tmp_path, data)
    gen.write(tmp_path, data)
    written = (tmp_path / "TEST.md").read_text(encoding="utf-8")
    assert preview == written


# ---------------------------------------------------------------------------
# Attention-list section: fix history leads, churn is the fallback
# ---------------------------------------------------------------------------


def _hotspot(path: str, **kw) -> HotspotFile:
    base = {"churn_percentile": 99.0, "commit_count_90d": 28, "owner": None}
    return HotspotFile(path=path, **{**base, **kw})


def test_render_hotspot_section_no_longer_claims_to_rank_by_churn(gen):
    # The header used to read "high churn" while telling the agent to call
    # get_risk, a defect tool. The list and its own instruction disagreed.
    import dataclasses

    data = dataclasses.replace(_minimal_data(), hotspots=[_hotspot("src/a.py")])
    result = gen.render(data)
    assert "high churn" not in result
    assert "get_risk" in result


def test_render_hotspot_row_leads_with_fix_history(gen):
    import dataclasses

    data = dataclasses.replace(
        _minimal_data(),
        hotspots=[_hotspot("src/a.py", fix_count=5, bug_magnet=True, last_fix_date="2026-03-14")],
    )
    result = gen.render(data)
    assert "5 bug fixes in 6 months, last fix 2026-03-14 (bug magnet); 28 commits/90d" in result


def test_render_hotspot_row_singularizes_one_fix(gen):
    import dataclasses

    data = dataclasses.replace(
        _minimal_data(),
        hotspots=[_hotspot("src/a.py", fix_count=1, last_fix_date="2026-03-27")],
    )
    result = gen.render(data)
    assert "1 bug fix in 6 months, last fix 2026-03-27" in result
    assert "1 bug fixes" not in result


def test_render_hotspot_row_falls_back_to_churn_without_fix_history(gen):
    # A repo whose commit messages carry no fix convention has zero fix mass
    # everywhere. The section must still render, on churn alone.
    import dataclasses

    data = dataclasses.replace(_minimal_data(), hotspots=[_hotspot("src/a.py")])
    result = gen.render(data)
    assert "- `src/a.py`: 28 commits/90d" in result
    assert "bug fix" not in result


def test_render_never_shows_a_fix_count_without_its_age(gen):
    # The recency contract: a count with no timestamp reads as an accusation
    # about 2019, so an unanchored count degrades to the churn row.
    import dataclasses

    data = dataclasses.replace(
        _minimal_data(),
        hotspots=[_hotspot("src/a.py", fix_count=9, bug_magnet=True, last_fix_date=None)],
    )
    result = gen.render(data)
    assert "9 bug fixes" not in result
    assert "bug magnet" not in result
    assert "28 commits/90d" in result