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
"""Golden tests for the C4 builder.
Each test seeds an in-memory DB with a tiny but realistic fixture
(repository + graph_nodes + graph_edges + external_systems) and then
asserts the shape of build_l1 / build_l2 / build_l3 output.
"""
from __future__ import annotations
import json
import pytest
from repowise.core.persistence import (
batch_upsert_graph_edges,
batch_upsert_graph_nodes,
bulk_upsert_external_systems,
link_graph_nodes_to_external_systems,
upsert_repository,
)
from repowise.core.persistence.models import (
DeadCodeFinding,
GitMetadata,
KnowledgeGraphProjectMeta,
)
from repowise.server.services import c4_builder
async def _seed_monorepo(session):
"""Two containers — packages/core and packages/web — with one cross-edge
and a single external dep on each side.
"""
repo = await upsert_repository(session, name="demo", local_path="/tmp/demo")
files = [
"packages/core/ingestion/parser.py",
"packages/core/ingestion/graph.py",
"packages/core/persistence/models.py",
"packages/web/app/page.tsx",
"packages/web/lib/api.ts",
]
nodes = [
{"node_id": f, "node_type": "file", "language": "python" if f.endswith(".py") else "typescript", "symbol_count": 1}
for f in files
]
# External nodes for imports
nodes.append({"node_id": "external:fastapi", "node_type": "file", "language": "python", "symbol_count": 0})
nodes.append({"node_id": "external:react", "node_type": "file", "language": "typescript", "symbol_count": 0})
await batch_upsert_graph_nodes(session, repo.id, nodes)
edges = [
# Within container
{"source_node_id": "packages/core/ingestion/parser.py", "target_node_id": "packages/core/ingestion/graph.py", "edge_type": "imports"},
# Cross container
{"source_node_id": "packages/web/lib/api.ts", "target_node_id": "packages/core/persistence/models.py", "edge_type": "imports"},
# To externals
{"source_node_id": "packages/core/ingestion/parser.py", "target_node_id": "external:fastapi", "edge_type": "imports"},
{"source_node_id": "packages/web/app/page.tsx", "target_node_id": "external:react", "edge_type": "imports"},
]
await batch_upsert_graph_edges(session, repo.id, edges)
externals = [
{"name": "fastapi", "display_name": "FastAPI", "ecosystem": "pypi", "category": "framework", "version": "0.110", "declared_in": "packages/core/pyproject.toml", "is_dev_dep": False},
{"name": "react", "display_name": "React", "ecosystem": "npm", "category": "framework", "version": "^18", "declared_in": "packages/web/package.json", "is_dev_dep": False},
]
id_map = await bulk_upsert_external_systems(session, repo.id, externals)
name_to_id = {name: sid for (name, _), sid in id_map.items()}
await link_graph_nodes_to_external_systems(session, repo.id, name_to_id)
await session.commit()
return repo
@pytest.mark.asyncio
async def test_build_l1_lists_externals_and_user(async_session):
repo = await _seed_monorepo(async_session)
view = await c4_builder.build_l1(async_session, repo.id)
assert view.system.name == "demo"
assert [p.id for p in view.people] == ["person:user"]
assert {e.name for e in view.external_systems} == {"fastapi", "react"}
# Every external has an edge from system; plus one user→system edge
assert any(r.source_id == "person:user" and r.target_id == view.system.id for r in view.relations)
assert sum(1 for r in view.relations if r.source_id == view.system.id) == 2
@pytest.mark.asyncio
async def test_build_l2_detects_containers_and_aggregates_edges(async_session):
repo = await _seed_monorepo(async_session)
view = await c4_builder.build_l2(async_session, repo.id)
container_paths = {c.path for c in view.containers}
assert container_paths == {"packages/core", "packages/web"}
by_path = {c.path: c for c in view.containers}
assert by_path["packages/core"].language == "python"
assert by_path["packages/web"].language == "typescript"
assert by_path["packages/core"].file_count == 3
assert by_path["packages/web"].file_count == 2
# web → core (one file-level edge rolled up)
relations = {(r.source_id, r.target_id): r for r in view.relations}
assert ("pkg:packages/web", "pkg:packages/core") in relations
cross = relations[("pkg:packages/web", "pkg:packages/core")]
assert cross.edge_count == 1
# External edges
assert ("pkg:packages/core", "ext:fastapi") in relations
assert ("pkg:packages/web", "ext:react") in relations
# No self-loops
assert all(r.source_id != r.target_id for r in view.relations)
@pytest.mark.asyncio
async def test_build_l3_returns_components_and_filters_externals(async_session):
repo = await _seed_monorepo(async_session)
view = await c4_builder.build_l3(async_session, repo.id, "pkg:packages/core")
assert view is not None
assert view.container.path == "packages/core"
comp_names = {c.name for c in view.components}
assert comp_names == {"ingestion", "persistence"}
# Only fastapi should appear under L3 of packages/core (not react)
assert {e.name for e in view.external_systems} == {"fastapi"}
@pytest.mark.asyncio
async def test_build_l3_unknown_container_returns_none(async_session):
repo = await _seed_monorepo(async_session)
view = await c4_builder.build_l3(async_session, repo.id, "pkg:does/not/exist")
assert view is None
# ---------------------------------------------------------------------------
# Phase 3 shaping: root naming, external/sibling exclusion, component depth,
# signal counts, derived L1 actors.
# ---------------------------------------------------------------------------
async def _seed_single_package(session):
"""A root-manifest repo (one pyproject.toml at the root) with a ``src``
layout, a stray unresolved external node, and curated entry points.
"""
repo = await upsert_repository(session, name="acme-tool", local_path="/tmp/acme")
files = [
"pyproject.toml",
"README.md",
"src/acme/cli/main.py",
"src/acme/server/app.py",
"src/acme/core/engine.py",
"scripts/run.py",
]
nodes = [
{"node_id": f, "node_type": "file", "language": "python", "symbol_count": 2}
for f in files
]
# An unresolved-import target — must never become a file/component.
nodes.append({"node_id": "external:@/lib/thing", "node_type": "file", "language": "python", "symbol_count": 0})
await batch_upsert_graph_nodes(session, repo.id, nodes)
session.add(
KnowledgeGraphProjectMeta(
repository_id=repo.id,
entry_points_json=json.dumps(
["src/acme/cli/main.py", "src/acme/server/app.py", "scripts/run.py"]
),
)
)
# One hotspot + one dead file so the counts have something to report.
session.add(GitMetadata(repository_id=repo.id, file_path="src/acme/core/engine.py", is_hotspot=True))
session.add(
DeadCodeFinding(
repository_id=repo.id,
kind="unreachable_file",
file_path="src/acme/cli/main.py",
status="open",
confidence=0.9,
reason="",
)
)
await session.commit()
return repo
@pytest.mark.asyncio
async def test_root_container_uses_repo_name_not_dot(async_session):
repo = await _seed_single_package(async_session)
view = await c4_builder.build_l2(async_session, repo.id)
root = next(c for c in view.containers if c.path == "")
assert root.name == "acme-tool"
assert root.name != "."
@pytest.mark.asyncio
async def test_external_nodes_excluded_from_counts_and_components(async_session):
repo = await _seed_single_package(async_session)
view = await c4_builder.build_l2(async_session, repo.id)
root = next(c for c in view.containers if c.path == "")
# 6 real files, not 7 — the external:@ node is excluded.
assert root.file_count == 6
l3 = await c4_builder.build_l3(async_session, repo.id, root.id)
assert l3 is not None
assert all("external:" not in c.id for c in l3.components)
assert all("external:" not in c.path for c in l3.components)
@pytest.mark.asyncio
async def test_component_depth_skips_passthrough_and_names_root_bucket(async_session):
repo = await _seed_single_package(async_session)
root = next(
c for c in (await c4_builder.build_l2(async_session, repo.id)).containers if c.path == ""
)
l3 = await c4_builder.build_l3(async_session, repo.id, root.id)
assert l3 is not None
names = {c.name for c in l3.components}
# `src/acme/...` strips `src`, surfacing `acme` rather than a giant `src`;
# the root-level files collapse into a labeled bucket, never "_root".
assert "acme" in names
assert "scripts" in names
assert "_root" not in names
assert "(root)" in names
assert not any(c.id.endswith("/_root") or "_root" in c.id for c in l3.components)
@pytest.mark.asyncio
async def test_container_signal_counts_populated(async_session):
repo = await _seed_single_package(async_session)
view = await c4_builder.build_l2(async_session, repo.id)
root = next(c for c in view.containers if c.path == "")
assert root.hotspot_count == 1
assert root.dead_count == 1
@pytest.mark.asyncio
async def test_l1_actors_derived_from_entry_points(async_session):
repo = await _seed_single_package(async_session)
view = await c4_builder.build_l1(async_session, repo.id)
kinds = [p.kind for p in view.people]
assert kinds == ["cli", "api", "developer"]
# Every actor drives one edge into the system.
actor_edges = [r for r in view.relations if r.target_id == view.system.id]
assert len(actor_edges) == 3
@pytest.mark.asyncio
async def test_relation_labels_are_readable_with_coupling(async_session):
repo = await _seed_monorepo(async_session)
view = await c4_builder.build_l2(async_session, repo.id)
cross = next(r for r in view.relations if r.source_id == "pkg:packages/web")
assert cross.label == "imports"
assert cross.coupling in {"loose", "moderate", "tight"}
assert "+1" not in cross.label
async def _seed_nodes_and_edges(session, local_path, nodes, edges=()):
repo = await upsert_repository(session, name="shop", local_path=local_path)
await batch_upsert_graph_nodes(
session,
repo.id,
[{"node_id": n, "node_type": "file", "language": lang, "symbol_count": 1} for n, lang in nodes],
)
if edges:
await batch_upsert_graph_edges(
session,
repo.id,
[{"source_node_id": s, "target_node_id": t, "edge_type": e} for s, t, e in edges],
)
await session.commit()
return repo
@pytest.mark.asyncio
async def test_dominant_language_ignores_markdown(async_session):
nodes = [
("packages/docs-kit/package.json", "json"),
("packages/docs-kit/a.md", "markdown"),
("packages/docs-kit/b.md", "markdown"),
("packages/docs-kit/c.md", "markdown"),
("packages/docs-kit/index.ts", "typescript"),
]
repo = await _seed_nodes_and_edges(async_session, "/nonexistent/shop", nodes)
view = await c4_builder.build_l2(async_session, repo.id)
(container,) = view.containers
assert container.language == "typescript"
assert container.file_count == 5
@pytest.mark.asyncio
async def test_fixture_manifest_not_container(async_session):
nodes = [
("package.json", "json"),
("src/index.ts", "typescript"),
("tests/fixtures/app/package.json", "json"),
("tests/fixtures/app/index.ts", "typescript"),
("examples/demo/package.json", "json"),
("examples/demo/main.ts", "typescript"),
("packages/core/package.json", "json"),
("packages/core/src/lib.ts", "typescript"),
("packages/core/test/fixture/package.json", "json"),
]
repo = await _seed_nodes_and_edges(async_session, "/nonexistent/shop", nodes)
view = await c4_builder.build_l2(async_session, repo.id)
by_path = {c.path: c for c in view.containers}
assert set(by_path) == {"", "packages/core"}
# Fixture and sample files fold into the nearest remaining container.
assert by_path[""].file_count == 6
assert by_path["packages/core"].file_count == 3
# With no readable manifest a container is named by its relative path.
assert by_path["packages/core"].name == "packages/core"
assert by_path[""].name == "shop"
@pytest.mark.asyncio
async def test_fallback_top_level_dirs_skip_tests_and_examples(async_session):
nodes = [
("app/main.go", "go"),
("tests/app_test.go", "go"),
("examples/hello/main.go", "go"),
]
repo = await _seed_nodes_and_edges(async_session, "/nonexistent/shop", nodes)
view = await c4_builder.build_l2(async_session, repo.id)
assert [c.path for c in view.containers] == ["app"]
@pytest.mark.asyncio
async def test_container_named_from_manifest(async_session, tmp_path):
(tmp_path / "packages" / "core").mkdir(parents=True)
(tmp_path / "packages" / "core" / "package.json").write_text('{"name": "@shop/core"}')
(tmp_path / "pyproject.toml").write_text('[project]\nname = "shop-root"\n')
nodes = [
("pyproject.toml", "toml"),
("shop/app.py", "python"),
("packages/core/package.json", "json"),
("packages/core/index.ts", "typescript"),
]
repo = await _seed_nodes_and_edges(async_session, str(tmp_path), nodes)
names = {c.path: c.name for c in (await c4_builder.build_l2(async_session, repo.id)).containers}
assert names == {"": "shop-root", "packages/core": "@shop/core"}
async def _seed_two_containers_with_edges(session, edges):
nodes = [
("packages/a/package.json", "json"),
("packages/a/index.ts", "typescript"),
("packages/a/tsconfig.json", "json"),
("packages/b/package.json", "json"),
("packages/b/index.ts", "typescript"),
]
return await _seed_nodes_and_edges(session, "/nonexistent/shop", nodes, edges)
@pytest.mark.asyncio
async def test_l2_excludes_cochange(async_session):
repo = await _seed_two_containers_with_edges(
async_session, [("packages/a/index.ts", "packages/b/index.ts", "co_changes")]
)
assert (await c4_builder.build_l2(async_session, repo.id)).relations == []
# The shared roll-up drops history everywhere, the export included.
model = await c4_builder.build_model(async_session, repo.id)
assert model.container_relations == [] and model.component_relations == []
overlay = await c4_builder.build_l2(async_session, repo.id, include_co_changes=True)
assert [(r.source_id, r.target_id, r.label) for r in overlay.relations] == [
("pkg:packages/a", "pkg:packages/b", "co-changes")
]
@pytest.mark.asyncio
async def test_l2_skips_edges_to_config_files(async_session):
repo = await _seed_two_containers_with_edges(
async_session,
[
("packages/b/index.ts", "packages/a/tsconfig.json", "imports"),
("packages/b/index.ts", "packages/a/index.ts", "imports"),
],
)
(relation,) = (await c4_builder.build_l2(async_session, repo.id)).relations
assert (relation.source_id, relation.target_id, relation.edge_count) == (
"pkg:packages/b",
"pkg:packages/a",
1,
)
async def _add_test_import(session, repo) -> None:
"""A test in web importing core: not a dependency of web on core."""
await batch_upsert_graph_nodes(
session,
repo.id,
[{"node_id": "packages/web/tests/test_api.py", "node_type": "file", "language": "python", "symbol_count": 1}],
)
await batch_upsert_graph_edges(
session,
repo.id,
[{"source_node_id": "packages/web/tests/test_api.py", "target_node_id": "packages/core/ingestion/graph.py", "edge_type": "imports"}],
)
await session.commit()
def test_roll_up_drops_edges_touching_a_test_file():
from repowise.core.analysis.c4.relations import roll_up_edges
boxes = {"a/src/x.py": "a", "a/tests/test_x.py": "a", "b/src/y.py": "b"}
rolled = roll_up_edges(
[
("a/src/x.py", "b/src/y.py", "imports"),
("a/tests/test_x.py", "b/src/y.py", "imports"),
],
boxes,
)
assert rolled == {("a", "b"): (1, frozenset({"imports"}))}
@pytest.mark.asyncio
async def test_container_view_and_dependencies_agree_without_tests(async_session):
repo = await _seed_monorepo(async_session)
await _add_test_import(async_session, repo)
containers, relations = await c4_builder.container_dependencies(async_session, repo.id)
view = await c4_builder.build_l2(async_session, repo.id)
assert {c.path for c in containers} == {"packages/core", "packages/web"}
internal = [(r.source_id, r.target_id, r.edge_count) for r in relations]
assert internal == [("pkg:packages/web", "pkg:packages/core", 1)]
in_view = [
(r.source_id, r.target_id, r.edge_count)
for r in view.relations
if not r.target_id.startswith("ext:")
]
assert in_view == internal
@pytest.mark.asyncio
async def test_container_dependencies_honour_exclusions(async_session):
import pathspec
repo = await _seed_monorepo(async_session)
spec = pathspec.PathSpec.from_lines("gitwildmatch", ["packages/web/lib/"])
_, relations = await c4_builder.container_dependencies(
async_session, repo.id, exclude_spec=spec
)
assert relations == []
@pytest.mark.asyncio
async def test_overview_dependency_block_is_cached_and_empty_for_one_package(async_session):
from types import SimpleNamespace
from repowise.server.mcp_server.tool_overview.graph import (
_build_package_dependencies,
reset_cache,
)
reset_cache()
repo = await _seed_monorepo(async_session)
handle = SimpleNamespace(id=repo.id, head_commit="c1")
expected = {
"edges": [{"from": "packages/web", "to": "packages/core", "verb": "imports", "weight": 1}]
}
block = await _build_package_dependencies(async_session, handle)
assert block == expected
# Same index state: served from the cache, blind to a new edge. A new
# commit re-derives it.
await batch_upsert_graph_edges(
async_session,
repo.id,
[{"source_node_id": "packages/web/app/page.tsx", "target_node_id": "packages/core/ingestion/graph.py", "edge_type": "imports"}],
)
await async_session.commit()
block["edges"].clear()
assert await _build_package_dependencies(async_session, handle) == expected
moved = SimpleNamespace(id=repo.id, head_commit="c2")
assert (await _build_package_dependencies(async_session, moved))["edges"][0]["weight"] == 2
single = await upsert_repository(async_session, name="single", local_path="/tmp/single")
await batch_upsert_graph_nodes(
async_session,
single.id,
[
{"node_id": "pyproject.toml", "node_type": "file", "language": "toml", "symbol_count": 0},
{"node_id": "src/app.py", "node_type": "file", "language": "python", "symbol_count": 1},
{"node_id": "src/util.py", "node_type": "file", "language": "python", "symbol_count": 1},
],
)
await batch_upsert_graph_edges(
async_session,
single.id,
[{"source_node_id": "src/app.py", "target_node_id": "src/util.py", "edge_type": "imports"}],
)
await async_session.commit()
single_handle = SimpleNamespace(id=single.id, head_commit="c1")
assert await _build_package_dependencies(async_session, single_handle) == {}