scip-query 0.1.0

package/src/queries/hierarchy.ts

@@ -0,0 +1,49 @@
+import type { ScipDatabase } from '../db.js';
+import type { HierarchyNode } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Walk the enclosing_symbol chain upward to show a symbol's ancestry.
+ * e.g., method → class → module → file
+ *
+ * Falls back to parsing the SCIP symbol descriptor chain when
+ * enclosing_symbol is not populated by the indexer.
+ */
+export function hierarchy(db: ScipDatabase, symbolPattern: string): HierarchyNode[] {
+  // Find the symbol
+  const sym = db.get<{ symbol: string; enclosing_symbol: string | null }>(
+    `SELECT symbol, enclosing_symbol FROM global_symbols
+     WHERE symbol LIKE ? LIMIT 1`,
+    `%${symbolPattern}%`,
+  );
+
+  if (!sym) return [];
+
+  const chain: HierarchyNode[] = [
+    { symbol: sym.symbol, shortName: shortenSymbol(sym.symbol), depth: 0 },
+  ];
+
+  // Walk enclosing_symbol chain if available
+  let current = sym.enclosing_symbol;
+  let depth = 1;
+  const seen = new Set<string>([sym.symbol]);
+
+  while (current && !seen.has(current) && depth < 20) {
+    seen.add(current);
+    const parent = db.get<{ symbol: string; enclosing_symbol: string | null }>(
+      `SELECT symbol, enclosing_symbol FROM global_symbols WHERE symbol = ?`,
+      current,
+    );
+    if (!parent) break;
+
+    chain.push({
+      symbol: parent.symbol,
+      shortName: shortenSymbol(parent.symbol),
+      depth,
+    });
+    current = parent.enclosing_symbol;
+    depth++;
+  }
+
+  return chain;
+}

package/src/queries/hotspots.ts

@@ -0,0 +1,53 @@
+import type { ScipDatabase } from '../db.js';
+import type { HotspotResult } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Find the most-referenced symbols in the codebase — the choke points
+ * where changes have the widest blast radius.
+ */
+export function hotspots(
+  db: ScipDatabase,
+  opts: { limit?: number; scope?: string } = {},
+): HotspotResult[] {
+  const { limit = 30, scope } = opts;
+
+  const scopeFilter = scope ? `AND def_d.relative_path LIKE '%${scope}%'` : '';
+
+  const rows = db.all<{
+    symbol: string;
+    ref_count: number;
+    file_count: number;
+    defined_in: string;
+  }>(
+    `SELECT
+      gs.symbol,
+      COUNT(*) AS ref_count,
+      COUNT(DISTINCT ref_d.id) AS file_count,
+      def_d.relative_path AS defined_in
+    FROM mentions m
+    JOIN chunks c ON m.chunk_id = c.id
+    JOIN documents ref_d ON c.document_id = ref_d.id
+    JOIN global_symbols gs ON m.symbol_id = gs.id
+    JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
+    JOIN documents def_d ON der.document_id = def_d.id
+    WHERE m.role = 0
+      ${db.pathExclusionsFor('def_d')}
+      ${db.symbolNoiseFor('gs')}
+      ${scopeFilter}
+    GROUP BY gs.id
+    ORDER BY ref_count DESC
+    LIMIT ?`,
+    limit,
+  );
+
+  return rows
+    .filter((r) => !db.isIgnored(r.defined_in))
+    .map((r) => ({
+      symbol: r.symbol,
+      shortName: shortenSymbol(r.symbol),
+      refCount: r.ref_count,
+      fileCount: r.file_count,
+      definedIn: r.defined_in,
+    }));
+}

package/src/queries/imports.ts

