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
feat(context): keep only the target symbol's body in a symbol skeleton (#3135)
Raghav Chamadiya76090a333190
diff --git a/packages/core/src/repowise/core/distill/skeleton.py b/packages/core/src/repowise/core/distill/skeleton.pyindex 5ae8d7447..6b3e5a015 100644--- a/packages/core/src/repowise/core/distill/skeleton.py+++ b/packages/core/src/repowise/core/distill/skeleton.py@@ -34,7 +34,7 @@ from __future__ import annotationsimport refrom collections.abc import Sequence-from dataclasses import dataclass, field+from dataclasses import dataclass, field, replacefrom repowise.core.distill.budget import estimate_tokens@@ -98,6 +98,9 @@ class SkeletonSymbol:``importance`` is whatever ranking signal the caller has — symbol-nodePageRank in the indexed case, 0.0 when the graph has nothing. Theskeleton only compares importances relative to each other.++ ``focus`` marks the symbol the caller asked about: its whole body is kept+ and no other body is, so the file reads as signatures around one symbol."""name: str@@ -106,6 +109,7 @@ class SkeletonSymbol:end_line: int # 1-indexed, inclusivesignature: str = ""importance: float = 0.0+ focus: bool = False@dataclass(frozen=True)@@ -155,9 +159,12 @@ def build_skeleton(symbol_count=0,)+ focused = [sym for sym in usable if sym.focus]+if mode == "plus":keep = [True] * total_elide_callable_bodies(lines, usable, keep)+ _keep_focus(focused, keep)text = _render(lines, keep)return SkeletonResult(text=text,@@ -165,6 +172,7 @@ def build_skeleton(full_tokens=full_tokens,skeleton_tokens=estimate_tokens(text),symbol_count=len(usable),+ bodies_kept=tuple(sym.name for sym in focused),)keep = [False] * total@@ -190,14 +198,20 @@ def build_skeleton(_keep_small_gaps(lines, usable, total, keep)bodies_kept: tuple[str, ...] = ()- if smart:+ if focused:+ bodies_kept = tuple(sym.name for sym in focused)+ elif smart:budget = int(token_budget * (_HOTSPOT_BUDGET_FACTOR if hotspot else 1.0))bodies_kept = _keep_smart_bodies(lines, usable, sig_ends, keep, budget, query)- # Decorative banner comments add bytes, not structure.+ # Decorative banner comments add bytes, not structure; a focused body+ # stays whole.+ in_focus = [False] * total+ _keep_focus(focused, in_focus)for i in range(total):- if keep[i] and _DECOR_RE.match(lines[i]):+ if keep[i] and not in_focus[i] and _DECOR_RE.match(lines[i]):keep[i] = False+ _keep_focus(focused, keep)text = _render(lines, keep)return SkeletonResult(@@ -225,19 +239,19 @@ def _sanitize(symbols: Sequence[SkeletonSymbol], total: int) -> list[SkeletonSymcontinueend = max(sym.start_line, min(sym.end_line, total))if end != sym.end_line:- sym = SkeletonSymbol(- name=sym.name,- kind=sym.kind,- start_line=sym.start_line,- end_line=end,- signature=sym.signature,- importance=sym.importance,- )+ sym = replace(sym, end_line=end)out.append(sym)out.sort(key=lambda s: (s.start_line, -(s.end_line - s.start_line)))return out+def _keep_focus(focused: list[SkeletonSymbol], keep: list[bool]) -> None:+ """Mark every line of each focused symbol, signature through last line."""+ for sym in focused:+ for i in range(sym.start_line - 1, sym.end_line):+ keep[i] = True++def _keep_preamble(lines: list[str], first_start: int, keep: list[bool]) -> None:"""Mark the pre-symbol region: whole if small, docstring+imports if not."""if first_start <= 0:diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.pyindex 76edd7712..b2c6d9e6a 100644--- a/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py+++ b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py@@ -59,7 +59,11 @@ from repowise.core.persistence.models import (Repository,)from repowise.server.mcp_server._basis import call_resolution_basis-from repowise.server.mcp_server._budget import OmissionCollector, cap_collection+from repowise.server.mcp_server._budget import (+ DEFAULT_RESPONSE_CHARS,+ OmissionCollector,+ cap_collection,+)from repowise.server.mcp_server._graph_files import keep_projected_edge, node_to_filefrom repowise.server.mcp_server._helpers import (filter_dicts_by_key,@@ -897,6 +901,10 @@ def _doc_reference_block(return block+#: Same threshold get_symbol uses to outline a container instead of inlining it.+_FOCUS_CONTAINER_MAX_CHARS = DEFAULT_RESPONSE_CHARS // 2++async def _resolve_skeleton(session: AsyncSession,repository: Repository,@@ -913,9 +921,8 @@ async def _resolve_skeleton((zero parsing), keeping every signature and the bodies of thehighest-PageRank symbols under a token budget. ``include=["skeleton+"]``passes ``mode="plus"``: all non-function code kept, every function and- method body elided. File targets only:- a symbol's "skeleton" is just its signature, which the triage card- already carries.+ method body elided. A ``file.py::Symbol`` target renders its file with+ that symbol's whole body and every other symbol as its signature."""# A "file.py::Symbol" target still has a useful skeleton — the file that# defines the symbol. Strip the suffix and skeleton that file rather than@@ -935,6 +942,7 @@ async def _resolve_skeleton(from repowise.core.distill.skeleton import SkeletonSymbol, build_skeletonfrom repowise.core.persistence.models import WikiSymbol+ from repowise.server.mcp_server._symbol_lookup import symbol_id_variantsrepo_id = repository.idres = await session.execute(@@ -976,11 +984,19 @@ async def _resolve_skeleton(# hydrator / incremental update, which hold a writable session on their path.from repowise.server.mcp_server._verify import check_symbol_bounds+ focus_ids = set(symbol_id_variants(target)) if is_symbol_target else set()+ source_lines = source.splitlines()symbols = []for r in rows:check = check_symbol_bounds(r, source)if check.approximate:continue+ focus = r.symbol_id in focus_ids+ if focus and r.kind not in ("function", "method"):+ # Ceiling: a container body over the get_symbol outline threshold is+ # not inlined; the ranked skeleton shows its methods as signatures.+ span = source_lines[check.start_line - 1 : check.end_line]+ focus = sum(len(ln) + 1 for ln in span) <= _FOCUS_CONTAINER_MAX_CHARSsymbols.append(SkeletonSymbol(name=r.name,@@ -989,6 +1005,7 @@ async def _resolve_skeleton(end_line=check.end_line,signature=r.signature,importance=pagerank.get(r.name, 0.0),+ focus=focus,))result = build_skeleton(@@ -1009,22 +1026,31 @@ async def _resolve_skeleton(# a verified response never needs a follow-up Read."verified": True,}+ focused = any(sym.focus for sym in symbols)if is_symbol_target:- # The caller passed "file.py::Symbol"; tell them this is the whole- # file's skeleton, and how to get just the symbol's body.+ name = target.split("::", 1)[1]result_data["skeleton"]["of_file"] = file_target- result_data["skeleton"]["symbol_hint"] = (- f"Skeleton of the file defining '{target.split('::', 1)[1]}'. For that "- f"symbol's full body call get_symbol('{target}')."- )+ if focused:+ result_data["skeleton"]["symbol_hint"] = (+ f"Skeleton of the file defining '{name}': its full body, every "+ "other symbol as its signature."+ )+ else:+ # No row for the symbol passed the bounds check, or it is a container+ # over the ceiling, so its body is not guaranteed here.+ result_data["skeleton"]["symbol_hint"] = (+ f"Skeleton of the file defining '{name}'. For that "+ f"symbol's full body call get_symbol('{target}')."+ )if result.mode == "raw":result_data["skeleton"]["note"] = ("No usable symbol bounds for this file — returned source as-is.")- elif result.pct_of_full > 40.0:+ elif result.pct_of_full > 40.0 and not focused:# Small files skeletonize poorly: when the skeleton is already a# large fraction of the source, tell the agent a Read costs little- # more and carries everything.+ # more and carries everything. A focused skeleton is already the+ # symbol plus a file map, so a Read is not the cheaper answer.result_data["skeleton"]["mostly_full"] = Trueresult_data["skeleton"]["note"] = (f"Skeleton is {round(result.pct_of_full, 1)}% of the full file — "diff --git a/tests/unit/distill/test_skeleton.py b/tests/unit/distill/test_skeleton.pyindex f4eb66b50..a2e2e85c0 100644--- a/tests/unit/distill/test_skeleton.py+++ b/tests/unit/distill/test_skeleton.py@@ -246,3 +246,53 @@ def test_a_signature_after_an_annotation_line_is_kept(mode, source, signature) -assert result.text.splitlines()[:2] == source.splitlines()[:2]assert signature in result.textassert "... " 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_keptdiff --git a/tests/unit/server/mcp/test_context_skeleton.py b/tests/unit/server/mcp/test_context_skeleton.pyindex 98ecc8384..74efb0c18 100644--- a/tests/unit/server/mcp/test_context_skeleton.py+++ b/tests/unit/server/mcp/test_context_skeleton.py@@ -137,9 +137,80 @@ async def test_skeleton_for_symbol_target_renders_defining_file(assert "error" not in skassert "class AuthService:" in sk["text"] # whole file, not just the symbolassert sk["of_file"] == "src/auth/service.py"+ # The target's body is whole; the enclosing class's other code is elided.+ assert all(f"step_{n} = {n}" in sk["text"] for n in range(21, 41))+ assert "tail_99 = 99" not in sk["text"]+ assert sk["bodies_kept"] == ["login"]+ assert "every other symbol as its signature" in sk["symbol_hint"]+ assert "mostly_full" not in sk+++async def _add_symbol_node(session, name, kind, start, end):+ from sqlalchemy import select++ from repowise.core.persistence.models import GraphNode, Repository++ repo = (await session.execute(select(Repository))).scalars().first()+ target_id = f"src/auth/service.py::{name}"+ session.add(+ GraphNode(+ id=f"sk_{name}",+ repository_id=repo.id,+ node_id=target_id,+ node_type="symbol",+ name=name,+ file_path="src/auth/service.py",+ kind=kind,+ start_line=start,+ end_line=end,+ )+ )+ await session.flush()+ return target_id+++async def test_large_class_target_falls_back_to_ranked_skeleton(+ setup_mcp, session, tmp_path, monkeypatch+):+ """A container over the get_symbol outline threshold is not inlined whole."""+ from repowise.server.mcp_server import _state, get_context++ monkeypatch.setattr(_state, "_repo_path", str(tmp_path))+ target_id = await _add_symbol_node(session, "AuthService", "class", 10, 100)++ _write_source(tmp_path)+ small = (await get_context([target_id], include=["skeleton"]))["targets"][target_id]+ assert small["skeleton"]["bodies_kept"] == ["AuthService"]++ path = _write_source(tmp_path)+ pad = "x" * 300 # 60 tail lines push the class body past 12,000 chars+ path.write_text(+ path.read_text(encoding="utf-8").replace("tail_", f"tail_{pad}_"), encoding="utf-8"+ )+ sk = (await get_context([target_id], include=["skeleton"]))["targets"][target_id]["skeleton"]+ assert "AuthService" not in sk["bodies_kept"]+ assert "class AuthService:" in sk["text"]+ assert f"tail_{pad}_99 = 99" not in sk["text"]assert "get_symbol" in sk["symbol_hint"]+async def test_symbol_target_with_no_matching_row_takes_the_fallback(+ setup_mcp, session, tmp_path, monkeypatch+):+ from repowise.server.mcp_server import _state, get_context++ _write_source(tmp_path)+ monkeypatch.setattr(_state, "_repo_path", str(tmp_path))+ target_id = await _add_symbol_node(session, "ghost", "function", 20, 40)++ sk = (await get_context([target_id], include=["skeleton"]))["targets"][target_id]["skeleton"]+ assert "error" not in sk+ assert "ghost" not in sk["bodies_kept"]+ assert sk["symbol_hint"].endswith(f"get_symbol('{target_id}').")++@pytest.mark.asyncioasync def test_skeleton_missing_source_file(setup_mcp, tmp_path, monkeypatch):from repowise.server.mcp_server import _state, get_context