scip-query 0.1.0

package/src/queries/similar-signatures.ts

@@ -0,0 +1,151 @@
+import type { ScipDatabase } from '../db.js';
+import type { SimilarSignatureGroup } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Find functions with near-identical type signatures (same parameter types
+ * and return type) but different names. These are "same shape" functions
+ * that may be doing similar work even if their internal implementation differs.
+ *
+ * The SCIP `documentation` field often contains the full type signature
+ * after a `|` delimiter. We parse it, normalize it (strip the function name,
+ * whitespace, and case), then group by normalized signature.
+ *
+ * Groups with 2+ functions = same-shape candidates.
+ */
+export function similarSignatures(
+  db: ScipDatabase,
+  opts: { scope?: string; minLoc?: number; limit?: number } = {},
+): SimilarSignatureGroup[] {
+  const { scope, minLoc = 1, limit } = opts;
+
+  const scopeFilter = scope ? `AND d.relative_path LIKE '%${scope}%'` : '';
+
+  // Get all function-level symbols with their documentation/signature strings.
+  // We use the same signature extraction pattern as symbols.ts / trace.ts.
+  // Filter to symbols that have a documentation field containing '|' (the sig delimiter)
+  // and whose signature contains '(' (indicating a callable).
+  const rows = db.all<{
+    symbol: string;
+    relative_path: string;
+    start_line: number;
+    end_line: number;
+    loc: number;
+    sig: string;
+  }>(
+    `SELECT
+      gs.symbol,
+      d.relative_path,
+      der.start_line,
+      der.end_line,
+      (der.end_line - der.start_line + 1) AS loc,
+      REPLACE(SUBSTR(gs.documentation, INSTR(gs.documentation, '|') + 1), char(10), ' ') AS sig
+    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 gs.documentation IS NOT NULL
+      AND gs.documentation != ''
+      AND INSTR(gs.documentation, '|') > 0
+      AND (der.end_line - der.start_line + 1) >= ?
+      ${db.pathExclusionsFor('d')}
+      ${db.symbolNoiseFor('gs')}
+      ${scopeFilter}
+    ORDER BY d.relative_path, der.start_line`,
+    minLoc,
+  );
+
+  // Group by normalized signature
+  const sigGroups = new Map<string, Array<{
+    symbol: string;
+    shortName: string;
+    file: string;
+    startLine: number;
+    endLine: number;
+    loc: number;
+  }>>();
+
+  for (const row of rows) {
+    if (db.isIgnored(row.relative_path)) continue;
+
+    const normalized = normalizeSignature(row.sig);
+    if (!normalized) continue;
+
+    const entry = {
+      symbol: row.symbol,
+      shortName: shortenSymbol(row.symbol),
+      file: row.relative_path,
+      startLine: row.start_line,
+      endLine: row.end_line,
+      loc: row.loc,
+    };
+
+    const existing = sigGroups.get(normalized);
+    if (existing) {
+      existing.push(entry);
+    } else {
+      sigGroups.set(normalized, [entry]);
+    }
+  }
+
+  // Collect groups with 2+ functions
+  const results: SimilarSignatureGroup[] = [];
+
+  for (const [signature, functions] of sigGroups) {
+    if (functions.length < 2) continue;
+
+    results.push({ signature, functions });
+  }
+
+  // Sort by group size descending (largest groups = most duplication),
+  // then by total LOC in the group
+  results.sort((a, b) => {
+    const sizeDiff = b.functions.length - a.functions.length;
+    if (sizeDiff !== 0) return sizeDiff;
+    const locA = a.functions.reduce((sum, f) => sum + f.loc, 0);
+    const locB = b.functions.reduce((sum, f) => sum + f.loc, 0);
+    return locB - locA;
+  });
+
+  return limit ? results.slice(0, limit) : results;
+}
+
+/**
+ * Normalize a signature for comparison:
+ * 1. Clean markdown fences and SCIP prefixes
+ * 2. Strip everything before the first '(' (removes the function name)
+ * 3. Strip whitespace and lowercase
+ *
+ * Returns null if the signature doesn't contain a callable form.
+ */
+function normalizeSignature(raw: string): string | null {
+  if (!raw || !raw.trim()) return null;
+
+  // Clean markdown and SCIP decoration (same as cleanSignature)
+  let sig = raw
+    .replace(/^```\w*\s*/, '')
+    .replace(/\s*```$/, '')
+    .replace(/^\(method\)\s*/, '')
+    .replace(/^\(property\)\s*/, '')
+    .replace(/^\(function\)\s*/, '')
+    .replace(/^\(class\)\s*/, '')
+    .replace(/^\(interface\)\s*/, '')
+    .replace(/^\(enum\)\s*/, '')
+    .replace(/^\(type alias\)\s*/, '')
+    .replace(/^\(const\)\s*/, '')
+    .replace(/^\(var\)\s*/, '')
+    .trim();
+
+  // Find the first '(' — everything from there is the parameter/return signature
+  const parenIdx = sig.indexOf('(');
+  if (parenIdx === -1) return null;
+
+  sig = sig.slice(parenIdx);
+
+  // Normalize: strip all whitespace, lowercase
+  sig = sig.replace(/\s+/g, '').toLowerCase();
+
+  // Must have meaningful content after normalization
+  if (sig.length < 3) return null; // e.g. "()" alone is too generic
+
+  return sig;
+}

