scip-query

Language-agnostic code intelligence CLI powered by SCIP indexes. Index any codebase, then query it for references, dependencies, dead code, similarity, coupling, and more — without an IDE or language server running.

Works with every language that has a SCIP indexer: TypeScript, JavaScript, Vue, Java, Scala, Kotlin, Rust, Python, Ruby, Go, C/C++, C#, Visual Basic, Dart, PHP.

Workflows

For goal-oriented usage guides (not just command reference), see Agent Guide:

• Understand a system — map a module, trace symbols, check blast radius
• Write an implementation plan — identify contracts, map dependencies, find reusable code
• De-bloat a codebase — prioritized cleanup from dead code to pattern drift
• Assess code quality — health score, complexity hotspots, coupling risks
• Verify change impact — diff impact, transitive blast radius, consumer blast radius

Quick Start

# Install
npm install -g scip-query
scip-query install-skills            # installs built-in Codex/Claude skills, including scip-language-playbook

# Index your project (auto-detects language)
scip-query reindex

# Start querying
scip-query stats
scip-query health                        # full codebase health report
scip-query symbols src/auth.service.ts
scip-query refs login
scip-query affected login                # transitive blast radius
scip-query dead --min-loc 10
scip-query similar --min-similarity 0.5
scip-query diff-impact                   # what did my changes affect?

Prerequisites

• Node.js >= 18
• scip CLI — Install from releases (converts index to SQLite)
• A language-specific SCIP indexer for your project:

| Language | Indexer | Install | |---|---|---| | TypeScript / JavaScript / Vue | scip-typescript | npm install -g @sourcegraph/scip-typescript | | Java / Scala / Kotlin | scip-java | releases | | Rust | rust-analyzer | Ships with rust-analyzer (rust-analyzer scip) | | Python | scip-python-plus | npm install -g scip-python-plus | | Go | scip-go | go install github.com/sourcegraph/scip-go@latest | | Ruby | scip-ruby | releases | | C / C++ | scip-clang | releases | | C# / VB | scip-dotnet | releases | | Dart | scip-dart | releases | | PHP | scip-php | releases |

For Python, the npm package is scip-python-plus. Depending on which version you installed, the executable on your PATH may be scip-python, scip-python-plus, or both. scip-query accepts either name.

Vue single-file components (.vue) are handled by the JavaScript/TypeScript indexer. scip-query extracts the <script> block (or <script setup>, picking the language from the lang= attribute) and parses it as TS/JS so symbol, reference, and import queries cover Vue components alongside regular .ts/.js files.

How It Works

1. A SCIP indexer analyzes your source code using the actual compiler/type checker and produces a index.scip protobuf file containing every symbol, definition, and reference — fully type-resolved.
2. The scip CLI converts the protobuf to a SQLite database (index.db).
3. scip-query runs SQL queries against that database to answer questions about your codebase.

Because the index comes from the real compiler, direct symbol, definition, and reference queries are precise — not grep-based approximations. When a language index is missing enough call-site detail for higher-level analyses, scip-query can fall back to source parsing and identifier recovery so those commands stay useful, but they should be treated as source-backed heuristics rather than compiler-proof facts.

Configuration

Per-project config

Run scip-query init to generate a .scipquery.json in your project root:

{
  "languages": ["typescript"],
  "watch": {
    "enabled": false,
    "debounceMs": 30000,
    "cooldownMs": 60000
  },
  "indexer": {
    "typescript": {
      "pnpmWorkspaces": true
    }
  }
}

Environment variables

| Variable | Purpose | |---|---| | SCIP_QUERY_PROJECT_ROOT | Override the project root directory | | SCIP_QUERY_INDEX_DB | Override the SQLite database path | | SCIP_QUERY_INDEX_SCIP | Override the SCIP protobuf path | | SCIP_QUERY_CACHE_DIR | Override the cache directory |

Index storage

By default, indexes are stored in ~/.cache/scip-query/projects/<hash>/ (following XDG conventions). This keeps your project directory clean. Override with the dbPath field in .scipquery.json or the SCIP_QUERY_CACHE_DIR environment variable.

Gitignore integration

All query results are filtered through your project's .gitignore. Build artifacts (dist/, target/, __pycache__/), dependency directories (node_modules/, vendor/), and virtual environments (.venv/) are automatically excluded. If no .gitignore exists, sensible defaults are applied.

