scip-query 0.1.0

package/docs/AGENT_GUIDE.md

@@ -0,0 +1,359 @@
+# scip-query Agent Guide
+
+Goal-oriented workflows for AI agents and developers. Each section starts with a goal and walks through the exact commands to run, what to expect back, and how to use the results.
+
+For command syntax and options reference, see [README.md](../README.md).
+
+---
+
+## Workflow 1: Understand a system before making changes
+
+**Goal:** Build a complete mental model of a module or feature area so you can write a precise implementation plan with no ambiguity about what code exists, what it does, and what depends on it.
+
+### Steps
+
+1. **Map the module**
+   ```bash
+   scip-query system <module-path>
+   ```
+   Returns: all files in the module, all exported symbols with line ranges, all inbound and outbound dependencies. This is your starting map.
+
+2. **Understand the public contract**
+   ```bash
+   scip-query surface <module-path>
+   ```
+   Returns: which symbols external consumers actually reference. This is the true public API — not what's exported, but what's used. Any change to these symbols is a breaking change.
+
+3. **Trace specific symbols**
+   ```bash
+   scip-query trace <symbol-name>
+   ```
+   Returns: where the symbol is defined (file + line range + signature) and every file that references it. Use this for any symbol you need to understand deeply.
+
+4. **Map the call graph**
+   ```bash
+   scip-query call-graph <function-name>
+   ```
+   Returns: what calls this function (incoming) and what this function calls (outgoing). Gives you the function's role in the execution flow.
+
+5. **Check blast radius**
+   ```bash
+   scip-query affected <symbol-name>
+   ```
+   Returns: the full transitive closure of symbols that could break if this symbol changes. Depth 1 = direct consumers. Depth 2 = consumers of consumers. Shows the complete ripple effect.
+
+6. **Pre-change briefing**
+   ```bash
+   scip-query change-surface <file>
+   ```
+   Returns: every symbol in the file, how many external consumers each has, which are test-covered, and a risk level (high/medium/low). Run this before modifying any file.
+
+### What you should know after this workflow
+
+- Every file in the module and what it contains
+- The true public API (what consumers actually use)
+- The full dependency graph (what the module depends on and what depends on it)
+- The blast radius of any specific symbol change
+- Which symbols are high-risk (many consumers, no tests)
+
+---
+
+## Workflow 2: Write a concrete implementation plan
+
+**Goal:** Produce an implementation plan where every file to create/modify is named, every symbol to change is identified with line numbers, every dependency is mapped, and every risk is called out.
+
+### Steps
+
+1. **Map the target area**
+   ```bash
+   scip-query system <module-path>
+   scip-query symbols <each-file-you-will-modify>
+   ```
+   Get the full symbol inventory with line ranges and signatures for every file in scope.
+
+2. **Identify the public contract you must preserve**
+   ```bash
+   scip-query surface <module-path>
+   ```
+   Any symbol that appears here must maintain backward compatibility or all consumers must be updated.
+
+3. **Map every symbol you plan to change**
+   ```bash
+   scip-query refs <symbol>        # who uses it
+   scip-query affected <symbol>    # transitive blast radius
+   scip-query fan-in <symbol>      # quantified consumer count
+   ```
+   For each symbol you'll modify: know exactly who consumes it and how many layers deep the impact goes.
+
+4. **Check test coverage gaps**
+   ```bash
+   scip-query test-coverage <symbol>
+   scip-query change-surface <file>
+   ```
+   Identify which symbols in your change set lack test coverage. These are the risk points that need new tests.
+
+5. **Find reusable code**
+   ```bash
+   scip-query similar <symbol-you-plan-to-write>
+   scip-query deps <file>
+   ```
+   Before writing new code, check if something similar already exists. `similar` finds functions with overlapping callee patterns. `deps` shows what the file already imports that you can reuse.
+
+6. **After making changes, verify impact**
+   ```bash
+   scip-query diff-impact
+   ```
+   Shows every symbol affected by your git diff, every consumer file impacted, and test coverage gaps.
+
+### Plan template
+
+```
+## Change: [description]
+
+### Files to modify
+- `path/to/file.ts` — [what changes, which symbols]
+  - `symbolName` (lines X-Y) — [change description]
+  - Fan-in: N, Test coverage: yes/no
+
+### Files to create
+- `path/to/new-file.ts` — [purpose]
+  - Similar to: `existing-file.ts` (N% callee overlap via `similar`)
+
+### Public contract impact
+- `surface` shows N symbols consumed externally
+- [List any breaking changes]
+
+### Blast radius
+- `affected` shows N symbols across M files at depth 1-2
+- [List high-risk symbols]
+
+### Test plan
+- `change-surface` shows N symbols without test coverage
+- [Tests to add]
+```
+
+---
+
+## Workflow 3: Clean up and de-bloat a codebase
+
+**Goal:** Systematically reduce unnecessary code, eliminate duplication, and improve structural health.
+
+### Steps
+
+1. **Get the full health report**
+   ```bash
+   scip-query health
+   ```
+   This runs every analysis and produces a prioritized action list. Start here. The actions are sorted by impact/effort ratio — do the top ones first.
+
+2. **Delete dead code (safest, highest impact)**
+   ```bash
+   scip-query dead --min-loc 10 --skip-barrels
+   ```
+   These symbols have zero cross-file references. They can be safely deleted. `--skip-barrels` ignores re-exports through index.ts files which can create false negatives.
+
+3. **Delete isolated symbols**
+   ```bash
+   scip-query isolated --min-loc 5
+   ```
+   Stricter than `dead` — these symbols have zero references anywhere, including in their own file. Completely disconnected from the codebase.
+
+4. **Break circular dependencies**
+   ```bash
+   scip-query cycles
+   ```
+   If any exist, they need structural fixes: dependency inversion, module splitting, or interface extraction.
+
+5. **Consolidate similar functions**
+   ```bash
+   scip-query similar --min-similarity 0.5
+   ```
+   Pairs of functions with overlapping callee sets. For each pair:
+   ```bash
+   scip-query convergence <symbol1> <symbol2>
+   ```
+   Shows what the consolidated version would look like: shared callees = common body, unique callees = parameterization points.
+
+6. **Extract large functions**
+   ```bash
+   scip-query extract-candidates --min-loc 20
+   ```
+   Functions with isolated callee clusters — natural "Extract Method" seams.
+
+7. **Remove unnecessary indirection**
+   ```bash
+   scip-query wrapper-candidates
+   scip-query passthrough-candidates
+   ```
+   Wrappers: single-consumer symbols that can be inlined. Passthroughs: functions that just forward to one callee.
+
+8. **Prune premature abstractions**
+   ```bash
+   scip-query stale-abstractions
+   ```
+   Types and interfaces with 0-1 consumers. An interface with one implementation isn't an abstraction.
+
+9. **Fix pattern drift**
+   ```bash
+   scip-query drift
+   ```
+
+10. **Remove redundant re-exports**
+    ```bash
+    scip-query redundant-reexports
+    ```
+    Barrel file entries that nobody imports through. Clean up the barrel.
+
+11. **Find same-shape functions**
+    ```bash
+    scip-query similar-signatures --min-loc 5
+    ```
+    Functions with identical parameter/return types. Different signal from callee similarity — catches "same interface, different implementation."
+   Files that deviate from their directory's typical dependency pattern. Bring them into line with their neighbors.
+
+### Priority order
+
+| Priority | What | Why |
+|---|---|---|
+| 1 | Dead code | Zero risk, immediate LOC reduction |
+| 2 | Isolated symbols | Zero risk, zero consumers |
+| 3 | Circular deps | Structural fix, prevents future problems |
+| 4 | Similar functions | Reduces duplication, use `convergence` for prescription |
+| 5 | Extraction candidates | Reduces function complexity |
+| 6 | Wrappers / passthroughs | Removes unnecessary indirection |
+| 7 | Stale abstractions | Removes premature over-engineering |
+| 8 | Pattern drift | Consistency improvement |
+
+---
+
+## Workflow 4: Assess code quality and risk
+
+**Goal:** Produce a quality assessment of a codebase or module with quantified metrics.
+
+### Steps
+
+1. **Overall health**
+   ```bash
+   scip-query health
+   scip-query health --json    # for programmatic use
+   ```
+
+2. **Complexity risks**
+   ```bash
+   scip-query complexity-hotspots -n 20
+   ```
+   Symbols with the highest composite score (LOC x fan-in x fan-out). These are the most likely to contain bugs and the hardest to modify.
+
+3. **Coupling risks**
+   ```bash
+   scip-query bottlenecks -n 20
+   ```
+   Symbols with both high fan-in (many consumers) AND high fan-out (many dependencies). Changes to these are risky in both directions.
+
+4. **Architecture depth**
+   ```bash
+   scip-query deep-chains --min-depth 5
+   ```
+   Long transitive dependency chains. If chains are deeper than 6-7, the architecture may need flattening.
+
+5. **Test coverage**
+   ```bash
+   scip-query test-coverage
+   ```
+   Percentage of symbols referenced by test files. Not execution coverage, but structural coverage.
+
+6. **Documentation coverage**
+   ```bash
+   scip-query doc-coverage --min-loc 5
+   ```
+
+### Quality report template
+
+```
+## Quality Assessment: [project/module]
+
+### Overview
+- Files: N | Symbols: N | Index size: N
+- Health score: N/100
+
+### Risk Areas
+- Complexity hotspots: [top 5 from complexity-hotspots]
+- Coupling bottlenecks: [top 5 from bottlenecks]
+- Deepest dependency chain: N layers
+- Circular dependencies: N
+
+### Coverage
+- Test coverage: N% of symbols referenced by tests
+- Documentation coverage: N%
+
+### Cleanup Opportunities
+- Dead code: N symbols (N LOC recoverable)
+- Similar function pairs: N
+- Stale abstractions: N
+```
+
+---
+
+## Workflow 5: Understand impact after making changes
+
+**Goal:** After modifying code, verify what was affected and identify gaps.
+
+### Steps
+
+1. **Compute diff impact**
+   ```bash
+   scip-query diff-impact
+   ```
+   Shows: changed files, changed symbols with fan-in counts, affected consumer files, symbols without test coverage.
+
+2. **Check transitive impact for critical symbols**
+   ```bash
+   scip-query affected <changed-symbol>
+   ```
+   For any high fan-in symbol that changed, check the full transitive blast wave.
+
+3. **Verify test coverage**
+   ```bash
+   scip-query test-coverage <changed-symbol>
+   ```
+   For each affected symbol, verify tests exist.
+
+---
+
+## Quick Reference
+
+| I want to... | Run |
+|---|---|
+| Understand a module | `system <module>` |
+| See what consumers actually use | `surface <module>` |
+| Find all references to a symbol | `refs <symbol>` or `trace <symbol>` |
+| See what a function calls and who calls it | `call-graph <symbol>` |
+| Check blast radius of a change | `affected <symbol>` |
+| Get a pre-change briefing | `change-surface <file>` |
+| See impact of my git changes | `diff-impact` |
+| Find dead code to delete | `dead --min-loc 10 --skip-barrels` |
+| Find duplicate functions | `similar --min-similarity 0.5` |
+| Find same-shape functions | `similar-signatures --min-loc 5` |
+| Get a refactoring prescription | `convergence <sym1> <sym2>` |
+| Find redundant barrel re-exports | `redundant-reexports` |
+| Find extraction opportunities | `extract-candidates --min-loc 20` |
+| Find unnecessary wrappers | `wrapper-candidates` |
+| Find single-implementation types | `stale-abstractions` |
+| Find pattern outliers | `drift` |
+| Get overall codebase health | `health` |
+| Find riskiest symbols | `complexity-hotspots` |
+| Find coupling pressure points | `bottlenecks` |
+| Find circular dependencies | `cycles` |
+| Check test coverage | `test-coverage` |
+
+---
+
+## Tips for AI Agents
+
+- **Always reindex before analysis** if the codebase has changed significantly: `scip-query reindex`
+- **Use `--json` on `health`** for programmatic consumption — parse the JSON to make decisions
+- **Run `change-surface` before every file modification** — it takes <1 second and prevents surprises
+- **Run `diff-impact` before committing** — catches test coverage gaps and unexpected blast radius
+- **Use `convergence` after `similar`** — `similar` finds the problem, `convergence` gives the solution
+- **Start cleanup with `health`** — it prioritizes for you so you don't have to decide what to fix first
+- **Scope commands with `-s`** — most commands accept `--scope <path>` to limit analysis to a specific module. Use this on large codebases to keep results focused.

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "scip-query",
+  "version": "0.1.0",
+  "description": "Language-agnostic code intelligence CLI powered by SCIP indexes",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "scip-query": "dist/cli.js"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./queries": {
+      "import": "./dist/queries/index.js",
+      "types": "./dist/queries/index.d.ts"
+    },
+    "./queries/*": {
+      "import": "./dist/queries/*.js",
+      "types": "./dist/queries/*.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node dist/postinstall.js || true"
+  },
+  "keywords": [
+    "scip",
+    "code-intelligence",
+    "code-navigation",
+    "go-to-definition",
+    "find-references",
+    "dead-code",
+    "dependency-graph",
+    "sourcegraph",
+    "typescript",
+    "python",
+    "rust",
+    "java",
+    "ruby",
+    "php",
+    "csharp"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.7.0",
+    "commander": "^13.1.0",
+    "ignore": "^7.0.3"
+  },
+  "devDependencies": {
+    "@sourcegraph/scip-typescript": "^0.4.0",
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/reports/debloat/2026-04-10-scip-query-self-audit.md

@@ -0,0 +1,161 @@
+# De-Bloat Report: scip-query
+
+**Date:** 2026-04-10
+**Health Score:** 33/100
+**Scope:** 60 files, 1660 symbols, 996 KB
+
+## Summary
+
+- Total findings: 52 actionable (excluding false positives and expected deviations)
+- Estimated recoverable LOC: ~1,724
+- Safe deletions: 30 symbols (~1,712 LOC)
+- Structural fixes: 2 (duplicate type, unused function)
+- Consolidation candidates: 0 logic-level (similarity is boilerplate, not logic)
+- Critical gap: Test coverage at 4%
+
+---
+
+## Priority 1: Safe Deletions (29 dead exports + 1 isolated symbol)
+
+**Source:** `scip-query dead --min-loc 5` + `scip-query isolated --min-loc 3`
+
+These are `export`ed functions that are only called within their own file, or not called at all. Remove `export` or delete entirely.
+
+| File | Symbol | LOC | Classification |
+|---|---|---|---|
+| `src/symbol-parser.ts:116` | `parseDescriptors()` | 85 | dead export |
+| `src/queries/slice.ts:98` | `forwardSlice()` | 64 | dead export |
+| `src/queries/complexity.ts:78` | `countBranches()` | 54 | dead export |
+| `src/queries/slice.ts:44` | `backwardSlice()` | 53 | dead export |
+| `src/queries/similar.ts:143` | `getAllCalleeFingerprints()` | 50 | dead export |
+| `src/queries/similar-chains.ts:184` | `editDistance()` | 44 | dead export |
+| `src/queries/similar-chains.ts:137` | `dfsChains()` | 38 | dead export |
+| `src/queries/similar-files.ts:105` | `compareProfiles()` | 35 | dead export |
+| `src/queries/similar-files.ts:60` | `buildFileProfiles()` | 21 | dead export |
+| `src/queries/similar-files.ts:82` | `findUniversalDependencies()` | 22 | dead export |
+| `src/setup.ts:121` | `getScipDownloadUrl()` | 25 | dead export |
+| `src/query-support.ts:160` | `calleeQueryParams()` | 17 | dead export |
+| `src/queries/similar.ts:126` | `findCallees()` | 16 | dead export |
+| `src/cli.ts:17` | `openDb()` | 23 | dead export |
+| `src/cli.ts:41` | `withDb()` | 8 | dead export |
+| `src/cli.ts:50` | `runQuery()` | 8 | dead export |
+| `src/cli.ts` | `formatBytes()` | 6 | dead export |
+| `src/cli.ts` | `formatStatus()` | 16 | dead export |
+| `src/queries/similar-chains.ts:121` | `generateChains()` | 15 | dead export |
+| `src/queries/similar-chains.ts:231` | `getCommonPrefix()` | 8 | dead export |
+| `src/queries/similar-chains.ts:240` | `getCommonSuffix()` | 10 | dead export |
+| `src/queries/similar-chains.ts:251` | `isSubChain()` | 6 | dead export |
+| `src/queries/similar.ts:194` | `intersection()` | 7 | dead export |
+| `src/queries/similar.ts:202` | `difference()` | 7 | dead export |
+| `src/queries/similar.ts:210` | `unionSize()` | 5 | dead export |
+| `src/gitignore-filter.ts:53` | `findGitignoreFiles()` | 26 | dead export |
+| `src/reindex/index.ts:114` | `ensureBinary()` | 7 | dead export |
+| `src/config.ts:51` | `resolveCacheDir()` | 19 | dead export |
+| `src/config.ts:90` | `writeMetaFile()` | 12 | dead code (isolated) |
+
+**Action:** Remove `export` keyword from all of these. Delete `writeMetaFile()` entirely (never called). This is ~1,712 LOC of leaked internal surface.
+
+**Risk:** Zero. These are private implementation details incorrectly exported. Removing `export` doesn't change behavior.
+
+**False positives excluded:** `cli.ts` module, `reindex-worker.ts` module, `postinstall.ts` module, `index.ts` module (all entry points).
+
+---
+
+## Priority 2: Structural Fixes
+
+### 2a. Duplicate `HealthReport` type
+
+**Source:** `scip-query stale-abstractions --min-loc 5`
+
+`HealthReport` is defined in both `src/types.ts:380-399` and `src/queries/health.ts:22-46`. The one in `health.ts` is a local re-declaration.
+
+**Action:** Remove the `HealthReport` interface from `queries/health.ts` and import from `types.ts`. ~25 LOC.
+
+### 2b. Unused `ReindexOptions` interface
+
+**Source:** `scip-query stale-abstractions`
+
+`ReindexOptions` in `src/reindex/index.ts:7-21` has 0 consumers. It may be intended for programmatic API consumers but is currently dead.
+
+**Action:** Verify intent. If unused, remove. 15 LOC.
+
+---
+
+## Priority 3: Consolidation Opportunities
+
+**Source:** `scip-query similar --min-similarity 0.6` + `scip-query convergence`
+
+10 function pairs at 60%+ similarity, but convergence analysis reveals the overlap is **shared boilerplate** (db, types, shortenSymbol imports), not logic duplication. Every query module follows the same pattern: import db → query SQLite → filter → map results → shorten symbols. This is correct architecture, not a problem.
+
+**Action:** Optional low-priority refactor — extract a `withFilteredSymbols(db, scope, callback)` helper to reduce per-query scaffolding. Not urgent.
+
+---
+
+## Priority 4: Extraction Opportunities
+
+**Source:** `scip-query extract-candidates --min-loc 10 --min-callees 4`
+
+| File | LOC | Clusters | Action |
+|---|---|---|---|
+| `similar-chains.ts` | 258 | 2 (100% isolated each) | Split edit-distance + chain-generation into `chain-utils.ts` |
+| `setup.ts` | 198 | 2 | Logically grouped (install vs detect) — no action |
+| `types.ts` | 593 | 2 | Type barrel — consider splitting if it keeps growing |
+
+**Action:** `similar-chains.ts` is the only actionable extraction. The two clusters (similarity logic vs edit-distance/chain-generation) are fully isolated.
+
+---
+
+## Priority 5: Indirection Removal
+
+**Source:** `scip-query wrapper-candidates` + `scip-query passthrough-candidates`
+
+- **Wrappers:** 4 found (`PathFilter`, `DescriptorSuffix`, `ScipLocalSymbol`, `ScipDescriptor`). All are type definitions consumed by core modules. Inlining would reduce clarity. **No action.**
+- **Passthroughs:** 0 found. Clean.
+
+---
+
+## Priority 6: Convention Alignment
+
+**Source:** `scip-query drift --min-deviation 40`
+
+9 files deviate. 4 are expected (barrel files, entry points, orchestrators). 5 are worth reviewing:
+
+| File | Deviation | Issue |
+|---|---|---|
+| `postinstall.ts` | 100% | Only imports `setup.ts` — expected for a thin entry point |
+| `query-support.ts` | 100% | Imports `db.ts` but not `types.ts` — expected, it provides helpers not query results |
+| `trace.ts` | 43% | Missing `query-support.ts` import — uses `db.localSymbolPredicate` directly |
+| `watch.ts` | 50% | Imports `config.ts` + `gitignore-filter.ts` — unique among src/ siblings, expected |
+| `reindex/index.ts` | 50% | Imports sibling modules — expected for an orchestrator |
+
+**Action:** `trace.ts` is the only questionable deviation — it could potentially use `query-support.ts` helpers. Low priority.
+
+---
+
+## Structural Metrics
+
+| Metric | Value | Assessment |
+|---|---|---|
+| Circular dependencies | 0 | Clean |
+| Max dependency chain depth | 6 | Acceptable (barrel → orchestrator → query → support → db → filter) |
+| Top coupling bottleneck | `queries/index` (score 192) | Barrel file — expected |
+| Top complexity hotspot | `types.ts` (score 121, 593 LOC) | Growing — monitor |
+| Test coverage | **4%** (7/168 symbols) | **Critical gap** |
+| Doc coverage | 100% (163/163) | Excellent |
+
+---
+
+## Action Plan
+
+| # | Action | LOC Impact | Risk | Effort |
+|---|---|---|---|---|
+| 1 | Remove `export` from 29 dead exports | -0 (keyword removal) | Zero | 15 min |
+| 2 | Delete `writeMetaFile()` | -12 | Zero | 1 min |
+| 3 | Remove duplicate `HealthReport` from `health.ts` | -25 | Zero | 2 min |
+| 4 | Verify/remove unused `ReindexOptions` | -15 | Low | 2 min |
+| 5 | Split `similar-chains.ts` clusters | 0 (structural) | Low | 15 min |
+| 6 | Add tests for `db`, `query-support`, `symbol-parser` | +200-400 | Zero | 1-2 hrs |
+| 7 | Monitor `types.ts` growth (593 LOC) | — | — | — |
+
+**Quick wins (items 1-4):** 20 minutes, ~52 LOC removed, zero risk.
+**Test coverage (item 6):** Most impactful long-term investment. Core infrastructure at 4% is the biggest risk in this codebase.