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.4 KB
Raw Blame
"""Unit tests for the in-code rationale miner (`_code_rationale`).

The miner recovers the "why" that lives in source comments — the unbiased
A/B's one durable loss (task T4): rationale in a code comment that neither
get_why's decision/git search nor get_answer's wiki retrieval can find.
"""

from __future__ import annotations

import subprocess
from pathlib import Path

from repowise.server.mcp_server._code_rationale import (
    _salient_numbers,
    extract_comment_blocks,
    grep_comment_candidates,
    mine_rationale,
)

PY_SOURCE = '''import os

# We set PYTHONIOENCODING here because the Windows console uses cp1252
# and the checkmark glyph crashes the CLI otherwise.
ENCODING = "utf-8"

def divide(a, b):
    denom = b or 1  # fall back to 1 to avoid a divide-by-zero downstream
    return a / denom

# TODO: refactor this later
LIMIT = 50

class Bar:
    """Bar exists instead of a dict because callers need attribute access."""
    pass

URL = "https://example.com/path"  # not a comment, lives in a string
'''

TS_SOURCE = """import { x } from 'y';

// We debounce at 200ms rather than 100ms because the API rate-limits
// bursts and a tighter window trips the limiter.
const DEBOUNCE = 200;

/* This block is a workaround for a Safari layout bug: flex-basis must be
   set explicitly or the panel collapses. */
function layout() {}

// plain label
const z = 1;
"""


def _write(tmp_path, name, content):
    p = tmp_path / name
    p.write_text(content, encoding="utf-8")
    return p


def test_extract_coalesces_multiline_python_comment():
    # Shared core tokenizer returns CommentBlock dataclasses; trailing inline
    # comments are recall-only (include_trailing=True), matching mine_rationale.
    blocks = extract_comment_blocks(PY_SOURCE, "py", include_trailing=True)
    texts = [b.text for b in blocks]
    # The two-line # comment becomes one block spanning lines 3-4.
    enc = next(b for b in blocks if "PYTHONIOENCODING" in b.text)
    assert enc.start_line == 3 and enc.end_line == 4
    assert "checkmark glyph crashes" in enc.text
    # Trailing inline comment recovered.
    assert any("divide-by-zero" in t for t in texts)
    # Docstring recovered.
    assert any("attribute access" in t for t in texts)


def test_extract_handles_c_style_block_and_line_comments():
    blocks = extract_comment_blocks(TS_SOURCE, "ts")
    texts = [b.text for b in blocks]
    assert any("debounce" in t.lower() and "rate-limits" in t.lower() for t in texts)
    assert any("workaround for a Safari layout bug" in t for t in texts)


def test_mine_ranks_marker_plus_query_overlap_first(tmp_path):
    _write(tmp_path, "mod.py", PY_SOURCE)
    out = mine_rationale(str(tmp_path), ["mod.py"], "why PYTHONIOENCODING windows console")
    assert out, "expected at least one rationale block"
    top = out[0]
    assert "PYTHONIOENCODING" in top["comment"]
    assert top["lines"] == [3, 4]
    assert "window" in top["matched_terms"]


def test_mine_path_mode_returns_marker_comments_without_query(tmp_path):
    _write(tmp_path, "mod.py", PY_SOURCE)
    out = mine_rationale(str(tmp_path), ["mod.py"], None)
    comments = " ".join(r["comment"] for r in out)
    # All three rationale-marker comments surface...
    assert "PYTHONIOENCODING" in comments
    assert "divide-by-zero" in comments
    assert "attribute access" in comments
    # ...but the bare "TODO: refactor" label (no rationale marker) does not.
    assert "refactor this later" not in comments


def test_mine_drops_non_rationale_comments_under_query(tmp_path):
    _write(tmp_path, "mod.ts", TS_SOURCE)
    out = mine_rationale(str(tmp_path), ["mod.ts"], "debounce rate limit")
    assert any("debounce" in r["comment"].lower() for r in out)
    # "plain label" has neither a marker nor query overlap.
    assert all("plain label" not in r["comment"] for r in out)


