scip-query 0.5.0 → 0.6.1

package/dist/{db-6F9R9e_t.d.ts → db-BSTtBG_H.d.ts}

@@ -16,6 +16,111 @@ interface PathFilter {
     filter: (paths: string[]) => string[];
 }
 
+/**
+ * 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;
+}
+/**
+ * Reference-site of a symbol — where (file + line) the symbol is used,
+ * and the smallest enclosing definition at that line (for credit
+ * attribution in reverse-index views).
+ */
+interface ReferenceSite {
+    file: string;
+    line: number;
+    enclosingSymbol: string | null;
+}
+/**
+ * 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;
+}
+/**
+ * Internal scoring shape used by `path-resolver` to rank document path
+ * candidates against a user-supplied file pattern. Not part of any
+ * public CLI interface.
+ */
+interface DocumentPathCandidate {
+    relativePath: string;
+    score: number;
+}
+/**
+ * A single import binding parsed out of a source file. Captures both the
+ * lexical shape (kind, names, source path) and a usage flag computed from
+ * the source's body — `used` is `true` when the imported binding's local
+ * name appears anywhere in the file outside the import statement itself.
+ *
+ * Producers: each per-language parser in `src/language-parsers/*.ts`.
+ * Consumers: import-graph queries (`imports`, `drift`, `redundant-reexports`),
+ * unused-imports queries, and the import-attribution path inside
+ * `identifier-attribution.ts`.
+ */
+interface ParsedSourceImport {
+    importedName: string;
+    localName: string | null;
+    sourcePath: string | null;
+    kind: 'named' | 'default' | 'namespace' | 'side-effect';
+    used: boolean;
+    usedMembers: string[];
+}
+/**
+ * A single export-from binding parsed out of a source file. Used by the
+ * languages that have an explicit re-export construct (Rust `pub use`,
+ * Dart `export`) to surface what a barrel module re-shapes.
+ */
+interface ParsedSourceExport {
+    sourcePath: string | null;
+    specifier: string;
+}
+/**
+ * A re-export statement in a JavaScript/TypeScript source file — one of:
+ *   export { X [as Y] } from './path'
+ *   export type { X } from './path'
+ *   export * from './path'
+ *   export * as Ns from './path'
+ *
+ * The `sourcePath` is the resolved, project-relative path to the re-exported
+ * module (same convention as ParsedSourceImport.sourcePath).
+ */
+interface ParsedReExport {
+    kind: 'named' | 'star' | 'star-as';
+    sourcePath: string | null;
+    /** For 'named': the list of re-exported identifiers as they appear in THIS file. */
+    names: string[];
+    /** Start line in the source (0-indexed) — inclusive. */
+    startLine: number;
+    /** End line in the source (0-indexed) — inclusive. */
+    endLine: number;
+}
 /** Parsed components of a SCIP symbol string */
 interface ScipSymbol {
     /** The indexer scheme (e.g. "scip-typescript", "scip-java", "rust-analyzer") */
@@ -161,6 +266,15 @@ interface CouplingResult {
 interface CycleResult {
     /** Files forming a cycle, in order */
     path: string[];
+    /**
+     * Classification of the cycle:
+     *   - 'real':            architectural cycle worth fixing
+     *   - 'module-hierarchy': barrel-file pattern (mod.rs / index.ts /
+     *                        __init__.py declaring children that re-import
+     *                        parent re-exports). Standard module structure,
+     *                        not actionable.
+     */
+    kind: 'real' | 'module-hierarchy';
 }
 interface BottleneckResult {
     symbol: string;
@@ -258,7 +372,31 @@ interface StaleAbstraction {
     startLine: number;
     endLine: number;
     loc: number;
+    /**
+     * Cross-file consumers NOT counting files that only re-export the symbol
+     * through a barrel (`export { X } from '...'`). Barrel files expand the
+     * public surface; they aren't real consumers.
+     */
     consumers: number;
+    /** Number of files whose only reference is a passthrough re-export. */
+    barrelConsumers: number;
+    /** What the definition is syntactically — detected from source at the definition line. */
+    kind: 'class' | 'interface' | 'type' | 'enum' | 'other';
+    /**
+     * Does the defining file itself reference the type outside its own declaration?
+     * `false` is the strongest stale signal — the type lives in a file that never
+     * uses it (misplaced types file), while another file is its only consumer.
+     */
+    definerUsesType: boolean;
+    /**
+     * Ranked confidence in the "stale" verdict:
+     *   'high'   — consumers === 0, OR consumers === 1 && !definerUsesType && kind !== 'class'.
+     *   'medium' — consumers <= 1 with one of the signals pointing weakly stale.
+     *   'low'    — consumers === 1 but kind === 'class' (likely encapsulation, not over-abstraction).
+     */
+    confidence: 'high' | 'medium' | 'low';
+    /** Short human-readable explanation of why this was flagged. */
+    reason: string;
 }
 interface ComplexityHotspot {
     symbol: string;
@@ -536,6 +674,13 @@ interface IndexerConfig {
     installMethods?: InstallMethod[];
     /** URL for manual installation if auto-install fails */
     installUrl?: string;
+    /**
+     * npm package bundled with scip-query as an optionalDependency. When this
+     * package resolves locally (i.e. it installed successfully), the indexer is
+     * considered available even if its binary isn't on PATH — `npx <binary>`
+     * will pick up the local install.
+     */
+    bundledNpmPackage?: string;
 }
 interface ScipQueryConfig {
     /** Path to the SQLite database (index.db) */
@@ -662,4 +807,4 @@ declare class ScipDatabase {
     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 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 ScipSymbol as N, type OutlineNode as O, type PassthroughCandidate as P, type ScipLocalSymbol as Q, type RefResult 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 DriftResult as a1, type HealthAction as a2, type IndexerOverrides as a3, type InstallMethod as a4, type ScipDescriptor as a5, type ScipQueryConfig as a6, type WatchConfig as a7, createGitignoreFilter as a8, 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 };
+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 HealthAction as a3, type IndexedDefinition as a4, type IndexerOverrides as a5, type InstallMethod as a6, type ParsedReExport as a7, type ParsedSourceExport as a8, type ParsedSourceImport as a9, type ReferenceSite as aa, type ScipDescriptor as ab, type ScipQueryConfig as ac, type SymbolLocation as ad, type SymbolMatch as ae, type WatchConfig as af, createGitignoreFilter as ag, 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 };

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-6F9R9e_t.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 DriftResult, n as DriftSummary, E as ExtractCandidate, F as FanResult, o as FileResult, a2 as HealthAction, H as HealthReport, p as HierarchyNode, q as HotspotResult, I as ImportResult, a3 as IndexerOverrides, a4 as InstallMethod, r as IsolatedResult, M as MemberResult, s as MethodResult, O as OutlineNode, P as PassthroughCandidate, K as RedundantReexport, R as RefResult, S as ScipDatabase, a5 as ScipDescriptor, a6 as ScipQueryConfig, 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, U as UnusedImportResult, a7 as WatchConfig, W as WrapperCandidate, a8 as createGitignoreFilter } from './db-6F9R9e_t.js';
+import { N as ScipSymbol, Q as ScipLocalSymbol, V as SupportedLanguage, X as IndexerConfig, Y as ProjectConfig, Z as WatcherStatus } from './db-BSTtBG_H.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, E as ExtractCandidate, F as FanResult, o as FileResult, a3 as HealthAction, H as HealthReport, p as HierarchyNode, q as HotspotResult, I as ImportResult, a4 as IndexedDefinition, a5 as IndexerOverrides, a6 as InstallMethod, r as IsolatedResult, M as MemberResult, s as MethodResult, O as OutlineNode, a7 as ParsedReExport, a8 as ParsedSourceExport, a9 as ParsedSourceImport, P as PassthroughCandidate, R as RedundantReexport, v as RefResult, aa as ReferenceSite, S as ScipDatabase, ab as ScipDescriptor, ac 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, ad as SymbolLocation, ae as SymbolMatch, u as SymbolResult, w as SystemResult, T as TraceResult, U as UnusedImportResult, af as WatchConfig, W as WrapperCandidate, ag as createGitignoreFilter } from './db-BSTtBG_H.js';
 export { stats } from './queries/stats.js';
 export { files } from './queries/files.js';
 export { symbols } from './queries/symbols.js';
@@ -157,10 +157,19 @@ interface ReindexOptions {
     skipAutoInstall?: boolean;
 }
 interface ReindexResult {
+    /** Languages that were successfully indexed. */
     languages: SupportedLanguage[];
     indexPath: string;
     dbPath: string;
     durationMs: number;
+    /**
+     * 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),