scip-query 0.1.0

package/src/queries/deep-chains.ts

@@ -0,0 +1,59 @@
+import type { ScipDatabase } from '../db.js';
+import { buildFileDepGraph } from '../query-support.js';
+import type { DeepChainResult } from '../types.js';
+
+/**
+ * Find the longest transitive dependency chains between files.
+ * A chain A → B → C → D means A depends on B, B on C, C on D.
+ *
+ * Long chains = high coupling depth = changes at the end ripple through many layers.
+ */
+export function deepChains(
+  db: ScipDatabase,
+  opts: { limit?: number; scope?: string; minDepth?: number } = {},
+): DeepChainResult[] {
+  const { limit = 10, scope, minDepth = 3 } = opts;
+  const graph = buildFileDepGraph(db, scope);
+
+  // DFS to find longest paths (with cycle detection)
+  const results: DeepChainResult[] = [];
+
+  function dfs(node: string, path: string[], visited: Set<string>): void {
+    const neighbors = graph.get(node);
+    if (!neighbors || neighbors.size === 0) {
+      if (path.length >= minDepth) {
+        results.push({ chain: [...path], depth: path.length });
+      }
+      return;
+    }
+
+    let extended = false;
+    for (const next of neighbors) {
+      if (visited.has(next)) continue; // skip cycles
+      visited.add(next);
+      path.push(next);
+      dfs(next, path, visited);
+      path.pop();
+      visited.delete(next);
+      extended = true;
+    }
+
+    // If no unvisited neighbors, this is a leaf in this path
+    if (!extended && path.length >= minDepth) {
+      results.push({ chain: [...path], depth: path.length });
+    }
+  }
+
+  // Start DFS from each node
+  for (const startNode of graph.keys()) {
+    const visited = new Set<string>([startNode]);
+    dfs(startNode, [startNode], visited);
+
+    // Early termination if we have enough results
+    if (results.length > limit * 10) break;
+  }
+
+  // Sort by depth descending, take top N
+  results.sort((a, b) => b.depth - a.depth);
+  return results.slice(0, limit);
+}

package/src/queries/deps.ts

@@ -0,0 +1,46 @@
+import type { ScipDatabase } from '../db.js';
+import type { DepResult } from '../types.js';
+
+/** What internal files does this file depend on? (forward dependencies) */
+export function deps(db: ScipDatabase, filePattern: string): DepResult[] {
+  const rows = db.all<{ relative_path: string }>(
+    `SELECT DISTINCT d2.relative_path
+    FROM mentions m
+    JOIN chunks c ON m.chunk_id = c.id
+    JOIN documents d1 ON c.document_id = d1.id
+    JOIN global_symbols gs ON m.symbol_id = gs.id
+    JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
+    JOIN documents d2 ON der.document_id = d2.id
+    WHERE d1.relative_path LIKE ?
+      AND d2.relative_path <> d1.relative_path
+      AND ${db.localSymbolPredicate}
+    ORDER BY d2.relative_path`,
+    `%${filePattern}%`,
+  );
+
+  return rows
+    .filter((r) => !db.isIgnored(r.relative_path))
+    .map((r) => ({ relativePath: r.relative_path }));
+}
+
+/** What files depend on this file/module? (reverse dependencies) */
+export function rdeps(db: ScipDatabase, filePattern: string): DepResult[] {
+  const rows = db.all<{ relative_path: string }>(
+    `SELECT DISTINCT d1.relative_path
+    FROM mentions m
+    JOIN chunks c ON m.chunk_id = c.id
+    JOIN documents d1 ON c.document_id = d1.id
+    JOIN global_symbols gs ON m.symbol_id = gs.id
+    JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
+    JOIN documents d2 ON der.document_id = d2.id
+    WHERE d2.relative_path LIKE ?
+      AND d1.relative_path NOT LIKE ?
+    ORDER BY d1.relative_path`,
+    `%${filePattern}%`,
+    `%${filePattern}%`,
+  );
+
+  return rows
+    .filter((r) => !db.isIgnored(r.relative_path))
+    .map((r) => ({ relativePath: r.relative_path }));
+}

package/src/queries/diff-impact.ts

