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.2 KB
Raw Blame
"""Tests for the documentation drift endpoints.

Weighted toward what the surface may not claim rather than toward what it
serves. A drift dashboard has two easy ways to lie: reporting a store nobody
filled as a clean tree, and letting a reference row read as "this document
describes your file". Both have a test here.
"""

from __future__ import annotations

import pytest
from httpx import AsyncClient
from sqlalchemy import text

from repowise.core.analysis.doc_drift.constants import (
    DETECTION_BASIS,
    REFERENCE_BASIS,
)
from repowise.core.analysis.doc_drift.models import (
    DocDriftFindingData,
    DriftKind,
    ResolvedDocReference,
)
from repowise.core.analysis.doc_drift.serialize import derive_doc_drift_id
from repowise.core.persistence import crud
from repowise.core.persistence.database import get_session
from tests.unit.server.conftest import create_test_repo


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: src/auth.py"],
        "raw": "src/auth.py",
        "context": "The resolver lives in src/auth.py.",
    }
    base.update(over)
    return DocDriftFindingData(**base)


async def _seed(session_factory, repo_id: str, *, findings=None, references=None):
    """Write drift rows the way the pipeline writes them."""
    async with get_session(session_factory) as session:
        await crud.replace_doc_drift_findings(session, repo_id, list(findings or []))
        await crud.replace_doc_drift_references(
            session, repo_id, list(references or [])
        )


def _reference(**over) -> ResolvedDocReference:
    base = {
        "doc_path": "docs/overview.md",
        "target_path": "src/auth.py",
        "kind": DriftKind.LINK,
        "line": 9,
        "section": "Extension points",
    }
    base.update(over)
    return ResolvedDocReference(**base)


