Hybrid semantic + structural query over the Swift codebase graph.

:param q: Natural-language query, e.g. "request retry policy". :param k: Number of semantic seed nodes (default 8). :param hop: Graph expansion hops (default 1). :param rels: Comma-separated edge types to follow. :param max_nodes: Maximum nodes to return (default 25). :param min_score: Minimum semantic score for seed inclusion in [0, 1]. :param max_per_module: Maximum nodes per module (default 3; 0 disables). :param rerank_mode: 'hybrid' (default), 'semantic', or 'legacy'. :param rerank_semantic_weight: Semantic weight for hybrid mode (default 0.7). :param rerank_lexical_weight: Lexical weight for hybrid mode (default 0.3). :param format: 'json' (default) or 'markdown'. :return: JSON string or Markdown table.

Hybrid query + source-grounded Swift snippet extraction.

Returns a Markdown context pack with ranked, deduplicated code snippets and line numbers — ready for direct LLM ingestion.

:param q: Natural-language query, e.g. "request error handling". :param k: Number of semantic seed nodes (default 8). :param hop: Graph expansion hops (default 1). :param rels: Comma-separated edge types to follow. :param context: Extra context lines around each definition (default 5). :param max_lines: Maximum lines per snippet block (default 60). :param max_nodes: Maximum nodes to include in the pack (default 15). :param min_score: Minimum semantic score for seed inclusion in [0, 1]. :param max_per_module: Maximum nodes per module (default 3; 0 disables). :param rerank_mode: 'hybrid' (default), 'semantic', or 'legacy'. :param rerank_semantic_weight: Semantic weight for hybrid mode (default 0.7). :param rerank_lexical_weight: Lexical weight for hybrid mode (default 0.3). :return: Markdown string with source-grounded code snippets.

Return all nodes that call a given node, resolving through sym: stubs.

Unlike query_codebase (which seeds on semantics and expands outward), this tool performs a precise reverse lookup: it finds every caller of the specified node, including cross-module callers that reference it via an import alias recorded as a sym: stub.

The rel parameter accepts any edge relation, not just CALLS::

callers(node_id, rel="INHERITS")    # find all subclasses
callers(node_id, rel="CONFORMS")    # every type conforming to a protocol
callers(node_id, rel="IMPORTS")     # find all importers

Typical workflow::

# 1. Resolve the exact node ID
get_node("meth:Sources/Networking/Client.swift:HTTPClient.send")

# 2. Find all callers (production code only)
callers("meth:Sources/Networking/Client.swift:HTTPClient.send", paths="Sources/")

:param node_id: Target node identifier, e.g. cls:Sources/Networking/Client.swift:HTTPClient. :param rel: Relation type to invert (default "CALLS"). :param paths: Comma-separated module path prefixes to include, e.g. "Sources/" to exclude test callers. Empty string (default) returns all callers. :return: JSON with node_id, rel, caller_count, and callers list of node dicts.

Return everything the graph knows about one Swift type's relationships.

Swift spreads a type across three relations that the sibling language modules do not have to separate, and answering "what is this type" means reading all three at once:

• conformers — every type and extension conforming to it, if it is a protocol. This is the question about a protocol.

• subclasses — every direct subclass, if it is a class or actor.

• extensions — every extension declared on it, which in Swift routinely live in other files. "Where is the rest of this type" is a real question with a graph answer.

• conforms_to / inherits_from — what it declares for itself.

Calling callers() three times with three relations returns the same facts; this returns them together, already labelled, because for a Swift type they are one question.

:param node_id: Node ID of a class, struct, enum, protocol or actor, e.g. proto:Sources/SampleKit/Storage.swift:Repository. :return: JSON with node, conformers, subclasses, extensions, conforms_to and inherits_from.

List the declared public API surface.

Swift states access level with a keyword and SwiftKG stores it, so this is a fact read out of the graph rather than a heuristic. Use it to review what a module actually exposes, or to find public declarations that no longer need to be.

:param module_path: Restrict to files under this path prefix. Empty (default) covers the whole repository. :param limit: Maximum declarations to return (1-1000). :return: JSON with count and a declarations list, each carrying its visibility.

Fetch a single Swift node by its stable ID and render as Markdown.

Node IDs follow the pattern <kind>:<module_path>:<qualname>, e.g. cls:Sources/Networking/Client.swift:HTTPClient or meth:Sources/Networking/Client.swift:HTTPClient.send.

:param node_id: Stable node identifier. :param include_edges: If True, append outgoing edges and incoming callers. :return: Markdown-formatted node summary.

Return node and edge counts by kind and relation as Markdown.

