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(context): resolve get_context targets through an ordered resolver list (#3988)
Raghav Chamadiya6ed500d0ca8d
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/preview.py b/packages/server/src/repowise/server/mcp_server/tool_context/preview.pynew file mode 100644index 000000000..7951c9b3d--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_context/preview.py@@ -0,0 +1,174 @@+"""Preview of a file the symbol index has nothing to say about.++Counts plus a few verbatim lines (headings for documents, head lines for+anything else), used by the file card and by the resolution ladder to accept a+live file that was never indexed.+"""++from __future__ import annotations++import re+from typing import Any++from repowise.server.mcp_server._helpers import read_repo_file_text++# 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"+++def _preview_summary(file_path: str, preview: dict[str, Any]) -> str:+ """One truthful line about a symbol-less file, built from its own counts."""+ name = file_path.rsplit("/", 1)[-1]+ lines = preview.get("lines", 0)+ if not lines:+ return f"{name}: empty file"+ heading_count = preview.get("heading_count")+ if heading_count:+ return f"{name}: {lines}-line document, {heading_count} headings, no indexed symbols."+ return f"{name}: {lines} lines, no indexed symbols."+++# Bounds on the preview a symbol-less file (README, YAML, SQL) gets: counts+# plus a few verbatim lines, cheap enough to stay on by default.+_PREVIEW_MAX_LINES = 3+_PREVIEW_MAX_LINE_CHARS = 120+# Beyond this the file is big enough that a preview would misrepresent it; the+# counts and the "go Read it" note are the honest reply.+_PREVIEW_MAX_BYTES = 2_000_000++_MARKDOWN_EXTS = (".md", ".markdown", ".mdx")+_RST_EXTS = (".rst",)+_MD_HEADING = re.compile(r" {0,3}#{1,6}(\s|$)")+_MD_FENCE = re.compile(r" {0,3}(`{3,}|~{3,})")+_RST_ADORNMENT = re.compile(r"([!-/:-@\[-`{-~])\1+")+# Lines that open with a comment marker: licence banners and the like.+_COMMENT_PREFIXES = ("#", "//", "--", "/*", "*", "<!--")+++def _markdown_headings(lines: list[str]) -> list[str]:+ """ATX headings outside front matter, fenced code and HTML comments."""+ headings: list[str] = []+ start = 0+ if lines and lines[0].strip() == "---":+ close = next((i for i in range(1, len(lines)) if lines[i].strip() in ("---", "...")), None)+ if close is not None:+ start = close + 1+ fence = ""+ in_comment = False+ for ln in lines[start:]:+ if in_comment:+ in_comment = "-->" not in ln+ continue+ if fence:+ # Only a bare run of the opening character, at least as long, closes.+ bare = ln.strip()+ if bare and set(bare) == {fence[0]} and len(bare) >= len(fence):+ fence = ""+ continue+ m = _MD_FENCE.match(ln)+ if m:+ fence = m.group(1)+ continue+ opened = ln.find("<!--")+ if opened != -1 and "-->" not in ln[opened + 4 :]:+ in_comment = True+ continue+ if _MD_HEADING.match(ln):+ headings.append(ln.strip())+ return headings+++def _rst_table_lines(lines: list[str]) -> set[int]:+ """Line indexes inside simple tables: a blank-free block with 3+ ``=`` borders."""+ inside: set[int] = set()+ i = 0+ while i < len(lines):+ if not lines[i].strip():+ i += 1+ continue+ j = i+ while j < len(lines) and lines[j].strip():+ j += 1+ borders = sum(1 for k in range(i, j) if set(lines[k].strip()) <= {"=", " "})+ if borders >= 3 and set(lines[i].strip()) <= {"=", " "}:+ inside.update(range(i, j))+ i = j+ return inside+++def _rst_headings(lines: list[str]) -> list[str]:+ """Section titles: an unindented line underlined by punctuation at least as long.++ Indented lines (literal and directive bodies) are never titles, so a+ ``# comment`` inside a ``code-block`` is not one either, and neither is a+ row of a simple table framed by ``=`` borders.+ """+ tables = _rst_table_lines(lines)+ headings: list[str] = []+ for i in range(len(lines) - 1):+ title, under = lines[i].rstrip(), lines[i + 1].rstrip()+ if (+ i not in tables+ and title+ and not title[0].isspace()+ and not _RST_ADORNMENT.fullmatch(title)+ and _RST_ADORNMENT.fullmatch(under)+ and len(under) >= len(title)+ ):+ headings.append(title)+ return headings+++def _outline_lines(text: str, file_path: str) -> tuple[str, list[str]]:+ """Return a document's headings, or the head lines of anything else.++ Returns the kind of excerpt chosen so the caller can label it truthfully.+ A heading-less document falls through to head lines rather than reporting+ an empty outline. Head lines skip comment banners unless that is all+ the file has.+ """+ lines = text.splitlines()+ lower = file_path.lower()+ if lower.endswith(_MARKDOWN_EXTS):+ headings = _markdown_headings(lines)+ elif lower.endswith(_RST_EXTS):+ headings = _rst_headings(lines)+ else:+ headings = []+ if headings:+ return "headings", headings+ head = [ln.rstrip() for ln in lines if ln.strip()]+ content = [ln for ln in head if not ln.lstrip().startswith(_COMMENT_PREFIXES)]+ return "head", content or head+++def _file_preview(repo_root: Any, file_path: str) -> dict[str, Any] | None:+ """Cheap, true facts about a file the symbol index has nothing to say about.++ Only counts and verbatim excerpts, nothing inferred. Returns None when the+ file cannot be read, so the caller keeps its existing behaviour rather than+ reporting an empty preview as if the file were empty.+ """+ text = read_repo_file_text(repo_root, file_path)+ if text is None:+ return None++ lines = text.splitlines()+ preview: dict[str, Any] = {"lines": len(lines), "chars": len(text)}+ if not text.strip():+ preview["note"] = "File is empty."+ return preview+ if len(text) > _PREVIEW_MAX_BYTES:+ preview["note"] = "File is too large to preview; Read it directly."+ return preview++ kind, excerpt = _outline_lines(text, file_path)+ if kind == "headings":+ preview["heading_count"] = len(excerpt)+ if excerpt:+ preview[kind] = [ln[:_PREVIEW_MAX_LINE_CHARS] for ln in excerpt[:_PREVIEW_MAX_LINES]]+ preview["note"] = (+ "No indexed symbols; counts and a short excerpt only. Read the file for its content."+ )+ return previewdiff --git a/packages/server/src/repowise/server/mcp_server/tool_context/resolution.py b/packages/server/src/repowise/server/mcp_server/tool_context/resolution.pynew file mode 100644index 000000000..95ef249f2--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_context/resolution.py@@ -0,0 +1,466 @@+"""The get_context resolution ladder: which kind of thing a target names.++Each resolver either answers (a ``ResolvedTarget`` to build a card from, or a+finished error/degrade payload) or returns None to fall through. They run in+``_RESOLVERS`` order and the first answer wins; ``_not_found`` answers last.+"""++from __future__ import annotations++import re+from collections.abc import Awaitable, Callable+from dataclasses import dataclass, field+from datetime import datetime+from pathlib import Path+from typing import Any++from sqlalchemy import or_, select+from sqlalchemy.ext.asyncio import AsyncSession++from repowise.core.persistence.models import (+ GitMetadata,+ GraphNode,+ Page,+ Repository,+ WikiSymbol,+)+from repowise.server.mcp_server._budget import OmissionCollector+from repowise.server.mcp_server._helpers import (+ LIKE_ESCAPE,+ escape_like,+ filter_path_list,+ is_excluded,+)+from repowise.server.mcp_server._references import symbol_identity+from repowise.server.mcp_server._symbol_lookup import (+ nearest_symbol_ids,+ resolve_symbol_rows,+ symbol_id_variants,+)+from repowise.server.mcp_server.tool_context.preview import _file_preview+++@dataclass(frozen=True)+class TargetQuery:+ """One get_context target and the call options a resolver may need."""++ session: AsyncSession+ repository: Repository+ target: str+ include: set[str] | None+ compact: bool = False+ exclude_spec: Any = None+ repo_root: Any = None+ collector: OmissionCollector | None = None+ as_of_ts: datetime | None = None++ @property+ def repo_id(self) -> str:+ return self.repository.id++ @property+ def clean_target(self) -> str:+ """The target with a directory's trailing slash dropped."""+ return self.target.rstrip("/")+++@dataclass+class ResolvedTarget:+ """What a target resolved to; the card is built from these fields."""++ target_type: str+ page: Page | None = None+ # The file whose git history, freshness and layer the card reads.+ file_path: str | None = None+ sym_matches: list[Any] = field(default_factory=list)+ # The resolved symbol's graph id. Graph queries key on it, never on the+ # caller's spelling, so ``Class.method`` and ``Class::method`` agree.+ symbol_node_id: str | None = None+ # Set only when a symbol target resolved through the call graph rather than+ # the symbol index (index-only mode); carries the fields the node has.+ graph_symbol: GraphNode | None = None+ live_file_meta: GitMetadata | None = None+ live_unindexed_file: bool = False+++Resolution = ResolvedTarget | dict[str, Any]+Resolver = Callable[[TargetQuery], Awaitable[Resolution | None]]+++async def _did_you_mean(+ session: AsyncSession,+ repo_id: str,+ target: str,+ file_path: str | None = None,+ exclude_spec: Any = None,+) -> dict[str, list[str]]:+ """``{"did_you_mean": [...]}``: the nearest symbol ids to a missed name, or ``{}``.++ The missed name follows the file head when ``file_path`` is given or the+ head is a path (``src/a.py::sned``), else it is the whole target+ (``Clinet.send``, ``httpx.Client::send``); a plain path has none. A path+ has a separator, as in ``resolve_symbol_rows``' path-less rung.+ """+ head, sep, tail = target.partition("::")+ path_head = any(c in head for c in "/\\")+ if file_path or (sep and path_head):+ query = tail+ elif path_head:+ return {}+ else:+ query = target+ ids = await nearest_symbol_ids(session, repo_id, query, file_path, exclude_spec)+ return {"did_you_mean": [symbol_identity(sid) for sid in ids]} if ids else {}+++def _size_exclusion_note(repo_root: Any, target: str) -> str | None:+ """Explain a missing file that ingestion dropped on size, else None.++ Computed live from the file on disk rather than read from the index,+ because a file excluded from ingestion leaves no row to read. Delegates the+ actual rule to ``size_verdict`` so this answer cannot drift from the code+ that produced the exclusion.+ """+ if repo_root is None:+ return None+ try:+ from repowise.core.ingestion.traverser import size_verdict++ root = Path(str(repo_root))+ abs_path = (root / target).resolve()+ # An index row is not a trust boundary; refuse anything outside the repo.+ abs_path.relative_to(root.resolve())+ size_bytes = abs_path.stat().st_size+ verdict = size_verdict(abs_path, size_bytes)+ except (OSError, ValueError):+ return None+ if verdict is None or not verdict.is_source:+ return None+ detail = {+ "minified": "it looks minified (machine-packed, not hand-written)",+ "unreadable": "it could not be read",+ }.get(verdict.reason, "it exceeds the maximum size for an indexed source file")+ return (+ f"'{target}' is not indexed: {detail} "+ f"({size_bytes // 1024:,} KB). It has no page and no symbols, and "+ "`repowise update` will not create them. Read the file directly."+ )+++async def _excluded(q: TargetQuery) -> Resolution | None:+ """Reject excluded file / ``path::Name`` targets outright (bare symbol names+ aren't path-matchable here and fall through to neighbor filtering)."""+ gate_path = q.target.split("::", 1)[0] if "::" in q.target else q.target+ if is_excluded(gate_path, q.exclude_spec):+ return {+ "target": q.target,+ "error": f"'{q.target}' is excluded by exclude_patterns configuration",+ }+ return None+++async def _file_page_by_id(q: TargetQuery) -> Resolution | None:+ """A file page, the most common target."""+ page = await q.session.get(Page, f"file_page:{q.target}")+ if page and page.repository_id == q.repo_id:+ return ResolvedTarget("file", page=page, file_path=q.target)+ return None+++async def _module_page_at(q: TargetQuery, target_path: str) -> Page | None:+ res = await q.session.execute(+ select(Page).where(+ Page.repository_id == q.repo_id,+ Page.page_type == "module_page",+ Page.target_path == target_path,+ )+ )+ return res.scalar_one_or_none()+++async def _module_page_partial(q: TargetQuery) -> Page | None:+ """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 rungs below."""+ clean_target = q.clean_target+ file_meta_res = await q.session.execute(+ select(GitMetadata.file_path).where(+ GitMetadata.repository_id == q.repo_id,+ GitMetadata.file_path == clean_target,+ )+ )+ if file_meta_res.scalar_one_or_none() is not None:+ return None+ esc = escape_like(clean_target)+ res = await q.session.execute(+ select(Page).where(+ Page.repository_id == q.repo_id,+ Page.page_type == "module_page",+ or_(+ Page.target_path == clean_target,+ Page.target_path.like(f"%/{esc}", escape=LIKE_ESCAPE),+ Page.target_path.like(f"{esc}/%", escape=LIKE_ESCAPE),+ Page.target_path.like(f"%/{esc}/%", escape=LIKE_ESCAPE),+ ),+ )+ )+ # Deterministic pick among several matches: shortest path, then+ # lexicographic.+ candidates = sorted(res.scalars().all(), key=lambda p: (len(p.target_path), p.target_path))+ return candidates[0] if candidates else None+++async def _module_page(q: TargetQuery) -> Resolution | None:+ """A module page: exact, then without a trailing slash, then partial."""+ page = await _module_page_at(q, q.target)+ if page is None and q.clean_target != q.target:+ page = await _module_page_at(q, q.clean_target)+ if page is None:+ page = await _module_page_partial(q)+ return ResolvedTarget("module", page=page) if page else None+++async def _symbol_rows(q: TargetQuery) -> Any:+ """Symbol rows for the target. A "{path}::{Name}" id goes through+ get_symbol's lookup so ids resolve the same in both tools; the name rungs+ can never match a path-qualified id."""+ if "::" in q.target:+ return await resolve_symbol_rows(q.session, q.repo_id, q.target)+ res = await q.session.execute(+ select(WikiSymbol).where(+ WikiSymbol.repository_id == q.repo_id,+ WikiSymbol.name == q.target,+ )+ )+ sym_matches = list(res.scalars().all())+ if not sym_matches:+ # "Client.send": a qualified name with no file.+ sym_matches = await resolve_symbol_rows(q.session, q.repo_id, q.target)+ if not sym_matches:+ res = await q.session.execute(+ select(WikiSymbol)+ .where(+ WikiSymbol.repository_id == q.repo_id,+ WikiSymbol.name.ilike(f"%{escape_like(q.target)}%", escape=LIKE_ESCAPE),+ )+ .limit(10)+ )+ sym_matches = list(res.scalars().all())+ return sym_matches+++async def _symbol(q: TargetQuery) -> Resolution | None:+ sym_matches = await _symbol_rows(q)+ if not sym_matches:+ return None+ return ResolvedTarget(+ "symbol",+ file_path=sym_matches[0].file_path,+ sym_matches=sym_matches,+ symbol_node_id=sym_matches[0].symbol_id,+ )+++async def _file_page_by_path(q: TargetQuery) -> Resolution | None:+ """A file page found by its target_path rather than its id."""+ res = await q.session.execute(+ select(Page).where(+ Page.repository_id == q.repo_id,+ Page.page_type == "file_page",+ Page.target_path == q.target,+ )+ )+ page = res.scalar_one_or_none()+ if page:+ return ResolvedTarget("file", page=page, file_path=q.target)+ return None+++async def _graph_node(q: TargetQuery) -> Resolution | None:+ """Index-only mode (no wiki pages): 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. Every separator form is tried, as the symbol rung does. Among several,+ the verbatim id wins, then a symbol node, then the id order, so the pick+ never depends on row order.+ """+ res = await q.session.execute(+ select(GraphNode).where(+ GraphNode.repository_id == q.repo_id,+ GraphNode.node_id.in_(symbol_id_variants(q.target)),+ )+ )+ gnode = min(+ res.scalars().all(),+ key=lambda g: (g.node_id != q.target, g.node_type != "symbol", g.node_id),+ default=None,+ )+ if gnode is None:+ return None+ if gnode.node_type == "symbol":+ return ResolvedTarget(+ "symbol",+ graph_symbol=gnode,+ file_path=gnode.file_path,+ symbol_node_id=gnode.node_id,+ )+ # No wiki page; the card sections guard for this.+ return ResolvedTarget("file", file_path=q.target)+++async def _git_metadata(q: TargetQuery) -> Resolution | None:+ """A file with no wiki page and no graph node, known from git_metadata."""+ res = await q.session.execute(+ select(GitMetadata).where(+ GitMetadata.repository_id == q.repo_id,+ GitMetadata.file_path == q.target,+ )+ )+ meta = res.scalar_one_or_none()+ if not meta:+ return None+ # 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(q.repo_root, q.target)+ if size_note:+ return {"target": q.target, "error": size_note, "exists_in_git": True}+ return ResolvedTarget("file", file_path=q.target, live_file_meta=meta)+++async def _live_file(q: TargetQuery) -> Resolution | None:+ """A live file never indexed into git_metadata is still a valid public+ path; resolve it from the checkout."""+ if _file_preview(q.repo_root, q.target) is not None:+ return ResolvedTarget("file", file_path=q.target, live_unindexed_file=True)+ return None+++async def _legacy_community_id(q: TargetQuery) -> Resolution | None:+ """Legacy "community-12" module ids; point them at the directory-path+ vocabulary."""+ if not re.fullmatch(r"community[-_]\d+", q.clean_target, re.IGNORECASE):+ return None+ res = await q.session.execute(+ select(Page.target_path)+ .where(+ Page.repository_id == q.repo_id,+ Page.page_type == "module_page",+ )+ .order_by(Page.target_path)+ .limit(10)+ )+ module_paths = filter_path_list([row[0] for row in res.all()], q.exclude_spec)+ return {+ "target": q.target,+ "error": (+ f"Target not found: '{q.target}'. Module pages are no longer "+ "keyed by community ordinal — pass the module's directory "+ "path instead (see suggestions)."+ ),+ "suggestions": module_paths,+ }+++async def _symbol_in_known_file(q: TargetQuery) -> Resolution | None:+ """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."""+ target = q.target+ if "::" not in target:+ return None+ file_part = target.split("::", 1)[0]+ if not file_part or file_part == target or is_excluded(file_part, q.exclude_spec):+ return None+ # Imported here: targets imports this module.+ from repowise.server.mcp_server.tool_context.targets import _resolve_one_target++ # file_part contains no "::", so this recursion is depth-1. The caller is+ # hunting for a name: ``did_you_mean`` picks the closest from every symbol+ # of the file, so the list keeps its cap.+ card = await _resolve_one_target(+ q.session,+ q.repository,+ file_part,+ q.include,+ q.compact,+ exclude_spec=q.exclude_spec,+ repo_root=q.repo_root,+ collector=q.collector,+ as_of_ts=q.as_of_ts,+ )+ # Only a file card is the degrade; a symbol card for the head ("Command"+ # of "Command::Nope") would claim the wrong symbol.+ if "error" in card or card.get("type") != "file":+ return None+ card["target"] = target+ card["resolved_to"] = file_part+ nearest = await _did_you_mean(q.session, q.repo_id, target, file_part)+ card.update(nearest)+ card["note"] = (+ f"No symbol matched {target.split('::', 1)[1]!r} in this file; "+ f"showing the card for {file_part!r} instead. "+ + (+ "Closest names are in did_you_mean."+ if nearest+ else "Pass include=['symbols'] for the full symbol list."+ )+ )+ return card+++async def _not_found(q: TargetQuery) -> dict[str, Any]:+ """Fuzzy path suggestions: files under a directory-like target, else by+ filename or partial path; plus the nearest symbol names."""+ target = q.target+ dir_prefix = q.clean_target.rstrip("/") + "/"+ res = await q.session.execute(+ select(GitMetadata.file_path)+ .where(+ GitMetadata.repository_id == q.repo_id,+ GitMetadata.file_path.like(f"{escape_like(dir_prefix)}%", escape=LIKE_ESCAPE),+ )+ .limit(5)+ )+ suggestions = [row[0] for row in res.all()]+ if not suggestions:+ tail = target.rsplit("/", 1)[-1]+ res = await q.session.execute(+ select(GitMetadata.file_path)+ .where(+ GitMetadata.repository_id == q.repo_id,+ GitMetadata.file_path.contains(tail),+ )+ .limit(5)+ )+ suggestions = [row[0] for row in res.all() if row[0] != target]+ suggestions = filter_path_list(suggestions, q.exclude_spec)+ miss: dict[str, Any] = {"target": target, "error": f"Target not found: '{target}'"}+ if suggestions:+ miss["suggestions"] = suggestions+ miss.update(await _did_you_mean(q.session, q.repo_id, target, exclude_spec=q.exclude_spec))+ return miss+++#: The ladder, in precedence order. The first four are the indexed kinds; the+#: rest are fallbacks for targets with no page and no symbol row.+_RESOLVERS: tuple[Resolver, ...] = (+ _excluded,+ _file_page_by_id,+ _module_page,+ _symbol,+ _file_page_by_path,+ _graph_node,+ _git_metadata,+ _live_file,+ _legacy_community_id,+ _symbol_in_known_file,+)+++async def resolve_target(q: TargetQuery) -> Resolution:+ """Run the ladder; the first resolver that answers wins."""+ for resolver in _RESOLVERS:+ found = await resolver(q)+ if found is not None:+ return found+ return await _not_found(q)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 35651f579..eaa6bf4fc 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@@ -1,7 +1,7 @@"""Single-target resolution for get_context.-``_resolve_one_target`` walks the file → module → symbol → fallback ladder for-one target and assembles its triage card (docs, triage signals, ownership,+``_resolve_one_target`` resolves one target through the ladder in+``resolution`` and assembles its triage card (docs, triage signals, ownership,last_change, decisions, freshness, KG layer/tour, and the opt-in enrichmentblocks delegated to ``enrichment``)."""@@ -10,9 +10,7 @@ from __future__ import annotationsimport contextlibimport json-import refrom datetime import UTC, datetime-from pathlib import Pathfrom typing import Anyfrom sqlalchemy import func, or_, select@@ -55,17 +53,11 @@ from repowise.server.mcp_server._helpers import (escape_like,filter_dicts_by_key,filter_path_list,- is_excluded,- read_repo_file_text,)from repowise.server.mcp_server._index_state import index_state_keyfrom repowise.server.mcp_server._meta import served_root, uncommitted_targetsfrom repowise.server.mcp_server._references import path_identity, symbol_identity-from repowise.server.mcp_server._symbol_lookup import (- nearest_symbol_ids,- resolve_symbol_rows,- symbol_id_variants,-)+from repowise.server.mcp_server._symbol_lookup import symbol_id_variantsfrom repowise.server.mcp_server.tool_context.enrichment import (_DOC_DRIFT_PATH,_MIN_CALL_CONFIDENCE,@@ -80,6 +72,22 @@ from repowise.server.mcp_server.tool_context.kg import (_find_layer_for_file,_find_tour_step_for_file,)+from repowise.server.mcp_server.tool_context.preview import ( # noqa: F401 (re-exported)+ _NO_SYMBOL_SUMMARY_SUFFIX,+ _file_preview,+ _markdown_headings,+ _outline_lines,+ _preview_summary,+ _rst_headings,+ _rst_table_lines,+)+from repowise.server.mcp_server.tool_context.resolution import ( # noqa: F401 (re-exported)+ ResolvedTarget,+ TargetQuery,+ _did_you_mean,+ _size_exclusion_note,+ resolve_target,+)from repowise.server.mcp_server.tool_risk.assessment import fix_annotation#: How many users of a symbol the card carries. The file target's@@ -113,32 +121,6 @@ def _kind_rank(kind: str | None) -> int:return 0 if kind in _TYPE_KINDS else 1 if kind in _CALLABLE_KINDS else 2-async def _did_you_mean(- session: AsyncSession,- repo_id: str,- target: str,- file_path: str | None = None,- exclude_spec: Any = None,-) -> dict[str, list[str]]:- """``{"did_you_mean": [...]}``: the nearest symbol ids to a missed name, or ``{}``.-- The missed name follows the file head when ``file_path`` is given or the- head is a path (``src/a.py::sned``), else it is the whole target- (``Clinet.send``, ``httpx.Client::send``); a plain path has none. A path- has a separator, as in ``resolve_symbol_rows``' path-less rung.- """- head, sep, tail = target.partition("::")- path_head = any(c in head for c in "/\\")- if file_path or (sep and path_head):- query = tail- elif path_head:- return {}- else:- query = target- ids = await nearest_symbol_ids(session, repo_id, query, file_path, exclude_spec)- return {"did_you_mean": [symbol_identity(sid) for sid in ids]} if ids else {}--async def _compact_symbol_rows(session: AsyncSession, repo_id: str, file_path: str, symbols: Any) -> list[dict[str, Any]]:@@ -201,202 +183,6 @@ def _synthesize_structural_summary(file_path: str, classes: list[str], functionsreturn f"{name}: " + "; ".join(parts) + "."-# 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"---def _preview_summary(file_path: str, preview: dict[str, Any]) -> str:- """One truthful line about a symbol-less file, built from its own counts."""- name = file_path.rsplit("/", 1)[-1]- lines = preview.get("lines", 0)- if not lines:- return f"{name}: empty file"- heading_count = preview.get("heading_count")- if heading_count:- return f"{name}: {lines}-line document, {heading_count} headings, no indexed symbols."- return f"{name}: {lines} lines, no indexed symbols."---# Bounds on the preview a symbol-less file (README, YAML, SQL) gets: counts-# plus a few verbatim lines, cheap enough to stay on by default.-_PREVIEW_MAX_LINES = 3-_PREVIEW_MAX_LINE_CHARS = 120-# Beyond this the file is big enough that a preview would misrepresent it; the-# counts and the "go Read it" note are the honest reply.-_PREVIEW_MAX_BYTES = 2_000_000--_MARKDOWN_EXTS = (".md", ".markdown", ".mdx")-_RST_EXTS = (".rst",)-_MD_HEADING = re.compile(r" {0,3}#{1,6}(\s|$)")-_MD_FENCE = re.compile(r" {0,3}(`{3,}|~{3,})")-_RST_ADORNMENT = re.compile(r"([!-/:-@\[-`{-~])\1+")-# Lines that open with a comment marker: licence banners and the like.-_COMMENT_PREFIXES = ("#", "//", "--", "/*", "*", "<!--")---def _markdown_headings(lines: list[str]) -> list[str]:- """ATX headings outside front matter, fenced code and HTML comments."""- headings: list[str] = []- start = 0- if lines and lines[0].strip() == "---":- close = next((i for i in range(1, len(lines)) if lines[i].strip() in ("---", "...")), None)- if close is not None:- start = close + 1- fence = ""- in_comment = False- for ln in lines[start:]:- if in_comment:- in_comment = "-->" not in ln- continue- if fence:- # Only a bare run of the opening character, at least as long, closes.- bare = ln.strip()- if bare and set(bare) == {fence[0]} and len(bare) >= len(fence):- fence = ""- continue- m = _MD_FENCE.match(ln)- if m:- fence = m.group(1)- continue- opened = ln.find("<!--")- if opened != -1 and "-->" not in ln[opened + 4 :]:- in_comment = True- continue- if _MD_HEADING.match(ln):- headings.append(ln.strip())- return headings---def _rst_table_lines(lines: list[str]) -> set[int]:- """Line indexes inside simple tables: a blank-free block with 3+ ``=`` borders."""- inside: set[int] = set()- i = 0- while i < len(lines):- if not lines[i].strip():- i += 1- continue- j = i- while j < len(lines) and lines[j].strip():- j += 1- borders = sum(1 for k in range(i, j) if set(lines[k].strip()) <= {"=", " "})- if borders >= 3 and set(lines[i].strip()) <= {"=", " "}:- inside.update(range(i, j))- i = j- return inside---def _rst_headings(lines: list[str]) -> list[str]:- """Section titles: an unindented line underlined by punctuation at least as long.-- Indented lines (literal and directive bodies) are never titles, so a- ``# comment`` inside a ``code-block`` is not one either, and neither is a- row of a simple table framed by ``=`` borders.- """- tables = _rst_table_lines(lines)- headings: list[str] = []- for i in range(len(lines) - 1):- title, under = lines[i].rstrip(), lines[i + 1].rstrip()- if (- i not in tables- and title- and not title[0].isspace()- and not _RST_ADORNMENT.fullmatch(title)- and _RST_ADORNMENT.fullmatch(under)- and len(under) >= len(title)- ):- headings.append(title)- return headings---def _outline_lines(text: str, file_path: str) -> tuple[str, list[str]]:- """Return a document's headings, or the head lines of anything else.-- Returns the kind of excerpt chosen so the caller can label it truthfully.- A heading-less document falls through to head lines rather than reporting- an empty outline. Head lines skip comment banners unless that is all- the file has.- """- lines = text.splitlines()- lower = file_path.lower()- if lower.endswith(_MARKDOWN_EXTS):- headings = _markdown_headings(lines)- elif lower.endswith(_RST_EXTS):- headings = _rst_headings(lines)- else:- headings = []- if headings:- return "headings", headings- head = [ln.rstrip() for ln in lines if ln.strip()]- content = [ln for ln in head if not ln.lstrip().startswith(_COMMENT_PREFIXES)]- return "head", content or head---def _file_preview(repo_root: Any, file_path: str) -> dict[str, Any] | None:- """Cheap, true facts about a file the symbol index has nothing to say about.-- Only counts and verbatim excerpts, nothing inferred. Returns None when the- file cannot be read, so the caller keeps its existing behaviour rather than- reporting an empty preview as if the file were empty.- """- text = read_repo_file_text(repo_root, file_path)- if text is None:- return None-- lines = text.splitlines()- preview: dict[str, Any] = {"lines": len(lines), "chars": len(text)}- if not text.strip():- preview["note"] = "File is empty."- return preview- if len(text) > _PREVIEW_MAX_BYTES:- preview["note"] = "File is too large to preview; Read it directly."- return preview-- kind, excerpt = _outline_lines(text, file_path)- if kind == "headings":- preview["heading_count"] = len(excerpt)- if excerpt:- preview[kind] = [ln[:_PREVIEW_MAX_LINE_CHARS] for ln in excerpt[:_PREVIEW_MAX_LINES]]- preview["note"] = (- "No indexed symbols; counts and a short excerpt only. Read the file for its content."- )- return preview---def _size_exclusion_note(repo_root: Any, target: str) -> str | None:- """Explain a missing file that ingestion dropped on size, else None.-- Computed live from the file on disk rather than read from the index,- because a file excluded from ingestion leaves no row to read. Delegates the- actual rule to ``size_verdict`` so this answer cannot drift from the code- that produced the exclusion.- """- if repo_root is None:- return None- try:- from repowise.core.ingestion.traverser import size_verdict-- root = Path(str(repo_root))- abs_path = (root / target).resolve()- # An index row is not a trust boundary; refuse anything outside the repo.- abs_path.relative_to(root.resolve())- size_bytes = abs_path.stat().st_size- verdict = size_verdict(abs_path, size_bytes)- except (OSError, ValueError):- return None- if verdict is None or not verdict.is_source:- return None- detail = {- "minified": "it looks minified (machine-packed, not hand-written)",- "unreadable": "it could not be read",- }.get(verdict.reason, "it exceeds the maximum size for an indexed source file")- return (- f"'{target}' is not indexed: {detail} "- f"({size_bytes // 1024:,} KB). It has no page and no symbols, and "- "`repowise update` will not create them. Read the file directly."- )--async def _days_since_last_change(session: AsyncSession,repo_id: str,@@ -443,289 +229,31 @@ async def _resolve_one_target() -> dict:"""Resolve a single target and return its full context."""repo_id = repository.id- result_data: dict[str, Any] = {}-- # Reject excluded file / ``path::Name`` targets outright (bare symbol names- # aren't path-matchable here and fall through to neighbor filtering).- gate_path = target.split("::", 1)[0] if "::" in target else target- if is_excluded(gate_path, exclude_spec):- return {- "target": target,- "error": f"'{target}' is excluded by exclude_patterns configuration",- }-- # --- Determine target type ---- # 1. Try file page (most common)- page_id = f"file_page:{target}"- page = await session.get(Page, page_id)- target_type = None- file_path_for_git: str | None = None- live_file_meta: GitMetadata | None = None- live_unindexed_file = False- # Set only when a symbol target resolved through the call graph rather than- # the symbol index (index-only mode); carries the fields the node has.- graph_symbol: GraphNode | None = None- # The resolved symbol's graph id. Graph queries key on it, never on the- # caller's spelling, so ``Class.method`` and ``Class::method`` agree.- symbol_node_id: str | None = None-- if page and page.repository_id == repo_id:- target_type = "file"- file_path_for_git = target- else:- # 1b. Normalise directory targets: strip trailing slash and try module- clean_target = target.rstrip("/")- # 2. Try module page (exact, then cleaned, then partial)- res = await session.execute(- select(Page).where(- Page.repository_id == repo_id,- Page.page_type == "module_page",- Page.target_path == target,- )- )- page = res.scalar_one_or_none()- if page is None and clean_target != target:- res = await session.execute(- select(Page).where(- Page.repository_id == repo_id,- Page.page_type == "module_page",- Page.target_path == clean_target,- )- )- page = res.scalar_one_or_none()- if page is None:- # 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,- GitMetadata.file_path == clean_target,- )- )- is_known_file = file_meta_res.scalar_one_or_none() is not None- if not is_known_file:- esc = escape_like(clean_target)- res = await session.execute(- select(Page).where(- Page.repository_id == repo_id,- Page.page_type == "module_page",- or_(- Page.target_path == clean_target,- Page.target_path.like(f"%/{esc}", escape=LIKE_ESCAPE),- Page.target_path.like(f"{esc}/%", escape=LIKE_ESCAPE),- Page.target_path.like(f"%/{esc}/%", escape=LIKE_ESCAPE),- ),- )- )- # Deterministic pick among several matches: shortest path, then- # lexicographic.- candidates = sorted(- res.scalars().all(), key=lambda p: (len(p.target_path), p.target_path)- )- if candidates:- page = candidates[0]- if page:- target_type = "module"- else:- # 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:- res = await session.execute(- select(WikiSymbol).where(- WikiSymbol.repository_id == repo_id,- WikiSymbol.name == target,- )- )- sym_matches = list(res.scalars().all())- if not sym_matches:- # "Client.send": a qualified name with no file.- sym_matches = await resolve_symbol_rows(session, repo_id, target)- if not sym_matches:- res = await session.execute(- select(WikiSymbol)- .where(- WikiSymbol.repository_id == repo_id,- WikiSymbol.name.ilike(f"%{escape_like(target)}%", escape=LIKE_ESCAPE),- )- .limit(10)- )- sym_matches = list(res.scalars().all())- if sym_matches:- target_type = "symbol"- file_path_for_git = sym_matches[0].file_path- symbol_node_id = sym_matches[0].symbol_id- else:- # 4. Try file page by target_path search- res = await session.execute(- select(Page).where(- Page.repository_id == repo_id,- Page.page_type == "file_page",- Page.target_path == target,- )- )- page = res.scalar_one_or_none()- if page:- target_type = "file"- file_path_for_git = target-- if target_type is None:- # 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. Every separator form is tried, as the- # symbol rung does. Among several, the verbatim id wins, then a symbol- # node, then the id order, so the pick never depends on row order.- res = await session.execute(- select(GraphNode).where(- GraphNode.repository_id == repo_id,- GraphNode.node_id.in_(symbol_id_variants(target)),- )- )- gnode = min(- res.scalars().all(),- key=lambda g: (g.node_id != target, g.node_type != "symbol", g.node_id),- default=None,+ resolved = await resolve_target(+ TargetQuery(+ session,+ repository,+ target,+ include,+ compact,+ exclude_spec=exclude_spec,+ repo_root=repo_root,+ collector=collector,+ as_of_ts=as_of_ts,)- if gnode is not None and gnode.node_type == "symbol":- target_type = "symbol"- graph_symbol = gnode- file_path_for_git = gnode.file_path- symbol_node_id = gnode.node_id- page = None- elif gnode is not None:- target_type = "file"- file_path_for_git = target- page = None # no wiki page; subsequent blocks must guard for this-- # Fallback 2: check git_metadata — file may exist but have no wiki page AND no graph node- if target_type is None:- res = await session.execute(- select(GitMetadata).where(- GitMetadata.repository_id == repo_id,- GitMetadata.file_path == target,- )- )- meta = res.scalar_one_or_none()- if meta:- # 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 {- "target": target,- "error": size_note,- "exists_in_git": True,- }- target_type = "file"- file_path_for_git = target- live_file_meta = meta- page = None-- # 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 = target- page = None- live_unindexed_file = True-- # 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)- .where(- Page.repository_id == repo_id,- Page.page_type == "module_page",- )- .order_by(Page.target_path)- .limit(10)- )- module_paths = filter_path_list([row[0] for row in res.all()], exclude_spec)- return {- "target": target,- "error": (- f"Target not found: '{target}'. Module pages are no longer "- "keyed by community ordinal — pass the module's directory "- "path instead (see suggestions)."- ),- "suggestions": module_paths,- }-- # 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):- # file_part contains no "::", so this recursion is depth-1. The- # caller is hunting for a name: ``did_you_mean`` picks the- # closest from every symbol of the file, so the list keeps its cap.- card = await _resolve_one_target(- session,- repository,- file_part,- include,- compact,- exclude_spec=exclude_spec,- repo_root=repo_root,- collector=collector,- as_of_ts=as_of_ts,- )- # Only a file card is the degrade; a symbol card for the head- # ("Command" of "Command::Nope") would claim the wrong symbol.- if "error" not in card and card.get("type") == "file":- card["target"] = target- card["resolved_to"] = file_part- nearest = await _did_you_mean(session, repo_id, target, file_part)- card.update(nearest)- card["note"] = (- f"No symbol matched {target.split('::', 1)[1]!r} in this file; "- f"showing the card for {file_part!r} instead. "- + (- "Closest names are in did_you_mean."- if nearest- else "Pass include=['symbols'] for the full symbol list."- )- )- return card-- # Fallback 3: fuzzy path suggestions — match by filename or partial path.- # Only runs if the prior fallbacks didn't resolve the target.- if target_type is None:- # For directory-like targets, suggest files within that directory- dir_prefix = clean_target.rstrip("/") + "/"- res = await session.execute(- select(GitMetadata.file_path)- .where(- GitMetadata.repository_id == repo_id,- GitMetadata.file_path.like(f"{escape_like(dir_prefix)}%", escape=LIKE_ESCAPE),- )- .limit(5)- )- suggestions = [row[0] for row in res.all()]- if not suggestions:- # Fall back to filename / partial path match- tail = target.rsplit("/", 1)[-1]- res = await session.execute(- select(GitMetadata.file_path)- .where(- GitMetadata.repository_id == repo_id,- GitMetadata.file_path.contains(tail),- )- .limit(5)- )- suggestions = [row[0] for row in res.all() if row[0] != target]- suggestions = filter_path_list(suggestions, exclude_spec)- miss: dict[str, Any] = {"target": target, "error": f"Target not found: '{target}'"}- if suggestions:- miss["suggestions"] = suggestions- miss.update(await _did_you_mean(session, repo_id, target, exclude_spec=exclude_spec))- return miss+ )+ if isinstance(resolved, dict):+ return resolved+ target_type = resolved.target_type+ page = resolved.page+ file_path_for_git = resolved.file_path+ live_file_meta = resolved.live_file_meta+ live_unindexed_file = resolved.live_unindexed_file+ graph_symbol = resolved.graph_symbol+ symbol_node_id = resolved.symbol_node_id+ sym_matches = resolved.sym_matches+ result_data: dict[str, Any] = {}result_data["target"] = targetresult_data["type"] = target_typeif target_type == "file" and file_path_for_git:@@ -961,7 +489,7 @@ async def _resolve_one_target(# In index-only mode the symbol may exist as a graph node with no# WikiSymbol row, so the node carries the fields it has and the# rest are simply absent rather than faked.- sym = sym_matches[0] if sym_matches else graph_symbol # type: ignore[possibly-undefined]+ sym = sym_matches[0] if sym_matches else graph_symboldocs["name"] = sym.namedocs["kind"] = sym.kinddocs["file_path"] = sym.file_path@@ -1058,7 +586,7 @@ async def _resolve_one_target(cache_key=index_state_key(repository),)# Candidates- if len(sym_matches) > 1: # type: ignore[possibly-undefined]+ if len(sym_matches) > 1:docs["candidates"] = filter_dicts_by_key([{@@ -1067,7 +595,7 @@ async def _resolve_one_target("file_path": m.file_path,"symbol_id": symbol_identity(m.symbol_id),}- for m in sym_matches[1:5] # type: ignore[possibly-undefined]+ for m in sym_matches[1:5]],"file_path",exclude_spec,