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.

21.2 KB
Raw Blame
"""A commit footprint keeps its files and stops answering per-file questions.

The defect these pin: the ``pr`` and ``git_archaeology`` miners read one
decision out of one commit body and then take that commit's whole file list,
so a decision mined from a large refactor claims every file it touched, and
``get_why`` on a file answers with decisions about something else.

The case the fixtures are modelled on: ``search_digest.py``, whose whole job
is compacting Grep output, carried five decisions about collapsing repeated
file reads -- a mechanism in a sibling module -- because all five were mined
from one 38-file commit that happened to touch it.
"""

from __future__ import annotations

import json

from sqlalchemy import select

from repowise.core.analysis.decisions.scope import (
    SCOPE_BASIS_FOOTPRINT,
    SCOPE_BASIS_PROXIMITY,
    SCOPE_BASIS_REPOSITORY,
    SCOPE_BASIS_SELECTED,
    SCOPE_BASIS_STATED,
)
from repowise.core.persistence.crud import bulk_upsert_decisions, update_decision_metadata
from repowise.core.persistence.crud.authority import accept_decision
from repowise.core.persistence.decision_graph import (
    get_governed_nodes,
    get_governing_decisions,
)
from repowise.core.persistence.decision_migration import (
    backfill_scope_basis,
    backfill_session_scope_basis,
    prune_unindexed_scope_files,
)
from repowise.core.persistence.models import (
    DecisionNodeLink,
    DecisionRecord,
    GraphNode,
)
from tests.unit.persistence.helpers import insert_repo

#: The mechanism file and the bystander, as in the real commit.
_MECHANISM = "packages/cli/src/repowise/cli/commands/augment_cmd/read_state.py"
_BYSTANDER = "packages/cli/src/repowise/cli/commands/augment_cmd/search_digest.py"
_COMMIT_FILES = [_MECHANISM, _BYSTANDER] + [
    f"packages/core/src/mod{i:02d}.py" for i in range(36)
]


def _decision(
    title: str, *, files: list[str], scope_basis: str = "", source: str = "pr"
) -> dict:
    return {
        "title": title,
        "decision": f"{title} body",
        "rationale": "measured",
        "source": source,
        "status": "active",
        "affected_files": files,
        "affected_modules": [],
        "scope_basis": scope_basis,
        "evidence_file": None,
        "confidence": 0.8,
        "verification": "exact",
        "source_quote": title,
    }


async def test_a_footprint_writes_no_file_links(async_session):
    repo = await insert_repo(async_session)
    ids = await bulk_upsert_decisions(
        async_session,
        repo.id,
        [
            _decision(
                "Collapse unchanged hook re-reads",
                files=_COMMIT_FILES,
                scope_basis=SCOPE_BASIS_FOOTPRINT,
            )
        ],
    )
    did = ids[0]

    # The bystander must not be told this governs it. Nor must the mechanism:
    # the record carries no evidence naming either one.
    assert await get_governing_decisions(async_session, repo.id, _BYSTANDER) == []
    assert await get_governing_decisions(async_session, repo.id, _MECHANISM) == []
    assert [link.link_type for link in await get_governed_nodes(async_session, did)] == []


async def test_a_footprint_keeps_its_files_on_the_record(async_session):
    """Provenance survives. Staleness and the origin story both read this."""
    repo = await insert_repo(async_session)
    ids = await bulk_upsert_decisions(
        async_session,
        repo.id,
        [_decision("Wide rule", files=_COMMIT_FILES, scope_basis=SCOPE_BASIS_FOOTPRINT)],
    )
    rec = await async_session.get(DecisionRecord, ids[0])
    assert json.loads(rec.affected_files_json) == _COMMIT_FILES
    assert rec.scope_basis == SCOPE_BASIS_FOOTPRINT


async def test_a_narrow_record_still_binds(async_session):
    repo = await insert_repo(async_session)
    ids = await bulk_upsert_decisions(
        async_session,
        repo.id,
        [_decision("Pin the read state", files=[_MECHANISM], source="inline_marker")],
    )
    governing = await get_governing_decisions(async_session, repo.id, _MECHANISM)
    assert [d.id for d in governing] == ids