class TestFindings:
    @pytest.mark.asyncio
    async def test_it_serves_findings_with_the_rollup_over_them(
        self, client: AsyncClient, app
    ) -> None:
        repo = await create_test_repo(client)
        await _seed(
            app.state.session_factory,
            repo["id"],
            findings=[
                _finding(),
                _finding(line_number=50, kind=DriftKind.ANCHOR, confidence=0.95),
                _finding(file_path="docs/cli.md", confidence=0.5),
            ],
            references=[_reference()],
        )

        resp = await client.get(f"/api/repos/{repo['id']}/doc-drift")
        assert resp.status_code == 200
        data = resp.json()

        assert data["unavailable"] is None
        assert len(data["findings"]) == 3
        assert data["findings_emitted"] == 3
        assert data["summary"]["findings_total"] == 3
        assert data["summary"]["documents"] == 2
        assert data["summary"]["confidence"] == {"high": 2, "medium": 1, "low": 0}
        assert data["summary"]["by_kind"] == {"anchor": 1, "path": 2}

    @pytest.mark.asyncio
    async def test_findings_new_since_the_last_update_are_marked(
        self, client: AsyncClient, app
    ) -> None:
        repo = await create_test_repo(client)
        await _seed(app.state.session_factory, repo["id"], findings=[_finding()])
        await _seed(
            app.state.session_factory,
            repo["id"],
            findings=[_finding(), _finding(target="src/new.py", raw="src/new.py")],
        )

        data = (await client.get(f"/api/repos/{repo['id']}/doc-drift")).json()
        new = {f["target"]: (f["is_new"], f["first_seen_at"]) for f in data["findings"]}
        assert new["src/auth.py"] == (False, None)
        assert new["src/new.py"][0] is True
        assert new["src/new.py"][1] is not None
        assert data["summary"]["new_since_last_update"] == 1

    @pytest.mark.asyncio
    async def test_a_failing_history_read_is_reported_not_raised(
        self, client: AsyncClient, app, monkeypatch
    ) -> None:
        from sqlalchemy.exc import OperationalError

        repo = await create_test_repo(client)
        await _seed(app.state.session_factory, repo["id"], findings=[_finding()])

        async def _locked(*_a, **_k):
            raise OperationalError("select", {}, Exception("database is locked"))

        monkeypatch.setattr(crud, "doc_drift_last_written", _locked)
        resp = await client.get(f"/api/repos/{repo['id']}/doc-drift")
        assert resp.status_code == 200
        assert resp.json()["unavailable"] == "drift_read_failed"

    @pytest.mark.asyncio
    async def test_a_count_never_travels_without_what_it_covers(
        self, client: AsyncClient, app
    ) -> None:
        """Most references in a real tree are uncheckable; the basis says so."""
        repo = await create_test_repo(client)
        await _seed(
            app.state.session_factory,
            repo["id"],
            findings=[_finding()],
            references=[_reference()],
        )

        resp = await client.get(f"/api/repos/{repo['id']}/doc-drift")
        assert resp.json()["summary"]["findings_basis"] == DETECTION_BASIS

    @pytest.mark.asyncio
    async def test_the_finding_names_the_document_to_edit(
        self, client: AsyncClient, app
    ) -> None:
        """Not the target it names. The opposite reading is the whole risk."""
        repo = await create_test_repo(client)
        await _seed(
            app.state.session_factory,
            repo["id"],
            findings=[_finding()],
            references=[_reference()],
        )

        finding = (await client.get(f"/api/repos/{repo['id']}/doc-drift")).json()[
            "findings"
        ][0]
        assert finding["file_path"] == "docs/architecture.md"
        assert finding["target"] == "src/auth.py"

    @pytest.mark.asyncio
    async def test_every_finding_carries_the_id_a_client_keys_triage_on(
        self, client: AsyncClient, app
    ) -> None:
        repo = await create_test_repo(client)
        await _seed(
            app.state.session_factory,
            repo["id"],
            findings=[_finding()],
            references=[_reference()],
        )

        finding = (await client.get(f"/api/repos/{repo['id']}/doc-drift")).json()[
            "findings"
        ][0]
        assert finding["id"] == derive_doc_drift_id(
            "docs/architecture.md", "path", 42, "src/auth.py"
        )

    @pytest.mark.asyncio
    async def test_an_unfilled_store_refuses_rather_than_reporting_a_clean_tree(
        self, client: AsyncClient, app
    ) -> None:
        """The pass only runs when an update has work, so "never analysed"
        looks exactly like "every document is correct"."""
        repo = await create_test_repo(client)

        resp = await client.get(f"/api/repos/{repo['id']}/doc-drift")
        assert resp.status_code == 200
        data = resp.json()
        assert data["unavailable"] == "not_computed"
        assert data["findings"] == []
        assert data["summary"] is None

    @pytest.mark.asyncio
    async def test_a_repository_with_documentation_and_no_drift_reads_as_clean(
        self, client: AsyncClient, app
    ) -> None:
        """The other side of the probe: references stored, no findings."""
        repo = await create_test_repo(client)
        await _seed(app.state.session_factory, repo["id"], references=[_reference()])

        data = (await client.get(f"/api/repos/{repo['id']}/doc-drift")).json()
        assert data["unavailable"] is None
        assert data["summary"]["findings_total"] == 0

    @pytest.mark.asyncio
    async def test_a_narrowing_filter_cannot_claim_the_pass_never_ran(
        self, client: AsyncClient, app
    ) -> None:
        """The probe answers a question about the index, not about the query.

        A repository whose documents resolve to nothing stores no references,
        so probing the reference table alone would let ``min_confidence`` turn
        findings that exist into "nobody has ever checked this".
        """
        repo = await create_test_repo(client)
        await _seed(
            app.state.session_factory,
            repo["id"],
            findings=[_finding(confidence=0.5)],
            references=[],
        )

        data = (
            await client.get(
                f"/api/repos/{repo['id']}/doc-drift", params={"min_confidence": 0.9}
            )
        ).json()
        assert data["unavailable"] is None
        assert data["summary"]["findings_total"] == 0

    @pytest.mark.asyncio
    async def test_a_document_filter_matching_nothing_is_not_a_missing_pass(
        self, client: AsyncClient, app
    ) -> None:
        repo = await create_test_repo(client)
        await _seed(
            app.state.session_factory, repo["id"], findings=[_finding()], references=[]
        )

        data = (
            await client.get(
                f"/api/repos/{repo['id']}/doc-drift",
                params={"document": "docs/absent.md"},
            )
        ).json()
        assert data["unavailable"] is None

    @pytest.mark.asyncio
    async def test_an_unknown_repository_is_not_answered_as_documented(
        self, client: AsyncClient
    ) -> None:
        resp = await client.get("/api/repos/does-not-exist/doc-drift")
        assert resp.status_code == 404

    @pytest.mark.asyncio
    async def test_the_confidence_floor_filters_the_list_and_its_summary_together(
        self, client: AsyncClient, app
    ) -> None:
        repo = await create_test_repo(client)
        await _seed(
            app.state.session_factory,
            repo["id"],
            findings=[_finding(), _finding(file_path="docs/cli.md", confidence=0.5)],
            references=[_reference()],
        )

        data = (
            await client.get(
                f"/api/repos/{repo['id']}/doc-drift", params={"min_confidence": 0.8}
            )
        ).json()
        assert len(data["findings"]) == 1
        assert data["summary"]["findings_total"] == 1

    @pytest.mark.asyncio
    async def test_the_kind_filter_narrows_the_summary_too(
        self, client: AsyncClient, app
    ) -> None:
        repo = await create_test_repo(client)
        await _seed(
            app.state.session_factory,
            repo["id"],
            findings=[_finding(), _finding(line_number=9, kind=DriftKind.ANCHOR)],
            references=[_reference()],
        )

        data = (
            await client.get(
                f"/api/repos/{repo['id']}/doc-drift", params={"kind": "anchor"}
            )
        ).json()
        assert data["summary"]["by_kind"] == {"anchor": 1}
        assert data["summary"]["findings_total"] == 1

    @pytest.mark.asyncio
    async def test_a_capped_page_still_counts_the_whole_repository(
        self, client: AsyncClient, app
    ) -> None:
        repo = await create_test_repo(client)
        await _seed(
            app.state.session_factory,
            repo["id"],
            findings=[_finding(line_number=n) for n in range(1, 6)],
            references=[_reference()],
        )

        data = (
            await client.get(f"/api/repos/{repo['id']}/doc-drift", params={"limit": 2})
        ).json()
        assert data["findings_emitted"] == 2
        assert len(data["findings"]) == 2
        assert data["summary"]["findings_total"] == 5

    @pytest.mark.asyncio
    async def test_one_document_can_be_asked_about_on_its_own(
        self, client: AsyncClient, app
    ) -> None:
        repo = await create_test_repo(client)
        await _seed(
            app.state.session_factory,
            repo["id"],
            findings=[_finding(), _finding(file_path="docs/cli.md")],
            references=[_reference()],
        )

        data = (
            await client.get(
                f"/api/repos/{repo['id']}/doc-drift",
                params={"document": "docs/cli.md"},
            )
        ).json()
        assert [f["file_path"] for f in data["findings"]] == ["docs/cli.md"]


