scip-query 0.6.9 → 0.7.1

package/dist/index.d.ts

@@ -1,51 +1,73 @@
-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-Rx8Ho_JF.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-Rx8Ho_JF.js';
-export { stats } from './queries/stats.js';
-export { files } from './queries/files.js';
-export { symbols } from './queries/symbols.js';
-export { methods } from './queries/methods.js';
-export { refs } from './queries/refs.js';
-export { trace } from './queries/trace.js';
-export { deps, rdeps } from './queries/deps.js';
-export { system } from './queries/system.js';
-export { surface } from './queries/surface.js';
-export { dead } from './queries/dead.js';
-export { hotspots } from './queries/hotspots.js';
-export { importedBy, imports, unusedImports } from './queries/imports.js';
-export { outline } from './queries/outline.js';
-export { members } from './queries/members.js';
-export { fanIn, fanOut, topFanIn, topFanOut } from './queries/fan.js';
-export { coupling, topCoupling } from './queries/coupling.js';
-export { cycles } from './queries/cycles.js';
-export { bottlenecks } from './queries/bottlenecks.js';
-export { isolated } from './queries/isolated.js';
-export { byKind, kindCounts } from './queries/by-kind.js';
-export { deepChains } from './queries/deep-chains.js';
-export { hierarchy } from './queries/hierarchy.js';
-export { callGraph } from './queries/call-graph.js';
-export { similar, similarAll } from './queries/similar.js';
-export { similarFiles } from './queries/similar-files.js';
-export { similarChains } from './queries/similar-chains.js';
-export { extractCandidates } from './queries/extract-candidates.js';
-export { affected } from './queries/affected.js';
-export { changeSurface } from './queries/change-surface.js';
-export { diffImpact, diffImpactPartial, diffImpactPlan, mergeDiffImpactPartials } from './queries/diff-impact.js';
-export { drift } from './queries/drift.js';
-export { wrapperCandidates } from './queries/wrapper-candidates.js';
-export { passthroughCandidates } from './queries/passthrough-candidates.js';
-export { staleAbstractions } from './queries/stale-abstractions.js';
-export { complexityHotspots } from './queries/complexity-hotspots.js';
-export { HEALTH_PHASES, health, healthPhase, healthReportFromPhases } from './queries/health.js';
-export { convergence } from './queries/convergence.js';
-export { code } from './queries/code.js';
-export { complexity } from './queries/complexity.js';
-export { dataflow } from './queries/dataflow.js';
-export { slice } from './queries/slice.js';
-export { redundantReexports } from './queries/redundant-reexports.js';
-export { similarSignatures } from './queries/similar-signatures.js';
-import { Index } from '@c4312/scip';
+import { S as ScipDatabase } from './db-DdTPetj5.js';
+export { c as createGitignoreFilter } from './db-DdTPetj5.js';
+export { S as ScipQueryConfig } from './config-types-CGIeLEpY.js';
 import 'better-sqlite3';
 
+/**
+ * A symbol's location in the SCIP index. The minimum data needed to
+ * identify a definition: which document it lives in, which lines it
+ * spans, and the global symbol id. Used as a lightweight handle when
+ * the caller doesn't need the symbol's textual name or path.
+ */
+interface SymbolLocation {
+    documentId: number;
+    startLine: number;
+    endLine: number;
+    symbolId: number;
+}
+/**
+ * A SymbolLocation plus the human-readable bits: the SCIP symbol string
+ * and the document's relative path. Returned by lookup helpers like
+ * `findFirstSymbolMatch` so callers don't have to round-trip through the
+ * documents table to get a path or symbol name.
+ */
+interface SymbolMatch extends SymbolLocation {
+    symbol: string;
+    relativePath: string;
+}
+/**
+ * A full definition record: SymbolMatch plus per-symbol metadata
+ * (leaf name, parent type, kind, documentation, enclosing symbol).
+ * Used by the catalog APIs (`getDefinitionsForFile`, `getAllDefinitions`,
+ * `getScopedDefinitions`) so consumers don't have to re-derive any of
+ * these per-record.
+ */
+interface IndexedDefinition extends SymbolMatch {
+    leaf: string;
+    parentTypeName: string | null;
+    isFunctionLike: boolean;
+    isTypeLike: boolean;
+    kind: number | null;
+    documentation: string | null;
+    enclosingSymbol: string | null;
+}
+/** 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;
+}
+
 /**
  * File classifier — one place to decide what role a source file plays.
  *
@@ -67,48 +89,13 @@ type FileKind = 'entry' | 'barrel' | 'worker' | 'test' | 'source';
  */
 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).
