nw-code-analysis-port
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,
SKILL.mdnWave/skills/nw-code-analysis-port/SKILL.md
GitHubnw-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
approxconfidence (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
noisyanswer presented as fact is the failure mode this skill exists to prevent. - The CLI's
tracearray 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:
indexis{ "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).coverageis{ 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
missingorstaleis non-empty, the CLI prints{ "resolution": "indeterminate", uncovered, index, coverage, trace }and exits 1.uncoveredis exactlymissingplusstale. 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) orindeterminate(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:
- Stable-core queries — use
code-fact query.<capability>with the exact form above.- The CLI parses JSON and emits it; consume the
provider,confidence, andpayloadfields. - Inspect
tracefor the answering provider + scan-scope honesty (AST unavailable → TextSearch fallback).
- The CLI parses JSON and emits it; consume the
- Beyond the five capabilities — feature-level change-scope / call-graph analysis has no stable CLI today.
Say so and take the fallback: bounded stable queries (e.g.
query.callers-ofper known seams) + manual inspection + explicit limitation note. - Bundled additive tools —
code-fact find-similar-responsibility --scope ROOT --name NAMElocates similar responsibilities;code-fact impacted-tests PATH... --root ROOTreports test reach. Neither requires selecting an external provider.
Tag every answer with provider + confidence (approx | binding-resolved | noisy). Defaulting to grep/Read for a structural fact (callers/reads/never-wired/atoms) is the anti-pattern this skill exists to prevent — CLI first, grep last.
WHY through the CLI, not grep
- Structural vs lexical. AST is structural and reports
approxconfidence; TextSearch (grep) is lexical and reportsnoisyconfidence. grep over-reports (same-named symbols, comments, strings) and under-reports (dynamic/indirect refs). - Confidence is carried, not assumed. Every answer comes back in a
{provider, confidence, payload, index, coverage, trace}envelope. The confidence label is the honesty signal — a consumer can see whether a fact isapprox,binding-resolvedornoisy— andindexandcoveragesay which snapshot it was read from and which files that snapshot covers. reason_codedisambiguateslive-non-callablefromabsentinside a capability's ownpayload(e.g.query.never-wired) — a distinction grep cannot make. Degrade signals — which adapter answered, and its scan-scope honesty — live in the envelope'strace: per-query entries carryingprovider_id,event,fault_countandscope.- One seam, no per-task
import ast. Re-deriving a fact through one honest provider beats each agent hand-rolling its own search.
Implementation ownership
src/codefact/model.py owns the envelope and the provider port: each provider record declares its id, a cover function returning an answer capability, stale coverage or a pass, and an answer function returning a reply or fault. src/codefact/fold.py owns resolution over the single provider tuple composed in src/codefact/shell/cli.py. Each provider reads immutable snapshots. The index-backed provider admits an index only when its pairing record contains exactly graph_sha256 and manifest_sha256, matching the bytes read. Filesystem and refresh effects belong only to src/codefact/shell/. The public wheel binds only the AST and text-search providers: answers name their provider and carry approx or noisy confidence. It binds no code index, so refresh refuses with a reason explaining that there is nothing to regenerate and queries answer from live sources.
Scope note
This complements — it does NOT replace — reading the code and tests. Use the port to LOCATE facts (callers, definitions, references, atoms) precisely; then read the located code to understand it. The port answers "where / who / what", not "is this correct".