@@ -0,0 +1,95 @@
+import type { ScipDatabase } from '../db.js';
+import type { ImportResult, UnusedImportResult } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * What symbols does this file import?
+ * Uses role=2 (import) from the SCIP mentions table.
+ */
+export function imports(db: ScipDatabase, filePattern: string): ImportResult[] {
+  const rows = db.all<{
+    symbol: string;
+    from_file: string;
+  }>(
+    `SELECT DISTINCT gs.symbol, def_d.relative_path AS from_file
+    FROM mentions m
+    JOIN chunks c ON m.chunk_id = c.id
+    JOIN documents imp_d ON c.document_id = imp_d.id
+    JOIN global_symbols gs ON m.symbol_id = gs.id
+    LEFT JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
+    LEFT JOIN documents def_d ON der.document_id = def_d.id
+    WHERE imp_d.relative_path LIKE ?
+      AND m.role = 2
+    ORDER BY def_d.relative_path, gs.symbol`,
+    `%${filePattern}%`,
+  );
+
+  return rows.map((r) => ({
+    symbol: r.symbol,
+    shortName: shortenSymbol(r.symbol),
+    fromFile: r.from_file ?? '(external)',
+  }));
+}
+
+/**
+ * Which files import this symbol?
+ */
+export function importedBy(db: ScipDatabase, symbolPattern: string): ImportResult[] {
+  const rows = db.all<{
+    symbol: string;
+    importer: string;
+  }>(
+    `SELECT DISTINCT gs.symbol, d.relative_path AS importer
+    FROM mentions m
+    JOIN chunks c ON m.chunk_id = c.id
+    JOIN documents d ON c.document_id = d.id
+    JOIN global_symbols gs ON m.symbol_id = gs.id
+    WHERE gs.symbol LIKE ?
+      AND m.role = 2
+    ORDER BY d.relative_path`,
+    `%${symbolPattern}%`,
+  );
+
+  return rows
+    .filter((r) => !db.isIgnored(r.importer))
+    .map((r) => ({
+      symbol: r.symbol,
+      shortName: shortenSymbol(r.symbol),
+      fromFile: r.importer,
+    }));
+}
+
+/**
+ * Find imports in a file that are never referenced (role=0) in the same file.
+ * These are likely unused imports.
+ */
+export function unusedImports(db: ScipDatabase, filePattern: string): UnusedImportResult[] {
+  const rows = db.all<{
+    symbol: string;
+    imported_in: string;
+  }>(
+    `SELECT gs.symbol, d.relative_path AS imported_in
+    FROM mentions m
+    JOIN chunks c ON m.chunk_id = c.id
+    JOIN documents d ON c.document_id = d.id
+    JOIN global_symbols gs ON m.symbol_id = gs.id
+    WHERE d.relative_path LIKE ?
+      AND m.role = 2
+      AND NOT EXISTS (
+        SELECT 1
+        FROM mentions ref_m
+        JOIN chunks ref_c ON ref_m.chunk_id = ref_c.id
+        WHERE ref_m.symbol_id = gs.id
+          AND ref_m.role = 0
+          AND ref_c.document_id = d.id
+      )
+    ORDER BY d.relative_path, gs.symbol`,
+    `%${filePattern}%`,
+  );
+
+  return rows.map((r) => ({
+    symbol: r.symbol,
+    shortName: shortenSymbol(r.symbol),
+    importedIn: r.imported_in,
+  }));
+}

package/src/queries/index.ts

