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
"""Pure checks over an exported knowledge-graph.json dict.
Two layers, both side-effect free so they unit-test on synthetic dicts:
- :func:`compute_stats` — per-language graph-quality numbers (edge density,
resolution rate, orphan ratio). These are the canary metrics: express's
CommonJS re-export gap showed up as 1.7 imports/file vs chi's 9.7 long
before any tour smell fired.
- :func:`run_smells` — the smell suite. Ports the original 7 checks from the
throwaway /tmp inspect.py and adds graph-level ones (edgeless graphs,
density regression vs a stored baseline, catch-all layers, entry-point
sanity). Each smell carries a severity: FAIL smells gate, WARN smells
report.
Thresholds were locked at the project's acceptance gate from the 38-repo
matrix data (each enforced value leaves ~30% headroom past the worst clean
repo of its tier). The degradation-honesty check: a dominant language with
no import support must yield a structural tour — no execution-flow
vocabulary, layers labeled canonical.
"""
from __future__ import annotations
import re
from dataclasses import dataclass, field
from pathlib import PurePosixPath
# --- Enforced thresholds (locked from the 38-repo matrix) -------------------
#
# Density floors (FAIL): dominant-language imports/file below the tier floor.
# full 0.9 — matrix minimum 1.31 (sinatra, post-stdlib-filter honest)
# partial 0.8 — matrix minimum 1.17 (jason) among repos at/above the
# small-repo cutoff
# Repos with fewer than SMALL_REPO_FILES dominant-language files are exempt
# from all three tier gates (edgeless, floor, ceiling): a 3-file repo's
# density is noise, not evidence (roblox-lua-promise 0.67), and a 2-file
# repo with no imports between its files is normal. Same rationale as the
# curation graph-mode small-repo skip; tiny-repo honesty is still covered
# by the degradation_honesty and tour smells.
DENSITY_FLOORS = {"full": 0.9, "partial": 0.8}
SMALL_REPO_FILES = 10
# Orphan-ratio ceilings (FAIL): dominant language only.
# full 0.30 — matrix maximum 0.232 (django: test-heavy, honest)
# partial 0.35 — matrix maximum 0.25 (plug/jason: elixir fully-qualified
# module references need no alias — recorded residual)
ORPHAN_CEILINGS = {"full": 0.30, "partial": 0.35}
# "Graph claims support but is effectively edgeless" — far below the tier
# floors; kept for the message's specificity on totally broken graphs.
EDGELESS_FLOOR = 0.05
DENSITY_REGRESSION_TOLERANCE = 0.15 # >15% drop vs baseline fails; conscious
# baseline updates are the escape hatch — that friction is the feature.
CATCHALL_WARN_FRACTION = 0.50 # one layer holding >50% of layered nodes
# WARN escalates to FAIL when a single layer holds >95% in a repo with at
# least CATCHALL_FAIL_MIN_FILES code files: layering effectively failed.
# Tiny flat repos legitimately approach one layer (cowlib 95.1% at 29 code
# files is exempt via the size gate; dfmt 93% at 256 files passes).
CATCHALL_FAIL_FRACTION = 0.95
CATCHALL_FAIL_MIN_FILES = 30
LAYER_COUNT_MIN, LAYER_COUNT_MAX = 2, 12 # sanity for repos > LAYER_COUNT_MIN_FILES
LAYER_COUNT_MIN_FILES = 30
# --- Curated wiki modules (kg.modules, derive_modules output) ---------------
# Mirrors kg_curation's granularity window and naming invariants so a broken
# derivation fails the matrix before it ships a wiki regen.
MODULE_TARGET_MAX = 120 # split window; flat dirs may honestly exceed (WARN)
MODULE_MIN_FILES = 3 # layers below this legitimately yield no module
MODULE_COUNT_DIVISOR = 8 # module count must stay within [1, code_files/8]
MODULE_GENERIC_FRACTION = 0.60 # segment in >60% of paths = namespace noise
MODULES_EXPECTED_MIN_FILES = 30 # curated repos this big should have modules
TEST_MODULE_MIN_FILES = 30 # Test layers this big should surface test modules
# Execution-flow vocabulary a structural tour must never use ("named like an
# entry file" is the one sanctioned entry phrasing; "import analysis isn't
# supported" / "import resolution is incomplete" are the honesty disclaimers
# and deliberately absent from this list).
FLOW_CLAIM_TERMS = (
"entry point",
"imports fan out",
"imports deep",
"import path",
"directly used by the entry",
"widely-imported",
)
_EXAMPLE_DIRS = {"examples", "_examples", "example", "samples", "sample", "demo", "demos"}
_TEST_DIRS = {"tests", "test", "__tests__", "e2e"}
@dataclass
class Smell:
severity: str # "FAIL" | "WARN"
code: str
message: str
@dataclass
class RepoReport:
repo: str
stats: dict
smells: list[Smell] = field(default_factory=list)
# Full module inventory for the human-review markdown report
# (--modules-report); deliberately NOT serialized into baselines —
# stats["modules"] carries the diffable snapshot.
modules_detail: list[dict] = field(default_factory=list)
@property
def failed(self) -> bool:
return any(s.severity == "FAIL" for s in self.smells)
def as_dict(self) -> dict:
return {
"repo": self.repo,
"stats": self.stats,
"smells": [
{"severity": s.severity, "code": s.code, "message": s.message}
for s in self.smells
],
}
def looks_like_test(path: str) -> bool:
name = PurePosixPath(path).name.lower()
parts = [p.lower() for p in PurePosixPath(path).parts]
return (
name.startswith("test_")
or name == "conftest.py"
or ".test." in name
or ".spec." in name
or any(p in _TEST_DIRS for p in parts[:-1])
)
# ---------------------------------------------------------------------------
# Stats
# ---------------------------------------------------------------------------
def compute_stats(kg: dict, import_support: dict[str, str] | None = None) -> dict:
"""Per-language graph-quality stats from the exported KG dict.
``import_support`` maps language tag -> "full" | "partial" | "none"
(from the language registry); unknown languages count as "none".
"""
support = import_support or {}
file_nodes = [n for n in kg.get("nodes", []) if n.get("type") == "file" and n.get("filePath")]
lang_by_id = {f"file:{n['filePath']}": (n.get("language") or "unknown") for n in file_nodes}
by_lang: dict[str, dict] = {}
for n in file_nodes:
lang = n.get("language") or "unknown"
bucket = by_lang.setdefault(
lang,
{
"files": 0,
"import_edges": 0,
"internal_targets": 0,
"external_targets": 0,
"hint_edges": {},
"files_with_edges": set(),
},
)
bucket["files"] += 1
for e in kg.get("edges", []):
if e.get("type") not in ("imports", "tested_by"):
continue
src, dst = e.get("source", ""), e.get("target", "")
lang = lang_by_id.get(src)
if lang is None:
continue
bucket = by_lang.get(lang)
if bucket is None:
continue
bucket["import_edges"] += 1
# Convention-pass edges (e.g. hint="same_package") counted separately
# so declared-import density and synthesised density are diffable.
hint = e.get("hint")
if hint:
bucket["hint_edges"][hint] = bucket["hint_edges"].get(hint, 0) + 1
if dst.startswith("file:external:"):
bucket["external_targets"] += 1
else:
bucket["internal_targets"] += 1
if dst in lang_by_id:
by_lang[lang_by_id[dst]]["files_with_edges"].add(dst)
bucket["files_with_edges"].add(src)
out: dict[str, dict] = {}
for lang, b in sorted(by_lang.items()):
files = b["files"]
resolved = b["internal_targets"]
total_t = b["internal_targets"] + b["external_targets"]
out[lang] = {
"files": files,
"import_edges": b["import_edges"],
"edges_per_file": round(b["import_edges"] / files, 2) if files else 0.0,
"resolution_rate": round(resolved / total_t, 3) if total_t else None,
"orphan_files": files - len(b["files_with_edges"]),
"orphan_ratio": round((files - len(b["files_with_edges"])) / files, 3)
if files
else 0.0,
"import_support": support.get(lang, "none"),
}
if b["hint_edges"]:
out[lang]["hint_edges"] = dict(sorted(b["hint_edges"].items()))
dominant = max(out, key=lambda k: out[k]["files"], default=None)
stats = {"by_language": out, "dominant_language": dominant}
# Curated wiki module snapshot — lands in baselines so naming or count
# drift across runs shows up as a reviewable diff, like tour_paths.
modules = kg.get("modules") or []
if modules:
sizes = [len(m.get("nodeIds", [])) for m in modules]
stats["modules"] = {
"count": len(modules),
"names": sorted(m.get("name", "") for m in modules),
"min_size": min(sizes, default=0),
"max_size": max(sizes, default=0),
}
return stats
# ---------------------------------------------------------------------------
# Smells
# ---------------------------------------------------------------------------
def run_smells(
kg: dict,
stats: dict,
baseline: dict | None = None,
) -> list[Smell]:
smells: list[Smell] = []
layers = kg.get("layers") or []
tour = kg.get("tour") or []
project = kg.get("project") or {}
ordered = [lyr["name"] for lyr in sorted(layers, key=lambda x: x.get("display_order", 0))]
# -- original 7 (from /tmp inspect.py) ---------------------------------
if "Test" in ordered and ordered[-1] != "Test":
smells.append(Smell("FAIL", "test_layer_not_last", f"layer order: {ordered}"))
for s in tour[:4]:
tp = s.get("target_path") or ""
if "test suite" in (s.get("reason") or "").lower():
continue # the designated closing stop — short tours put it early
if s.get("kind") != "overview" and looks_like_test(tp):
smells.append(
Smell("FAIL", "test_file_early_in_tour", f"step {s.get('order')} = {tp}")
)
for s in tour:
if "Top of the stack" in (s.get("reason") or ""):
smells.append(
Smell("FAIL", "stack_position_reason", f"step {s.get('order')}")
)
targets = [s.get("target_path") for s in tour]
dupes = sorted({t for t in targets if t and targets.count(t) > 1})
if dupes:
smells.append(Smell("FAIL", "duplicate_tour_targets", str(dupes)))
for s in tour:
tp = s.get("target_path") or ""
parts = PurePosixPath(tp).parts
if any(seg.lower() in _EXAMPLE_DIRS for seg in parts[:-1]):
smells.append(Smell("FAIL", "example_file_in_tour", f"step {s.get('order')} = {tp}"))
if s.get("kind") == "code" and parts and parts[0].startswith("."):
smells.append(Smell("FAIL", "dot_dir_file_in_tour", f"step {s.get('order')} = {tp}"))
if len(tour) < 6:
smells.append(Smell("WARN", "tour_too_short", f"only {len(tour)} steps"))
# -- graph-level -------------------------------------------------------
by_lang = stats.get("by_language", {})
dominant = stats.get("dominant_language")
dom = by_lang.get(dominant, {}) if dominant else {}
# All three dominant-tier gates exempt repos under SMALL_REPO_FILES
# dominant-language files: a 2-file repo with no imports between its
# files is normal, not broken — tiny-repo honesty is covered by the
# degradation_honesty and tour smells instead.
if (
dom
and dom.get("import_support") in ("full", "partial")
and dom.get("files", 0) >= SMALL_REPO_FILES
):
if dom.get("edges_per_file", 0.0) < EDGELESS_FLOOR:
smells.append(
Smell(
"FAIL",
"edgeless_graph",
f"{dominant} declares import_support={dom['import_support']} but "
f"edges_per_file={dom.get('edges_per_file')}",
)
)
floor = DENSITY_FLOORS[dom["import_support"]]
if dom.get("edges_per_file", 0.0) < floor:
smells.append(
Smell(
"FAIL",
"density_floor",
f"{dominant} ({dom['import_support']}) edges_per_file="
f"{dom.get('edges_per_file')} < tier floor {floor}",
)
)
ceiling = ORPHAN_CEILINGS[dom["import_support"]]
if dom.get("orphan_ratio", 0.0) > ceiling:
smells.append(
Smell(
"FAIL",
"orphan_ceiling",
f"{dominant} ({dom['import_support']}) orphan_ratio="
f"{dom.get('orphan_ratio')} > tier ceiling {ceiling}",
)
)
# -- degradation honesty -----------------------------------------------
if dom and dom.get("import_support") == "none":
mode = project.get("graph_mode")
if mode != "structural":
smells.append(
Smell(
"FAIL",
"degradation_honesty",
f"{dominant} has import_support=none but graph_mode={mode!r}",
)
)
for s in tour:
reason = (s.get("reason") or "").lower()
hit = next((t for t in FLOW_CLAIM_TERMS if t in reason), None)
if hit:
smells.append(
Smell(
"FAIL",
"degradation_honesty",
f"step {s.get('order')} claims flow ({hit!r}): {s.get('reason')!r}",
)
)
for layer in layers:
if layer.get("order_basis") != "canonical":
smells.append(
Smell(
"FAIL",
"degradation_honesty",
f"layer {layer.get('name')} order_basis="
f"{layer.get('order_basis')!r} on an edgeless graph",
)
)
if baseline:
base_langs = (baseline.get("stats") or {}).get("by_language", {})
for lang, cur in by_lang.items():
prev = base_langs.get(lang)
if not prev or prev.get("edges_per_file", 0) <= 0:
continue
drop = 1.0 - (cur.get("edges_per_file", 0.0) / prev["edges_per_file"])
if drop > DENSITY_REGRESSION_TOLERANCE:
smells.append(
Smell(
"FAIL",
"density_regression",
f"{lang}: {prev['edges_per_file']} -> {cur.get('edges_per_file')} "
f"imports/file ({drop:.0%} drop)",
)
)
code_file_count = sum(
b["files"] for lang, b in by_lang.items() if b.get("import_support") != "none"
) or sum(b["files"] for b in by_lang.values())
if layers and code_file_count:
biggest = max(layers, key=lambda lyr: len(lyr.get("nodeIds", [])))
frac = len(biggest.get("nodeIds", [])) / max(
1, sum(len(lyr.get("nodeIds", [])) for lyr in layers)
)
if frac > CATCHALL_FAIL_FRACTION and code_file_count >= CATCHALL_FAIL_MIN_FILES:
smells.append(
Smell(
"FAIL",
"catchall_layer",
f"{biggest.get('name')} holds {frac:.0%} of layered nodes "
f"({code_file_count} code files — layering effectively failed)",
)
)
elif frac > CATCHALL_WARN_FRACTION:
smells.append(
Smell(
"WARN",
"catchall_layer",
f"{biggest.get('name')} holds {frac:.0%} of layered nodes",
)
)
total_files = project.get("total_files", 0)
if (
total_files > LAYER_COUNT_MIN_FILES
and layers
and not (LAYER_COUNT_MIN <= len(layers) <= LAYER_COUNT_MAX)
):
smells.append(
Smell("WARN", "layer_count", f"{len(layers)} layers for {total_files} files")
)
# -- entry-point sanity --------------------------------------------------
eps = project.get("entry_points") or []
node_paths = {n.get("filePath") for n in kg.get("nodes", []) if n.get("filePath")}
for ep in eps:
if ep not in node_paths:
smells.append(Smell("FAIL", "entry_point_missing", f"{ep} not in graph"))
if looks_like_test(ep):
smells.append(Smell("FAIL", "entry_point_is_test", ep))
parts = PurePosixPath(ep).parts
if any(seg.lower() in _EXAMPLE_DIRS for seg in parts[:-1]):
smells.append(Smell("FAIL", "entry_point_is_example", ep))
if not eps:
for s in tour:
if "An entry point" in (s.get("reason") or ""):
smells.append(
Smell(
"FAIL",
"entry_claim_without_entry_points",
f"step {s.get('order')} claims an entry point but entry_points=[]",
)
)
smells.extend(_module_smells(kg, code_file_count))
return smells
def _dominant_path_segments(paths: list[str]) -> set[str]:
"""Dir segments in > MODULE_GENERIC_FRACTION of *paths* (namespace noise).
Mirrors kg_curation's data-driven stripping: ``src``, ``packages``, the
repo's own package name. A module *named* one of these tells the reader
nothing.
"""
n = len(paths)
if not n:
return set()
counts: dict[str, int] = {}
for p in paths:
for seg in set(PurePosixPath(p).parts[:-1]):
counts[seg] = counts.get(seg, 0) + 1
return {s.lower() for s, c in counts.items() if c / n > MODULE_GENERIC_FRACTION}
def _module_smells(kg: dict, code_file_count: int) -> list[Smell]:
"""Curated wiki module invariants over the exported ``kg.modules``.
The derivation's unit tests cover synthetic shapes; these checks catch
what only real repos surface — Java namespace prefixes leaking into
names, confetti module counts on flat-package repos, Test layers losing
their modules on test-heavy codebases.
"""
smells: list[Smell] = []
modules = kg.get("modules") or []
layers = kg.get("layers") or []
file_paths = {
n["id"]: n["filePath"]
for n in kg.get("nodes", [])
if n.get("type") == "file" and n.get("filePath")
}
if not modules:
# Curated layers without modules = derivation degraded. Tiny repos
# legitimately yield none (every layer under MODULE_MIN_FILES).
if layers and code_file_count >= MODULES_EXPECTED_MIN_FILES:
smells.append(
Smell(
"WARN",
"modules_missing",
f"curated layers present but no modules for {code_file_count} code files",
)
)
return smells
# Partition: no file in two modules (coverage is checked per-layer below).
seen: set[str] = set()
for m in modules:
for nid in m.get("nodeIds", []):
if nid in seen:
smells.append(
Smell("FAIL", "module_partition", f"{file_paths.get(nid, nid)} in >1 module")
)
return smells # one witness is enough; rest would be noise
seen.add(nid)
# Coverage: every layer big enough to module must be fully covered.
for layer in layers:
member_files = [nid for nid in layer.get("nodeIds", []) if nid in file_paths]
if len(member_files) < MODULE_MIN_FILES:
continue
missing = [nid for nid in member_files if nid not in seen]
if missing:
smells.append(
Smell(
"FAIL",
"module_coverage",
f"layer {layer.get('name')}: {len(missing)} files in no module "
f"(e.g. {file_paths.get(missing[0], missing[0])})",
)
)
# Naming invariants: unique, no size suffixes, no generic-only names.
names = [m.get("name", "") for m in modules]
ids = [m.get("id", "") for m in modules]
for label, values in (("module_name_collision", names), ("module_id_collision", ids)):
dupes = sorted({v for v in values if values.count(v) > 1})
if dupes:
smells.append(Smell("FAIL", label, str(dupes)))
generic = _dominant_path_segments(sorted(file_paths.values()))
layer_names = {(layer.get("name") or "").lower() for layer in layers}
for m in modules:
name = m.get("name", "")
if not name.strip() or name.strip().lower() in {"(root)", "root"}:
smells.append(Smell("FAIL", "module_empty_name", repr(name)))
continue
if re.search(r"\(\d+\)\s*$", name):
smells.append(Smell("FAIL", "module_size_suffix", name))
segs = [s.lower() for s in name.split("/")]
# Two honest exemptions: layer-named modules (whole-layer fallback —
# "API" names the API layer even if "api" is also a path segment),
# and modules whose OWN path offers no informative segment (fixture
# subtrees that dominate the repo: the raw tail is the best name
# available, flagging it would demand a name that can't exist).
path_segs = {s.lower() for s in (m.get("path") or "").split("/") if s}
had_alternative = bool(path_segs - generic)
if (
segs
and all(s in generic for s in segs)
and name.lower() not in layer_names
and had_alternative
):
smells.append(
Smell("FAIL", "module_generic_name", f"{name!r} is namespace noise only")
)
# Granularity: oversized modules are honest only for flat directories.
for m in modules:
size = len(m.get("nodeIds", []))
if size <= MODULE_TARGET_MAX:
continue
prefix = m.get("path", "")
rels = [
file_paths[nid][len(prefix) + 1 :] if prefix and file_paths[nid].startswith(prefix + "/")
else file_paths[nid]
for nid in m.get("nodeIds", [])
if nid in file_paths
]
if any("/" in r for r in rels):
smells.append(
Smell(
"WARN",
"module_oversized",
f"{m.get('name')} has {size} files with subdirs (window {MODULE_TARGET_MAX})",
)
)
# Count bounds: confetti detection ([1, code_files/8] acceptance gate).
# Small repos are exempt — a 12-file repo with two honest 6-file modules
# is structure, not confetti; the gate targets matrix-scale repos.
ceiling = max(1, code_file_count // MODULE_COUNT_DIVISOR)
if code_file_count >= MODULES_EXPECTED_MIN_FILES and len(modules) > ceiling:
smells.append(
Smell(
"WARN",
"module_count",
f"{len(modules)} modules for {code_file_count} code files (ceiling {ceiling})",
)
)
# Test-heavy repos must keep their test modules (user-valued invariant).
for layer in layers:
if (layer.get("name") or "").lower() != "test":
continue
test_files = [nid for nid in layer.get("nodeIds", []) if nid in file_paths]
if len(test_files) >= TEST_MODULE_MIN_FILES:
layer_id = layer.get("id", "")
if not any(m.get("layerId") == layer_id for m in modules):
smells.append(
Smell(
"WARN",
"test_modules_missing",
f"Test layer has {len(test_files)} files but no module",
)
)
return smells