async def test_a_footprint_links_no_modules_either(async_session):
    """Its module list is the directories of the same file list, so no better
    evidenced."""
    repo = await insert_repo(async_session)
    payload = _decision(
        "Wide rule", files=_COMMIT_FILES, scope_basis=SCOPE_BASIS_FOOTPRINT
    )
    payload["affected_modules"] = ["packages/core/src"]
    ids = await bulk_upsert_decisions(async_session, repo.id, [payload])
    assert await get_governed_nodes(async_session, ids[0]) == []


# ---------------------------------------------------------------------------
# The backfill, for records written before the basis existed
# ---------------------------------------------------------------------------


async def test_backfill_marks_a_legacy_wide_pr_record_and_drops_its_file_links(
    async_session,
):
    repo = await insert_repo(async_session)
    # Written the way the old code wrote it: no basis, whole commit list.
    ids = await bulk_upsert_decisions(
        async_session, repo.id, [_decision("Legacy wide", files=_COMMIT_FILES)]
    )
    did = ids[0]
    assert await get_governing_decisions(async_session, repo.id, _BYSTANDER) != []

    assert await backfill_scope_basis(async_session, repo.id) == 1

    rec = await async_session.get(DecisionRecord, did)
    assert rec.scope_basis == SCOPE_BASIS_FOOTPRINT
    assert json.loads(rec.affected_files_json) == _COMMIT_FILES
    assert await get_governing_decisions(async_session, repo.id, _BYSTANDER) == []


async def test_backfill_repairs_a_narrow_legacy_commit_record_too(async_session):
    """Narrowness does not make a legacy commit list a claim about files.

    The miner never chose any of them. A four-file legacy scope is four files
    of one commit, and out of sample it is no more on topic than a wide one:
    at a five-file cutoff, 82% of the records that still bound came from
    commits that had touched more than five files, because the stored list is
    an inversion of per-file git metadata rather than the commit's diff.
    """
    repo = await insert_repo(async_session)
    files = [f"pkg/m{i}.py" for i in range(4)]
    await bulk_upsert_decisions(
        async_session, repo.id, [_decision("Narrow", files=files)]
    )

    assert await backfill_scope_basis(async_session, repo.id) == 1
    assert await get_governing_decisions(async_session, repo.id, files[0]) == []


async def test_backfill_leaves_an_accepted_record_alone(async_session):
    """A decision somebody confirmed keeps its files.

    The repair cannot tell an accepted record by its basis: ``accept_decision``
    writes ``stated`` only when the accepter passed an explicit scope, and
    neither ``repowise decision confirm`` nor the web accept route does. So a
    reviewer who confirmed a commit-derived decision as-is would have had its
    file links deleted on the next index, and its hotspots would have started
    reporting themselves ungoverned.
    """
    repo = await insert_repo(async_session)
    payload = _decision("Confirmed as is", files=_COMMIT_FILES)
    payload["evidence_file"] = _MECHANISM
    ids = await bulk_upsert_decisions(async_session, repo.id, [payload])
    rec = await async_session.get(DecisionRecord, ids[0])
    # No ``scope=``, which is what both real accept paths do, so the basis is
    # left empty and only the acceptance row marks the record as reviewed.
    await accept_decision(async_session, rec, accepter="tester")
    assert rec.scope_basis == ""

    assert await backfill_scope_basis(async_session, repo.id) == 0
    assert await get_governing_decisions(async_session, repo.id, _MECHANISM) != []


async def test_backfill_leaves_a_selected_scope_alone(async_session):
    """A scope the model chose file by file is not repaired into a footprint.

    This is the whole point of the separate basis: the repair has to be able
    to tell a pre-selector row from one the selector wrote, and both are
    commit-derived with a short file list.
    """
    repo = await insert_repo(async_session)
    await bulk_upsert_decisions(
        async_session,
        repo.id,
        [
            _decision(
                "Chosen", files=[_MECHANISM], scope_basis=SCOPE_BASIS_SELECTED
            )
        ],
    )

    assert await backfill_scope_basis(async_session, repo.id) == 0
    assert await get_governing_decisions(async_session, repo.id, _MECHANISM) != []


