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.

13.0 KB
Raw Blame
"""A report and a store serialize to the same bytes.

The reason this file exists: one consumer of this data holds ORM rows and
another holds a ``DocDriftReport`` with no database under it at all. Those were
two hand-written dicts waiting to drift, which is the failure
``tests/unit/dead_code/test_confidence_parity.py`` records having already
happened once. Both paths now go through one builder, and these tests assert
the identity rather than the resemblance.
"""

from __future__ import annotations

import json
from datetime import UTC, datetime

import pytest

from repowise.core.analysis.doc_drift.constants import DETECTION_BASIS
from repowise.core.analysis.doc_drift.models import (
    DocDriftFindingData,
    DocDriftReport,
    DriftKind,
    ResolvedDocReference,
)
from repowise.core.analysis.doc_drift.serialize import (
    collapse_reference_sites,
    derive_doc_drift_fingerprint,
    derive_doc_drift_id,
    documents_with_drift,
    finding_dict,
    fingerprint_of,
    serialize_finding,
    serialize_reference,
    serialize_report,
    summarize_findings,
)
from repowise.core.persistence.crud.analysis.doc_drift import (
    serialize_doc_drift_reference_row,
    serialize_doc_drift_row,
)
from repowise.core.persistence.models import DocDriftFinding, DocDriftReference


def _finding(**over) -> DocDriftFindingData:
    base = {
        "kind": DriftKind.PATH,
        "file_path": "docs/architecture.md",
        "line_number": 42,
        "target": "src/auth.py",
        "confidence": 0.9,
        "reason": "No file matches this path.",
        "origin": "path_no_candidate",
        "evidence": ["line 42: see src/auth.py"],
        "raw": "src/auth.py",
        "context": "The resolver lives in src/auth.py.",
    }
    base.update(over)
    return DocDriftFindingData(**base)


def _row_from(finding: DocDriftFindingData) -> DocDriftFinding:
    """The ORM row the writer would have produced for *finding*."""
    return DocDriftFinding(
        repository_id="r1",
        file_path=finding.file_path,
        kind=str(finding.kind.value),
        line_number=finding.line_number,
        target=finding.target,
        confidence=finding.confidence,
        reason=finding.reason,
        origin=finding.origin,
        evidence_json=json.dumps(list(finding.evidence)),
        raw=finding.raw,
        context=finding.context,
        suggestion=finding.suggestion or None,
        suggestion_basis=finding.suggestion_basis or None,
    )


def test_a_report_finding_and_its_stored_row_serialize_identically():
    finding = _finding()
    assert serialize_finding(finding) == serialize_doc_drift_row(_row_from(finding))


def test_the_evidence_toggle_agrees_on_both_paths():
    finding = _finding()
    assert serialize_finding(finding, evidence=False) == serialize_doc_drift_row(
        _row_from(finding), evidence=False
    )
    assert "evidence" not in serialize_finding(finding, evidence=False)


def test_a_suggestion_round_trips_identically_on_both_paths():
    finding = _finding(suggestion="src/auth/", suggestion_basis="package_split")
    served = serialize_finding(finding)
    assert served == serialize_doc_drift_row(_row_from(finding))
    assert served["suggestion"] == "src/auth/"
    assert served["suggestion_basis"] == "package_split"


def test_no_suggestion_means_no_keys_not_nulls():
    """MCP get_health serves these dicts; most findings must not grow noise."""
    assert "suggestion" not in serialize_finding(_finding())
    assert "suggestion_basis" not in serialize_doc_drift_row(_row_from(_finding()))
    served = finding_dict(
        file_path="docs/a.md", kind="path", line_number=1, target="x",
        confidence=0.9, origin="o", reason="r", raw="x", context="c",
        suggestion="", suggestion_basis="",
    )
    assert "suggestion" not in served and "fingerprint" not in served


def test_a_suggestion_with_a_null_basis_omits_the_basis():
    served = finding_dict(
        file_path="docs/a.md", kind="path", line_number=1, target="x",
        confidence=0.9, origin="o", reason="r", raw="x", context="c",
        suggestion="y/", suggestion_basis=None,
    )
    assert served["suggestion"] == "y/" and "suggestion_basis" not in served


