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.

8.6 KB
Raw Blame
"""The drift pass end to end: report shape, cutoff, and the known defects."""

from __future__ import annotations

import pytest

from repowise.core.analysis.doc_drift import DocDriftAnalyzer, summarize_confidence
from repowise.core.analysis.doc_drift.constants import (
    DEFAULT_MIN_CONFIDENCE,
    DRIFT_ORIGIN_VALUES,
    HIGH_CONFIDENCE_THRESHOLD,
    ORIGIN_CONFIDENCE,
    REVIEW_CONFIDENCE_THRESHOLD,
)
from repowise.core.analysis.doc_drift.models import DriftKind, DriftVerdict


def _analyze(files: dict[str, str], config: dict | None = None):
    source_map = {k: v.encode("utf-8") for k, v in files.items()}
    return DocDriftAnalyzer("repo", source_map=source_map).analyze(config)


# ---------------------------------------------------------------------------
# The fourteen known defects, as fixtures
# ---------------------------------------------------------------------------


def test_module_became_a_package():
    """The single most common drift shape Phase 1 found.

    Four of the eleven real path findings are this: a module became a package
    and the prose still names the ``.py``.
    """
    report = _analyze(
        {
            "docs/a.md": "See `packages/core/ingestion/git_indexer.py` for this.\n",
            "packages/core/ingestion/git_indexer/__init__.py": "",
            "packages/core/ingestion/git_indexer/walker.py": "",
        }
    )
    assert report.total_findings == 1
    assert report.findings[0].kind is DriftKind.PATH
    assert report.findings[0].line_number == 1


def test_deleted_file_is_flagged():
    report = _analyze(
        {"docs/a.md": "See `src/persistence/vector.py`.\n", "src/persistence/store.py": ""}
    )
    assert report.total_findings == 1


def test_renamed_heading_leaves_the_inbound_link_behind():
    """All three real anchor findings are this shape."""
    report = _analyze(
        {
            "docs/CONTRIBUTING.md": "See [quickstart](../README.md#quickstart-under-5-minutes).\n",
            "README.md": "## Start in minutes (no API key)\n",
        }
    )
    anchors = [f for f in report.findings if f.kind is DriftKind.ANCHOR]
    assert len(anchors) == 1
    assert anchors[0].origin == "anchor_no_heading"


def test_a_correct_document_produces_nothing():
    report = _analyze(
        {
            "docs/a.md": "See `src/app.py` and [readme](../README.md#setup).\n",
            "README.md": "## Setup\n",
            "src/app.py": "",
        }
    )
    assert report.total_findings == 0
    assert report.verdict_summary[DriftVerdict.MISSING.value] == 0


# ---------------------------------------------------------------------------
# Report shape
# ---------------------------------------------------------------------------


def test_uncheckable_is_counted_not_hidden():
    """684 of 903 path references on this repo are uncheckable.

    Saying so is the difference between a detector and a noise generator.
    """
    report = _analyze({"docs/a.md": "Edit `CLAUDE.md` and `config.yaml`.\n", "src/x.py": ""})
    assert report.total_findings == 0
    assert report.verdict_summary[DriftVerdict.UNCHECKABLE.value] == 2
    assert report.references_checked == 2


def test_verdict_summary_covers_every_reference():
    report = _analyze(
        {
            "docs/a.md": "`src/app.py` `CLAUDE.md` `src/gone.py`\n",
            "src/app.py": "",
        }
    )
    assert sum(report.verdict_summary.values()) == report.references_checked


def test_historical_documents_are_not_scanned():
    report = _analyze({"CHANGELOG.md": "Removed `src/gone.py` in 1.0.\n", "src/a.py": ""})
    assert report.documents_scanned == 0
    assert report.total_findings == 0


def test_min_confidence_cutoff_and_hidden_counter():
    files = {"docs/tutorial.md": "Create `src/specs/mylang.py`.\n", "src/specs/real.py": ""}
    shown = _analyze(files)
    assert shown.total_findings == 1
    assert shown.hidden_below_threshold == 0

    hidden = _analyze(files, {"min_confidence": 0.9})
    assert hidden.total_findings == 0
    assert hidden.hidden_below_threshold == 1


def test_classes_can_be_disabled_independently():
    files = {
        "docs/a.md": "`src/gone.py` and [x](../README.md#nope)\n",
        "README.md": "## Yes\n",
        # A real file under src/, so the path reference is anchored and
        # therefore checkable. Without it the path is uncheckable and this
        # test would pass for the wrong reason.
        "src/real.py": "",
    }
    assert _analyze(files, {"check_path": False}).total_findings == 1
    assert _analyze(files, {"check_anchor": False}).total_findings == 1
    assert _analyze(files, {"check_path": False, "check_anchor": False}).total_findings == 0