async def test_backfill_leaves_a_scopeless_commit_record_alone(async_session):
    """A record with no files has nothing to demote.

    Stamping it a footprint would claim its empty list is a commit's, which is
    the one thing it is not: the selector writes an empty list on purpose when
    the decision is about none of the commit's files.
    """
    repo = await insert_repo(async_session)
    ids = await bulk_upsert_decisions(
        async_session, repo.id, [_decision("No files", files=[])]
    )

    assert await backfill_scope_basis(async_session, repo.id) == 0
    rec = await async_session.get(DecisionRecord, ids[0])
    assert rec.scope_basis == ""


async def test_backfill_leaves_a_wide_record_from_another_source_alone(async_session):
    """Only the two miners that never chose a file are repaired.

    A session-mined record names files the session touched, so a wide one is a
    wide claim rather than a footprint, and demoting it here would be guessing.
    """
    repo = await insert_repo(async_session)
    await bulk_upsert_decisions(
        async_session,
        repo.id,
        [_decision("Wide session rule", files=_COMMIT_FILES, source="session")],
    )
    assert await backfill_scope_basis(async_session, repo.id) == 0
    assert await get_governing_decisions(async_session, repo.id, _BYSTANDER) != []


async def test_backfill_is_idempotent(async_session):
    repo = await insert_repo(async_session)
    await bulk_upsert_decisions(
        async_session, repo.id, [_decision("Legacy wide", files=_COMMIT_FILES)]
    )
    assert await backfill_scope_basis(async_session, repo.id) == 1
    assert await backfill_scope_basis(async_session, repo.id) == 0


async def test_backfill_does_not_touch_a_basis_somebody_already_set(async_session):
    """``decision confirm --scope`` writes a scope by hand; it stays."""
    repo = await insert_repo(async_session)
    ids = await bulk_upsert_decisions(
        async_session,
        repo.id,
        [_decision("Confirmed wide", files=_COMMIT_FILES, scope_basis="stated")],
    )
    assert await backfill_scope_basis(async_session, repo.id) == 0
    rec = await async_session.get(DecisionRecord, ids[0])
    assert rec.scope_basis == "stated"


async def test_backfill_drops_every_link_the_record_had(async_session):
    """Matching what the write path would now produce for the same record."""
    repo = await insert_repo(async_session)
    payload = _decision("Legacy wide", files=_COMMIT_FILES)
    payload["affected_modules"] = ["packages/core/src"]
    ids = await bulk_upsert_decisions(async_session, repo.id, [payload])

    await backfill_scope_basis(async_session, repo.id)

    rows = (
        (
            await async_session.execute(
                select(DecisionNodeLink).where(DecisionNodeLink.decision_id == ids[0])
            )
        )
        .scalars()
        .all()
    )
    assert rows == []


# ---------------------------------------------------------------------------
# A scope a person states outranks a mined one
# ---------------------------------------------------------------------------


async def test_stating_a_scope_by_hand_makes_a_footprint_bind_again(async_session):
    """Storing the new files and then ignoring them would be the worst of
    both."""
    repo = await insert_repo(async_session)
    ids = await bulk_upsert_decisions(
        async_session,
        repo.id,
        [
            _decision(
                "Collapse unchanged hook re-reads",
                files=_COMMIT_FILES,
                scope_basis=SCOPE_BASIS_FOOTPRINT,
            )
        ],
    )
    assert await get_governing_decisions(async_session, repo.id, _MECHANISM) == []

    await update_decision_metadata(async_session, ids[0], affected_files=[_MECHANISM])

    rec = await async_session.get(DecisionRecord, ids[0])
    assert rec.scope_basis == SCOPE_BASIS_STATED
    assert json.loads(rec.affected_files_json) == [_MECHANISM]


async def test_the_backfill_never_re_marks_a_stated_scope(async_session):
    """The row still reads as a wide ``pr`` record to the repair, which looks
    only at source and file count, so the next index would walk it back."""
    repo = await insert_repo(async_session)
    ids = await bulk_upsert_decisions(
        async_session, repo.id, [_decision("Legacy wide", files=_COMMIT_FILES)]
    )
    await update_decision_metadata(async_session, ids[0], affected_files=_COMMIT_FILES)

    assert await backfill_scope_basis(async_session, repo.id) == 0
    rec = await async_session.get(DecisionRecord, ids[0])
    assert rec.scope_basis == SCOPE_BASIS_STATED