def test_fingerprint_of_prefers_a_carried_fingerprint():
    row = {"file_path": "docs/a.md", "kind": "path", "target": "x"}
    assert fingerprint_of(row) == derive_doc_drift_fingerprint("docs/a.md", "path", "x")
    assert fingerprint_of({**row, "fingerprint": "abc"}) == "abc"


def test_a_report_reference_and_its_stored_row_serialize_identically():
    reference = ResolvedDocReference(
        doc_path="docs/architecture.md",
        target_path="src/auth.py",
        kind=DriftKind.LINK,
        line=7,
        section="Extension points",
    )
    row = DocDriftReference(
        repository_id="r1",
        document_path=reference.doc_path,
        target_path=reference.target_path,
        kind=str(reference.kind.value),
        line_number=reference.line,
        section=reference.section,
    )
    assert serialize_reference(reference) == serialize_doc_drift_reference_row(row)


def test_an_empty_section_is_absent_rather_than_blank():
    reference = ResolvedDocReference(
        doc_path="docs/a.md", target_path="src/x.py", kind=DriftKind.PATH, line=1
    )
    assert "section" not in serialize_reference(reference)


def test_confidence_is_rounded_once_so_two_surfaces_cannot_disagree():
    finding = _finding(confidence=0.925)
    assert serialize_finding(finding)["confidence"] == 0.93
    assert serialize_doc_drift_row(_row_from(finding))["confidence"] == 0.93


class TestDeriveId:
    def test_the_same_site_gets_the_same_id_across_runs(self):
        first = derive_doc_drift_id("docs/a.md", DriftKind.PATH, 3, "src/x.py")
        second = derive_doc_drift_id("docs/a.md", "path", 3, "src/x.py")
        assert first == second

    def test_the_id_is_the_house_width(self):
        value = derive_doc_drift_id("docs/a.md", DriftKind.PATH, 3, "src/x.py")
        assert len(value) == 32
        assert value == value.lower()

    @pytest.mark.parametrize(
        "args",
        [
            ("docs/b.md", DriftKind.PATH, 3, "src/x.py"),
            ("docs/a.md", DriftKind.LINK, 3, "src/x.py"),
            ("docs/a.md", DriftKind.PATH, 4, "src/x.py"),
            ("docs/a.md", DriftKind.PATH, 3, "src/y.py"),
        ],
    )
    def test_every_part_of_the_key_moves_the_id(self, args):
        base = derive_doc_drift_id("docs/a.md", DriftKind.PATH, 3, "src/x.py")
        assert derive_doc_drift_id(*args) != base

    def test_the_separator_cannot_be_forged_by_concatenation(self):
        """Two different keys must not join to one string."""
        assert derive_doc_drift_id("a", "path", 1, "bc") != derive_doc_drift_id(
            "a", "path", 1, "b\x00c"
        )


class TestSummary:
    def test_it_counts_documents_not_findings(self):
        findings = [
            serialize_finding(_finding(file_path="docs/a.md", line_number=1)),
            serialize_finding(_finding(file_path="docs/a.md", line_number=2)),
            serialize_finding(_finding(file_path="docs/b.md")),
        ]
        summary = summarize_findings(findings)
        assert summary["findings_total"] == 3
        assert summary["documents"] == 2

    def test_it_carries_the_basis_so_a_count_never_travels_alone(self):
        assert summarize_findings([])["findings_basis"] == DETECTION_BASIS

    def test_an_empty_repository_still_names_every_tier(self):
        assert summarize_findings([])["confidence"] == {
            "high": 0,
            "medium": 0,
            "low": 0,
        }

    def test_kinds_are_ordered_so_equal_data_serializes_equal_bytes(self):
        findings = [
            serialize_finding(_finding(kind=DriftKind.PATH)),
            serialize_finding(_finding(kind=DriftKind.ANCHOR, line_number=2)),
            serialize_finding(_finding(kind=DriftKind.LINK, line_number=3)),
        ]
        assert list(summarize_findings(findings)["by_kind"]) == [
            "anchor",
            "link",
            "path",
        ]


