Skip to content

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

refactor(context): build the get_context card from a table of sections (#3997)

Raghav Chamadiyafe398dc0d500
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.py
index eaa6bf4fc..fc8f1c9a9 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
@@ -10,6 +10,8 @@ from __future__ import annotations
import contextlib
import json
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
from datetime import UTC, datetime
from typing import Any
@@ -215,6 +217,59 @@ def _as_utc(moment: datetime) -> datetime:
return moment if moment.tzinfo else moment.replace(tzinfo=UTC)
+@dataclass
+class CardState:
+ """One target's card while its sections write into ``data``."""
+
+ query: TargetQuery
+ resolved: ResolvedTarget
+ data: dict[str, Any] = field(default_factory=dict)
+
+ @property
+ def session(self) -> AsyncSession:
+ return self.query.session
+
+ @property
+ def repo_id(self) -> str:
+ return self.query.repo_id
+
+ @property
+ def target(self) -> str:
+ return self.query.target
+
+ @property
+ def include(self) -> set[str] | None:
+ return self.query.include
+
+ @property
+ def page(self) -> Page | None:
+ return self.resolved.page
+
+ def wants(self, name: str) -> bool:
+ """An opt-in block the caller named."""
+ return bool(self.include and name in self.include)
+
+ def default_on(self, name: str) -> bool:
+ """A default block: on with no ``include``, else only when named."""
+ return self.include is None or name in self.include
+
+ @property
+ def git_path(self) -> str | None:
+ """The path git rows are keyed on: the module's directory for a module."""
+ if self.resolved.target_type == "module" and self.page:
+ return self.page.target_path
+ return self.resolved.file_path
+
+ @property
+ def skeleton_plus(self) -> bool:
+ return self.wants("skeleton+")
+
+ @property
+ def want_skeleton(self) -> bool:
+ # Asking for both skeleton and skeleton+ renders one block, the plus view.
+ return self.skeleton_plus or self.wants("skeleton")
+
+
async def _resolve_one_target(
session: AsyncSession,
repository: Repository,
@@ -228,755 +283,873 @@ async def _resolve_one_target(
as_of_ts: datetime | None = None,
) -> dict:
"""Resolve a single target and return its full context."""
- repo_id = repository.id
- 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,
- )
+ query = TargetQuery(
+ session,
+ repository,
+ target,
+ include,
+ compact,
+ exclude_spec=exclude_spec,
+ repo_root=repo_root,
+ collector=collector,
+ as_of_ts=as_of_ts,
)
+ resolved = await resolve_target(query)
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"] = target
- result_data["type"] = target_type
- if target_type == "file" and file_path_for_git:
- result_data["path"] = path_identity(file_path_for_git)
- if live_file_meta is not None:
- result_data["index_status"] = "live_file_without_wiki_page"
- result_data["verification_basis"] = "indexed_plus_live"
- result_data["exists_in_git"] = True
- result_data["last_commit_at"] = (
- live_file_meta.last_commit_at.isoformat()
- if live_file_meta.last_commit_at
- else None
+ card = CardState(query, resolved)
+ _identity_section(card)
+ if _tombstone_section(card):
+ return card.data
+ for section in _CARD_SECTIONS:
+ await section(card)
+ return card.data
+
+
+def _identity_section(card: CardState) -> None:
+ data, resolved = card.data, card.resolved
+ data["target"] = card.target
+ data["type"] = resolved.target_type
+ if resolved.target_type == "file" and resolved.file_path:
+ data["path"] = path_identity(resolved.file_path)
+ meta = resolved.live_file_meta
+ if meta is not None:
+ data["index_status"] = "live_file_without_wiki_page"
+ data["verification_basis"] = "indexed_plus_live"
+ data["exists_in_git"] = True
+ data["last_commit_at"] = meta.last_commit_at.isoformat() if meta.last_commit_at else None
+ data["primary_owner"] = meta.primary_owner_name
+ data["is_hotspot"] = meta.is_hotspot
+ elif resolved.live_unindexed_file:
+ data["index_status"] = "live_file_without_index_record"
+ data["verification_basis"] = "live"
+
+
+def _tombstone_section(card: CardState) -> bool:
+ """The file was deleted or renamed since indexing: write the redirect
+ rather than a misleading card, and say the card ends here."""
+ page = card.page
+ if page is None or getattr(page, "freshness_status", "") != "tombstone":
+ return False
+ try:
+ successors = json.loads(page.metadata_json or "{}").get("successor_paths") or []
+ except (ValueError, TypeError):
+ successors = []
+ card.data["error"] = (
+ f"'{card.target}' was deleted or renamed after indexing — this page is a tombstone."
+ )
+ if successors:
+ card.data["successor_paths"] = successors
+ card.data["hint"] = f"Content moved; call get_context on {successors[0]!r} instead."
+ return True
+
+
+async def _parent_page_section(card: CardState) -> None:
+ """Position in the concept tree: a file up to its concept page, a concept
+ page up to its layer."""
+ page = card.page
+ if page is None or not page.parent_page_id:
+ return
+ parent = await card.session.get(Page, page.parent_page_id)
+ if (
+ parent is not None
+ and parent.repository_id == card.repo_id
+ and getattr(parent, "freshness_status", "") != "tombstone"
+ ):
+ # Skip a tombstoned parent, for the reason _tombstone_section redirects.
+ card.data["parent_page"] = {
+ "title": parent.title,
+ "target_path": parent.target_path,
+ "section": parent.section_number,
+ }
+
+
+async def _docs_section(card: CardState) -> None:
+ # "full_doc" implies "docs".
+ if not (card.default_on("docs") or card.wants("full_doc")):
+ return
+ docs: dict[str, Any] = {}
+ await _DOCS_BY_TYPE[card.resolved.target_type](card, docs)
+ card.data["docs"] = docs
+
+
+def _file_page_docs(card: CardState, docs: dict[str, Any]) -> None:
+ page = card.page
+ if page is None:
+ return
+ docs["title"] = page.title
+ docs["summary"] = page.summary or ""
+ if card.wants("full_doc"):
+ docs["content_md"] = page.content
+ if page.digest:
+ docs["digest_md"] = page.digest
+ if page.human_notes:
+ docs["human_notes"] = page.human_notes
+
+
+async def _file_docs(card: CardState, docs: dict[str, Any]) -> None:
+ target = card.target
+ _file_page_docs(card, docs)
+ res = await card.session.execute(
+ select(WikiSymbol)
+ .where(
+ WikiSymbol.repository_id == card.repo_id,
+ WikiSymbol.file_path == target,
)
- result_data["primary_owner"] = live_file_meta.primary_owner_name
- result_data["is_hotspot"] = live_file_meta.is_hotspot
- elif live_unindexed_file:
- result_data["index_status"] = "live_file_without_index_record"
- result_data["verification_basis"] = "live"
-
- # 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
-
- try:
- successors = _json_ts.loads(page.metadata_json or "{}").get("successor_paths") or []
- except (ValueError, TypeError):
- successors = []
- result_data["error"] = (
- f"'{target}' was deleted or renamed after indexing — this page is a tombstone."
+ .order_by(WikiSymbol.start_line, WikiSymbol.symbol_id)
+ )
+ symbols = res.scalars().all()
+ classes = [s.name for s in symbols if s.kind == "class"]
+ functions = [s.name for s in symbols if s.kind in ("function", "method")]
+ # The skeleton already renders every signature with line bounds, so a
+ # symbol list beside it would only double the response.
+ full = not (card.want_skeleton or card.query.compact)
+ if card.query.compact and not card.want_skeleton:
+ await _compact_file_symbols(card, docs, symbols)
+ elif full:
+ _full_file_symbols(docs, symbols, classes, functions)
+ if not docs.get("summary"):
+ docs["summary"] = _synthesize_structural_summary(target, classes, functions)
+ if full:
+ await _file_importers_and_community(card, docs)
+ # 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:
+ _attach_file_preview(card, docs)
+
+
+async def _compact_file_symbols(card: CardState, docs: dict[str, Any], symbols: Any) -> None:
+ docs["symbols"] = await _compact_symbol_rows(card.session, card.repo_id, card.target, symbols)
+ if not card.wants("symbols") and len(symbols) > _SYMBOL_CAP:
+ docs["symbols"] = docs["symbols"][:_SYMBOL_CAP]
+ # The budgeter's own total, so a later trim cannot report 15.
+ docs["symbols_total"] = len(symbols)
+ docs["symbols_truncated"] = {
+ "shown": _SYMBOL_CAP,
+ "total": len(symbols),
+ "hint": "Pass include=['symbols'] for the full list.",
+ }
+
+
+def _full_file_symbols(
+ docs: dict[str, Any], symbols: Any, classes: list[str], functions: list[str]
+) -> None:
+ docs["symbols"] = [
+ {
+ "name": s.name,
+ "kind": s.kind,
+ "signature": clean_signature(s.signature),
+ "start_line": s.start_line,
+ "end_line": s.end_line,
+ "symbol_id": symbol_identity(s.symbol_id),
+ "docstring": (s.docstring or "")[:400],
+ }
+ for s in symbols
+ ]
+ # Structure summary block — quick scan of what's in the file
+ total_loc = max((s.end_line for s in symbols), default=0)
+ avg_complexity = sum(s.complexity_estimate for s in symbols) / len(symbols) if symbols else 0
+ docs["structure"] = {
+ "classes": classes,
+ "functions": functions,
+ "symbol_count": len(symbols),
+ "total_loc": total_loc,
+ "avg_complexity": round(avg_complexity, 2),
+ }
+
+
+async def _file_importers_and_community(card: CardState, docs: dict[str, Any]) -> None:
+ """``imported_by`` and the file's community, on the full (non-compact) card."""
+ # Non-reference edges (e.g. co-change) are excluded, or a file that merely
+ # changes alongside this one reads as an importer.
+ res = await card.session.execute(
+ select(GraphEdge).where(
+ GraphEdge.repository_id == card.repo_id,
+ GraphEdge.target_node_id == card.target,
+ GraphEdge.edge_type.notin_(NON_DEPENDENCY_EDGE_TYPES),
)
- if successors:
- result_data["successor_paths"] = successors
- result_data["hint"] = f"Content moved; call get_context on {successors[0]!r} instead."
- return result_data
-
- # --- Parent page (position in the concept tree) -----------------------
- # 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 (
- parent is not None
- and parent.repository_id == repo_id
- and getattr(parent, "freshness_status", "") != "tombstone"
- ):
- # Skip a tombstoned parent, for the reason of the redirect above.
- result_data["parent_page"] = {
- "title": parent.title,
- "target_path": parent.target_path,
- "section": parent.section_number,
+ )
+ importers = res.scalars().all()
+ docs["imported_by"] = filter_path_list(
+ [e.source_node_id for e in importers], card.query.exclude_spec
+ )
+ # Community info (compact=False only, ~80 bytes)
+ res = await card.session.execute(
+ select(GraphNode).where(
+ GraphNode.repository_id == card.repo_id,
+ GraphNode.node_id == card.target,
+ )
+ )
+ gn = res.scalar_one_or_none()
+ if gn and has_community(gn.community_id):
+ _cmeta: dict[str, Any] = {}
+ with contextlib.suppress(json.JSONDecodeError, TypeError):
+ _cmeta = json.loads(gn.community_meta_json or "{}")
+ docs["community"] = {
+ "id": gn.community_id,
+ "label": _cmeta.get("label", ""),
+ }
+
+
+def _attach_file_preview(card: CardState, docs: dict[str, Any]) -> None:
+ preview = _file_preview(card.query.repo_root, card.target)
+ if preview is not None:
+ docs["file_preview"] = preview
+ # Replace the stub summary with the preview's own counts.
+ if docs.get("summary", "").endswith(_NO_SYMBOL_SUMMARY_SUFFIX):
+ docs["summary"] = _preview_summary(card.target, preview)
+
+
+async def _module_docs(card: CardState, docs: dict[str, Any]) -> None:
+ page = card.page
+ exclude_spec = card.query.exclude_spec
+ docs["title"] = page.title
+ docs["summary"] = page.summary or ""
+ if page.section_number:
+ docs["section"] = page.section_number
+ if card.wants("full_doc"):
+ docs["content_md"] = page.content
+ # Questions, identifiers, public API and git signals: kept off the
+ # reader's page body, served to agents beside it.
+ if page.digest:
+ docs["digest_md"] = page.digest
+ # Non-file children only; file children are in "files" below.
+ res = await card.session.execute(
+ select(Page)
+ .where(
+ Page.repository_id == card.repo_id,
+ Page.parent_page_id == page.id,
+ Page.page_type != "file_page",
+ )
+ .order_by(Page.display_order, Page.target_path)
+ )
+ child_pages = res.scalars().all()
+ if child_pages:
+ docs["children"] = filter_dicts_by_key(
+ [
+ {
+ "title": ch.title,
+ "target_path": ch.target_path,
+ "page_type": ch.page_type,
+ "section": ch.section_number,
+ }
+ for ch in child_pages
+ ],
+ "target_path",
+ exclude_spec,
+ )
+ # Child file pages
+ res = await card.session.execute(
+ select(Page).where(
+ Page.repository_id == card.repo_id,
+ Page.page_type == "file_page",
+ Page.target_path.like(f"{escape_like(page.target_path)}/%", escape=LIKE_ESCAPE),
+ )
+ )
+ file_pages = res.scalars().all()
+ docs["files"] = filter_dicts_by_key(
+ [
+ {
+ "path": f.target_path,
+ # The title ("File: <path>") repeats the path.
+ "description": (f.summary or "").strip()[:160],
+ "confidence_score": f.confidence,
}
+ for f in file_pages
+ ],
+ "path",
+ exclude_spec,
+ )
- # Asking for both skeleton and skeleton+ renders one block, the plus view.
- skeleton_plus = bool(include and "skeleton+" in include)
- want_skeleton = skeleton_plus or bool(include and "skeleton" in include)
- want_all_symbols = bool(include and "symbols" in include)
-
- # --- Docs ---
- # "full_doc" implies "docs" — entering the docs block whenever either is requested.
- if include is None or "docs" in include or "full_doc" in include:
- want_full_doc = bool(include and "full_doc" in include)
- docs: dict[str, Any] = {}
- if target_type == "file":
- if page is not None:
- docs["title"] = page.title
- docs["summary"] = page.summary or ""
- if want_full_doc:
- docs["content_md"] = page.content
- if page.digest:
- docs["digest_md"] = page.digest
- if page.human_notes:
- docs["human_notes"] = page.human_notes
- # Symbols in this file
- res = await session.execute(
- select(WikiSymbol)
- .where(
- WikiSymbol.repository_id == repo_id,
- WikiSymbol.file_path == target,
- )
- .order_by(WikiSymbol.start_line, WikiSymbol.symbol_id)
- )
- symbols = res.scalars().all()
- 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:
- # 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:
- docs["symbols"] = await _compact_symbol_rows(
- session, repo_id, target, symbols
- )
- if not want_all_symbols and len(symbols) > _SYMBOL_CAP:
- docs["symbols"] = docs["symbols"][:_SYMBOL_CAP]
- # The budgeter's own total, so a later trim cannot report 15.
- docs["symbols_total"] = len(symbols)
- docs["symbols_truncated"] = {
- "shown": _SYMBOL_CAP,
- "total": len(symbols),
- "hint": "Pass include=['symbols'] for the full list.",
- }
- if not docs.get("summary"):
- docs["summary"] = _synthesize_structural_summary(target, classes, functions)
- else:
- docs["symbols"] = [
- {
- "name": s.name,
- "kind": s.kind,
- "signature": clean_signature(s.signature),
- "start_line": s.start_line,
- "end_line": s.end_line,
- "symbol_id": symbol_identity(s.symbol_id),
- "docstring": (s.docstring or "")[:400],
- }
- for s in symbols
- ]
- # Structure summary block — quick scan of what's in the file
- total_loc = max((s.end_line for s in symbols), default=0)
- avg_complexity = (
- sum(s.complexity_estimate for s in symbols) / len(symbols) if symbols else 0
- )
- docs["structure"] = {
- "classes": classes,
- "functions": functions,
- "symbol_count": len(symbols),
- "total_loc": total_loc,
- "avg_complexity": round(avg_complexity, 2),
+
+async def _symbol_docs(card: CardState, docs: dict[str, Any]) -> None:
+ # 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_matches = card.resolved.sym_matches
+ sym = sym_matches[0] if sym_matches else card.resolved.graph_symbol
+ docs["name"] = sym.name
+ docs["kind"] = sym.kind
+ docs["file_path"] = sym.file_path
+ for attr, key in (
+ ("qualified_name", "qualified_name"),
+ ("signature", "signature"),
+ ("docstring", "docstring"),
+ ):
+ value = getattr(sym, attr, None)
+ if value:
+ docs[key] = clean_signature(value) if attr == "signature" else value
+ # File page summary (full content gated behind include=["full_doc"])
+ sym_page = await card.session.get(Page, f"file_page:{sym.file_path}")
+ if sym_page is not None:
+ docs["file_summary"] = sym_page.summary or ""
+ if card.wants("full_doc"):
+ docs["documentation"] = sym_page.content
+ await _symbol_used_by(card, sym, docs)
+ # Candidates
+ if len(sym_matches) > 1:
+ docs["candidates"] = filter_dicts_by_key(
+ [
+ {
+ "name": m.name,
+ "kind": m.kind,
+ "file_path": m.file_path,
+ "symbol_id": symbol_identity(m.symbol_id),
}
- if not docs.get("summary"):
- docs["summary"] = _synthesize_structural_summary(target, classes, functions)
- # 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,
- GraphEdge.target_node_id == target,
- GraphEdge.edge_type.notin_(NON_DEPENDENCY_EDGE_TYPES),
- )
- )
- importers = res.scalars().all()
- docs["imported_by"] = filter_path_list(
- [e.source_node_id for e in importers], exclude_spec
- )
+ for m in sym_matches[1:5]
+ ],
+ "file_path",
+ card.query.exclude_spec,
+ )
- # Community info (compact=False only, ~80 bytes)
- res = await session.execute(
- select(GraphNode).where(
- GraphNode.repository_id == repo_id,
- GraphNode.node_id == target,
- )
- )
- gn = res.scalar_one_or_none()
- if gn and has_community(gn.community_id):
- _cmeta: dict[str, Any] = {}
- with contextlib.suppress(json.JSONDecodeError, TypeError):
- _cmeta = json.loads(gn.community_meta_json or "{}")
- docs["community"] = {
- "id": gn.community_id,
- "label": _cmeta.get("label", ""),
- }
-
- # 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
- # 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)
-
- elif target_type == "module":
- docs["title"] = page.title
- docs["summary"] = page.summary or ""
- if page.section_number:
- docs["section"] = page.section_number
- if want_full_doc:
- docs["content_md"] = page.content
- # Questions, identifiers, public API and git signals: kept off
- # the reader's page body, served to agents beside it.
- if page.digest:
- docs["digest_md"] = page.digest
- # Non-file children only; file children are in "files" below.
- res = await session.execute(
- select(Page)
- .where(
- Page.repository_id == repo_id,
- Page.parent_page_id == page.id,
- Page.page_type != "file_page",
- )
- .order_by(Page.display_order, Page.target_path)
- )
- child_pages = res.scalars().all()
- if child_pages:
- docs["children"] = filter_dicts_by_key(
- [
- {
- "title": ch.title,
- "target_path": ch.target_path,
- "page_type": ch.page_type,
- "section": ch.section_number,
- }
- for ch in child_pages
- ],
- "target_path",
- exclude_spec,
- )
- # Child file pages
- res = await session.execute(
- select(Page).where(
- Page.repository_id == repo_id,
- Page.page_type == "file_page",
- Page.target_path.like(f"{escape_like(page.target_path)}/%", escape=LIKE_ESCAPE),
- )
- )
- file_pages = res.scalars().all()
- docs["files"] = filter_dicts_by_key(
- [
- {
- "path": f.target_path,
- # The title ("File: <path>") repeats the path.
- "description": (f.summary or "").strip()[:160],
- "confidence_score": f.confidence,
- }
- for f in file_pages
- ],
- "path",
- exclude_spec,
- )
- elif target_type == "symbol":
- # 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
- docs["name"] = sym.name
- docs["kind"] = sym.kind
- docs["file_path"] = sym.file_path
- for attr, key in (
- ("qualified_name", "qualified_name"),
- ("signature", "signature"),
- ("docstring", "docstring"),
- ):
- value = getattr(sym, attr, None)
- if value:
- docs[key] = clean_signature(value) if attr == "signature" else value
- # File page summary (full content gated behind include=["full_doc"])
- sym_page_id = f"file_page:{sym.file_path}"
- sym_page = await session.get(Page, sym_page_id)
- if sym_page is not None:
- docs["file_summary"] = sym_page.summary or ""
- if want_full_doc:
- docs["documentation"] = sym_page.content
- # 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, GraphEdge.confidence)
- .outerjoin(
- GraphNode,
- (GraphNode.repository_id == GraphEdge.repository_id)
- & (GraphNode.node_id == GraphEdge.source_node_id),
- )
- .where(
- GraphEdge.repository_id == repo_id,
- GraphEdge.target_node_id == sym_node_id,
- GraphEdge.edge_type.in_(SYMBOL_USE_EDGE_TYPES),
- )
- )
- # An id the graph no longer holds still names its file, so fall
- # back to the path half rather than dropping a real user.
- user_files: set[str] = set()
- # A same-file caller is a real use, but naming the file already
- # being read spends a capped row; ``callers`` has it at symbol grain.
- # Counted first, by the confidence floor include=["callers"] serves
- # (a recursive call is not a user), so an empty list can say so.
- same_file_users: set[str] = set()
- for source_node_id, file_path, confidence in res.all():
- path = file_path or source_node_id.split("::", 1)[0]
- user_files.add(path)
- if (
- path == sym.file_path
- and source_node_id != sym_node_id
- and (confidence or 0) >= _MIN_CALL_CONFIDENCE
- ):
- same_file_users.add(source_node_id)
- user_files.discard(sym.file_path)
- # Before exclusion: an excluded user elsewhere is still a user.
- other_file_users = bool(user_files)
- # Looked up by the folded path, not joined above: a source whose
- # symbol node is missing has no file to join through and would rank
- # 0.0. Chunked because this binds one parameter per using file.
- best_rank: dict[str, float] = {p: 0.0 for p in user_files}
- ordered = sorted(user_files)
- for start in range(0, len(ordered), _RANK_LOOKUP_CHUNK):
- rank_rows = await session.execute(
- select(GraphNode.node_id, GraphNode.pagerank).where(
- GraphNode.repository_id == repo_id,
- GraphNode.node_id.in_(ordered[start : start + _RANK_LOOKUP_CHUNK]),
- )
- )
- for node_id, pagerank in rank_rows.all():
- best_rank[node_id] = float(pagerank or 0.0)
- used_by = filter_path_list(
- sorted(best_rank, key=lambda p: (-best_rank[p], p)), exclude_spec
- )
- cap_collection(
- docs,
- "used_by",
- used_by,
- _MAX_USED_BY,
- collector,
- label=f"{target} :: docs.used_by beyond cap={_MAX_USED_BY}",
- )
- # No users found says nothing on its own until the reader knows how
- # much of this language's call graph the resolver actually bound.
- # Same-file users make the zero a fact about other files instead.
- if not docs.get("used_by") and same_file_users and not other_file_users:
- docs["used_by_basis"] = same_file_basis(len(same_file_users))
- elif not docs.get("used_by"):
- docs["used_by_basis"] = await call_resolution_basis(
- session,
- repo_id,
- getattr(sym, "language", None),
- cache_key=index_state_key(repository),
- )
- # Candidates
- if len(sym_matches) > 1:
- docs["candidates"] = filter_dicts_by_key(
- [
- {
- "name": m.name,
- "kind": m.kind,
- "file_path": m.file_path,
- "symbol_id": symbol_identity(m.symbol_id),
- }
- for m in sym_matches[1:5]
- ],
- "file_path",
- exclude_spec,
- )
+async def _symbol_user_files(
+ card: CardState, sym: Any, sym_node_id: Any
+) -> tuple[set[str], set[str]]:
+ """Files that use the symbol, and its same-file callers.
- result_data["docs"] = docs
-
- # --- Triage signals (always on) ---------------------------------------
- # 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_git
- if target_type == "module" and page:
- triage_path = page.target_path
- if triage_path:
- # Same single row, four columns instead of one: no extra round trip.
- triage_meta_res = await session.execute(
- select(
- GitMetadata.is_hotspot,
- GitMetadata.prior_defect_count,
- GitMetadata.bug_magnet,
- GitMetadata.last_fix_at,
- ).where(
- GitMetadata.repository_id == repo_id,
- GitMetadata.file_path == triage_path,
- )
+ Keyed on the symbol's 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``.
+ """
+ res = await card.session.execute(
+ select(GraphEdge.source_node_id, GraphNode.file_path, GraphEdge.confidence)
+ .outerjoin(
+ GraphNode,
+ (GraphNode.repository_id == GraphEdge.repository_id)
+ & (GraphNode.node_id == GraphEdge.source_node_id),
)
- triage_meta = triage_meta_res.one_or_none()
- result_data["hotspot"] = bool(triage_meta.is_hotspot) if triage_meta is not None else False
- if triage_meta is not None:
- # Row exposes the selected columns as attributes, which is exactly
- # the shape fix_annotation reads off a full ORM row.
- fixes = fix_annotation(triage_meta, now=as_of_ts)
- if fixes is not None:
- result_data["fix_history"] = fixes
-
- # 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()
- for lookup_node in dict.fromkeys(
- [triage_path, target] if triage_path != target else [triage_path]
- ):
- if not lookup_node:
- continue
- for dr in await get_governing_decisions(session, repo_id, lookup_node):
- if dr.id not in seen_ids:
- seen_ids.add(dr.id)
- governing.append(dr)
- if governing:
- governing_sorted = sorted(governing, key=lambda d: -(d.confidence or 0.0))
- result_data["decision_records"] = [dr.title for dr in governing_sorted[:3]]
- result_data["decision_records_hint"] = (
- "Decisions touch this file. Call get_why(targets=[...]) for rationale."
- )
+ .where(
+ GraphEdge.repository_id == card.repo_id,
+ GraphEdge.target_node_id == sym_node_id,
+ GraphEdge.edge_type.in_(SYMBOL_USE_EDGE_TYPES),
+ )
+ )
+ # An id the graph no longer holds still names its file, so fall back to
+ # the path half rather than dropping a real user.
+ user_files: set[str] = set()
+ # A same-file caller is a real use, but naming the file already being read
+ # spends a capped row; ``callers`` has it at symbol grain. Counted first,
+ # by the confidence floor include=["callers"] serves (a recursive call is
+ # not a user), so an empty list can say so.
+ same_file_users: set[str] = set()
+ for source_node_id, file_path, confidence in res.all():
+ path = file_path or source_node_id.split("::", 1)[0]
+ user_files.add(path)
+ if (
+ path == sym.file_path
+ and source_node_id != sym_node_id
+ and (confidence or 0) >= _MIN_CALL_CONFIDENCE
+ ):
+ same_file_users.add(source_node_id)
+ return user_files, same_file_users
- # --- Ownership ---
- if include is None or "ownership" in include:
- ownership: dict[str, Any] = {}
- git_path = file_path_for_git
- if target_type == "module" and page:
- git_path = page.target_path
- if git_path:
- res = await session.execute(
- select(GitMetadata).where(
- GitMetadata.repository_id == repo_id,
- GitMetadata.file_path == git_path,
- )
- )
- meta = res.scalar_one_or_none()
- if meta:
- ownership["primary_owner"] = meta.primary_owner_name
- # owner_pct is the owner's share of commits; owner_line_pct
- # their share of current lines by blame (None without blame).
- ownership["owner_pct"] = meta.primary_owner_commit_pct
- ownership["owner_line_pct"] = getattr(meta, "primary_owner_line_pct", None)
- ownership["contributor_count"] = getattr(meta, "contributor_count", 0) or len(
- json.loads(meta.top_authors_json)
- )
- ownership["bus_factor"] = getattr(meta, "bus_factor", 0) or 0
- # Recent owner (who maintains this file now)
- recent = getattr(meta, "recent_owner_name", None)
- if recent and recent != meta.primary_owner_name:
- ownership["recent_owner"] = recent
- ownership["recent_owner_pct"] = getattr(meta, "recent_owner_commit_pct", None)
- # Agent provenance, only when agent-attributed commits exist
- # and attribution is on. The share is of commits with a known
- # source, with its coverage; unknown is never human.
- if getattr(meta, "agent_commit_count", 0) and attribution_enabled(
- repository.local_path
- ):
- ownership["agent_share"] = file_share(
- meta.agent_commit_count,
- getattr(meta, "attribution_known_count", 0),
- meta.commit_count_total,
- ).summary()
- ownership["agent_commit_count"] = meta.agent_commit_count
- with contextlib.suppress(TypeError, ValueError):
- ownership["agent_tier_counts"] = json.loads(
- getattr(meta, "agent_tier_counts_json", None) or "{}"
- )
- else:
- ownership["primary_owner"] = None
- ownership["owner_pct"] = None
- ownership["contributor_count"] = 0
- ownership["bus_factor"] = 0
- else:
- ownership["primary_owner"] = None
- ownership["owner_pct"] = None
- ownership["contributor_count"] = 0
- ownership["bus_factor"] = 0
- result_data["ownership"] = ownership
-
- # --- Last change ---
- if include is None or "last_change" in include:
- last_change: dict[str, Any] = {}
- git_path = file_path_for_git
- if target_type == "module" and page:
- git_path = page.target_path
- if git_path:
- res = await session.execute(
- select(GitMetadata).where(
- GitMetadata.repository_id == repo_id,
- GitMetadata.file_path == git_path,
- )
+
+async def _file_ranks(card: CardState, user_files: set[str]) -> dict[str, float]:
+ """PageRank per using file, 0.0 when the graph has no node for it.
+
+ Looked up by the folded path, not joined: a source whose symbol node is
+ missing has no file to join through and would rank 0.0. Chunked because
+ this binds one parameter per using file.
+ """
+ best_rank: dict[str, float] = {p: 0.0 for p in user_files}
+ ordered = sorted(user_files)
+ for start in range(0, len(ordered), _RANK_LOOKUP_CHUNK):
+ rank_rows = await card.session.execute(
+ select(GraphNode.node_id, GraphNode.pagerank).where(
+ GraphNode.repository_id == card.repo_id,
+ GraphNode.node_id.in_(ordered[start : start + _RANK_LOOKUP_CHUNK]),
)
- meta = res.scalar_one_or_none()
- if meta:
- last_change["date"] = (
- meta.last_commit_at.isoformat() if meta.last_commit_at else None
- )
- last_change["author"] = meta.primary_owner_name
- last_change["days_ago"] = await _days_since_last_change(
- session, repo_id, meta.last_commit_at, as_of_ts
- )
- else:
- last_change["date"] = None
- last_change["author"] = None
- last_change["days_ago"] = None
+ )
+ for node_id, pagerank in rank_rows.all():
+ best_rank[node_id] = float(pagerank or 0.0)
+ return best_rank
+
+
+async def _symbol_used_by(card: CardState, sym: Any, docs: dict[str, Any]) -> None:
+ """Files that use the symbol. 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)
+ user_files, same_file_users = await _symbol_user_files(card, sym, sym_node_id)
+ user_files.discard(sym.file_path)
+ # Before exclusion: an excluded user elsewhere is still a user.
+ other_file_users = bool(user_files)
+ best_rank = await _file_ranks(card, user_files)
+ used_by = filter_path_list(
+ sorted(best_rank, key=lambda p: (-best_rank[p], p)), card.query.exclude_spec
+ )
+ target = card.target
+ cap_collection(
+ docs,
+ "used_by",
+ used_by,
+ _MAX_USED_BY,
+ card.query.collector,
+ label=f"{target} :: docs.used_by beyond cap={_MAX_USED_BY}",
+ )
+ # No users found says nothing on its own until the reader knows how much
+ # of this language's call graph the resolver actually bound. Same-file
+ # users make the zero a fact about other files instead.
+ if not docs.get("used_by") and same_file_users and not other_file_users:
+ docs["used_by_basis"] = same_file_basis(len(same_file_users))
+ elif not docs.get("used_by"):
+ docs["used_by_basis"] = await call_resolution_basis(
+ card.session,
+ card.repo_id,
+ getattr(sym, "language", None),
+ cache_key=index_state_key(card.query.repository),
+ )
+
+
+_DOCS_BY_TYPE = {"file": _file_docs, "module": _module_docs, "symbol": _symbol_docs}
+
+
+async def _triage_section(card: CardState) -> None:
+ """Triage signals (always on): 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 = card.git_path
+ if not triage_path:
+ return
+ # Same single row, four columns instead of one: no extra round trip.
+ triage_meta_res = await card.session.execute(
+ select(
+ GitMetadata.is_hotspot,
+ GitMetadata.prior_defect_count,
+ GitMetadata.bug_magnet,
+ GitMetadata.last_fix_at,
+ ).where(
+ GitMetadata.repository_id == card.repo_id,
+ GitMetadata.file_path == triage_path,
+ )
+ )
+ triage_meta = triage_meta_res.one_or_none()
+ card.data["hotspot"] = bool(triage_meta.is_hotspot) if triage_meta is not None else False
+ if triage_meta is not None:
+ # Row exposes the selected columns as attributes, which is exactly the
+ # shape fix_annotation reads off a full ORM row.
+ fixes = fix_annotation(triage_meta, now=card.query.as_of_ts)
+ if fixes is not None:
+ card.data["fix_history"] = fixes
+ # Governing decisions, opt-in only: the graph query is not worth its
+ # latency on every card. Returns titles; get_why has the rationale.
+ if card.wants("decisions"):
+ await _governing_decision_titles(card, triage_path)
+
+
+async def _governing_decision_titles(card: CardState, triage_path: str) -> None:
+ target = card.target
+ governing: list[DecisionRecord] = []
+ seen_ids: set[str] = set()
+ for lookup_node in dict.fromkeys(
+ [triage_path, target] if triage_path != target else [triage_path]
+ ):
+ if not lookup_node:
+ continue
+ for dr in await get_governing_decisions(card.session, card.repo_id, lookup_node):
+ if dr.id not in seen_ids:
+ seen_ids.add(dr.id)
+ governing.append(dr)
+ if governing:
+ governing_sorted = sorted(governing, key=lambda d: -(d.confidence or 0.0))
+ card.data["decision_records"] = [dr.title for dr in governing_sorted[:3]]
+ card.data["decision_records_hint"] = (
+ "Decisions touch this file. Call get_why(targets=[...]) for rationale."
+ )
+
+
+async def _git_meta_row(card: CardState, git_path: str | None) -> GitMetadata | None:
+ if not git_path:
+ return None
+ res = await card.session.execute(
+ select(GitMetadata).where(
+ GitMetadata.repository_id == card.repo_id,
+ GitMetadata.file_path == git_path,
+ )
+ )
+ return res.scalar_one_or_none()
+
+
+async def _ownership_section(card: CardState) -> None:
+ if not card.default_on("ownership"):
+ return
+ ownership: dict[str, Any] = {}
+ meta = await _git_meta_row(card, card.git_path)
+ if meta:
+ ownership["primary_owner"] = meta.primary_owner_name
+ # owner_pct is the owner's share of commits; owner_line_pct their
+ # share of current lines by blame (None without blame).
+ ownership["owner_pct"] = meta.primary_owner_commit_pct
+ ownership["owner_line_pct"] = getattr(meta, "primary_owner_line_pct", None)
+ ownership["contributor_count"] = getattr(meta, "contributor_count", 0) or len(
+ json.loads(meta.top_authors_json)
+ )
+ ownership["bus_factor"] = getattr(meta, "bus_factor", 0) or 0
+ # Recent owner (who maintains this file now)
+ recent = getattr(meta, "recent_owner_name", None)
+ if recent and recent != meta.primary_owner_name:
+ ownership["recent_owner"] = recent
+ ownership["recent_owner_pct"] = getattr(meta, "recent_owner_commit_pct", None)
+ _agent_provenance(card, meta, ownership)
+ else:
+ ownership["primary_owner"] = None
+ ownership["owner_pct"] = None
+ ownership["contributor_count"] = 0
+ ownership["bus_factor"] = 0
+ card.data["ownership"] = ownership
+
+
+def _agent_provenance(card: CardState, meta: GitMetadata, ownership: dict[str, Any]) -> None:
+ """Agent provenance, only when agent-attributed commits exist and
+ attribution is on. The share is of commits with a known source, with its
+ coverage; unknown is never human."""
+ if not (
+ getattr(meta, "agent_commit_count", 0)
+ and attribution_enabled(card.query.repository.local_path)
+ ):
+ return
+ ownership["agent_share"] = file_share(
+ meta.agent_commit_count,
+ getattr(meta, "attribution_known_count", 0),
+ meta.commit_count_total,
+ ).summary()
+ ownership["agent_commit_count"] = meta.agent_commit_count
+ with contextlib.suppress(TypeError, ValueError):
+ ownership["agent_tier_counts"] = json.loads(
+ getattr(meta, "agent_tier_counts_json", None) or "{}"
+ )
+
+
+async def _last_change_section(card: CardState) -> None:
+ if not card.default_on("last_change"):
+ return
+ last_change: dict[str, Any] = {}
+ meta = await _git_meta_row(card, card.git_path)
+ if meta:
+ last_change["date"] = meta.last_commit_at.isoformat() if meta.last_commit_at else None
+ last_change["author"] = meta.primary_owner_name
+ last_change["days_ago"] = await _days_since_last_change(
+ card.session, card.repo_id, meta.last_commit_at, card.query.as_of_ts
+ )
+ else:
+ last_change["date"] = None
+ last_change["author"] = None
+ last_change["days_ago"] = None
+ card.data["last_change"] = last_change
+
+
+async def _changes_section(card: CardState) -> None:
+ """Change Records and provenance (file targets, opt-in)."""
+ include = card.include
+ file_path = card.resolved.file_path
+ if not (
+ include
+ and card.resolved.target_type == "file"
+ and file_path
+ and include & {"changes", "provenance"}
+ ):
+ return
+ repository = card.query.repository
+ attribution = attribution_enabled(repository.local_path)
+ if "changes" in include:
+ found = await file_changes(card.session, repository, [file_path], attribution=attribution)
+ card.data.update(found[file_path])
+ if "provenance" in include:
+ meta = await load_file_meta(card.session, card.repo_id, file_path) if attribution else None
+ card.data["provenance"] = file_provenance(meta, attribution)
+
+
+async def _decisions_section(card: CardState) -> None:
+ """Decision lanes. 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: "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.
+ """
+ if not card.default_on("decisions"):
+ return
+ res = await card.session.execute(
+ select(DecisionRecord)
+ .where(
+ DecisionRecord.repository_id == card.repo_id,
+ or_(DecisionRecord.status != "dismissed", accepted_predicate()),
+ )
+ .order_by(*decision_priority_order())
+ )
+ all_decisions = list(res.scalars().all())
+ currencies = await decision_currencies(card.session, card.repo_id, all_decisions)
+ governing, candidates, history = _decision_lanes(card, all_decisions, currencies)
+ target, collector = card.target, card.query.collector
+ card.data["decisions"] = governing
+ # 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(
+ card.data,
+ "candidates",
+ candidates,
+ _MAX_CANDIDATES,
+ collector,
+ label=f"{target} :: candidates beyond cap={_MAX_CANDIDATES}",
+ )
+ if history:
+ cap_collection(
+ card.data,
+ "history",
+ history,
+ _MAX_DECISION_HISTORY,
+ collector,
+ label=f"{target} :: decision history beyond cap={_MAX_DECISION_HISTORY}",
+ )
+
+
+def _decision_lanes(
+ card: CardState, all_decisions: list[DecisionRecord], currencies: dict[str, Any]
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]:
+ """The decisions naming this target, split into governing, candidate and
+ history lanes."""
+ target, file_path = card.target, card.resolved.file_path
+ governing: list[dict[str, Any]] = []
+ 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.
+ if not binds_to_paths(d.scope_basis):
+ continue
+ affected_files = json.loads(d.affected_files_json)
+ affected_modules = json.loads(d.affected_modules_json)
+ if not (
+ target in affected_files
+ or target in affected_modules
+ or (file_path and file_path in affected_files)
+ ):
+ continue
+ entry: dict[str, Any] = {
+ "id": d.id,
+ "title": d.title,
+ "status": d.status,
+ "decision": _decision_body(d),
+ "rationale": d.rationale,
+ "confidence": d.confidence,
+ }
+ currency = currencies.get(d.id)
+ if currency is None:
+ entry["authority"] = "candidate"
+ candidates.append(entry)
+ elif is_governing(currency):
+ entry["authority"] = "accepted"
+ entry["currency"] = currency
+ governing.append(entry)
else:
- last_change["date"] = None
- last_change["author"] = None
- last_change["days_ago"] = None
- result_data["last_change"] = last_change
-
- # --- Change Records and provenance (file targets, opt-in) ---
- if include and target_type == "file" and file_path_for_git and include & {
- "changes",
- "provenance",
- }:
- attribution = attribution_enabled(repository.local_path)
- if "changes" in include:
- found = await file_changes(
- session, repository, [file_path_for_git], attribution=attribution
- )
- result_data.update(found[file_path_for_git])
- if "provenance" in include:
- meta = await load_file_meta(session, repo_id, file_path_for_git) if attribution else None
- result_data["provenance"] = file_provenance(meta, attribution)
-
- # --- Decisions ---
- if include is None or "decisions" in include:
- # 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: "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(
- DecisionRecord.repository_id == repo_id,
- or_(DecisionRecord.status != "dismissed", accepted_predicate()),
+ entry["authority"] = "withdrawn"
+ entry["currency"] = currency
+ history.append(entry)
+ return governing, candidates, history
+
+
+def _page_freshness(page: Page | None) -> dict[str, Any]:
+ if not page:
+ return {"confidence_score": None, "freshness_status": None, "is_stale": None}
+ return {
+ "confidence_score": page.confidence,
+ "freshness_status": page.freshness_status,
+ "is_stale": is_stale_status(page.freshness_status),
+ }
+
+
+async def _freshness_section(card: CardState) -> None:
+ """``is_stale`` uses ``is_stale_status``, the rule ``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 not card.default_on("freshness"):
+ return
+ file_path = card.resolved.file_path
+ page = card.page
+ if not page and card.resolved.target_type == "symbol" and file_path:
+ page = await card.session.get(Page, f"file_page:{file_path}")
+ freshness = _page_freshness(page)
+ if file_path and uncommitted_targets(
+ served_root(card.query.repository, card.query.repo_root), [file_path]
+ ):
+ freshness["working_tree"] = "modified"
+ card.data["freshness"] = freshness
+
+
+async def _kg_section(card: CardState) -> None:
+ """The file's architectural layer and its step in the guided tour."""
+ file_path = card.resolved.file_path
+ if not (card.resolved.target_type == "file" and file_path):
+ return
+ kg_layers = await get_kg_layers(card.session, card.repo_id)
+ if not kg_layers:
+ return
+ for _l in kg_layers:
+ _l._parsed_node_ids = json.loads(_l.node_ids_json) if _l.node_ids_json else []
+ file_layer = _find_layer_for_file(file_path, kg_layers)
+ if file_layer:
+ edge_res = await card.session.execute(
+ select(GraphEdge).where(
+ GraphEdge.repository_id == card.repo_id,
+ GraphEdge.target_node_id == file_path,
+ GraphEdge.edge_type == "imports",
)
- .order_by(*decision_priority_order())
)
- all_decisions = list(res.scalars().all())
- currencies = await decision_currencies(session, repo_id, all_decisions)
- governing: list[dict[str, Any]] = []
- 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.
- if not binds_to_paths(d.scope_basis):
- continue
- affected_files = json.loads(d.affected_files_json)
- affected_modules = json.loads(d.affected_modules_json)
- if not (
- target in affected_files
- or target in affected_modules
- or (file_path_for_git and file_path_for_git in affected_files)
- ):
- continue
- entry: dict[str, Any] = {
- "id": d.id,
- "title": d.title,
- "status": d.status,
- "decision": _decision_body(d),
- "rationale": d.rationale,
- "confidence": d.confidence,
+ incoming_edges = list(edge_res.scalars())
+ card.data["architectural_layer"] = {
+ "name": file_layer.name,
+ "description": (file_layer.description or "")[:200],
+ "role": _classify_file_role(file_path, file_layer, incoming_edges),
+ }
+ kg_tour = await get_kg_tour_steps(card.session, card.repo_id)
+ if kg_tour:
+ for _s in kg_tour:
+ _s._parsed_node_ids = json.loads(_s.node_ids_json) if _s.node_ids_json else []
+ file_tour_step = _find_tour_step_for_file(file_path, kg_tour)
+ if file_tour_step:
+ card.data["tour_context"] = {
+ "step": file_tour_step.step_order,
+ "title": file_tour_step.title,
+ "why": (file_tour_step.description or "")[:200],
}
- currency = currencies.get(d.id)
- if currency is None:
- entry["authority"] = "candidate"
- candidates.append(entry)
- elif is_governing(currency):
- entry["authority"] = "accepted"
- entry["currency"] = currency
- governing.append(entry)
- else:
- entry["authority"] = "withdrawn"
- entry["currency"] = currency
- history.append(entry)
- result_data["decisions"] = governing
- # 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,
- "candidates",
- candidates,
- _MAX_CANDIDATES,
- collector,
- label=f"{target} :: candidates beyond cap={_MAX_CANDIDATES}",
- )
- if history:
- cap_collection(
- result_data,
- "history",
- history,
- _MAX_DECISION_HISTORY,
- collector,
- label=f"{target} :: decision history beyond cap={_MAX_DECISION_HISTORY}",
- )
- # --- Freshness ---
- # ``is_stale`` uses ``is_stale_status``, the rule ``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] = {}
-
- if page:
- freshness["confidence_score"] = page.confidence
- freshness["freshness_status"] = page.freshness_status
- freshness["is_stale"] = is_stale_status(page.freshness_status)
- elif target_type == "symbol" and file_path_for_git:
- sym_page_id = f"file_page:{file_path_for_git}"
- sym_page = await session.get(Page, sym_page_id)
- if sym_page:
- freshness["confidence_score"] = sym_page.confidence
- freshness["freshness_status"] = sym_page.freshness_status
- freshness["is_stale"] = is_stale_status(sym_page.freshness_status)
- else:
- freshness["confidence_score"] = None
- freshness["freshness_status"] = None
- freshness["is_stale"] = None
- else:
- freshness["confidence_score"] = None
- freshness["freshness_status"] = None
- freshness["is_stale"] = None
- if file_path_for_git and uncommitted_targets(
- served_root(repository, repo_root), [file_path_for_git]
- ):
- freshness["working_tree"] = "modified"
- result_data["freshness"] = freshness
-
- # --- KG layer + tour context (Phase 9) ---
- if target_type == "file" and file_path_for_git:
- kg_layers = await get_kg_layers(session, repo_id)
- if kg_layers:
- for _l in kg_layers:
- _l._parsed_node_ids = json.loads(_l.node_ids_json) if _l.node_ids_json else []
- file_layer = _find_layer_for_file(file_path_for_git, kg_layers)
- if file_layer:
- edge_res = await session.execute(
- select(GraphEdge).where(
- GraphEdge.repository_id == repo_id,
- GraphEdge.target_node_id == file_path_for_git,
- GraphEdge.edge_type == "imports",
- )
- )
- incoming_edges = list(edge_res.scalars())
- result_data["architectural_layer"] = {
- "name": file_layer.name,
- "description": (file_layer.description or "")[:200],
- "role": _classify_file_role(file_path_for_git, file_layer, incoming_edges),
- }
- kg_tour = await get_kg_tour_steps(session, repo_id)
- if kg_tour:
- for _s in kg_tour:
- _s._parsed_node_ids = json.loads(_s.node_ids_json) if _s.node_ids_json else []
- file_tour_step = _find_tour_step_for_file(file_path_for_git, kg_tour)
- if file_tour_step:
- result_data["tour_context"] = {
- "step": file_tour_step.step_order,
- "title": file_tour_step.title,
- "why": (file_tour_step.description or "")[:200],
- }
-
- # --- Callers / Callees (replaces get_callers_callees) ---
- want_callers = bool(include and "callers" in include)
- want_callees = bool(include and "callees" in include)
- if want_callers or want_callees:
- await _resolve_call_graph(
- session,
- repository,
- symbol_node_id or target,
- target_type,
- result_data,
- want_callers=want_callers,
- want_callees=want_callees,
- exclude_spec=exclude_spec,
- collector=collector,
- repo_root=served_root(repository, repo_root),
- )
+async def _call_graph_section(card: CardState) -> None:
+ want_callers = card.wants("callers")
+ want_callees = card.wants("callees")
+ if not (want_callers or want_callees):
+ return
+ query = card.query
+ await _resolve_call_graph(
+ card.session,
+ query.repository,
+ card.resolved.symbol_node_id or card.target,
+ card.resolved.target_type,
+ card.data,
+ want_callers=want_callers,
+ want_callees=want_callees,
+ exclude_spec=query.exclude_spec,
+ collector=query.collector,
+ repo_root=served_root(query.repository, query.repo_root),
+ )
- # --- Reference edit set: every live site naming the symbol ---
- if include and "references" in include:
- ref_node = graph_symbol
- if ref_node is None and target_type == "symbol" and symbol_node_id:
- res = await session.execute(
- select(GraphNode).where(
- GraphNode.repository_id == repo_id,
- GraphNode.node_id.in_(symbol_id_variants(symbol_node_id)),
- GraphNode.node_type == "symbol",
- )
- )
- ref_node = min(
- res.scalars().all(),
- key=lambda g: (g.node_id != symbol_node_id, g.node_id),
- default=None,
- )
- root = served_root(repository, repo_root)
- if ref_node is not None and root:
- result_data["references"] = await reference_edit_set(
- session, repo_id, root, ref_node, collector
+
+async def _references_section(card: CardState) -> None:
+ """Reference edit set: every live site naming the symbol."""
+ if not card.wants("references"):
+ return
+ resolved = card.resolved
+ ref_node = resolved.graph_symbol
+ symbol_node_id = resolved.symbol_node_id
+ if ref_node is None and resolved.target_type == "symbol" and symbol_node_id:
+ res = await card.session.execute(
+ select(GraphNode).where(
+ GraphNode.repository_id == card.repo_id,
+ GraphNode.node_id.in_(symbol_id_variants(symbol_node_id)),
+ GraphNode.node_type == "symbol",
)
- else:
- result_data["references_note"] = "references require a symbol target in the graph"
+ )
+ ref_node = min(
+ res.scalars().all(),
+ key=lambda g: (g.node_id != symbol_node_id, g.node_id),
+ default=None,
+ )
+ root = served_root(card.query.repository, card.query.repo_root)
+ if ref_node is not None and root:
+ card.data["references"] = await reference_edit_set(
+ card.session, card.repo_id, root, ref_node, card.query.collector
+ )
+ else:
+ card.data["references_note"] = "references require a symbol target in the graph"
+
+
+async def _metrics_section(card: CardState) -> None:
+ if card.wants("metrics"):
+ await _resolve_metrics(
+ card.session,
+ card.query.repository,
+ card.resolved.symbol_node_id or card.target,
+ card.data,
+ )
- # --- Metrics (replaces get_graph_metrics) ---
- if include and "metrics" in include:
- await _resolve_metrics(session, repository, symbol_node_id or target, result_data)
- # --- Community (replaces get_community) ---
- if include and "community" in include:
+async def _community_section(card: CardState) -> None:
+ if card.wants("community"):
await _resolve_community(
- session, repository, symbol_node_id or target, result_data, exclude_spec=exclude_spec
+ card.session,
+ card.query.repository,
+ card.resolved.symbol_node_id or card.target,
+ card.data,
+ exclude_spec=card.query.exclude_spec,
+ )
+
+
+async def _health_section(card: CardState) -> None:
+ if card.wants("health"):
+ await _resolve_health(
+ card.session,
+ card.query.repository,
+ card.target,
+ card.resolved.target_type,
+ card.data,
)
- # --- Code health (Phase 2) ---
- if include and "health" in include:
- await _resolve_health(session, repository, target, target_type, result_data)
- # --- Documents naming this file (doc-drift reverse view) ---
- # Only the path is recorded here. The read itself is one batched pass over
- # every target, after the gather: see ``attach_doc_references``, which
- # explains why a savepoint per target cannot work on a shared session.
- if include and "doc_drift" in include:
- result_data[_DOC_DRIFT_PATH] = file_path_for_git
+async def _doc_drift_section(card: CardState) -> None:
+ """Documents naming this file (doc-drift reverse view).
- # --- Skeleton (distill) — opt-in only, see the module note ---
- if want_skeleton:
+ Only the path is recorded here. The read itself is one batched pass over
+ every target, after the gather: see ``attach_doc_references``, which
+ explains why a savepoint per target cannot work on a shared session.
+ """
+ if card.wants("doc_drift"):
+ card.data[_DOC_DRIFT_PATH] = card.resolved.file_path
+
+
+async def _skeleton_section(card: CardState) -> None:
+ """Skeleton (distill), opt-in only; see the module note."""
+ if card.want_skeleton:
await _resolve_skeleton(
- session,
- repository,
- target,
- target_type,
- result_data,
- repo_root=repo_root,
- mode="plus" if skeleton_plus else "smart",
+ card.session,
+ card.query.repository,
+ card.target,
+ card.resolved.target_type,
+ card.data,
+ repo_root=card.query.repo_root,
+ mode="plus" if card.skeleton_plus else "smart",
)
- return result_data
+
+CardSection = Callable[[CardState], Awaitable[None]]
+
+#: The card after identity, in wire (JSON key) order: each section adds its
+#: keys after the ones before it.
+_CARD_SECTIONS: tuple[CardSection, ...] = (
+ _parent_page_section,
+ _docs_section,
+ _triage_section,
+ _ownership_section,
+ _last_change_section,
+ _changes_section,
+ _decisions_section,
+ _freshness_section,
+ _kg_section,
+ _call_graph_section,
+ _references_section,
+ _metrics_section,
+ _community_section,
+ _health_section,
+ _doc_drift_section,
+ _skeleton_section,
+)