def test_mine_url_in_string_is_not_mistaken_for_comment(tmp_path):
    _write(tmp_path, "mod.py", PY_SOURCE)
    out = mine_rationale(str(tmp_path), ["mod.py"], None)
    assert all("example.com" not in r["comment"] for r in out)


def test_mine_near_line_boost_prefers_comment_by_named_symbol(tmp_path):
    src = (
        "# generic note because of history\n" * 1
        + "x = 1\n" * 50
        + "# special-cased because the loader needs it early\n"
        + "def loader():\n    pass\n"
    )
    _write(tmp_path, "m.py", src)
    near = {"m.py": 52}  # the loader comment sits at ~line 52
    out = mine_rationale(str(tmp_path), ["m.py"], "loader", near_lines=near)
    assert out[0]["lines"][0] >= 50  # the near-line comment wins the tie


def test_mine_is_bounded_and_safe(tmp_path):
    # Path escape: a file outside the root is refused, not read.
    _write(tmp_path, "mod.py", PY_SOURCE)
    assert mine_rationale(str(tmp_path), ["../../etc/passwd"], None) == []
    # No repo root -> empty, no raise.
    assert mine_rationale(None, ["mod.py"], "x") == []
    # Empty file list → empty.
    assert mine_rationale(str(tmp_path), [], "x") == []


def test_mine_ranks_the_marker_block_over_a_generic_docstring(tmp_path):
    """Generic query terms (lines/source/one) drag in plain docstrings; the
    marked block that carries the question ranks first, and an unmarked one
    carrying too little of its weight is dropped."""
    src = (
        '"""Slice text to source lines; one indexed symbol per call."""\n'
        "MAX = 1\n"
        "# The source line cap is 600 because round-trip count, not payload\n"
        "# size, dominates agent token cost.\n"
        "LIMIT = 600\n"
        '"""Read the source of a file."""\n'
    )
    p = tmp_path / "s.py"
    p.write_text(src, encoding="utf-8")
    out = mine_rationale(str(tmp_path), ["s.py"], "why source lines cap one")
    assert out, "expected the rationale block to survive"
    assert "round-trip count" in out[0]["comment"]
    assert all("Read the source" not in r["comment"] for r in out)


def test_mine_keeps_an_unmarked_block_carrying_the_question_beside_marked_ones(tmp_path):
    """A docstring stating the behaviour asked about has no causal connective;
    it must not be dropped because some other block in the file has one."""
    src = (
        "# Tiers run in order because the earlier tier is cheaper.\n"
        "TIERS = 3\n"
        "def narrow(rep, call):\n"
        '    """A tie between overloads keeps the representative."""\n'
        "    return rep\n"
    )
    _write(tmp_path, "r.py", src)
    out = mine_rationale(str(tmp_path), ["r.py"], "why does an overload tie keep the representative")
    assert out and "keeps the representative" in out[0]["comment"]


def test_mine_matches_whole_words_not_substrings(tmp_path):
    """``tie`` is not in "tier" or "entire"."""
    src = (
        "# The entire tier is skipped because it is slow.\n"
        "X = 1\n"
        "# A tie is broken by name because the order must be stable.\n"
        "Y = 2\n"
    )
    _write(tmp_path, "t.py", src)
    out = mine_rationale(str(tmp_path), ["t.py"], "why is a tie broken")
    assert [r["lines"][0] for r in out] == [3]


def test_mine_lone_number_does_not_qualify_a_block(tmp_path):
    """A number counts beside a content term, never on its own."""
    src = (
        "# Strategy 3 runs last because it is the most expensive.\n"
        "X = 1\n"
        "# Java is left out because its bare-call pattern also matches fields.\n"
        "LANGS = ()\n"
    )
    _write(tmp_path, "n.py", src)
    out = mine_rationale(str(tmp_path), ["n.py"], "why is java excluded after tier 3")
    assert [r["lines"][0] for r in out] == [3]


def test_mine_anchors_a_block_to_the_symbol_the_query_names(tmp_path):
    """The comment above a constant never repeats its name; naming it in the
    question ranks that comment over one sharing only the prose words."""
    src = (
        "# Checked in order because java is the common case.\n"
        "ORDER = ()\n"
        "\n"
        "# Kotlin is here and java is not because its receivers differ.\n"
        "_INHERITED_LANGUAGES = frozenset()\n"
    )
    _write(tmp_path, "a.py", src)
    out = mine_rationale(str(tmp_path), ["a.py"], "why is java not in _INHERITED_LANGUAGES")
    assert out[0]["lines"][0] == 4


