scip-query 0.10.1 → 0.10.2

package/docs/analyzer-inventory.md

@@ -0,0 +1,162 @@
+# Analyzer Inventory and Action-Tier Review
+
+An analyzer in this project is a query or command-backed program that examines repository evidence such as the SCIP graph, source text, AST profiles, git history, docs, or a diff, and returns a structured answer about code health, change risk, reuse, or navigation.
+
+A finding is an analyzer result that names a concrete codebase location, relationship, or diff condition as worth attention. Its defining role is to turn raw evidence into a maintainer-facing claim.
+
+The useful product split is not the same as evidence quality. Evidence quality says how the claim was obtained: graph fact, semantic provider, source heuristic, change graph, or baseline. Action tier says how strongly the claim justifies a repair without broader product or architecture judgment.
+
+Companion docs:
+
+- `docs/analyzer-validation-protocol.md` defines how to validate true positives, false positives, and false negatives across real repositories.
+- `docs/analyzer-validation-ledger.md` tracks the remaining validation work, run batches, and completion state.
+- `docs/locality-analyzer-design.md` designs the missing code-organization analyzer for extraction placement and shared-folder locality.
+
+The action tiers are:
+
+- Direct repair evidence identifies code or docs that usually need a local action: delete, wire up, finish migration, remove unused surface, break a cycle, or split excessive complexity. Review is still required, but the default next step is action.
+- Contextual signal evidence identifies a pattern that may hide a better design, but the right action depends on ownership, product semantics, locality, naming, or architecture. The default next step is investigation.
+- Support analysis provides facts used by people, agents, or other analyzers, but does not itself assert a smell.
+
+## Current Surfaces
+
+The published query surface lives in `src/queries/public-query-entries.ts`. The CLI command order and families live in `src/runtime/commands/query-command-specs.ts`. The composite health score runs the phases listed in `HEALTH_PHASES` in `src/queries/health/health.ts`. The diff gate runs the checks listed in `DIFF_GATE_CHECKS` in `src/queries/impact/diff-gate.ts`.
+
+`health --json` on this repository currently reports:
+
+- score 100, riskScore 100, hygieneScore 100
+- zero active findings across all health phases
+- 174 suppression comments: 72 extract, 62 wrapper, 17 stale, 15 similar, 8 passthrough
+
+That suppression shape is evidence that broad candidate analyzers have historically produced enough accepted or false-positive results to need explicit maintainer judgment. The suppression lifecycle review confirmed the current source comments are recent and reasoned, while structured file-scoped suppressions now warn when their file path goes stale.
+
+The declared-coupling config has been refreshed after the inventory surfaced old pre-folder-move paths. `config-validate` now warns when a declared-coupling entry names a file that no longer exists, so known maintenance units stay connected to the current file graph instead of silently becoming stale metadata.
+
+## Health-Scored Analyzers
+
+| Analyzer                         | Evidence examined                                                                                                                                                                                                   |                 Current health role | Recommended action tier                                                                              | Evaluation                                                                                                                                                                                                                                                                                                      |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------: | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dead`                           | Production definitions, SCIP/source/caller references, package roots, framework-discovered route/page roots, and entry exclusions                                                                                   |                Risk, graph findings | Direct repair for `dead-code`; contextual for `file-internal`                                        | Strong when `kind === dead-code`: zero references and excluded external-live surfaces make deletion likely. `file-internal` is not direct deletion evidence; it may be private helper ownership.                                                                                                                |
+| `cleanup-plan`                   | `dead --only-dead` seed plus conservative cascade references                                                                                                                                                        | Standalone, not direct health phase | Direct repair                                                                                        | Strongest deletion analyzer. It computes ordered batches and can be compiler-verified from the command layer.                                                                                                                                                                                                   |
+| `isolated`                       | Production callables with no callers and no non-self callees                                                                                                                                                        |                Risk, graph findings | Direct repair                                                                                        | Strong dead-leaf signal. It is stricter than `dead` and usually means remove or wire up.                                                                                                                                                                                                                        |
+| `cycles`                         | File dependency graph, with module-hierarchy/test/barrel/entry cycle classification                                                                                                                                 |                                Risk | Direct repair for `real`; support/noise for `module-hierarchy`                                       | Good split already exists. Real cycles normally need architectural repair. Module-hierarchy cycles should not score.                                                                                                                                                                                            |
+| `similar` / `similarAll`         | Callable callee fingerprints, IDF weighting, source-token fallback                                                                                                                                                  |                             Hygiene | Contextual signal                                                                                    | Similarity is a reuse lead, not proof of duplicate semantics. Needs naming, behavior, signatures, and product intent before action. Shared evidence is now labeled as domain, access/query, framework/generic, mixed, or neutral structural overlap.                                                            |
+| `recent-duplicates`              | `similarAll`, React/Vue duplicate analyzers, git file-age orientation                                                                                                                                               |                  Standalone cleanup | Direct repair for `echo`; contextual for `twin`                                                      | Directionality makes this much stronger than plain similarity. A recent echo usually should reuse/delete. Twins still need choice of owner.                                                                                                                                                                     |
+| `react-component-duplicates`     | JSX structure tokens from React profiles                                                                                                                                                                            |                             Hygiene | Contextual signal                                                                                    | Good UI reuse lead. Needs product semantics and design-system judgment before extracting.                                                                                                                                                                                                                       |
+| `react-hook-candidates`          | Shared React hook/state/effect/request/handler tokens, evidence class, action tier, and recommendation                                                                                                              | Hygiene, with `scoreCount` discount | Contextual signal for domain or mixed behavior; support for generic workflow/shared abstraction rows | Better than raw similarity because behavior tokens are named. The output now separates generic UI workflow and existing shared abstractions from domain behavior, but extraction still needs product judgment.                                                                                                  |
+| `react-large-component-pressure` | Component LOC, file LOC, JSX token count, behavior token count, pressure kind, context, recommendation kind                                                                                                         |                             Hygiene | Direct repair pressure with review direction                                                         | Large component pressure usually implies splitting. It now distinguishes JSX, behavior, file, and route/page pressure, but still does not choose the destination directory for extracted code.                                                                                                                  |
+| `vue-component-duplicates`       | Vue template structure tokens                                                                                                                                                                                       |                             Hygiene | Contextual signal                                                                                    | Same reuse caveat as React component duplicates.                                                                                                                                                                                                                                                                |
+| `vue-composable-candidates`      | Vue composable/store/reactivity/lifecycle/request/function/template tokens, evidence class, action tier, and recommendation                                                                                         | Hygiene, with `scoreCount` discount | Contextual signal for domain or mixed behavior; support for generic workflow/shared abstraction rows | Good extraction lead when domain behavior is present. Generic workflow scaffolding remains visible as support, and extraction still needs domain and locality judgment.                                                                                                                                         |
+| `vue-large-view-pressure`        | SFC total/template/script/style/external-script line counts, pressure kind, context, recommendation kind                                                                                                            |                             Hygiene | Direct repair pressure with review direction                                                         | Usually implies splitting a large view. It now distinguishes template, script, style, external-script, and route/page pressure, but still needs companion directory-locality guidance.                                                                                                                          |
+| `extract-candidates`             | Large callable callee clusters, co-occurrence isolation, extraction kind, action tier, and recommendation                                                                                                           |                             Hygiene | Contextual signal                                                                                    | It finds possible extraction seams, not proof of a new abstraction. The output now distinguishes workflow orchestration from broad/cohesive helper clusters and keeps every row as signal.                                                                                                                      |
+| `wrapper-candidates`             | Small production callables with one real external caller, caller fan-in, and boundary-token evidence                                                                                                                |                             Hygiene | Contextual signal, sometimes direct                                                                  | Single-caller wrappers can be needless indirection, but may also be names, domain/lifecycle boundaries, test seams, or API shaping. Boundary evidence discounts those without hiding them.                                                                                                                      |
+| `passthrough-candidates`         | Small production callables with exactly one callee, literal pass-through body, runtime-boundary evidence, public-facade evidence, action tier, recommendation, and score count                                      | Hygiene, with `scoreCount` discount | Direct when no boundary or public-facade evidence is present; contextual signal when either exists   | Body-shape gate is real. Boundary evidence distinguishes adapter, provider, public, capability, transport, lifecycle, access-policy, and facade-shaped forwarders; public-facade evidence separately identifies package-public or rooted exported passthroughs.                                                 |
+| `stale-abstractions`             | Type-like definitions, real consumers, barrel consumers, transitive reachability, definer usage, confidence, staleness kind, action tier, and recommendation                                                        |                             Hygiene | Direct for unused abstractions; contextual signal for one-consumer ownership rows                    | `0 consumers` is direct repair. `1 consumer` is contextual, including high-confidence misplaced types, because the repair may be move, inline, keep, or document as public contract.                                                                                                                            |
+| `drift`                          | File dep graph, symbol ref graph, semantic/source import usage, explicit or inferred layer policy, sibling patterns, action tier, policy basis, recommendation                                                      |                             Hygiene | Split by kind                                                                                        | `unused-import` is direct repair. Explicit `layer-violation` is direct; inferred layer policy and `pattern-deviation` rows are contextual signal. Pattern deviations remain excluded from health scoring.                                                                                                       |
+| `complexity-hotspots`            | Production callable LOC, fan-in, fan-out, callee count                                                                                                                                                              |                                Risk | Direct repair pressure                                                                               | Complexity pressure usually means refactor, but the current score is structural, not cyclomatic. It should be separate from branch-count complexity.                                                                                                                                                            |
+| `co-change` / hidden coupling    | Git co-change pairs, dependency edges, declared couplings, file noise filters, partner-class labels, declared-coupling suggestions, commit scope, recency context, commit-subject context, and score-weighted count |  Risk, weighted by history strength | Contextual signal                                                                                    | Strong evidence that coordination may be missing, but not proof that extraction or unification is correct. Partner classes, history context, subject context, and score weighting now separate contract-like focused current pairs from broad, stale, or unlabeled history before suggesting declared coupling. |
+| Suppression inventory            | `scip-query: ignore-*` comments in source, plus structured `.scipquery.json` suppressions                                                                                                                           |               Evidence quality axis | Meta signal                                                                                          | Useful precision feedback. High suppressions should reduce trust or weight for that detector family. Structured file-scoped suppressions now validate path freshness.                                                                                                                                           |
+
+## Diff-Gate Checks
+
+| Check                  | Evidence examined                                                                                                                                                                         | Recommended action tier    | Evaluation                                                                                                                                                                                                                                                                                                    |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `echo`                 | Changed symbols compared to established `similar` matches outside the diff                                                                                                                | Direct repair leaning      | More actionable than repo-wide `similar` because it is scoped to new or changed code. Still verify semantics before reuse.                                                                                                                                                                                    |
+| `incomplete-migration` | New helpers in the diff, existing references, leftover established sites with helper-callee containment, site coverage, helper-shape evidence, and migration-scope hints                  | Direct repair              | Strong. It models the exact failure mode of half-finished extraction and gives concrete leftover sites, while rejecting broad old sites where the helper pattern is only a small fragment and labeling possible subtype/variant leftovers for review.                                                         |
+| `co-change-partner`    | Historical partner changed without the other side in current diff, with co-change partner class, commit scope, recency, commit-subject context, and optional declared-coupling suggestion | Contextual signal          | Good sync warning, but sometimes the coupling no longer holds or should be intentionally broken. Partner classes, history context, and subject context make doc/code, config/code, schema/script, model/view, test/code, broad-sweep, stale, docs-labeled, fix-labeled, and issue-ref cases easier to review. |
+| `doc-reference`        | Living docs citing changed files, excluding import-only source changes, with citation kind and Markdown-local cited-claim context                                                         | Split by citation evidence | Behavioral/current doc claims are direct doc-review evidence. Configuration examples and intentional records are support-tier checks unless the cited target changed meaning.                                                                                                                                 |
+| `unused-params`        | Trailing unused params in changed files                                                                                                                                                   | Direct repair              | Conservative enough to be a high-confidence local fix.                                                                                                                                                                                                                                                        |
+| `new-dead`             | Changed production symbols with zero consumers, excluding entry/root/test/framework-discovered cases                                                                                      | Direct repair              | Either wire it up, remove it, or mark it as an externally live root before it lands.                                                                                                                                                                                                                          |
+| `baseline`             | New health finding identity versus committed baseline                                                                                                                                     | Direct gate                | It does not explain the smell itself, but correctly blocks regression until fixed or accepted.                                                                                                                                                                                                                |
+
+## Standalone Cleanup and Similarity Analyzers
+
+| Analyzer              | Evidence examined                                                                                                                              | Recommended action tier                                       | Evaluation                                                                                                                                                                                    |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `unused-params`       | TS/JS AST facts plus identifier usage lines                                                                                                    | Direct repair                                                 | Intentionally conservative: trailing only, simple params only, underscore-intent skipped, external roots skipped. Should be in the direct tier despite heuristic metadata.                    |
+| `unused-imports`      | Source/AST import facts plus local binding usage                                                                                               | Direct repair                                                 | A narrower direct cleanup analyzer. It should stay direct when the imported binding is unused in executable and type surfaces, with framework/compiler caveats handled in `drift` validation. |
+| `redundant-reexports` | Barrel exports, JS/TS re-export statements, SCIP/source fallback consumers, direct importers, package-surface evidence                         | Direct for private barrels; signal for package-public barrels | Strong when the candidate barrel is private and both barrel and direct consumers are zero. Package-public barrels stay visible as signal because external consumers may import through them.  |
+| `similar-files`       | File dependency-profile Jaccard with infrastructure and distinctive-dep gates                                                                  | Contextual signal                                             | Good for copy-paste family discovery, not direct extraction proof.                                                                                                                            |
+| `similar-chains`      | Dependency chain generation, infrastructure filtering, edit distance                                                                           | Contextual signal                                             | Finds duplicated pipelines, but pipeline ownership and abstraction shape require design judgment.                                                                                             |
+| `similar-signatures`  | Semantic/documented/source normalized function signatures                                                                                      | Contextual signal                                             | Same type shape is only a weak lead. Useful for search, not scoring unless combined with behavior evidence.                                                                                   |
+| `convergence`         | Two symbols' shared and unique callees                                                                                                         | Support/contextual signal                                     | It explains a possible consolidation strategy; it should not score by itself.                                                                                                                 |
+| `locality-candidates` | Candidate symbol/file path, directory ancestry, consumer files, consumer coverage, nearest common owner, boundary markers, and counterevidence | Contextual signal                                             | Guides placement and ownership review for extracted or shared code. It is deliberately report-only and should not force moves or affect health score without repair-outcome evidence.         |
+| `doc-drift`           | Living docs, path citations, cited-claim contexts, doc-code co-change, doc intent, action tier, code churn after doc update, broken references | Split by evidence                                             | Broken references are direct repair. Path-cited stale subjects now expose citation context. Co-change-only staleness is signal for current guidance and support for historical notes.         |
+
+## Graph, Risk, and Planning Analyzers
+
+| Analyzer             | Evidence examined                                                                                                                  | Recommended role          | Evaluation                                                                                                                                                          |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `affected`           | Transitive symbol impact from a changed symbol                                                                                     | Support analysis          | Blast-radius map, not smell.                                                                                                                                        |
+| `change-surface`     | Definitions in a file plus external consumer counts                                                                                | Support/risk analysis     | Pre-change risk briefing. Useful for planning and score context, not a repair.                                                                                      |
+| `plan-context`       | Trace, references, call graph, dataflow, deps/rdeps, surface, affected, change-surface, complexity, history                        | Support analysis          | Composite planning bundle. It should not contribute smell score directly.                                                                                           |
+| `bottlenecks`        | Callable fan-in times fan-out, risk kind, action tier, evidence reasons, recommendation                                            | Contextual signal         | Good risk hotspot, not automatic refactor. Output now states `signal` and frames central code as coordination risk rather than repair proof.                        |
+| `hotspots`           | Most referenced symbols                                                                                                            | Support/contextual signal | Identifies choke points. Not a smell alone.                                                                                                                         |
+| `fan-in` / `fan-out` | Reference counts into symbols or out of files                                                                                      | Support analysis          | Raw graph metrics.                                                                                                                                                  |
+| `coupling`           | Shared symbols between two files or top coupled pairs, coupling kind, action tier, evidence reasons, recommendation                | Contextual signal         | May reveal boundary problems, but shared symbols can be intended. Output now makes the coordination-pressure interpretation explicit.                               |
+| `deep-chains`        | Longest dependency chains after SCC condensation, suffix de-duplication, chain kind, action tier, evidence reasons, recommendation | Contextual signal         | Long chains imply propagation risk, but action depends on layers and ownership. Strict suffix duplicates are now removed from top results.                          |
+| `complexity`         | Branch count, cyclomatic estimate, callee count, fan-in, fan-out for one symbol                                                    | Direct repair pressure    | This is closer to the user-specified "cyclomatic complexity" analyzer than `complexity-hotspots`. Should score strongly when branches/cyclomatic exceed thresholds. |
+| `self-audit`         | Cheap evidence paths checked against TypeScript compiler oracle                                                                    | Meta analysis             | Measures analyzer accuracy. Should guide trust/weight, not code health directly.                                                                                    |
+
+## Navigation and Evidence Providers
+
+These commands analyze the index, but they are not finding detectors and should not affect health score directly: `stats`, `files`, `methods`, `refs`, `trace`, `deps`, `rdeps`, `system`, `surface`, `imports`, `imported-by`, `outline`, `members`, `by-kind`, `kind-counts`, `hierarchy`, `call-graph`, `code`, `dataflow`, and `slice`.
+
+They are essential because other analyzers and agents use them to ground claims. Their defining characteristic is retrieval or explanation, not smell detection.
+
+The support-analysis accuracy review confirmed that `refs`, `affected`, `change-surface`, `plan-context`, `imports`, `deps`, `rdeps`, `fan-in`, `fan-out`, `hotspots`, `status`, and `self-audit` return useful source-grounded evidence for a TypeScript target. It also fixed diagnostic parity so `status` and `doctor` use the same root-aware config validation as `config-validate`.
+
+The cross-language boundary review confirmed that Rust projects have graph-backed indexing, source fallback, cleanup detector output, git/diff support, and compiler cleanup verification when `rust-analyzer` and `cargo check` are available. It also confirmed that TypeScript semantic self-audit is explicitly unavailable on Rust and that React/Vue analyzers return stack-specific empty results rather than Rust findings.
+
+`cleanup-apply` is not an analyzer. It is an action command that applies a `cleanup-plan` batch, so it should be validated through the `cleanup-plan --verify` path and normal project checks.
+
+## Overlap and Duplication Review
+
+The codebase already avoids some duplicate analysis by sharing kernels:
+
+- `runCandidateAnalysis` gives candidate-style analyzers one lifecycle for scan limits, preparation, evaluation, ordering, and result caps.
+- `rankedPairwiseProfileResults` gives React, Vue, file-profile, and pairwise similarity analyzers a shared pair-ranking shape.
+- `HEALTH_DETECTOR_PROFILES` keeps health and baseline detector options aligned.
+
+The remaining conceptual overlap is mostly healthy, but needs product labels:
+
+| Overlap family             | Members                                                                                                                              | Same analysis or distinct?                                                                                      | Recommendation                                                                                                                                          |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Deletability               | `dead`, `isolated`, `cleanup-plan`, `redundant-reexports`, `new-dead`                                                                | Distinct evidence scopes over the same core question: can this be removed or must it be wired?                  | Model as one "deletability" action family with subtypes and confidence.                                                                                 |
+| Similarity and reuse       | `similar`, `similar-files`, `similar-chains`, `similar-signatures`, `convergence`, React/Vue duplicates, `recent-duplicates`, `echo` | Distinct evidence bases. The risk is UX confusion, not implementation duplication.                              | Keep separate, but expose basis, action tier, and root-cause groups where pairwise rows repeat.                                                         |
+| Extraction pressure        | `extract-candidates`, React/Vue behavior candidates, large component/view pressure, `incomplete-migration`                           | Different stages: discover seam, detect duplicated behavior, detect excessive size, catch unfinished migration. | Score unfinished migrations higher than discovery leads.                                                                                                |
+| Indirection                | `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`                                                                 | Related but not the same: single caller, literal forwarding, low-consumer types.                                | Passthrough and wrapper rows now split by boundary evidence; stale should split by confidence.                                                          |
+| Architecture/history drift | `drift`, `doc-drift`, `co-change`, `co-change-partner`, `doc-reference`                                                              | Same broad problem of things moving out of sync, but sources differ.                                            | Co-change should remain signal; doc-reference is direct only for behavioral cited claims and support for configuration examples or intentional records. |
+| Graph risk                 | `fan-in`, `fan-out`, `hotspots`, `bottlenecks`, `coupling`, `deep-chains`, `change-surface`, `affected`                              | Mostly layered views of graph pressure.                                                                         | Treat as support/context, except `cycles` and high cyclomatic complexity.                                                                               |
+
+## Score Model Implications
+
+The current report has `riskScore`, `hygieneScore`, evidence labels, `scoreCount`, pressure penalties, validation lift, and suppression inventory. That is close, but it does not encode action implication directly.
+
+Recommended model:
+
+1. Add an action tier to each finding category: `direct`, `signal`, or `support`.
+2. Keep evidence quality separate: `graph-fact`, `semantic`, `heuristic`, `change-graph`, `baseline`.
+3. Score direct findings with heavier base penalties because they usually imply a local repair.
+4. Score signal findings with lighter base penalties and stronger pressure penalties when signals accumulate.
+5. Add a "signal backlog pressure" multiplier when direct findings are near zero but contextual signals remain high. This captures the user's point: a repo with no obvious smells but many unresolved architectural signals is not actually clean.
+6. Let suppression history and `self-audit` validation adjust detector trust. A detector with many suppressions or low validation lift should score less until recalibrated.
+
+Suggested initial tier map:
+
+- Direct: `cleanup-plan`, `dead-code`, `isolated`, `real cycles`, `unused-params`, `new-dead`, `incomplete-migration`, behavioral/current `doc-reference` claims, broken `doc-drift` references, `redundant-reexports` with zero consumers, direct passthrough rows with no boundary or public-facade role, `unused-import` drift, high branch/cyclomatic `complexity`, large React/Vue pressure.
+- Signal: `co-change`, `co-change-partner`, ordinary `similar`, `similar-files`, `similar-chains`, `similar-signatures`, `convergence`, `extract-candidates`, `locality-candidates`, `wrapper-candidates`, `passthrough-candidates` with boundary or public-facade roles, single-consumer `stale-abstractions`, React/Vue duplicate or behavior candidates, bottlenecks, hotspots, coupling, deep chains, inferred layer or pattern drift, doc staleness from churn.
+- Support: navigation commands, `affected`, `change-surface`, `plan-context`, `stats`, `self-audit`, suppression inventory, baseline comparison mechanics, configuration-example and intentional-record `doc-reference` rows.
+
+## Directory Locality Analyzer
+
+`locality-candidates` now evaluates extraction locality after a large component/view or helper extraction. The referents are directories, feature folders, local shared folders, global shared folders, import distances, consumer sets, and abstraction ownership. The analyzer classifies where an extracted unit may belong by comparing actual consumers and directory boundaries.
+
+Command shape:
+
+- `scip-query locality-candidates [symbol-or-file]`
+- Inputs: extracted or candidate symbol/file, consumer files, nearest common ancestor, feature/domain folders, existing shared folders, import path depth, package/workspace boundaries, and whether consumers cross feature boundaries.
+- Outputs: recommended locality level such as same file, sibling folder, feature-local shared folder, app-level shared folder, package-level shared module, or no extraction.
+- Action tier: contextual signal. It guides placement; it should not force moves without architecture judgment.
+
+This should pair with `react-large-component-pressure`, `vue-large-view-pressure`, `extract-candidates`, and `incomplete-migration` so agents do not reduce size scores by dumping extracted pieces into flat local directories.

package/docs/analyzer-validation-ledger.md

@@ -0,0 +1,262 @@
+# Analyzer Validation Ledger
+
+This ledger records the analyzer evaluation work carried out after the analyzer inventory, validation protocol, and locality design. It is the operating document for keeping analyzer accuracy work traceable end to end.
+
+The companion documents are:
+
+- `docs/analyzer-inventory.md`: names the analyzers and their action tiers.
+- `docs/analyzer-validation-protocol.md`: defines the review protocol and per-analyzer TP/FP/FN criteria.
+- `docs/locality-analyzer-design.md`: defines the locality and organization analyzer behavior.
+
+## Source Anchors
+
+The ledger is anchored to the current tool surface, not memory.
+
+| Surface                   | Source                                                                                                                                                                                                                                                                                                       | Why it anchors the ledger                                                                     |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| Repo-wide health analysis | `scip-query code health --json` reported `src/queries/health/health.ts:194`, where `health()` runs `runHealthAnalyses()` and `buildHealthReport()`.                                                                                                                                                          | Every repo-wide analyzer validation must eventually reconcile with health output and scoring. |
+| Change-time gate analysis | `scip-query code diffGate --json` reported `src/queries/impact/diff-gate.ts:94`, where `diffGate()` runs `echo`, `incomplete-migration`, `co-change-partner`, `doc-reference`, `unused-params`, `new-dead`, and `baseline`.                                                                                  | Every diff-only analyzer needs a separate validation path from repo-wide health.              |
+| Public command registry   | `scip-query trace queryCommandOrder --json` reported `src/runtime/commands/query-command-specs.ts:10`, where the public query command order starts. `scip-query code queryCommandDescriptor --json` reported `src/runtime/commands/query-command-specs.ts:94`, where command descriptors are resolved by id. | The ledger must not silently miss a public analyzer command.                                  |
+| Diff-gate check list      | `scip-query trace DIFF_GATE_CHECKS --json` reported `src/queries/impact/diff-gate.ts:27`, where the canonical diff-gate check list is exported.                                                                                                                                                              | The ledger must cover every change-time check that can block a diff.                          |
+
+## Core Concepts
+
+A validation ledger is a maintained record of analyzer evaluation work, including the claim being tested, the repositories used, the evidence captured, the verdict, and the next precision action. Its essential role is to keep validation from dissolving into scattered notes by making every analyzer claim traceable to a reviewed outcome.
+
+A ledger item is one independently completable evaluation obligation. It may cover one analyzer, one analyzer family, one repository run, or one score-model decision; its essential characteristic is that it has a clear done signal and can move from ready to complete without needing the whole validation effort to finish.
+
+A run batch is a bounded execution of analyzer commands against one repository and revision. It is the smallest repeatable field-test unit because it records the project, commit, commands, raw output, sample selection, and reviewer verdicts together.
+
+A calibration decision is a documented change to detector confidence, action tier, score weight, threshold, wording, or evidence fields. It is not just a preference; it is a maintainer decision justified by reviewed true positives, false positives, false negatives, suppressions, or repair outcomes.
+
+A repair outcome is the result of acting on an analyzer finding. It matters because an analyzer can be locally accurate while still causing bad repairs, churn, misplaced abstractions, or broader APIs when an agent follows it.
+
+## Status Values
+
+| Status     | Meaning                                                                            |
+| ---------- | ---------------------------------------------------------------------------------- |
+| `ready`    | The item has a defined scope, command set, corpus, and done signal.                |
+| `running`  | Raw analyzer output or human review is currently being collected.                  |
+| `blocked`  | The item cannot be completed until tooling, indexing, or corpus access improves.   |
+| `complete` | The item has reviewed evidence, verdicts, and any next precision actions recorded. |
+| `deferred` | The item is valid but intentionally lower priority than other ledger work.         |
+
+## Active Ledger
+
+Closeout status: all active ledger rows are complete as of 2026-06-22. Remaining future work is provider- or corpus-gated, not an unfinished validation slice: true co-change issue/PR label ingestion needs a repository metadata provider, and locality score integration needs stronger consumer-coverage plus repair-outcome evidence.
+
+| ID      | Item                                   | Scope                                                                                                                                                                                  | Status     | Next action                                                                               | Done signal                                                                                              |
+| ------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| AVL-001 | Field evaluation baseline              | Run the protocol on `scip-query`, `Stable_Management`, `Vega_2.0`, and `SynthRunnerRust`.                                                                                              | `complete` | Completed in `docs/validation/2026-06-21-second-repo-confirmation.md`.                    | A dated run summary exists for each repo with raw-output locations and sampling notes.                   |
+| AVL-002 | Direct repair analyzer verdicts        | `cleanup-plan`, `dead`, `new-dead`, `isolated`, `unused-params`, `unused-imports`, `redundant-reexports`, `passthrough-candidates`, `cycles`, broken `doc-drift`, and `doc-reference`. | `complete` | Completed in `docs/validation/2026-06-21-direct-deletion-family-closure-result.md`.       | Each direct analyzer has TP/FP/FN counts, accepted-design examples, and precision actions.               |
+| AVL-003 | Contextual signal analyzer verdicts    | Similarity, extraction, locality, wrapper, stale abstraction, frontend duplicate, hook/composable, co-change, bottleneck, coupling, drift, and deep-chain families.                    | `complete` | Completed in `docs/validation/2026-06-21-contextual-signal-closure-result.md`.            | Each contextual family has a reviewed precision note and a score-weight recommendation.                  |
+| AVL-004 | Support analysis accuracy              | `affected`, `change-surface`, `plan-context`, navigation commands, graph metrics, and `self-audit`.                                                                                    | `complete` | Completed in `docs/validation/2026-06-21-support-analysis-accuracy-result.md`.            | Support commands have referential-accuracy notes and known unsupported cases.                            |
+| AVL-005 | Analyzer implementation parity         | Confirm each public analyzer command's documented behavior matches implementation behavior.                                                                                            | `complete` | Completed in `docs/validation/2026-06-21-analyzer-implementation-parity-result.md`.       | The inventory and protocol either match implementation or list required doc/code corrections.            |
+| AVL-006 | Score calibration                      | Evaluate direct findings, contextual signals, suppressions, validation ratio, and signal backlog pressure.                                                                             | `complete` | Completed in `docs/validation/2026-06-21-score-calibration-finalization-result.md`.       | A calibration memo states score-weight changes, accepted current weights, or blocked evidence gaps.      |
+| AVL-007 | Output and schema quality              | Verify each analyzer emits enough structured evidence for users and agents to review the claim.                                                                                        | `complete` | Completed in `docs/validation/2026-06-21-output-schema-quality-finalization-result.md`.   | Each analyzer family has an output-quality verdict and missing-field list.                               |
+| AVL-008 | Performance and budget behavior        | Check large-index behavior, `--full`, scan limits, git-history bounds, and graceful degradation.                                                                                       | `complete` | Completed in `docs/validation/2026-06-21-performance-budget-behavior-result.md`.          | Budget behavior is documented with any timeout, cap, or misleading-empty-output issues.                  |
+| AVL-009 | Suppression lifecycle                  | Evaluate whether suppressions are stale, justified, expired, or useful as detector precision feedback.                                                                                 | `complete` | Completed in `docs/validation/2026-06-21-suppression-lifecycle-result.md`.                | Suppression categories have counts, stale examples, and trust-weight recommendations.                    |
+| AVL-010 | Cross-language capability boundaries   | Establish what works for TypeScript, React, Vue, Rust, and any unsupported language surfaces.                                                                                          | `complete` | Completed in `docs/validation/2026-06-21-cross-language-capability-boundaries-result.md`. | Capability notes distinguish "no findings" from "not supported by current evidence."                     |
+| AVL-011 | Agent repair outcomes                  | Test whether acting on analyzer findings produces better code rather than churn or misplaced abstraction.                                                                              | `complete` | Completed in `docs/validation/2026-06-21-agent-repair-outcomes-result.md`.                | Each action tier has at least one reviewed repair outcome or an explicit reason it cannot be tested yet. |
+| AVL-012 | Locality analyzer validation           | Validate the proposed `locality-candidates` report and `scip-locality-review` skill workflow before implementation.                                                                    | `complete` | Completed in `docs/validation/2026-06-21-locality-analyzer-validation-result.md`.         | The locality design has TP/FP/FN-style examples and a go/no-go recommendation for implementation.        |
+| AVL-013 | Config and declared-coupling freshness | Check whether `.scipquery.json` declared couplings and suppressions still point at current paths.                                                                                      | `complete` | Completed in `docs/validation/2026-06-21-config-declared-coupling-freshness-result.md`.   | Stale config paths are fixed, removed, or documented as intentionally retained.                          |
+| AVL-014 | Public command surface coverage        | Ensure every public analyzer command is present in the inventory, protocol, and ledger.                                                                                                | `complete` | Completed in `docs/validation/2026-06-21-public-command-surface-coverage-result.md`.      | A coverage checklist shows no missing analyzer or marks non-analyzer support commands separately.        |
+
+## Public Command Coverage Checklist
+
+The canonical source is `src/runtime/commands/query-command-specs.ts:10-73`, where `queryCommandOrder` lists the public query command surface.
+
+- Core and navigation support: `stats`, `files`, `methods`, `refs`, `trace`, `deps`, `rdeps`, `system`, `surface`, `imports`, `imported-by`, `outline`, `members`, `by-kind`, `kind-counts`, `hierarchy`, `call-graph`, `code`, `dataflow`, `slice`
+- Direct cleanup and deletion analyzers: `dead`, `isolated`, `unused-imports`, `cleanup-plan`, `unused-params`, `passthrough-candidates`, `redundant-reexports`
+- Similarity, reuse, extraction, and locality analyzers: `similar`, `similar-files`, `similar-chains`, `similar-signatures`, `recent-duplicates`, `extract-candidates`, `locality-candidates`, `wrapper-candidates`, `stale-abstractions`, `doc-drift`, `drift`, `convergence`
+- Frontend analyzers: `react-component-duplicates`, `react-hook-candidates`, `react-large-component-pressure`, `vue-component-duplicates`, `vue-composable-candidates`, `vue-large-view-pressure`
+- Graph, risk, and complexity analyzers: `hotspots`, `fan-in`, `fan-out`, `coupling`, `cycles`, `bottlenecks`, `deep-chains`, `complexity-hotspots`, `complexity`
+- Diff, impact, and planning analyzers: `affected`, `change-surface`, `co-change`, `diff-gate`, `incomplete-migration`, `plan-context`
+- Meta and action commands: `self-audit`, `cleanup-apply`
+
+## Completed Run Batches
+
+The completed effort used this order so early runs created useful evidence for later calibration work.
+
+Current pilot:
+
+- Plan: `docs/plans/2026-06-21-analyzer-validation-pilot.md`
+- Summary: `docs/validation/2026-06-21-analyzer-validation-pilot.md`
+- Verdict review: `docs/validation/2026-06-21-analyzer-verdict-review.md`
+- Calibration memo: `docs/validation/2026-06-21-analyzer-calibration-memo.md`
+- Precision implementation plan: `docs/plans/2026-06-21-analyzer-precision-implementation.md`
+- Precision implementation result: `docs/validation/2026-06-21-analyzer-precision-implementation-result.md`
+- Stable_Management second confirmation: `docs/validation/2026-06-21-stable-management-second-confirmation.md`
+- Echo tier refinement result: `docs/validation/2026-06-21-echo-tier-refinement-result.md`
+- Wrapper boundary evidence result: `docs/validation/2026-06-21-wrapper-boundary-evidence-result.md`
+- Passthrough boundary evidence result: `docs/validation/2026-06-22-passthrough-boundary-evidence-result.md`
+- Passthrough public-facade caveats result: `docs/validation/2026-06-22-passthrough-public-facade-caveats-result.md`
+- Public surface caveats result: `docs/validation/2026-06-22-public-surface-caveats-result.md`
+- Doc cited-claim metadata result: `docs/validation/2026-06-22-doc-cited-claim-metadata-result.md`
+- Root-cause grouping result: `docs/validation/2026-06-22-root-cause-grouping-result.md`
+- Co-change partner labels result: `docs/validation/2026-06-22-co-change-partner-labels-result.md`
+- Incomplete migration containment result: `docs/validation/2026-06-22-incomplete-migration-containment-result.md`
+- Co-change recency and broad-sweep context result: `docs/validation/2026-06-22-co-change-recency-sweep-result.md`
+- Doc drift historical intent result: `docs/validation/2026-06-22-doc-drift-historical-intent-result.md`
+- Framework entry caveats result: `docs/validation/2026-06-22-framework-entry-caveats-result.md`
+- Incomplete migration scope hints result: `docs/validation/2026-06-22-incomplete-migration-scope-hints-result.md`
+- Doc reference citation parser result: `docs/validation/2026-06-22-doc-reference-citation-parser-result.md`
+- Co-change subject context result: `docs/validation/2026-06-22-co-change-subject-context-result.md`
+- Second-corpus score-weight confirmation result: `docs/validation/2026-06-22-second-corpus-score-weight-confirmation-result.md`
+- Passthrough exported-facade second-corpus result: `docs/validation/2026-06-22-passthrough-exported-facade-second-corpus-result.md`
+- Incomplete migration second-corpus scope result: `docs/validation/2026-06-22-incomplete-migration-second-corpus-scope-result.md`
+- Doc parser second-corpus validation result: `docs/validation/2026-06-22-doc-parser-second-corpus-validation-result.md`
+- Validation ledger closeout result: `docs/validation/2026-06-22-validation-ledger-closeout-result.md`
+- Global install cross-verification result: `docs/validation/2026-06-22-global-install-cross-verification-result.md`
+- Stable Management locality suggested-home review: `docs/validation/2026-06-22-stable-management-locality-suggested-home-review.md`
+- Locality positive suggested-home result: `docs/validation/2026-06-22-locality-positive-suggested-home-result.md`
+- Stable_Management wrapper confirmation: `docs/validation/2026-06-21-stable-management-wrapper-boundary-confirmation.md`
+- Vue pressure-kind output result: `docs/validation/2026-06-21-vue-pressure-kind-output-result.md`
+- Similarity evidence split result: `docs/validation/2026-06-21-similarity-evidence-split-result.md`
+- Doc citation-kind output result: `docs/validation/2026-06-21-doc-citation-kind-output-result.md`
+- Baseline metadata inheritance result: `docs/validation/2026-06-21-baseline-metadata-inheritance-result.md`
+- Second-repo confirmation: `docs/validation/2026-06-21-second-repo-confirmation.md`
+- Rust wrapper and React pressure review: `docs/validation/2026-06-21-rust-wrapper-react-pressure-review.md`
+- React pressure-kind output result: `docs/validation/2026-06-21-react-pressure-kind-output-result.md`
+- Rust wrapper boundary vocabulary result: `docs/validation/2026-06-21-rust-wrapper-boundary-vocabulary-result.md`
+- Frontend behavior evidence classification result: `docs/validation/2026-06-21-frontend-behavior-evidence-classification-result.md`
+- Extract candidate evidence classification result: `docs/validation/2026-06-21-extract-candidate-evidence-classification-result.md`
+- Stale abstraction action-tier result: `docs/validation/2026-06-21-stale-abstraction-action-tier-result.md`
+- Health score action-tier counts result: `docs/validation/2026-06-21-health-score-action-tier-counts-result.md`
+- Graph-risk family result: `docs/validation/2026-06-21-graph-risk-family-result.md`
+- Config declared-coupling freshness result: `docs/validation/2026-06-21-config-declared-coupling-freshness-result.md`
+- Suppression lifecycle result: `docs/validation/2026-06-21-suppression-lifecycle-result.md`
+- Support analysis accuracy result: `docs/validation/2026-06-21-support-analysis-accuracy-result.md`
+- Cross-language capability boundaries result: `docs/validation/2026-06-21-cross-language-capability-boundaries-result.md`
+- Public command surface coverage result: `docs/validation/2026-06-21-public-command-surface-coverage-result.md`
+- Analyzer implementation parity result: `docs/validation/2026-06-21-analyzer-implementation-parity-result.md`
+- Performance and budget behavior result: `docs/validation/2026-06-21-performance-budget-behavior-result.md`
+- Agent repair outcomes result: `docs/validation/2026-06-21-agent-repair-outcomes-result.md`
+- Locality analyzer validation result: `docs/validation/2026-06-21-locality-analyzer-validation-result.md`
+- Direct small analyzer verdicts result: `docs/validation/2026-06-21-direct-small-analyzer-verdicts-result.md`
+- Direct remaining verdicts result: `docs/validation/2026-06-21-direct-remaining-verdicts-result.md`
+- Direct deletion-family closure result: `docs/validation/2026-06-21-direct-deletion-family-closure-result.md`
+- Contextual signal closure result: `docs/validation/2026-06-21-contextual-signal-closure-result.md`
+- Score calibration finalization result: `docs/validation/2026-06-21-score-calibration-finalization-result.md`
+- Output/schema quality finalization result: `docs/validation/2026-06-21-output-schema-quality-finalization-result.md`
+- Raw output root: `/tmp/scip-query-validation/2026-06-21-pilot`
+
+### Batch 1: Corpus Baseline
+
+- Repositories: `scip-query`, `Stable_Management`, `Vega_2.0`, `SynthRunnerRust`.
+- Commands:
+  - `git rev-parse HEAD`
+  - `scip-query reindex`
+  - `scip-query health --full --json`
+  - `scip-query diff-gate --json`
+  - `scip-query capability-matrix`
+- Outputs:
+  - Raw JSON outside the repo unless intentionally promoted.
+  - Plain text output when a command does not expose `--json`.
+  - Summary in `docs/validation/YYYY-MM-DD-corpus-baseline.md`.
+
+### Batch 2: Direct Repair Families
+
+- Commands:
+  - `scip-query cleanup-plan --json`
+  - `scip-query dead --only-dead --json`
+  - `scip-query isolated --json`
+  - `scip-query unused-params --json`
+  - `scip-query redundant-reexports`
+  - `scip-query passthrough-candidates --json`
+  - `scip-query cycles --json`
+  - `scip-query doc-drift --json`
+- Review:
+  - Top 10 findings, 5 threshold-edge findings, and 5 false-negative probes where possible.
+  - Classify as `tp`, `fp`, `accepted_design`, `needs_judgment`, or `fn`.
+
+### Batch 3: Contextual Signal Families
+
+- Commands:
+  - `scip-query similar --json`
+  - `scip-query similar-files --json`
+  - `scip-query similar-chains --json`
+  - `scip-query similar-signatures --json`
+  - `scip-query recent-duplicates --json`
+  - `scip-query extract-candidates --json`
+  - `scip-query wrapper-candidates --json`
+  - `scip-query stale-abstractions --json`
+  - `scip-query co-change --json`
+  - `scip-query bottlenecks --json`
+  - `scip-query coupling --json`
+  - `scip-query deep-chains --json`
+  - `scip-query drift --json`
+- Review:
+  - Separate "true signal" from "direct repair."
+  - Record what product or architecture judgment was needed.
+
+### Batch 4: Frontend-Specific Families
+
+- React corpus: `Vega_2.0`.
+- Vue corpus: `Stable_Management`.
+- Commands:
+  - `scip-query react-component-duplicates --full --json`
+  - `scip-query react-hook-candidates --full --json`
+  - `scip-query react-large-component-pressure --full --json`
+  - `scip-query vue-component-duplicates --full --json`
+  - `scip-query vue-composable-candidates --full --json`
+  - `scip-query vue-large-view-pressure --full --json`
+- Review:
+  - Validate whether findings imply component extraction, hook/composable extraction, locality repair, or only investigation.
+
+### Batch 5: Evidence Providers and Agent Outcomes
+
+- Commands:
+  - `scip-query plan-context <target> --full --json`
+  - `scip-query change-surface <file> --json`
+  - `scip-query affected <symbol> --json`
+  - `scip-query refs <symbol> --json`
+  - `scip-query imports <file> --json`
+  - `scip-query rdeps <file>`
+  - `scip-query self-audit --samples 100 --json`
+- Review:
+  - Confirm reference accuracy.
+  - Pick a small number of analyzer findings and record whether an agent could repair them cleanly.
+
+## Verdict Record Template
+
+```json
+{
+  "ledgerId": "AVL-002",
+  "repo": "scip-query",
+  "revision": "COMMIT",
+  "command": "dead --only-dead --json",
+  "findingId": "stable id or pasted summary",
+  "location": "src/path/file.ts:10",
+  "verdict": "tp | fp | accepted_design | needs_judgment | fn",
+  "actionTier": "direct | signal | support",
+  "evidence": ["facts that support the verdict"],
+  "counterevidence": ["facts that weaken the analyzer claim"],
+  "repairOutcome": "not_attempted | improved | churn | bad_abstraction | blocked",
+  "precisionAction": "none | parser | root_detection | threshold | score_weight | output_schema | docs | tests",
+  "notes": "short reviewer note"
+}
+```
+
+## Update Rules
+
+When a run batch completes:
+
+1. Update the relevant `AVL-*` rows from `ready` or `running` to `complete`, `blocked`, or `deferred`.
+2. Add a dated summary under `docs/validation/` when the result is worth retaining.
+3. Keep raw JSON out of the repo unless it is small and useful as a fixture.
+4. Turn precision actions into implementation issues or a concrete implementation plan.
+5. If a finding changes an action tier or score-weight recommendation, update `docs/analyzer-inventory.md` and `docs/analyzer-validation-protocol.md`.
+
+## Initial End-to-End Slice
+
+The first concrete run was intentionally narrow:
+
+1. Run Batch 1 on `scip-query` and `Stable_Management`.
+2. Run Batch 2 only for `dead`, `unused-params`, `passthrough-candidates`, and `doc-drift`.
+3. Run Batch 3 only for `similar`, `wrapper-candidates`, and `co-change`.
+4. Run Batch 4 only for Vue on `Stable_Management`.
+5. Record at least 30 reviewed verdicts.
+6. Produce one calibration memo that says whether the current direct/signal/support split still holds.
+
+That slice tested the ledger, the protocol, the review burden, and the score model before the later completion passes covered the remaining analyzer families.