scip-query 0.1.0 → 0.2.1

package/dist/reindex-worker.js

@@ -1,9 +1,11 @@
 import {
+  describeIndexerBinary,
   isBinaryAvailable,
   isIndexerInstalled,
+  resolveIndexerBinary,
   tryInstallIndexer,
   tryInstallScipCli
-} from "./chunk-DVWGWHFW.js";
+} from "./chunk-NG5F43OU.js";
 
 // src/reindex/index.ts
 import { execFileSync } from "child_process";
@@ -140,9 +142,10 @@ var INDEXER_CONFIGS = {
   python: {
     language: "python",
     indexerBinary: "scip-python",
+    binaryAliases: ["scip-python-plus"],
     checkCommand: "scip-python --version",
-    indexArgs: ({ outputPath }) => ({
-      binary: "scip-python",
+    indexArgs: ({ outputPath, indexerBinary }) => ({
+      binary: indexerBinary,
       args: ["index", "--output", outputPath, "--project-name", "project"]
     }),
     markerFiles: ["pyproject.toml", "setup.py"],
@@ -285,26 +288,35 @@ async function reindex(opts) {
   };
   for (const lang of languages2) {
     const config = getIndexerConfig(lang);
+    const binaryLabel = describeIndexerBinary(config);
     if (!isIndexerInstalled(config)) {
       if (skipAutoInstall) {
         throw new Error(
-          `${config.indexerBinary} is required to index ${lang} but not found on PATH.
-` + (config.installUrl ? `Install from: ${config.installUrl}` : `Make sure ${config.indexerBinary} is installed and available on PATH.`)
+          `${binaryLabel} is required to index ${lang} but not found on PATH.
+` + (config.installUrl ? `Install from: ${config.installUrl}` : `Make sure ${binaryLabel} is installed and available on PATH.`)
         );
       }
-      onStatus(`${config.indexerBinary} not found. Attempting auto-install...`);
+      onStatus(`${binaryLabel} not found. Attempting auto-install...`);
       if (!tryInstallIndexer(config, onStatus)) {
         throw new Error(
-          `${config.indexerBinary} is required to index ${lang} but could not be installed.
-` + (config.installUrl ? `Install manually from: ${config.installUrl}` : `Make sure ${config.indexerBinary} is installed and available on PATH.`)
+          `${binaryLabel} is required to index ${lang} but could not be installed.
+` + (config.installUrl ? `Install manually from: ${config.installUrl}` : `Make sure ${binaryLabel} is installed and available on PATH.`)
         );
       }
     }
-    onStatus(`Indexing ${lang} with ${config.indexerBinary}...`);
+    const resolvedBinary = resolveIndexerBinary(config);
+    if (!resolvedBinary) {
+      throw new Error(
+        `${binaryLabel} is required to index ${lang} but was not found on PATH after installation checks.
+` + (config.installUrl ? `Install manually from: ${config.installUrl}` : `Make sure ${binaryLabel} is installed and available on PATH.`)
+      );
+    }
+    onStatus(`Indexing ${lang} with ${resolvedBinary}...`);
     const { binary, args } = config.indexArgs({
       projectRoot: projectRoot2,
       outputPath: outputScip2,
-      pnpmWorkspaces: opts.pnpmWorkspaces
+      pnpmWorkspaces: opts.pnpmWorkspaces,
+      indexerBinary: resolvedBinary
     });
     try {
       execFileSync(binary, args, {
@@ -316,8 +328,8 @@ async function reindex(opts) {
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       throw new Error(
-        `Failed to index ${lang} with ${config.indexerBinary}: ${msg}
-Make sure ${config.indexerBinary} is installed and available on PATH.`
+        `Failed to index ${lang} with ${resolvedBinary}: ${msg}
+Make sure ${binaryLabel} is installed and available on PATH.`
       );
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scip-query",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Language-agnostic code intelligence CLI powered by SCIP indexes",
   "type": "module",
   "main": "dist/index.js",
@@ -8,6 +8,11 @@
   "bin": {
     "scip-query": "dist/cli.js"
   },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "skills/**/SKILL.md"
+  ],
   "sideEffects": false,
   "exports": {
     ".": {

package/IMPROVEMENTS.md

@@ -1,143 +0,0 @@
-# Improvement Opportunities
-
-Self-audit of the scip-query codebase using its own analysis tools. Each finding includes the command that surfaced it, what it means, and what the fix looks like.
-
----
-
-## 1. Replace 26 inline `symbolNoise` filters with `db.symbolNoise`
-
-**Found by:** `grep` on `similar` output (78-80% callee overlap driven by shared SQL boilerplate)
-
-**Problem:** The fragment `AND gs.symbol NOT LIKE '%typeLiteral%'` appears 26 times across 16 query files. The companion `AND gs.symbol NOT LIKE '%().(%'` appears in most of those too. `db.symbolNoise` was added as a reusable getter but never wired in.
-
-**Files affected:**
-- `bottlenecks.ts`, `by-kind.ts`, `call-graph.ts` (3 occurrences), `dead.ts`, `doc-coverage.ts` (3), `extract-candidates.ts` (2), `fan.ts`, `hotspots.ts`, `isolated.ts`, `members.ts`, `methods.ts`, `outline.ts`, `similar.ts` (4), `symbols.ts`, `system.ts`, `test-coverage.ts` (2), `trace.ts` (2)
-
-**Fix:** Replace each inline `AND gs.symbol NOT LIKE '%typeLiteral%' AND gs.symbol NOT LIKE '%().(%'` with `AND ${db.symbolNoise}` (or a string interpolation of the getter). This cuts ~50 lines and ensures the noise filter is defined in one place — if we need to add a new pattern (e.g., filtering out synthetic generics), it changes in one spot.
-
----
-
-## 2. Replace 32 inline `node_modules` exclusions with `db.pathExclusions`
-
-**Found by:** `grep` on `similar-files` output (100% dep-profile similarity across all query modules)
-
-**Problem:** `d.relative_path NOT LIKE 'node_modules/%'` appears 32 times across 18 files. Often paired with `.git/%` exclusions. The `db.pathExclusions` getter exists but isn't used.
-
-**Files affected:** Every query file.
-
-**Fix:** Same pattern as #1 — interpolate `${db.pathExclusions}` where applicable. Some queries use different table aliases (`def_d`, `ref_d`, `d1`, `d2`) so the getter may need a parameter for the alias, or we add alias-specific variants.
-
----
-
-## 3. Extract shared `buildFileDepGraph()` helper
-
-**Found by:** `similar-chains`, `cycles`, `deep-chains`, `similar-files` all contain identical graph-building SQL
-
-**Problem:** Four query modules build the exact same file dependency graph:
-- `cycles.ts:17-35`
-- `deep-chains.ts:16-34`
-- `similar-chains.ts:125-143`
-- `similar-files.ts:66-84`
-
-Each runs this ~18-line SQL query, builds a `Map<string, Set<string>>` adjacency list, and filters by gitignore. The code is identical except for the `scopeFilter` variable name.
-
-**Fix:** Extract a shared `buildFileDepGraph(db, scope?)` helper that returns a `Map<string, Set<string>>`. All four modules import and call it. Saves ~54 lines and ensures graph-building logic stays consistent (e.g., if we later add `.d.ts` exclusions, it changes in one place).
-
----
-
-## 4. Extract shared test-file pattern constants
-
-**Found by:** `grep` on test-pattern strings
-
-**Problem:** Test file path patterns (`%/__tests__/%`, `%.test.%`, `%.spec.%`, etc.) are defined:
-- As an array in `test-coverage.ts:7-16`
-- As individual SQL fragments in `dead.ts:34-37`
-- As individual SQL fragments in `isolated.ts:35-37`
-
-Three different representations of the same concept.
-
-**Fix:** Export a `TEST_FILE_PATTERNS` constant (and a `testFileExclusionSql(alias)` helper that generates the SQL) from a shared location. `dead.ts`, `isolated.ts`, and `test-coverage.ts` all import it.
-
----
-
-## 5. `queries/index.ts` barrel has score 136 bottleneck
-
-**Found by:** `bottlenecks` command
-
-**Problem:** The barrel re-export file (`queries/index.ts`) has fan-in=2, fan-out=68. Every query symbol is re-exported through it, so any consumer (`cli.ts`, `index.ts`) pulls the entire query surface. This is fine for a CLI tool, but if this package is used as a library, consumers pay for every query module even if they use one.
-
-**Fix (for later):** Support tree-shaking by also exporting individual query modules:
-```ts
-// Direct import for library consumers
-import { hotspots } from 'scip-query/queries/hotspots';
-```
-This needs `exports` map entries in `package.json`. Not urgent — the barrel is correct for CLI use.
-
----
-
-## 6. `cli.ts` is the highest fan-out non-barrel file (23 external symbols)
-
-**Found by:** `fan-out` command
-
-**Problem:** `cli.ts` imports from 8 internal modules and references 23 external symbols. It's a 770+ line file that defines 34 commands inline. Each command's `.action()` handler does its own `openDb()` / `queries.X()` / `console.log()` / `db.close()` dance.
-
-**Fix:** This isn't a bug — CLIs are inherently high fan-out. But if the file keeps growing, the repetitive `openDb` → query → format → `close` pattern could be extracted into a `runQuery(queryFn, formatter)` wrapper that handles the lifecycle. Each command would then be ~3 lines instead of ~15.
-
----
-
-## 7. `similar-files` shows 100% similarity across all query modules
-
-**Found by:** `similar-files --min-similarity 0.7`
-
-**Problem:** Every query file depends on the same 3 files: `db.ts`, `types.ts`, `symbol-parser.ts`. This makes the file-level similarity metric saturate at 100%. It's not a code quality issue — it's a signal that the dependency profile is too uniform to distinguish files at this level.
-
-**Implication for the tool itself:** The `similar-files` command should probably discount "universal" dependencies (files imported by >50% of the codebase) to surface more meaningful similarity. Universal deps like `types.ts` are infrastructure, not similarity signals.
-
----
-
-## 8. Callee-set queries repeat identical SQL in `similar.ts` and `extract-candidates.ts`
-
-**Found by:** `similar` command (78% overlap between those two files)
-
-**Problem:** Both `similar.ts` and `extract-candidates.ts` run the same "find all callees of a symbol within its definition range" SQL query. `similar.ts` has it in `findCallees()` (line ~120) and `getAllCalleeFingerprints()` (line ~175). `extract-candidates.ts` has it inline (line ~55).
-
-**Fix:** Extract a `getCalleesForSymbol(db, documentId, startLine, endLine, symbolId)` helper. Used by `similar.ts` (twice) and `extract-candidates.ts` (once). Also usable by `call-graph.ts` which runs a similar query.
-
----
-
-## 9. Deep chains are all rooted at `queries/index.ts` → `cli.ts`
-
-**Found by:** `deep-chains --min-depth 4`
-
-**Problem:** Every deep chain starts at `index.ts` or `cli.ts` because they're the barrel/entry points. The chains themselves are only depth 4-5, which is healthy. No action needed — this confirms the architecture is flat.
-
-**Assessment:** Not an issue. Healthy architecture signal.
-
----
-
-## 10. No circular dependencies
-
-**Found by:** `cycles` command
-
-**Assessment:** Clean. No action needed.
-
----
-
-## Summary
-
-| # | Finding | Severity | Effort | Lines saved |
-|---|---------|----------|--------|-------------|
-| 1 | Inline `symbolNoise` filters (26x) | Medium | Low | ~50 |
-| 2 | Inline `node_modules` exclusions (32x) | Medium | Low | ~30 |
-| 3 | Duplicated graph-building SQL (4 files) | Medium | Low | ~54 |
-| 4 | Duplicated test-file patterns (3 files) | Low | Low | ~15 |
-| 5 | Barrel bottleneck (tree-shaking) | Low | Medium | 0 (structure) |
-| 6 | CLI fan-out / repetitive handlers | Low | Medium | ~100 |
-| 7 | `similar-files` universal dep discount | Low | Medium | 0 (algorithm) |
-| 8 | Duplicated callee-set SQL | Medium | Low | ~30 |
-| 9 | Deep chains rooted at entry points | None | — | — |
-| 10 | No cycles | None | — | — |
-
-**Quick wins (items 1-4, 8):** ~180 lines eliminated, 5 shared helpers, ~30 minutes of work. All low-risk mechanical extractions.
-
-**Structural improvements (items 5-7):** Algorithm and architecture changes that improve the tool's own quality and the accuracy of its similarity detection. Medium effort, high value for the product.

package/PLAN.md

@@ -1,320 +0,0 @@
-# Implementation Plan: Phase 2 Commands + Agent Documentation
-
-This plan adds 10 new analysis commands and a comprehensive agent usage guide. Organized into 4 phases to keep diffs bounded and independently testable.
-
----
-
-## Phase 1: Transitive Impact + Change Planning (3 commands)
-
-These serve Use Case 1 — deep understanding for concrete planning.
-
-### 1.1 `affected <symbol>`
-
-**Purpose:** Full transitive closure of symbols that could break if a given symbol changes. Walks rdeps recursively at the symbol level (not just file level like `rdeps`).
-
-**Implementation:**
-- New file: `src/queries/affected.ts`
-- Algorithm: BFS from the target symbol through the mention graph. For each symbol that references the target, find symbols that reference *that* symbol, and so on. Track depth. Cap at configurable max depth (default 5) to avoid full-graph traversal on hub symbols.
-- Reuse: `findFirstSymbolMatch()` from `query-support.ts` to resolve the target.
-- SQL core: Recursive walk on `mentions` (role=0) → `defn_enclosing_ranges` → back to `mentions`. Each hop finds the enclosing symbol of each reference site, then finds references to *that* symbol.
-- Output type: `AffectedResult` — array of `{ symbol, shortName, file, depth }` sorted by depth then file.
-- CLI: `scip-query affected <symbol> [--max-depth N] [--scope path]`
-
-**Value:** "If I change this function's signature, what's the full blast wave?" Direct rdeps are depth 1. Their consumers are depth 2. This shows the full picture.
-
-### 1.2 `change-surface <file>`
-
-**Purpose:** Pre-change briefing: "I'm about to modify this file. What do I need to know?"
-
-**Implementation:**
-- New file: `src/queries/change-surface.ts`
-- Composes existing queries internally — not a raw SQL query but an orchestrator:
-  1. Call `symbols()` to get all symbols in the file
-  2. For each symbol, call the refs logic to count external consumers
-  3. Call `testCoverage()` to check which symbols are test-covered
-  4. Call `fanIn()` to get reference counts
-- Output type: `ChangeSurfaceResult` — per-symbol: `{ symbol, shortName, externalConsumers: number, testFiles: string[], riskLevel: 'low' | 'medium' | 'high' }` where risk = high if fan-in > 10 and no test coverage.
-- CLI: `scip-query change-surface <file>`
-
-**Value:** One command before modifying a file. Shows what's exported, who uses it, what's tested, and what's risky.
-
-### 1.3 `diff-impact`
-
-**Purpose:** Given the current git diff, compute the affected symbol set.
-
-**Implementation:**
-- New file: `src/queries/diff-impact.ts`
-- Algorithm:
-  1. Run `git diff --name-only HEAD` (via `execFileSync`) to get changed files
-  2. For each changed file, get all symbols defined in it via `symbols()` logic
-  3. For each symbol, get its fan-in count and test coverage
-  4. Aggregate: total changed symbols, total consumers affected, test coverage gaps
-- Output type: `DiffImpactResult` — `{ changedFiles, changedSymbols[], affectedConsumers[], uncoveredSymbols[], summary }`
-- CLI: `scip-query diff-impact [--base <ref>]` (default: diff against HEAD)
-- Note: Needs git available. If not in a git repo, error gracefully.
-
-**Value:** "You changed 3 files — here are the 47 symbols affected, the 12 files that consume them, and the 5 gaps in test coverage."
-
-### Phase 1 files to create:
-- `src/queries/affected.ts`
-- `src/queries/change-surface.ts`
-- `src/queries/diff-impact.ts`
-- Types added to `src/types.ts`
-- Exports added to `src/queries/index.ts`
-- CLI commands added to `src/cli.ts`
-
-### Phase 1 files to modify:
-- `src/types.ts` — add `AffectedResult`, `ChangeSurfaceResult`, `DiffImpactResult`
-- `src/queries/index.ts` — add exports
-- `src/cli.ts` — add 3 commands
-
----
-
-## Phase 2: De-bloating Commands (5 commands)
-
-These serve Use Case 2 — keeping the codebase clean.
-
-### 2.1 `drift [module]`
-
-**Purpose:** Detect pattern drift — files that don't match the typical dependency profile for their directory.
-
-**Implementation:**
-- New file: `src/queries/drift.ts`
-- Algorithm:
-  1. Build file dep profiles per directory (group files by their parent dir)
-  2. For each directory with 3+ files, compute the "median" dependency set — deps that appear in >50% of files in that dir
-  3. For each file, compute how much it deviates from the median: which expected deps are missing, which unexpected deps are present
-  4. Score deviation as a percentage. Report files with highest deviation.
-- Reuse: `buildFileDepGraph()` from `query-support.ts` for the dep edges.
-- Output type: `DriftResult` — `{ file, directory, deviationPercent, missingExpectedDeps[], unexpectedDeps[] }`
-- CLI: `scip-query drift [module] [--min-deviation N]` (default min-deviation: 30%)
-
-**Value:** Finds the files that don't follow the conventions of their neighbors. If 8 of 10 services import a validator and 2 don't, those 2 are flagged.
-
-### 2.2 `wrapper-candidates`
-
-**Purpose:** Find symbols that are only ever called through one intermediary — premature abstractions that add indirection without value.
-
-**Implementation:**
-- New file: `src/queries/wrapper-candidates.ts`
-- Algorithm:
-  1. Find all symbols with fan-in = 1 (exactly one caller)
-  2. For each, check if that single caller has fan-in > 3 (is widely used)
-  3. If so, the single-caller symbol is a wrapper candidate — it could be inlined into its caller
-  4. Also check LOC: small wrappers (< 10 LOC) are the strongest candidates
-- SQL: Subquery on `mentions` grouped by `symbol_id`, `HAVING COUNT(DISTINCT document_id) = 1`, then join to find the caller's fan-in.
-- Output type: `WrapperCandidate` — `{ symbol, shortName, file, loc, singleCaller, callerFanIn }`
-- CLI: `scip-query wrapper-candidates [--scope path] [--max-loc N]`
-
-**Value:** "This function exists only to call another function. You can inline it." Catches over-engineering.
-
-### 2.3 `passthrough-candidates`
-
-**Purpose:** Find functions that just forward to one other function without adding logic.
-
-**Implementation:**
-- New file: `src/queries/passthrough-candidates.ts`
-- Algorithm:
-  1. Find symbols with exactly 1 callee (they only call one external thing)
-  2. Filter to small functions (< 15 LOC)
-  3. These are likely passthroughs: `getUser(id) { return userRepo.findById(id); }`
-- Reuse: `getCalleeRowsForSymbol()` from `query-support.ts` to count callees.
-- Output type: `PassthroughCandidate` — `{ symbol, shortName, file, loc, forwardsTo, forwardsToFile }`
-- CLI: `scip-query passthrough-candidates [--scope path] [--max-loc N]`
-
-**Value:** Finds functions that are pure indirection. Either inline them or verify they exist for a reason (dependency inversion, testing boundary, etc.)
-
-### 2.4 `stale-abstractions`
-
-**Purpose:** Find interfaces/base classes/generics with exactly 1 implementation or 1 caller.
-
-**Implementation:**
-- New file: `src/queries/stale-abstractions.ts`
-- Algorithm:
-  1. Find type-level symbols (using `#` in the SCIP symbol — indicates class/interface/type)
-  2. For each, count cross-file references (fan-in)
-  3. Symbols with fan-in = 1 are single-consumer abstractions
-  4. Cross-reference with LOC: large single-consumer abstractions are the most wasteful
-- SQL: Filter `gs.symbol LIKE '%#%'` (type-level), then count mentions with role=0 from different documents.
-- Output type: `StaleAbstraction` — `{ symbol, shortName, file, loc, consumers: number, implementors: number }`
-- CLI: `scip-query stale-abstractions [--scope path] [--min-loc N]`
-
-**Value:** An interface with one implementation isn't an abstraction — it's indirection. A generic helper called from one place isn't reusable — it's premature.
-
-### 2.5 `complexity-hotspots`
-
-**Purpose:** Composite complexity score per symbol combining LOC, fan-in, fan-out, and callee count.
-
-**Implementation:**
-- New file: `src/queries/complexity-hotspots.ts`
-- Algorithm:
-  1. For each non-trivial symbol (>= minLoc), compute:
-     - LOC (from defn_enclosing_ranges)
-     - Fan-in (count of distinct referencing documents)
-     - Fan-out (count of distinct referenced symbols in other files)
-     - Callee count (total callees within definition range)
-  2. Score = `(LOC / 50) * (fanIn / 5) * (fanOut / 5)` (normalized so a 50-LOC function with 5 consumers and 5 callees scores ~1.0)
-  3. Sort by score descending
-- Reuse: Similar SQL patterns to `bottlenecks.ts` and `fan.ts`.
-- Output type: `ComplexityHotspot` — `{ symbol, shortName, file, loc, fanIn, fanOut, calleeCount, score }`
-- CLI: `scip-query complexity-hotspots [--scope path] [--min-loc N] [-n limit]`
-
-**Value:** The symbols with the highest scores are the ones most likely to contain bugs, be hardest to modify, and benefit most from decomposition. Combines multiple signals into one prioritized view.
-
-### Phase 2 files to create:
-- `src/queries/drift.ts`
-- `src/queries/wrapper-candidates.ts`
-- `src/queries/passthrough-candidates.ts`
-- `src/queries/stale-abstractions.ts`
-- `src/queries/complexity-hotspots.ts`
-
-### Phase 2 files to modify:
-- `src/types.ts` — add 5 result types
-- `src/queries/index.ts` — add 5 exports
-- `src/cli.ts` — add 5 commands
-
----
-
-## Phase 3: Composite Health Report (2 commands)
-
-### 3.1 `health`
-
-**Purpose:** Single command that runs all de-bloat analyses and produces a prioritized action list.
-
-**Implementation:**
-- New file: `src/queries/health.ts`
-- Algorithm: Run each analysis in sequence, aggregate results:
-  1. `dead()` → count dead symbols, total recoverable LOC
-  2. `isolated()` → count orphaned symbols
-  3. `cycles()` → count circular deps
-  4. `similarAll()` → count high-similarity pairs
-  5. `extractCandidates()` → count extraction opportunities
-  6. `wrapperCandidates()` → count wrapper symbols (new, from Phase 2)
-  7. `passthroughCandidates()` → count passthroughs (new, from Phase 2)
-  8. `staleAbstractions()` → count single-consumer types (new, from Phase 2)
-  9. `drift()` → count drifted files (new, from Phase 2)
-  10. `complexityHotspots()` → top 5 most complex symbols (new, from Phase 2)
-- Output: Grouped sections with counts and top items. A "health score" (0-100) based on weighted findings. Concrete action items sorted by effort/impact.
-- Output type: `HealthReport` — sections for each analysis, overall score, prioritized action list.
-- CLI: `scip-query health [--scope path] [--json]` (JSON mode for programmatic consumption by agents)
-
-**Value:** The difference between "powerful tool for experts" and "tool that actually gets used." One command, one report, one action list.
-
-### 3.2 `convergence <symbol1> <symbol2>`
-
-**Purpose:** Given two similar symbols (flagged by `similar`), show what a consolidated version would look like.
-
-**Implementation:**
-- New file: `src/queries/convergence.ts`
-- Algorithm:
-  1. Get callee sets for both symbols (via `getCalleeRowsForSymbol()`)
-  2. Compute shared callees (the body of the consolidated function)
-  3. Compute unique-to-A and unique-to-B (the parameterization points)
-  4. Report: "The consolidated function would call [shared callees]. A's unique behavior ([unique-to-A]) and B's unique behavior ([unique-to-B]) become parameters or strategy arguments."
-  5. Also show the file locations and LOC of both symbols for context.
-- Output type: `ConvergenceResult` — `{ symbolA, symbolB, sharedCallees[], uniqueToA[], uniqueToB[], consolidationStrategy }`
-- CLI: `scip-query convergence <symbol1> <symbol2>`
-
-**Value:** Turns a similarity finding into a concrete refactoring prescription. "These two are 75% similar" becomes "here's what the merged version looks like."
-
-### Phase 3 files to create:
-- `src/queries/health.ts`
-- `src/queries/convergence.ts`
-
-### Phase 3 files to modify:
-- `src/types.ts` — add `HealthReport`, `ConvergenceResult`
-- `src/queries/index.ts` — add 2 exports
-- `src/cli.ts` — add 2 commands
-
-### Phase 3 depends on: Phase 2 (health report calls Phase 2 commands)
-
----
-
-## Phase 4: Agent Usage Guide + Use Case Documentation
-
-### 4.1 `docs/AGENT_GUIDE.md`
-
-Comprehensive guide for AI agents (and humans) on how to use scip-query for specific goals. Structured as goal-oriented workflows, not command reference (that's already in README.md).
-
-**Sections:**
-
-#### "I need to understand how a system works before making changes"
-1. Start with `system <module>` for the full map
-2. Pick the entry point and run `call-graph <symbol>` to see what it calls and who calls it
-3. Run `deps <file>` and `rdeps <file>` to map the file-level dependency boundary
-4. Run `surface <module>` to understand the true public API (not just what's exported)
-5. Run `trace <symbol>` for any specific symbol you need to understand
-6. Run `change-surface <file>` for a pre-change briefing on anything you're about to modify
-7. Run `diff-impact` after making changes to verify the blast radius
-
-#### "I need to write a concrete implementation plan"
-1. Run `system <module>` to understand the target area
-2. Run `symbols <file>` on each file you'll modify to get line ranges and signatures
-3. Run `surface <module>` to identify the public contract you must preserve
-4. Run `refs <symbol>` for any symbol you plan to change, rename, or remove
-5. Run `affected <symbol>` for transitive impact on critical symbols
-6. Run `fan-in <symbol>` to quantify blast radius for each change
-7. Run `test-coverage <symbol>` to identify test gaps before you start
-
-#### "I want to clean up and de-bloat a codebase"
-1. Run `health` for the full prioritized report (start here)
-2. Address dead code first: `dead --min-loc 10 --skip-barrels` → safe deletions
-3. Address isolated symbols: `isolated --min-loc 5` → completely safe deletions
-4. Break cycles: `cycles` → structural fixes
-5. Reduce duplication: `similar --min-similarity 0.6` → consolidation candidates
-6. For each similar pair, run `convergence <a> <b>` to get the refactoring prescription
-7. Find extraction opportunities: `extract-candidates --min-loc 20`
-8. Remove unnecessary indirection: `wrapper-candidates`, `passthrough-candidates`
-9. Prune premature abstractions: `stale-abstractions`
-10. Fix pattern drift: `drift` → bring outlier files into line with their neighbors
-
-#### "I want to assess code quality and risk"
-1. Run `health` for the overall score
-2. Run `complexity-hotspots -n 20` for the riskiest symbols
-3. Run `bottlenecks -n 20` for coupling pressure points
-4. Run `deep-chains --min-depth 5` for architectural layering issues
-5. Run `test-coverage` for the coverage percentage
-6. Run `doc-coverage` for documentation gaps
-
-#### "I want to understand the impact of a change I already made"
-1. Run `diff-impact` to see what your changes affect
-2. Run `affected <symbol>` for any symbol you modified
-3. Run `test-coverage <symbol>` for each affected symbol to find test gaps
-
-#### Command cheat sheet
-Quick reference table: "If you want to know X, run Y."
-
-### 4.2 Update `README.md`
-
-- Add link to AGENT_GUIDE.md in the README
-- Add a "Workflows" section that links to the guide
-- Update command count and command table with new Phase 1-3 commands
-
-### Phase 4 files to create:
-- `docs/AGENT_GUIDE.md`
-
-### Phase 4 files to modify:
-- `README.md` — add workflows section, update command count
-
----
-
-## Execution Order
-
-```
-Phase 1 (impact + planning)     → 3 new commands, ~400 LOC
-Phase 2 (de-bloating)           → 5 new commands, ~500 LOC
-Phase 3 (health + convergence)  → 2 new commands, ~300 LOC
-Phase 4 (documentation)         → 1 new doc, README update
-
-Total: 10 new commands, ~1200 LOC of query logic, 1 agent guide
-```
-
-Each phase is independently testable and committable. Phase 3 depends on Phase 2. Phase 4 depends on Phases 1-3 (references all commands). Phases 1 and 2 are independent and can be built in parallel.
-
-### Shared infrastructure all phases will use:
-- `query-support.ts` — `buildFileDepGraph()`, `findFirstSymbolMatch()`, `getCalleeRowsForSymbol()`
-- `db.ts` — `pathExclusionsFor()`, `symbolNoiseFor()`, `symbolNoise`, `localSymbolPredicate`
-- `clean-signature.ts` — for any command that displays signatures
-- `symbol-parser.ts` — `shortenSymbol()` for all display output
-
-No new shared infrastructure needed. The existing helpers cover all planned commands.

package/dist/chunk-2QZ23IBN.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/queries/bottlenecks.ts"],"sourcesContent":["import type { ScipDatabase } from '../db.js';\nimport type { BottleneckResult } from '../types.js';\nimport { shortenSymbol } from '../symbol-parser.js';\n\n/**\n * Find coupling hubs: symbols with both high fan-in (many consumers)\n * AND high fan-out (references many other symbols).\n *\n * These are the most dangerous symbols to change — they sit at the\n * intersection of many dependency paths. Score = fanIn * fanOut.\n */\nexport function bottlenecks(\n  db: ScipDatabase,\n  opts: { limit?: number; scope?: string; minFanIn?: number; minFanOut?: number } = {},\n): BottleneckResult[] {\n  const { limit = 20, scope, minFanIn = 2, minFanOut = 2 } = opts;\n  const scopeFilter = scope ? `AND def_d.relative_path LIKE '%${scope}%'` : '';\n\n  // Use a wrapping query to filter on computed columns\n  const rows = db.all<{\n    symbol: string;\n    defined_in: string;\n    fan_in: number;\n    fan_out: number;\n  }>(\n    `SELECT * FROM (\n      SELECT\n        gs.symbol,\n        def_d.relative_path AS defined_in,\n        (SELECT COUNT(DISTINCT ref_c.document_id)\n         FROM mentions ref_m\n         JOIN chunks ref_c ON ref_m.chunk_id = ref_c.id\n         WHERE ref_m.symbol_id = gs.id AND ref_m.role = 0\n        ) AS fan_in,\n        (SELECT COUNT(DISTINCT ref_gs.id)\n         FROM mentions ref_m\n         JOIN chunks ref_c ON ref_m.chunk_id = ref_c.id\n         JOIN global_symbols ref_gs ON ref_m.symbol_id = ref_gs.id\n         JOIN defn_enclosing_ranges ref_der ON ref_gs.id = ref_der.symbol_id\n         WHERE ref_c.document_id = def_d.id\n           AND ref_m.role = 0\n           AND ref_der.document_id != def_d.id\n        ) AS fan_out\n      FROM global_symbols gs\n      JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id\n      JOIN documents def_d ON der.document_id = def_d.id\n      WHERE 1 = 1\n        ${db.pathExclusionsFor('def_d')}\n        ${db.symbolNoiseFor('gs')}\n        ${scopeFilter}\n    ) WHERE fan_in >= ? AND fan_out >= ?\n    ORDER BY (fan_in * fan_out) DESC\n    LIMIT ?`,\n    minFanIn, minFanOut, limit,\n  );\n\n  return rows\n    .filter((r) => !db.isIgnored(r.defined_in))\n    .map((r) => ({\n      symbol: r.symbol,\n      shortName: shortenSymbol(r.symbol),\n      fanIn: r.fan_in,\n      fanOut: r.fan_out,\n      score: r.fan_in * r.fan_out,\n      definedIn: r.defined_in,\n    }));\n}\n"],"mappings":";;;;;AAWO,SAAS,YACd,IACA,OAAkF,CAAC,GAC/D;AACpB,QAAM,EAAE,QAAQ,IAAI,OAAO,WAAW,GAAG,YAAY,EAAE,IAAI;AAC3D,QAAM,cAAc,QAAQ,kCAAkC,KAAK,OAAO;AAG1E,QAAM,OAAO,GAAG;AAAA,IAMd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,UAsBM,GAAG,kBAAkB,OAAO,CAAC;AAAA,UAC7B,GAAG,eAAe,IAAI,CAAC;AAAA,UACvB,WAAW;AAAA;AAAA;AAAA;AAAA,IAIjB;AAAA,IAAU;AAAA,IAAW;AAAA,EACvB;AAEA,SAAO,KACJ,OAAO,CAAC,MAAM,CAAC,GAAG,UAAU,EAAE,UAAU,CAAC,EACzC,IAAI,CAAC,OAAO;AAAA,IACX,QAAQ,EAAE;AAAA,IACV,WAAW,cAAc,EAAE,MAAM;AAAA,IACjC,OAAO,EAAE;AAAA,IACT,QAAQ,EAAE;AAAA,IACV,OAAO,EAAE,SAAS,EAAE;AAAA,IACpB,WAAW,EAAE;AAAA,EACf,EAAE;AACN;","names":[]}

package/dist/chunk-36OMT7ZJ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/queries/drift.ts"],"sourcesContent":["import path from 'node:path';\nimport type { ScipDatabase } from '../db.js';\nimport { buildFileDepGraph } from '../query-support.js';\nimport type { DriftResult, DriftSummary } from '../types.js';\n\n/**\n * Detect structural drift using the reference graph, not just import patterns.\n *\n * Three types of drift, each detecting a real problem:\n *\n * 1. **Unused imports** — file depends on a module but never references\n *    any of its symbols. Dead dependency, safe to remove.\n *\n * 2. **Layer violations** — file imports from a directory it shouldn't\n *    based on the project's directory structure (e.g., a query importing\n *    from reindex, a helper importing from CLI). Architectural decay.\n *\n * 3. **Pattern deviations** — file imports something no sibling does,\n *    suggesting it's reaching outside its expected scope. Only flagged\n *    when the file is the ONLY one in its directory with that dep.\n */\nexport function drift(\n  db: ScipDatabase,\n  opts?: { scope?: string; minDeviation?: number },\n): DriftSummary {\n  const { scope } = opts ?? {};\n\n  // Build file dep graph (which files depend on which)\n  const depGraph = buildFileDepGraph(db, scope);\n\n  // Build symbol-level reference graph: for each file, which other files'\n  // symbols does it actually reference?\n  const symbolRefs = buildSymbolRefGraph(db, scope);\n\n  const results: DriftResult[] = [];\n\n  // ── Angle 1: Unused imports ──────────────────────────────\n  // File depends on module B (via dep graph) but never references\n  // any symbol defined in B (via symbol ref graph).\n  for (const [file, deps] of depGraph) {\n    if (isStructuralRole(path.basename(file))) continue;\n\n    const referencedFiles = symbolRefs.get(file) ?? new Set<string>();\n\n    for (const dep of deps) {\n      if (!referencedFiles.has(dep)) {\n        // This file \"depends on\" dep but never references its symbols.\n        // This can happen when the dep is imported for types only\n        // (which don't appear in the mention graph). Skip type-heavy deps.\n        if (isLikelyTypeOnlyDep(dep)) continue;\n\n        results.push({\n          file,\n          kind: 'unused-import',\n          description: `Depends on ${dep} but references none of its symbols`,\n          dep,\n        });\n      }\n    }\n  }\n\n  // ── Angle 2: Layer violations ────────────────────────────\n  // Detect when a file imports from a directory that represents\n  // a different architectural layer. We infer layers from the\n  // directory structure: files in the same top-level dir are peers,\n  // files in different top-level dirs crossing inward is a violation.\n  const layerRules = inferLayerRules(depGraph);\n\n  for (const [file, deps] of depGraph) {\n    if (isStructuralRole(path.basename(file))) continue;\n\n    const fileLayer = getTopDir(file);\n    for (const dep of deps) {\n      const depLayer = getTopDir(dep);\n      if (fileLayer === depLayer) continue; // same layer, fine\n\n      const violation = layerRules.get(`${fileLayer}->${depLayer}`);\n      if (violation === 'violation') {\n        results.push({\n          file,\n          kind: 'layer-violation',\n          description: `Imports from ${depLayer}/ (${dep}) — may cross architectural boundary`,\n          dep,\n          detail: `${fileLayer}/ should not depend on ${depLayer}/`,\n        });\n      }\n    }\n  }\n\n  // ── Angle 3: Unique deps (pattern deviation) ─────────────\n  // If a file is the ONLY one in its directory that depends on a\n  // particular module, that dependency is unusual and worth flagging.\n  const dirToFiles = new Map<string, string[]>();\n  for (const file of depGraph.keys()) {\n    const dir = path.dirname(file);\n    if (!dirToFiles.has(dir)) dirToFiles.set(dir, []);\n    dirToFiles.get(dir)!.push(file);\n  }\n\n  for (const [dir, files] of dirToFiles) {\n    if (files.length < 3) continue;\n\n    // Count dep frequency across siblings\n    const depFreq = new Map<string, number>();\n    for (const file of files) {\n      if (isStructuralRole(path.basename(file))) continue;\n      for (const dep of depGraph.get(file) ?? []) {\n        depFreq.set(dep, (depFreq.get(dep) ?? 0) + 1);\n      }\n    }\n\n    for (const file of files) {\n      if (isStructuralRole(path.basename(file))) continue;\n      for (const dep of depGraph.get(file) ?? []) {\n        if ((depFreq.get(dep) ?? 0) === 1) {\n          // This file is the only one in its dir that depends on this module\n          // Skip if dep is in the same directory (sibling imports are normal)\n          if (path.dirname(dep) === dir) continue;\n\n          results.push({\n            file,\n            kind: 'pattern-deviation',\n            description: `Only file in ${dir}/ that depends on ${dep}`,\n            dep,\n          });\n        }\n      }\n    }\n  }\n\n  return {\n    results,\n    unusedImports: results.filter((r) => r.kind === 'unused-import').length,\n    layerViolations: results.filter((r) => r.kind === 'layer-violation').length,\n    patternDeviations: results.filter((r) => r.kind === 'pattern-deviation').length,\n  };\n}\n\n// ── Helpers ────────────────────────────────────────────────\n\n/**\n * Build a map of file → set of files whose symbols it references.\n * This is more precise than the dep graph because it uses actual\n * symbol mentions, not just import statements.\n */\nfunction buildSymbolRefGraph(\n  db: ScipDatabase,\n  scope?: string,\n): Map<string, Set<string>> {\n  const scopeFilter = scope ? `AND d1.relative_path LIKE '%${scope}%'` : '';\n\n  const rows = db.all<{ from_file: string; to_file: string }>(\n    `SELECT DISTINCT d1.relative_path AS from_file, d2.relative_path AS to_file\n    FROM mentions m\n    JOIN chunks c ON m.chunk_id = c.id\n    JOIN documents d1 ON c.document_id = d1.id\n    JOIN global_symbols gs ON m.symbol_id = gs.id\n    JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id\n    JOIN documents d2 ON der.document_id = d2.id\n    WHERE d1.id != d2.id\n      AND m.role = 0\n      ${db.pathExclusionsFor('d1', 'd2')}\n      ${scopeFilter}`,\n  );\n\n  const graph = new Map<string, Set<string>>();\n  for (const r of rows) {\n    if (db.isIgnored(r.from_file) || db.isIgnored(r.to_file)) continue;\n    if (!graph.has(r.from_file)) graph.set(r.from_file, new Set());\n    graph.get(r.from_file)!.add(r.to_file);\n  }\n  return graph;\n}\n\n/**\n * Infer layer boundary rules from the dependency graph.\n * If directory A never depends on directory B across the entire codebase,\n * then a new A→B dependency is a violation.\n */\nfunction inferLayerRules(\n  depGraph: Map<string, Set<string>>,\n): Map<string, 'ok' | 'violation'> {\n  const layerEdges = new Map<string, number>();\n  const layerSet = new Set<string>();\n\n  for (const [file, deps] of depGraph) {\n    const fromLayer = getTopDir(file);\n    layerSet.add(fromLayer);\n    for (const dep of deps) {\n      const toLayer = getTopDir(dep);\n      if (fromLayer === toLayer) continue;\n      layerSet.add(toLayer);\n      const key = `${fromLayer}->${toLayer}`;\n      layerEdges.set(key, (layerEdges.get(key) ?? 0) + 1);\n    }\n  }\n\n  // An edge that appears only 1-2 times across the whole codebase\n  // is likely a violation (anomalous cross-layer dep).\n  // Edges that appear many times are established patterns.\n  const rules = new Map<string, 'ok' | 'violation'>();\n  for (const [edge, count] of layerEdges) {\n    rules.set(edge, count <= 2 ? 'violation' : 'ok');\n  }\n\n  return rules;\n}\n\nfunction getTopDir(filePath: string): string {\n  const parts = filePath.split('/');\n  return parts[0] ?? filePath;\n}\n\nfunction isLikelyTypeOnlyDep(dep: string): boolean {\n  return dep.includes('types') || dep.endsWith('.d.ts');\n}\n\nfunction isStructuralRole(basename: string): boolean {\n  if (basename === 'index.ts' || basename === 'index.js') return true;\n  if (basename === 'cli.ts' || basename === 'main.ts' || basename === 'main.rs') return true;\n  if (basename.includes('worker.') || basename.includes('postinstall.')) return true;\n  if (basename === 'health.ts' || basename === 'health.js') return true;\n  return false;\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-3E2X7RIE.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/queries/redundant-reexports.ts"],"sourcesContent":["import type { ScipDatabase } from '../db.js';\nimport type { RedundantReexport } from '../types.js';\nimport { shortenSymbol } from '../symbol-parser.js';\n\n/**\n * Find barrel re-exports that no consumer actually imports through.\n *\n * If `queries/index.ts` re-exports `byKind` from `by-kind.ts`, but every\n * consumer of `byKind` imports it directly from `by-kind.ts` (not through\n * `index.ts`), the re-export in the barrel is dead weight.\n *\n * Algorithm:\n * 1. Find all barrel files (index.ts / index.js)\n * 2. For each barrel, find symbols it re-exports (defined elsewhere, referenced in barrel with role=0)\n * 3. For each re-exported symbol, count consumers through the barrel vs direct from the source\n * 4. If zero consumers go through the barrel, the re-export is redundant\n */\nexport function redundantReexports(\n  db: ScipDatabase,\n  opts: { scope?: string; limit?: number } = {},\n): RedundantReexport[] {\n  const { scope, limit } = opts;\n\n  const scopeFilter = scope ? `AND barrel_d.relative_path LIKE '%${scope}%'` : '';\n\n  // Step 1 + 2: Find all barrel files and symbols they re-export.\n  // A re-export is a symbol that:\n  //   - is mentioned in a barrel file with role=0 (reference/import)\n  //   - has its definition (defn_enclosing_ranges) in a DIFFERENT file\n  const reexportRows = db.all<{\n    barrel_doc_id: number;\n    barrel_path: string;\n    symbol_id: number;\n    symbol: string;\n    original_doc_id: number;\n    original_path: string;\n  }>(\n    `SELECT DISTINCT\n      barrel_d.id AS barrel_doc_id,\n      barrel_d.relative_path AS barrel_path,\n      gs.id AS symbol_id,\n      gs.symbol AS symbol,\n      orig_d.id AS original_doc_id,\n      orig_d.relative_path AS original_path\n    FROM mentions m\n    JOIN chunks c ON m.chunk_id = c.id\n    JOIN documents barrel_d ON c.document_id = barrel_d.id\n    JOIN global_symbols gs ON m.symbol_id = gs.id\n    JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id\n    JOIN documents orig_d ON der.document_id = orig_d.id\n    WHERE m.role = 0\n      AND (barrel_d.relative_path LIKE '%/index.ts'\n        OR barrel_d.relative_path LIKE '%/index.js'\n        OR barrel_d.relative_path = 'index.ts'\n        OR barrel_d.relative_path = 'index.js')\n      AND orig_d.id != barrel_d.id\n      ${db.pathExclusionsFor('barrel_d', 'orig_d')}\n      ${db.symbolNoiseFor('gs')}\n      -- Only function-level symbols (ending with ().), not module-level\n      AND gs.symbol LIKE '%().'\n      ${scopeFilter}\n    ORDER BY barrel_d.relative_path, gs.symbol`,\n  );\n\n  const results: RedundantReexport[] = [];\n\n  for (const row of reexportRows) {\n    if (db.isIgnored(row.barrel_path) || db.isIgnored(row.original_path)) continue;\n\n    // Step 3: Count consumers that reference this symbol through the barrel\n    // A \"barrel consumer\" is a file (other than the barrel itself and the original file)\n    // that mentions this symbol AND also mentions something from the barrel document.\n    // More precisely: count distinct files that reference this symbol AND whose\n    // chunk is in a document that also has a role=0 mention pointing to the barrel file's symbols.\n    //\n    // Simpler approach: count distinct documents that reference this symbol (role=0)\n    // grouped by whether the reference chunk is in a file that imports from the barrel\n    // or from the original.\n    //\n    // Actually, the most reliable approach with SCIP data: count how many distinct\n    // consumer documents reference this symbol_id with role=0, excluding the barrel\n    // and the original file themselves. Then check if those consumers also reference\n    // ANY symbol through a mention in the barrel doc vs the original doc.\n    //\n    // Simplest correct approach: In SCIP, when file A does `import { foo } from './bar/index'`,\n    // the mention of `foo` in file A points to the same global symbol regardless of import path.\n    // SCIP doesn't track import provenance. BUT the barrel file itself contains mentions\n    // (role=0 references) of the re-exported symbols. So we can check:\n    // - barrelConsumers: files that mention both this symbol AND any symbol whose definition\n    //   is in the barrel (i.e., they import the barrel)\n    // - directConsumers: files that mention this symbol but don't import the barrel\n    //\n    // Even simpler: check if the barrel document is in the deps of the consumer.\n    // A consumer \"goes through the barrel\" if it has ANY role=0 mention pointing to a\n    // chunk in the barrel file. Otherwise it goes direct.\n\n    const consumerCounts = db.get<{\n      barrel_consumers: number;\n      direct_consumers: number;\n    }>(\n      `SELECT\n        SUM(CASE WHEN uses_barrel = 1 THEN 1 ELSE 0 END) AS barrel_consumers,\n        SUM(CASE WHEN uses_barrel = 0 THEN 1 ELSE 0 END) AS direct_consumers\n      FROM (\n        SELECT\n          consumer_d.id AS consumer_doc_id,\n          MAX(CASE WHEN EXISTS (\n            SELECT 1\n            FROM mentions barrel_m\n            JOIN chunks barrel_c ON barrel_m.chunk_id = barrel_c.id\n            WHERE barrel_c.document_id = consumer_d.id\n              AND barrel_m.role = 0\n              AND barrel_m.symbol_id IN (\n                SELECT m2.symbol_id\n                FROM mentions m2\n                JOIN chunks c2 ON m2.chunk_id = c2.id\n                WHERE c2.document_id = ?\n                  AND m2.role = 0\n              )\n          ) THEN 1 ELSE 0 END) AS uses_barrel\n        FROM mentions ref_m\n        JOIN chunks ref_c ON ref_m.chunk_id = ref_c.id\n        JOIN documents consumer_d ON ref_c.document_id = consumer_d.id\n        WHERE ref_m.symbol_id = ?\n          AND ref_m.role = 0\n          AND consumer_d.id != ?\n          AND consumer_d.id != ?\n          ${db.pathExclusionsFor('consumer_d')}\n        GROUP BY consumer_d.id\n      )`,\n      row.barrel_doc_id,  // for the inner subquery checking barrel mentions\n      row.symbol_id,      // the re-exported symbol\n      row.barrel_doc_id,  // exclude the barrel itself\n      row.original_doc_id, // exclude the original file\n    );\n\n    const barrelConsumers = consumerCounts?.barrel_consumers ?? 0;\n    const directConsumers = consumerCounts?.direct_consumers ?? 0;\n\n    // In TypeScript, `import * as X from './barrel'` resolves all references\n    // directly to the source file — the barrel is transparent to SCIP.\n    // This means barrelConsumers is always 0 for namespace imports.\n    //\n    // We can only confidently report symbols with 0 consumers EVERYWHERE\n    // (both barrel and direct). These are truly dead re-exports.\n    //\n    // Symbols with directConsumers > 0 but barrelConsumers === 0 might be\n    // consumed through a namespace import — we can't tell, so we skip them.\n    if (barrelConsumers === 0 && directConsumers === 0) {\n      results.push({\n        barrelFile: row.barrel_path,\n        symbol: row.symbol,\n        shortName: shortenSymbol(row.symbol),\n        originalFile: row.original_path,\n        barrelConsumers,\n        directConsumers,\n      });\n    }\n  }\n\n  // Sort: symbols with the most direct consumers first (biggest cleanup wins),\n  // then by barrel file path for stable output\n  results.sort((a, b) =>\n    b.directConsumers - a.directConsumers\n    || a.barrelFile.localeCompare(b.barrelFile)\n    || a.shortName.localeCompare(b.shortName),\n  );\n\n  return limit ? results.slice(0, limit) : results;\n}\n"],"mappings":";;;;;AAiBO,SAAS,mBACd,IACA,OAA2C,CAAC,GACvB;AACrB,QAAM,EAAE,OAAO,MAAM,IAAI;AAEzB,QAAM,cAAc,QAAQ,qCAAqC,KAAK,OAAO;AAM7E,QAAM,eAAe,GAAG;AAAA,IAQtB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAmBI,GAAG,kBAAkB,YAAY,QAAQ,CAAC;AAAA,QAC1C,GAAG,eAAe,IAAI,CAAC;AAAA;AAAA;AAAA,QAGvB,WAAW;AAAA;AAAA,EAEjB;AAEA,QAAM,UAA+B,CAAC;AAEtC,aAAW,OAAO,cAAc;AAC9B,QAAI,GAAG,UAAU,IAAI,WAAW,KAAK,GAAG,UAAU,IAAI,aAAa,EAAG;AA6BtE,UAAM,iBAAiB,GAAG;AAAA,MAIxB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,YA2BM,GAAG,kBAAkB,YAAY,CAAC;AAAA;AAAA;AAAA,MAGxC,IAAI;AAAA;AAAA,MACJ,IAAI;AAAA;AAAA,MACJ,IAAI;AAAA;AAAA,MACJ,IAAI;AAAA;AAAA,IACN;AAEA,UAAM,kBAAkB,gBAAgB,oBAAoB;AAC5D,UAAM,kBAAkB,gBAAgB,oBAAoB;AAW5D,QAAI,oBAAoB,KAAK,oBAAoB,GAAG;AAClD,cAAQ,KAAK;AAAA,QACX,YAAY,IAAI;AAAA,QAChB,QAAQ,IAAI;AAAA,QACZ,WAAW,cAAc,IAAI,MAAM;AAAA,QACnC,cAAc,IAAI;AAAA,QAClB;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AAIA,UAAQ;AAAA,IAAK,CAAC,GAAG,MACf,EAAE,kBAAkB,EAAE,mBACnB,EAAE,WAAW,cAAc,EAAE,UAAU,KACvC,EAAE,UAAU,cAAc,EAAE,SAAS;AAAA,EAC1C;AAEA,SAAO,QAAQ,QAAQ,MAAM,GAAG,KAAK,IAAI;AAC3C;","names":[]}