Call this first when engaging with a new Swift repo. Reports doc-comment coverage (fraction of functions/methods with doc-comment comments).

:return: Markdown summary with total counts, nodes-by-kind, and edges-by-relation tables.

List nodes filtered by module path prefix and/or kind.

:param module_path: Module path prefix filter (e.g. "Sources/Networking/Client.swift"). :param kind: Node kind filter: module | class | struct | enum | protocol | actor | extension | function | method | property | typealias. :return: JSON array of matching node dicts.

Find graph nodes by name without knowing their full stable ID.

Case-insensitive match against name and qualname. Use when you know a function or class name from reading code and need its stable ID.

:param name: Function, type, or protocol name to search for. :param kind: Optional kind filter: module | class | struct | protocol | function | method | etc. :return: JSON array of matching node dicts.

Compute Structural Importance Ranking (SIR) for the indexed codebase.

Runs a deterministic weighted PageRank over the sym-stub-resolved call graph. Edge weights are tuned per relation type (CALLS > INHERITS/CONFORMS/EXTENDS > IMPORTS > CONTAINS) and amplified for cross-module links; private symbols receive a post-convergence penalty. Scores are normalized to sum to 1.0.

Use this to:

• Identify the most structurally critical functions, types, and protocols

• Understand which modules are most depended upon

• Prioritize code review, refactoring, or test coverage efforts

:param top: Maximum number of ranked entries to return (default 20). :param kinds: Comma-separated node kinds to include: module, class, struct, protocol, actor, function, method. Empty string returns all kinds. Ignored when group_by='module' (all kinds contribute to module aggregation). :param group_by: node (default) returns individual node rankings with score, inbound edge count, and cross-module inbound count; module aggregates node scores per module. :return: Markdown-formatted ranking table.

Compute module connectivity: how many unique modules each module interacts with.

For well-modularized codebases, identifies orchestrator and hub modules that touch many other modules. Replaces betweenness centrality (which is meaningless when inter-module edges are zero).

Connectivity score = (unique modules called + unique modules calling this) / 30 + frequency / 50 Higher score = more complex coupling with other modules.

Scores are persisted to the centrality_scores table under the module_connectivity metric for use by framework_nodes().

:param top: Number of top connectivity modules to return (default 20). :param include_imports: Whether to include IMPORTS in connectivity (default True). :return: Markdown-formatted ranking table of modules by connectivity.

Identify framework-like (hub) modules using SIR + module connectivity.

A "framework node" is a module that is both:

• Structurally important (high SIR/PageRank — central to the graph)

• Highly connected (calls/imports many modules — orchestrator/hub role)

Framework score = 0.6 × normalized SIR + 0.4 × normalized connectivity, both auto-computed on first call. High-scoring modules are critical hubs: architecturally central AND complex in their interactions.

:param top: Number of top framework-like modules to return (default 20). :return: Markdown-formatted ranking table of framework nodes.

Find the code node whose definition spans a given file location.

Reverse-resolves a (file, line) pair to a graph node ID and returns the same Markdown report as explain(). Useful when reading a file in an IDE and wanting to understand the symbol at a specific line without constructing a node ID manually.

Matches the innermost (most-specific) function, method, type, extension, type alias, or enum whose lineno ≤ line ≤ end_lineno. Falls back to the module node when no narrower match exists.

:param file: Module path as stored in the graph, e.g. Sources/Networking/Client.swift. Leading ./ is stripped automatically. :param line: Line number (1-indexed) within the file. :return: Markdown explanation from explain(), or an informative error message if no node spans that location.

Run a full structural analysis of the indexed Swift repository.

Executes the 14-phase SwiftKG analysis pipeline — baseline metrics, CodeRank, fan-in/fan-out, module coupling, critical call chains, public API surface, doc-comment coverage, type hierarchy and conformance, insights, snapshot history, and SIR centrality — and returns the results as Markdown.

:return: Markdown-formatted analysis report.

Return a natural-language explanation of a code node.

Given a node ID (e.g., meth:Sources/Networking/Client.swift:HTTPClient.send), returns a markdown-formatted explanation that includes:

• What it is: The node's kind, short description from its doc-comment

• Where it lives: Module path and source location

• What calls it: The callers (reverse call graph)

• What it calls: The callees (functions/methods this node invokes)

• Documentation: Full doc-comment if available

This is ideal for understanding the role and context of a specific node without needing to read the full source code. Use pack_snippets() to then retrieve the actual implementation.

:param node_id: Stable node identifier, e.g. meth:Sources/Networking/Client.swift:HTTPClient.send. :param limit: Maximum callers and callees to list (default 10). Pass 0 to list all. :return: Markdown-formatted explanation ready for LLM consumption.

