scip-query 0.1.0

package/src/queries/by-kind.ts

@@ -0,0 +1,204 @@
+import type { ScipDatabase } from '../db.js';
+import type { ByKindResult } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * SCIP SymbolInformation.Kind enum values.
+ * From: https://github.com/sourcegraph/scip/blob/main/scip.proto
+ */
+const KIND_NAMES: Record<number, string> = {
+  0: 'UnspecifiedKind',
+  1: 'AbstractMethod',
+  2: 'Accessor',
+  3: 'Array',
+  4: 'Assertion',
+  5: 'AssociatedType',
+  6: 'Attribute',
+  7: 'Axiom',
+  8: 'Boolean',
+  9: 'Class',
+  10: 'Constant',
+  11: 'Constructor',
+  12: 'Contract',
+  13: 'DataFamily',
+  14: 'DefinitionMacro',
+  15: 'Delegate',
+  16: 'Enum',
+  17: 'EnumMember',
+  18: 'Error',
+  19: 'Event',
+  20: 'Fact',
+  21: 'Field',
+  22: 'File',
+  23: 'Function',
+  24: 'Getter',
+  25: 'Grammar',
+  26: 'Instance',
+  27: 'Interface',
+  28: 'Key',
+  29: 'Lang',
+  30: 'Lemma',
+  31: 'Library',
+  32: 'Macro',
+  33: 'Method',
+  34: 'MethodAlias',
+  35: 'MethodReceiver',
+  36: 'MethodSpecification',
+  37: 'Message',
+  38: 'Modifier',
+  39: 'Module',
+  40: 'Namespace',
+  41: 'Null',
+  42: 'Number',
+  43: 'Object',
+  44: 'Operator',
+  45: 'Package',
+  46: 'PackageObject',
+  47: 'Parameter',
+  48: 'ParameterLabel',
+  49: 'Pattern',
+  50: 'Predicate',
+  51: 'Property',
+  52: 'Protocol',
+  53: 'ProtocolMethod',
+  54: 'PureVirtualMethod',
+  55: 'Quasiquoter',
+  56: 'SelfParameter',
+  57: 'Setter',
+  58: 'Signature',
+  59: 'SingletonClass',
+  60: 'SingletonMethod',
+  61: 'StaticDataMember',
+  62: 'StaticEvent',
+  63: 'StaticField',
+  64: 'StaticMethod',
+  65: 'StaticProperty',
+  66: 'StaticVariable',
+  67: 'String',
+  68: 'Struct',
+  69: 'Subscript',
+  70: 'Tactic',
+  71: 'Theorem',
+  72: 'ThisParameter',
+  73: 'Trait',
+  74: 'TraitMethod',
+  75: 'Type',
+  76: 'TypeAlias',
+  77: 'TypeClass',
+  78: 'TypeClassMethod',
+  79: 'TypeFamily',
+  80: 'TypeParameter',
+  81: 'Union',
+  82: 'Value',
+  83: 'Variable',
+};
+
+/** Reverse lookup: name -> kind number */
+const KIND_BY_NAME = new Map<string, number>();
+for (const [k, v] of Object.entries(KIND_NAMES)) {
+  KIND_BY_NAME.set(v.toLowerCase(), Number(k));
+}
+
+/**
+ * Find symbols by SCIP kind (class, interface, enum, function, etc.)
+ */
+export function byKind(
+  db: ScipDatabase,
+  kindQuery: string,
+  opts: { scope?: string; limit?: number } = {},
+): ByKindResult[] {
+  const { scope, limit = 100 } = opts;
+
+  // Resolve kind: accept number or name
+  let kindNum: number | null = null;
+  const asNum = parseInt(kindQuery, 10);
+  if (!isNaN(asNum)) {
+    kindNum = asNum;
+  } else {
+    kindNum = KIND_BY_NAME.get(kindQuery.toLowerCase()) ?? null;
+    // Fuzzy match: try partial name
+    if (kindNum === null) {
+      for (const [name, num] of KIND_BY_NAME) {
+        if (name.includes(kindQuery.toLowerCase())) {
+          kindNum = num;
+          break;
+        }
+      }
+    }
+  }
+
+  if (kindNum === null) {
+    return [];
+  }
+
+  const scopeFilter = scope ? `AND d.relative_path LIKE '%${scope}%'` : '';
+
+  // Check if the index actually has kind data populated
+  const hasKinds = db.get<{ c: number }>(
+    `SELECT COUNT(*) AS c FROM global_symbols WHERE kind IS NOT NULL`,
+  );
+  if (!hasKinds || hasKinds.c === 0) {
+    return []; // Indexer doesn't populate kind field
+  }
+
+  const rows = db.all<{
+    symbol: string;
+    kind: number;
+    relative_path: string;
+    start_line: number;
+    end_line: number;
+  }>(
+    `SELECT gs.symbol, gs.kind, d.relative_path, der.start_line, der.end_line
+    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.kind = ?
+      ${db.pathExclusionsFor('d')}
+      ${scopeFilter}
+    ORDER BY d.relative_path, der.start_line
+    LIMIT ?`,
+    kindNum, limit,
+  );
+
+  return rows
+    .filter((r) => !db.isIgnored(r.relative_path))
+    .map((r) => ({
+      symbol: r.symbol,
+      shortName: shortenSymbol(r.symbol),
+      kind: r.kind,
+      kindName: KIND_NAMES[r.kind] ?? 'Unknown',
+      relativePath: r.relative_path,
+      startLine: r.start_line,
+      endLine: r.end_line,
+    }));
+}
+
+/** List all symbol kinds present in the index with counts */
+export function kindCounts(
+  db: ScipDatabase,
+  opts: { scope?: string } = {},
+): Array<{ kind: number; kindName: string; count: number }> {
+  const scopeFilter = opts.scope
+    ? `AND d.relative_path LIKE '%${opts.scope}%'`
+    : '';
+
+  const rows = db.all<{ kind: number; cnt: number }>(
+    `SELECT gs.kind, COUNT(*) AS cnt
+    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 gs.kind IS NOT NULL
+      AND gs.kind != 0
+      ${scopeFilter}
+    GROUP BY gs.kind
+    ORDER BY cnt DESC`,
+  );
+
+  return rows.map((r) => ({
+    kind: r.kind,
+    kindName: KIND_NAMES[r.kind] ?? 'Unknown',
+    count: r.cnt,
+  }));
+}

