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.md

GitHub

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 / call-graph analysis has no stable CLI today. Say so and take the fallback: bounded stable queries (e.g. query.callers-of per known seams) + manual inspection + explicit limitation note.
  3. Bundled additive tools — code-fact find-similar-responsibility --scope ROOT --name NAME locates similar responsibilities; code-fact impacted-tests PATH... --root ROOT reports 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 approx confidence; TextSearch (grep) is lexical and reports noisy confidence. 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 is approx, binding-resolved or noisy — and index and coverage say which snapshot it was read from and which files that snapshot covers.
  • reason_code disambiguates live-non-callable from absent inside a capability's own payload (e.g. query.never-wired) — a distinction grep cannot make. Degrade signals — which adapter answered, and its scan-scope honesty — live in the envelope's trace: per-query entries carrying provider_id, event, fault_count and scope.
  • 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".