/nw-code-analysis-port

name: nw-code-analysis-port
description: "KNOWLEDGE — resolve code facts (who-calls-X / where-defined-or-read / call-graph / change-scope / file-atoms) through the vendor-neutral CLI `code-fact`, degrading LOUD through bundled adapters (AST, TextSearch). Trigger: any time an agent designs, writes, analyzes, or reviews code or tests and needs a structural code fact."
user-invocable: false

nw-code-analysis-port (KNOWLEDGE)

**Kind**: KNOWLEDGE (reference / discipline). Consulted whenever you need a fact about code. No forced sequence — load it, obey the resolution rule.

TRIGGER

Any time you design, write, analyze, or review code or tests and need a code fact — who calls X, where Y is defined or read, the call graph, the blast-radius of a change, or what a file contains — resolve it **through the vendor-neutral `code-fact` CLI**, not ad-hoc grep.

Public CLI — available now

The five-capability public stable core is wrapped in the production CLI:

code-fact query.callers-of SYMBOL --root ROOT
code-fact query.reads-of SYMBOL --root ROOT
code-fact query.never-wired SYMBOL --root ROOT
code-fact query.atoms-in-file --root FILE_OR_ROOT
code-fact query.adr-section ANCHOR --root ROOT

The CLI returns JSON: `{ provider, confidence, payload, index, coverage, trace }`. Agents consume that envelope and degrade LOUD; they never probe/install/select an analyzer themselves. `code-fact refresh --root ROOT` is the one explicit way to regenerate the index (see "Index snapshot, coverage and refresh").

The resolution rule (one order, every time)

The CLI delegates to the best available bundled adapter. You report the answer tagged with which adapter answered.

The chain is walked top-down, highest declared precision first; the first provider covering the capability answers. The query's `trace` names the answering provider and scope. Do not duplicate a provider ranking in prose or infer precision from a familiar module name. What is stable, and all a consumer needs:

• AST gives `approx` confidence (structural, per-language) on any parseable target.
• grep / lexical search is the **last resort**, never the default. Reach for it only when AST cannot answer.

DEGRADE-LOUD (never silent)

• Always state which adapter answered and at what confidence: `approx` | `binding-resolved` | `noisy`.
• If the answer came from **TextSearch (grep)**, announce the degradation AND its limits. Example: "AST unavailable → grep fallback (`noisy`): may include false positives, miss dynamic/indirect references, and conflate same-named symbols."
• Never silently let grep stand in for the port. A `noisy` answer presented as fact is the failure mode this skill exists to prevent.
• The CLI's `trace` array names which provider answered and its scan-scope honesty (`complete` | `filtered` | `unfiltered`) — that per-query record is the loud announcement a gate reads.

Operations quick-reference (question → CLI command)

| Code fact you need | CLI command | Stable | |--------------------|-------------|--------| | Who calls X? | `code-fact query.callers-of SYMBOL --root ROOT` | yes | | Where is Y read / referenced? | `code-fact query.reads-of SYMBOL --root ROOT` | yes | | Is this symbol defined-but-never-wired/used? | `code-fact query.never-wired SYMBOL --root ROOT` | yes | | What atoms (defs/symbols) does this file contain? | `code-fact query.atoms-in-file --root FILE_OR_ROOT` | yes | | What does an ADR / design-prose section say? | `code-fact query.adr-section ANCHOR --root ROOT` | yes | | Call graph / change-scope / scope-delta | **unsupported by stable CLI** — use bounded stable queries + manual inspection with explicit limitation note | no |

The five stable-core capabilities answer on any UTF-8 repository, including repositories without Python: textsearch supplies the lexical floor at `noisy` confidence. A capability with no covering adapter returns no answer (none faked), records the honest failure in `trace`, and the work proceeds — do NOT substitute grep and call it the same fact.

Index snapshot, coverage and refresh

A query never writes a file and never regenerates anything. Every answer states where it was read from and what that source covers:

• `index` is `{ "kind": "present", graph_sha256, manifest_sha256, indexed_files }` when a paired code index answered, or `{ "kind": "live-source" }` when the answer was read from live sources (no index, or an index no refresh has paired).
• `coverage` is `{ missing, stale, empty_unindexed }`: non-empty files in scope the index never recorded, files whose recorded modification time differs from the live one, and 0-byte files absent from the index. The lists are complete and sorted, matched by exact path (never by a shared file name). An empty unindexed file is reported but never makes an answer indeterminate.
• When the index claims a capability and `missing` or `stale` is non-empty, the CLI prints `{ "resolution": "indeterminate", uncovered, index, coverage, trace }` and exits 1. `uncovered` is exactly `missing` plus `stale`. No lower tier answers in its place. Do NOT treat it as an answer, and do NOT treat an empty result as "none": say which files are uncovered.
• To regenerate the index, run `code-fact refresh --root ROOT`. It prints `{ "refresh": "refreshed", index, coverage }` and exits 0; `refused` (index unchanged) or `indeterminate` (naming the changed index files) exit 1 with a reason. It is the only command that regenerates, it needs the indexing tool on PATH, and refuses without it.

Invocation — how to use the CLI

For ANY structural code fact, call the CLI directly:

1. **Stable-core queries** — use `code-fact query.<capability>` with the exact form above.

• The CLI parses JSON and emits it; consume the `provider`, `confidence`, and `payload` fields.
• Inspect `trace` for the answering provider + scan-scope honesty (AST unavailable → TextSearch fallback).

2. **Beyond the five capabilities** — feature-level change-scope / ca