@@ -0,0 +1,45 @@
+export { stats } from './stats.js';
+export { files } from './files.js';
+export { symbols } from './symbols.js';
+export { methods } from './methods.js';
+export { refs } from './refs.js';
+export { trace } from './trace.js';
+export { deps, rdeps } from './deps.js';
+export { system } from './system.js';
+export { surface } from './surface.js';
+export { dead } from './dead.js';
+export { hotspots } from './hotspots.js';
+export { imports, importedBy, unusedImports } from './imports.js';
+export { outline } from './outline.js';
+export { members } from './members.js';
+export { fanIn, fanOut, topFanIn, topFanOut } from './fan.js';
+export { coupling, topCoupling } from './coupling.js';
+export { cycles } from './cycles.js';
+export { bottlenecks } from './bottlenecks.js';
+export { isolated } from './isolated.js';
+export { byKind, kindCounts } from './by-kind.js';
+export { testCoverage, testCoverageSummary } from './test-coverage.js';
+export { docCoverage } from './doc-coverage.js';
+export { deepChains } from './deep-chains.js';
+export { hierarchy } from './hierarchy.js';
+export { callGraph } from './call-graph.js';
+export { similar, similarAll } from './similar.js';
+export { similarFiles } from './similar-files.js';
+export { similarChains } from './similar-chains.js';
+export { extractCandidates } from './extract-candidates.js';
+export { affected } from './affected.js';
+export { changeSurface } from './change-surface.js';
+export { diffImpact } from './diff-impact.js';
+export { drift } from './drift.js';
+export { wrapperCandidates } from './wrapper-candidates.js';
+export { passthroughCandidates } from './passthrough-candidates.js';
+export { staleAbstractions } from './stale-abstractions.js';
+export { complexityHotspots } from './complexity-hotspots.js';
+export { health } from './health.js';
+export { convergence } from './convergence.js';
+export { code } from './code.js';
+export { complexity } from './complexity.js';
+export { dataflow } from './dataflow.js';
+export { slice } from './slice.js';
+export { redundantReexports } from './redundant-reexports.js';
+export { similarSignatures } from './similar-signatures.js';

package/src/queries/isolated.ts

@@ -0,0 +1,67 @@
+import type { ScipDatabase } from '../db.js';
+import { testFileExclusionSql } from '../query-support.js';
+import type { IsolatedResult } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Find isolated symbols: defined locally, referenced by nothing,
+ * and referencing nothing external. These are truly orphaned code —
+ * not just unused exports, but completely disconnected from the graph.
+ */
+export function isolated(
+  db: ScipDatabase,
+  opts: { scope?: string; minLoc?: number } = {},
+): IsolatedResult[] {
+  const { scope, minLoc = 3 } = opts;
+  const scopeFilter = scope ? `AND d.relative_path LIKE '%${scope}%'` : '';
+
+  const rows = db.all<{
+    symbol: string;
+    relative_path: string;
+    start_line: number;
+    end_line: number;
+    loc: number;
+  }>(
+    `SELECT
+      gs.symbol,
+      d.relative_path,
+      der.start_line,
+      der.end_line,
+      (der.end_line - der.start_line + 1) AS loc
+    FROM global_symbols gs
+    JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
+    JOIN documents d ON der.document_id = d.id
+    WHERE 1 = 1
+      ${db.pathExclusionsFor('d')}
+      AND ${testFileExclusionSql('d')}
+      ${db.symbolNoiseFor('gs')}
+      AND gs.symbol NOT LIKE '%#%'
+      AND (der.end_line - der.start_line + 1) >= ?
+      ${scopeFilter}
+      -- No cross-file references TO this symbol
+      AND NOT EXISTS (
+        SELECT 1 FROM mentions m
+        JOIN chunks c ON m.chunk_id = c.id
+        WHERE m.symbol_id = gs.id AND m.role = 0 AND c.document_id != d.id
+      )
+      -- No same-file references either
+      AND NOT EXISTS (
+        SELECT 1 FROM mentions m
+        JOIN chunks c ON m.chunk_id = c.id
+        WHERE m.symbol_id = gs.id AND m.role = 0 AND c.document_id = d.id
+      )
+    ORDER BY loc DESC, d.relative_path`,
+    minLoc,
+  );
+
+  return rows
+    .filter((r) => !db.isIgnored(r.relative_path))
+    .map((r) => ({
+      symbol: r.symbol,
+      shortName: shortenSymbol(r.symbol),
+      relativePath: r.relative_path,
+      startLine: r.start_line,
+      endLine: r.end_line,
+      loc: r.loc,
+    }));
+}

package/src/queries/members.ts