class TestStaleIndex:
    """An index older than the store must say so, and say which cause.

    Reached for real: starting the server against a pre-drift index creates
    the tables without running the pass, so "table absent" and "table empty"
    are different states with different advice. Telling a reader to re-index
    when the database is merely locked is the third.
    """

    @staticmethod
    async def _drop_tables(session_factory) -> None:
        async with get_session(session_factory) as session:
            await session.execute(text("DROP TABLE doc_drift_findings"))
            await session.execute(text("DROP TABLE doc_drift_references"))

    @pytest.mark.asyncio
    async def test_findings_name_the_stale_index_rather_than_a_failure(
        self, client: AsyncClient, app
    ) -> None:
        repo = await create_test_repo(client)
        await self._drop_tables(app.state.session_factory)

        resp = await client.get(f"/api/repos/{repo['id']}/doc-drift")
        assert resp.status_code == 200
        data = resp.json()
        assert data["unavailable"] == "index_predates_doc_drift"
        assert data["summary"] is None

    @pytest.mark.asyncio
    async def test_the_reverse_view_says_the_same_thing(
        self, client: AsyncClient, app
    ) -> None:
        repo = await create_test_repo(client)
        await self._drop_tables(app.state.session_factory)

        data = (
            await client.get(
                f"/api/repos/{repo['id']}/doc-drift/references",
                params={"target": "src/auth.py"},
            )
        ).json()
        assert data["unavailable"] == "index_predates_doc_drift"
        # The refusal still carries what a reference would have claimed, so a
        # reader is never left to infer it from an empty list.
        assert data["references_basis"] == REFERENCE_BASIS