async def test_patching_only_modules_leaves_the_basis_alone(async_session):
    """The basis describes the file list, so a module-only patch says nothing."""
    repo = await insert_repo(async_session)
    ids = await bulk_upsert_decisions(
        async_session,
        repo.id,
        [_decision("Wide", files=_COMMIT_FILES, scope_basis=SCOPE_BASIS_FOOTPRINT)],
    )
    await update_decision_metadata(async_session, ids[0], affected_modules=["pkg"])

    rec = await async_session.get(DecisionRecord, ids[0])
    assert rec.scope_basis == SCOPE_BASIS_FOOTPRINT


async def test_accepting_with_a_corrected_scope_makes_the_record_bind(async_session):
    """``decision confirm --scope`` runs through ``accept_decision``, not
    through ``update_decision_metadata``."""
    from repowise.core.persistence.crud.authority import accept_decision

    repo = await insert_repo(async_session)
    ids = await bulk_upsert_decisions(
        async_session,
        repo.id,
        [
            _decision(
                "Collapse unchanged hook re-reads",
                files=_COMMIT_FILES,
                scope_basis=SCOPE_BASIS_FOOTPRINT,
            )
        ],
    )
    rec = await async_session.get(DecisionRecord, ids[0])
    rec.rationale = "because the reads were measured redundant"

    await accept_decision(
        async_session,
        rec,
        accepter="tester",
        scope=[_MECHANISM],
        evidence=["abc1234"],
    )

    refreshed = await async_session.get(DecisionRecord, ids[0])
    assert refreshed.scope_basis == SCOPE_BASIS_STATED
    assert json.loads(refreshed.affected_files_json) == [_MECHANISM]


async def test_accepting_without_a_scope_leaves_the_basis_alone(async_session):
    """No scope argument means no claim about files, so nothing changes."""
    from repowise.core.persistence.crud.authority import accept_decision

    repo = await insert_repo(async_session)
    ids = await bulk_upsert_decisions(
        async_session,
        repo.id,
        [_decision("Narrow", files=[_MECHANISM], source="inline_marker")],
    )
    rec = await async_session.get(DecisionRecord, ids[0])
    rec.rationale = "measured"
    rec.scope_basis = SCOPE_BASIS_FOOTPRINT

    await accept_decision(
        async_session, rec, accepter="tester", evidence=["abc1234"]
    )

    refreshed = await async_session.get(DecisionRecord, ids[0])
    assert refreshed.scope_basis == SCOPE_BASIS_FOOTPRINT


# ---------------------------------------------------------------------------
# Session scope: proximity is not a claim
# ---------------------------------------------------------------------------

_A1 = "pkg/area_a/one.py"
_A2 = "pkg/area_a/two.py"
_B1 = "pkg/area_b/one.py"


def _session(title: str, *, files: list[str], kind: str = "architectural") -> dict:
    payload = _decision(title, files=files, source="session")
    payload["kind"] = kind
    return payload


async def test_backfill_marks_a_session_record_spanning_directories(async_session):
    repo = await insert_repo(async_session)
    ids = await bulk_upsert_decisions(
        async_session, repo.id, [_session("Restated while editing", files=[_A1, _B1])]
    )
    assert await get_governing_decisions(async_session, repo.id, _A1) != []

    assert await backfill_session_scope_basis(async_session, repo.id) == 1

    rec = await async_session.get(DecisionRecord, ids[0])
    assert rec.scope_basis == SCOPE_BASIS_PROXIMITY
    assert json.loads(rec.affected_files_json) == [_A1, _B1]
    assert await get_governing_decisions(async_session, repo.id, _A1) == []


async def test_backfill_leaves_a_session_record_inside_one_directory(async_session):
    repo = await insert_repo(async_session)
    await bulk_upsert_decisions(
        async_session, repo.id, [_session("About this area", files=[_A1, _A2])]
    )
    assert await backfill_session_scope_basis(async_session, repo.id) == 0
    assert await get_governing_decisions(async_session, repo.id, _A1) != []


