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 index-backed skeletonization.
Fixtures are real files from this repo pinned at the commit the index was
built from (``*.src.txt`` content + ``*.symbols.json`` WikiSymbol rows with
symbol-node PageRank), so the tests never depend on the live working tree
or on a parser running at test time.
"""
from __future__ import annotations
import json
import pytest
from repowise.core.distill.skeleton import (
SkeletonResult,
SkeletonSymbol,
build_skeleton,
)
def _load_case(load_fixture, stem: str) -> tuple[str, list[SkeletonSymbol]]:
source = load_fixture(f"{stem}.src.txt")
payload = json.loads(load_fixture(f"{stem}.symbols.json"))
symbols = [
SkeletonSymbol(
name=s["name"],
kind=s["kind"],
start_line=s["start_line"],
end_line=s["end_line"],
signature=s["signature"],
importance=s["pagerank"],
)
for s in payload["symbols"]
]
return source, symbols
@pytest.fixture(scope="module")
def python_case(load_fixture):
return _load_case(load_fixture, "skeleton_traverser")
@pytest.fixture(scope="module")
def tsx_case(load_fixture):
return _load_case(load_fixture, "skeleton_artifacts")
class TestSignaturesMode:
def test_size_and_completeness_python(self, python_case) -> None:
source, symbols = python_case
result = build_skeleton(source, symbols, mode="signatures")
assert result.mode == "signatures"
# Exit criterion: a ~600-line file compresses to <=~15% of full tokens.
assert result.skeleton_tokens <= result.full_tokens * 0.15, (
f"{result.skeleton_tokens}/{result.full_tokens} = {result.pct_of_full:.1f}%"
)
# Every signature line is present verbatim.
lines = source.splitlines()
for sym in symbols:
if sym.name == "__module__":
continue
assert lines[sym.start_line - 1] in result.text, sym.name
def test_size_and_completeness_tsx(self, tsx_case) -> None:
source, symbols = tsx_case
result = build_skeleton(source, symbols, mode="signatures")
assert result.skeleton_tokens <= result.full_tokens * 0.35
lines = source.splitlines()
for sym in symbols:
assert lines[sym.start_line - 1] in result.text, sym.name
def test_imports_and_module_docstring_kept(self, python_case) -> None:
source, symbols = python_case
result = build_skeleton(source, symbols, mode="signatures")
for line in source.splitlines():
if line.startswith(("import ", "from ")):
assert line in result.text, line
# Module docstring opener is the first line of the file.
assert source.splitlines()[0] in result.text
def test_elision_markers_carry_line_ranges(self, python_case) -> None:
source, symbols = python_case
result = build_skeleton(source, symbols, mode="signatures")
import re
markers = re.findall(r"\.\.\. (\d+) lines \((\d+)-(\d+)\)", result.text)
assert markers, "expected at least one elision marker"
for n, a, b in markers:
assert int(b) - int(a) + 1 == int(n)
assert 1 <= int(a) <= int(b) <= len(source.splitlines())
def test_no_bodies_in_signatures_mode(self, python_case) -> None:
source, symbols = python_case
result = build_skeleton(source, symbols, mode="signatures")
assert result.bodies_kept == ()
class TestSmartMode:
def test_keeps_high_pagerank_bodies(self, python_case) -> None:
source, symbols = python_case
result = build_skeleton(source, symbols, mode="smart", token_budget=2500)
assert result.bodies_kept, "smart mode kept no bodies"
# The kept bodies are the top-importance leaf symbols, in rank order.
ranked = sorted(symbols, key=lambda s: -s.importance)
top_names = [s.name for s in ranked[:10]]
assert result.bodies_kept[0] in top_names
# And the skeleton is strictly larger than signatures-only.
sig_only = build_skeleton(source, symbols, mode="signatures")
assert result.skeleton_tokens > sig_only.skeleton_tokens
def test_respects_token_budget(self, python_case) -> None:
source, symbols = python_case
small = build_skeleton(source, symbols, mode="smart", token_budget=900)
large = build_skeleton(source, symbols, mode="smart", token_budget=3000)
assert small.skeleton_tokens <= large.skeleton_tokens
# Budget bounds the output with slack for the signature floor.
assert small.skeleton_tokens <= 900 * 1.3
def test_query_match_boosts_symbol(self, python_case) -> None:
source, symbols = python_case
# Pick a low-importance leaf symbol and query for it by name.
leaf = min(
(s for s in symbols if s.end_line - s.start_line > 8),
key=lambda s: s.importance,
)
result = build_skeleton(source, symbols, mode="smart", token_budget=2500, query=leaf.name)
assert leaf.name in result.bodies_kept
def test_hotspot_widens_budget(self, python_case) -> None:
source, symbols = python_case
cold = build_skeleton(source, symbols, mode="smart", token_budget=1500)
hot = build_skeleton(source, symbols, mode="smart", token_budget=1500, hotspot=True)
assert hot.skeleton_tokens >= cold.skeleton_tokens
class TestDegradation:
def test_no_symbols_returns_raw(self) -> None:
source = "line one\nline two\nline three\n"
result = build_skeleton(source, [])
assert result.mode == "raw"
assert result.text == source
assert result.skeleton_tokens == result.full_tokens
def test_out_of_range_symbols_returns_raw(self) -> None:
source = "x = 1\n"
bad = [SkeletonSymbol(name="ghost", kind="function", start_line=50, end_line=80)]
result = build_skeleton(source, bad)
assert result.mode == "raw"
assert result.text == source
def test_synthetic_module_symbol_ignored(self) -> None:
source = "x = 1\ny = 2\n"
syn = [SkeletonSymbol(name="__module__", kind="module", start_line=0, end_line=0)]
result = build_skeleton(source, syn)
assert result.mode == "raw"
def test_end_line_clamped_to_file(self) -> None:
source = "def f():\n return 1\n"
sym = [SkeletonSymbol(name="f", kind="function", start_line=1, end_line=999)]
result = build_skeleton(source, sym, mode="signatures")
assert "def f():" in result.text
def test_unknown_mode_falls_back_to_signatures(self, python_case) -> None:
source, symbols = python_case
result = build_skeleton(source, symbols, mode="banana")
assert result.mode == "signatures"
assert result.bodies_kept == ()
class TestSignatureEndHeuristics:
def test_multiline_python_signature(self) -> None:
source = (
"def f(\n"
" a: int,\n"
" b: str,\n"
") -> bool:\n"
" x = 1\n"
" y = 2\n"
" z = 3\n"
" w = 4\n"
" return True\n"
)
sym = [SkeletonSymbol(name="f", kind="function", start_line=1, end_line=9)]
result = build_skeleton(source, sym, mode="signatures")
assert ") -> bool:" in result.text
assert "return True" not in result.text
def test_brace_language_signature(self) -> None:
source = (
"func Process(items []string) error {\n" + "\tstep := 0\n" * 8 + "\treturn nil\n}\n"
)
sym = [SkeletonSymbol(name="Process", kind="function", start_line=1, end_line=11)]
result = build_skeleton(source, sym, mode="signatures")
assert "func Process(items []string) error {" in result.text
assert "step := 0" not in result.text
def test_docstring_summary_kept_in_smart_mode_only(self) -> None:
body = (
' """Summary line.\n\n Detail one.\n Detail two.\n Detail three.\n Detail four.\n """\n'
+ " x = 1\n" * 6
)
source = "def f():\n" + body + " return x\n"
total = source.count("\n")
sym = [SkeletonSymbol(name="f", kind="function", start_line=1, end_line=total)]
smart = build_skeleton(source, sym, mode="smart", token_budget=1)
assert '"""Summary line.' in smart.text
sigs = build_skeleton(source, sym, mode="signatures")
assert "Summary line." not in sigs.text
assert "x = 1" not in sigs.text
class TestResultShape:
def test_pct_of_full(self) -> None:
r = SkeletonResult(
text="x", mode="signatures", full_tokens=200, skeleton_tokens=30, symbol_count=3
)
assert r.pct_of_full == 15.0
# Bounds that start on an annotation line, as some parsers persist them.
_ANNOTATED = [
(
"@decorator\ndef run(a, b):\n x = a\n y = b\n z = x + y\n return z\n",
"def run(a, b):",
),
(
"@Override\npublic String toString() {\n String s = \"x\";\n s = s + 1;\n"
" s = s + 2;\n return s;\n}\n",
"public String toString() {",
),
(
"#[inline]\nfn top(a: u32) -> u32 {\n let s = a;\n let t = s * 2;\n"
" let u = t + 1;\n u\n}\n",
"fn top(a: u32) -> u32 {",
),
]
@pytest.mark.parametrize("mode", ["smart", "signatures"])
@pytest.mark.parametrize(("source", "signature"), _ANNOTATED)
def test_a_signature_after_an_annotation_line_is_kept(mode, source, signature) -> None:
total = len(source.splitlines())
sym = SkeletonSymbol(name="f", kind="function", start_line=1, end_line=total)
result = build_skeleton(source, [sym], mode=mode)
assert result.text.splitlines()[:2] == source.splitlines()[:2]
assert signature in result.text
assert "... " in result.text # the body itself is still elided
_FOCUS_SOURCE = '''"""Display helpers."""
from datetime import datetime
def format_timestamp(value: str) -> str:
"""Format a timestamp."""
dt = datetime.fromisoformat(value)
if dt.tzinfo is not None:
dt = dt.astimezone()
out = dt.strftime("%b %d")
return out
def format_file_size(size: float) -> str:
"""Format a file size."""
# ----------
if size < 1024:
return f"{int(size)} B"
size /= 1024
return f"{size:.1f} KB"
'''
def _focus_symbols(focus: str | None) -> list[SkeletonSymbol]:
bounds = {"format_timestamp": (5, 11, 1.0), "format_file_size": (14, 20, 0.1)}
return [
SkeletonSymbol(name, "function", start, end, importance=rank, focus=name == focus)
for name, (start, end, rank) in bounds.items()
]
class TestFocus:
@pytest.mark.parametrize("mode", ["smart", "plus"])
def test_keeps_only_the_focused_body(self, mode) -> None:
result = build_skeleton(_FOCUS_SOURCE, _focus_symbols("format_file_size"), mode=mode)
lines = _FOCUS_SOURCE.splitlines()
# The focused symbol is whole, decorative comment included.
for line in lines[13:20]:
assert line in result.text
# The other symbol, though higher-ranked, is reduced to its signature.
assert "def format_timestamp(value: str) -> str:" in result.text
assert "dt.strftime" not in result.text
assert result.bodies_kept == ("format_file_size",)
assert "from datetime import datetime" in result.text
def test_without_focus_smart_ranks_bodies(self) -> None:
result = build_skeleton(_FOCUS_SOURCE, _focus_symbols(None), mode="smart")
assert "format_timestamp" in result.bodies_kept