def test_findings_are_ordered_most_confident_first():
    report = _analyze(
        {
            "docs/guide.md": "`src/one.py`\n",
            "docs/architecture.md": "`src/two.py`\n",
            "src/real.py": "",
        }
    )
    confidences = [f.confidence for f in report.findings]
    assert confidences == sorted(confidences, reverse=True)


def test_finding_carries_evidence_and_a_reason():
    report = _analyze({"docs/a.md": "See `src/gone.py`.\n", "src/real.py": ""})
    finding = report.findings[0]
    assert finding.reason
    assert any("docs/a.md:1" in e for e in finding.evidence)
    assert finding.raw == "src/gone.py"


def test_oversized_documents_are_skipped():
    """Reproduces the 500KB ``max_file_size_kb`` ceiling."""
    big = "See `src/gone.py`.\n" + ("x" * (600 * 1024))
    report = _analyze({"docs/big.md": big, "src/real.py": ""})
    assert report.documents_scanned == 0


def test_rerunning_changes_nothing():
    """Exit criterion: re-running changes no rows."""
    files = {"docs/a.md": "See `src/gone.py`.\n", "src/real.py": ""}
    first, second = _analyze(files), _analyze(files)
    key = lambda r: [  # noqa: E731
        (f.file_path, f.kind, f.line_number, f.target, f.confidence) for f in r.findings
    ]
    assert key(first) == key(second)


def test_empty_repository_produces_an_empty_report():
    report = _analyze({})
    assert report.total_findings == 0
    assert report.documents_scanned == 0
    assert report.confidence_summary == {"high": 0, "medium": 0, "low": 0}


# ---------------------------------------------------------------------------
# Confidence vocabulary
# ---------------------------------------------------------------------------


def test_every_origin_has_a_confidence():
    """The Literal vocabulary and the confidence table are two views of one
    thing, so neither may carry a name the other lacks."""
    assert frozenset(ORIGIN_CONFIDENCE) == DRIFT_ORIGIN_VALUES


@pytest.mark.parametrize("origin", sorted(DRIFT_ORIGIN_VALUES))
def test_confidences_are_probabilities(origin: str):
    assert 0.0 < ORIGIN_CONFIDENCE[origin] <= 1.0


def test_default_cutoff_hides_nothing_that_ships():
    """Every shipping origin sits at or above the default cutoff, so a user
    who passes no flag sees the whole detector."""
    assert min(ORIGIN_CONFIDENCE.values()) >= DEFAULT_MIN_CONFIDENCE


def test_bucket_boundaries_are_ordered():
    assert 0.0 < REVIEW_CONFIDENCE_THRESHOLD < HIGH_CONFIDENCE_THRESHOLD <= 1.0


def test_summarize_confidence_buckets_are_exhaustive():
    class _F:
        def __init__(self, c):
            self.confidence = c

    findings = [_F(0.95), _F(0.9), _F(0.5), _F(0.2)]
    summary = summarize_confidence(findings)
    assert summary == {"high": 2, "medium": 1, "low": 1}
    assert sum(summary.values()) == len(findings)


# ---------------------------------------------------------------------------
# Working-tree probe and opaque directories
# ---------------------------------------------------------------------------


def test_disk_probe_is_case_exact(tmp_path):
    (tmp_path / "src").mkdir()
    (tmp_path / "src" / "fixture.json").write_text("{}")
    doc = "See `src/fixture.json` and `src/Fixture.json`.\n"
    source_map = {"docs/a.md": doc.encode(), "src/app.json": b""}
    report = DocDriftAnalyzer(
        "repo", source_map=source_map, repo_root=tmp_path, rename_lookup=lambda _p: {}
    ).analyze()
    # A case-insensitive filesystem would call the second uncheckable locally
    # and CI on Linux would call it missing; the probe answers as Linux does.
    assert [f.target for f in report.findings] == ["src/Fixture.json"]


def test_reference_inside_a_submodule_is_uncheckable():
    files = {"docs/a.md": "See `libs/sub/x.py` and `libs/gone.py`.\n", "libs/other.py": ""}
    source_map = {k: v.encode() for k, v in files.items()}
    report = DocDriftAnalyzer(
        "repo", source_map=source_map, opaque_dirs=frozenset({"libs/sub"})
    ).analyze()
    assert [f.target for f in report.findings] == ["libs/gone.py"]
    assert report.verdict_summary[DriftVerdict.UNCHECKABLE.value] == 1