scip-query 0.6.4 → 0.6.5

package/dist/{db-DKhNQ75l.d.ts → db-BZPa7dzJ.d.ts}

@@ -91,6 +91,7 @@ interface ParsedSourceImport {
     kind: 'named' | 'default' | 'namespace' | 'side-effect';
     used: boolean;
     usedMembers: string[];
+    isTypeOnly?: boolean;
 }
 /**
  * A single export-from binding parsed out of a source file. Used by the
@@ -417,13 +418,15 @@ interface SimilarSymbolResult {
     symbolB: string;
     shortNameB: string;
     fileB: string;
-    /** Jaccard similarity of callee sets (0-1) */
+    /** Similarity score (0-1). Basis says what evidence was compared. */
     similarity: number;
-    /** Callees shared by both symbols */
+    /** Evidence used for similarity: call graph callees or lexical source tokens. */
+    similarityBasis?: 'callees' | 'source-tokens';
+    /** Shared callees or source tokens, depending on similarityBasis. */
     sharedCallees: string[];
-    /** Callees unique to A */
+    /** Callees or source tokens unique to A, depending on similarityBasis. */
     uniqueToA: string[];
-    /** Callees unique to B */
+    /** Callees or source tokens unique to B, depending on similarityBasis. */
     uniqueToB: string[];
 }
 interface SimilarFileResult {
@@ -693,6 +696,8 @@ interface ScipQueryConfig {
     entryRoots?: EntryRootsConfig;
     /** Paths to .gitignore files to load for filtering */
     gitignorePaths?: string[];
+    /** Optional semantic-provider configuration */
+    semantic?: SemanticConfig;
 }
 interface ProjectConfig {
     /** Override which languages to index (default: auto-detect) */
@@ -705,6 +710,15 @@ interface ProjectConfig {
     dbPath?: string;
     /** Project-specific externally-live roots for dead-code filtering */
     entryRoots?: EntryRootsConfig;
+    /** Optional semantic-provider configuration */
+    semantic?: SemanticConfig;
+}
+interface SemanticConfig {
+    typescript?: TypeScriptSemanticConfig;
+}
+interface TypeScriptSemanticConfig {
+    /** Explicit tsconfig paths, relative to project root unless absolute */
+    tsconfigs?: string[];
 }
 interface EntryRootsConfig {
     /** Any symbol defined in these path prefixes is externally live */
@@ -814,11 +828,7 @@ declare class ScipDatabase {
     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 DeadSymbolResult 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 SimilarChainResult as G, type HealthReport as H, type ImportResult as I, type StaleAbstraction as J, type SliceResult as K, type SimilarSignatureGroup as L, type MemberResult as M, type ScipSymbol as N, type OutlineNode as O, type PassthroughCandidate as P, type ScipLocalSymbol as Q, type RedundantReexport as R, ScipDatabase as S, type TraceResult as T, type UnusedImportResult as U, type SupportedLanguage as V, type WrapperCandidate as W, type IndexerConfig as X, type ProjectConfig as Y, type WatcherStatus as Z, type ChangeSurfaceEntry as _, type ByKindResult as a, type DescriptorSuffix as a0, type DocumentPathCandidate as a1, type DriftResult as a2, type EntryRootsConfig as a3, type HealthAction as a4, type IndexedDefinition as a5, type IndexerOverrides as a6, type InstallMethod as a7, type ParsedReExport as a8, type ParsedSourceExport as a9, type ParsedSourceImport as aa, type ReferenceSite as ab, type ScipDescriptor as ac, type ScipQueryConfig as ad, type SymbolLocation as ae, type SymbolMatch as af, type WatchConfig as ag, createGitignoreFilter as ah, 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 DriftSummary as n, type FileResult as o, type HierarchyNode as p, type HotspotResult as q, type IsolatedResult as r, type MethodResult as s, type StatsResult as t, type SymbolResult as u, type RefResult as v, type SystemResult as w, type SurfaceResult as x, type SimilarSymbolResult as y, type SimilarFileResult as z };
+export { type ProjectConfig 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 StaleAbstraction as G, type HealthReport as H, type ImportResult as I, type SliceResult as J, type RedundantReexport as K, type SimilarSignatureGroup as L, type MemberResult as M, type SymbolMatch as N, type OutlineNode as O, type PassthroughCandidate as P, type SymbolLocation as Q, type RefResult as R, ScipDatabase as S, type TraceResult as T, type UnusedImportResult as U, type IndexedDefinition as V, type WrapperCandidate as W, type ScipSymbol as X, type ScipLocalSymbol as Y, type SupportedLanguage as Z, type IndexerConfig as _, type ByKindResult as a, type WatcherStatus as a0, type ChangeSurfaceEntry as a1, type DeadSymbolResult as a2, type DescriptorSuffix as a3, type DocumentPathCandidate as a4, type DriftResult as a5, type EntryRootsConfig as a6, type HealthAction as a7, type IndexerOverrides as a8, type InstallMethod as a9, type ParsedReExport as aa, type ParsedSourceExport as ab, type ParsedSourceImport as ac, type ReferenceSite as ad, type ScipDescriptor as ae, type ScipQueryConfig as af, type SemanticConfig as ag, type TypeScriptSemanticConfig as ah, type WatchConfig as ai, createGitignoreFilter as aj, 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 DriftSummary as n, type FileResult as o, type HierarchyNode as p, type HotspotResult as q, type IsolatedResult as r, type MethodResult as s, type StatsResult as t, type SymbolResult as u, type SystemResult as v, type SurfaceResult as w, type SimilarSymbolResult as x, type SimilarFileResult as y, type SimilarChainResult as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { N as ScipSymbol, Q as ScipLocalSymbol, V as SupportedLanguage, X as IndexerConfig, Y as ProjectConfig, Z as WatcherStatus } from './db-DKhNQ75l.js';
-export { A as AffectedResult, B as BottleneckResult, a as ByKindResult, C as CallGraphResult, _ as ChangeSurfaceEntry, b as ChangeSurfaceResult, c as CodeResult, d as ComplexityHotspot, e as ComplexityResult, f as ConvergenceResult, g as CouplingResult, h as CycleResult, D as DataflowResult, i as DeadOptions, j as DeadSummary, $ as DeadSymbolResult, k as DeepChainResult, l as DepResult, a0 as DescriptorSuffix, m as DiffImpactResult, a1 as DocumentPathCandidate, a2 as DriftResult, n as DriftSummary, a3 as EntryRootsConfig, E as ExtractCandidate, F as FanResult, o as FileResult, a4 as HealthAction, H as HealthReport, p as HierarchyNode, q as HotspotResult, I as ImportResult, a5 as IndexedDefinition, a6 as IndexerOverrides, a7 as InstallMethod, r as IsolatedResult, M as MemberResult, s as MethodResult, O as OutlineNode, a8 as ParsedReExport, a9 as ParsedSourceExport, aa as ParsedSourceImport, P as PassthroughCandidate, R as RedundantReexport, v as RefResult, ab as ReferenceSite, S as ScipDatabase, ac as ScipDescriptor, ad as ScipQueryConfig, G as SimilarChainResult, z as SimilarFileResult, L as SimilarSignatureGroup, y as SimilarSymbolResult, K as SliceResult, J as StaleAbstraction, t as StatsResult, x as SurfaceResult, ae as SymbolLocation, af as SymbolMatch, u as SymbolResult, w as SystemResult, T as TraceResult, U as UnusedImportResult, ag as WatchConfig, W as WrapperCandidate, ah as createGitignoreFilter } from './db-DKhNQ75l.js';
+import { S as ScipDatabase, N as SymbolMatch, Q as SymbolLocation, V as IndexedDefinition, X as ScipSymbol, Y as ScipLocalSymbol, Z as SupportedLanguage, _ as IndexerConfig, $ as ProjectConfig, a0 as WatcherStatus } from './db-BZPa7dzJ.js';
+export { A as AffectedResult, B as BottleneckResult, a as ByKindResult, C as CallGraphResult, a1 as ChangeSurfaceEntry, b as ChangeSurfaceResult, c as CodeResult, d as ComplexityHotspot, e as ComplexityResult, f as ConvergenceResult, g as CouplingResult, h as CycleResult, D as DataflowResult, i as DeadOptions, j as DeadSummary, a2 as DeadSymbolResult, k as DeepChainResult, l as DepResult, a3 as DescriptorSuffix, m as DiffImpactResult, a4 as DocumentPathCandidate, a5 as DriftResult, n as DriftSummary, a6 as EntryRootsConfig, E as ExtractCandidate, F as FanResult, o as FileResult, a7 as HealthAction, H as HealthReport, p as HierarchyNode, q as HotspotResult, I as ImportResult, a8 as IndexerOverrides, a9 as InstallMethod, r as IsolatedResult, M as MemberResult, s as MethodResult, O as OutlineNode, aa as ParsedReExport, ab as ParsedSourceExport, ac as ParsedSourceImport, P as PassthroughCandidate, K as RedundantReexport, R as RefResult, ad as ReferenceSite, ae as ScipDescriptor, af as ScipQueryConfig, ag as SemanticConfig, z as SimilarChainResult, y as SimilarFileResult, L as SimilarSignatureGroup, x as SimilarSymbolResult, J as SliceResult, G as StaleAbstraction, t as StatsResult, w as SurfaceResult, u as SymbolResult, v as SystemResult, T as TraceResult, ah as TypeScriptSemanticConfig, U as UnusedImportResult, ai as WatchConfig, W as WrapperCandidate, aj as createGitignoreFilter } from './db-BZPa7dzJ.js';
 export { stats } from './queries/stats.js';
 export { files } from './queries/files.js';
 export { symbols } from './queries/symbols.js';
@@ -46,6 +46,216 @@ export { similarSignatures } from './queries/similar-signatures.js';
 import { Index } from '@c4312/scip';
 import 'better-sqlite3';
 
+/**
+ * File classifier — one place to decide what role a source file plays.
+ *
+ * Multiple queries (dead, health, cycles, drift) all need to ask
+ * questions like "is this a test file?", "is this an entry point?",
+ * "is this a barrel?" Pre-this-module each query had its own answer
+ * with subtle divergences. classifyFile gives every query one
+ * consistent verdict.
+ *
+ * `FileKind` is closed — when a future contributor adds a kind they
+ * edit the type, and the compiler forces every consumer's switch to
+ * handle it.
+ */
+
+type FileKind = 'entry' | 'barrel' | 'worker' | 'test' | 'source';
+/**
+ * Classify a file by role. Pure pattern matching — doesn't need a DB.
+ * For "is this barrel reachable?" use `isLiveBarrel(db, file)` instead.
+ */
+declare function classifyFile(file: string): FileKind;
+
+/**
+ * reference-graph — bulk caller/callee maps and reference-site
+ * resolution.
+ *
+ * Where to get what:
+ *   Reference lines (where is this used?):
+ *     - Primary:    `getSourceReferenceSites` — cross-file identifier
+ *                   scan (re-exported from identifier-attribution).
+ *                   Returns [] when the leaf name is ambiguous.
+ *     - Fallback:   `getResolvedReferenceSites` — mention-resolved
+ *                   chunks with in-chunk line refinement. Always
+ *                   returns a result when the symbol has mentions.
+ *   Do NOT read `chunks.start_line` as the "line of a reference"; a
+ *   chunk spans many source lines.
+ *
+ *   Bulk graph builders:
+ *     - `buildCalleeMap(db, defs)` — for each definition, the symbols
+ *       it calls (AST + chunk merged).
+ *     - `buildCrossFileCallerMap(db, defs?)` — reverse: symbolId →
+ *       set of files that reference it.
+ *     - `buildCallerRowsMap(db)` — symbolId → list of caller
+ *       (symbol, file) rows, cached once per DB.
+ *     - `getCalleeRowsForSymbol` / `getCallerRowsForSymbol` — narrow
+ *       single-symbol views over the bulk maps.
+ *
+ *   File-dependency graph:
+ *     - `buildFileDepGraph(db, scope?)` — file → set of files it
+ *       imports/references.
+ *
+ * Layer position: top of the layering — uses path-resolver,
+ * symbol-lookup, and definition-catalog. Identifier-attribution sits
+ * alongside (re-exported here as `getSourceReferenceSites` /
+ * `buildSourceFallbackCallerFiles` so callers don't have to learn a
+ * second module name).
+ */
+
+declare function buildFileDepGraph(db: ScipDatabase, scope?: string): Map<string, Set<string>>;
+/**
+ * Bulk callee map: for each definition in the list, find every symbol it
+ * actually calls.
+ *
+ * For files with tree-sitter support (Rust, TS/JS, Python), we use AST
+ * call_expression / new_expression nodes — every callsite is exact, every
+ * attribution is to the precise enclosing function.
+ *
+ * For files without AST support (Java, JVM, Ruby, .NET, Dart, PHP, C/C++),
+ * we fall back to chunk-level SCIP mentions.
+ *
+ * `opts.additive`:
+ *   - false (default, "call-strict"): AST is the ground truth for AST files;
+ *     chunk attribution is NOT unioned in. Use for callee fingerprints,
+ *     extract/passthrough analysis, callGraph — anywhere you need exact
+ *     "what does this function call" without false positives from chunk
+ *     attribution placing a mention in the wrong enclosing function.
+ *   - true ("union with chunks"): merges both paths. Use for liveness
+ *     checks (isolated, "has any callee at all") where ambiguous-leaf
+ *     callees that AST resolution skips would otherwise produce false
+ *     positives.
+ */
+declare function buildCalleeMap(db: ScipDatabase, definitions: ReadonlyArray<SymbolMatch>, opts?: {
+    additive?: boolean;
+}): Map<number, Array<{
+    symbol: string;
+    file: string;
+    chunkId: number;
+}>>;
+/**
+ * Bulk caller map: symbolId → set of distinct files that reference the
+ * symbol.
+ *
+ * For files with tree-sitter support, callers come from AST call_expression
+ * nodes — each callsite resolves to a real symbol via the global leaf index
+ * with same-file preference. For non-AST files, callers come from SCIP's
+ * mentions table (chunk-level) with self-reference filtering.
+ *
+ * If `definitions` is supplied, references that fall inside the symbol's own
+ * defining file are treated as potential self-references and only counted
+ * when they originate from a different document.
+ */
+declare function buildCrossFileCallerMap(db: ScipDatabase, definitions?: ReadonlyArray<SymbolLocation>): Map<number, Set<string>>;
+
+/**
+ * Identifier-attribution module — one owner of "given a textual identifier
+ * hit in file F, which SCIP symbol(s) does it refer to?"
+ *
+ * Pre-this-module the same logic lived in four places (sourceCandidateLines,
+ * importAttributedCandidateLines, buildSourceFallbackCallerFiles inner loop,
+ * dead.ts:resolveLeaf) with subtle drift. Bug fixes in one site silently
+ * coexisted with the bug in the others. The Vue support and interface-
+ * dispatch fixes from earlier had to touch all four sites separately.
+ *
+ * The forward call (`attributeIdentifier`) is the core. The inverse views
+ * (`findReferences`, `findCallerFiles`) build on it.
+ *
+ * The disambiguation policy — same-file > direct import > interface-dispatch
+ * (all candidates in same imported file) > empty — is owned here. Callers
+ * receive the answer, not raw candidates.
+ */
+
+interface SymbolRef {
+    symbolId: number;
+    symbol: string;
+    /** Defining file of the symbol. */
+    relativePath: string;
+}
+/**
+ * What symbol(s) does identifier `name` in file `file` refer to?
+ *
+ * Returns the symbols this textual hit reasonably resolves to. May
+ * return >1 entry when an interface and one or more impls all live
+ * in the same imported file (runtime dispatch could land on any).
+ * Returns [] when the leaf is ambiguous and no disambiguation
+ * signal applies.
+ */
+declare function attributeIdentifier(db: ScipDatabase, file: string, identifier: string): SymbolRef[];
+/**
+ * For each symbol in `candidates`, which files reference it?
+ *
+ * Bulk variant of `findReferences` — one file walk credits every
+ * candidate-leaf hit in the file at once, instead of N walks per
+ * candidate. Used by the dead-code source-fallback path.
+ */
+declare function findCallerFiles(db: ScipDatabase, candidates: ReadonlyArray<IndexedDefinition>): Map<number, Set<string>>;
+
+interface CallableSignature {
+    paramCount: number;
+}
+/**
+ * Pull a function's parameter count from the AST. Used by similar-pair
+ * filtering to avoid declaring a 1-arg helper similar to a 7-arg orchestrator
+ * just because they happen to share infrastructure callees.
+ *
+ * On first call per file, walks the entire AST once and indexes every
+ * callable's signature by (startLine, endLine). Subsequent calls are O(1)
+ * Map lookups — critical when called for thousands of candidates.
+ */
+declare function getCallableSignature(db: ScipDatabase, relativePath: string, startLine: number, endLine: number): CallableSignature | null;
+
+type SourceReferenceKind = 'identifier' | 'cross-language-dispatch' | 'rust-attribute';
+type SourceReferenceTarget = ReturnType<typeof attributeIdentifier>[number];
+interface SourceReferenceHit {
+    sourceFile: string;
+    name: string;
+    target: SourceReferenceTarget;
+    occurrences: number;
+    kind: SourceReferenceKind;
+}
+interface ScanSourceReferencesOptions {
+    paths: Iterable<string>;
+    includeVueSfc?: boolean;
+    includeCrossLanguageDispatchNames?: boolean;
+    includeRustAttributeNames?: boolean;
+    identifierResolution?: 'strict' | 'permissive';
+    skipPath?: (relativePath: string) => boolean;
+}
+declare function scanSourceReferences(db: ScipDatabase, opts: ScanSourceReferencesOptions, visit: (hit: SourceReferenceHit) => void): void;
+
+interface ProductionCallableDefinitionsOptions {
+    scope?: string;
+    minLoc?: number;
+    maxLoc?: number;
+    excludeSymbol?: string;
+    excludeEntrySurfaces?: boolean;
+    excludeTypesFiles?: boolean;
+    excludeRustTraitImplMembers?: boolean;
+    includeSuppressed?: boolean;
+    requireFunctionLikeSymbol?: boolean;
+    requireCallableSymbol?: boolean;
+    sortByLocDesc?: boolean;
+}
+declare class ProjectIndex {
+    private readonly db;
+    constructor(db: ScipDatabase);
+    scopedDefinitions(scope?: string): IndexedDefinition[];
+    definitionsForFile(relativePath: string): IndexedDefinition[];
+    productionCallableDefinitions(opts?: ProductionCallableDefinitionsOptions): IndexedDefinition[];
+    calleeMap(definitions: ReadonlyArray<SymbolMatch>, opts?: {
+        additive?: boolean;
+    }): ReturnType<typeof buildCalleeMap>;
+    crossFileCallerMap(definitions?: ReadonlyArray<SymbolMatch>): ReturnType<typeof buildCrossFileCallerMap>;
+    sourceFallbackCallerFiles(definitions: ReadonlyArray<IndexedDefinition>): ReturnType<typeof findCallerFiles>;
+    fileDependencyGraph(scope?: string): ReturnType<typeof buildFileDepGraph>;
+    fileKind(relativePath: string): ReturnType<typeof classifyFile>;
+    hasSuppressionComment(definition: Pick<IndexedDefinition, 'relativePath' | 'startLine'>): boolean;
+    sourceFiles(): string[];
+    scanSourceReferences(opts: Parameters<typeof scanSourceReferences>[1], visit: Parameters<typeof scanSourceReferences>[2]): void;
+    callableSignature(definition: Pick<IndexedDefinition, 'relativePath' | 'startLine' | 'endLine'>): ReturnType<typeof getCallableSignature>;
+}
+
 /**
  * Parse a SCIP symbol string into its structured components.
  * Works for any SCIP-indexed language (TypeScript, Java, Rust, Python, etc.)
@@ -188,6 +398,12 @@ interface ReindexOptions {
     pnpmWorkspaces?: boolean;
     /** Skip auto-install prompts */
     skipAutoInstall?: boolean;
+    /** Reuse an existing index when tracked source inputs are unchanged (default true). */
+    skipIfUnchanged?: boolean;
+    /** Permit a partial index when some detected/requested languages fail (default false). */
+    allowPartial?: boolean;
+    /** Number of language indexers to run at once (default: conservative auto). */
+    indexerConcurrency?: number;
 }
 interface ReindexResult {
     /** Languages that were successfully indexed. */
@@ -195,6 +411,8 @@ interface ReindexResult {
     indexPath: string;
     dbPath: string;
     durationMs: number;
+    /** True when existing SCIP/SQLite outputs were reused because inputs were unchanged. */
+    reused: boolean;
     /**
      * Languages detected in the project but skipped because their indexer
      * could not be located, installed, or run. Each entry includes the reason.
@@ -215,16 +433,6 @@ declare function reindex(opts: ReindexOptions): Promise<ReindexResult>;
  * Returns defaults for anything not specified.
  */
 declare function loadProjectConfig(projectRoot: string): ProjectConfig;
-/**
- * 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.
- */
-declare function resolveCacheDir(projectRoot: string, config?: ProjectConfig): string;
 /**
  * Resolve all paths for a project's index files.
  */
@@ -307,4 +515,4 @@ declare function installSkills(opts?: {
     quiet?: boolean;
 }): InstallSkillsResult;
 
-export { INDEXER_CONFIGS, IndexerConfig, ProjectConfig, ScipLocalSymbol, ScipSymbol, SupportedLanguage, Watcher, WatcherStatus, augmentAuxiliaryDocuments, augmentVueResolvedReferences, detectLanguages, getIndexerConfig, getScipVersion, initProjectConfig, installSkills, isBinaryAvailable, isIndexerInstalled, isScipInstalled, leafName, loadProjectConfig, mergeScipFiles, mergeScipIndexes, parseSymbol, printScipInstallInstructions, reindex, resolveCacheDir, resolveIndexPaths, shortenSymbol, tryInstallIndexer, tryInstallScipCli };
+export { INDEXER_CONFIGS, IndexedDefinition, IndexerConfig, ProjectConfig, ProjectIndex, ScipDatabase, ScipLocalSymbol, ScipSymbol, SupportedLanguage, SymbolLocation, SymbolMatch, Watcher, WatcherStatus, augmentAuxiliaryDocuments, augmentVueResolvedReferences, detectLanguages, getIndexerConfig, getScipVersion, initProjectConfig, installSkills, isBinaryAvailable, isIndexerInstalled, isScipInstalled, leafName, loadProjectConfig, mergeScipFiles, mergeScipIndexes, parseSymbol, printScipInstallInstructions, reindex, resolveIndexPaths, shortenSymbol, tryInstallIndexer, tryInstallScipCli };