package/src/queries/similar.ts

@@ -0,0 +1,305 @@
+import type { ScipDatabase } from '../db.js';
+import { findFirstSymbolMatch, getCalleeRowsForSymbol } from '../query-support.js';
+import type { SimilarSymbolResult } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Find functions with similar callee fingerprints using TF-IDF weighted
+ * cosine similarity.
+ *
+ * Plain Jaccard similarity inflates scores when functions share ubiquitous
+ * infrastructure imports (db, types, shortenSymbol). TF-IDF fixes this by
+ * weighting each shared callee by how rare it is:
+ *
+ *   - A callee used by 2 functions (rare) gets high weight → strong signal
+ *   - A callee used by 30 functions (common) gets low weight → noise
+ *
+ * This means two functions sharing `sendWelcomeEmail()` (rare) score
+ * much higher than two functions sharing `db.all()` (ubiquitous), even
+ * though both are "shared callees."
+ */
+export function similar(
+  db: ScipDatabase,
+  symbolPattern: string,
+  opts: { minSimilarity?: number; limit?: number } = {},
+): SimilarSymbolResult[] {
+  const { minSimilarity = 0.4, limit = 20 } = opts;
+
+  const target = findCallees(db, symbolPattern);
+  if (!target || target.callees.size === 0) return [];
+
+  const candidates = getAllCalleeFingerprints(db, {
+    minCallees: 3,
+    excludeSymbol: target.symbol,
+  });
+
+  // Compute IDF weights across all fingerprints + target
+  const allFingerprints = [target, ...candidates];
+  const idfWeights = computeIdf(allFingerprints);
+
+  const results: SimilarSymbolResult[] = [];
+
+  for (const candidate of candidates) {
+    if (candidate.callees.size < 3) continue;
+
+    const { similarity, significantShared, trivialShared } = weightedSimilarity(
+      target.callees, candidate.callees, idfWeights,
+    );
+
+    if (similarity < minSimilarity) continue;
+    if (significantShared.length < 1) continue; // no real overlap
+
+    results.push({
+      symbolA: target.symbol,
+      shortNameA: shortenSymbol(target.symbol),
+      fileA: target.file,
+      symbolB: candidate.symbol,
+      shortNameB: shortenSymbol(candidate.symbol),
+      fileB: candidate.file,
+      similarity,
+      sharedCallees: significantShared.map(shortenSymbol),
+      uniqueToA: [...difference(target.callees, candidate.callees)].map(shortenSymbol),
+      uniqueToB: [...difference(candidate.callees, target.callees)].map(shortenSymbol),
+    });
+  }
+
+  results.sort((a, b) => b.similarity - a.similarity);
+  return results.slice(0, limit);
+}
+
+/**
+ * Find similar symbols across the entire codebase.
+ * Uses TF-IDF weighted similarity to filter out infrastructure noise.
+ */
+export function similarAll(
+  db: ScipDatabase,
+  opts: { minSimilarity?: number; limit?: number; scope?: string; minCallees?: number } = {},
+): SimilarSymbolResult[] {
+  const { minSimilarity = 0.5, limit = 20, scope, minCallees = 4 } = opts;
+
+  const all = getAllCalleeFingerprints(db, { minCallees, scope });
+  const idfWeights = computeIdf(all);
+
+  const results: SimilarSymbolResult[] = [];
+
+  for (let i = 0; i < all.length; i++) {
+    for (let j = i + 1; j < all.length; j++) {
+      const a = all[i]!;
+      const b = all[j]!;
+
+      if (a.file === b.file) continue;
+
+      const { similarity, significantShared } = weightedSimilarity(
+        a.callees, b.callees, idfWeights,
+      );
+
+      if (similarity < minSimilarity) continue;
+      if (significantShared.length < 2) continue;
+
+      results.push({
+        symbolA: a.symbol,
+        shortNameA: shortenSymbol(a.symbol),
+        fileA: a.file,
+        symbolB: b.symbol,
+        shortNameB: shortenSymbol(b.symbol),
+        fileB: b.file,
+        similarity,
+        sharedCallees: significantShared.map(shortenSymbol),
+        uniqueToA: [...difference(a.callees, b.callees)].map(shortenSymbol),
+        uniqueToB: [...difference(b.callees, a.callees)].map(shortenSymbol),
+      });
+    }
+
+    if (results.length > limit * 5) break;
+  }
+
+  results.sort((a, b) => b.similarity - a.similarity);
+  return results.slice(0, limit);
+}
+
+// ── TF-IDF Engine ──────────────────────────────────────────
+
+/**
+ * Compute inverse document frequency for each callee.
+ * IDF(callee) = log(N / df(callee)) where N is total functions
+ * and df is how many functions reference that callee.
+ *
+ * High IDF = rare callee = strong similarity signal.
+ * Low IDF = ubiquitous callee = noise.
+ */
+function computeIdf(fingerprints: SymbolFingerprint[]): Map<string, number> {
+  const n = fingerprints.length;
+  if (n === 0) return new Map();
+
+  // Count how many functions reference each callee
+  const docFreq = new Map<string, number>();
+  for (const fp of fingerprints) {
+    for (const callee of fp.callees) {
+      docFreq.set(callee, (docFreq.get(callee) ?? 0) + 1);
+    }
+  }
+
+  // Compute IDF
+  const idf = new Map<string, number>();
+  for (const [callee, df] of docFreq) {
+    idf.set(callee, Math.log(n / df));
+  }
+
+  return idf;
+}
+
+/**
+ * Compute TF-IDF weighted cosine similarity between two callee sets.
+ *
+ * Each callee is a dimension. Its weight is its IDF score.
+ * Cosine similarity of the weighted vectors gives a similarity
+ * that ignores ubiquitous callees and emphasizes rare shared ones.
+ *
+ * Also returns which shared callees are "significant" (above-median IDF)
+ * vs "trivial" (below-median IDF, i.e., infrastructure).
+ */
+function weightedSimilarity(
+  a: Set<string>,
+  b: Set<string>,
+  idf: Map<string, number>,
+): { similarity: number; significantShared: string[]; trivialShared: string[] } {
+  const shared = intersection(a, b);
+  if (shared.size === 0) return { similarity: 0, significantShared: [], trivialShared: [] };
+
+  // Compute weighted dot product and magnitudes
+  let dotProduct = 0;
+  let magA = 0;
+  let magB = 0;
+
+  const allCallees = new Set([...a, ...b]);
+  for (const callee of allCallees) {
+    const weight = idf.get(callee) ?? 0;
+    const inA = a.has(callee) ? weight : 0;
+    const inB = b.has(callee) ? weight : 0;
+    dotProduct += inA * inB;
+    magA += inA * inA;
+    magB += inB * inB;
+  }
+
+  const magnitude = Math.sqrt(magA) * Math.sqrt(magB);
+  const similarity = magnitude > 0 ? dotProduct / magnitude : 0;
+
+  // Split shared callees into significant (high IDF) and trivial (low IDF)
+  const medianIdf = getMedianIdf(idf);
+  const significantShared: string[] = [];
+  const trivialShared: string[] = [];
+
+  for (const callee of shared) {
+    const weight = idf.get(callee) ?? 0;
+    if (weight >= medianIdf) {
+      significantShared.push(callee);
+    } else {
+      trivialShared.push(callee);
+    }
+  }
+
+  // Sort significant callees by IDF descending (most distinctive first)
+  significantShared.sort((x, y) => (idf.get(y) ?? 0) - (idf.get(x) ?? 0));
+
+  return { similarity, significantShared, trivialShared };
+}
+
+function getMedianIdf(idf: Map<string, number>): number {
+  const values = [...idf.values()].sort((a, b) => a - b);
+  if (values.length === 0) return 0;
+  const mid = Math.floor(values.length / 2);
+  return values.length % 2 === 0
+    ? (values[mid - 1]! + values[mid]!) / 2
+    : values[mid]!;
+}
+
+// ── Internal helpers ───────────────────────────────────────
+
+interface SymbolFingerprint {
+  symbol: string;
+  file: string;
+  callees: Set<string>;
+}
+
+function findCallees(
+  db: ScipDatabase,
+  symbolPattern: string,
+): SymbolFingerprint | null {
+  const target = findFirstSymbolMatch(db, symbolPattern);
+
+  if (!target) return null;
+
+  const calleeRows = getCalleeRowsForSymbol(db, target);
+
+  return {
+    symbol: target.symbol,
+    file: target.relativePath,
+    callees: new Set(calleeRows.map((r) => r.symbol)),
+  };
+}
+
+function getAllCalleeFingerprints(
+  db: ScipDatabase,
+  opts: { minCallees: number; scope?: string; excludeSymbol?: string },
+): SymbolFingerprint[] {
+  const { minCallees, scope, excludeSymbol } = opts;
+  const scopeFilter = scope ? `AND d.relative_path LIKE '%${scope}%'` : '';
+  const excludeFilter = excludeSymbol ? `AND gs.symbol != '${excludeSymbol.replace(/'/g, "''")}'` : '';
+
+  const symbols = db.all<{
+    id: number;
+    symbol: string;
+    document_id: number;
+    start_line: number;
+    end_line: number;
+    relative_path: string;
+  }>(
+    `SELECT gs.id, gs.symbol, der.document_id, der.start_line, der.end_line, 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')}
+      ${db.symbolNoiseFor('gs')}
+      AND (der.end_line - der.start_line + 1) >= 5
+      ${scopeFilter}
+      ${excludeFilter}
+    ORDER BY d.relative_path`,
+  );
+
+  const fingerprints: SymbolFingerprint[] = [];
+
+  for (const sym of symbols) {
+    if (db.isIgnored(sym.relative_path)) continue;
+
+    const calleeRows = getCalleeRowsForSymbol(db, {
+      documentId: sym.document_id,
+      startLine: sym.start_line,
+      endLine: sym.end_line,
+      symbolId: sym.id,
+    });
+
+    const callees = new Set(calleeRows.map((r) => r.symbol));
+    if (callees.size >= minCallees) {
+      fingerprints.push({ symbol: sym.symbol, file: sym.relative_path, callees });
+    }
+  }
+
+  return fingerprints;
+}
+
+function intersection<T>(a: Set<T>, b: Set<T>): Set<T> {
+  const result = new Set<T>();
+  for (const item of a) {
+    if (b.has(item)) result.add(item);
+  }
+  return result;
+}
+
+function difference<T>(a: Set<T>, b: Set<T>): Set<T> {
+  const result = new Set<T>();
+  for (const item of a) {
+    if (!b.has(item)) result.add(item);
+  }
+  return result;
+}

