scip-query 0.1.0

package/src/config.ts

@@ -0,0 +1,117 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import type { ProjectConfig, WatchConfig } from './types.js';
+
+const CONFIG_FILENAME = '.scipquery.json';
+
+const DEFAULT_WATCH: Required<WatchConfig> = {
+  enabled: false,
+  debounceMs: 30_000,
+  cooldownMs: 60_000,
+  ignore: [],
+};
+
+/**
+ * Load project config from .scipquery.json in the project root.
+ * Returns defaults for anything not specified.
+ */
+export function loadProjectConfig(projectRoot: string): ProjectConfig {
+  const configPath = join(projectRoot, CONFIG_FILENAME);
+
+  if (!existsSync(configPath)) {
+    return {};
+  }
+
+  try {
+    const raw = readFileSync(configPath, 'utf-8');
+    return JSON.parse(raw) as ProjectConfig;
+  } catch {
+    return {};
+  }
+}
+
+/** Resolve watch config with defaults applied */
+export function resolveWatchConfig(config: ProjectConfig): Required<WatchConfig> {
+  return {
+    ...DEFAULT_WATCH,
+    ...config.watch,
+  };
+}
+
+/**
+ * Resolve the cache directory for a project's SCIP index.
+ *
+ * Default: ~/.cache/scip-query/projects/<hash>/
+ * Override: project config dbPath, or SCIP_QUERY_DB_PATH env var
+ *
+ * The hash is derived from the absolute project path so each
+ * project gets its own isolated index storage.
+ */
+export function resolveCacheDir(projectRoot: string, config?: ProjectConfig): string {
+  // CLI/env override
+  const envOverride = process.env['SCIP_QUERY_CACHE_DIR'];
+  if (envOverride) return ensureDir(envOverride);
+
+  // Project config override
+  if (config?.dbPath) return ensureDir(resolve(projectRoot, config.dbPath));
+
+  // Default: XDG cache dir / fallback to ~/.cache
+  const xdgCache = process.env['XDG_CACHE_HOME'];
+  const cacheBase = xdgCache || join(homedir(), '.cache');
+  const projectHash = createHash('sha256')
+    .update(resolve(projectRoot))
+    .digest('hex')
+    .slice(0, 12);
+
+  const dir = join(cacheBase, 'scip-query', 'projects', projectHash);
+  return ensureDir(dir);
+}
+
+/**
+ * Resolve all paths for a project's index files.
+ */
+export function resolveIndexPaths(projectRoot: string, config?: ProjectConfig): {
+  cacheDir: string;
+  dbPath: string;
+  indexPath: string;
+  metaPath: string;
+} {
+  const cacheDir = resolveCacheDir(projectRoot, config);
+  return {
+    cacheDir,
+    dbPath: join(cacheDir, 'index.db'),
+    indexPath: join(cacheDir, 'index.scip'),
+    metaPath: join(cacheDir, 'meta.json'),
+  };
+}
+
+/**
+ * Scaffold a default .scipquery.json in the project root.
+ * Does not overwrite an existing config.
+ */
+export function initProjectConfig(projectRoot: string, languages: string[]): string {
+  const configPath = join(projectRoot, CONFIG_FILENAME);
+
+  if (existsSync(configPath)) {
+    return configPath;
+  }
+
+  const config: ProjectConfig = {
+    languages: languages as ProjectConfig['languages'],
+    watch: {
+      enabled: false,
+      debounceMs: 30_000,
+      cooldownMs: 60_000,
+    },
+  };
+
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  return configPath;
+}
+
+function ensureDir(dir: string): string {
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}

package/src/db.ts