@@ -0,0 +1,204 @@
+import { execFileSync } from 'node:child_process';
+import type { ScipDatabase } from '../db.js';
+import { TEST_FILE_PATTERNS, testFileMatchSql } from '../query-support.js';
+import type { DiffImpactResult } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Given a git diff, compute the affected symbol set.
+ * Finds all symbols defined in changed files, their fan-in,
+ * the files that consume them, and test coverage gaps.
+ */
+export function diffImpact(
+  db: ScipDatabase,
+  opts: { base?: string } = {},
+): DiffImpactResult {
+  const { base = 'HEAD' } = opts;
+
+  // Get changed files from git
+  let changedFileLines: string[];
+  try {
+    const stdout = execFileSync('git', ['diff', '--name-only', base], {
+      encoding: 'utf-8',
+      cwd: db.config.projectRoot,
+      timeout: 10_000,
+    });
+    changedFileLines = stdout
+      .split('\n')
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0);
+  } catch {
+    // Not in a git repo or git not available — return empty result
+    return {
+      changedFiles: [],
+      changedSymbols: [],
+      affectedConsumers: [],
+      uncoveredSymbols: [],
+      summary: {
+        totalChangedFiles: 0,
+        totalChangedSymbols: 0,
+        totalAffectedFiles: 0,
+        testCoveragePercent: 0,
+      },
+    };
+  }
+
+  if (changedFileLines.length === 0) {
+    return {
+      changedFiles: [],
+      changedSymbols: [],
+      affectedConsumers: [],
+      uncoveredSymbols: [],
+      summary: {
+        totalChangedFiles: 0,
+        totalChangedSymbols: 0,
+        totalAffectedFiles: 0,
+        testCoveragePercent: 0,
+      },
+    };
+  }
+
+  // Match changed files against the index
+  const changedFiles: string[] = [];
+  const changedDocIds: number[] = [];
+
+  for (const file of changedFileLines) {
+    const doc = db.get<{ id: number; relative_path: string }>(
+      `SELECT id, relative_path FROM documents
+       WHERE relative_path LIKE ?
+       LIMIT 1`,
+      `%${file}`,
+    );
+    if (doc && !db.isIgnored(doc.relative_path)) {
+      changedFiles.push(doc.relative_path);
+      changedDocIds.push(doc.id);
+    }
+  }
+
+  if (changedDocIds.length === 0) {
+    return {
+      changedFiles: changedFileLines,
+      changedSymbols: [],
+      affectedConsumers: [],
+      uncoveredSymbols: [],
+      summary: {
+        totalChangedFiles: changedFileLines.length,
+        totalChangedSymbols: 0,
+        totalAffectedFiles: 0,
+        testCoveragePercent: 0,
+      },
+    };
+  }
+
+  // Get all symbols defined in changed files
+  const docPlaceholders = changedDocIds.map(() => '?').join(',');
+  const syms = db.all<{
+    symbol_id: number;
+    symbol: string;
+    relative_path: string;
+  }>(
+    `SELECT DISTINCT gs.id AS symbol_id, gs.symbol, d.relative_path
+    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 IN (${docPlaceholders})
+      ${db.symbolNoiseFor('gs')}
+    ORDER BY d.relative_path`,
+    ...changedDocIds,
+  );
+
+  // For each symbol, compute fan-in (distinct referencing documents)
+  const testPatternSql = testFileMatchSql('ref_d', TEST_FILE_PATTERNS);
+  const changedSymbols: DiffImpactResult['changedSymbols'] = [];
+  const consumerMap = new Map<string, Set<string>>(); // file -> set of consumed symbol shortNames
+  const uncoveredSymbols: DiffImpactResult['uncoveredSymbols'] = [];
+  let coveredCount = 0;
+
+  for (const sym of syms) {
+    // Fan-in: distinct files that reference this symbol
+    const fanInRow = db.get<{ fan_in: number }>(
+      `SELECT COUNT(DISTINCT c.document_id) AS fan_in
+      FROM mentions m
+      JOIN chunks c ON m.chunk_id = c.id
+      WHERE m.symbol_id = ?
+        AND m.role = 0`,
+      sym.symbol_id,
+    );
+
+    const fanIn = fanInRow?.fan_in ?? 0;
+    const shortName = shortenSymbol(sym.symbol);
+
+    changedSymbols.push({
+      symbol: sym.symbol,
+      shortName,
+      file: sym.relative_path,
+      fanIn,
+    });
+
+    // Collect consumer files (excluding the changed files themselves)
+    const consumers = 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 ref_d.relative_path NOT IN (${changedFiles.map(() => '?').join(',')})
+        ${db.pathExclusionsFor('ref_d')}`,
+      sym.symbol_id,
+      ...changedFiles,
+    );
+
+    for (const consumer of consumers) {
+      if (db.isIgnored(consumer.relative_path)) continue;
+      if (!consumerMap.has(consumer.relative_path)) {
+        consumerMap.set(consumer.relative_path, new Set());
+      }
+      consumerMap.get(consumer.relative_path)!.add(shortName);
+    }
+
+    // Check test coverage
+    const hasTest = db.get<{ c: number }>(
+      `SELECT COUNT(*) AS c
+      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})`,
+      sym.symbol_id,
+    );
+
+    if (hasTest && hasTest.c > 0) {
+      coveredCount++;
+    } else {
+      uncoveredSymbols.push({
+        symbol: sym.symbol,
+        shortName,
+        file: sym.relative_path,
+      });
+    }
+  }
+
+  // Build affected consumers list
+  const affectedConsumers = [...consumerMap.entries()]
+    .map(([file, symbols]) => ({ file, consumedSymbols: symbols.size }))
+    .sort((a, b) => b.consumedSymbols - a.consumedSymbols);
+
+  const totalSymbols = changedSymbols.length;
+  const testCoveragePercent =
+    totalSymbols > 0 ? Math.round((coveredCount / totalSymbols) * 100) : 0;
+
+  return {
+    changedFiles,
+    changedSymbols,
+    affectedConsumers,
+    uncoveredSymbols,
+    summary: {
+      totalChangedFiles: changedFiles.length,
+      totalChangedSymbols: totalSymbols,
+      totalAffectedFiles: affectedConsumers.length,
+      testCoveragePercent,
+    },
+  };
+}

package/src/queries/doc-coverage.ts

@@ -0,0 +1,86 @@
+import type { ScipDatabase } from '../db.js';
+import type { DocCoverageResult } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Check documentation coverage: what percentage of symbols have doc strings?
+ * Reports overall stats and lists undocumented symbols.
+ */
+export function docCoverage(
+  db: ScipDatabase,
+  opts: { scope?: string; minLoc?: number; limit?: number } = {},
+): DocCoverageResult {
+  const { scope, minLoc = 3, limit = 50 } = opts;
+  const scopeFilter = scope ? `AND d.relative_path LIKE '%${scope}%'` : '';
+
+  // Count all local symbols meeting the threshold
+  const totalRow = db.get<{ c: number }>(
+    `SELECT COUNT(*) AS c
+    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 gs.symbol NOT LIKE '%#%'
+      AND (der.end_line - der.start_line + 1) >= ?
+      ${scopeFilter}`,
+    minLoc,
+  );
+
+  const docRow = db.get<{ c: number }>(
+    `SELECT COUNT(*) AS c
+    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 gs.symbol NOT LIKE '%#%'
+      AND (der.end_line - der.start_line + 1) >= ?
+      AND gs.documentation IS NOT NULL
+      AND gs.documentation != ''
+      ${scopeFilter}`,
+    minLoc,
+  );
+
+  const total = totalRow?.c ?? 0;
+  const documented = docRow?.c ?? 0;
+
+  // Get undocumented symbols
+  const undocRows = db.all<{
+    symbol: string;
+    relative_path: string;
+    start_line: number;
+  }>(
+    `SELECT gs.symbol, d.relative_path, der.start_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 1 = 1
+      ${db.pathExclusionsFor('d')}
+      ${db.symbolNoiseFor('gs')}
+      AND gs.symbol NOT LIKE '%#%'
+      AND (der.end_line - der.start_line + 1) >= ?
+      AND (gs.documentation IS NULL OR gs.documentation = '')
+      ${scopeFilter}
+    ORDER BY d.relative_path, der.start_line
+    LIMIT ?`,
+    minLoc, limit,
+  );
+
+  return {
+    totalSymbols: total,
+    documented,
+    undocumented: total - documented,
+    coveragePercent: total > 0 ? Math.round((documented / total) * 100) : 0,
+    undocumentedSymbols: undocRows
+      .filter((r) => !db.isIgnored(r.relative_path))
+      .map((r) => ({
+        symbol: r.symbol,
+        shortName: shortenSymbol(r.symbol),
+        relativePath: r.relative_path,
+        startLine: r.start_line,
+      })),
+  };
+}

package/src/queries/drift.ts

@@ -0,0 +1,224 @@
+import path from 'node:path';
+import type { ScipDatabase } from '../db.js';
+import { buildFileDepGraph } from '../query-support.js';
+import type { DriftResult, DriftSummary } from '../types.js';
+
+/**
+ * Detect structural drift using the reference graph, not just import patterns.
+ *
+ * Three types of drift, each detecting a real problem:
+ *
+ * 1. **Unused imports** — file depends on a module but never references
+ *    any of its symbols. Dead dependency, safe to remove.
+ *
+ * 2. **Layer violations** — file imports from a directory it shouldn't
+ *    based on the project's directory structure (e.g., a query importing
+ *    from reindex, a helper importing from CLI). Architectural decay.
+ *
+ * 3. **Pattern deviations** — file imports something no sibling does,
+ *    suggesting it's reaching outside its expected scope. Only flagged
+ *    when the file is the ONLY one in its directory with that dep.
+ */
+export function drift(
+  db: ScipDatabase,
+  opts?: { scope?: string; minDeviation?: number },
+): DriftSummary {
+  const { scope } = opts ?? {};
+
+  // Build file dep graph (which files depend on which)
+  const depGraph = buildFileDepGraph(db, scope);
+
+  // Build symbol-level reference graph: for each file, which other files'
+  // symbols does it actually reference?
+  const symbolRefs = buildSymbolRefGraph(db, scope);
+
+  const results: DriftResult[] = [];
+
+  // ── Angle 1: Unused imports ──────────────────────────────
+  // File depends on module B (via dep graph) but never references
+  // any symbol defined in B (via symbol ref graph).
+  for (const [file, deps] of depGraph) {
+    if (isStructuralRole(path.basename(file))) continue;
+
+    const referencedFiles = symbolRefs.get(file) ?? new Set<string>();
+
+    for (const dep of deps) {
+      if (!referencedFiles.has(dep)) {
+        // This file "depends on" dep but never references its symbols.
+        // This can happen when the dep is imported for types only
+        // (which don't appear in the mention graph). Skip type-heavy deps.
+        if (isLikelyTypeOnlyDep(dep)) continue;
+
+        results.push({
+          file,
+          kind: 'unused-import',
+          description: `Depends on ${dep} but references none of its symbols`,
+          dep,
+        });
+      }
+    }
+  }
+
+  // ── Angle 2: Layer violations ────────────────────────────
+  // Detect when a file imports from a directory that represents
+  // a different architectural layer. We infer layers from the
+  // directory structure: files in the same top-level dir are peers,
+  // files in different top-level dirs crossing inward is a violation.
+  const layerRules = inferLayerRules(depGraph);
+
+  for (const [file, deps] of depGraph) {
+    if (isStructuralRole(path.basename(file))) continue;
+
+    const fileLayer = getTopDir(file);
+    for (const dep of deps) {
+      const depLayer = getTopDir(dep);
+      if (fileLayer === depLayer) continue; // same layer, fine
+
+      const violation = layerRules.get(`${fileLayer}->${depLayer}`);
+      if (violation === 'violation') {
+        results.push({
+          file,
+          kind: 'layer-violation',
+          description: `Imports from ${depLayer}/ (${dep}) — may cross architectural boundary`,
+          dep,
+          detail: `${fileLayer}/ should not depend on ${depLayer}/`,
+        });
+      }
+    }
+  }
+
+  // ── Angle 3: Unique deps (pattern deviation) ─────────────
+  // If a file is the ONLY one in its directory that depends on a
+  // particular module, that dependency is unusual and worth flagging.
+  const dirToFiles = new Map<string, string[]>();
+  for (const file of depGraph.keys()) {
+    const dir = path.dirname(file);
+    if (!dirToFiles.has(dir)) dirToFiles.set(dir, []);
+    dirToFiles.get(dir)!.push(file);
+  }
+
+  for (const [dir, files] of dirToFiles) {
+    if (files.length < 3) continue;
+
+    // Count dep frequency across siblings
+    const depFreq = new Map<string, number>();
+    for (const file of files) {
+      if (isStructuralRole(path.basename(file))) continue;
+      for (const dep of depGraph.get(file) ?? []) {
+        depFreq.set(dep, (depFreq.get(dep) ?? 0) + 1);
+      }
+    }
+
+    for (const file of files) {
+      if (isStructuralRole(path.basename(file))) continue;
+      for (const dep of depGraph.get(file) ?? []) {
+        if ((depFreq.get(dep) ?? 0) === 1) {
+          // This file is the only one in its dir that depends on this module
+          // Skip if dep is in the same directory (sibling imports are normal)
+          if (path.dirname(dep) === dir) continue;
+
+          results.push({
+            file,
+            kind: 'pattern-deviation',
+            description: `Only file in ${dir}/ that depends on ${dep}`,
+            dep,
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    results,
+    unusedImports: results.filter((r) => r.kind === 'unused-import').length,
+    layerViolations: results.filter((r) => r.kind === 'layer-violation').length,
+    patternDeviations: results.filter((r) => r.kind === 'pattern-deviation').length,
+  };
+}
+
+// ── Helpers ────────────────────────────────────────────────
+
+/**
+ * Build a map of file → set of files whose symbols it references.
+ * This is more precise than the dep graph because it uses actual
+ * symbol mentions, not just import statements.
+ */
+function buildSymbolRefGraph(
+  db: ScipDatabase,
+  scope?: string,
+): Map<string, Set<string>> {
+  const scopeFilter = scope ? `AND d1.relative_path LIKE '%${scope}%'` : '';
+
+  const rows = db.all<{ from_file: string; to_file: string }>(
+    `SELECT DISTINCT d1.relative_path AS from_file, d2.relative_path AS to_file
+    FROM mentions m
+    JOIN chunks c ON m.chunk_id = c.id
+    JOIN documents d1 ON c.document_id = d1.id
+    JOIN global_symbols gs ON m.symbol_id = gs.id
+    JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
+    JOIN documents d2 ON der.document_id = d2.id
+    WHERE d1.id != d2.id
+      AND m.role = 0
+      ${db.pathExclusionsFor('d1', 'd2')}
+      ${scopeFilter}`,
+  );
+
+  const graph = new Map<string, Set<string>>();
+  for (const r of rows) {
+    if (db.isIgnored(r.from_file) || db.isIgnored(r.to_file)) continue;
+    if (!graph.has(r.from_file)) graph.set(r.from_file, new Set());
+    graph.get(r.from_file)!.add(r.to_file);
+  }
+  return graph;
+}
+
+/**
+ * Infer layer boundary rules from the dependency graph.
+ * If directory A never depends on directory B across the entire codebase,
+ * then a new A→B dependency is a violation.
+ */
+function inferLayerRules(
+  depGraph: Map<string, Set<string>>,
+): Map<string, 'ok' | 'violation'> {
+  const layerEdges = new Map<string, number>();
+  const layerSet = new Set<string>();
+
+  for (const [file, deps] of depGraph) {
+    const fromLayer = getTopDir(file);
+    layerSet.add(fromLayer);
+    for (const dep of deps) {
+      const toLayer = getTopDir(dep);
+      if (fromLayer === toLayer) continue;
+      layerSet.add(toLayer);
+      const key = `${fromLayer}->${toLayer}`;
+      layerEdges.set(key, (layerEdges.get(key) ?? 0) + 1);
+    }
+  }
+
+  // An edge that appears only 1-2 times across the whole codebase
+  // is likely a violation (anomalous cross-layer dep).
+  // Edges that appear many times are established patterns.
+  const rules = new Map<string, 'ok' | 'violation'>();
+  for (const [edge, count] of layerEdges) {
+    rules.set(edge, count <= 2 ? 'violation' : 'ok');
+  }
+
+  return rules;
+}
+
+function getTopDir(filePath: string): string {
+  const parts = filePath.split('/');
+  return parts[0] ?? filePath;
+}
+
+function isLikelyTypeOnlyDep(dep: string): boolean {
+  return dep.includes('types') || dep.endsWith('.d.ts');
+}
+
+function isStructuralRole(basename: string): boolean {
+  if (basename === 'index.ts' || basename === 'index.js') return true;
+  if (basename === 'cli.ts' || basename === 'main.ts' || basename === 'main.rs') return true;
+  if (basename.includes('worker.') || basename.includes('postinstall.')) return true;
+  if (basename === 'health.ts' || basename === 'health.js') return true;
+  return false;
+}