Command Reference

Index Management

reindex

Index (or re-index) the codebase. Auto-detects which languages are present, runs the appropriate SCIP indexer, and converts the output to SQLite.

scip-query reindex
scip-query reindex --language typescript
scip-query reindex --pnpm-workspaces        # for pnpm monorepos

Options:

• -l, --language <lang> — Index only this language (can repeat)
• --pnpm-workspaces — Enable pnpm workspace support (TypeScript)

When to use: After significant code changes, after pulling, or before running analysis commands for the first time.

watch

Watch the project for file changes and automatically reindex in the background. Uses a single-flight model: only one reindex runs at a time, changes during reindex set a dirty flag for one follow-up run.

scip-query watch
scip-query watch --debounce 60000           # wait 60s after last change

Options:

• --debounce <ms> — Milliseconds to wait after the last file change before reindexing (default: 30000)
• --cooldown <ms> — Minimum milliseconds between reindex completions (default: 60000)

How it works: Watches for file changes (respecting .gitignore), debounces, runs reindex in a child process writing to a temp file, then atomically swaps the database. Queries against the old index continue working during reindex — no downtime.

status

Show the current index status: where it's stored, how big it is, when it was built.

scip-query status

stats

Show index statistics: document count, symbol count, definition count, reference count, database size.

scip-query stats
# Documents:   42
# Symbols:     1111
# Definitions: 803
# References:  2094
# Index size:  660 KB
# Last built:  2026-04-10 16:12:58

Value: Quick sanity check that your index is healthy and up to date.

init

Create a .scipquery.json config file in the project root with auto-detected languages and default settings.

scip-query init

Navigation

These commands help you understand and navigate the codebase — find where things are defined, where they're used, and how files relate to each other.

files <pattern>

Find indexed files matching a path pattern.

scip-query files auth              # all files with "auth" in the path
scip-query files .service.ts       # all service files

Value: Quick file discovery without leaving the terminal. Respects gitignore.

symbols <file>

List all symbols defined in a file with their line ranges and type signatures.

scip-query symbols auth.service.ts
#   1-50   AuthService  — class AuthService
#   5-20   AuthService:login()  — login(email: string): Promise<Token>
#   22-35  AuthService:logout()  — logout(): void

Value: Instant overview of a file's API surface — like a table of contents with type information. Faster than reading the file.

methods <className>

List all methods of a class with their line ranges.

scip-query methods AuthService
#   5-20   login
#   22-35  logout

Value: Quick method inventory for a class. Useful when you need to know what a class can do without reading its full source.

refs <symbol>

Find every file that references a symbol, grouped by file with line numbers.

scip-query refs login
# src/controllers/auth.controller.ts
#   line 15
# src/__tests__/auth.test.ts
#   line 8

Value: "Who uses this?" — the most fundamental code intelligence question. Compiler-resolved, so no false positives from string matches.

trace <symbol>

Show a symbol's definition (with signature) and every file that references it. Like refs but also shows you where the symbol is defined.

scip-query trace parseSymbol
# ═══ DEFINITION ═══
#   src/symbol-parser.ts:35-99  — parseSymbol(raw: string): ScipSymbol | ScipLocalSymbol
#
# ═══ REFERENCED BY ═══
#   src/index.ts
#   src/symbol-parser.ts

Value: End-to-end symbol investigation. Answers "where is this defined, what's its signature, and who uses it?" in one command.

outline <file>

Tree-structured view of all symbols in a file, using parent-child nesting when the indexer provides enclosing_symbol data.

scip-query outline db.ts
# 0-111  src:db
# 19-110  src:db:ScipDatabase
#   24-29  src:db:ScipDatabase:constructor()
#   32-34  src:db:ScipDatabase:setPathFilter()

Value: Visual file structure at a glance — like an IDE's outline panel but in the terminal.

hierarchy <symbol>

Show a symbol's ancestry chain — from the symbol up through its enclosing scopes (method → class → module → file).

scip-query hierarchy login
# src:auth:AuthService:login()
#   src:auth:AuthService

Value: Understand where a symbol lives in the nesting hierarchy. Requires the indexer to populate enclosing_symbol.

members <symbol>

