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
"""The conventions source: majority import patterns proposed from the graph.
Each hazard has an ablation partner, and no count ever makes a record active.
"""
from __future__ import annotations
from datetime import datetime
from pathlib import Path
import pytest
from repowise.core.analysis.decisions.conventions import (
MAX_PROPOSALS,
MIN_RATIO,
MIN_THROUGH,
scan_conventions,
)
from repowise.core.analysis.decisions.extractor import DecisionExtractor
from repowise.core.analysis.decisions.gate import apply_substring_gate
from repowise.core.ingestion.graph import GraphBuilder
from repowise.core.ingestion.models import FileInfo
from repowise.core.ingestion.parser import parse_file
from repowise.server.mcp_server._helpers import _compute_alignment
WRAPPER = "net/client.py"
WRAPPER_SRC = "import httpx\n\n\ndef get(url):\n return httpx.get(url)\n\n\ndef other_helper():\n return 1\n"
DIRECT_SRC = "import httpx\n\n\ndef raw(url):\n return httpx.get(url)\n"
def _language(path: str) -> str:
return {"py": "python", "go": "go", "ts": "typescript", "mod": "go"}[path.rsplit(".", 1)[1]]
def _build(tmp_path: Path, files: dict[str, str]):
"""Write *files*, parse them with the real parser, and build the graph."""
parsed_files = []
source_map: dict[str, bytes] = {}
for rel, src in files.items():
target = tmp_path / rel
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text(src, encoding="utf-8")
raw = src.encode("utf-8")
info = FileInfo(
path=rel,
abs_path=str(target),
language=_language(rel),
size_bytes=len(raw),
git_hash="",
last_modified=datetime.now(),
is_test=rel.startswith("tests/"),
is_config=False,
is_api_contract=False,
is_entry_point=False,
)
parsed_files.append(parse_file(info, raw))
source_map[rel] = raw
builder = GraphBuilder(repo_path=tmp_path)
for pf in parsed_files:
builder.add_file(pf)
builder.build()
return builder.graph(), parsed_files, source_map
def _repo(through: int = 6, direct: int = 1, **extra: str) -> dict[str, str]:
files = {"net/__init__.py": "", "svc/__init__.py": "", WRAPPER: WRAPPER_SRC}
for i in range(through):
files[f"svc/user{i}.py"] = f"from net.client import get\n\n\ndef load{i}():\n return get('u')\n"
for i in range(direct):
files[f"svc/raw{i}.py"] = DIRECT_SRC
files.update(extra)
return files
GO_CLIENT = '''package client
import "net/http"
func Get(u string) (*http.Response, error) {
return http.Get(u)
}
func Other() int {
return 1
}
'''
GO_CALLER = '''package svc
import "example.com/x/client"
func F() {
client.Get("u")
}
'''
GO_RAW = '''package raw
import "net/http"
func R() {
http.Get("u")
}
'''
def _go_repo(callers: int, direct: int) -> dict[str, str]:
files = {"go.mod": "module example.com/x\n\ngo 1.22\n", "client/client.go": GO_CLIENT}
for i in range(callers):
files[f"svc{i}/main.go"] = GO_CALLER
for i in range(direct):
files[f"raw{i or ''}/raw.go"] = GO_RAW
return files
def _scan(tmp_path: Path, files: dict[str, str], **kw):
graph, parsed, source_map = _build(tmp_path, files)
return scan_conventions(graph, parsed, source_map, tmp_path, **kw)
class TestOneWrapperOneLibrary:
def test_proposes_exactly_one_candidate_with_the_counts(self, tmp_path):
out = _scan(tmp_path, _repo(through=6, direct=1))
assert len(out) == 1
d = out[0]
assert d.title == f"httpx goes through {WRAPPER}"
assert d.decision == f"6 of 7 files reach httpx through {WRAPPER}; 1 import it directly."
assert d.consequences == ["svc/raw0.py imports httpx directly"]
assert d.affected_files == [WRAPPER, "svc/raw0.py"]
assert d.affected_modules == ["net", "svc"]
assert d.evidence_file == WRAPPER
assert d.evidence_line == 4
assert d.tags == ["convention", "network"]
assert d.source == "conventions"
assert d.status == "proposed"
assert d.staleness_score == pytest.approx(1 / 7, abs=1e-3)
assert f"Wrapper symbol {WRAPPER}::get at {WRAPPER}:4" in d.context
assert "svc/user0.py:5" in d.context
def test_the_gate_reads_the_counts_as_exact(self, tmp_path):
kept, rejected = apply_substring_gate(_scan(tmp_path, _repo()))
assert rejected == 0
assert kept[0].verification == "exact"
assert kept[0].source_text == ""
assert kept[0].source_quote.startswith("6 of 7 files reach httpx")
def test_no_direct_importers_is_a_clean_majority(self, tmp_path):
out = _scan(tmp_path, _repo(through=6, direct=0))
assert len(out) == 1
assert out[0].decision.endswith("; 0 import it directly.")
assert out[0].consequences == []
assert out[0].staleness_score == 0.0
class TestThresholds:
def test_below_min_through_emits_nothing(self, tmp_path):
assert _scan(tmp_path, _repo(through=MIN_THROUGH - 1, direct=0)) == []
def test_at_min_through_emits(self, tmp_path):
assert len(_scan(tmp_path, _repo(through=MIN_THROUGH, direct=0))) == 1
def test_too_many_direct_importers_emits_nothing(self, tmp_path):
through = MIN_RATIO * 2
assert _scan(tmp_path, _repo(through=through, direct=3)) == []
def test_direct_importers_at_the_ratio_still_emit(self, tmp_path):
through = MIN_RATIO * 2
assert len(_scan(tmp_path, _repo(through=through, direct=2))) == 1
def test_the_cap_holds_and_orders_by_reach(self, tmp_path):
files = _repo(through=6, direct=0)
files["os/runner.py"] = "import subprocess\n\n\ndef run(cmd):\n return subprocess.run(cmd)\n"
for i in range(8):
files[f"jobs/job{i}.py"] = "from os.runner import run\n\n\ndef go():\n return run('x')\n"
files["jobs/__init__.py"] = ""
files["os/__init__.py"] = ""
out = _scan(tmp_path, files)
assert [d.title.split(" goes")[0] for d in out] == ["subprocess", "httpx"]
assert len(_scan(tmp_path, files, limit=1)) == 1
assert MAX_PROPOSALS >= 2
class TestHazards:
def test_test_files_count_on_neither_side(self, tmp_path):
files = _repo(through=6, direct=1)
files["tests/test_client.py"] = "import httpx\nfrom net.client import get\n\n\ndef test_it():\n assert httpx and get\n"
out = _scan(tmp_path, files)
assert out[0].decision.startswith("6 of 7 files")
def test_the_wrapper_own_file_is_not_a_direct_importer(self, tmp_path):
out = _scan(tmp_path, _repo(through=6, direct=0))
assert out[0].decision.endswith("; 0 import it directly.")
def test_two_confirmed_wrappers_emit_nothing(self, tmp_path):
files = _repo(through=6, direct=0)
files["net/client2.py"] = WRAPPER_SRC
for i in range(6):
files[f"svc/second{i}.py"] = "from net.client2 import get\n\n\ndef f():\n return get('u')\n"
assert _scan(tmp_path, files) == []
def test_co_location_is_not_wrapping(self, tmp_path):
files = _repo(through=6, direct=0)
# The library is imported and used at module level, but no callable
# in the file reaches it, so importing the file is not reaching httpx.
files[WRAPPER] = "import httpx\n\nTIMEOUT = httpx.Timeout(5)\n\n\ndef get(url):\n return url\n"
assert _scan(tmp_path, files) == []
def test_a_reference_inside_a_string_or_comment_does_not_confirm(self, tmp_path):
files = _repo(through=6, direct=0)
files[WRAPPER] = (
"import httpx\n\n\ndef get(url):\n # httpx.get(url) used to live here\n"
" return 'httpx.get(' + url\n"
)
assert _scan(tmp_path, files) == []
def test_importing_the_file_for_another_helper_is_not_reaching(self, tmp_path):
files = _repo(through=0, direct=0)
for i in range(6):
files[f"svc/helper{i}.py"] = "from net.client import other_helper\n\n\ndef f():\n return other_helper()\n"
assert _scan(tmp_path, files) == []
def test_importing_the_module_whole_does_reach(self, tmp_path):
files = _repo(through=0, direct=0)
for i in range(6):
files[f"svc/whole{i}.py"] = "from net import client\n\n\ndef f():\n return client.get('u')\n"
out = _scan(tmp_path, files)
assert len(out) == 1
assert out[0].decision.startswith("6 of 6 files")
def test_an_untyped_library_emits_nothing(self, tmp_path):
files = _repo(through=6, direct=0)
files[WRAPPER] = "import somelib\n\n\ndef get(url):\n return somelib.get(url)\n"
assert _scan(tmp_path, files) == []
def test_a_barrel_reexport_is_neither_wrapper_nor_direct(self, tmp_path):
graph, parsed, source_map = _build(tmp_path, _repo(through=6, direct=1))
# Mark the direct importer's statement as a re-export: the name is
# forwarded, not used, so it drops out of the direct count.
raw = next(pf for pf in parsed if pf.file_info.path == "svc/raw0.py")
raw.imports[0].is_reexport = True
out = scan_conventions(graph, parsed, source_map, tmp_path)
assert out[0].decision.endswith("; 0 import it directly.")
def test_a_go_wrapper_is_counted_by_package(self, tmp_path):
files = _go_repo(callers=6, direct=1)
out = _scan(tmp_path, files)
assert len(out) == 1
d = out[0]
assert d.title == "net/http goes through client/client.go"
assert d.decision == "6 of 7 packages reach net/http through client/client.go; 1 import it directly."
assert d.consequences == ["raw imports net/http directly"]
assert d.affected_files == ["client/client.go", "raw/raw.go"]
assert "call edges" in d.rationale
assert "svc0/main.go:" in d.context
def test_a_go_package_importing_the_wrapper_without_calling_it_does_not_reach(self, tmp_path):
files = _go_repo(callers=0, direct=0)
for i in range(6):
files[f"svc{i}/main.go"] = GO_CALLER.replace("client.Get(\"u\")", "client.Other()")
assert _scan(tmp_path, files) == []
def test_two_go_files_in_one_package_are_one_wrapper(self, tmp_path):
files = _go_repo(callers=6, direct=0)
files["client/more.go"] = GO_CLIENT.replace("Get(u string) (*http.Response, error)", "Post(u string) (*http.Response, error)").replace("http.Get(u)", "http.Post(u, \"\", nil)")
out = _scan(tmp_path, files)
assert len(out) == 1
assert out[0].decision.startswith("6 of 6 packages")
class TestOnlyAPersonAccepts:
@pytest.mark.parametrize("through", [MIN_THROUGH, 50, 200])
def test_no_count_produces_an_active_record(self, tmp_path, through):
out = _scan(tmp_path, _repo(through=through, direct=0))
assert out and all(d.status == "proposed" for d in out)
def test_a_conventions_candidate_governs_nothing_until_accepted(self):
result = _compute_alignment(
WRAPPER, [{"id": "c1", "title": f"httpx goes through {WRAPPER}"}], [], {}
)
assert result["active_count"] == 0
assert result["candidate_count"] == 1
class TestExtractorWiring:
async def test_extract_all_runs_the_source_and_gates_it(self, tmp_path):
graph, parsed, source_map = _build(tmp_path, _repo())
ex = DecisionExtractor(
repo_path=tmp_path, graph=graph, parsed_files=parsed, source_map=source_map
)
report = await ex.extract_all(enabled_sources=["conventions"])
assert report.by_source == {"conventions": 1}
assert report.decisions[0].verification == "exact"
async def test_no_graph_means_no_candidates(self, tmp_path):
assert await DecisionExtractor(repo_path=tmp_path).scan_conventions() == []
class TestBoundInstance:
"""The second wrapper shape: a client built once at module level."""
TS_WRAPPER = 'import axios from "axios";\n\nexport const service = axios.create({ baseURL: "/api" });\n\nexport const TIMEOUT = 5000;\n'
def _ts_repo(self, users: int, direct: int = 0, readers: int = 0) -> dict[str, str]:
files = {"src/utils/request.ts": self.TS_WRAPPER}
for i in range(users):
files[f"src/api/user{i}.ts"] = 'import { service } from "../utils/request";\n\nexport function load() {\n return service.get("/u");\n}\n'
for i in range(direct):
files[f"src/api/raw{i}.ts"] = 'import axios from "axios";\n\nexport function raw() {\n return axios.get("/u");\n}\n'
for i in range(readers):
files[f"src/api/reader{i}.ts"] = 'import { TIMEOUT } from "../utils/request";\n\nexport function wait() {\n return TIMEOUT * 2;\n}\n'
return files
def test_a_called_instance_is_a_wrapper(self, tmp_path):
out = _scan(tmp_path, self._ts_repo(users=6, direct=1))
assert len(out) == 1
d = out[0]
assert d.title == "axios goes through src/utils/request.ts"
assert d.decision.startswith("6 of 7 files reach axios")
assert d.consequences == ["src/api/raw0.ts imports axios directly"]
assert "Wrapper instance src/utils/request.ts::service" in d.context
assert "src/api/user0.ts:4" in d.context
def test_a_setting_that_is_only_read_is_not_a_wrapper(self, tmp_path):
# Six files import TIMEOUT and read it; nothing calls through it.
files = self._ts_repo(users=0, readers=6)
files["src/utils/request.ts"] = 'import axios from "axios";\n\nexport const TIMEOUT = axios.defaults.timeout;\n'
assert _scan(tmp_path, files) == []
def test_readers_do_not_count_toward_the_instance(self, tmp_path):
out = _scan(tmp_path, self._ts_repo(users=6, readers=6))
assert len(out) == 1
assert out[0].decision.startswith("6 of 6 files")
def test_a_python_client_instance_is_a_wrapper(self, tmp_path):
files = {
"net/__init__.py": "",
"svc/__init__.py": "",
"net/client.py": "import httpx\n\nclient = httpx.Client(base_url='http://x')\n",
}
for i in range(6):
files[f"svc/user{i}.py"] = "from net.client import client\n\n\ndef load():\n return client.get('/u')\n"
out = _scan(tmp_path, files)
assert len(out) == 1
assert "Wrapper instance net/client.py::client" in out[0].context
assert out[0].evidence_line == 3