Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
"""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"]