async def test_backfill_scopes_an_agreement_to_the_repository(async_session):
    """It governs how the work is conducted, so no file is what it is about."""
    repo = await insert_repo(async_session)
    ids = await bulk_upsert_decisions(
        async_session,
        repo.id,
        [_session("Never attribute the agent", files=[_A1], kind="agreement")],
    )
    assert await backfill_session_scope_basis(async_session, repo.id) == 1
    rec = await async_session.get(DecisionRecord, ids[0])
    assert rec.scope_basis == SCOPE_BASIS_REPOSITORY
    assert await get_governing_decisions(async_session, repo.id, _A1) == []


async def test_the_session_backfill_leaves_other_sources_alone(async_session):
    repo = await insert_repo(async_session)
    await bulk_upsert_decisions(
        async_session,
        repo.id,
        [_decision("Marker", files=[_A1, _B1], source="inline_marker")],
    )
    assert await backfill_session_scope_basis(async_session, repo.id) == 0
    assert await get_governing_decisions(async_session, repo.id, _A1) != []


async def test_the_session_backfill_is_idempotent(async_session):
    repo = await insert_repo(async_session)
    await bulk_upsert_decisions(
        async_session, repo.id, [_session("Wide", files=[_A1, _B1])]
    )
    assert await backfill_session_scope_basis(async_session, repo.id) == 1
    assert await backfill_session_scope_basis(async_session, repo.id) == 0


# ---------------------------------------------------------------------------
# Pruning scope entries the index does not hold
# ---------------------------------------------------------------------------


async def _index_files(session, repo_id, paths: list[str]) -> None:
    """Enough file nodes to clear the unbuilt-graph guard."""
    filler = [f"pkg/filler/f{i:03d}.py" for i in range(60)]
    for node_id in [*paths, *filler]:
        session.add(
            GraphNode(
                repository_id=repo_id,
                node_id=node_id,
                node_type="file",
                name=node_id.rsplit("/", 1)[-1],
            )
        )
    await session.flush()


async def test_prune_drops_a_path_the_index_does_not_hold(async_session):
    """A transcript names plan docs and sibling checkouts; they resolve on
    disk and are still not this codebase."""
    repo = await insert_repo(async_session)
    await _index_files(async_session, repo.id, [_A1])
    ids = await bulk_upsert_decisions(
        async_session,
        repo.id,
        [_session("Mixed", files=[_A1, "local-stash/plan/NOTES.md"])],
    )

    assert await prune_unindexed_scope_files(async_session, repo.id) == 1

    rec = await async_session.get(DecisionRecord, ids[0])
    assert json.loads(rec.affected_files_json) == [_A1]
    assert await get_governing_decisions(async_session, repo.id, _A1) != []
    rows = (
        (
            await async_session.execute(
                select(DecisionNodeLink).where(DecisionNodeLink.decision_id == ids[0])
            )
        )
        .scalars()
        .all()
    )
    assert "local-stash/plan/NOTES.md" not in {r.node_id for r in rows}


async def test_prune_does_nothing_when_the_graph_looks_unbuilt(async_session):
    """Pruning against a failed graph build would empty every scope."""
    repo = await insert_repo(async_session)
    ids = await bulk_upsert_decisions(
        async_session,
        repo.id,
        [_session("Mixed", files=[_A1, "local-stash/plan/NOTES.md"])],
    )
    assert await prune_unindexed_scope_files(async_session, repo.id) == 0
    rec = await async_session.get(DecisionRecord, ids[0])
    assert len(json.loads(rec.affected_files_json)) == 2


async def test_prune_is_idempotent(async_session):
    repo = await insert_repo(async_session)
    await _index_files(async_session, repo.id, [_A1])
    await bulk_upsert_decisions(
        async_session, repo.id, [_session("Mixed", files=[_A1, "local-stash/x.md"])]
    )
    assert await prune_unindexed_scope_files(async_session, repo.id) == 1
    assert await prune_unindexed_scope_files(async_session, repo.id) == 0


async def test_prune_rewrites_the_module_list_with_the_files(async_session):
    repo = await insert_repo(async_session)
    await _index_files(async_session, repo.id, [_A1])
    ids = await bulk_upsert_decisions(
        async_session, repo.id, [_session("Mixed", files=[_A1, "outside/gone.py"])]
    )
    await prune_unindexed_scope_files(async_session, repo.id)
    rec = await async_session.get(DecisionRecord, ids[0])
    assert json.loads(rec.affected_modules_json) == ["pkg/area_a"]