class TestReferences:
    @pytest.mark.asyncio
    async def test_it_answers_which_documents_name_a_file(
        self, client: AsyncClient, app
    ) -> None:
        repo = await create_test_repo(client)
        await _seed(
            app.state.session_factory,
            repo["id"],
            references=[_reference(), _reference(doc_path="docs/cli.md", line=3)],
        )

        resp = await client.get(
            f"/api/repos/{repo['id']}/doc-drift/references",
            params={"target": "src/auth.py"},
        )
        assert resp.status_code == 200
        data = resp.json()
        assert data["target_path"] == "src/auth.py"
        assert data["documents"] == 2
        assert {r["document"] for r in data["references"]} == {
            "docs/overview.md",
            "docs/cli.md",
        }
        assert data["references"][0]["section"] in {"Extension points", ""}

    @pytest.mark.asyncio
    async def test_absence_is_not_proof_that_nothing_documents_the_file(
        self, client: AsyncClient, app
    ) -> None:
        repo = await create_test_repo(client)
        await _seed(app.state.session_factory, repo["id"], references=[_reference()])

        data = (
            await client.get(
                f"/api/repos/{repo['id']}/doc-drift/references",
                params={"target": "src/never_mentioned.py"},
            )
        ).json()
        assert data["references"] == []
        assert data["references_basis"] == REFERENCE_BASIS

    @pytest.mark.asyncio
    async def test_an_unfilled_store_refuses_the_reverse_question_too(
        self, client: AsyncClient
    ) -> None:
        repo = await create_test_repo(client)

        data = (
            await client.get(
                f"/api/repos/{repo['id']}/doc-drift/references",
                params={"target": "src/auth.py"},
            )
        ).json()
        assert data["unavailable"] == "not_computed"
        assert data["references"] == []

    @pytest.mark.asyncio
    async def test_drift_is_reported_against_the_document_not_the_target(
        self, client: AsyncClient, app
    ) -> None:
        """``documents_with_drift`` counts a document's own findings, which
        need not be about the file that was asked about."""
        repo = await create_test_repo(client)
        await _seed(
            app.state.session_factory,
            repo["id"],
            findings=[_finding(file_path="docs/overview.md", target="src/gone.py")],
            references=[_reference()],
        )

        data = (
            await client.get(
                f"/api/repos/{repo['id']}/doc-drift/references",
                params={"target": "src/auth.py"},
            )
        ).json()
        assert data["documents_with_drift"] == [
            {"document": "docs/overview.md", "findings": 1}
        ]

    @pytest.mark.asyncio
    async def test_a_link_with_a_fragment_is_one_mention_not_two(
        self, client: AsyncClient, app
    ) -> None:
        repo = await create_test_repo(client)
        await _seed(
            app.state.session_factory,
            repo["id"],
            references=[
                _reference(kind=DriftKind.LINK),
                _reference(kind=DriftKind.ANCHOR),
            ],
        )

        data = (
            await client.get(
                f"/api/repos/{repo['id']}/doc-drift/references",
                params={"target": "src/auth.py"},
            )
        ).json()
        assert len(data["references"]) == 1
        assert data["documents"] == 1

    @pytest.mark.asyncio
    async def test_a_document_past_the_display_cap_still_reports_its_drift(
        self, client: AsyncClient, app
    ) -> None:
        repo = await create_test_repo(client)
        await _seed(
            app.state.session_factory,
            repo["id"],
            findings=[_finding(file_path="docs/z.md", target="src/gone.py")],
            references=[
                _reference(doc_path=f"docs/{name}.md", line=1)
                for name in ("a", "b", "z")
            ],
        )

        data = (
            await client.get(
                f"/api/repos/{repo['id']}/doc-drift/references",
                params={"target": "src/auth.py", "limit": 1},
            )
        ).json()
        assert len(data["references"]) == 1
        assert data["documents_with_drift"] == [{"document": "docs/z.md", "findings": 1}]

    @pytest.mark.asyncio
    async def test_a_capped_answer_says_how_much_it_left_out(
        self, client: AsyncClient, app
    ) -> None:
        """Otherwise 50 rows sit beside an uncapped document count with no way
        for a reader to tell a complete answer from a slice."""
        repo = await create_test_repo(client)
        await _seed(
            app.state.session_factory,
            repo["id"],
            references=[
                _reference(doc_path=f"docs/{n}.md", line=1) for n in range(1, 6)
            ],
        )

        data = (
            await client.get(
                f"/api/repos/{repo['id']}/doc-drift/references",
                params={"target": "src/auth.py", "limit": 2},
            )
        ).json()
        assert data["references_emitted"] == 2
        assert data["references_total"] == 5
        assert data["documents"] == 5

    @pytest.mark.asyncio
    async def test_an_unknown_repository_is_not_answered_as_undocumented(
        self, client: AsyncClient
    ) -> None:
        resp = await client.get(
            "/api/repos/does-not-exist/doc-drift/references",
            params={"target": "src/auth.py"},
        )
        assert resp.status_code == 404