package/src/queries/call-graph.ts

@@ -0,0 +1,66 @@
+import type { ScipDatabase } from '../db.js';
+import { findFirstSymbolMatch, getCalleeRowsForSymbol } from '../query-support.js';
+import type { CallGraphResult } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Build a call graph for a symbol: who calls it (incoming) and
+ * what it calls (outgoing).
+ *
+ * Incoming: other symbols whose definition ranges contain a reference to this symbol.
+ * Outgoing: symbols referenced within this symbol's definition range.
+ */
+export function callGraph(db: ScipDatabase, symbolPattern: string): CallGraphResult | null {
+  // Find the target symbol and its definition range
+  const target = findFirstSymbolMatch(db, symbolPattern);
+
+  if (!target) return null;
+
+  // CALLERS: symbols whose definition ranges contain a reference to our target.
+  // Find chunks that reference our symbol, then find which symbol's definition encloses that chunk.
+  const callerRows = db.all<{
+    caller_symbol: string;
+    caller_file: string;
+  }>(
+    `SELECT DISTINCT caller_gs.symbol AS caller_symbol, caller_d.relative_path AS caller_file
+    FROM mentions m
+    JOIN chunks c ON m.chunk_id = c.id
+    JOIN documents ref_d ON c.document_id = ref_d.id
+    -- Find the enclosing symbol for where the reference appears
+    JOIN defn_enclosing_ranges caller_der
+      ON caller_der.document_id = ref_d.id
+      AND c.start_line >= caller_der.start_line
+      AND c.end_line <= caller_der.end_line
+    JOIN global_symbols caller_gs ON caller_der.symbol_id = caller_gs.id
+    JOIN documents caller_d ON caller_der.document_id = caller_d.id
+    WHERE m.symbol_id = ?
+      AND m.role = 0
+      AND caller_gs.id != ?
+      ${db.symbolNoiseFor('caller_gs')}
+      ${db.pathExclusionsFor('caller_d')}
+    ORDER BY caller_d.relative_path
+    LIMIT 50`,
+    target.symbolId, target.symbolId,
+  );
+
+  // CALLEES: symbols referenced within our target's definition range.
+  const calleeRows = getCalleeRowsForSymbol(db, target, { limit: 50 });
+
+  return {
+    symbol: target.symbol,
+    shortName: shortenSymbol(target.symbol),
+    callers: callerRows
+      .filter((r) => !db.isIgnored(r.caller_file))
+      .map((r) => ({
+        symbol: r.caller_symbol,
+        shortName: shortenSymbol(r.caller_symbol),
+        file: r.caller_file,
+      })),
+    callees: calleeRows
+      .map((r) => ({
+        symbol: r.symbol,
+        shortName: shortenSymbol(r.symbol),
+        file: r.file,
+      })),
+  };
+}