Compute global weighted CodeRank (PageRank) over the repository graph.

Builds a directed weighted graph from the SQLite store and runs weighted PageRank to identify the most structurally important nodes. Relation weights follow the CodeRank defaults: CALLS=1.0, IMPORTS=0.9, INHERITS/CONFORMS/EXTENDS=0.75. Test paths are excluded by default.

Optionally persists the scores into the node_metrics table under the given metric name so they can be loaded at query time without recomputing.

:param top: Number of top-ranked nodes to return (default 25). :param rels: Comma-separated relations to include in the graph (default "CALLS,IMPORTS,INHERITS,CONFORMS,EXTENDS"). :param persist_metric: If non-empty, persist scores to node_metrics under this metric name (e.g. "coderank_global"). :param exclude_tests: Exclude test-path nodes from the graph (default True). :return: JSON array of ranked node dicts with node_id, score, top_pct (e.g. "top 0.5%"), kind, qualname, module_path, and rank fields.

Rank query results using CodeRank-enhanced hybrid or personalized PageRank.

Combines semantic seed scores from the vector index with structural centrality and graph proximity to produce a final ranked list with explainability components.

Two modes are available:

• hybrid (default): 0.60 × semantic + 0.25 × centrality + 0.15 × proximity

• ppr: 0.70 × personalized PageRank + 0.30 × semantic

:param q: Natural-language query string. :param k: Number of semantic seed nodes to retrieve (default 8). :param mode: Ranking mode — "hybrid" (default) or "ppr". :param top: Maximum ranked results to return (default 25). :param rels: Comma-separated relations to include in the local graph. :param radius: Graph expansion radius around seeds (default 2). :param exclude_tests: Exclude test-path nodes (default True). :return: JSON array of ranked result dicts with score components and why explanation strings. sym: import stub nodes are always excluded from the output.

Explain the CodeRank score components for a specific node.

Returns a Markdown report showing the node's structural position in the graph: how many nodes call it, import it, or inherit from / implement / extend it; its global CodeRank score; and, when a query is provided, its semantic relevance and proximity to the query seed set.

:param node_id: Stable node identifier, e.g. meth:Sources/Networking/Client.swift:HTTPClient.send. :param q: Optional query string. When provided, semantic score and proximity to the query seed set are included in the report. :return: Markdown-formatted explanation of the node's rank components.

List saved temporal snapshots of codebase metrics in reverse chronological order.

Each entry in the returned list contains a key (tree hash snapshot identifier), branch, timestamp, version, and a summary of key metrics (node count, edge count, doc-comment coverage) plus deltas vs. the previous snapshot. Use the key field when calling snapshot_show() or snapshot_diff(key_a=..., key_b=...).

Use this tool to answer questions like "how has the codebase grown?" or "when did doc-comment coverage improve?" or "show me only main-branch snapshots".

:param limit: Maximum number of snapshots to return (default 10; pass 0 for all). :param branch: If provided, filter to snapshots from this branch only (e.g. "main" or "develop"). :return: JSON array of snapshot metadata dicts, most recent first.

Show full details of a specific codebase metrics snapshot.

Pass a snapshot key (tree hash) to retrieve that exact snapshot, or use the special value "latest" (default) to retrieve the most recent one.

Snapshot keys are the key field returned by snapshot_list().

The returned object contains the full metrics dict (total_nodes, total_edges, meaningful_nodes, docstring_coverage, node_counts, edge_counts, critical_issues, complexity_median), the top hotspots, and deltas computed vs. both the previous and the baseline (oldest) snapshots.

:param key: Snapshot key to load, or "latest" for the most recent snapshot (default "latest"). Keys are tree hashes returned by snapshot_list(). :return: JSON object with full snapshot details, or an error dict if the requested snapshot does not exist.

Compare two codebase metric snapshots side-by-side.

Returns the full metrics dict for both snapshots and a computed delta (b − a) covering node and edge counts, plus per-kind node count and per-relation edge count deltas.

Typical workflow::

# 1. List available snapshots — note the 'key' field in each entry
snapshot_list()

# 2. Diff any two using the key= field values
snapshot_diff(key_a="abc1234ef...", key_b="def5678ab...")

:param key_a: First (older) snapshot key — the key field from snapshot_list() output (a tree-hash string). :param key_b: Second (newer) snapshot key — the key field from snapshot_list() output (a tree-hash string). :return: JSON object with keys a (metrics + issues list for key_a), b (metrics + issues list for key_b), delta (b − a), node_counts_delta, and edge_counts_delta. Returns an error dict if either snapshot is missing.