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
refactor(symbol): get_symbol guards and read stages; split _cross_repo_block (#4018)
Raghav Chamadiya89a3876ea9e4
diff --git a/packages/server/src/repowise/server/mcp_server/tool_change_risk.py b/packages/server/src/repowise/server/mcp_server/tool_change_risk.pyindex 53c25c280..e09918b18 100644--- a/packages/server/src/repowise/server/mcp_server/tool_change_risk.py+++ b/packages/server/src/repowise/server/mcp_server/tool_change_risk.py@@ -761,178 +761,203 @@ def _filter_changed(return {path: lines for path, lines in changed.items() if counts(path)}+def _present(key: str, value: Any) -> dict[str, Any]:+ """``{key: value}`` when *value* is truthy, else ``{}``: an optional field."""+ return {key: value} if value else {}+++def _cross_repo_consumers(enricher: Any, alias: str, changed_files: list[str]) -> list[dict]:+ """Contract links in other repos whose provider file this change touches."""+ consumers: list[dict[str, Any]] = []+ seen: set[tuple[str, str, str, str]] = set()+ for path in changed_files:+ for link in enricher.get_contract_links_as_provider(alias, path):+ if link.get("consumer_repo") == alias:+ continue+ # Keyed by contract too: collapsing loses a contract_id.+ key = (+ link.get("consumer_repo") or "",+ link.get("consumer_file") or "",+ link.get("contract_id") or "",+ path,+ )+ if key in seen:+ continue+ seen.add(key)+ consumers.append(+ {+ "provider_file": path,+ "repo": link.get("consumer_repo"),+ "file": link.get("consumer_file"),+ "contract_id": link.get("contract_id"),+ "contract_type": link.get("contract_type"),+ "match_type": link.get("match_type"),+ **_present("provider_symbol_id", link.get("provider_symbol_id")),+ **_present("symbol_id", link.get("consumer_symbol_id")),+ }+ )+ return consumers+++def _breaking_row(change: dict[str, Any], cross: list[dict[str, Any]]) -> dict[str, Any]:+ return {+ "contract_id": change.get("contract_id"),+ "type": change.get("contract_type"),+ "kind": change.get("kind"),+ "severity": change.get("severity"),+ "detail": change.get("detail"),+ "provider_file": change.get("provider_file"),+ **_present("side", change.get("side")),+ **_present("comparison_source", change.get("comparison_source")),+ **_present("comparison_key", change.get("comparison_key")),+ **_present("field_name", change.get("field_name")),+ "impacted_repos": sorted({c.get("repo") or "" for c in cross}),+ **_present("provider_symbol_id", change.get("provider_symbol_id")),+ }+++def _cross_repo_breaking(+ enricher: Any, alias: str, touched: set[str]+) -> tuple[list[dict[str, Any]], int, int]:+ """Capped breaking rows with consumers elsewhere, the total, and how many are incompatible."""+ breaking: list[dict[str, Any]] = []+ total = 0+ incompatible = 0+ for change in enricher.get_breaking_changes_for_repo(alias):+ if change.get("provider_file") not in touched:+ continue+ cross = [c for c in change.get("impacted_consumers", []) if c.get("repo") != alias]+ if not cross:+ continue+ total += 1+ if change.get("severity") == "breaking":+ incompatible += 1+ if len(breaking) < _CROSS_REPO_BREAKING_LIMIT:+ breaking.append(_breaking_row(change, cross))+ return breaking, total, incompatible+++def _cross_repo_summary(+ consumers: list[dict], repos: list[str], totals: tuple[int, int], has_breaking_report: bool+) -> str:+ breaking_total, breaking_incompatible_total = totals+ summary = (+ f"{len(consumers)} consumer link(s) in {len(repos)} other repo(s) touch the "+ f"files this change edits"+ )+ if breaking_total:+ warnings = breaking_total - breaking_incompatible_total+ summary += (+ f"; {breaking_incompatible_total} provider incompatibility finding(s) and "+ f"{warnings} comparison warning(s) have endpoint-exposed consumers."+ )+ elif has_breaking_report:+ summary += "; the last workspace update found no break in them."+ else:+ summary += "; no breaking-change report has been built for them."+ return summary+++def _consumer_test_files(shown: list[dict], impact: Any) -> set[str]:+ """Test files recommended for the shown consumer rows."""+ # Counted over the shown rows, so it never promises tests the cap dropped.+ keys = {+ (+ row.get("repo") or "",+ comparable_path(row.get("file") or ""),+ row.get("contract_id") or "",+ )+ for row in shown+ }+ return {+ rec.test_file+ for rec in impact.recommendations+ for path in rec.consumer_files+ for cid in rec.contract_ids+ if (rec.consumer_repo, path, cid) in keys+ }+++def _attach_consumer_tests(+ shown: list[dict], impact: Any, collector: OmissionCollector | None+) -> str:+ """Add each shown consumer's tests block; return the sentence counting them."""+ for i, row in enumerate(shown):+ row["tests"] = tests_block_for(+ impact,+ row.get("repo") or "",+ row.get("file") or "",+ row.get("contract_id") or "",+ collector,+ f"cross_repo.consumers[{i}].tests.tests_to_run",+ )+ test_files = _consumer_test_files(shown, impact)+ undetermined = sum(1 for row in shown if row["tests"]["state"] == "unresolved")+ return (+ f" {len(test_files)} consumer test file(s) to run, "+ f"{undetermined} link(s) could not be determined."+ )+++def _workspace_enricher(changed_files: list[str]) -> Any:+ """The cross-repo enricher when it holds contract data for a non-empty change."""+ from repowise.server.mcp_server import _state++ if not changed_files or not _is_workspace_mode():+ return None+ enricher = _state._cross_repo_enricher+ if enricher is None or not getattr(enricher, "has_contract_data", False):+ return None+ return enricher++def _cross_repo_block(alias: str,changed_files: list[str],impact: Any = None,collector: OmissionCollector | None = None,) -> dict[str, Any] | None:- """What this commit does to consumers in other repos, or ``None``.-- A commit that changes a published signature is the same class of fact as- its fix history, so it belongs beside it. Two sources, both from the last- ``repowise update --workspace``: the contract links whose provider file this- commit touched (who calls it), and the breaking-change report entries- attributed to those same files (what broke). ``None`` outside workspace- mode, without artifacts, or when the commit touches no published file, so- the block never appears just to say nothing. Never raises.+ """What this change does to consumers in other repos, or ``None``.++ Built from the last workspace update: contract links whose provider file the+ change touches, and breaking-change entries for those files. ``None`` outside+ workspace mode, without artifacts, or when nothing published is touched.+ Never raises."""try:- from repowise.server.mcp_server import _state-- if not changed_files or not _is_workspace_mode():+ enricher = _workspace_enricher(changed_files)+ if enricher is None:return None- enricher = _state._cross_repo_enricher- if enricher is None or not getattr(enricher, "has_contract_data", False):- return None-- touched = set(changed_files)- consumers: list[dict[str, Any]] = []- seen: set[tuple[str, str, str, str]] = set()- for path in changed_files:- for link in enricher.get_contract_links_as_provider(alias, path):- if link.get("consumer_repo") == alias:- continue- # Keyed by contract too: collapsing loses a contract_id.- key = (- link.get("consumer_repo") or "",- link.get("consumer_file") or "",- link.get("contract_id") or "",- path,- )- if key in seen:- continue- seen.add(key)- consumers.append(- {- "provider_file": path,- "repo": link.get("consumer_repo"),- "file": link.get("consumer_file"),- "contract_id": link.get("contract_id"),- "contract_type": link.get("contract_type"),- "match_type": link.get("match_type"),- **(- {"provider_symbol_id": psid}- if (psid := link.get("provider_symbol_id"))- else {}- ),- **({"symbol_id": sid} if (sid := link.get("consumer_symbol_id")) else {}),- }- )-- breaking: list[dict[str, Any]] = []- breaking_total = 0- breaking_incompatible_total = 0+ consumers = _cross_repo_consumers(enricher, alias, changed_files)has_breaking_report = bool(getattr(enricher, "has_breaking_changes", False))- if has_breaking_report:- for change in enricher.get_breaking_changes_for_repo(alias):- if change.get("provider_file") not in touched:- continue- cross = [c for c in change.get("impacted_consumers", []) if c.get("repo") != alias]- if not cross:- continue- breaking_total += 1- if change.get("severity") == "breaking":- breaking_incompatible_total += 1- if len(breaking) >= _CROSS_REPO_BREAKING_LIMIT:- continue- breaking.append(- {- "contract_id": change.get("contract_id"),- "type": change.get("contract_type"),- "kind": change.get("kind"),- "severity": change.get("severity"),- "detail": change.get("detail"),- "provider_file": change.get("provider_file"),- **({"side": side} if (side := change.get("side")) else {}),- **(- {"comparison_source": source}- if (source := change.get("comparison_source"))- else {}- ),- **(- {"comparison_key": key} if (key := change.get("comparison_key")) else {}- ),- **(- {"field_name": field_name}- if (field_name := change.get("field_name"))- else {}- ),- "impacted_repos": sorted({c.get("repo") or "" for c in cross}),- **(- {"provider_symbol_id": psid}- if (psid := change.get("provider_symbol_id"))- else {}- ),- }- )-+ breaking, breaking_total, incompatible = (+ _cross_repo_breaking(enricher, alias, set(changed_files))+ if has_breaking_report+ else ([], 0, 0)+ )if not consumers and not breaking:return Nonereport = enricher.get_breaking_changes() or {}- # A removed endpoint has no current link, so its repos survive only on- # the breaking side.+ # A removed endpoint has no current link; its repos survive only as breaks.repos = sorted({c["repo"] for c in consumers if c.get("repo")}| {r for b in breaking for r in b["impacted_repos"] if r})- summary = (- f"{len(consumers)} consumer link(s) in {len(repos)} other repo(s) touch the "- f"files this change edits"+ summary = _cross_repo_summary(+ consumers, repos, (breaking_total, incompatible), has_breaking_report)- if breaking_total:- warnings = breaking_total - breaking_incompatible_total- summary += (- f"; {breaking_incompatible_total} provider incompatibility finding(s) and "- f"{warnings} comparison warning(s) have endpoint-exposed consumers."- )- elif has_breaking_report:- summary += "; the last workspace update found no break in them."- else:- summary += "; no breaking-change report has been built for them."shown = consumers[:_CROSS_REPO_CONSUMER_LIMIT]if impact is not None:- for i, row in enumerate(shown):- row["tests"] = tests_block_for(- impact,- row.get("repo") or "",- row.get("file") or "",- row.get("contract_id") or "",- collector,- f"cross_repo.consumers[{i}].tests.tests_to_run",- )- # Counted over the rows this payload actually carries, so the- # sentence never promises tests for a consumer the cap dropped.- keys = {- (- row.get("repo") or "",- comparable_path(row.get("file") or ""),- row.get("contract_id") or "",- )- for row in shown- }- test_files = {- rec.test_file- for rec in impact.recommendations- for path in rec.consumer_files- for cid in rec.contract_ids- if (rec.consumer_repo, path, cid) in keys- }- undetermined = sum(1 for row in shown if row["tests"]["state"] == "unresolved")- summary += (- f" {len(test_files)} consumer test file(s) to run, "- f"{undetermined} link(s) could not be determined."- )+ summary += _attach_consumer_tests(shown, impact, collector)return {"consumers": shown,"consumers_truncated": max(0, len(consumers) - _CROSS_REPO_CONSUMER_LIMIT),"consumer_repos": repos,"breaking_changes": breaking,"breaking_changes_truncated": breaking_total - len(breaking),- # False = no detection pass ran, so the empty list is silence.+ # False: no detection pass ran, so an empty list is silence."breaking_changes_available": has_breaking_report,- # Stamps the breaking half only; the consumer list comes from the- # contract artifact, which carries no exposed stamp.+ # Dates the breaking half only; contract links carry no stamp."breaking_changes_as_of": report.get("generated_at") or None,"summary": summary,}diff --git a/packages/server/src/repowise/server/mcp_server/tool_symbol.py b/packages/server/src/repowise/server/mcp_server/tool_symbol.pyindex 164d887a8..8be985ac1 100644--- a/packages/server/src/repowise/server/mcp_server/tool_symbol.py+++ b/packages/server/src/repowise/server/mcp_server/tool_symbol.py@@ -995,250 +995,214 @@ def _correct_ambiguity_note(result: dict[str, Any], _collector: Any) -> None:register_post_shed("get_symbol", _correct_ambiguity_note)[email protected](surface_order=30, artifact_type="source", presentation="source", evidence_basis="measured")-async def get_symbol(- symbol_id: str | None = None,- context_lines: int = 0,- repo: str | None = None,- query: str | None = None,- id: str | None = None,- depth: int = 1,- reference: dict[str, Any] | None = None,-) -> dict:- """Follow-up read of one symbol whose id another response already gave you.-- **Not an entry point.** ``get_answer`` already ships ``symbol_bodies``, and- for a whole file ``get_context(include=["skeleton"])`` or a plain Read is- one call instead of many. Reach here for a body that was elided, or for a- ``continuation`` / omission ref. Never walk a file symbol by symbol.-- Returns verified, line-numbered source for one indexed symbol, live range,- or omission ref. Ambiguity returns every candidate; an index miss returns- live fallback lines. A truncated result carries the exact continuation to- pass straight back.-- Args:- symbol_id: "path/to/file.py::Name", "path/to/file.py:140-180" for a- live range, or an omission ref.- context_lines: extra lines before/after (0-50).- repo: usually omitted.- query: omission refs only, regex/substring filter on lines. With- no id given, it is read as ``symbol_id``.- id: accepted alias for ``symbol_id``.- depth: 1 (default) is this symbol alone; 2-3 also returns the bodies- it calls, transitively, in ``callee_bodies``.- reference: structured source reference emitted by this tool. Its id- and repository are accepted together without caller translation.- """- if reference:- if not symbol_id and not id and isinstance(reference.get("id"), str):- symbol_id = reference["id"]- if (- repo is None- and _is_workspace_mode()- and isinstance(reference.get("repository"), str)- ):- repo = reference["repository"]- if repo == "all":- return _unsupported_repo_all("get_symbol")- ctx = await _resolve_repo_context(repo)-- t0 = time.perf_counter()- # ``id`` is an alias for ``symbol_id``. The CLAUDE.md tool table and the- # tool description both refer to this tool as ``get_symbol(id)``, so agents- # naturally call it with ``id=`` and hit a pydantic "field required" error- # on ``symbol_id`` — one isError early teaches the agent to abandon the- # server (agent-context doctrine). Accept both; ``symbol_id`` wins when both- # are given.+def _elapsed_ms(t0: float) -> float:+ return (time.perf_counter() - t0) * 1000+++def _reference_arguments(+ reference: dict[str, Any] | None,+ symbol_id: str | None,+ id: str | None,+ repo: str | None,+) -> tuple[str | None, str | None]:+ """``symbol_id`` and ``repo`` filled from a structured source reference."""+ if not reference:+ return symbol_id, repo+ if not symbol_id and not id and isinstance(reference.get("id"), str):+ symbol_id = reference["id"]+ if repo is None and _is_workspace_mode() and isinstance(reference.get("repository"), str):+ repo = reference["repository"]+ return symbol_id, repo+++def _requested_id(+ symbol_id: str | None, id: str | None, query: str | None+) -> tuple[str | None, str | None]:+ """The id asked for, from ``symbol_id``, its ``id`` alias, or a lone ``query``."""+ # Agents call this tool as ``get_symbol(id)``; ``symbol_id`` wins when both are given.if not symbol_id and id:symbol_id = idelif not symbol_id and query and query.strip():- # Hosts that defer tool schemas let a model guess ``query`` for the id.- # The line filter needs an id to apply to, so alone it is the id.+ # A lone ``query`` is a guessed id: the line filter needs an id to apply to.symbol_id, query = query, None- if not symbol_id or not symbol_id.strip():- return {- "symbol_id": symbol_id,- "error": 'get_symbol requires `symbol_id`, e.g. "path/to/file.py::Name".',- "_meta": _build_meta(timing_ms=(time.perf_counter() - t0) * 1000),- }+ return symbol_id, query- omission_ref = _extract_omission_ref(symbol_id)- if omission_ref is not None:- canonical_omission = omission_reference(symbol_id) or symbol_id- return _resolve_omission_ref(- canonical_omission,- omission_ref,- query,- ctx.path,- t0,- other_repo_roots() if repo is None else (),- )-- routes = await route_targets([symbol_id.strip()]) if repo is None else None- if needs_routing(routes):- route = routes[0]- if route.repo is None:- return {"symbol_id": symbol_id, **route.card(), "_meta": _build_meta()}- routed = await get_symbol(- route.local, context_lines=context_lines, repo=route.repo, query=query, depth=depth- )- if route.routed:- routed = {"repo": route.repo, **routed}- hint_misses(routed, routes)- return routed- # Range read: "path/to/file.py:140-180" (single colon + numeric range —- # never collides with "{path}::{name}").- range_match = _RANGE_ID_RE.match(symbol_id.strip())- if range_match and "::" not in symbol_id:- normalized_path = path_identity(range_match.group("path"))- range_start = int(range_match.group("start"))- range_end = int(range_match.group("end"))- if range_end < range_start:- range_start, range_end = range_end, range_start- normalized_id = f"{normalized_path}:{range_start}-{range_end}"- return await _resolve_range_read(- normalized_id,- normalized_path,- range_start,- range_end,- max(0, min(50, context_lines)),- ctx,- t0,- )+async def _routed_read(+ symbol_id: str, context_lines: int, query: str | None, depth: int+) -> dict | None:+ """The read served by the repo that owns *symbol_id*, or None to serve it here."""+ routes = await route_targets([symbol_id.strip()])+ if not needs_routing(routes):+ return None+ route = routes[0]+ if route.repo is None:+ return {"symbol_id": symbol_id, **route.card(), "_meta": _build_meta()}+ routed = await get_symbol(+ route.local, context_lines=context_lines, repo=route.repo, query=query, depth=depth+ )+ if route.routed:+ routed = {"repo": route.repo, **routed}+ hint_misses(routed, routes)+ return routed- repository = None- if context_lines < 0 or context_lines > 50:- # Bound context_lines to a sane range — runaway values would- # defeat the whole point of symbol-level retrieval.- context_lines = max(0, min(50, context_lines))- # Clamp rather than reject: an out-of-range depth is a caller reaching for- # more of the chain, and the useful reply is the deepest walk we will do.- depth = max(1, min(_MAX_CALLEE_DEPTH, depth))- async with get_session(ctx.session_factory) as session:- repository = await _get_repo(session)- rows = await _resolve_symbol(session, repository.id, symbol_id)+async def _range_id_read(symbol_id: str, context_lines: int, ctx: Any, t0: float) -> dict | None:+ """A live range read for a ``path:start-end`` id, else None."""+ range_match = _RANGE_ID_RE.match(symbol_id.strip())+ if not range_match or "::" in symbol_id:+ return None+ normalized_path = path_identity(range_match.group("path"))+ range_start = int(range_match.group("start"))+ range_end = int(range_match.group("end"))+ if range_end < range_start:+ range_start, range_end = range_end, range_start+ normalized_id = f"{normalized_path}:{range_start}-{range_end}"+ return await _resolve_range_read(+ normalized_id,+ normalized_path,+ range_start,+ range_end,+ max(0, min(50, context_lines)),+ ctx,+ t0,+ )- # Before the exclusion spec: it is built from the repo path.- if not ctx.path:- return {- "symbol_id": symbol_id,- "error": "MCP server has no repo path configured",- "_meta": _build_meta(- timing_ms=(time.perf_counter() - t0) * 1000,- repository=repository,- ),- }- exclude_spec = _get_exclude_spec(ctx.path)+async def _rows_in_scope(+ ctx: Any, repository: Any, symbol_id: str, rows: list[Any], exclude_spec: Any+) -> list[Any]:+ """*rows* outside the exclusion spec; a bare name one symbol carries resolves to it."""rows = [r for r in rows if not is_excluded(r.file_path, exclude_spec)]if not rows and "::" not in symbol_id:# A bare name one symbol carries is that symbol; several stay suggestions.async with get_session(ctx.session_factory) as session:- named, complete = await _symbols_named(- session, repository.id, symbol_id, exclude_spec- )+ named, complete = await _symbols_named(session, repository.id, symbol_id, exclude_spec)if complete and len(named) == 1:rows = await _resolve_symbol(session, repository.id, named[0])- if not rows:- # Dead-end recovery: constants/imports/aliases between indexed- # symbols miss the index but live in the file — grep the live file- # for the name and serve the matching lines instead of a pure error.- if ctx.path:- file_part, name_part = _parse_symbol_id(symbol_id)- if file_part and name_part and not is_excluded(file_part, exclude_spec):- matches = _live_grep_fallback(Path(str(ctx.path)), file_part, name_part)- if matches:- likely = (- "defined here, so likely added after the last index; "- "run `repowise update` to index it"- if any(m.get("defines") for m in matches)- else "likely a constant, import, or alias"- )- return {- "symbol_id": symbol_id,- "file": file_part,- "resolution": "live_grep",- "fallback_lines": matches,- "verified": True,- "note": (- "Not an indexed symbol, but the name matches these "- f"live-file lines ({likely}). For surrounding source "- f'use a range read: "{file_part}:<start>-<end>".'- ),- "_meta": _build_meta(- timing_ms=(time.perf_counter() - t0) * 1000,- repository=repository,- targets=[file_part],- ),- }- async with get_session(ctx.session_factory) as session:- suggestions = await _symbol_suggestions(session, repository.id, symbol_id, exclude_spec)- if suggestions:- return {- "symbol_id": symbol_id,- "error": (- f"Symbol not found: {symbol_id!r}. A symbol with this name "- "exists at the path(s) below — retry with one of these "- "exact symbol_ids."- ),- "suggestions": suggestions,- "_meta": _build_meta(- timing_ms=(time.perf_counter() - t0) * 1000,- repository=repository,- ),- }- return {- "symbol_id": symbol_id,- "error": (- f"Symbol not found: {symbol_id!r}. Use get_context to list "- "available symbols in the file, then try again with the "- "exact symbol_id from that response."- ),- "_meta": _build_meta(- timing_ms=(time.perf_counter() - t0) * 1000,- repository=repository,- ),- }+ return rows- if len(rows) > 1:- return await _render_ambiguous(rows, symbol_id, ctx, repository, t0, context_lines)- row = rows[0]- repo_root = Path(str(ctx.path))- text = _read_file_text(repo_root, row.file_path)+def _live_grep_response(+ ctx: Any, repository: Any, symbol_id: str, exclude_spec: Any, t0: float+) -> dict | None:+ """Live-file lines naming a symbol the index lacks (a constant, import or alias), else None."""+ file_part, name_part = _parse_symbol_id(symbol_id)+ if not file_part or not name_part or is_excluded(file_part, exclude_spec):+ return None+ matches = _live_grep_fallback(Path(str(ctx.path)), file_part, name_part)+ if not matches:+ return None+ likely = (+ "defined here, so likely added after the last index; "+ "run `repowise update` to index it"+ if any(m.get("defines") for m in matches)+ else "likely a constant, import, or alias"+ )+ return {+ "symbol_id": symbol_id,+ "file": file_part,+ "resolution": "live_grep",+ "fallback_lines": matches,+ "verified": True,+ "note": (+ "Not an indexed symbol, but the name matches these "+ f"live-file lines ({likely}). For surrounding source "+ f'use a range read: "{file_part}:<start>-<end>".'+ ),+ "_meta": _build_meta(+ timing_ms=_elapsed_ms(t0),+ repository=repository,+ targets=[file_part],+ ),+ }- if text is None:++async def _not_found_response(+ ctx: Any, repository: Any, symbol_id: str, exclude_spec: Any, t0: float+) -> dict:+ """Live lines, exact-id suggestions, or a not-found error for an index miss."""+ if ctx.path:+ live = _live_grep_response(ctx, repository, symbol_id, exclude_spec, t0)+ if live is not None:+ return live+ async with get_session(ctx.session_factory) as session:+ suggestions = await _symbol_suggestions(session, repository.id, symbol_id, exclude_spec)+ if suggestions:return {"symbol_id": symbol_id,- "file": row.file_path,- "name": row.name,- "kind": row.kind,- "signature": row.signature,"error": (- "Symbol metadata exists but source file could not be read. "- "The file may have been moved or deleted since indexing."+ f"Symbol not found: {symbol_id!r}. A symbol with this name "+ "exists at the path(s) below — retry with one of these "+ "exact symbol_ids."),+ "suggestions": suggestions,"_meta": _build_meta(- timing_ms=(time.perf_counter() - t0) * 1000,+ timing_ms=_elapsed_ms(t0),repository=repository,),}+ return {+ "symbol_id": symbol_id,+ "error": (+ f"Symbol not found: {symbol_id!r}. Use get_context to list "+ "available symbols in the file, then try again with the "+ "exact symbol_id from that response."+ ),+ "_meta": _build_meta(+ timing_ms=_elapsed_ms(t0),+ repository=repository,+ ),+ }- from repowise.core.distill.budget import estimate_tokens- full_tokens = estimate_tokens(text)+def _unreadable_source_response(row: Any, symbol_id: str, repository: Any, t0: float) -> dict:+ return {+ "symbol_id": symbol_id,+ "file": row.file_path,+ "name": row.name,+ "kind": row.kind,+ "signature": row.signature,+ "error": (+ "Symbol metadata exists but source file could not be read. "+ "The file may have been moved or deleted since indexing."+ ),+ "_meta": _build_meta(+ timing_ms=_elapsed_ms(t0),+ repository=repository,+ ),+ }+++class _ServedBody(NamedTuple):+ """The numbered lines served for one symbol, and the outline if it was outlined."""++ numbered: str+ start: int+ end: int+ truncated: bool+ outline: tuple[list[dict], int, int] | None- # Trust contract: verify the stored bounds against the live file before- # serving a single byte. Stale bounds get corrected via a one-file- # re-parse (and healed in the DB); un-relocatable symbols are served as- # the indexed guess, explicitly tagged approximate.- check = check_symbol_bounds(row, text)- if check.corrected:- await heal_symbol_row(ctx.session_factory, row, check.start_line, check.end_line)+async def _outline_if_large(+ ctx: Any, repository: Any, row: Any, text: str, check: Any+) -> tuple[list[dict], int, int] | None:+ """Members outline of a verified container body too large to serve whole."""+ if row.kind not in _CONTAINER_KINDS or not check.verified:+ return None+ # Sized on the body alone, so context_lines never tips a class into an outline.+ bare, bare_start, _e, _t = _slice_text(text, check.start_line, check.end_line, 0)+ if len(_number_lines(bare, bare_start)) <= _OUTLINE_MIN_CHARS:+ return None+ return await _container_outline(+ ctx.session_factory, repository.id, row, text, check.start_line, check.end_line+ )+++async def _served_body(+ ctx: Any, repository: Any, row: Any, text: str, check: Any, context_lines: int+) -> _ServedBody:+ """The body slice to serve: the whole body, a capped head, or a header plus outline."""source, start, end, _total = _slice_text(text, check.start_line, check.end_line, context_lines)numbered = _number_lines(source, start)@@ -1246,31 +1210,70 @@ async def get_symbol(check.end_line - check.start_line + 1 + 2 * context_lines) > _MAX_SOURCE_LINES- outline = None- if row.kind in _CONTAINER_KINDS and check.verified:- # Sized on the body alone, so context_lines never tips a class into an outline.- bare, bare_start, _e, _t = _slice_text(text, check.start_line, check.end_line, 0)- if len(_number_lines(bare, bare_start)) > _OUTLINE_MIN_CHARS:- outline = await _container_outline(- ctx.session_factory, repository.id, row, text, check.start_line, check.end_line- )- if outline is not None:- members, first_member, members_total = outline- header_end = min(- first_member - 1, check.start_line + _OUTLINE_HEADER_LINES - 1, check.end_line- )- # context_lines widens the header upward only; below it are the members.- source, start, end, _total = _slice_text(- text,- max(1, check.start_line - context_lines),- max(check.start_line, header_end),- 0,+ outline = await _outline_if_large(ctx, repository, row, text, check)+ if outline is None:+ return _ServedBody(numbered, start, end, truncated, None)+ _members, first_member, _members_total = outline+ header_end = min(first_member - 1, check.start_line + _OUTLINE_HEADER_LINES - 1, check.end_line)+ # context_lines widens the header upward only; below it are the members.+ source, start, end, _total = _slice_text(+ text,+ max(1, check.start_line - context_lines),+ max(check.start_line, header_end),+ 0,+ )+ source = source.rstrip()+ end = start + len(source.splitlines()) - 1 if source else start+ return _ServedBody(_number_lines(source, start), start, end, False, outline)+++def _note_outline(+ response: dict, outline: tuple[list[dict], int, int], row: Any, check: Any+) -> None:+ """Mark an outlined body and say how to fetch its members or the whole body."""+ members, _first_member, members_total = outline+ # An outline is not the body, so it never claims ``_meta.complete``.+ response["outlined"] = True+ response["members"] = members+ response["note"] = (+ f"Body ({check.start_line}-{check.end_line}) outlined: header plus "+ f"{len(members)} members. Fetch one member with get_symbol on its "+ f"symbol_id, or Read {row.file_path} lines "+ f"{check.start_line}-{check.end_line} for the whole body."+ )+ if members_total > len(members):+ response["members_total"] = members_total+ last = members[-1]["end_line"] if members else check.start_line+ response["note"] += (+ f" {members_total - len(members)} more members are not listed;"+ f" they start after line {last}.")- source = source.rstrip()- end = start + len(source.splitlines()) - 1 if source else start- numbered = _number_lines(source, start)- truncated = False++def _note_continuation(+ response: dict, body: _ServedBody, row: Any, check: Any, alias: Any+) -> None:+ """Hand back the exact range read that fetches the rest of a capped body."""+ continuation_reference = source_reference(+ alias,+ row.file_path,+ lines=[body.end + 1, check.end_line],+ verification_basis="live",+ source_kind="source",+ )+ response["continuation"] = continuation_reference["id"]+ response["continuation_reference"] = continuation_reference+ response["note"] = (+ f"Symbol body ({check.start_line}-{check.end_line}) exceeds the "+ f"{_MAX_SOURCE_LINES}-line serve cap; served {body.start}-{body.end}. Fetch "+ f"the remainder in one call: get_symbol({response['continuation']!r})."+ )+++def _symbol_body_response(+ row: Any, check: Any, body: _ServedBody, repository: Any, alias: Any, t0: float+) -> dict:+ """The served body with its outline, continuation and bounds notes."""response = {"symbol_id": symbol_identity(row.symbol_id),"file": row.file_path,@@ -1279,61 +1282,29 @@ async def get_symbol("qualified_name": row.qualified_name,"signature": row.signature,"language": row.language,- "start_line": start,- "end_line": end,+ "start_line": body.start,+ "end_line": body.end,"symbol_start_line": check.start_line,"symbol_end_line": check.end_line,- "source": numbered,- "truncated": truncated,+ "source": body.numbered,+ "truncated": body.truncated,"verified": check.verified,"_meta": _build_meta(- timing_ms=(time.perf_counter() - t0) * 1000,+ timing_ms=_elapsed_ms(t0),hint=_symbol_hint(row.symbol_id, check.end_line, check.start_line),repository=repository,# Served bytes are live-verified; only this file's drift matters.targets=[row.file_path],),}- if outline is not None:- # An outline is not the body, so it never claims ``_meta.complete``.- response["outlined"] = True- response["members"] = members- response["note"] = (- f"Body ({check.start_line}-{check.end_line}) outlined: header plus "- f"{len(members)} members. Fetch one member with get_symbol on its "- f"symbol_id, or Read {row.file_path} lines "- f"{check.start_line}-{check.end_line} for the whole body."- )- if members_total > len(members):- response["members_total"] = members_total- last = members[-1]["end_line"] if members else check.start_line- response["note"] += (- f" {members_total - len(members)} more members are not listed;"- f" they start after line {last}."- )- elif not truncated and check.verified:+ if body.outline is not None:+ _note_outline(response, body.outline, row, check)+ elif not body.truncated and check.verified:# The whole body was served against live bytes, so nothing is left to# fetch for this symbol.response["_meta"]["complete"] = _completeness_line(bodies=1)- if truncated and not check.approximate and end < check.end_line:- # The body exceeds the serve cap. Hand back the exact range read that- # fetches the remainder so the agent never has to guess the next span- # (the S1 dogfood found it would otherwise grub-around with a guessed- # range, doubling the call cost).- continuation_reference = source_reference(- ctx.alias,- row.file_path,- lines=[end + 1, check.end_line],- verification_basis="live",- source_kind="source",- )- response["continuation"] = continuation_reference["id"]- response["continuation_reference"] = continuation_reference- response["note"] = (- f"Symbol body ({check.start_line}-{check.end_line}) exceeds the "- f"{_MAX_SOURCE_LINES}-line serve cap; served {start}-{end}. Fetch "- f"the remainder in one call: get_symbol({response['continuation']!r})."- )+ if body.truncated and not check.approximate and body.end < check.end_line:+ _note_continuation(response, body, row, check, alias)if check.approximate:response["bounds"] = "approximate"response["note"] = (@@ -1343,8 +1314,39 @@ async def get_symbol("the indexed line range from the current file contents; verify ""before citing.")+ return response+++async def _serve_symbol(+ ctx: Any,+ repository: Any,+ row: Any,+ symbol_id: str,+ context_lines: int,+ depth: int,+ exclude_spec: Any,+ t0: float,+) -> dict:+ """Live-verified body of one resolved symbol, with callee bodies past depth 1."""+ repo_root = Path(str(ctx.path))+ text = _read_file_text(repo_root, row.file_path)+ if text is None:+ return _unreadable_source_response(row, symbol_id, repository, t0)++ from repowise.core.distill.budget import estimate_tokens++ full_tokens = estimate_tokens(text)++ # Stored bounds are checked against the live file first: stale ones are+ # corrected and healed, unfindable ones served as approximate.+ check = check_symbol_bounds(row, text)+ if check.corrected:+ await heal_symbol_row(ctx.session_factory, row, check.start_line, check.end_line)++ body = await _served_body(ctx, repository, row, text, check, context_lines)+ response = _symbol_body_response(row, check, body, repository, ctx.alias, t0)# An outline answers for the shape; callee bodies would undo its size.- if depth > 1 and outline is None:+ if depth > 1 and body.outline is None:async with get_session(ctx.session_factory) as session:callee_block = await _expand_callees(session,@@ -1358,9 +1360,113 @@ async def get_symbol(if callee_block is not None:response["callee_bodies"] = callee_block- # Declare the exact counterfactual: serving one symbol replaced Reading the- # whole file. The savings instrumentation prefers this over its estimator.+ # Serving one symbol replaced reading the whole file.from repowise.server.mcp_server._savings import declare_replaceddeclare_replaced(response, full_tokens)return response+++async def _indexed_symbol_read(+ ctx: Any, symbol_id: str, context_lines: int, depth: int, t0: float+) -> dict:+ """Resolve *symbol_id* in the index and serve it, its candidates, or a miss."""+ context_lines = max(0, min(50, context_lines))+ # Clamped, not rejected: the deepest walk we do is the useful reply.+ depth = max(1, min(_MAX_CALLEE_DEPTH, depth))++ async with get_session(ctx.session_factory) as session:+ repository = await _get_repo(session)+ rows = await _resolve_symbol(session, repository.id, symbol_id)++ # Before the exclusion spec: it is built from the repo path.+ if not ctx.path:+ return {+ "symbol_id": symbol_id,+ "error": "MCP server has no repo path configured",+ "_meta": _build_meta(+ timing_ms=_elapsed_ms(t0),+ repository=repository,+ ),+ }++ exclude_spec = _get_exclude_spec(ctx.path)+ rows = await _rows_in_scope(ctx, repository, symbol_id, rows, exclude_spec)+ if not rows:+ return await _not_found_response(ctx, repository, symbol_id, exclude_spec, t0)+ if len(rows) > 1:+ return await _render_ambiguous(rows, symbol_id, ctx, repository, t0, context_lines)+ return await _serve_symbol(+ ctx, repository, rows[0], symbol_id, context_lines, depth, exclude_spec, t0+ )++[email protected](surface_order=30, artifact_type="source", presentation="source", evidence_basis="measured")+async def get_symbol(+ symbol_id: str | None = None,+ context_lines: int = 0,+ repo: str | None = None,+ query: str | None = None,+ id: str | None = None,+ depth: int = 1,+ reference: dict[str, Any] | None = None,+) -> dict:+ """Follow-up read of one symbol whose id another response already gave you.++ **Not an entry point.** ``get_answer`` already ships ``symbol_bodies``, and+ for a whole file ``get_context(include=["skeleton"])`` or a plain Read is+ one call instead of many. Reach here for a body that was elided, or for a+ ``continuation`` / omission ref. Never walk a file symbol by symbol.++ Returns verified, line-numbered source for one indexed symbol, live range,+ or omission ref. Ambiguity returns every candidate; an index miss returns+ live fallback lines. A truncated result carries the exact continuation to+ pass straight back.++ Args:+ symbol_id: "path/to/file.py::Name", "path/to/file.py:140-180" for a+ live range, or an omission ref.+ context_lines: extra lines before/after (0-50).+ repo: usually omitted.+ query: omission refs only, regex/substring filter on lines. With+ no id given, it is read as ``symbol_id``.+ id: accepted alias for ``symbol_id``.+ depth: 1 (default) is this symbol alone; 2-3 also returns the bodies+ it calls, transitively, in ``callee_bodies``.+ reference: structured source reference emitted by this tool. Its id+ and repository are accepted together without caller translation.+ """+ symbol_id, repo = _reference_arguments(reference, symbol_id, id, repo)+ if repo == "all":+ return _unsupported_repo_all("get_symbol")+ ctx = await _resolve_repo_context(repo)++ t0 = time.perf_counter()+ symbol_id, query = _requested_id(symbol_id, id, query)+ if not symbol_id or not symbol_id.strip():+ return {+ "symbol_id": symbol_id,+ "error": 'get_symbol requires `symbol_id`, e.g. "path/to/file.py::Name".',+ "_meta": _build_meta(timing_ms=_elapsed_ms(t0)),+ }++ omission_ref = _extract_omission_ref(symbol_id)+ if omission_ref is not None:+ canonical_omission = omission_reference(symbol_id) or symbol_id+ return _resolve_omission_ref(+ canonical_omission,+ omission_ref,+ query,+ ctx.path,+ t0,+ other_repo_roots() if repo is None else (),+ )++ if repo is None:+ routed = await _routed_read(symbol_id, context_lines, query, depth)+ if routed is not None:+ return routed+ ranged = await _range_id_read(symbol_id, context_lines, ctx, t0)+ if ranged is not None:+ return ranged+ return await _indexed_symbol_read(ctx, symbol_id, context_lines, depth, t0)