package/src/queries/change-surface.ts

@@ -0,0 +1,110 @@
+import type { ScipDatabase } from '../db.js';
+import { TEST_FILE_PATTERNS, testFileMatchSql } from '../query-support.js';
+import type { ChangeSurfaceEntry, ChangeSurfaceResult } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Pre-change briefing for a file. For each symbol defined in the file,
+ * reports external consumer count, test coverage, and risk level.
+ */
+export function changeSurface(
+  db: ScipDatabase,
+  filePattern: string,
+): ChangeSurfaceResult | null {
+  // Find the file
+  const doc = db.get<{ id: number; relative_path: string }>(
+    `SELECT id, relative_path FROM documents
+     WHERE relative_path LIKE ?
+       ${db.pathExclusionsFor('documents')}
+     LIMIT 1`,
+    `%${filePattern}%`,
+  );
+
+  if (!doc || db.isIgnored(doc.relative_path)) return null;
+
+  // Get all symbols defined in this file, excluding typeLiterals
+  const syms = db.all<{
+    symbol_id: number;
+    symbol: string;
+    start_line: number;
+    end_line: number;
+  }>(
+    `SELECT DISTINCT gs.id AS symbol_id, gs.symbol, der.start_line, der.end_line
+    FROM defn_enclosing_ranges der
+    JOIN global_symbols gs ON der.symbol_id = gs.id
+    WHERE der.document_id = ?
+      ${db.symbolNoiseFor('gs')}
+    ORDER BY der.start_line`,
+    doc.id,
+  );
+
+  const testPatternSql = testFileMatchSql('ref_d', TEST_FILE_PATTERNS);
+
+  const symbols: ChangeSurfaceEntry[] = [];
+  let totalExternalConsumers = 0;
+  let coveredCount = 0;
+
+  for (const sym of syms) {
+    // Count external consumers: mentions with role=0 from different documents
+    const consumerRow = db.get<{ consumer_count: number }>(
+      `SELECT COUNT(DISTINCT c.document_id) AS consumer_count
+      FROM mentions m
+      JOIN chunks c ON m.chunk_id = c.id
+      WHERE m.symbol_id = ?
+        AND m.role = 0
+        AND c.document_id != ?`,
+      sym.symbol_id,
+      doc.id,
+    );
+
+    const externalConsumers = consumerRow?.consumer_count ?? 0;
+
+    // Find test files that reference this symbol
+    const testFiles = db.all<{ relative_path: string }>(
+      `SELECT DISTINCT ref_d.relative_path
+      FROM mentions m
+      JOIN chunks c ON m.chunk_id = c.id
+      JOIN documents ref_d ON c.document_id = ref_d.id
+      WHERE m.symbol_id = ?
+        AND m.role = 0
+        AND (${testPatternSql})
+      ORDER BY ref_d.relative_path`,
+      sym.symbol_id,
+    ).map((r) => r.relative_path);
+
+    const hasTests = testFiles.length > 0;
+    if (hasTests) coveredCount++;
+
+    // Risk level determination
+    let riskLevel: 'low' | 'medium' | 'high';
+    if (externalConsumers > 10 && !hasTests) {
+      riskLevel = 'high';
+    } else if (externalConsumers > 5 || !hasTests) {
+      riskLevel = 'medium';
+    } else {
+      riskLevel = 'low';
+    }
+
+    totalExternalConsumers += externalConsumers;
+
+    symbols.push({
+      symbol: sym.symbol,
+      shortName: shortenSymbol(sym.symbol),
+      startLine: sym.start_line,
+      endLine: sym.end_line,
+      externalConsumers,
+      testFiles,
+      riskLevel,
+    });
+  }
+
+  const testCoveragePercent =
+    symbols.length > 0 ? Math.round((coveredCount / symbols.length) * 100) : 0;
+
+  return {
+    file: doc.relative_path,
+    symbols,
+    totalExternalConsumers,
+    testCoveragePercent,
+  };
+}