@@ -0,0 +1,54 @@
+import type { ScipDatabase } from '../db.js';
+import type { MemberResult } from '../types.js';
+import { shortenSymbol, parseSymbol } from '../symbol-parser.js';
+import type { ScipSymbol } from '../types.js';
+
+/**
+ * Find all direct children of a symbol (methods, fields, nested types).
+ * Uses the enclosing_symbol relationship in global_symbols.
+ */
+export function members(db: ScipDatabase, symbolPattern: string): MemberResult[] {
+  // First find the parent symbol(s)
+  const parents = db.all<{ symbol: string }>(
+    `SELECT symbol FROM global_symbols WHERE symbol LIKE ?`,
+    `%${symbolPattern}%`,
+  );
+
+  if (parents.length === 0) return [];
+
+  // Find children whose enclosing_symbol matches any parent
+  const placeholders = parents.map(() => '?').join(',');
+  const parentSymbols = parents.map((p) => p.symbol);
+
+  const rows = db.all<{
+    symbol: string;
+    start_line: number;
+    end_line: number;
+  }>(
+    `SELECT gs.symbol, der.start_line, der.end_line
+    FROM global_symbols gs
+    JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
+    WHERE gs.enclosing_symbol IN (${placeholders})
+      ${db.symbolNoise}
+    ORDER BY der.start_line`,
+    ...parentSymbols,
+  );
+
+  return rows.map((r) => {
+    const parsed = parseSymbol(r.symbol);
+    let kind = 'unknown';
+    if (!('kind' in parsed)) {
+      const sym = parsed as ScipSymbol;
+      const last = sym.descriptors[sym.descriptors.length - 1];
+      if (last) kind = last.suffix;
+    }
+
+    return {
+      symbol: r.symbol,
+      shortName: shortenSymbol(r.symbol),
+      startLine: r.start_line,
+      endLine: r.end_line,
+      kind,
+    };
+  });
+}

package/src/queries/methods.ts

@@ -0,0 +1,27 @@
+import type { ScipDatabase } from '../db.js';
+import type { MethodResult } from '../types.js';
+import { leafName } from '../symbol-parser.js';
+
+export function methods(db: ScipDatabase, className: string): MethodResult[] {
+  const rows = db.all<{
+    start_line: number;
+    end_line: number;
+    symbol: string;
+  }>(
+    `SELECT der.start_line, der.end_line, gs.symbol
+    FROM global_symbols gs
+    JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
+    WHERE gs.symbol LIKE ?
+      AND ${db.localSymbolPredicate}
+      AND gs.symbol LIKE '%().%'
+      ${db.symbolNoise}
+    ORDER BY der.start_line`,
+    `%${className}#%`,
+  );
+
+  return rows.map((r) => ({
+    startLine: r.start_line,
+    endLine: r.end_line,
+    name: leafName(r.symbol),
+  }));
+}

package/src/queries/outline.ts

@@ -0,0 +1,52 @@
+import type { ScipDatabase } from '../db.js';
+import type { OutlineNode } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Build a tree-structured outline of symbols in a file,
+ * using the enclosing_symbol field to establish parent-child relationships.
+ */
+export function outline(db: ScipDatabase, filePattern: string): OutlineNode[] {
+  const rows = db.all<{
+    symbol: string;
+    enclosing_symbol: string | null;
+    start_line: number;
+    end_line: number;
+  }>(
+    `SELECT gs.symbol, gs.enclosing_symbol, der.start_line, der.end_line
+    FROM defn_enclosing_ranges der
+    JOIN global_symbols gs ON der.symbol_id = gs.id
+    JOIN documents d ON der.document_id = d.id
+    WHERE d.relative_path LIKE ?
+      ${db.symbolNoise}
+    ORDER BY der.start_line`,
+    `%${filePattern}%`,
+  );
+
+  // Build a map of symbol -> node
+  const nodeMap = new Map<string, OutlineNode>();
+  const roots: OutlineNode[] = [];
+
+  for (const r of rows) {
+    const node: OutlineNode = {
+      symbol: r.symbol,
+      shortName: shortenSymbol(r.symbol),
+      startLine: r.start_line,
+      endLine: r.end_line,
+      children: [],
+    };
+    nodeMap.set(r.symbol, node);
+  }
+
+  // Wire up parent-child via enclosing_symbol
+  for (const r of rows) {
+    const node = nodeMap.get(r.symbol)!;
+    if (r.enclosing_symbol && nodeMap.has(r.enclosing_symbol)) {
+      nodeMap.get(r.enclosing_symbol)!.children.push(node);
+    } else {
+      roots.push(node);
+    }
+  }
+
+  return roots;
+}

