Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.py
index 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 annotations
import re
from collections.abc import Sequence
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
from repowise.core.distill.budget import estimate_tokens
@@ -98,6 +98,9 @@ class SkeletonSymbol:
``importance`` is whatever ranking signal the caller has — symbol-node
PageRank in the indexed case, 0.0 when the graph has nothing. The
skeleton 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, inclusive
signature: 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[SkeletonSym
continue
end = 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.py
index 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_file
from 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 the
highest-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_skeleton
from repowise.core.persistence.models import WikiSymbol
+ from repowise.server.mcp_server._symbol_lookup import symbol_id_variants
repo_id = repository.id
res = 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_CHARS
symbols.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"] = True
result_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.py
index 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.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
diff --git a/tests/unit/server/mcp/test_context_skeleton.py b/tests/unit/server/mcp/test_context_skeleton.py
index 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 sk
assert "class AuthService:" in sk["text"] # whole file, not just the symbol
assert 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.asyncio
async def test_skeleton_missing_source_file(setup_mcp, tmp_path, monkeypatch):
from repowise.server.mcp_server import _state, get_context