Find all direct children of a symbol (methods, fields, nested types) using the enclosing_symbol relationship.

scip-query members AuthService
#   5-20   [method]  login
#   22-35  [method]  logout
#   37-37  [term]    tokenSecret

Value: Like methods but includes fields, nested types, and anything else directly inside a symbol. Requires enclosing_symbol support from the indexer.

call-graph <symbol>

Show what calls a symbol (incoming) and what the symbol calls (outgoing).

scip-query call-graph shortenSymbol
# Symbol: src:symbol-parser:shortenSymbol()
#
# ═══ CALLERS (16) ═══
#   src/queries/dead.ts        src:queries:dead
#   src/queries/hotspots.ts    src:queries:hotspots
#   ...
#
# ═══ CALLEES (0) ═══

Value: Understand a function's role in the call chain. High caller count = widely used, be careful changing it. Many callees = complex function, may need decomposition.

Dependency Analysis

These commands map how files and modules depend on each other — forward deps, reverse deps, and full module maps.

deps <file>

List all internal files that this file depends on (forward dependencies).

scip-query deps cli.ts
# src/config.ts
# src/db.ts
# src/queries/index.ts
# src/reindex/index.ts

Value: "What does this file need to work?" Useful before refactoring — tells you what you're coupled to.

rdeps <file>

List all files that depend on this file (reverse dependencies).

scip-query rdeps symbol-parser
# src/index.ts
# src/queries/dead.ts
# src/queries/hotspots.ts
# ...

Value: "Who breaks if I change this?" The blast radius of a modification. High rdeps count = be very careful with changes.

system <module>

Full module map: all files in the module, all exported symbols, all inbound and outbound dependencies.

scip-query system queries
# ═══ FILES ═══
# src/queries/dead.ts
# src/queries/deps.ts
# ...
#
# ═══ EXPORTED SYMBOLS ═══
#   8-124  dead()
#   4-23   deps()
# ...
#
# ═══ DEPENDS ON (internal) ═══
#   src/db.ts
#   src/symbol-parser.ts
#
# ═══ DEPENDED ON BY ═══
#   src/cli.ts
#   src/index.ts

Value: Complete module overview in one command. Shows the module's interface, its internal structure, and its position in the dependency graph.

surface <module>

What symbols do external consumers actually use from this module? The true public API — not what's exported, but what's actually imported and referenced by other modules.

scip-query surface db.ts
#   src/cli.ts → ScipDatabase
#   src/cli.ts → ScipDatabase:close()
#   src/queries/dead.ts → ScipDatabase:all()
#   src/queries/dead.ts → ScipDatabase:isIgnored()

Value: Distinguish "exported" from "actually used." If you export 20 symbols but only 5 are referenced externally, the other 15 are candidates for removal or making private.

imports <file>

What symbols does this file import? Uses SCIP role=2 (import) mentions.

scip-query imports auth.controller.ts
#   AuthService:login()  ← src/services/auth.service.ts
#   validateInput()      ← src/utils/validation.ts