def test_mine_does_not_anchor_a_comment_to_a_call_site(tmp_path):
    """A line that only calls the named symbol lends nothing: the comment below
    it is about something else, and carries none of the question's words."""
    src = (
        "r = _narrow_overload(1)\n"
        "# never retry here, it is unsafe\n"
        "x = 2\n"
    )
    _write(tmp_path, "c.py", src)
    out = mine_rationale(str(tmp_path), ["c.py"], "why does _narrow_overload narrow first")
    assert out == []


def test_mine_anchored_block_still_needs_a_word_of_its_own(tmp_path):
    """The declaration lends its words, but a marked block must carry one
    question word itself."""
    src = (
        "# never retry here, it is unsafe\n"
        "def _narrow_overload(rep):\n"
        "    return rep\n"
    )
    _write(tmp_path, "d.py", src)
    out = mine_rationale(str(tmp_path), ["d.py"], "why does _narrow_overload narrow first")
    assert out == []


def test_mine_keeps_term_only_blocks_when_no_marker_exists(tmp_path):
    """Recall fallback: if nothing carries a marker, strong term overlap still
    surfaces (so a marker-less but on-topic comment isn't lost)."""
    src = "# configures the source line buffer for one pass\nBUF = 1\n"
    p = tmp_path / "s.py"
    p.write_text(src, encoding="utf-8")
    out = mine_rationale(str(tmp_path), ["s.py"], "source line buffer pass")
    assert any("source line buffer" in r["comment"] for r in out)


def test_mine_caps_result_count(tmp_path):
    # Many rationale comments → result list is capped (<= _MAX_RESULTS=6).
    lines = [f"# reason {i}: we avoid path {i} because it deadlocks\n" for i in range(40)]
    _write(tmp_path, "big.py", "".join(lines))
    out = mine_rationale(str(tmp_path), ["big.py"], None)
    assert 0 < len(out) <= 6


# --- Number-aware scoring (concept anchoring, piece 1) ----------------------


def test_salient_numbers_extracts_whole_tokens():
    assert _salient_numbers("why is the caller list capped at 50") == ["50"]
    assert _salient_numbers("cap symbols at 40 not 600") == ["40", "600"]
    # No number, version-dotted ignored as one float token, no bare words.
    assert _salient_numbers("why is this limited") == []


def test_mine_number_disambiguates_two_caps(tmp_path):
    """The literal question number picks the right cap comment - the cap-40 vs
    cap-600 mis-rank the prototype surfaced: _content_terms drops '50', so
    without number scoring both 'because'-marked caps tie."""
    src = (
        "# The caller list cap is 50 because the median fan-in is 2.\n"
        "CALLER_CAP = 50\n"
        "# The source line cap is 600 because round-trip count dominates.\n"
        "SOURCE_CAP = 600\n"
    )
    _write(tmp_path, "s.py", src)
    out = mine_rationale(str(tmp_path), ["s.py"], "why is the caller list capped at 50")
    assert out
    assert "50" in out[0]["comment"] and "600" not in out[0]["comment"]
    assert "50" in out[0]["matched_terms"]


def test_mine_number_match_is_whole_token(tmp_path):
    """'40' must not match '400' / '0.40' - a substring match would re-introduce
    the very mis-rank number scoring exists to fix."""
    src = (
        "# We page in batches of 400 because the API rejects larger requests.\n"
        "BATCH = 400\n"
        "# The symbol cap is 40 because dense files flood the context window.\n"
        "SYMBOL_CAP = 40\n"
    )
    _write(tmp_path, "s.py", src)
    out = mine_rationale(str(tmp_path), ["s.py"], "why does it cap symbols at 40")
    assert out
    assert "40" in out[0]["comment"] and "400" not in out[0]["comment"]