class TestCollapseAndDrift:
    def test_a_link_with_a_fragment_is_one_mention_not_two(self):
        rows = [
            {"document": "docs/a.md", "line": 5, "kind": "link"},
            {"document": "docs/a.md", "line": 5, "kind": "anchor"},
            {"document": "docs/a.md", "line": 6, "kind": "link"},
        ]
        collapsed = collapse_reference_sites(rows)
        assert [r["kind"] for r in collapsed] == ["link", "link"]
        assert [r["line"] for r in collapsed] == [5, 6]

    def test_collapsing_does_not_mutate_the_caller_s_rows(self):
        rows = [{"document": "docs/a.md", "line": 5, "kind": "link"}]
        collapse_reference_sites(rows)[0]["kind"] = "anchor"
        assert rows[0]["kind"] == "link"

    def test_only_documents_that_carry_drift_are_listed(self):
        references = [
            {"document": "docs/a.md", "line": 1, "kind": "path"},
            {"document": "docs/b.md", "line": 1, "kind": "path"},
        ]
        assert documents_with_drift(references, {"docs/b.md": 2, "docs/c.md": 9}) == [
            {"document": "docs/b.md", "findings": 2}
        ]

    def test_a_clean_answer_lists_nothing(self):
        references = [{"document": "docs/a.md", "line": 1, "kind": "path"}]
        assert documents_with_drift(references, {}) == []


class TestSerializeReport:
    def _report(self) -> DocDriftReport:
        return DocDriftReport(
            repo_id="r1",
            analyzed_at=datetime(2026, 9, 18, tzinfo=UTC),
            total_findings=1,
            findings=[_finding()],
            confidence_summary={"high": 1, "medium": 0, "low": 0},
            documents_scanned=12,
            references_checked=340,
            verdict_summary={
                "resolved": 300,
                "missing": 1,
                "ambiguous": 5,
                "uncheckable": 34,
            },
            resolved_references=[
                ResolvedDocReference(
                    doc_path="docs/b.md",
                    target_path="src/auth.py",
                    kind=DriftKind.LINK,
                    line=9,
                ),
                ResolvedDocReference(
                    doc_path="docs/a.md",
                    target_path="src/auth.py",
                    kind=DriftKind.PATH,
                    line=3,
                ),
                ResolvedDocReference(
                    doc_path="docs/a.md",
                    target_path="src/other.py",
                    kind=DriftKind.PATH,
                    line=4,
                ),
            ],
        )

    def test_references_arrive_inverted_by_the_file_that_was_named(self):
        payload = serialize_report(self._report())
        assert set(payload["references_by_target"]) == {"src/auth.py", "src/other.py"}
        assert len(payload["references_by_target"]["src/auth.py"]) == 2

    def test_each_target_is_ordered_the_way_the_store_returns_it(self):
        payload = serialize_report(self._report())
        rows = payload["references_by_target"]["src/auth.py"]
        assert [r["document"] for r in rows] == ["docs/a.md", "docs/b.md"]

    def test_the_findings_are_the_same_dicts_a_store_would_serve(self):
        """Identical but for the id and fingerprint, which no store column holds."""
        report = self._report()
        payload = serialize_report(report)
        minted = {"id", "fingerprint"}
        served = [{k: v for k, v in f.items() if k not in minted} for f in payload["findings"]]
        assert served == [
            serialize_doc_drift_row(_row_from(f)) for f in report.findings
        ]

    def test_every_finding_carries_the_id_the_wire_contract_requires(self):
        """A consumer serving drift from this artifact feeds a table that keys
        its rows on the id; without one, every row keys on nothing."""
        report = self._report()
        payload = serialize_report(report)
        assert [f["id"] for f in payload["findings"]] == [
            derive_doc_drift_id(f.file_path, f.kind, f.line_number, f.target)
            for f in report.findings
        ]

    def test_every_finding_carries_a_line_independent_fingerprint(self):
        report = self._report()
        payload = serialize_report(report)
        assert [f["fingerprint"] for f in payload["findings"]] == [
            derive_doc_drift_fingerprint(f.file_path, f.kind, f.target)
            for f in report.findings
        ]

    def test_the_suppressed_count_survives_serialization(self):
        report = self._report()
        assert serialize_report(report)["suppressed"] == 0
        report.suppressed = 3
        assert serialize_report(report)["suppressed"] == 3

    def test_the_uncheckable_denominator_survives_serialization(self):
        """The count that keeps the detector honest about its own coverage."""
        payload = serialize_report(self._report())
        assert payload["verdict_summary"]["uncheckable"] == 34
        assert payload["references_checked"] == 340

    def test_the_summary_rides_along_so_no_consumer_recomputes_it(self):
        payload = serialize_report(self._report())
        assert payload["summary"] == summarize_findings(payload["findings"])