package/src/queries/clean-signature.ts

@@ -0,0 +1,22 @@
+/**
+ * Clean up the raw doc/signature string from the SCIP index.
+ *
+ * Shared across symbols, trace, and system queries.
+ * Previously duplicated as cleanSig/cleanSignature in three files.
+ */
+export function cleanSignature(sig: string | null): string | null {
+  if (!sig || !sig.trim()) return null;
+  return sig
+    .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() || null;
+}

package/src/queries/code.ts

@@ -0,0 +1,101 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ScipDatabase } from '../db.js';
+import { findFirstSymbolMatch } from '../query-support.js';
+import type { CodeResult } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Read the source code for a symbol, bounded to its definition range.
+ * Language-agnostic: just reads the file and extracts the relevant lines.
+ *
+ * Accepts:
+ *   - Symbol name pattern: "processVegaMention"
+ *   - Full short name: "src:modules:chat:processVegaMention"
+ *   - File:line-line syntax: "src/chat/service.ts:100-200"
+ */
+export function code(
+  db: ScipDatabase,
+  symbolPattern: string,
+  opts: { context?: number } = {},
+): CodeResult | null {
+  const { context = 0 } = opts;
+
+  // Handle direct file:line-line syntax (bypass symbol lookup)
+  const fileLineMatch = symbolPattern.match(/^(.+\.\w+):(\d+)-(\d+)$/);
+  if (fileLineMatch) {
+    return readFileRange(db, fileLineMatch[1]!, parseInt(fileLineMatch[2]!, 10), parseInt(fileLineMatch[3]!, 10), context);
+  }
+
+  const match = findFirstSymbolMatch(db, symbolPattern);
+  if (!match) return null;
+
+  // Get the language from the documents table
+  const doc = db.get<{ language: string | null }>(
+    `SELECT language FROM documents WHERE relative_path = ?`,
+    match.relativePath,
+  );
+
+  // Read the file
+  const filePath = join(db.config.projectRoot, match.relativePath);
+  let fileContent: string;
+  try {
+    fileContent = readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+
+  const lines = fileContent.split('\n');
+  const startLine = Math.max(0, match.startLine - context);
+  const endLine = Math.min(lines.length - 1, match.endLine + context);
+  const source = lines.slice(startLine, endLine + 1).join('\n');
+
+  return {
+    symbol: match.symbol,
+    shortName: shortenSymbol(match.symbol),
+    relativePath: match.relativePath,
+    startLine: startLine + 1, // 1-indexed for display
+    endLine: endLine + 1,
+    language: doc?.language ?? null,
+    source,
+  };
+}
+
+/** Read source by file path and line range directly (no symbol lookup) */
+function readFileRange(
+  db: ScipDatabase,
+  filePath: string,
+  startLine: number,
+  endLine: number,
+  context: number,
+): CodeResult | null {
+  // Find the file in the index
+  const doc = db.get<{ relative_path: string; language: string | null }>(
+    `SELECT relative_path, language FROM documents WHERE relative_path LIKE ?`,
+    `%${filePath}%`,
+  );
+  if (!doc) return null;
+
+  const fullPath = join(db.config.projectRoot, doc.relative_path);
+  let fileContent: string;
+  try {
+    fileContent = readFileSync(fullPath, 'utf-8');
+  } catch {
+    return null;
+  }
+
+  const lines = fileContent.split('\n');
+  const start = Math.max(0, startLine - 1 - context); // convert to 0-indexed
+  const end = Math.min(lines.length - 1, endLine - 1 + context);
+  const source = lines.slice(start, end + 1).join('\n');
+
+  return {
+    symbol: `${doc.relative_path}:${startLine}-${endLine}`,
+    shortName: `${doc.relative_path}:${startLine}-${endLine}`,
+    relativePath: doc.relative_path,
+    startLine: start + 1,
+    endLine: end + 1,
+    language: doc.language,
+    source,
+  };
+}

package/src/queries/complexity-hotspots.ts

@@ -0,0 +1,119 @@
+import type { ScipDatabase } from '../db.js';
+import { testFileExclusionSql } from '../query-support.js';
+import type { ComplexityHotspot } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Find complexity hotspots: symbols with a composite score based on
+ * LOC, fan-in, fan-out, and callee count.
+ *
+ * Score = (loc / 50) * (fanIn / 5) * max(fanOut / 5, 1)
+ *
+ * High scores indicate symbols that are large, widely depended upon,
+ * AND reach out to many other modules — the riskiest code to change.
+ */
+export function complexityHotspots(
+  db: ScipDatabase,
+  opts?: { scope?: string; minLoc?: number; limit?: number },
+): ComplexityHotspot[] {
+  const { scope, minLoc = 10, 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;
+    fan_in: number;
+    fan_out: number;
+    callee_count: number;
+  }>(
+    `SELECT
+      gs.symbol,
+      d.relative_path AS file,
+      der.start_line,
+      der.end_line,
+      (der.end_line - der.start_line + 1) AS loc,
+      -- fanIn: distinct files that reference this symbol
+      (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
+      ) AS fan_in,
+      -- fanOut: distinct symbols referenced within this definition range
+      -- that are defined in different files
+      (SELECT COUNT(DISTINCT out_gs.id)
+       FROM mentions out_m
+       JOIN chunks out_c ON out_m.chunk_id = out_c.id
+       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
+       WHERE out_c.document_id = der.document_id
+         AND out_c.start_line >= der.start_line
+         AND out_c.end_line <= der.end_line
+         AND out_m.role = 0
+         AND out_gs.id != gs.id
+         AND out_der.document_id != der.document_id
+      ) AS fan_out,
+      -- calleeCount: total distinct callees within definition range
+      (SELECT COUNT(DISTINCT callee_gs.id)
+       FROM mentions callee_m
+       JOIN chunks callee_c ON callee_m.chunk_id = callee_c.id
+       JOIN global_symbols callee_gs ON callee_m.symbol_id = callee_gs.id
+       WHERE callee_c.document_id = der.document_id
+         AND callee_c.start_line >= der.start_line
+         AND callee_c.end_line <= der.end_line
+         AND callee_m.role = 0
+         AND callee_gs.id != gs.id
+      ) AS callee_count
+    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) >= ?
+      ${scopeFilter}
+    ORDER BY (
+      CAST((der.end_line - der.start_line + 1) AS REAL) / 50.0
+      * CAST((SELECT COUNT(DISTINCT ref_c2.document_id)
+              FROM mentions ref_m2
+              JOIN chunks ref_c2 ON ref_m2.chunk_id = ref_c2.id
+              WHERE ref_m2.symbol_id = gs.id AND ref_m2.role = 0
+             ) AS REAL) / 5.0
+      * MAX(CAST((SELECT COUNT(DISTINCT out_gs2.id)
+                  FROM mentions out_m2
+                  JOIN chunks out_c2 ON out_m2.chunk_id = out_c2.id
+                  JOIN global_symbols out_gs2 ON out_m2.symbol_id = out_gs2.id
+                  JOIN defn_enclosing_ranges out_der2 ON out_gs2.id = out_der2.symbol_id
+                  WHERE out_c2.document_id = der.document_id
+                    AND out_c2.start_line >= der.start_line
+                    AND out_c2.end_line <= der.end_line
+                    AND out_m2.role = 0
+                    AND out_gs2.id != gs.id
+                    AND out_der2.document_id != der.document_id
+                 ) AS REAL) / 5.0, 1.0)
+    ) DESC
+    LIMIT ?`,
+    minLoc, limit,
+  );
+
+  return rows
+    .filter((r) => !db.isIgnored(r.file))
+    .map((r) => ({
+      symbol: r.symbol,
+      shortName: shortenSymbol(r.symbol),
+      file: r.file,
+      startLine: r.start_line,
+      endLine: r.end_line,
+      loc: r.loc,
+      fanIn: r.fan_in,
+      fanOut: r.fan_out,
+      calleeCount: r.callee_count,
+      score:
+        Math.round(
+          (r.loc / 50) * (r.fan_in / 5) * Math.max(r.fan_out / 5, 1) * 100,
+        ) / 100,
+    }));
+}