- */
-
+type CalleeEvidenceSource = 'ast-callsite' | 'semantic-callee' | 'scip-chunk';
 interface CalleeRow {
     symbol: string;
     file: string;
     chunkId: number;
+    source: CalleeEvidenceSource;
 }
-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.
@@ -135,19 +122,9 @@ declare function buildCalleeMap(db: ScipDatabase, definitions: ReadonlyArray<Sym
     additive?: boolean;
     semantic?: boolean;
 }): Map<number, CalleeRow[]>;
-/**
- * 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 buildFileDepGraph(db: ScipDatabase, scope?: string): Map<string, Set<string>>;
+
 declare function buildCrossFileCallerMap(db: ScipDatabase, definitions?: ReadonlyArray<SymbolLocation>, opts?: {
     semantic?: boolean;
 }): Map<number, Set<string>>;
@@ -157,7 +134,7 @@ declare function buildCrossFileCallerMap(db: ScipDatabase, definitions?: Readonl
  * 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,
+ * importAttributedCandidateLines, findCallerFiles 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.
@@ -206,11 +183,18 @@ interface CallableSignature {
  * 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.
+ *
+ * scip-query: ignore-wrapper — public AST-signature primitive used through
+ * ProjectIndex; callers should not know the per-tree signature cache shape.
  */
 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];
+type DefaultSourceReferenceTarget = ReturnType<typeof attributeIdentifier>[number];
+interface SourceReferenceTarget {
+    symbolId: number;
+    relativePath: string;
+}
 interface SourceReferenceHit {
     sourceFile: string;
     name: string;
@@ -226,6 +210,14 @@ interface ScanSourceReferencesOptions {
     identifierResolution?: 'strict' | 'permissive';
     candidateNames?: ReadonlySet<string>;
     skipPath?: (relativePath: string) => boolean;
+    resolveTargets?: (ctx: SourceReferenceResolveContext) => Iterable<SourceReferenceTarget>;
+    afterPath?: (relativePath: string) => void;
+}
+interface SourceReferenceResolveContext {
+    sourceFile: string;
+    name: string;
+    kind: SourceReferenceKind;
+    defaultTargets: () => readonly DefaultSourceReferenceTarget[];
 }
 declare function scanSourceReferences(db: ScipDatabase, opts: ScanSourceReferencesOptions, visit: (hit: SourceReferenceHit) => void): void;
 
@@ -256,6 +248,15 @@ declare class ProjectIndex {
         semantic?: boolean;
     }): ReturnType<typeof buildCrossFileCallerMap>;
     sourceFallbackCallerFiles(definitions: ReadonlyArray<IndexedDefinition>): ReturnType<typeof findCallerFiles>;
+    callerFileMap(definitions: ReadonlyArray<IndexedDefinition>, opts?: {
+        semantic?: boolean;
+        sourceFallback?: boolean;
+    }): Map<number, Set<string>>;
+    frameworkReferencedSymbolIds(definitions: ReadonlyArray<IndexedDefinition>): Set<number>;
+    symbolsWithNonSelfCallees(definitions: ReadonlyArray<IndexedDefinition>, opts?: {
+        additive?: boolean;
+        semantic?: boolean;
+    }): Set<number>;
     fileDependencyGraph(scope?: string): ReturnType<typeof buildFileDepGraph>;
     fileKind(relativePath: string): ReturnType<typeof classifyFile>;
     hasSuppressionComment(definition: Pick<IndexedDefinition, 'relativePath' | 'startLine'>): boolean;