package/src/queries/slice.ts

@@ -0,0 +1,154 @@
+import type { ScipDatabase } from '../db.js';
+import { findFirstSymbolMatch, getCalleeRowsForSymbol, type SymbolMatch } from '../query-support.js';
+import type { SliceResult } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Reference-level program slicing: track what affects a symbol (backward)
+ * or what a symbol affects (forward).
+ *
+ * Backward slice: "What feeds into this?" — symbols referenced in the same
+ * function that defines the target. These are the inputs/dependencies.
+ *
+ * Forward slice: "What does this feed into?" — at each site where the target
+ * is referenced, find the enclosing function, then find what that function
+ * exports/defines. These are the outputs/consumers.
+ *
+ * Language-agnostic: works with any SCIP index.
+ */
+export function slice(
+  db: ScipDatabase,
+  symbolPattern: string,
+  opts: { direction?: 'backward' | 'forward' } = {},
+): SliceResult | null {
+  const { direction = 'backward' } = opts;
+
+  const match = findFirstSymbolMatch(db, symbolPattern);
+  if (!match) return null;
+
+  if (direction === 'backward') {
+    return backwardSlice(db, match);
+  } else {
+    return forwardSlice(db, match);
+  }
+}
+
+
+function backwardSlice(db: ScipDatabase, match: SymbolMatch): SliceResult {
+  // Find all symbols referenced within the definition range of the target.
+  // These are what "feeds into" the target — the inputs.
+  const callees = getCalleeRowsForSymbol(db, match);
+
+  // Also find symbols whose definitions are in the same file and whose
+  // ranges overlap or precede the target — local variables, parameters, etc.
+  const localPredecessors = db.all<{ symbol: string; file: string }>(
+    `SELECT DISTINCT gs.symbol, d.relative_path AS file
+    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 der.document_id = ?
+      AND der.end_line < ?
+      AND gs.id != ?
+      ${db.symbolNoiseFor('gs')}
+    ORDER BY der.start_line DESC
+    LIMIT 15`,
+    match.documentId, match.startLine, match.symbolId,
+  );
+
+  const seen = new Set<string>();
+  const connected: SliceResult['connectedSymbols'] = [];
+
+  for (const c of callees) {
+    if (seen.has(c.symbol)) continue;
+    seen.add(c.symbol);
+    connected.push({
+      symbol: c.symbol,
+      shortName: shortenSymbol(c.symbol),
+      file: c.file,
+      relationship: 'referenced within definition (callee)',
+    });
+  }
+
+  for (const p of localPredecessors) {
+    if (seen.has(p.symbol) || db.isIgnored(p.file)) continue;
+    seen.add(p.symbol);
+    connected.push({
+      symbol: p.symbol,
+      shortName: shortenSymbol(p.symbol),
+      file: p.file,
+      relationship: 'defined before target in same file (local predecessor)',
+    });
+  }
+
+  return {
+    symbol: match.symbol,
+    shortName: shortenSymbol(match.symbol),
+    direction: 'backward',
+    connectedSymbols: connected,
+  };
+}
+
+function forwardSlice(db: ScipDatabase, match: SymbolMatch): SliceResult {
+  // Find where the target is referenced, then at each reference site,
+  // find what else the enclosing function defines/exports.
+  const rows = db.all<{
+    enclosing_symbol: string;
+    enclosing_file: string;
+    output_symbol: string;
+    output_file: string;
+  }>(
+    `SELECT DISTINCT
+      enc_gs.symbol AS enclosing_symbol,
+      enc_d.relative_path AS enclosing_file,
+      out_gs.symbol AS output_symbol,
+      out_d.relative_path AS output_file
+    FROM mentions ref_m
+    JOIN chunks ref_c ON ref_m.chunk_id = ref_c.id
+    JOIN documents ref_d ON ref_c.document_id = ref_d.id
+    -- Find enclosing function at each reference site
+    JOIN defn_enclosing_ranges enc_der
+      ON enc_der.document_id = ref_d.id
+      AND enc_der.start_line <= ref_c.start_line
+      AND enc_der.end_line >= ref_c.end_line
+    JOIN global_symbols enc_gs ON enc_der.symbol_id = enc_gs.id
+    JOIN documents enc_d ON enc_der.document_id = enc_d.id
+    -- Find other symbols referenced within that enclosing function
+    JOIN mentions out_m ON out_m.role = 0
+    JOIN chunks out_c ON out_m.chunk_id = out_c.id
+      AND out_c.document_id = enc_der.document_id
+      AND out_c.start_line >= enc_der.start_line
+      AND out_c.end_line <= enc_der.end_line
+    JOIN global_symbols out_gs ON out_m.symbol_id = out_gs.id
+    JOIN defn_enclosing_ranges out_der ON out_gs.id = out_der.symbol_id
+    JOIN documents out_d ON out_der.document_id = out_d.id
+    WHERE ref_m.symbol_id = ? AND ref_m.role = 0
+      AND out_gs.id != ? AND out_gs.id != enc_gs.id
+      AND out_d.id != ref_d.id
+      ${db.symbolNoiseFor('out_gs')}
+      ${db.pathExclusionsFor('out_d')}
+    ORDER BY out_d.relative_path
+    LIMIT 30`,
+    match.symbolId, match.symbolId,
+  );
+
+  const seen = new Set<string>();
+  const connected: SliceResult['connectedSymbols'] = [];
+
+  for (const r of rows) {
+    if (seen.has(r.output_symbol) || db.isIgnored(r.output_file)) continue;
+    seen.add(r.output_symbol);
+    connected.push({
+      symbol: r.output_symbol,
+      shortName: shortenSymbol(r.output_symbol),
+      file: r.output_file,
+      relationship: `used alongside target in ${shortenSymbol(r.enclosing_symbol)}`,
+    });
+  }
+
+  return {
+    symbol: match.symbol,
+    shortName: shortenSymbol(match.symbol),
+    direction: 'forward',
+    connectedSymbols: connected,
+  };
+}