package/src/queries/passthrough-candidates.ts

@@ -0,0 +1,94 @@
+import type { ScipDatabase } from '../db.js';
+import { getCalleeRowsForSymbol, testFileExclusionSql } from '../query-support.js';
+import type { PassthroughCandidate } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Find passthrough candidates: functions that just forward to one
+ * other function.
+ *
+ * A function with exactly 1 callee and small LOC is likely a thin
+ * wrapper that adds no value — it just passes arguments through to
+ * the real implementation.
+ */
+export function passthroughCandidates(
+  db: ScipDatabase,
+  opts?: { scope?: string; maxLoc?: number; limit?: number },
+): PassthroughCandidate[] {
+  const { scope, maxLoc = 15, limit = 30 } = opts ?? {};
+  const scopeFilter = scope ? `AND d.relative_path LIKE '%${scope}%'` : '';
+
+  // 1. Find all non-trivial symbols with definition ranges (>= 3 LOC)
+  const symbols = db.all<{
+    id: number;
+    symbol: string;
+    document_id: number;
+    start_line: number;
+    end_line: number;
+    loc: number;
+    relative_path: string;
+  }>(
+    `SELECT
+      gs.id,
+      gs.symbol,
+      der.document_id,
+      der.start_line,
+      der.end_line,
+      (der.end_line - der.start_line + 1) AS loc,
+      d.relative_path
+    FROM global_symbols gs
+    JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
+    JOIN documents d ON der.document_id = d.id
+    WHERE 1 = 1
+      ${db.pathExclusionsFor('d')}
+      AND ${testFileExclusionSql('d')}
+      ${db.symbolNoiseFor('gs')}
+      AND (der.end_line - der.start_line + 1) >= 3
+      AND (der.end_line - der.start_line + 1) <= ?
+      ${scopeFilter}
+    ORDER BY d.relative_path`,
+    maxLoc,
+  );
+
+  const results: PassthroughCandidate[] = [];
+
+  for (const sym of symbols) {
+    if (db.isIgnored(sym.relative_path)) continue;
+
+    // 2. Count callees for this symbol
+    const callees = getCalleeRowsForSymbol(db, {
+      documentId: sym.document_id,
+      startLine: sym.start_line,
+      endLine: sym.end_line,
+      symbolId: sym.id,
+    });
+
+    // Deduplicate by symbol (same callee may appear in multiple chunks)
+    const uniqueCallees = new Map<string, { symbol: string; file: string }>();
+    for (const c of callees) {
+      if (!uniqueCallees.has(c.symbol)) {
+        uniqueCallees.set(c.symbol, { symbol: c.symbol, file: c.file });
+      }
+    }
+
+    // 3. Passthrough = exactly 1 unique callee
+    if (uniqueCallees.size !== 1) continue;
+
+    const [, callee] = [...uniqueCallees.entries()][0]!;
+
+    results.push({
+      symbol: sym.symbol,
+      shortName: shortenSymbol(sym.symbol),
+      file: sym.relative_path,
+      startLine: sym.start_line,
+      endLine: sym.end_line,
+      loc: sym.loc,
+      forwardsTo: callee.symbol,
+      forwardsToShort: shortenSymbol(callee.symbol),
+      forwardsToFile: callee.file,
+    });
+  }
+
+  results.sort((a, b) => a.loc - b.loc || a.file.localeCompare(b.file));
+  return results.slice(0, limit);
+}