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
"""Review lanes over the acceptance join.
The lane a record is in answers "who accepted this and does it still bind",
which the ``status`` column cannot: it is a projection every writer keeps in
step, so it agrees right up until something writes it without an acceptance.
These tests hold the two apart, including on a record stored ``active`` that
nobody ever accepted.
"""
from __future__ import annotations
import pytest
from httpx import AsyncClient
from repowise.core.persistence import crud
from repowise.core.persistence.database import get_session
from tests.unit.server.conftest import create_test_repo
async def _seed(
session_factory,
repo_id: str,
*,
title: str,
status: str = "proposed",
accept: bool = False,
scope: list[str] | None = None,
staleness: float = 0.0,
) -> str:
"""One record, accepted or not, independently of its status column."""
async with get_session(session_factory) as session:
rec = await crud.upsert_decision(
session,
repository_id=repo_id,
title=title,
status=status,
context="ctx",
# Distinct per seed: identity is the evidence, so ten records
# sharing one body over one file are one decision, not ten.
decision=f"dec for {title}",
rationale="why",
source="inline_marker",
affected_files=["src/app.py"] if scope is None else scope,
evidence_file="src/app.py",
confidence=0.5,
)
rec.staleness_score = staleness
# ``upsert_decision`` refuses to write ``active``: extraction cannot
# confer authority. A record stored active with no acceptance behind it
# therefore only arises from a pre-split store, which is exactly the
# seam under test, so write the column directly to reproduce one.
if status == "active" and not accept:
rec.status = "active"
if accept:
await crud.accept_decision(
session, rec, accepter="tester", evidence=["seed"]
)
# accept_decision projects the column back to ``active``; restore
# the staleness the seed asked for, which the projection does not
# touch and ``effective_currency`` reads.
rec.staleness_score = staleness
await session.flush()
return rec.id
async def _lane(client: AsyncClient, repo_id: str, lane: str) -> list[dict]:
res = await client.get(
f"/api/repos/{repo_id}/decisions", params={"lane": lane, "limit": 500}
)
assert res.status_code == 200, res.text
return res.json()
@pytest.mark.asyncio
async def test_an_active_status_without_an_acceptance_is_a_candidate(
client: AsyncClient, app
) -> None:
"""The seam, at the wire. The column says active; nobody accepted it."""
repo = await create_test_repo(client)
sf = app.state.session_factory
await _seed(sf, repo["id"], title="Never accepted", status="active")
candidates = await _lane(client, repo["id"], "candidates")
governing = await _lane(client, repo["id"], "governing")
assert [d["title"] for d in candidates] == ["Never accepted"]
assert candidates[0]["status"] == "active"
assert candidates[0]["currency"] is None
assert governing == []
@pytest.mark.asyncio
async def test_an_accepted_record_governs_and_carries_its_currency(
client: AsyncClient, app
) -> None:
repo = await create_test_repo(client)
sf = app.state.session_factory
await _seed(sf, repo["id"], title="A rule", accept=True)
governing = await _lane(client, repo["id"], "governing")
assert [d["title"] for d in governing] == ["A rule"]
assert governing[0]["currency"] == "active"
@pytest.mark.asyncio
async def test_a_decision_whose_files_moved_lands_in_needs_review(
client: AsyncClient, app
) -> None:
"""It still governs. ``needs_review`` is a decision to re-read, not to drop."""
repo = await create_test_repo(client)
sf = app.state.session_factory
await _seed(sf, repo["id"], title="Drifted", accept=True, staleness=0.9)
assert [d["title"] for d in await _lane(client, repo["id"], "needs_review")] == [
"Drifted"
]
assert [d["title"] for d in await _lane(client, repo["id"], "governing")] == [
"Drifted"
]
assert await _lane(client, repo["id"], "active") == []
@pytest.mark.asyncio
async def test_a_scopeless_acceptance_is_uncheckable_and_does_not_govern(
client: AsyncClient, app
) -> None:
"""Only reachable through the manifest, which accepts with an artifact.
The acceptance contract refuses a scopeless acceptance at the API, so this
seeds one directly to prove the read side classifies it rather than
reporting it as a rule.
"""
repo = await create_test_repo(client)
sf = app.state.session_factory
did = await _seed(sf, repo["id"], title="Names nothing", accept=True)
async with get_session(sf) as session:
rec = await crud.get_decision(session, did)
rec.affected_files_json = "[]"
rec.affected_modules_json = "[]"
await session.flush()
assert [d["title"] for d in await _lane(client, repo["id"], "uncheckable")] == [
"Names nothing"
]
assert await _lane(client, repo["id"], "governing") == []
@pytest.mark.asyncio
async def test_withdrawing_authority_moves_a_record_to_history(
client: AsyncClient, app
) -> None:
repo = await create_test_repo(client)
sf = app.state.session_factory
did = await _seed(sf, repo["id"], title="Retired", accept=True)
res = await client.patch(
f"/api/repos/{repo['id']}/decisions/{did}", json={"status": "deprecated"}
)
assert res.status_code == 200, res.text
assert [d["title"] for d in await _lane(client, repo["id"], "history")] == [
"Retired"
]
assert await _lane(client, repo["id"], "governing") == []
@pytest.mark.asyncio
async def test_a_dismissed_decision_stays_in_history(client: AsyncClient, app) -> None:
"""A withdrawn decision is history; a dismissed candidate is a tombstone.
``dismiss_candidate`` writes ``status="dismissed"`` for both, and the
default listing hides that status, so the accepted one used to fall out of
every lane and every badge while the History copy promised it was kept.
"""
repo = await create_test_repo(client)
sf = app.state.session_factory
did = await _seed(sf, repo["id"], title="Withdrawn rule", accept=True)
await _seed(sf, repo["id"], title="Rejected guess")
async with get_session(sf) as session:
from repowise.core.persistence.crud.authority import dismiss_candidate
for title in ("Withdrawn rule", "Rejected guess"):
rec = await crud.find_decision_by_title(
session,
repo["id"],
title,
source="inline_marker",
evidence_file="src/app.py",
)
await dismiss_candidate(session, rec, accepter="tester")
await session.flush()
assert [d["title"] for d in await _lane(client, repo["id"], "history")] == [
"Withdrawn rule"
]
assert await _lane(client, repo["id"], "candidates") == []
counts = (
await client.get(f"/api/repos/{repo['id']}/decisions/lane-counts")
).json()
assert counts["history"] == 1
assert counts["candidates"] == 0
assert counts["total"] == 1
assert did
@pytest.mark.asyncio
async def test_the_governing_lane_pages_over_its_own_rows(
client: AsyncClient, app
) -> None:
"""It filters accepted rows by currency, so its page is cut after that.
Cutting first returned an empty tab on a repository whose newest accepted
records had all been superseded.
"""
repo = await create_test_repo(client)
sf = app.state.session_factory
from repowise.core.persistence.crud.authority import record_acceptance
for i in range(4):
did = await _seed(sf, repo["id"], title=f"Retired {i}", accept=True)
async with get_session(sf) as session:
rec = await crud.get_decision(session, did)
await record_acceptance(
session,
rec,
action="superseded",
currency="superseded",
accepter="tester",
kind="person",
evidence=["seed"],
)
await session.flush()
await _seed(sf, repo["id"], title="The only rule", accept=True)
res = await client.get(
f"/api/repos/{repo['id']}/decisions",
params={"lane": "governing", "limit": 2},
)
assert res.status_code == 200, res.text
assert [d["title"] for d in res.json()] == ["The only rule"]
@pytest.mark.asyncio
async def test_lane_counts_partition_the_repository(
client: AsyncClient, app
) -> None:
repo = await create_test_repo(client)
sf = app.state.session_factory
await _seed(sf, repo["id"], title="Rule", accept=True)
await _seed(sf, repo["id"], title="Drifted", accept=True, staleness=0.9)
await _seed(sf, repo["id"], title="Candidate one")
await _seed(sf, repo["id"], title="Candidate two", status="active")
res = await client.get(f"/api/repos/{repo['id']}/decisions/lane-counts")
assert res.status_code == 200, res.text
counts = res.json()
assert counts["active"] == 1
assert counts["needs_review"] == 1
assert counts["uncheckable"] == 0
assert counts["history"] == 0
assert counts["candidates"] == 2
# The five exclusive lanes add up, and governing rolls up the two that bind.
assert (
counts["active"]
+ counts["needs_review"]
+ counts["uncheckable"]
+ counts["history"]
+ counts["candidates"]
== counts["total"]
)
assert counts["governing"] == 2
@pytest.mark.asyncio
async def test_lane_counts_and_status_counts_are_different_questions(
client: AsyncClient, app
) -> None:
"""A record written straight to the column is counted by one and not the other."""
repo = await create_test_repo(client)
sf = app.state.session_factory
await _seed(sf, repo["id"], title="Never accepted", status="active")
status_counts = (
await client.get(f"/api/repos/{repo['id']}/decisions/counts")
).json()
lane_counts = (
await client.get(f"/api/repos/{repo['id']}/decisions/lane-counts")
).json()
assert status_counts["active"] == 1
assert lane_counts["active"] == 0
assert lane_counts["candidates"] == 1
@pytest.mark.asyncio
async def test_a_lane_page_is_a_page_of_that_lane(client: AsyncClient, app) -> None:
"""The filter runs before the page is cut, not after it.
Priority sort leads with accepted records, so a lane filtered after the cut
returned an empty Candidates page on a store holding hundreds of them. This
seeds more accepted records than the page holds and asks for the lane
behind them.
"""
repo = await create_test_repo(client)
sf = app.state.session_factory
for i in range(6):
await _seed(sf, repo["id"], title=f"Rule {i}", accept=True)
await _seed(sf, repo["id"], title="The only candidate")
res = await client.get(
f"/api/repos/{repo['id']}/decisions",
params={"lane": "candidates", "limit": 3},
)
assert res.status_code == 200, res.text
assert [d["title"] for d in res.json()] == ["The only candidate"]
@pytest.mark.asyncio
async def test_a_derived_lane_pages_over_its_own_rows(
client: AsyncClient, app
) -> None:
"""``needs_review`` is derived, so its page is cut after the derivation."""
repo = await create_test_repo(client)
sf = app.state.session_factory
for i in range(4):
await _seed(sf, repo["id"], title=f"Fresh {i}", accept=True)
for i in range(3):
await _seed(
sf, repo["id"], title=f"Drifted {i}", accept=True, staleness=0.9
)
first = await client.get(
f"/api/repos/{repo['id']}/decisions",
params={"lane": "needs_review", "limit": 2, "offset": 0},
)
second = await client.get(
f"/api/repos/{repo['id']}/decisions",
params={"lane": "needs_review", "limit": 2, "offset": 2},
)
titles = [d["title"] for d in first.json()] + [
d["title"] for d in second.json()
]
assert len(first.json()) == 2
assert len(second.json()) == 1
assert sorted(titles) == ["Drifted 0", "Drifted 1", "Drifted 2"]
@pytest.mark.asyncio
async def test_an_unknown_lane_is_rejected_rather_than_ignored(
client: AsyncClient, app
) -> None:
"""A misspelt lane must not return an unfiltered page that reads as the lane."""
repo = await create_test_repo(client)
res = await client.get(
f"/api/repos/{repo['id']}/decisions", params={"lane": "governng"}
)
assert res.status_code == 422
@pytest.mark.asyncio
async def test_the_lane_parameter_is_optional(client: AsyncClient, app) -> None:
"""Omitting it lists everything, so an older client keeps working."""
repo = await create_test_repo(client)
sf = app.state.session_factory
await _seed(sf, repo["id"], title="Rule", accept=True)
await _seed(sf, repo["id"], title="Candidate")
res = await client.get(f"/api/repos/{repo['id']}/decisions")
assert res.status_code == 200
assert len(res.json()) == 2
# ---------------------------------------------------------------------------
# Creating a record by hand
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
async def test_creating_with_a_scope_records_an_acceptance(
client: AsyncClient, app
) -> None:
repo = await create_test_repo(client)
res = await client.post(
f"/api/repos/{repo['id']}/decisions",
json={
"title": "Use JWT",
"decision": "Issue signed JWTs",
"rationale": "sessions did not survive a restart",
"affected_files": ["src/auth/service.py"],
},
)
assert res.status_code == 201, res.text
assert res.json()["status"] == "active"
assert [d["title"] for d in await _lane(client, repo["id"], "governing")] == [
"Use JWT"
]
@pytest.mark.asyncio
async def test_creating_without_a_scope_lands_a_candidate_rather_than_failing(
client: AsyncClient, app
) -> None:
"""The form and the acceptance contract have to agree.
An acceptance names what it governs, so a scopeless entry cannot be one.
Refusing the write instead would throw away every field the author did
fill in, and reported the gap in a failure toast after the fact; the
record is kept as a candidate, which is what ``repowise decision add``
does with the same input.
"""
repo = await create_test_repo(client)
res = await client.post(
f"/api/repos/{repo['id']}/decisions",
json={"title": "Use JWT", "decision": "Issue signed JWTs"},
)
assert res.status_code == 201, res.text
assert res.json()["status"] == "proposed"
assert [d["title"] for d in await _lane(client, repo["id"], "candidates")] == [
"Use JWT"
]
assert await _lane(client, repo["id"], "governing") == []
@pytest.mark.asyncio
async def test_a_scoped_entry_with_no_reason_also_lands_a_candidate(
client: AsyncClient, app
) -> None:
"""A scope is not enough on its own: the entry has to say why it binds.
Same rule as the scope-less case above, and the same reason for it. The
author's fields are kept rather than refused, and the record waits in
review until somebody states the reason.
"""
repo = await create_test_repo(client)
res = await client.post(
f"/api/repos/{repo['id']}/decisions",
json={
"title": "Use JWT",
"decision": "Issue signed JWTs",
"affected_files": ["src/auth/service.py"],
},
)
assert res.status_code == 201, res.text
assert res.json()["status"] == "proposed"
assert res.json()["affected_files"] == ["src/auth/service.py"]
assert await _lane(client, repo["id"], "governing") == []
@pytest.mark.asyncio
async def test_a_context_is_reason_enough_to_accept(client: AsyncClient, app) -> None:
"""``context`` is what forced the decision, so it is a why and it counts."""
repo = await create_test_repo(client)
res = await client.post(
f"/api/repos/{repo['id']}/decisions",
json={
"title": "Use JWT",
"decision": "Issue signed JWTs",
"context": "sessions were lost on every deploy",
"affected_files": ["src/auth/service.py"],
},
)
assert res.status_code == 201, res.text
assert res.json()["status"] == "active"
@pytest.mark.asyncio
async def test_a_module_only_scope_is_enough_to_accept(
client: AsyncClient, app
) -> None:
"""The scope is files *or* modules, the same pair the contract checks."""
repo = await create_test_repo(client)
res = await client.post(
f"/api/repos/{repo['id']}/decisions",
json={
"title": "Keep the resolver pure",
"decision": "No I/O in resolvers",
"rationale": "a resolver that reads the disk cannot be memoised",
"affected_modules": ["src/resolvers"],
},
)
assert res.status_code == 201, res.text
assert res.json()["status"] == "active"
@pytest.mark.asyncio
async def test_recording_a_title_again_cannot_withdraw_its_scope(
client: AsyncClient, app
) -> None:
"""The create endpoint upserts on the title, so it can hit a live decision.
``upsert_decision`` overwrites the scope with whatever the body carries. A
second post of an accepted decision's title with no files therefore cleared
the files it governed and left its acceptance row pointing at a record that
no longer binds, from a call that says "create". Refuse instead.
"""
repo = await create_test_repo(client)
body = {
"title": "Use JWT",
"decision": "Issue signed JWTs",
"rationale": "sessions did not survive a restart",
"affected_files": ["src/auth/service.py"],
}
first = await client.post(f"/api/repos/{repo['id']}/decisions", json=body)
assert first.status_code == 201, first.text
again = await client.post(
f"/api/repos/{repo['id']}/decisions",
json={"title": "Use JWT", "decision": "Issue signed JWTs"},
)
assert again.status_code == 409
assert "already an accepted decision" in again.json()["detail"]
governing = await _lane(client, repo["id"], "governing")
assert [d["title"] for d in governing] == ["Use JWT"]
assert governing[0]["affected_files"] == ["src/auth/service.py"]
@pytest.mark.asyncio
async def test_recording_a_title_again_with_a_scope_still_works(
client: AsyncClient, app
) -> None:
"""Only the withdrawal is refused, not an ordinary re-record."""
repo = await create_test_repo(client)
body = {
"title": "Use JWT",
"decision": "Issue signed JWTs",
"rationale": "sessions did not survive a restart",
"affected_files": ["src/auth/service.py"],
}
await client.post(f"/api/repos/{repo['id']}/decisions", json=body)
again = await client.post(
f"/api/repos/{repo['id']}/decisions",
json={**body, "affected_files": ["src/auth/service.py", "src/auth/mw.py"]},
)
assert again.status_code == 201, again.text
assert again.json()["affected_files"] == [
"src/auth/service.py",
"src/auth/mw.py",
]
@pytest.mark.asyncio
async def test_a_scopeless_re_record_of_a_candidate_is_fine(
client: AsyncClient, app
) -> None:
"""Nothing is withdrawn, because nothing was accepted."""
repo = await create_test_repo(client)
body = {"title": "Maybe JWT", "decision": "Consider signed JWTs"}
await client.post(f"/api/repos/{repo['id']}/decisions", json=body)
again = await client.post(f"/api/repos/{repo['id']}/decisions", json=body)
assert again.status_code == 201, again.text
assert again.json()["status"] == "proposed"
# ---------------------------------------------------------------------------
# The health rollup
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
async def test_health_counts_the_acceptance_not_the_status_column(
client: AsyncClient, app
) -> None:
"""The fifth governance reader, and the one a migrated store meets first.
Between the acceptance tables appearing and the classifier running, the
status column still says ``active`` for records nobody accepted. Counting
it made ``repowise decision health`` and ``get_why()`` report a hundred
governing decisions on a store whose acceptance log was empty, while every
other surface reported none.
"""
repo = await create_test_repo(client)
sf = app.state.session_factory
await _seed(sf, repo["id"], title="Never accepted", status="active")
await _seed(sf, repo["id"], title="A real rule", accept=True)
res = await client.get(f"/api/repos/{repo['id']}/decisions/health")
assert res.status_code == 200, res.text
summary = res.json()["summary"]
assert summary["active"] == 1
assert summary["proposed"] == 1
titles = [d["title"] for d in res.json()["proposed_awaiting_review"]]
assert "Never accepted" in titles
@pytest.mark.asyncio
async def test_a_candidate_does_not_make_a_hotspot_governed(
client: AsyncClient, app
) -> None:
"""``ungoverned_hotspots`` exists to say where nobody has decided anything.
A candidate naming a hotspot used to remove it from that list, which is
the one answer the list must not give.
"""
repo = await create_test_repo(client)
sf = app.state.session_factory
async with get_session(sf) as session:
from repowise.core.persistence.models import GitMetadata
session.add(
GitMetadata(
repository_id=repo["id"],
file_path="src/app.py",
is_hotspot=True,
temporal_hotspot_score=0.9,
)
)
await session.flush()
await _seed(sf, repo["id"], title="Names the hotspot", status="active")
res = await client.get(f"/api/repos/{repo['id']}/decisions/health")
assert res.status_code == 200, res.text
assert "src/app.py" in res.json()["ungoverned_hotspots"]
# Accepting it is what makes the file governed, and only then.
async with get_session(sf) as session:
rec = await crud.find_decision_by_title(
session,
repo["id"],
"Names the hotspot",
source="inline_marker",
evidence_file="src/app.py",
)
await crud.accept_decision(session, rec, accepter="tester", evidence=["x"])
await session.flush()
after = await client.get(f"/api/repos/{repo['id']}/decisions/health")
assert "src/app.py" not in after.json()["ungoverned_hotspots"]
@pytest.mark.asyncio
async def test_health_and_lane_counts_agree(client: AsyncClient, app) -> None:
"""Two rollups, one question. They disagreed before, and loudly."""
repo = await create_test_repo(client)
sf = app.state.session_factory
await _seed(sf, repo["id"], title="Rule", accept=True)
await _seed(sf, repo["id"], title="Drifted", accept=True, staleness=0.9)
await _seed(sf, repo["id"], title="Candidate", status="active")
health = (await client.get(f"/api/repos/{repo['id']}/decisions/health")).json()
lanes = (
await client.get(f"/api/repos/{repo['id']}/decisions/lane-counts")
).json()
assert health["summary"]["active"] == lanes["governing"]
assert health["summary"]["proposed"] == lanes["candidates"]
assert health["summary"]["stale"] == lanes["needs_review"]
assert health["summary"]["unscoped"] == lanes["uncheckable"]