query-code

NOT for: rebuilding the index (use /codemap-py:scan-codebase), renaming symbols (use /codemap-py:rename-refs), or which tests cover or are affected by a change (use /codemap-py:test-impact).

Test-impact split: a one-off structural fact ("which tests would this touch?") uses table subcommand test-impact <target>; full affected-test workflow (index ensure, JSON parse, pytest command, not_covered caveat) uses /codemap-py:test-impact. NOT-for defers workflow, not subcommand.

Skip Codemap when exact file + symbol localize edit and no caller, dependency, blast-radius, test-impact, import, or source-slice fact remains open. Lifecycle boundary—callback/hook, cancellation/exception, scheduling/cleanup, state transfer—keeps scope open: inspect source + named test/oracle, then query fn-rdeps for caller or fn-deps for callee responsibility. Explicit structural query/tool requirement overrides skip. Otherwise use smallest complete query.

Choose the smallest complete query set

"Affected if X changes" = reverse dependencies. Run every query from the caller's current repository; working directory selects project index. Do not cd into $CLAUDE_PLUGIN_ROOT or plugin directory.

codemap-py query --compact <subcommand> [arguments]

Enabled plugin adds version-matched bin/ to Bash PATH. If unavailable interactively, invoke installed plugin's absolute bin/codemap-py launcher as one standalone command and accept normal host permission prompt. Prepend no cd, export, or other shell command.

Goal	Query subcommand
production module importers / blast radius	rdeps <module> --exclude-tests
direct test-module importers	rdeps <module> then filter/report test modules
module imports	deps <module>
shortest import chain	path <from> <to>
production centrality / highest in-degree	central --top N --exclude-tests
internal-import coupling (not centrality)	coupled --top N
symbol source including module imports or module symbols	symbol <name> --with-imports · symbols <module>
regex symbol search	find-symbol <pattern>
direct production callers	fn-rdeps <module::symbol> --exclude-tests
callers plus test-module importers	fn-rdeps <module::symbol> --exclude-tests, then rdeps <module>
direct imports / callees	fn-deps <module::symbol>
transitive callers / function blast	fn-blast <module::symbol>
broken Sphinx cross-references	xrefs --broken <module>
changed-code blast radius	diff-impact [--base REF]
transitive affected tests / mocks	test-impact <target> · mock-rdeps <target>
pytest fixtures	fixture-rdeps <name> · fixture-graph <test-file>
subprocess relationships	subprocess-deps <module> · subprocess-rdeps <module>
coverage / documentation gaps	coverage <target> · coverage-gap [module] · undocumented [module]

Direct/every/all/production/blast-radius callers → fn-rdeps <module::symbol> --exclude-tests; fn-blast <module::symbol> only for explicit transitive, closure, hops, or all-levels requests.

Test modules directly importing module: use rdeps <module>, then filter/report tests. Reserve test-impact <target> for transitive affected-test selection.

symbol <name> accepts bare function (for example authenticate) or qualified method (for example MyClass.method); module::symbol belongs to fn-* call-graph queries. To chain symbol into fn-*, compose returned module + qualified_name exactly as <module>::<qualified_name>; example mypackage.module::MyClass.method. For feature scaffolding, query requested qualified extension method (for example, symbol MyClass.add_feature), not nearby symbol MyClass or symbols <module> listing unless broader scope requested.

For method changes possibly affecting overrides, use find-symbol '<ClassSuffix>\.<method>$' --exclude-tests --limit 0 for same-name override candidates. Name match discovers candidates, not inheritance; inspect each source to verify ancestry + package boundaries before treating as override.