Value: Quick import inventory. Note: depends on the indexer emitting role=2 — not all do (e.g., scip-typescript currently doesn't).

imported-by <symbol>

Which files import this symbol?

scip-query imported-by AuthService
#   src/controllers/auth.controller.ts
#   src/__tests__/auth.test.ts

unused-imports <file>

Find imports in a file that are never referenced in the same file — likely unused imports that should be cleaned up.

scip-query unused-imports auth.controller.ts
#   formatDate  in src/controllers/auth.controller.ts
# 1 unused import(s)

Value: Automated unused import detection. Note: same role=2 limitation as imports.

Code Quality & Dead Code

These commands find code that can be removed, consolidated, or cleaned up.

dead [scope]

Find dead exports: symbols defined locally with no cross-file references. Distinguishes between "dead code" (not referenced anywhere, even in the same file) and "dead exports" (used locally but never imported by other files).

scip-query dead --min-loc 10
scip-query dead src/utils --skip-barrels --include-members

Options:

• --min-loc <n> — Only show symbols >= N lines (default: 1)
• --include-tests — Include test files in results (excluded by default)
• --skip-barrels — Ignore references from inactive barrel re-export files
• --include-members — Include class members (module-level only by default)
• --only-dead — Show only [dead code] symbols (skip [file-internal only])
• --only-internal — Show only [file-internal only] symbols (skip [dead code])

Value: Find code you can delete. The --skip-barrels flag is key when a codebase has unused barrels, but it now keeps live entry-surface barrels counted so active exports do not look dead.

isolated

Find completely orphaned symbols: defined locally, not referenced by anything (not even in the same file), and not referencing anything external. These are truly disconnected from the codebase graph.

scip-query isolated --min-loc 5
scip-query isolated --scope src/utils

Options:

• -s, --scope <path> — Limit to files matching path
• --min-loc <n> — Minimum lines of code (default: 3)

Value: Stricter than dead — these symbols serve no purpose at all. Safe deletion candidates.

Codebase Metrics

These commands measure structural properties of the codebase — hotspots, coupling, bottlenecks, fan-in/out.

hotspots

Find the most-referenced symbols in the codebase. These are the choke points where changes have the widest blast radius.

scip-query hotspots -n 15
#   refs  files  symbol
#   ────  ─────  ──────
#     39     39  src:types
#     33     31  src:db:ScipDatabase
#     27     27  src:db:ScipDatabase:all()

Options:

• -n, --limit <n> — Number of results (default: 30)
• -s, --scope <path> — Limit to files matching path

Value: Identify the symbols where a bug or breaking change would affect the most consumers. Hotspots deserve the most careful review and the most stable interfaces.

fan-in [symbol]

How many distinct files reference a symbol. Without an argument, shows the top N symbols by fan-in across the codebase.

scip-query fan-in ScipDatabase
#    19 files  ScipDatabase
#    16 files  ScipDatabase:all()
#    13 files  ScipDatabase:isIgnored()

scip-query fan-in -n 10
#   files  symbol
#   ─────  ──────
#      31  ScipDatabase
#      27  ScipDatabase:all()

Options:

• -n, --limit <n> — Number of results for top mode (default: 30)
• -s, --scope <path> — Limit to files matching path

Value: High fan-in = widely depended upon. Changes to high fan-in symbols have large blast radius. These symbols should have stable interfaces and careful review.

fan-out [file]

How many external symbols a file references. Without an argument, shows the top N files by fan-out. High fan-out files are fragile — they depend on many things, so upstream changes are more likely to break them.

scip-query fan-out cli.ts
#    23 symbols  src/cli.ts

scip-query fan-out -n 10
#   symbols  file
#   ───────  ────
#       68  src/queries/index.ts
#       23  src/cli.ts

Options:

• -n, --limit <n> — Number of results for top mode (default: 30)
• -s, --scope <path> — Limit to files matching path

Value: Identify files that are tightly coupled to the rest of the codebase. High fan-out files are the first to break when dependencies change.

bottlenecks

Find coupling hubs: symbols with both high fan-in (many consumers) AND high fan-out (many dependencies). Score = fan-in × fan-out. These are the most dangerous symbols to change — they sit at the intersection of many dependency paths.

scip-query bottlenecks -n 10
#   score  fan-in  fan-out  symbol
#   ─────  ──────  ───────  ──────
#     136       2       68  src:queries:index
#     124      31        4  src:db:ScipDatabase

Options:

• -n, --limit <n> — Number of results (default: 20)
• -s, --scope <path> — Limit to files matching path
• --min-fan-in <n> — Minimum fan-in (default: 2)
• --min-fan-out <n> — Minimum fan-out (default: 2)

Value: These are the architectural pressure points. A symbol with fan-in=20 and fan-out=5 is both heavily depended upon and heavily dependent — changes to it are risky in both directions.

coupling [file1] [file2]

Measure coupling between two specific files (how many symbols they share), or find the most coupled file pairs across the codebase.

scip-query coupling db.ts cli.ts
# db.ts ↔ cli.ts: 4 shared symbols

scip-query coupling -n 10
#   shared  file1 → file2
#   ──────  ─────────────
#        5  src/db.ts → src/queries/stats.ts

Options:

• -n, --limit <n> — Number of results for top mode (default: 20)
• -s, --scope <path> — Limit to files matching path

Value: Quantify how tightly two files are linked. High coupling between files that shouldn't be related is a design smell. Useful for identifying candidates for interface extraction.

cycles

Detect circular dependency chains between files. A cycle exists when file A depends on B, B on C, and C on A.

scip-query cycles
# No circular dependencies found.

scip-query cycles --scope src/services
# Cycle 1 (3 files):
#   src/services/auth.ts →
#   src/services/user.ts →
#   src/services/auth.ts (cycle)

Options:

• -s, --scope <path> — Limit to files matching path
• --max-depth <n> — Maximum cycle depth (default: 10)

Value: Circular dependencies make code harder to test, harder to understand, and harder to refactor. This command finds them so you can break the cycles.

deep-chains

Find the longest transitive dependency chains in the codebase. A chain A → B → C → D means A depends on B, B on C, C on D.

scip-query deep-chains -n 5 --min-depth 4
# Chain 1 (depth 5):
#   → src/cli.ts
#   → src/queries/index.ts
#   → src/queries/surface.ts
#   → src/db.ts
#   → src/types.ts

Options:

• -n, --limit <n> — Number of chains to show (default: 10)
• -s, --scope <path> — Limit to files matching path
• --min-depth <n> — Minimum chain depth (default: 3)

Value: Long dependency chains mean changes at the bottom ripple through many layers. If chains are excessively deep, it may indicate that the architecture needs flattening or that intermediate layers aren't adding value.

by-kind <kind>

Find symbols by their SCIP symbol kind (class, interface, enum, function, struct, method, etc.).

scip-query by-kind class
scip-query by-kind interface --scope src/types
scip-query by-kind 68                          # kind number for Struct

Options:

• -s, --scope <path> — Limit to files matching path
• -n, --limit <n> — Number of results (default: 100)

Value: Structural inventory — "how many classes do we have?", "where are all the interfaces?", "list every enum." Requires the indexer to populate the kind field.

kind-counts

Show a histogram of symbol kinds in the codebase.

scip-query kind-counts
#   count  kind
#   ─────  ────
#      45  Class (9)
#      23  Interface (27)
#      12  Enum (16)

Options:

• -s, --scope <path> — Limit to files matching path

Value: Architectural overview — what types of symbols make up the codebase? Useful for understanding whether a codebase is class-heavy, function-heavy, interface-driven, etc.

Similarity & Consolidation

These commands find duplication, redundancy, and extraction opportunities — the tools for de-bloating a codebase.

similar [symbol]

Find functions with similar callee fingerprints using TF-IDF weighted cosine similarity. Each callee is weighted by how rare it is across the codebase — two functions sharing a niche helper (sendWelcomeEmail()) score much higher than two functions sharing infrastructure callees (db.all(), shortenSymbol()). The "shared" list shown for each pair is the high-IDF (significant) intersection, not every shared callee.

Without a symbol argument, finds the top N most similar pairs across the codebase. With a symbol, finds what's most similar to that specific function.

scip-query similar --min-similarity 0.5
# 80% similar:
#   A: by-kind  (src/queries/by-kind.ts)
#   B: call-graph  (src/queries/call-graph.ts)
#   Shared: ScipDatabase, db.all(), db.get(), db.isIgnored(), shortenSymbol()

scip-query similar dead --min-similarity 0.3
# 64% similar:
#   A: dead  (src/queries/dead.ts)
#   B: bottlenecks  (src/queries/bottlenecks.ts)
#   Shared callees: db, ScipDatabase, db.all(), db.isIgnored(), shortenSymbol()
#   Only in A: DeadOptions, DeadSummary, DeadSymbolResult
#   Only in B: BottleneckResult

Options:

• --min-similarity <n> — Minimum cosine similarity 0-1 (default: 0.4)
• -n, --limit <n> — Number of results (default: 20)
• -s, --scope <path> — Limit to files matching path
• --min-callees <n> — Minimum callees to consider a symbol (default: 4)
• --cross-file-only — Only show cross-file pairs (skip same-file matches)

Value: Finds "these two functions do basically the same thing" at scale. The shared callee list shows exactly what's duplicated. The unique callees show where they diverge — that's the parameterization point for a consolidated version.

similar-files [file]

Find files with similar dependency profiles using Jaccard similarity on their dependency sets. Files that import the same modules are structurally doing similar work.

scip-query similar-files --min-similarity 0.7
# 100% similar:
#   src/queries/symbols.ts
#   src/queries/system.ts
#   Shared deps (4): db.ts, types.ts, symbol-parser.ts, clean-signature.ts

scip-query similar-files auth.controller.ts

Options:

• --min-similarity <n> — Minimum Jaccard similarity 0-1 (default: 0.5)
• -n, --limit <n> — Number of results (default: 20)
• -s, --scope <path> — Limit to files matching path
• --min-deps <n> — Minimum dependencies on the smaller side (auto-tunes by default; pass to override)

Value: Finds copy-paste file variants and structurally redundant modules. When two files have 90%+ dependency overlap, they're likely doing similar jobs and should share code or be merged.

similar-chains

Find end-to-end dependency flows through the codebase that are structurally similar but diverge at a few points. Uses edit distance on the file-node sequences.

scip-query similar-chains --min-similarity 0.5
# ── Chain pair 1 (67% similar, 1 divergence point) ──
#   Chain A: auth.controller.ts → auth.service.ts → user.repo.ts
#   Chain B: org.controller.ts  → org.service.ts  → user.repo.ts
#   Common suffix: user.repo.ts
#   Divergence points (consolidation targets):
#     [0] auth.controller.ts  ↔  org.controller.ts
#     [1] auth.service.ts     ↔  org.service.ts

Options:

• --min-similarity <n> — Minimum chain similarity 0-1 (default: 0.5)
• -n, --limit <n> — Number of results (default: 15)
• -s, --scope <path> — Limit to files matching path
• --min-length <n> — Minimum chain length (default: 3)
• --max-length <n> — Maximum chain length (default: 8)

Value: This is the most powerful consolidation finder. It detects "you have two parallel end-to-end mechanisms doing the same thing through different code paths." The divergence points are exactly where to extract a shared abstraction. Unlike function-level similarity, this catches architectural-level duplication.

extract-candidates

Find large functions with natural extraction seams — isolated groups of callees that form distinct clusters within a single function. When a function calls symbols A, B, C together and separately calls D, E, F, that's two potential extracted functions.

scip-query extract-candidates --min-loc 20 --min-callees 6
# src/services/auth.ts:10-85  processAuth  (75 LOC, 12 callees)
#   Cluster 1 (92% isolated, 4 callees):
#     validateToken, parseJwt, checkExpiry, refreshToken
#   Cluster 2 (88% isolated, 3 callees):
#     formatUser, enrichProfile, cacheResult

Options:

• -s, --scope <path> — Limit to files matching path
• --min-loc <n> — Minimum function LOC (default: 10)
• --min-callees <n> — Minimum callees to analyze (default: 6)
• -n, --limit <n> — Number of results (default: 20)

Value: Identifies concrete extraction opportunities within large functions. Each cluster is a group of callees that are used together but independently from the rest of the function — a natural candidate for "Extract Method" refactoring. The isolation score tells you how cleanly the extraction would separate.

Impact & Planning

affected <symbol>

Full transitive closure of symbols that could break if this symbol changes. BFS through the mention graph at configurable depth.

scip-query affected login --max-depth 3
#   ── Depth 1 ──
#   src/controllers/auth.controller.ts  handleLogin
#   src/__tests__/auth.test.ts  authTests
#
#   ── Depth 2 ──
#   src/routes/index.ts  routes

Options:

• --max-depth <n> — Maximum traversal depth (default: 5)
• -s, --scope <path> — Limit to files matching path

Value: "If I change this, what's the full blast wave?" Goes beyond direct rdeps to show consumers-of-consumers.

change-surface <file>

Pre-change briefing for a file: every exported symbol, consumer count, and blast-radius risk.

scip-query change-surface auth.service.ts
# File: src/services/auth.service.ts
# External consumers: 45
#
#   1-50   AuthService  [12 consumers] *** HIGH RISK ***
#   5-20   login()      [8 consumers]  * medium risk *
#   22-35  logout()     [0 consumers]

Value: One command before modifying any file. Shows what's exported, who uses it, and which symbols carry the largest downstream blast radius.

diff-impact

Compute affected symbols from the current git diff.

scip-query diff-impact
scip-query diff-impact --base main
# Changed files: 3
# Changed symbols: 12
# Affected consumer files: 28

Options:

• --base <ref> — Git ref to diff against (default: HEAD)

Value: Run before committing. Shows everything your changes affect and which consumer files sit downstream of the changed symbols.

De-bloating

drift [module]

Detect files that deviate from their directory's typical dependency pattern.

scip-query drift
# src/services/legacy-auth.ts  (65% deviation from src/services)
#   Missing expected: validator.ts, logger.ts
#   Unexpected:       raw-sql.ts, deprecated-crypto.ts

Value: Finds files that don't follow their neighbors' conventions. The outliers are either legacy code needing migration or intentional exceptions needing documentation.

wrapper-candidates

Find symbols only called by one consumer — potential premature abstractions.

scip-query wrapper-candidates --max-loc 15
#   src/utils/format.ts:10-18  formatCurrency  (8 LOC)
#     Only called by: formatInvoice  (fan-in: 12)

Options:

• -s, --scope <path> — Limit to files matching path
• --max-loc <n> — Maximum LOC (default: 15)
• -n, --limit <n> — Number of results (default: 30)

Value: If a function is only called by one other function, it might be inlineable. The smaller it is, the stronger the signal.

passthrough-candidates

Find functions that forward to exactly one callee — pure indirection.

scip-query passthrough-candidates
#   src/services/user.ts:5-10  getUser  (5 LOC)
#     Forwards to: userRepo.findById  (src/repos/user.repo.ts)

Options:

• -s, --scope <path> — Limit to files matching path
• --max-loc <n> — Maximum LOC (default: 15)
• -n, --limit <n> — Number of results (default: 30)

Value: Functions that just call one other function without adding logic. Either inline them or verify they serve a purpose (testing boundary, dependency inversion).

stale-abstractions

Find types, interfaces, and classes with 0-1 cross-file consumers.

scip-query stale-abstractions --min-loc 5
#   src/types/deprecated.ts:1-25  OldUserType  (25 LOC, unused)
#   src/interfaces/single.ts:1-15  ISingleUse  (15 LOC, 1 consumer)

Options:

• -s, --scope <path> — Limit to files matching path
• --min-loc <n> — Minimum LOC (default: 3)
• -n, --limit <n> — Number of results (default: 30)
• --include-low-confidence — Include 1-consumer classes (usually encapsulation, not stale)

Value: An interface with one implementation isn't an abstraction — it's indirection. Finds over-engineering.

complexity-hotspots

Composite complexity score per symbol: LOC x fan-in x fan-out.

scip-query complexity-hotspots -n 10
#   score   LOC  fan-in  fan-out  callees  symbol
#   ─────  ────  ──────  ───────  ───────  ──────
#   101.7   541      47        0       16  types
#    31.3   279      28        5       33  symbol-parser

Options:

• -s, --scope <path> — Limit to files matching path
• --min-loc <n> — Minimum LOC (default: 10)
• -n, --limit <n> — Number of results (default: 20)

Value: The symbols most likely to contain bugs and be hardest to modify. High score = high LOC + many consumers + many dependencies.

Composite Reports

health

Single command that runs all analyses and produces a prioritized action list with a health score.

scip-query health
# Codebase Health Score: 72/100
# 54 files | 1501 symbols | 900 KB
#
# Findings:
#   Dead code:          12 symbols (340 LOC)
#   Similar pairs:      8
#   Stale abstractions: 5
#
# Prioritized Actions:
#   1. [low effort / high impact] 12 symbols with zero references — safe to delete (~340 LOC)
#   2. [low effort / medium impact] 5 types with 0-1 consumers — premature abstraction
#   3. [medium effort / medium impact] 8 pairs with >60% callee overlap — consolidation candidates

scip-query health --json    # JSON output for programmatic use

Options:

• -s, --scope <path> — Limit to files matching path
• --json — Output as JSON

Value: The one command to rule them all. Runs every cleanup analysis, scores the codebase, and tells you exactly what to fix and in what order.

convergence <symbol1> <symbol2>

Given two similar functions (from similar), show what a consolidated version would look like.

scip-query convergence bottlenecks hotspots
# 82% callee overlap
#
#   A: bottlenecks  (src/queries/bottlenecks.ts, 68 LOC)
#   B: hotspots     (src/queries/hotspots.ts, 54 LOC)
#
#   Shared callees (9): ScipDatabase, db.all(), db.isIgnored(), ...
#   Unique to A (1): BottleneckResult
#   Unique to B (1): HotspotResult
#
#   Strategy: Create a shared function with the 9 common callees.
#   Pass the 2 divergent callees as parameters or strategy callbacks.

Value: Turns "these two functions are similar" into a concrete refactoring prescription.

Source & Analysis

code <symbol>

Read the source code for a symbol, bounded to its definition range.

scip-query code shortenSymbol
scip-query code shortenSymbol -C 5    # 5 extra lines of context

Options:

• -C, --context <n> — Extra lines above/below the definition (default: 0)

Value: Read source without leaving the terminal. Language-agnostic — just reads the file at the line range from the index.

complexity <symbol>

Per-symbol complexity analysis: source-level branch counting + index-level metrics.

scip-query complexity login
#   LOC:                  41
#   Branches:             8
#   Cyclomatic estimate:  9
#   Callees:              5
#   Fan-in:               12
#   Fan-out:              3

Value: Combines source-level analysis (branch counting via language-aware regex) with graph-level metrics (fan-in, fan-out, callee count) for a complete complexity picture.

dataflow <symbol>

Reference-level dataflow: where data around a symbol comes from and where it goes.

scip-query dataflow login
#   ═══ DEFINED AT ═══
#     src/auth.service.ts:5
#   ═══ USED AT ═══
#     src/auth.controller.ts:15  in handleAuth
#   ═══ PRODUCERS (feeds into this) ═══
#     validateInput, formatName
#   ═══ CONSUMERS (this feeds into) ═══
#     sendEmail, logAudit

Value: Shows the data flow context: what other symbols are referenced alongside this one, what feeds in, what consumes it.

slice <symbol>

Reference-level program slicing: what affects a symbol (backward) or what it affects (forward).

scip-query slice login               # backward: what feeds in
scip-query slice login --forward     # forward: what this feeds into

Options:

• --forward — Forward slice instead of backward (default: backward)
• --depth <n> — Max transitive depth for backward slice (default: 3)

Value: Backward slice shows inputs/dependencies. Forward slice shows outputs/effects. Useful for tracing data flow through error handling and concurrency paths.

Additional Cleanup

redundant-reexports

Find barrel file re-exports that nobody imports through.

scip-query redundant-reexports
#   src/index.ts
#     resolveCacheDir()  (from src/config.ts)
#       barrel: 0 consumer(s) | direct: 0 consumer(s)

Options:

• -s, --scope <path> — Limit to files matching path
• -n, --limit <n> — Number of results (default: 30)

Value: Finds dead entries in inactive barrel files. Live barrels are skipped so shared entry surfaces like package roots and CLI registries do not show up as false positives.

similar-signatures

Find functions with near-identical type signatures (same parameter types and return type).

scip-query similar-signatures --min-loc 5
#   Signature: (email: string): Promise<Token>  (2 functions)
#     src/auth.ts:5-20   login   (15 LOC)
#     src/auth.ts:22-37  signup  (15 LOC)

Options:

• -s, --scope <path> — Limit to files matching path
• --min-loc <n> — Minimum LOC per function (default: 3)
• -n, --limit <n> — Number of groups (default: 20)

Value: Different signal from callee similarity — catches "same interface, different implementation" even when the internal logic differs completely.

Programmatic API

Every CLI command is also a TypeScript function. The queries namespace exports cover all of them — including the top* variants of fan-in, fan-out, and coupling, plus similarAll for the cross-codebase mode of similar:

import {
  ScipDatabase, createGitignoreFilter,
  health, affected, changeSurface, diffImpact,
  hotspots, similar, dead, convergence,
} from 'scip-query';

const filter = createGitignoreFilter('/path/to/project');
const db = new ScipDatabase({
  dbPath: '/path/to/index.db',
  indexPath: '/path/to/index.scip',
  projectRoot: '/path/to/project',
}, filter);

// Full health report
const report = health(db);
console.log(`Score: ${report.score}/100`);
console.log(`Actions: ${report.actions.length}`);

// Impact analysis
const blast = affected(db, 'login', { maxDepth: 3 });
const brief = changeSurface(db, 'auth.service.ts');
const impact = diffImpact(db, { base: 'main' });

// Consolidation
const pairs = similar(db, 'myFunction', { minSimilarity: 0.5 });
const recipe = convergence(db, 'funcA', 'funcB');

db.close();

License

Apache-2.0