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
docs(server): shorten comments in get_context target resolution (#2579)
Raghav Chamadiya664582cb294c
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py b/packages/server/src/repowise/server/mcp_server/tool_context/targets.pyindex dbaa0c287..011f512aa 100644--- a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py+++ b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py@@ -69,14 +69,11 @@ from repowise.server.mcp_server.tool_context.kg import ()from repowise.server.mcp_server.tool_risk.assessment import fix_annotation-#: How many users of a symbol the card carries. The asymmetry is recorded, not-#: explained: the sibling ``imported_by`` on a file target carries no cap at-#: all, and nothing in the code or its history says whether that is a decision-#: or an omission. This constant only names the cut that already existed.+#: How many users of a symbol the card carries. The file target's+#: ``imported_by`` is uncapped; whether that asymmetry is intended is unknown._MAX_USED_BY = 20-#: Caps for the two decision lanes that are not the accepted one. A candidate-#: is a review request rather than a rule, and a withdrawn decision is context,-#: so neither is worth spending the shared response budget the card needs.+#: Caps for the non-accepted decision lanes: a candidate is a review request+#: and a withdrawn decision is context, neither worth the shared budget._MAX_CANDIDATES = 3_MAX_DECISION_HISTORY = 2@@ -84,27 +81,9 @@ _MAX_DECISION_HISTORY = 2#: 32,766 after, and which applies depends on the libsqlite3 linked at runtime._RANK_LOOKUP_CHUNK = 500-# Skeleton-by-default is GONE; ``include=["skeleton"]`` still serves it in full.-#-# It was introduced on the claim that "a 1,400-line file's default card costs-# ~2.5k tokens for 16 bare signatures, while the smart skeleton costs ~1.7k" —-# strictly better per token. Re-measured 2026-08-11 on pinned Textualize/rich,-# whole serialised cards in characters, auto-upgrade suppressed for the-# comparison:-#-# target auto card symbol-list card skeleton text alone-# rich/ansi.py 6,585 2,171 5,295-# rich/text.py 13,365 8,562 12,247-# rich/color.py 8,591 4,818 7,405-#-# The symbol list is 1,321 chars on ansi.py where the skeleton text is 5,295.-# The original claim is inverted on this corpus, and the auto card was 73-91%-# source text on every sample — text the agent can Read for ~1/5 the marginal-# cost of a mid-session tool result, which is what the block's own-# ``mostly_full`` note ("a direct Read costs little more") was already saying-# at the agent's expense. So the default card is the symbol list again and the-# skeleton is opt-in. If you restore an auto-upgrade, re-run the measurement-# first: the numbers above are the bar.+# The default file card is the symbol list; the skeleton is opt-in via+# ``include=["skeleton"]``. An auto-upgraded card was mostly source text, which+# a direct Read serves more cheaply, so measure card sizes before restoring one.def _synthesize_structural_summary(file_path: str, classes: list[str], functions: list[str]) -> str:@@ -129,9 +108,8 @@ def _synthesize_structural_summary(file_path: str, classes: list[str], functionsreturn f"{name}: " + "; ".join(parts) + "."-# The summary a file with no indexed symbols falls back to. Named so the-# preview block below can recognise its own stub and correct it rather than-# string-matching the sentence in two places.+# The summary a symbol-less file falls back to; named so the preview block can+# recognise and replace its own stub._NO_SYMBOL_SUMMARY_SUFFIX = "empty or non-symbol file"@@ -147,11 +125,8 @@ def _preview_summary(file_path: str, preview: dict[str, Any]) -> str:return f"{name}: {lines} lines, no indexed symbols."-# A file with no indexed symbols (README, YAML config, SQL, plain text) used to-# get a card whose entire content was "<name>: empty or non-symbol file", a-# reply that restates the filename and answers nothing, so the next move was-# always a Read or a grep the tool could have saved. These bounds keep the-# replacement preview cheap enough to stay on by default.+# Bounds on the preview a symbol-less file (README, YAML, SQL) gets, cheap+# enough to stay on by default._PREVIEW_MAX_LINES = 15_PREVIEW_MAX_LINE_CHARS = 120# Beyond this the file is big enough that a preview would misrepresent it; the@@ -316,16 +291,9 @@ async def _resolve_one_target()page = res.scalar_one_or_none()if page is None:- # Partial match fallback for modules — but only on a path-segment- # boundary, so "api" matches "src/api" yet "apiclient"/"pi" do not.- # Curated module ids are path-shaped, so a raw substring match can- # (a) hit 2+ module paths (→ MultipleResultsFound) and (b) shadow a- # real file of the same name. Guard against both here.- #- # First: if the target is itself a known real file (present in- # git_metadata, the same source the git fallback rung uses), do NOT- # let a partial module match preempt that — fall through so the- # ladder reaches the "exists but no wiki page" rung below.+ # Partial module match, only on a path-segment boundary ("api"+ # matches "src/api", not "apiclient"). Skipped when the target is a+ # known file, so a module match cannot shadow the file rung below.file_meta_res = await session.execute(select(GitMetadata.file_path).where(GitMetadata.repository_id == repo_id,@@ -347,9 +315,8 @@ async def _resolve_one_target(),))- # Deterministic pick when several module paths match: shortest- # target_path first, ties broken lexicographically. Module- # counts are small, so picking in Python is robust and cheap.+ # Deterministic pick among several matches: shortest path, then+ # lexicographic.candidates = sorted(res.scalars().all(), key=lambda p: (len(p.target_path), p.target_path))@@ -358,16 +325,9 @@ async def _resolve_one_target(if page:target_type = "module"else:- # 3. Try symbol.- #- # A "{path}::{Name}" target goes through the shared symbol lookup,- # the same ladder get_symbol uses, so an id lifted from one tool's- # response resolves in the other, in whichever separator style the- # caller wrote the qualified part. Matching such a target verbatim- # against WikiSymbol.name can only ever miss (a stored name is one- # segment, never a path-qualified id), and the ilike below would- # then scan for a "%path::Class.method%" substring that no name- # column contains. Both rungs are skipped for qualified ids.+ # 3. Try symbol. A "{path}::{Name}" id goes through get_symbol's+ # lookup so ids resolve the same in both tools; the name rungs+ # below can never match a path-qualified id.if "::" in target:sym_matches = await resolve_symbol_rows(session, repo_id, target)else:@@ -406,14 +366,9 @@ async def _resolve_one_target(file_path_for_git = targetif target_type is None:- # Fallback 1: index-only mode (no wiki pages). Return the graph node.- #- # The call graph keys its symbol nodes as "{path}::{Class}::{method}",- # so a symbol target with no WikiSymbol row matches here, and used to- # be typed as a *file*. The card then looked up symbols whose file_path- # was the whole id, found none, and reported the symbol as an "empty or- # non-symbol file". Type the node by what it is instead: a symbol node- # is a symbol target, and its file is the node's file, not its id.+ # Fallback 1: index-only mode (no wiki pages). Return the graph node,+ # typed by what it is: a symbol node is a symbol target whose file is+ # the node's file, not its id.res = await session.execute(select(GraphNode).where(GraphNode.repository_id == repo_id,@@ -441,12 +396,8 @@ async def _resolve_one_target()meta = res.scalar_one_or_none()if meta:- # Say so when the file was excluded on size. The generic answer- # below ("too few symbols or below the PageRank threshold")- # sends the reader to regenerate docs, which cannot help: the- # file was never read, so no amount of updating will produce a- # page. Computed from the same function that made the decision,- # so the two cannot drift (#1237).+ # A file excluded on size will never get a page, so regenerating+ # docs cannot help; say so instead of the generic answer.size_note = _size_exclusion_note(repo_root, target)if size_note:return {@@ -459,19 +410,16 @@ async def _resolve_one_target(live_file_meta = metapage = None- # A producer can legitimately surface a live repository file that was- # never indexed into git_metadata (for example, an analysis finding- # imported from an older index). Its repository-relative path remains- # a valid public identifier, so resolve it from the live checkout.+ # A live file never indexed into git_metadata is still a valid public+ # path; resolve it from the checkout.if target_type is None and _file_preview(repo_root, target) is not None:target_type = "file"file_path_for_git = targetpage = Nonelive_unindexed_file = True- # Fallback 2b: legacy module ids. Wiki modules used to be keyed by- # community ordinal ("community-12"); they are now keyed by directory- # path. Point old agent habits at the new vocabulary.+ # Fallback 2b: legacy "community-12" module ids; point them at the+ # directory-path vocabulary.if target_type is None and re.fullmatch(r"community[-_]\d+", clean_target, re.IGNORECASE):res = await session.execute(select(Page.target_path)@@ -493,13 +441,9 @@ async def _resolve_one_target("suggestions": module_paths,}- # Fallback 2c: a "{path}::{Name}" target whose symbol half did not- # resolve, but whose file half is a real indexed file. The caller asked- # about something *in* that file, so the file's card is a partial answer- # and a strictly better reply than "not found": it carries the symbol- # list, which is where the correct id was going to come from anyway.- # Reported as ``resolved_to`` so the degrade is legible rather than- # looking like the symbol was found.+ # Fallback 2c: an unresolved "{path}::{Name}" whose file is real gets+ # the file's card (its symbol list holds the right id), marked with+ # ``resolved_to`` so the degrade is legible.if target_type is None and "::" in target:file_part = target.split("::", 1)[0]if file_part and file_part != target and not is_excluded(file_part, exclude_spec):@@ -578,9 +522,8 @@ async def _resolve_one_target(result_data["index_status"] = "live_file_without_index_record"result_data["verification_basis"] = "live"- # Tombstone redirect: the page documents a file deleted or renamed since- # indexing. A "fresh" card here is an active trap — return the redirect- # instead of the card.+ # Tombstone: the file was deleted or renamed since indexing, so return the+ # redirect rather than a misleading card.if page is not None and getattr(page, "freshness_status", "") == "tombstone":import json as _json_ts@@ -597,10 +540,7 @@ async def _resolve_one_target(return result_data# --- Parent page (position in the concept tree) ------------------------ # Every placed page now carries parent_page_id, so a file target can point- # up to the subsystem/concept page that documents it, and a concept page- # up to its layer. One extra get() on the already-open session; the row is- # a full ORM object here, so parent_page_id is already loaded.+ # Points a file up to its concept page, a concept page up to its layer.if page is not None and page.parent_page_id:parent = await session.get(Page, page.parent_page_id)if (@@ -608,9 +548,7 @@ async def _resolve_one_target(and parent.repository_id == repo_idand getattr(parent, "freshness_status", "") != "tombstone"):- # Skip a tombstoned parent: pointing an agent up-tree at a page- # whose directory was deleted or renamed since indexing is the- # same trap the target's own tombstone redirect above avoids.+ # Skip a tombstoned parent, for the reason of the redirect above.result_data["parent_page"] = {"title": parent.title,"target_path": parent.target_path,@@ -643,24 +581,14 @@ async def _resolve_one_target(classes = [s.name for s in symbols if s.kind == "class"]functions = [s.name for s in symbols if s.kind in ("function", "method")]if want_skeleton:- # A requested skeleton suppresses the symbol list: it already- # renders every signature with line bounds, so repeating the- # list in docs would roughly double the response for zero- # information. Keep the cheap title/summary card only.+ # The skeleton already renders every signature with line+ # bounds, so the symbol list would only double the response.if not docs.get("summary"):docs["summary"] = _synthesize_structural_summary(target, classes, functions)elif compact:- # Compact mode: name+kind+signature+line+symbol_id only. Drops- # docstrings, line ranges, structure, and imported_by — those- # live behind compact=False or include= flags. The symbol_id- # is the canonical handle the caller pipes straight into- # get_symbol when it wants bytes.- #- # Cap at 40 symbols so a dense generated file (protobuf- # wrappers, vendored libs) can't blow the triage card past- # the agent's budget. Order matches WikiSymbol.start_line- # (assigned at index time), so the head is the navigationally- # useful slice.+ # Compact: name, kind, signature, line and symbol_id only. The+ # cap stops a dense generated file blowing the budget; symbols+ # are in start_line order, so the head is the useful slice.symbol_cap = 40visible = list(symbols)[:symbol_cap]docs["symbols"] = [@@ -706,14 +634,10 @@ async def _resolve_one_target("total_loc": total_loc,"avg_complexity": round(avg_complexity, 2),}- # Fallback summary: if no Page (index-only mode) or page.summary- # is empty, synthesize a deterministic one-liner from structure.if not docs.get("summary"):docs["summary"] = _synthesize_structural_summary(target, classes, functions)- # Importers. The key is literally ``imported_by``, so the scan- # has to exclude the edge types that are not references —- # otherwise a file that merely tends to change alongside this- # one is served to the agent as one of its importers.+ # Non-reference edges (e.g. co-change) are excluded, or a file+ # that merely changes alongside this one reads as an importer.res = await session.execute(select(GraphEdge).where(GraphEdge.repository_id == repo_id,@@ -743,19 +667,13 @@ async def _resolve_one_target("label": _cmeta.get("label", ""),}- # A file the symbol index has nothing for still exists and still has- # content. Serving counts and a verbatim excerpt costs one read and- # answers the "what is in here" the caller was asking; the card- # without it restates the filename. Applies to all three shapes- # above; none of them has anything to say about a symbol-less file.+ # A symbol-less file still has content: one read serves counts and+ # a verbatim excerpt instead of a card that restates the filename.if not symbols:preview = _file_preview(repo_root, target)if preview is not None:docs["file_preview"] = preview- # "empty or non-symbol file" is the only summary a- # symbol-less file could get, and next to a preview showing- # 800 lines of headings it is simply false. Restate it from- # what the preview actually counted.+ # Replace the stub summary with the preview's own counts.if docs.get("summary", "").endswith(_NO_SYMBOL_SUMMARY_SUFFIX):docs["summary"] = _preview_summary(target, preview)@@ -766,11 +684,7 @@ async def _resolve_one_target(docs["section"] = page.section_numberif want_full_doc:docs["content_md"] = page.content- # Direct sub-concept children in the tree (nested subsystems, api- # contracts, symbol spotlights). File children are covered by the- # member "files" list below, so listing them here too would just- # double the response; this surfaces the tree's real sub-structure- # where it exists and is omitted when there is none.+ # Non-file children only; file children are in "files" below.res = await session.execute(select(Page).where(@@ -808,9 +722,7 @@ async def _resolve_one_target([{"path": f.target_path,- # Page titles are "File: <path>" — pure redundancy- # next to the path field. Use the indexed one-line- # summary when there is one.+ # The title ("File: <path>") repeats the path."description": (f.summary or "").strip()[:160],"confidence_score": f.confidence,}@@ -843,21 +755,12 @@ async def _resolve_one_target(docs["file_summary"] = sym_page.summary or ""if want_full_doc:docs["documentation"] = sym_page.content- # Used by: the files that use THIS symbol. Keyed on the symbol's- # own node id, because a ``calls`` edge is symbol-to-symbol and- # targets a ``path::Name``; keyed on the file path, as it was until- # now, it could only match edges into the whole file and answered- # "who imports this symbol's file" instead. Positive vocabulary- # rather than a negative filter, for the reason #1905 gave the- # sibling path in get_risk: an untyped edge must not become a use.- #- # Sources fold to their file, which keeps one row per using file and- # keeps this distinct from ``callers`` (symbol-grained, calls-only,- # opt-in). The list is cut at ``_MAX_USED_BY`` and the agent never- # learns what fell off, so which twenty survive is the whole of what- # it says: on the 42-index corpus ranking moves the kept set on- # 4,447 of the 4,743 targets over the cap, a median of 7 of the 20.- # Rank by the source file's PageRank, path breaking ties.+ # Used by: files that use THIS symbol, keyed on its node id (a+ # ``calls`` edge targets ``path::Name``; the file path would answer+ # "who imports the file"). A positive edge vocabulary, so an untyped+ # edge never becomes a use. Sources fold to one row per file, unlike+ # symbol-grained ``callers``. The cap drops rows silently, so which+ # survive matters: rank by source-file PageRank, path breaking ties.sym_node_id = getattr(sym, "symbol_id", None) or getattr(sym, "node_id", None)res = await session.execute(select(GraphEdge.source_node_id, GraphNode.file_path)@@ -934,22 +837,12 @@ async def _resolve_one_target(result_data["docs"] = docs# --- Triage signals (always on) ---------------------------------------- # Two single-bit-ish pointers the agent uses to decide its next move:- # * ``hotspot``: lights the way to ``get_risk`` for files in the 95th+- # churn percentile. Just the boolean — the full risk dossier stays- # in ``get_risk`` so the triage card doesn't grow.- # * ``fix_history``: the same pointer for the defect signal, and the- # reason the card grew by one key. ``hotspot`` alone answers "is this- # file busy", which is not the same question as "does this file break",- # and get_risk already classifies targets bug-prone off these columns.- # Count plus age plus the magnet flag, no symbols and no dossier;- # omitted entirely on files with no counted fixes.- # * ``decision_records``: titles only, no body. Lights the way to- # ``get_why``. We deliberately don't inline the rationale here;- # duplicating it across every ``get_context`` response bloats the- # cached prompt prefix and defeats the split between the two tools.- #- # Cheap: two short queries piggybacking on the session we already opened.+ # Small pointers to the next tool, never the dossier itself:+ # * ``hotspot``: points to ``get_risk`` for high-churn files.+ # * ``fix_history``: "does this file break", which churn does not+ # answer; omitted on files with no counted fixes.+ # * ``decision_records``: titles only, pointing to ``get_why``; inlining+ # rationale would bloat every cached response.triage_path = file_path_for_gitif target_type == "module" and page:triage_path = page.target_path@@ -975,12 +868,8 @@ async def _resolve_one_target(if fixes is not None:result_data["fix_history"] = fixes- # Governing decisions — opt-in only (``include=["decisions"]``).- # The default triage card omits them: the rich form- # (id/staleness/verification) is low-signal for an agent's next move and- # the per-call graph query isn't worth the latency or the cached-prefix- # weight. Agents that want rationale call get_why directly; opting in- # here returns a lightweight titles list (no enriched objects).+ # Governing decisions, opt-in only: the graph query is not worth its+ # latency on every card. Returns titles; get_why has the rationale.if include and "decisions" in include:governing: list[DecisionRecord] = []seen_ids: set[str] = set()@@ -1079,30 +968,15 @@ async def _resolve_one_target(# --- Decisions ---if include is None or "decisions" in include:- # Acceptance is authority, and the status column is not it. This query- # used to select every record for the repository with no status, no- # acceptance and no dismissed filter and assign the whole list to- # ``decisions``, so a machine-mined candidate and a dismissed tombstone- # both reached an agent as a rule the repository had settled on.- #- # The lanes are ``get_why`` path mode's, spelled the same way on- # purpose: ``decisions`` is accepted and still binding, ``candidates``- # is never accepted, ``history`` is accepted and withdrawn. Two agent- # tools answering the same question in two vocabularies is the divergence- # the split exists to remove.- #- # The order is ``decision_priority_order``, which is what the Decisions- # page renders through ``crud.list_decisions(sort="priority")``. Ordering- # is shared rather than restated so the two surfaces cannot drift.+ # Acceptance is authority, not the status column. The lanes match+ # ``get_why`` path mode: ``decisions`` accepted and binding,+ # ``candidates`` never accepted, ``history`` accepted then withdrawn.+ # Ordering is ``decision_priority_order``, shared with the Decisions page.#- # The dismissed filter is ``count_decisions_by_lane``'s, and for its- # reason: ``dismiss_candidate`` writes ``status = "dismissed"`` both for- # a candidate tombstoned so re-extraction never re-proposes it and for a- # decision somebody accepted and later withdrew. Only the acceptance row- # tells the two apart. A bare ``status != "dismissed"`` drops both, which- # loses the withdrawn decision from every lane instead of putting it in- # the one that exists for it — and the Decisions page's History lane- # shows exactly those records, so dropping them here is a divergence.+ # The dismissed filter is ``count_decisions_by_lane``'s: "dismissed"+ # marks both a tombstoned candidate and a withdrawn decision, and only+ # the acceptance row tells them apart, so a bare status filter would+ # lose the withdrawn ones from the history lane.res = await session.execute(select(DecisionRecord).where(@@ -1117,8 +991,7 @@ async def _resolve_one_target(candidates: list[dict[str, Any]] = []history: list[dict[str, Any]] = []for d in all_decisions:- # A commit footprint is not a claim about any one of its- # files.+ # A commit footprint is not a claim about any one of its files.if not binds_to_paths(d.scope_basis):continueaffected_files = json.loads(d.affected_files_json)@@ -1150,12 +1023,9 @@ async def _resolve_one_target(entry["currency"] = currencyhistory.append(entry)result_data["decisions"] = governing- # The response budget is one ceiling over the whole payload, not one- # per block, so an uncapped new lane does not appear beside the card —- # it displaces the docs and symbols the caller asked for. Accepted- # decisions keep the behaviour they have (a set acceptance keeps small- # by construction); the two lanes this adds are capped where they are- # built, and what a cap drops is recoverable through the collector.+ # One budget covers the whole payload, so an uncapped lane would+ # displace the docs the caller asked for. Accepted decisions stay+ # uncapped (small by construction); dropped rows go to the collector.if candidates:cap_collection(result_data,@@ -1176,31 +1046,14 @@ async def _resolve_one_target()# --- Freshness ---- #- # ``is_stale`` reads ``freshness_status`` through the same predicate- # ``repowise generate --stale`` uses, rather than thresholding- # ``confidence``. Two separate corrections in one line.- #- # The axis was wrong: freshness is whether a page has fallen behind the- # code it documents, confidence is how far its statements can be trusted- # while it has not. Thresholding the latter reported a *module* page as- # stale on the day it was built, because generation stamped every module- # page a keyless run rendered below the threshold. File and symbol targets- # were unaffected, since their pages are template renders at full- # confidence, so this was a module-target bug rather than a whole-tool one.- #- # The word was also being redefined: importing the CLI's set keeps one- # meaning of "stale" in the product. A hand-rolled ``!= "fresh"`` would- # quietly widen it to cover ``tombstone`` and ``outdated`` too, which is a- # different claim than the one the flag makes.+ # ``is_stale`` uses ``STALE_STATUSES``, the set ``repowise generate --stale``+ # uses, so "stale" means one thing. Not ``confidence``: that rates how far a+ # page can be trusted, not whether it has fallen behind the code.if include is None or "freshness" in include:freshness: dict[str, Any] = {}def _is_stale(row: Page) -> bool:- # Defensive on None: the column is NOT NULL with a "fresh" default- # and every write path passes it, but the old expression guarded- # its input and dropping the guard would turn a hand-written row- # into a stale one rather than a fresh one.+ # The column is NOT NULL, but a hand-written None reads as fresh.return (row.freshness_status or "fresh") in STALE_STATUSESif page: