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
"""What other layers say about a plan's target: annotate only, served on detail."""
from __future__ import annotations
import dataclasses
import re
from datetime import UTC, datetime
from pathlib import Path
from typing import get_args
from repowise.core.analysis.health.queue.eligibility import dead_spans
from repowise.core.analysis.health.refactoring.annotations import (
AnnotationFacts,
PlanAnnotations,
PlanRisk,
RiskKind,
annotate,
partner_rows,
)
from repowise.core.analysis.health.refactoring.models import RefactoringSuggestion
from repowise.core.analysis.health.refactoring.opportunity import compose_opportunities
from repowise.core.analysis.health.refactoring.preconditions import (
JUDGMENT_REASONS,
classify_step,
)
from repowise.core.analysis.health.refactoring.recommendations import (
build_recommendations,
stored_recommendation,
)
_TYPES = Path(__file__).resolve().parents[3] / "packages" / "types" / "src" / "refactoring.ts"
_WHEN = datetime(2026, 10, 1, tzinfo=UTC)
def plan(kind: str = "extract_method", **kwargs) -> RefactoringSuggestion:
payload = {
"refactoring_type": kind,
"file_path": "svc/orders.py",
"target_symbol": "handle",
"line_start": 20,
"line_end": 30,
"plan": {},
"evidence": {},
"impact_delta": 1.0,
"effort_bucket": "S",
"blast_radius": {"scope": "local"},
"confidence": "high",
"source_biomarker": "large_method",
}
payload.update(kwargs)
return RefactoringSuggestion(**payload)
def annotate_any(item: RefactoringSuggestion, facts: AnnotationFacts) -> bool:
notes = annotate(item, facts)
return bool(notes.governed_by or notes.risks or notes.co_change_partners)
def kinds(notes: PlanAnnotations) -> list[str]:
return [risk.kind for risk in notes.risks]
def test_a_decision_naming_the_file_governs_the_plan() -> None:
facts = AnnotationFacts(decisions={"svc/orders.py": [("d1", "Keep handlers flat")]})
notes = annotate(plan(), facts)
assert notes.governed_by == ("d1",)
assert notes.risks == (
PlanRisk(
"decision",
'Decision "Keep handlers flat" governs this file; check it allows this change first.',
"d1",
),
)
# A module derived from a decision's files does not govern its other files.
assert not annotate_any(plan(), AnnotationFacts(decisions={"svc": [("d1", "Keep handlers flat")]}))
def test_a_dead_target_says_delete_it_by_the_fix_first_rule() -> None:
rows = [
{
"kind": "unused_function",
"file_path": "svc/orders.py",
"symbol_name": "handle",
"start_line": 18,
"end_line": 40,
"confidence": 0.9,
"safe_to_delete": False,
"status": "open",
}
]
notes = annotate(plan(), AnnotationFacts(dead=dead_spans(rows)))
assert notes.risks[0].text == "Nothing reaches `handle`; delete it instead of refactoring it."
# A finding below the sure bar is not a dead target.
unsure = dead_spans([{**rows[0], "confidence": 0.5}])
assert not annotate_any(plan(), AnnotationFacts(dead=unsure))
def test_moving_a_public_method_names_its_callers() -> None:
moved = plan(
"move_method",
target_symbol="Order.total",
plan={"to_class": "Pricing"},
blast_radius={"callers": 3},
)
notes = annotate(moved, AnnotationFacts())
assert kinds(notes) == ["public_api"]
assert "3 callers" in notes.risks[0].text and "`Pricing`" in notes.risks[0].text
private = plan("move_method", target_symbol="Order._total", blast_radius={"callers": 3})
assert not annotate_any(private, AnnotationFacts())
# A split names its importers; a local extraction moves nothing out.
split = plan("split_file", line_start=None, blast_radius={"dependent_count": 1})
assert annotate(split, AnnotationFacts()).risks[0].text.startswith("1 file imports from")
assert not annotate_any(plan(blast_radius={"callers": 9}), AnnotationFacts())
def _recent(*shas: str) -> dict[str, tuple[datetime, str]]:
return {sha: (_WHEN, f"author-{index % 2}") for index, sha in enumerate(shas)}
def test_recent_commits_on_the_innermost_function_read_as_an_active_edit() -> None:
functions = {
"svc/orders.py": [
(1, 100, ("a", "b", "old")), # the module-level wrapper
(15, 35, ("c", "d")), # the function holding lines 20-30
]
}
notes = annotate(plan(), AnnotationFacts(functions=functions, recent=_recent("a", "b", "c", "d")))
assert kinds(notes) == ["active_edit"]
assert notes.risks[0].text.startswith("Changed in 2 commits by 2 authors")
one = annotate(plan(), AnnotationFacts(functions=functions, recent=_recent("c")))
assert not one.risks
def test_shallow_history_gives_no_active_edit_signal() -> None:
functions = {"svc/orders.py": [(15, 35, ("c", "d"))]}
assert not annotate_any(plan(), AnnotationFacts(functions=functions, recent=None))
def test_annotations_round_trip_through_the_stored_rank() -> None:
notes = PlanAnnotations(
governed_by=("d1",),
risks=(PlanRisk("decision", "text", "d1"),),
co_change_partners=(("svc/models.py", 7),),
)
assert PlanAnnotations.from_dict(notes.as_dict()) == notes
# Checked with nothing found is stored as ``{}``; never checked as nothing.
assert PlanAnnotations().as_dict() == {}
assert PlanAnnotations.from_dict({}) == PlanAnnotations()
assert PlanAnnotations.from_dict(None) is None
def test_plan_detail_carries_annotations_and_lists_do_not() -> None:
(item,) = build_recommendations([plan()])
item.suggestion.id = "row-1" # type: ignore[attr-defined]
notes = PlanAnnotations(
governed_by=("d1",),
risks=(PlanRisk("decision", "text", "d1"),),
co_change_partners=(("svc/models.py", 7),),
)
annotated = dataclasses.replace(item, annotations=notes)
assert annotated.as_dict() == item.as_dict()
detail = annotated.detail_dict()
assert detail["governed_by"] == ["d1"]
assert detail["risks"] == [{"kind": "decision", "text": "text", "ref": "d1"}]
assert detail["blast_radius"]["co_change_partners"] == partner_rows(notes.co_change_partners)
assert "co_change_partners" not in annotated.as_dict()["blast_radius"]
# Never checked: absent, so it cannot read as "checked, nothing found".
bare = item.detail_dict()
assert "governed_by" not in bare and "risks" not in bare
checked = dataclasses.replace(item, annotations=PlanAnnotations()).detail_dict()
assert checked["governed_by"] == [] and checked["risks"] == []
row = {"id": "row-1", **item.as_dict(), "rank_json": annotated.rank_facts()}
assert stored_recommendation(row).detail_dict() == detail # type: ignore[union-attr]
unannotated = {"id": "row-1", **item.as_dict(), "rank_json": item.rank_facts()}
assert "annotations" not in item.rank_facts()
older = stored_recommendation(unannotated)
assert older is not None and older.annotations is None
assert "risks" not in older.detail_dict()
def test_a_governing_decision_makes_a_proved_extraction_a_judgment_call() -> None:
assert classify_step(plan(), governed=False).classification == "mechanical"
assert "governed_by_decision" not in classify_step(plan(), governed=False).unknowns
governed = classify_step(plan(), governed=True)
assert governed.classification == "judgment"
assert governed.reasons == ("dataflow_proved_local_extraction", "governed_by_decision")
assert "governed_by_decision" in JUDGMENT_REASONS
(free,) = compose_opportunities([plan()], governed=set())
plan_id = free.steps[0].plan_id
(held,) = compose_opportunities([plan()], governed={plan_id})
assert free.mechanical_steps == 1
assert held.mechanical_steps == 0
assert held.steps[0].applicability.reasons[-1] == "governed_by_decision"
def test_the_risk_contract_matches_the_typescript_one() -> None:
source = _TYPES.read_text(encoding="utf-8")
union = re.search(r"type PlanRiskKind\s*=\s*([^;]+);", source)
assert union and set(re.findall(r'"([^"]+)"', union.group(1))) == set(get_args(RiskKind))
for name, sample in (
("PlanRisk", PlanRisk("decision", "t").as_dict()),
("PlanCoChangePartner", partner_rows([("a.py", 1)])[0]),
):
body = re.search(rf"interface {name} \{{([^}}]+)\}}", source)
assert body, name
assert set(re.findall(r"^\s*(\w+)\??:", body.group(1), re.MULTILINE)) == set(sample)
def test_composition_not_told_about_decisions_leaves_governance_unknown() -> None:
"""The CLI composes detector rows with no decisions read: unknown, not "not governed"."""
(live,) = compose_opportunities([plan()])
step = live.steps[0].applicability
assert "governed_by_decision" in step.unknowns
assert "governed_by_decision" not in step.reasons
def test_a_test_reading_the_split_function_source_is_a_risk(tmp_path: Path) -> None:
from repowise.core.analysis.health.refactoring.annotations import _sources_read
# ours ``test_full_upgrade_progress.py`` asserts on ``inspect.getsource(_run_upgrade)``.
(tmp_path / "tests").mkdir()
(tmp_path / "tests" / "test_flow.py").write_text(
"import inspect\nimport svc.orders as so\nsrc = inspect.getsource(so.handle)\n"
"lines = inspect.getsourcelines(other.handle)\n",
encoding="utf-8",
)
(tmp_path / "tests" / "test_plain.py").write_text(
"def test_x():\n assert handle()\n", encoding="utf-8"
)
files = ["tests/test_flow.py", "tests/test_plain.py", "tests/missing.py", "../outside.py"]
(tmp_path.parent / "outside.py").write_text("inspect.getsource(handle)\n", encoding="utf-8")
read = _sources_read(tmp_path, files)
# The alias reads as the module it names; a file outside the root is not read.
assert read == {"tests/test_flow.py": frozenset({"orders.handle", "other.handle"})}
facts = AnnotationFacts(sources_read=read)
notes = annotate(plan(), facts, ["tests/test_flow.py::test_a", "tests/test_plain.py::test_x"])
assert kinds(notes) == ["source_text"]
assert notes.risks[0].ref == "tests/test_flow.py"
assert "may read the source text of `handle`" in notes.risks[0].text
# Another module's ``handle``, a test the plan does not run, a plan that keeps the body.
other = AnnotationFacts(sources_read={"tests/test_flow.py": frozenset({"other.handle"})})
assert annotate(plan(), other, ["tests/test_flow.py::test_a"]).risks == ()
assert annotate(plan(), facts, ["tests/test_plain.py::test_x"]).risks == ()
assert annotate(plan("split_file"), facts, ["tests/test_flow.py::test_a"]).risks == ()
def test_changing_an_exported_symbol_warns_about_outside_callers() -> None:
exported = {"svc/orders.py": {"svc/orders.py::Orders::handle": "svc/__init__.py"}}
facts = AnnotationFacts(exported=exported)
notes = annotate(plan(target_symbol="Orders.handle"), facts)
assert notes.risks == (
PlanRisk(
"public_api",
"`Orders.handle` is exported from `svc/__init__.py`; changing its signature "
"breaks consumers outside the repo.",
),
)
# Only the exported symbol, never a neighbour in the same file.
assert not annotate_any(plan(target_symbol="_helper"), facts)
assert not annotate_any(plan(file_path="svc/other.py", target_symbol="handle"), facts)
def test_changing_an_exported_ruby_symbol_warns_about_outside_callers() -> None:
exported = {
"lib/mygem/client.rb": {"lib/mygem/client.rb::Client::get": "lib/mygem/client.rb"}
}
facts = AnnotationFacts(exported=exported)
notes = annotate(plan(file_path="lib/mygem/client.rb", target_symbol="Client.get"), facts)
assert notes.risks == (
PlanRisk(
"public_api",
"`Client.get` is exported from `lib/mygem/client.rb`; changing its signature "
"breaks consumers outside the repo.",
),
)
def test_changing_an_exported_jvm_symbol_warns_about_outside_callers() -> None:
exported = {
"lib/src/main/java/a/Api.java": {
"lib/src/main/java/a/Api.java::Api::run": "lib/src/main/java/a/Api.java"
}
}
facts = AnnotationFacts(exported=exported)
notes = annotate(
plan(file_path="lib/src/main/java/a/Api.java", target_symbol="Api.run"), facts
)
assert notes.risks == (
PlanRisk(
"public_api",
"`Api.run` is exported from `lib/src/main/java/a/Api.java`; changing its signature "
"breaks consumers outside the repo.",
),
)
def test_changing_an_exported_go_method_warns_about_outside_callers() -> None:
exported = {"lib/send.go": {"lib/send.go::Client::Send": "lib/send.go"}}
notes = annotate(
plan(file_path="lib/send.go", target_symbol="Client.Send"),
AnnotationFacts(exported=exported),
)
assert kinds(notes) == ["public_api"]
assert notes.risks[0].text.endswith("breaks consumers outside the repo.")
def test_changing_an_exported_csharp_method_warns_about_outside_callers() -> None:
exported = {
"src/Lib/Client.cs": {"src/Lib/Client.cs::Client::Send": "src/Lib/Client.cs"},
}
facts = AnnotationFacts(exported=exported)
notes = annotate(plan(file_path="src/Lib/Client.cs", target_symbol="Client.Send"), facts)
assert notes.risks == (
PlanRisk(
"public_api",
"`Client.Send` is exported from `src/Lib/Client.cs`; changing its signature "
"breaks consumers outside the repo.",
),
)
# Only the exported member, never a neighbour in the same file.
assert not annotate_any(plan(file_path="src/Lib/Client.cs", target_symbol="Retry"), facts)
def test_a_moved_exported_method_carries_one_public_api_risk() -> None:
exported = {
"svc/orders.py": {
"svc/orders.py::Order::total": "svc/__init__.py",
"svc/orders.py::Order": "svc/__init__.py",
"svc/orders.py::Pricing": "svc/__init__.py",
}
}
moved = plan(
"move_method",
target_symbol="Order.total",
plan={"from_class": "Order", "to_class": "Pricing"},
blast_radius={"callers": 2},
)
notes = annotate(moved, AnnotationFacts(exported=exported))
assert kinds(notes) == ["public_api"]
text = notes.risks[0].text
# Callers inside the repo first, then every exported symbol the plan changes.
assert text.startswith("`Order.total` has 2 callers")
assert "`Order` (from `svc/__init__.py`)" in text and "`Pricing`" in text
assert text.endswith("are exported; changing their signatures breaks consumers outside the repo.")