@@ -290,239 +291,4 @@ declare function shortenSymbol(raw: string): string;
  */
 declare function leafName(raw: string): string;
 
-/**
- * Detect which languages are present in a project directory by checking for
- * marker files, root-level project files, and source-file extensions.
- */
-declare function detectLanguages(projectRoot: string): SupportedLanguage[];
-
-interface AugmentAuxiliaryDocumentsOptions {
-    projectRoot: string;
-    dbPath: string;
-    extensions?: readonly string[];
-    onStatus?: (message: string) => void;
-}
-interface AugmentAuxiliaryDocumentsResult {
-    scanned: number;
-    inserted: number;
-    existing: number;
-}
-/**
- * Add source files that upstream SCIP indexers skipped to the SQLite
- * documents table. Vue SFCs are the motivating case: scip-typescript can
- * resolve imports to generated TS, but it does not emit `.vue` documents.
- */
-declare function augmentAuxiliaryDocuments(opts: AugmentAuxiliaryDocumentsOptions): AugmentAuxiliaryDocumentsResult;
-
-interface AugmentVueResolvedOptions {
-    projectRoot: string;
-    dbPath: string;
-    tsconfig: string;
-    onStatus?: (message: string) => void;
-}
-interface AugmentVueResolvedResult {
-    vueFiles: number;
-    resolvedReferences: number;
-    insertedMentions: number;
-    skippedReferences: number;
-    syntheticSymbols: number;
-}
-declare function augmentVueResolvedReferences(opts: AugmentVueResolvedOptions): AugmentVueResolvedResult;
-
-/**
- * Indexer configurations for each supported language.
- * Each entry describes how to produce a SCIP index for that language.
- *
- * The `scip` CLI binary is required for all languages (to convert protobuf -> SQLite).
- * Each language also needs its own SCIP indexer installed.
- */
-declare const INDEXER_CONFIGS: Record<SupportedLanguage, IndexerConfig>;
-/** Get the indexer config for a language */
-declare function getIndexerConfig(language: SupportedLanguage): IndexerConfig;
-
-interface MergeScipResult {
-    documentCount: number;
-    externalSymbolCount: number;
-    inputCount: number;
-}
-/**
- * Merge multiple SCIP indices into a single index message.
- *
- * A SCIP index is a code graph snapshot: metadata about one indexed project plus
- * the documents and external symbols discovered by one or more indexers. Merging
- * means producing one unified snapshot so later conversion to SQLite sees the
- * whole repo instead of whichever language indexed last.
- */
-declare function mergeScipIndexes(indexes: readonly Index[]): Index;
-declare function mergeScipFiles(inputPaths: readonly string[], outputPath: string): MergeScipResult;
-
-/**
- * Check if a binary is available on PATH.
- */
-declare function isBinaryAvailable(name: string): boolean;
-/**
- * Check if an indexer's binary is available on PATH.
- */
-declare function isIndexerInstalled(config: IndexerConfig): boolean;
-/**
- * Attempt to auto-install an indexer using its configured install methods.
- * Tries each method in order, checking prerequisites first.
- * Returns true if installation succeeded.
- */
-declare function tryInstallIndexer(config: IndexerConfig, onStatus: (msg: string) => void): boolean;
-
-/**
- * Check if the `scip` CLI binary is available on PATH.
- */
-declare function isScipInstalled(): boolean;
-/**
- * Get the scip CLI version if installed.
- */
-declare function getScipVersion(): string | null;
-/**
- * Print instructions for installing the scip CLI binary.
- */
-declare function printScipInstallInstructions(): void;
-/**
- * Attempt to auto-install the `scip` CLI binary.
- * Tries brew (macOS), then go install, then prints manual instructions.
- * Returns true if installation succeeded.
- */
-declare function tryInstallScipCli(onStatus: (msg: string) => void): boolean;
-
-interface ReindexOptions {
-    projectRoot: string;
-    /** Override language detection — index only these languages */
-    languages?: SupportedLanguage[];
-    /** Path for the SCIP protobuf output (default: <projectRoot>/index.scip) */
-    outputScip?: string;
-    /** Path for the SQLite output (default: <projectRoot>/index.db) */
-    outputDb?: string;
-    /** Max Node.js heap size in MB (default: 8192) */
-    maxHeapMb?: number;
-    /** Callback for status updates */
-    onStatus?: (message: string) => void;
-    /** Extra flags for pnpm-workspace-aware TS indexing */
-    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. */
-    languages: SupportedLanguage[];
-    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.
-     */
-    skipped: {
-        language: SupportedLanguage;
-        reason: string;
-    }[];
-}
-/**
- * Reindex a project: detect languages, run the appropriate SCIP indexer(s),
- * and convert the output to SQLite.
- */
-declare function reindex(opts: ReindexOptions): Promise<ReindexResult>;
-
-/**
- * Load project config from .scipquery.json in the project root.
- * Returns defaults for anything not specified.
- */
-declare function loadProjectConfig(projectRoot: string): ProjectConfig;
-/**
- * Resolve all paths for a project's index files.
- */
-declare function resolveIndexPaths(projectRoot: string, config?: ProjectConfig): {
-    cacheDir: string;
-    dbPath: string;
-    indexPath: string;
-    metaPath: string;
-};
-/**
- * Scaffold a default .scipquery.json in the project root.
- * Does not overwrite an existing config.
- */
-declare function initProjectConfig(projectRoot: string, languages: string[]): string;
-
-interface WatcherOptions {
-    projectRoot: string;
-    config: ProjectConfig;
-    languages?: SupportedLanguage[];
-    onStatus?: (status: WatcherStatus) => void;
-    onReindexComplete?: (durationMs: number) => void;
-    onError?: (error: Error) => void;
-}
-/**
- * File watcher that triggers single-flight background reindexing.
- *
- * Design:
- *  - Debounce: waits 30s (configurable) after the last file change
- *  - Single-flight: only one reindex runs at a time, never queued
- *  - Dirty flag: changes during reindex schedule ONE follow-up
- *  - Cooldown: minimum interval between reindex completions
- *  - Atomic swap: writes to index.db.tmp, renames on success
- */
-declare class Watcher {
-    private projectRoot;
-    private watchConfig;
-    private indexPaths;
-    private languages?;
-    private pnpmWorkspaces;
-    private onStatus;
-    private onReindexComplete;
-    private onError;
-    private status;
-    private debounceTimer;
-    private cooldownTimer;
-    private dirty;
-    private changedFiles;
-    private reindexInFlight;
-    private lastReindexEnd;
-    private fsWatchers;
-    private gitignoreFilter;
-    private extraIgnore;
-    private stopped;
-    constructor(opts: WatcherOptions);
-    /** Start watching for file changes */
-    start(): void;
-    /** Stop watching and clean up */
-    stop(): void;
-    private handleFileChange;
-    private triggerReindex;
-    /**
-     * Run the reindex in a forked child process.
-     * Writes to index.db.tmp, then atomically renames to index.db.
-     */
-    private runReindex;
-    private setStatus;
-    private clearDebounceTimer;
-    private clearCooldownTimer;
-}
-
-interface InstallSkillsResult {
-    installed: string[];
-    skipped: string[];
-    alreadyLinked: string[];
-}
-/**
- * Install scip-query skills into both Claude Code (~/.claude/skills/)
- * and Codex (~/.codex/skills/). Uses symlinks (junctions on Windows)
- * so skills auto-update when the package updates.
- */
-declare function installSkills(opts?: {
-    quiet?: boolean;
-}): InstallSkillsResult;
-
-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 };
+export { ProjectIndex, ScipDatabase, leafName, parseSymbol, shortenSymbol };