scip-query 0.1.0

package/dist/db-BxaevAyc.d.ts

@@ -0,0 +1,683 @@
+import Database from 'better-sqlite3';
+
+/**
+ * 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.
+ */
+declare function createGitignoreFilter(projectRoot: string): PathFilter;
+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[];
+}
+
+/** Parsed components of a SCIP symbol string */
+interface ScipSymbol {
+    /** The indexer scheme (e.g. "scip-typescript", "scip-java", "rust-analyzer") */
+    scheme: string;
+    /** Package manager (e.g. "npm", "maven", "cargo") */
+    manager: string;
+    /** Package name (e.g. "@vega/api", "com.example/mylib") */
+    packageName: string;
+    /** Package version */
+    version: string;
+    /** Descriptor chain — the path to the symbol within the file */
+    descriptors: ScipDescriptor[];
+    /** The raw, unparsed symbol string */
+    raw: string;
+}
+interface ScipDescriptor {
+    name: string;
+    suffix: DescriptorSuffix;
+}
+type DescriptorSuffix = 'namespace' | 'type' | 'term' | 'method' | 'type-param' | 'parameter' | 'meta' | 'macro';
+/** A local symbol (file-scoped, no cross-file identity) */
+interface ScipLocalSymbol {
+    kind: 'local';
+    id: string;
+    raw: string;
+}
+interface StatsResult {
+    documents: number;
+    symbols: number;
+    definitions: number;
+    references: number;
+    indexSizeBytes: number;
+    lastBuilt: Date | null;
+}
+interface FileResult {
+    relativePath: string;
+}
+interface SymbolResult {
+    startLine: number;
+    endLine: number;
+    symbol: string;
+    shortName: string;
+    signature: string | null;
+}
+interface MethodResult {
+    startLine: number;
+    endLine: number;
+    name: string;
+}
+interface RefResult {
+    relativePath: string;
+    line: number;
+}
+interface DepResult {
+    relativePath: string;
+}
+interface TraceResult {
+    definitions: Array<{
+        relativePath: string;
+        startLine: number;
+        endLine: number;
+        signature: string | null;
+    }>;
+    referencedBy: string[];
+}
+interface SystemResult {
+    files: string[];
+    symbols: SymbolResult[];
+    dependsOn: string[];
+    dependedOnBy: string[];
+}
+interface SurfaceResult {
+    consumer: string;
+    symbol: string;
+    shortName: string;
+}
+interface DeadSymbolResult {
+    relativePath: string;
+    startLine: number;
+    endLine: number;
+    loc: number;
+    symbol: string;
+    shortName: string;
+    sameFileRefs: number;
+    kind: 'dead-code' | 'file-internal';
+}
+interface DeadSummary {
+    symbols: DeadSymbolResult[];
+    totalCount: number;
+    /** Symbols with zero references anywhere — safe to delete */
+    deadCodeCount: number;
+    /** Symbols referenced only within their own file — no cross-file consumers.
+     *  May be private helpers (fine) or forgotten exports (needs review). */
+    fileInternalCount: number;
+    totalLoc: number;
+}
+interface HotspotResult {
+    symbol: string;
+    shortName: string;
+    refCount: number;
+    fileCount: number;
+    definedIn: string;
+}
+interface ImportResult {
+    symbol: string;
+    shortName: string;
+    fromFile: string;
+}
+interface UnusedImportResult {
+    symbol: string;
+    shortName: string;
+    importedIn: string;
+}
+interface OutlineNode {
+    symbol: string;
+    shortName: string;
+    startLine: number;
+    endLine: number;
+    children: OutlineNode[];
+}
+interface MemberResult {
+    symbol: string;
+    shortName: string;
+    startLine: number;
+    endLine: number;
+    kind: string;
+}
+interface FanResult {
+    name: string;
+    count: number;
+}
+interface CouplingResult {
+    file1: string;
+    file2: string;
+    sharedSymbols: number;
+}
+interface CycleResult {
+    /** Files forming a cycle, in order */
+    path: string[];
+}
+interface BottleneckResult {
+    symbol: string;
+    shortName: string;
+    fanIn: number;
+    fanOut: number;
+    /** fanIn * fanOut — higher = more central coupling hub */
+    score: number;
+    definedIn: string;
+}
+interface IsolatedResult {
+    symbol: string;
+    shortName: string;
+    relativePath: string;
+    startLine: number;
+    endLine: number;
+    loc: number;
+}
+interface ByKindResult {
+    symbol: string;
+    shortName: string;
+    kind: number;
+    kindName: string;
+    relativePath: string;
+    startLine: number;
+    endLine: number;
+}
+interface TestCoverageResult {
+    symbol: string;
+    shortName: string;
+    definedIn: string;
+    testFiles: string[];
+    covered: boolean;
+}
+interface DocCoverageResult {
+    totalSymbols: number;
+    documented: number;
+    undocumented: number;
+    coveragePercent: number;
+    undocumentedSymbols: Array<{
+        symbol: string;
+        shortName: string;
+        relativePath: string;
+        startLine: number;
+    }>;
+}
+interface DeepChainResult {
+    /** Files in the chain, from leaf to root */
+    chain: string[];
+    depth: number;
+}
+interface HierarchyNode {
+    symbol: string;
+    shortName: string;
+    depth: number;
+}
+interface CallGraphResult {
+    symbol: string;
+    shortName: string;
+    /** Symbols that call this one (incoming) */
+    callers: Array<{
+        symbol: string;
+        shortName: string;
+        file: string;
+    }>;
+    /** Symbols called by this one (outgoing) */
+    callees: Array<{
+        symbol: string;
+        shortName: string;
+        file: string;
+    }>;
+}
+interface DriftResult {
+    file: string;
+    kind: 'unused-import' | 'layer-violation' | 'pattern-deviation';
+    description: string;
+    /** The dependency involved */
+    dep: string;
+    /** For layer violations: the expected layer boundary */
+    detail?: string;
+}
+interface DriftSummary {
+    results: DriftResult[];
+    unusedImports: number;
+    layerViolations: number;
+    patternDeviations: number;
+}
+interface WrapperCandidate {
+    symbol: string;
+    shortName: string;
+    file: string;
+    startLine: number;
+    endLine: number;
+    loc: number;
+    singleCaller: string;
+    singleCallerShort: string;
+    callerFanIn: number;
+}
+interface PassthroughCandidate {
+    symbol: string;
+    shortName: string;
+    file: string;
+    startLine: number;
+    endLine: number;
+    loc: number;
+    forwardsTo: string;
+    forwardsToShort: string;
+    forwardsToFile: string;
+}
+interface StaleAbstraction {
+    symbol: string;
+    shortName: string;
+    file: string;
+    startLine: number;
+    endLine: number;
+    loc: number;
+    consumers: number;
+}
+interface ComplexityHotspot {
+    symbol: string;
+    shortName: string;
+    file: string;
+    startLine: number;
+    endLine: number;
+    loc: number;
+    fanIn: number;
+    fanOut: number;
+    calleeCount: number;
+    score: number;
+}
+interface SimilarSymbolResult {
+    symbolA: string;
+    shortNameA: string;
+    fileA: string;
+    symbolB: string;
+    shortNameB: string;
+    fileB: string;
+    /** Jaccard similarity of callee sets (0-1) */
+    similarity: number;
+    /** Callees shared by both symbols */
+    sharedCallees: string[];
+    /** Callees unique to A */
+    uniqueToA: string[];
+    /** Callees unique to B */
+    uniqueToB: string[];
+}
+interface SimilarFileResult {
+    fileA: string;
+    fileB: string;
+    /** Jaccard similarity of dependency sets (0-1) */
+    similarity: number;
+    sharedDeps: string[];
+    uniqueToA: string[];
+    uniqueToB: string[];
+}
+interface SimilarChainResult {
+    chainA: string[];
+    chainB: string[];
+    /** Fraction of nodes shared (0-1) */
+    similarity: number;
+    /** Edit distance between the two chains */
+    editDistance: number;
+    /** Indices where the chains diverge — the consolidation targets */
+    divergencePoints: Array<{
+        index: number;
+        nodeA: string;
+        nodeB: string;
+    }>;
+    /** Shared prefix */
+    commonPrefix: string[];
+    /** Shared suffix */
+    commonSuffix: string[];
+}
+interface ExtractCandidate {
+    symbol: string;
+    shortName: string;
+    relativePath: string;
+    startLine: number;
+    endLine: number;
+    loc: number;
+    /** Total callees */
+    totalCallees: number;
+    /** Distinct clusters of callees (natural extraction seams) */
+    clusters: Array<{
+        callees: string[];
+        /** How isolated this cluster is from the rest (0-1, higher = more extractable) */
+        isolation: number;
+    }>;
+}
+interface HealthAction {
+    category: string;
+    description: string;
+    effort: 'low' | 'medium' | 'high';
+    impact: 'low' | 'medium' | 'high';
+    count: number;
+    locRecoverable: number;
+}
+interface HealthReport {
+    score: number;
+    overview: {
+        documents: number;
+        symbols: number;
+        indexSizeBytes: number;
+    };
+    findings: {
+        deadSymbols: number;
+        deadLoc: number;
+        isolatedSymbols: number;
+        isolatedLoc: number;
+        cycles: number;
+        similarPairs: number;
+        extractionCandidates: number;
+        wrappers: number;
+        passthroughs: number;
+        staleTypes: number;
+        driftedFiles: number;
+        complexityHotspotCount: number;
+        testCoveragePercent: number;
+    };
+    actions: HealthAction[];
+    topComplexity: Array<{
+        symbol: string;
+        score: number;
+    }>;
+}
+interface ConvergenceResult {
+    symbolA: {
+        symbol: string;
+        shortName: string;
+        file: string;
+        loc: number;
+    };
+    symbolB: {
+        symbol: string;
+        shortName: string;
+        file: string;
+        loc: number;
+    };
+    similarity: number;
+    sharedCallees: string[];
+    uniqueToA: string[];
+    uniqueToB: string[];
+    consolidationStrategy: string;
+}
+interface CodeResult {
+    symbol: string;
+    shortName: string;
+    relativePath: string;
+    startLine: number;
+    endLine: number;
+    language: string | null;
+    source: string;
+}
+interface ComplexityResult {
+    symbol: string;
+    shortName: string;
+    relativePath: string;
+    startLine: number;
+    endLine: number;
+    loc: number;
+    /** Branch count from source-level regex (if, else, for, while, switch, catch, ternary, &&, ||) */
+    branches: number;
+    /** Cyclomatic complexity estimate: branches + 1 */
+    cyclomaticEstimate: number;
+    /** Number of distinct callees within the definition */
+    calleeCount: number;
+    fanIn: number;
+    fanOut: number;
+}
+interface DataflowResult {
+    symbol: string;
+    shortName: string;
+    relativePath: string;
+    /** Where the symbol is defined (role=1) */
+    definitionSites: Array<{
+        file: string;
+        line: number;
+    }>;
+    /** Where the symbol is referenced (role=0) */
+    usageSites: Array<{
+        file: string;
+        line: number;
+        enclosingSymbol: string;
+        enclosingShort: string;
+    }>;
+    /** Symbols that appear in the same function that defines this symbol (producers/inputs) */
+    producers: Array<{
+        symbol: string;
+        shortName: string;
+        file: string;
+    }>;
+    /** Symbols defined by functions that reference this symbol (consumers/outputs) */
+    consumers: Array<{
+        symbol: string;
+        shortName: string;
+        file: string;
+    }>;
+}
+interface SliceResult {
+    symbol: string;
+    shortName: string;
+    direction: 'backward' | 'forward';
+    /** Backward: symbols referenced in the same function as the target's definition (inputs) */
+    /** Forward: symbols defined by functions that reference the target (outputs) */
+    connectedSymbols: Array<{
+        symbol: string;
+        shortName: string;
+        file: string;
+        relationship: string;
+    }>;
+}
+interface AffectedResult {
+    symbol: string;
+    shortName: string;
+    file: string;
+    depth: number;
+}
+interface ChangeSurfaceEntry {
+    symbol: string;
+    shortName: string;
+    startLine: number;
+    endLine: number;
+    externalConsumers: number;
+    testFiles: string[];
+    riskLevel: 'low' | 'medium' | 'high';
+}
+interface ChangeSurfaceResult {
+    file: string;
+    symbols: ChangeSurfaceEntry[];
+    totalExternalConsumers: number;
+    testCoveragePercent: number;
+}
+interface DiffImpactResult {
+    changedFiles: string[];
+    changedSymbols: Array<{
+        symbol: string;
+        shortName: string;
+        file: string;
+        fanIn: number;
+    }>;
+    affectedConsumers: Array<{
+        file: string;
+        consumedSymbols: number;
+    }>;
+    uncoveredSymbols: Array<{
+        symbol: string;
+        shortName: string;
+        file: string;
+    }>;
+    summary: {
+        totalChangedFiles: number;
+        totalChangedSymbols: number;
+        totalAffectedFiles: number;
+        testCoveragePercent: number;
+    };
+}
+interface DeadOptions {
+    scope?: string;
+    minLoc?: number;
+    includeTests?: boolean;
+    skipBarrels?: boolean;
+    includeMembers?: boolean;
+}
+interface InstallMethod {
+    /** Human-readable label (e.g., "npm", "pip", "go install") */
+    label: string;
+    /** Binary that must exist for this install method to work (e.g., "npm", "pip3", "go") */
+    prerequisite: string;
+    /** Command to execute */
+    binary: string;
+    /** Arguments for the command */
+    args: string[];
+}
+type SupportedLanguage = 'typescript' | 'javascript' | 'java' | 'scala' | 'kotlin' | 'rust' | 'python' | 'ruby' | 'go' | 'cpp' | 'c' | 'csharp' | 'dart' | 'php';
+interface IndexerConfig {
+    language: SupportedLanguage;
+    /** The npm/cargo/pip package or binary that produces the SCIP index */
+    indexerBinary: string;
+    /** Command to check if the indexer is installed */
+    checkCommand: string;
+    /** Returns the binary + args array for execFileSync (no shell injection) */
+    indexArgs: (opts: {
+        projectRoot: string;
+        outputPath: string;
+        pnpmWorkspaces?: boolean;
+    }) => {
+        binary: string;
+        args: string[];
+    };
+    /** Marker files that indicate this language is present */
+    markerFiles: string[];
+    /** Installation methods to try in order of preference */
+    installMethods?: InstallMethod[];
+    /** URL for manual installation if auto-install fails */
+    installUrl?: string;
+}
+interface ScipQueryConfig {
+    /** Path to the SQLite database (index.db) */
+    dbPath: string;
+    /** Path to the SCIP protobuf index (index.scip) */
+    indexPath: string;
+    /** Project root directory */
+    projectRoot: string;
+    /** Paths to .gitignore files to load for filtering */
+    gitignorePaths?: string[];
+}
+interface ProjectConfig {
+    /** Override which languages to index (default: auto-detect) */
+    languages?: SupportedLanguage[];
+    /** Watch mode settings */
+    watch?: WatchConfig;
+    /** Per-language indexer overrides */
+    indexer?: Partial<Record<SupportedLanguage, IndexerOverrides>>;
+    /** Override the database storage path (default: ~/.cache/scip-query/<hash>/) */
+    dbPath?: string;
+}
+interface WatchConfig {
+    /** Enable file watching (default: false, must opt in) */
+    enabled?: boolean;
+    /** Ms to wait after the last file change before triggering reindex (default: 30000) */
+    debounceMs?: number;
+    /** Minimum ms between reindex completions (default: 60000) */
+    cooldownMs?: number;
+    /** Extra glob patterns to ignore beyond .gitignore */
+    ignore?: string[];
+}
+interface IndexerOverrides {
+    /** Enable pnpm workspace support (TypeScript) */
+    pnpmWorkspaces?: boolean;
+}
+interface RedundantReexport {
+    barrelFile: string;
+    symbol: string;
+    shortName: string;
+    originalFile: string;
+    /** How many consumers import through the barrel */
+    barrelConsumers: number;
+    /** How many consumers import directly from the source */
+    directConsumers: number;
+}
+interface SimilarSignatureGroup {
+    /** The normalized signature shared by all functions in the group */
+    signature: string;
+    /** Functions that share this signature */
+    functions: Array<{
+        symbol: string;
+        shortName: string;
+        file: string;
+        startLine: number;
+        endLine: number;
+        loc: number;
+    }>;
+}
+type WatcherStatus = {
+    state: 'idle';
+} | {
+    state: 'waiting';
+    changedFiles: number;
+    reindexAt: number;
+} | {
+    state: 'indexing';
+    startedAt: number;
+} | {
+    state: 'cooldown';
+    until: number;
+    dirty: boolean;
+};
+
+/**
+ * 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)
+ */
+declare class ScipDatabase {
+    readonly db: Database.Database;
+    readonly config: ScipQueryConfig;
+    private pathFilter;
+    constructor(config: ScipQueryConfig, pathFilter?: PathFilter);
+    /** Attach a gitignore-based path filter for query results */
+    setPathFilter(filter: PathFilter): void;
+    /** Check if a path should be excluded based on .gitignore rules */
+    isIgnored(relativePath: string): boolean;
+    /** Filter an array of paths using the gitignore filter */
+    filterPaths(paths: string[]): string[];
+    /**
+     * 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;
+    /**
+     * SQL WHERE clause fragments to exclude common build/dependency paths.
+     * Complements the JS-level gitignore filtering for performance.
+     */
+    get pathExclusions(): string;
+    /** Reusable SQL fragment: filter out synthetic/internal symbol noise */
+    get symbolNoise(): string;
+    /** Build SQL path exclusions for one or more document table aliases */
+    pathExclusionsFor(...aliases: string[]): string;
+    /** Build SQL symbol exclusions for the given global_symbols alias */
+    symbolNoiseFor(alias: string): string;
+    /** Run a raw SQL query and return all rows */
+    all<T = Record<string, unknown>>(sql: string, ...params: unknown[]): T[];
+    /** Run a raw SQL query and return the first row */
+    get<T = Record<string, unknown>>(sql: string, ...params: unknown[]): T | undefined;
+    /** Get the database file size in bytes */
+    sizeBytes(): number;
+    /** Get the last modification time of the database file */
+    lastModified(): Date | null;
+    close(): void;
+}
+
+export { type WatcherStatus as $, type AffectedResult as A, type BottleneckResult as B, type CallGraphResult as C, type DataflowResult as D, type ExtractCandidate as E, type FanResult as F, type SimilarFileResult as G, type HealthReport as H, type ImportResult as I, type SimilarChainResult as J, type StaleAbstraction as K, type SliceResult as L, type MemberResult as M, type RedundantReexport as N, type OutlineNode as O, type PassthroughCandidate as P, type SimilarSignatureGroup as Q, type RefResult as R, ScipDatabase as S, type TraceResult as T, type UnusedImportResult as U, type ScipSymbol as V, type WrapperCandidate as W, type ScipLocalSymbol as X, type SupportedLanguage as Y, type IndexerConfig as Z, type ProjectConfig as _, type ByKindResult as a, type ChangeSurfaceEntry as a0, type DeadSymbolResult as a1, type DescriptorSuffix as a2, type DriftResult as a3, type HealthAction as a4, type IndexerOverrides as a5, type InstallMethod as a6, type ScipDescriptor as a7, type ScipQueryConfig as a8, type WatchConfig as a9, createGitignoreFilter as aa, type ChangeSurfaceResult as b, type CodeResult as c, type ComplexityHotspot as d, type ComplexityResult as e, type ConvergenceResult as f, type CouplingResult as g, type CycleResult as h, type DeadOptions as i, type DeadSummary as j, type DeepChainResult as k, type DepResult as l, type DiffImpactResult as m, type DocCoverageResult as n, type DriftSummary as o, type FileResult as p, type HierarchyNode as q, type HotspotResult as r, type IsolatedResult as s, type MethodResult as t, type StatsResult as u, type SymbolResult as v, type SystemResult as w, type SurfaceResult as x, type TestCoverageResult as y, type SimilarSymbolResult as z };