query-code

Query codemap structural index for import-graph analysis, symbol-level source extraction, function-level call graph traversal. Python projects only — index covers .py files; queries on non-Python projects return empty or error. scan-query on PATH (installed by codemap plugin).

Module-level queries (import graph):

• central [--top N] — most-imported modules (highest blast radius, default top 10)
• coupled [--top N] — modules with most imports (highest coupling, default top 10)
• deps <module> — what module imports
• rdeps <module> — what imports module
• path <from> <to> — shortest import path between two modules

Symbol-level queries (use instead of reading full files — ~94% token reduction):

• symbol <name> — get source of function/class/method by name
• symbols <module> — list all symbols in module (no file I/O)
• find-symbol <pattern> — regex search across all symbol names in index

Function-level call graph queries (v3 index — requires /codemap:scan-codebase with call graph):

• fn-deps <qname> — what does function/method call? (outgoing edges)
• fn-rdeps <qname> — what functions call this one? (incoming edges)
• fn-central [--top N] — most-called functions globally (default top 10)
• fn-blast <qname> — transitive reverse-call BFS with depth levels

Use module::function format for qname, e.g. mypackage.auth::validate_token. Requires v3 index — v2 returns clear upgrade prompt.

NOT for: building or rebuilding index (use /codemap:scan-codebase). All query subcommands are read-only — any request that modifies the index or project files belongs to /codemap:scan-codebase (index writes) or /codemap:integration (file injection). Ambiguous prompts like "show me the call graph" that imply read → query-code is correct; "update the call graph" → scan-codebase. If subcommand roster expands significantly, run /foundry:calibrate routing (requires foundry plugin) to verify no routing collisions.

Step 1: Run the query

deps vs rdeps — choose before calling:

Common mistake — direction matters: "which modules need updating if X changes?" = rdeps (callers), NOT deps. deps returns wrong direction — 0% recall.

Unsupported flag check — after all supported flags extracted, scan $ARGUMENTS for remaining --<token> tokens. If found: print ! Unknown flag(s): \--<token>`. Supported: `--top`, `--exclude-tests`, `--limit`, `--index`.then invokeAskUserQuestion` — (a) Abort (stop, re-invoke with correct flags) · (b) Continue ignoring (skip unknown flags, proceed). On Abort: stop.

Run scan-query via Bash:

# timeout: 20000
scan-query <QUERY_ARGS>

Replace <QUERY_ARGS>:

scan-query on PATH, locates index via git root — no setup. Missing index prints clear error.

Symbol names accept: bare name (authenticate), qualified name (MyClass.authenticate), or case-insensitive substring fallback. Function qnames use module::function format (e.g. mypackage.auth::validate_token). Index must be current — re-run /codemap:scan-codebase if stale warning appears.

Budget and stop rules

Query budget: max 3 calls per task. Stop after 3 even if not exhaustive — report what found. Exception: explicit exhaustive multi-target analysis requests — state exhaustive intent before first call, budget extends to 6. Declaring exhaustive intent after the first call has already been made is invalid — treat that run as non-exhaustive (budget=3).

Exhaustive path/fn-blast traversal — path and fn-blast queries traverse the graph internally and may require deeper exploration than 3 surface calls allow. For these subcommands, increase guidance to 10 calls when caller declares exhaustive intent OR set budget_override=unlimited before first call. Without override, path/fn-blast still capped at 6 (exhaustive-mode default) — caller must opt in explicitly for unbounded traversal.

exhaustive: true — STOP ALL TOOL CALLS: When rdeps or deps result contains "exhaustive": true, list complete and authoritative for unfiltered index. Note: if --exclude-tests used, exhaustive reflects unfiltered coverage — filtered results may omit callers; state caveat if relevant. Write answer immediately. Do NOT call codemap again. Do NOT run grep, bash, or Glob passes to verify or extend. No exceptions.

Non-exhaustive result — convergence rule: after budget calls still non-exhaustive, stop and report what found. Do NOT switch to grep/bash — index covers what it covers.

Step 2: Parse JSON output and format

scan-query always emits JSON object — parse before rendering. Stale-index detection has two channels: (1) stderr: if contains [stale] or ⚠ codemap index stale — surface warning; (2) JSON field index.stale (boolean) — check result.index.stale; if true, warn user to re-run /codemap:scan-codebase. Check index.degraded in result; if > 0, caveat that some modules unparsable.

{"error": "..."}: surface error, suggest re-running /codemap:scan-codebase.

Partial JSON handling: if output is truncated (does not parse as complete JSON object — e.g., ends mid-value or missing closing }), log ⚠ partial JSON response — results may be incomplete and attempt to parse only complete top-level fields present before truncation. Surface whatever was recovered; do not silently discard partial results.

Flags available on multiple commands (--exclude-tests, --limit, --index):

• --exclude-tests — drop test modules from results; applies to: rdeps, central, coupled, symbol, find-symbol, fn-rdeps, fn-central; not supported on path (see path row in table above)
• --limit N (default 20, use 0 for all) — caps results on symbol and find-symbol; pass --limit 0 before counting or ranking to avoid silent truncation
• --index <path> — explicit index file path (byp