@@ -0,0 +1,127 @@
+import Database from 'better-sqlite3';
+import { statSync } from 'node:fs';
+import type { PathFilter } from './gitignore-filter.js';
+import type { ScipQueryConfig } from './types.js';
+
+/**
+ * Thin wrapper around better-sqlite3 with a pre-configured connection
+ * and helper methods for the SCIP SQLite schema.
+ *
+ * The schema is produced by `scip expt-convert` and is identical
+ * regardless of source language (TypeScript, Rust, Python, etc.).
+ *
+ * Tables:
+ *   documents             — indexed files (id, language, relative_path)
+ *   global_symbols        — all symbols (id, symbol, display_name, kind, documentation)
+ *   defn_enclosing_ranges — definition locations (document_id, symbol_id, start/end line/char)
+ *   mentions              — references & definitions (chunk_id, symbol_id, role)
+ *   chunks                — code segments (document_id, chunk_index, start/end line, occurrences)
+ */
+export class ScipDatabase {
+  readonly db: Database.Database;
+  readonly config: ScipQueryConfig;
+  private pathFilter: PathFilter | null;
+
+  constructor(config: ScipQueryConfig, pathFilter?: PathFilter) {
+    this.config = config;
+    this.pathFilter = pathFilter ?? null;
+    this.db = new Database(config.dbPath, { readonly: true });
+    this.db.pragma('busy_timeout = 5000');
+  }
+
+  /** Attach a gitignore-based path filter for query results */
+  setPathFilter(filter: PathFilter): void {
+    this.pathFilter = filter;
+  }
+
+  /** Check if a path should be excluded based on .gitignore rules */
+  isIgnored(relativePath: string): boolean {
+    return this.pathFilter?.isIgnored(relativePath) ?? false;
+  }
+
+  /** Filter an array of paths using the gitignore filter */
+  filterPaths(paths: string[]): string[] {
+    return this.pathFilter?.filter(paths) ?? paths;
+  }
+
+  /**
+   * The local-symbol predicate: only match symbols that are defined
+   * in files NOT excluded by gitignore. This replaces the old hardcoded
+   * `NOT LIKE 'node_modules/%'` check.
+   *
+   * Since SQLite can't evaluate JS gitignore rules inline, we use a
+   * simpler approach: query broadly, then filter in JS. For queries
+   * that need SQL-level filtering, use excludedPathPatterns().
+   */
+  get localSymbolPredicate(): string {
+    // Basic SQL-level exclusions for the most common cases.
+    // JS-level gitignore filtering handles the rest post-query.
+    return `EXISTS (
+      SELECT 1
+      FROM defn_enclosing_ranges local_der
+      JOIN documents local_d ON local_der.document_id = local_d.id
+      WHERE local_der.symbol_id = gs.id
+        ${this.pathExclusionsFor('local_d').trimStart()}
+    )`;
+  }
+
+  /**
+   * SQL WHERE clause fragments to exclude common build/dependency paths.
+   * Complements the JS-level gitignore filtering for performance.
+   */
+  get pathExclusions(): string {
+    return this.pathExclusionsFor('d');
+  }
+
+  /** Reusable SQL fragment: filter out synthetic/internal symbol noise */
+  get symbolNoise(): string {
+    return this.symbolNoiseFor('gs');
+  }
+
+  /** Build SQL path exclusions for one or more document table aliases */
+  pathExclusionsFor(...aliases: string[]): string {
+    return aliases
+      .flatMap((alias) => [
+        `AND ${alias}.relative_path NOT LIKE 'node_modules/%'`,
+        `AND ${alias}.relative_path NOT LIKE '.git/%'`,
+      ])
+      .join('\n      ');
+  }
+
+  /** Build SQL symbol exclusions for the given global_symbols alias */
+  symbolNoiseFor(alias: string): string {
+    return `AND ${alias}.symbol NOT LIKE '%().(%' AND ${alias}.symbol NOT LIKE '%typeLiteral%'`;
+  }
+
+  /** Run a raw SQL query and return all rows */
+  all<T = Record<string, unknown>>(sql: string, ...params: unknown[]): T[] {
+    return this.db.prepare(sql).all(...params) as T[];
+  }
+
+  /** Run a raw SQL query and return the first row */
+  get<T = Record<string, unknown>>(sql: string, ...params: unknown[]): T | undefined {
+    return this.db.prepare(sql).get(...params) as T | undefined;
+  }
+
+  /** Get the database file size in bytes */
+  sizeBytes(): number {
+    try {
+      return statSync(this.config.dbPath).size;
+    } catch {
+      return 0;
+    }
+  }
+
+  /** Get the last modification time of the database file */
+  lastModified(): Date | null {
+    try {
+      return statSync(this.config.dbPath).mtime;
+    } catch {
+      return null;
+    }
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}

package/src/gitignore-filter.ts

@@ -0,0 +1,143 @@
+import ignore, { type Ignore } from 'ignore';
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+/**
+ * Builds a gitignore-based path filter from .gitignore files found
+ * in the project directory tree. This replaces hardcoded path exclusions
+ * like "node_modules/", "dist/", "target/", "__pycache__/" — instead,
+ * we respect whatever the project already ignores.
+ *
+ * Falls back to sensible defaults if no .gitignore is found.
+ */
+export function createGitignoreFilter(projectRoot: string): PathFilter {
+  const ig = ignore();
+  let loaded = false;
+
+  // Walk up from project root looking for .gitignore files
+  // (nested .gitignore files apply to their subdirectory)
+  const gitignorePaths = findGitignoreFiles(projectRoot);
+
+  for (const gitignorePath of gitignorePaths) {
+    try {
+      const content = readFileSync(gitignorePath, 'utf-8');
+      ig.add(content);
+      loaded = true;
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  // If no .gitignore found, use universal defaults
+  if (!loaded) {
+    ig.add(DEFAULT_IGNORES);
+  }
+
+  return {
+    isIgnored: (relativePath: string) => ig.ignores(relativePath),
+    filter: (paths: string[]) => paths.filter((p) => !ig.ignores(p)),
+  };
+}
+
+export interface PathFilter {
+  /** Returns true if this path should be excluded from results */
+  isIgnored: (relativePath: string) => boolean;
+  /** Filter an array of paths, keeping only non-ignored ones */
+  filter: (paths: string[]) => string[];
+}
+
+/**
+ * Find all .gitignore files from project root (including nested ones).
+ * We look at the root .gitignore and any in immediate subdirectories
+ * but don't recursively walk the entire tree (too expensive for large repos).
+ */
+function findGitignoreFiles(projectRoot: string): string[] {
+  const files: string[] = [];
+
+  // Root .gitignore
+  const rootGitignore = join(projectRoot, '.gitignore');
+  if (existsSync(rootGitignore)) {
+    files.push(rootGitignore);
+  }
+
+  // Also check parent directories (for monorepo setups where .gitignore
+  // is at the repo root but the project is in a subdirectory)
+  let dir = dirname(projectRoot);
+  let depth = 0;
+  while (dir !== dirname(dir) && depth < 5) {
+    const parentGitignore = join(dir, '.gitignore');
+    if (existsSync(parentGitignore)) {
+      files.push(parentGitignore);
+    }
+    // Stop if we find a .git directory — that's the repo root
+    if (existsSync(join(dir, '.git'))) break;
+    dir = dirname(dir);
+    depth++;
+  }
+
+  return files;
+}
+
+/**
+ * Universal defaults when no .gitignore exists.
+ * Covers build artifacts, dependency directories, and virtual environments
+ * across all SCIP-supported languages.
+ */
+const DEFAULT_IGNORES = `
+# Dependencies
+node_modules/
+vendor/
+.bundle/
+
+# Build output
+dist/
+build/
+out/
+target/
+bin/
+obj/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+.env/
+env/
+*.egg-info/
+
+# Rust
+target/
+
+# Java / Kotlin / Scala
+*.class
+.gradle/
+.mvn/
+
+# C# / .NET
+bin/
+obj/
+packages/
+
+# Go
+vendor/
+
+# Dart
+.dart_tool/
+build/
+
+# PHP
+vendor/
+
+# IDE / OS
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Type definitions (often noise in queries)
+*.d.ts
+`;

package/src/index.ts

@@ -0,0 +1,11 @@
+// scip-query — Language-agnostic code intelligence powered by SCIP indexes
+
+export { ScipDatabase } from './db.js';
+export { createGitignoreFilter } from './gitignore-filter.js';
+export { parseSymbol, shortenSymbol, leafName } from './symbol-parser.js';
+export { reindex, detectLanguages, getIndexerConfig, INDEXER_CONFIGS, isBinaryAvailable, isIndexerInstalled, tryInstallIndexer, tryInstallScipCli } from './reindex/index.js';
+export { loadProjectConfig, resolveIndexPaths, resolveCacheDir, initProjectConfig } from './config.js';
+export { Watcher } from './watch.js';
+export { installSkills, isScipInstalled, getScipVersion, printScipInstallInstructions } from './setup.js';
+export * from './queries/index.js';
+export type * from './types.js';

package/src/postinstall.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * npm postinstall hook. Runs automatically after `npm install -g scip-query`.
+ * Installs skills into Claude Code and Codex, checks for scip binary.
+ */
+import { postinstall } from './setup.js';
+
+postinstall();

package/src/queries/affected.ts

@@ -0,0 +1,86 @@
+import type { ScipDatabase } from '../db.js';
+import { findFirstSymbolMatch } from '../query-support.js';
+import type { AffectedResult } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Full transitive closure of symbols that could break if a given symbol changes.
+ * BFS from the target through the mention graph: depth 1 = direct consumers,
+ * depth 2 = consumers of consumers, etc.
+ */
+export function affected(
+  db: ScipDatabase,
+  symbolPattern: string,
+  opts: { maxDepth?: number; scope?: string } = {},
+): AffectedResult[] {
+  const { maxDepth = 5, scope } = opts;
+
+  const target = findFirstSymbolMatch(db, symbolPattern);
+  if (!target) return [];
+
+  const scopeFilter = scope
+    ? `AND enc_d.relative_path LIKE '%${scope}%'`
+    : '';
+
+  const results: AffectedResult[] = [];
+  const visited = new Set<number>([target.symbolId]);
+  let frontier = new Set<number>([target.symbolId]);
+
+  for (let depth = 1; depth <= maxDepth; depth++) {
+    if (frontier.size === 0) break;
+
+    const placeholders = [...frontier].map(() => '?').join(',');
+    const nextFrontier = new Set<number>();
+
+    // For each symbol in the frontier, find enclosing symbols whose
+    // definition ranges contain a reference (role=0) to that frontier symbol.
+    const rows = db.all<{
+      symbol_id: number;
+      symbol: string;
+      relative_path: string;
+    }>(
+      `SELECT DISTINCT
+        enc_gs.id AS symbol_id,
+        enc_gs.symbol AS symbol,
+        enc_d.relative_path AS 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
+      JOIN defn_enclosing_ranges enc_der
+        ON enc_der.document_id = ref_d.id
+        AND c.start_line >= enc_der.start_line
+        AND c.end_line <= enc_der.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
+      WHERE m.symbol_id IN (${placeholders})
+        AND m.role = 0
+        AND enc_gs.id NOT IN (${placeholders})
+        ${db.symbolNoiseFor('enc_gs')}
+        ${db.pathExclusionsFor('enc_d')}
+        ${scopeFilter}`,
+      ...[...frontier],
+      ...[...frontier],
+    );
+
+    for (const row of rows) {
+      if (visited.has(row.symbol_id)) continue;
+      if (db.isIgnored(row.relative_path)) continue;
+
+      visited.add(row.symbol_id);
+      nextFrontier.add(row.symbol_id);
+
+      results.push({
+        symbol: row.symbol,
+        shortName: shortenSymbol(row.symbol),
+        file: row.relative_path,
+        depth,
+      });
+    }
+
+    frontier = nextFrontier;
+  }
+
+  // Sort by depth then file path
+  results.sort((a, b) => a.depth - b.depth || a.file.localeCompare(b.file));
+  return results;
+}

package/src/queries/bottlenecks.ts

@@ -0,0 +1,67 @@
+import type { ScipDatabase } from '../db.js';
+import type { BottleneckResult } from '../types.js';
+import { shortenSymbol } from '../symbol-parser.js';
+
+/**
+ * Find coupling hubs: symbols with both high fan-in (many consumers)
+ * AND high fan-out (references many other symbols).
+ *
+ * These are the most dangerous symbols to change — they sit at the
+ * intersection of many dependency paths. Score = fanIn * fanOut.
+ */
+export function bottlenecks(
+  db: ScipDatabase,
+  opts: { limit?: number; scope?: string; minFanIn?: number; minFanOut?: number } = {},
+): BottleneckResult[] {
+  const { limit = 20, scope, minFanIn = 2, minFanOut = 2 } = opts;
+  const scopeFilter = scope ? `AND def_d.relative_path LIKE '%${scope}%'` : '';
+
+  // Use a wrapping query to filter on computed columns
+  const rows = db.all<{
+    symbol: string;
+    defined_in: string;
+    fan_in: number;
+    fan_out: number;
+  }>(
+    `SELECT * FROM (
+      SELECT
+        gs.symbol,
+        def_d.relative_path AS defined_in,
+        (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,
+        (SELECT COUNT(DISTINCT ref_gs.id)
+         FROM mentions ref_m
+         JOIN chunks ref_c ON ref_m.chunk_id = ref_c.id
+         JOIN global_symbols ref_gs ON ref_m.symbol_id = ref_gs.id
+         JOIN defn_enclosing_ranges ref_der ON ref_gs.id = ref_der.symbol_id
+         WHERE ref_c.document_id = def_d.id
+           AND ref_m.role = 0
+           AND ref_der.document_id != def_d.id
+        ) AS fan_out
+      FROM global_symbols gs
+      JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
+      JOIN documents def_d ON der.document_id = def_d.id
+      WHERE 1 = 1
+        ${db.pathExclusionsFor('def_d')}
+        ${db.symbolNoiseFor('gs')}
+        ${scopeFilter}
+    ) WHERE fan_in >= ? AND fan_out >= ?
+    ORDER BY (fan_in * fan_out) DESC
+    LIMIT ?`,
+    minFanIn, minFanOut, limit,
+  );
+
+  return rows
+    .filter((r) => !db.isIgnored(r.defined_in))
+    .map((r) => ({
+      symbol: r.symbol,
+      shortName: shortenSymbol(r.symbol),
+      fanIn: r.fan_in,
+      fanOut: r.fan_out,
+      score: r.fan_in * r.fan_out,
+      definedIn: r.defined_in,
+    }));
+}