package/src/queries/stale-abstractions.ts

@@ -0,0 +1,82 @@
+import type { ScipDatabase } from '../db.js';
+import { testFileExclusionSql } from '../query-support.js';
+import type { StaleAbstraction } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Find stale abstractions: type-level symbols (classes, interfaces, type
+ * aliases) that have 0 or 1 cross-file consumers.
+ *
+ * A type that only one file uses is over-abstracted — it was designed
+ * for reuse that never materialized. Large single-consumer types are
+ * the strongest signal of wasted abstraction.
+ */
+export function staleAbstractions(
+  db: ScipDatabase,
+  opts?: { scope?: string; minLoc?: number; limit?: number },
+): StaleAbstraction[] {
+  const { scope, minLoc = 3, limit = 30 } = opts ?? {};
+  const scopeFilter = scope ? `AND d.relative_path LIKE '%${scope}%'` : '';
+
+  const rows = db.all<{
+    symbol: string;
+    file: string;
+    start_line: number;
+    end_line: number;
+    loc: number;
+    consumers: number;
+  }>(
+    `SELECT * FROM (
+      SELECT
+        gs.symbol,
+        d.relative_path AS file,
+        der.start_line,
+        der.end_line,
+        (der.end_line - der.start_line + 1) AS loc,
+        (SELECT COUNT(DISTINCT ref_c.document_id)
+         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 != der.document_id
+        ) AS consumers
+      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')}
+        -- Top-level type symbols: ends with # but does not contain nested #
+        AND gs.symbol LIKE '%#'
+        AND gs.symbol NOT LIKE '%#%#%'
+        AND (der.end_line - der.start_line + 1) >= ?
+        ${scopeFilter}
+    ) WHERE consumers <= 1
+    ORDER BY loc DESC
+    LIMIT ?`,
+    minLoc, limit,
+  );
+
+  return rows
+    .filter((r) => !db.isIgnored(r.file))
+    // Exclude types defined in dedicated type files (types.ts, types/, etc.)
+    // These are intentional public API types, not premature abstractions.
+    .filter((r) => {
+      const basename = r.file.split('/').pop() ?? '';
+      const isTypeFile = basename.includes('types') || r.file.includes('/types/');
+      // Types in type files with 1 consumer are normal API types — skip them.
+      // Types in type files with 0 consumers are genuinely unused — keep them.
+      if (isTypeFile && r.consumers > 0) return false;
+      return true;
+    })
+    .map((r) => ({
+      symbol: r.symbol,
+      shortName: shortenSymbol(r.symbol),
+      file: r.file,
+      startLine: r.start_line,
+      endLine: r.end_line,
+      loc: r.loc,
+      consumers: r.consumers,
+    }));
+}