def _git_repo(tmp_path: Path, files: dict[str, str]) -> Path:
    """Create a committed git repo so ``git grep`` (tracked-files-only) works."""
    for name, content in files.items():
        p = tmp_path / name
        p.parent.mkdir(parents=True, exist_ok=True)
        p.write_text(content, encoding="utf-8")
    subprocess.run(["git", "init", "-q"], cwd=tmp_path, check=True)
    subprocess.run(["git", "add", "-A"], cwd=tmp_path, check=True)
    subprocess.run(
        [
            "git",
            "-c",
            "[email protected]",
            "-c",
            "user.name=t",
            "commit",
            "-qm",
            "init",
        ],
        cwd=tmp_path,
        check=True,
    )
    return tmp_path


_CALLER_CAP_FILES = {
    "enrichment.py": (
        "def neighbors():\n"
        "    # Cap the caller list at 50 because the median fan-in is 2 and\n"
        "    # 50 covers 99.5% of symbols in a single call.\n"
        "    limit = 50\n"
    ),
    # A boilerplate call site: number, but no rationale comment-leading line.
    "pager.py": "PAGE = 50  # default page size\n",
    "other.py": "# unrelated note about caching\nX = 1\n",
}


def test_grep_comment_candidates_ranks_number_bearing_file(tmp_path):
    repo = _git_repo(tmp_path, _CALLER_CAP_FILES)
    cands = grep_comment_candidates(str(repo), "why is the caller list capped at 50")
    assert cands, "expected at least one grep candidate"
    # The file whose COMMENT explains the 50 wins; the boilerplate call site
    # (trailing comment, not comment-leading) is not matched.
    assert cands[0] == "enrichment.py"
    assert "pager.py" not in cands


def test_grep_comment_candidates_skips_gitignored_file(tmp_path):
    """A gitignored path must not be returned as a rationale candidate.

    ``git grep`` scans tracked files, but a file force-added before it was
    gitignored stays tracked (this is exactly how a stale vendored copy leaks
    in). The compiled exclude spec must drop it while keeping the real file.
    """
    _RATIONALE = (
        "# The widget list cap is 77 because the median fan-in is small\n"
        "# and 77 covers nearly every widget in one call.\n"
        "LIMIT = 77\n"
    )
    (tmp_path / ".gitignore").write_text("stale/\n", encoding="utf-8")
    (tmp_path / "enrichment.py").write_text(_RATIONALE, encoding="utf-8")
    (tmp_path / "stale").mkdir()
    (tmp_path / "stale" / "leak.py").write_text(_RATIONALE, encoding="utf-8")
    subprocess.run(["git", "init", "-q"], cwd=tmp_path, check=True)
    subprocess.run(["git", "add", "enrichment.py", ".gitignore"], cwd=tmp_path, check=True)
    # Force-track the ignored copy so git grep can still see it.
    subprocess.run(["git", "add", "-f", "stale/leak.py"], cwd=tmp_path, check=True)
    subprocess.run(
        ["git", "-c", "[email protected]", "-c", "user.name=t", "commit", "-qm", "init"],
        cwd=tmp_path,
        check=True,
    )
    cands = grep_comment_candidates(str(tmp_path), "why is the widget list capped at 77")
    assert "enrichment.py" in cands
    assert "stale/leak.py" not in cands


def test_grep_comment_candidates_bounds_a_pasted_issue_body(tmp_path, monkeypatch):
    """A long issue body must not become an unbounded alternation or output."""
    from repowise.server.mcp_server import _code_rationale as cr

    repo = _git_repo(tmp_path, _CALLER_CAP_FILES)
    seen: list[list[str]] = []
    real_run = subprocess.run

    def spy(args, **kwargs):
        seen.append(list(args))
        return real_run(args, **kwargs)

    monkeypatch.setattr(cr.subprocess, "run", spy)
    filler = " ".join(f"longnoun{chr(97 + i % 26)}{chr(97 + i // 26)}" for i in range(60))
    numbers = " ".join(str(n) for n in range(100, 120))
    question = f"why is the caller list capped at 50 {filler} {numbers}"
    cands = grep_comment_candidates(str(repo), question)

    args = seen[0]
    pattern = args[args.index("-E") + 1]
    # Longest nouns are kept, so the 10-char filler crowds out "caller".
    assert pattern.count("longnoun") == 2 * cr._MAX_GREP_NOUNS
    assert "caller" not in pattern
    # The first numbers in question order: 50, 100, 101, 102.
    assert "102" in pattern and "103" not in pattern
    # Per-file counts, never one output line per matched source line.
    assert "-c" in args and "-n" not in args
    assert cands == []


def test_grep_comment_candidates_ranks_by_per_file_count(tmp_path):
    repo = _git_repo(
        tmp_path,
        {
            "one.py": "# caller cap 50\n",
            "three.py": "# caller cap 50\n# caller cap 50 again\n# caller 50 here\n",
        },
    )
    assert grep_comment_candidates(str(repo), "caller capped at 50") == ["three.py", "one.py"]


def test_grep_comment_candidates_needs_a_noun(tmp_path):
    # Numbers but no content noun (all stopwords) -> nothing to anchor on.
    repo = _git_repo(tmp_path, _CALLER_CAP_FILES)
    assert grep_comment_candidates(str(repo), "why is it at 50") == []
    # No repo root -> empty, no raise.
    assert grep_comment_candidates(None, "why is the caller list capped at 50") == []


# --- Concept anchoring hit injection (piece 3) ------------------------------


async def test_concept_anchor_injects_winner_as_dominant(tmp_path):
    from repowise.server.mcp_server.tool_answer.symbols import _concept_anchor_hits

    repo = _git_repo(tmp_path, _CALLER_CAP_FILES)
    # Retrieval missed enrichment.py - it led with the boilerplate pager file.
    hits = [
        {"target_path": "pager.py", "page_type": "file_page", "score": 2.0},
        {"target_path": "other.py", "page_type": "file_page", "score": 1.0},
    ]
    out = await _concept_anchor_hits(
        Path(str(repo)), "why is the caller list capped at 50", hits
    )
    assert out[0]["target_path"] == "enrichment.py"
    assert out[0]["_concept_anchored"] is True
    # Dominates the prior top so the dominance gate passes.
    assert out[0]["score"] > 2.0
    # The mined comment + its line are stashed for code_rationale surfacing.
    assert out[0]["_concept_near_line"] >= 1
    assert "50" in out[0]["_concept_rationale"]["comment"]


async def test_concept_anchor_skips_without_a_number(tmp_path):
    from repowise.server.mcp_server.tool_answer.symbols import _concept_anchor_hits

    repo = _git_repo(tmp_path, _CALLER_CAP_FILES)
    hits = [{"target_path": "pager.py", "page_type": "file_page", "score": 2.0}]
    out = await _concept_anchor_hits(
        Path(str(repo)), "why is the caller list capped", hits
    )
    assert all(not h.get("_concept_anchored") for h in out)


async def test_concept_anchor_skips_when_retrieval_already_led_with_winner(tmp_path):
    from repowise.server.mcp_server.tool_answer.symbols import _concept_anchor_hits

    repo = _git_repo(tmp_path, _CALLER_CAP_FILES)
    # Retrieval already ranked enrichment.py top - leave the confidence label to
    # the existing machinery; do not force it past the dominance gate.
    hits = [
        {"target_path": "enrichment.py", "page_type": "file_page", "score": 2.0},
        {"target_path": "other.py", "page_type": "file_page", "score": 1.95},
    ]
    out = await _concept_anchor_hits(
        Path(str(repo)), "why is the caller list capped at 50", hits
    )
    assert all(not h.get("_concept_anchored") for h in out)


def test_mine_drops_blocks_far_below_the_best_match(tmp_path):
    """A block clearing the term gate on generic vocabulary is not rationale."""
    _write(
        tmp_path,
        "strong.py",
        "# We project each call edge onto its two files because the graph keeps\n"
        "# symbols and files in separate layers.\nX = 1\n",
    )
    _write(
        tmp_path,
        "weak.py",
        "# Edges bow outward so they never cross a box.\nY = 2\n",
    )
    query = "why project call edge endpoints onto files graph layers symbols"
    out = mine_rationale(str(tmp_path), ["strong.py", "weak.py"], query)

    paths = {r["path"] for r in out}
    assert "strong.py" in paths
    assert "weak.py" not in paths