@jafreck/lore 0.3.5 → 0.3.6

package/dist/scip/enrichment.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @module indexer/scip/enrichment
+ *
+ * `ScipEnrichmentCoordinator` drives the SCIP enrichment workflow:
+ *
+ * 1. Run SCIP indexers (or read pre-computed index files) for each language.
+ * 2. Parse the resulting protobuf indexes into in-memory lookup structures.
+ * 3. For a batch of targets (file + position), resolve each to its
+ *    definition location and type signature using the SCIP data.
+ *
+ * Returns the same `ResolvedTypeMetadata` shape as the LSP enrichment
+ * coordinator, so the enrichment stage and resolution stage are agnostic
+ * to the enrichment source.
+ */
+import type { ResolvedTypeMetadata } from '../lsp/enrichment.js';
+import type { EffectiveScipSettings } from './config.js';
+export interface ScipEnrichmentTarget {
+    line: number;
+    character: number;
+}
+export interface ScipEnrichmentRequest {
+    filePath: string;
+    language: string;
+    source: string;
+    targets: readonly ScipEnrichmentTarget[];
+}
+export declare class ScipEnrichmentCoordinator {
+    private readonly settings;
+    private readonly rootDir;
+    private readonly resolvedIndexers;
+    /** Merged SCIP index data from all indexer runs. */
+    private indexData;
+    /** Languages for which SCIP indexing succeeded. */
+    private readonly enrichedLanguages;
+    constructor(settings: EffectiveScipSettings, rootDir: string);
+    /**
+     * Run SCIP indexers (or load pre-computed indexes) for the given languages.
+     * Must be called before `enrich()`.
+     *
+     * @returns Set of languages for which SCIP data is available.
+     */
+    start(languages: Iterable<string>): Promise<ReadonlySet<string>>;
+    /**
+     * Enrich a batch of targets with SCIP-derived metadata.
+     *
+     * Returns an array parallel to `request.targets` — each entry is either
+     * a `ResolvedTypeMetadata` or `null` (no SCIP data for that position).
+     */
+    enrich(request: ScipEnrichmentRequest): Array<ResolvedTypeMetadata | null>;
+    /** Set of languages for which SCIP enrichment data is available. */
+    get coveredLanguages(): ReadonlySet<string>;
+    dispose(): Promise<void>;
+    private readPrecomputedIndex;
+    private runIndexer;
+}
+//# sourceMappingURL=enrichment.d.ts.map

package/dist/scip/enrichment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrichment.d.ts","sourceRoot":"","sources":["../../src/scip/enrichment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAazD,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAC1C;AAID,qBAAa,yBAAyB;IASlC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAR3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6C;IAC9E,oDAAoD;IACpD,OAAO,CAAC,SAAS,CAA8B;IAC/C,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqB;gBAGpC,QAAQ,EAAE,qBAAqB,EAChD,OAAO,EAAE,MAAM;IAMjB;;;;;OAKG;IACG,KAAK,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAgFtE;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,qBAAqB,GAAG,KAAK,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA0C1E,oEAAoE;IACpE,IAAI,gBAAgB,IAAI,WAAW,CAAC,MAAM,CAAC,CAE1C;IAEK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAO9B,OAAO,CAAC,oBAAoB;YAiBd,UAAU;CA+DzB"}

package/dist/scip/enrichment.js

@@ -0,0 +1,258 @@
+/**
+ * @module indexer/scip/enrichment
+ *
+ * `ScipEnrichmentCoordinator` drives the SCIP enrichment workflow:
+ *
+ * 1. Run SCIP indexers (or read pre-computed index files) for each language.
+ * 2. Parse the resulting protobuf indexes into in-memory lookup structures.
+ * 3. For a batch of targets (file + position), resolve each to its
+ *    definition location and type signature using the SCIP data.
+ *
+ * Returns the same `ResolvedTypeMetadata` shape as the LSP enrichment
+ * coordinator, so the enrichment stage and resolution stage are agnostic
+ * to the enrichment source.
+ */
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { resolveScipIndexerRegistry, SCIP_SUPPORTED_LANGUAGES } from './registry.js';
+import { parseScipIndex, extractSignatureFromDocs, extractReturnType, } from './index-reader.js';
+import { getLogger } from '../logger.js';
+// ─── Coordinator ──────────────────────────────────────────────────────────────
+export class ScipEnrichmentCoordinator {
+    settings;
+    rootDir;
+    resolvedIndexers;
+    /** Merged SCIP index data from all indexer runs. */
+    indexData = null;
+    /** Languages for which SCIP indexing succeeded. */
+    enrichedLanguages = new Set();
+    constructor(settings, rootDir) {
+        this.settings = settings;
+        this.rootDir = rootDir;
+        this.resolvedIndexers = resolveScipIndexerRegistry(settings.indexers);
+    }
+    /**
+     * Run SCIP indexers (or load pre-computed indexes) for the given languages.
+     * Must be called before `enrich()`.
+     *
+     * @returns Set of languages for which SCIP data is available.
+     */
+    async start(languages) {
+        if (!this.settings.enabled)
+            return this.enrichedLanguages;
+        const log = getLogger();
+        const uniqueLanguages = new Set(languages);
+        // Determine which languages have SCIP coverage.
+        const toProcess = new Set();
+        for (const lang of uniqueLanguages) {
+            if (SCIP_SUPPORTED_LANGUAGES.has(lang)) {
+                const resolved = this.resolvedIndexers[lang];
+                if (resolved?.available || this.settings.indexDir) {
+                    toProcess.add(lang);
+                }
+            }
+        }
+        if (toProcess.size === 0) {
+            log.indexing('scip: no indexers available for requested languages');
+            return this.enrichedLanguages;
+        }
+        // Group languages by shared indexer command to avoid running the same
+        // indexer multiple times (e.g., scip-java for java + scala + kotlin).
+        const commandGroups = new Map();
+        for (const lang of toProcess) {
+            const resolved = this.resolvedIndexers[lang];
+            const key = resolved ? resolved.command : `indexDir:${lang}`;
+            if (!commandGroups.has(key))
+                commandGroups.set(key, new Set());
+            commandGroups.get(key).add(lang);
+        }
+        for (const [commandKey, langs] of commandGroups) {
+            const representativeLang = langs.values().next().value;
+            try {
+                let indexBuffer = null;
+                if (this.settings.indexDir) {
+                    // Read pre-computed index from the configured directory.
+                    indexBuffer = this.readPrecomputedIndex(representativeLang);
+                }
+                if (!indexBuffer) {
+                    // Run the SCIP indexer.
+                    indexBuffer = await this.runIndexer(representativeLang);
+                }
+                if (indexBuffer) {
+                    const parsed = parseScipIndex(indexBuffer, this.rootDir);
+                    // Merge documents and symbols into the combined index.
+                    for (const lang of langs) {
+                        this.enrichedLanguages.add(lang);
+                    }
+                    // Re-parse and merge (the parsed data is self-contained per ScipIndexData).
+                    // For a proper merge we need to transfer data. Since our parsing is
+                    // cheap, just re-assign if single or accumulate:
+                    if (this.indexData === null) {
+                        this.indexData = parsed;
+                    }
+                    else {
+                        // Merge by re-parsing into the existing index.
+                        // This is a design limitation — for now, multiple indexes are
+                        // handled by re-reading.  A future optimisation could merge the
+                        // ScipIndexData structures directly.
+                        this.indexData = mergeScipIndexDataPartial(this.indexData, parsed);
+                    }
+                    log.indexing(`scip: loaded index for ${[...langs].join(', ')}`, {
+                        files: parsed.fileCount,
+                        definitions: parsed.definitionCount,
+                    });
+                }
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                log.indexing(`scip: indexer failed for ${[...langs].join(', ')}: ${msg}`);
+            }
+        }
+        return this.enrichedLanguages;
+    }
+    /**
+     * Enrich a batch of targets with SCIP-derived metadata.
+     *
+     * Returns an array parallel to `request.targets` — each entry is either
+     * a `ResolvedTypeMetadata` or `null` (no SCIP data for that position).
+     */
+    enrich(request) {
+        const empty = request.targets.map(() => null);
+        if (!this.indexData || !this.enrichedLanguages.has(request.language)) {
+            return empty;
+        }
+        const results = [];
+        for (const target of request.targets) {
+            const occ = this.indexData.findOccurrence(request.filePath, target.line, target.character);
+            if (!occ || !occ.symbol) {
+                results.push(null);
+                continue;
+            }
+            // Resolve definition location.
+            const def = this.indexData.getDefinition(occ.symbol);
+            const info = this.indexData.getSymbolInfo(occ.symbol);
+            // Extract type signature.
+            const resolvedTypeSignature = info ? extractSignatureFromDocs(info) : null;
+            const resolvedReturnType = extractReturnType(resolvedTypeSignature);
+            if (!def && !resolvedTypeSignature) {
+                results.push(null);
+                continue;
+            }
+            const definitionUri = def ? pathToFileURL(def.filePath).toString() : null;
+            results.push({
+                resolvedTypeSignature,
+                resolvedReturnType,
+                definitionUri,
+                definitionPath: def?.filePath ?? null,
+                definitionLine: def?.line ?? null,
+                definitionCharacter: def?.character ?? null,
+            });
+        }
+        return results;
+    }
+    /** Set of languages for which SCIP enrichment data is available. */
+    get coveredLanguages() {
+        return this.enrichedLanguages;
+    }
+    async dispose() {
+        this.indexData = null;
+        this.enrichedLanguages.clear();
+    }
+    // ─── Private helpers ──────────────────────────────────────────────────────
+    readPrecomputedIndex(language) {
+        if (!this.settings.indexDir)
+            return null;
+        // Check for language-specific index or generic index.scip.
+        const candidates = [
+            join(this.rootDir, this.settings.indexDir, `${language}.scip`),
+            join(this.rootDir, this.settings.indexDir, 'index.scip'),
+        ];
+        for (const candidate of candidates) {
+            if (existsSync(candidate)) {
+                return readFileSync(candidate);
+            }
+        }
+        return null;
+    }
+    async runIndexer(language) {
+        const resolved = this.resolvedIndexers[language];
+        if (!resolved?.available)
+            return null;
+        const log = getLogger();
+        const outputPath = join(this.rootDir, `.lore-scip-${language}.scip`);
+        // Replace {output} placeholder in args.
+        const args = resolved.args.map((arg) => arg.replace(/\{output\}/gu, outputPath));
+        const cwd = resolved.cwd ? join(this.rootDir, resolved.cwd) : this.rootDir;
+        log.indexing(`scip: running ${resolved.command} for ${language}`);
+        try {
+            execFileSync(resolved.command, args, {
+                cwd,
+                timeout: this.settings.timeoutMs,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                encoding: 'utf8',
+            });
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            log.indexing(`scip: ${resolved.command} failed: ${msg}`);
+            // rust-analyzer scip writes to index.scip in cwd, not to {output}.
+            // Check if it wrote to the default location.
+            const defaultOutput = join(cwd, 'index.scip');
+            if (existsSync(defaultOutput) && defaultOutput !== outputPath) {
+                try {
+                    const data = readFileSync(defaultOutput);
+                    unlinkSync(defaultOutput);
+                    return data;
+                }
+                catch {
+                    // Fall through to return null.
+                }
+            }
+            return null;
+        }
+        // Read the output.
+        // Some indexers write to the specified path; others write to index.scip.
+        const candidatePaths = [outputPath, join(cwd, 'index.scip')];
+        for (const candidate of candidatePaths) {
+            if (existsSync(candidate)) {
+                try {
+                    const data = readFileSync(candidate);
+                    // Clean up temporary files.
+                    if (candidate.includes('.lore-scip-')) {
+                        try {
+                            unlinkSync(candidate);
+                        }
+                        catch { /* best effort */ }
+                    }
+                    return data;
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+        log.indexing(`scip: ${resolved.command} completed but no index file found`);
+        return null;
+    }
+}
+// ─── Merge helper ─────────────────────────────────────────────────────────────
+/**
+ * Partial merge of two ScipIndexData instances.
+ * In practice we re-parse the protobuf bytes, so this is a simple
+ * "use the second index" fallback.  A full merge would iterate the
+ * internal maps, but for the common case (one indexer per run) this
+ * is sufficient.
+ */
+function mergeScipIndexDataPartial(a, b) {
+    // For now, since ScipIndexData doesn't expose its internal maps for
+    // iteration, we rely on the coordinator loading indexes sequentially
+    // and always use the latest one.  A proper merge would require adding
+    // a `merge()` method to ScipIndexData.
+    //
+    // TODO: Implement proper merge across multiple SCIP indexes.
+    // For single-language projects (the common case), `b` is sufficient.
+    return b;
+}
+//# sourceMappingURL=enrichment.js.map

package/dist/scip/enrichment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrichment.js","sourceRoot":"","sources":["../../src/scip/enrichment.ts"],"names":[],"mappings":"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"}

package/dist/scip/index-reader.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @module indexer/scip/index-reader
+ *
+ * Parses a SCIP index (protobuf binary) into in-memory lookup structures
+ * that the enrichment coordinator can query by file + position.
+ *
+ * Uses the official SCIP protobuf schema (vendored `scip_pb.ts`) with
+ * `@bufbuild/protobuf` for decoding — no manual wire-format parsing.
+ *
+ * ## SCIP data model (relevant subset)
+ *
+ * - `Index.documents[]` — per-file occurrences and symbol definitions
+ * - `Index.external_symbols[]` — hover docs for symbols from other packages
+ * - `Occurrence.range` — `[startLine, startChar, endChar]` (3-elem) or
+ *   `[startLine, startChar, endLine, endChar]` (4-elem), 0-based
+ * - `Occurrence.symbol_roles` — bitset; bit 0 = Definition
+ * - `SymbolInformation.documentation` — markdown hover text
+ * - `SymbolInformation.signature_documentation` — structured signature
+ */
+import { type Document as ScipDocument, type SymbolInformation as ScipSymbolInformation } from './scip_pb.js';
+export interface ScipDefinitionLocation {
+    /** Absolute path to the file containing the definition. */
+    filePath: string;
+    /** 0-based line number. */
+    line: number;
+    /** 0-based character offset. */
+    character: number;
+}
+export interface ScipSymbolInfo {
+    symbol: string;
+    documentation: string[];
+    displayName: string;
+    signatureText: string | null;
+}
+export interface ScipOccurrenceRecord {
+    startLine: number;
+    startCharacter: number;
+    endLine: number;
+    endCharacter: number;
+    symbol: string;
+    isDefinition: boolean;
+}
+/**
+ * In-memory SCIP index optimised for enrichment lookups.
+ *
+ * Given a file path + position, returns the definition location and
+ * type signature for the symbol at that position.
+ */
+export declare class ScipIndexData {
+    private readonly projectRoot;
+    /** symbol → definition location */
+    private readonly definitions;
+    /** symbol → metadata (docs, display name, signature) */
+    private readonly symbolInfo;
+    /** absolute file path → sorted occurrences */
+    private readonly fileOccurrences;
+    /** Set of languages present in this index */
+    readonly languages: Set<string>;
+    constructor(projectRoot: string);
+    addDocument(doc: ScipDocument): void;
+    addExternalSymbol(sym: ScipSymbolInformation): void;
+    /**
+     * Look up the occurrence at (or nearest to) the given position in a file.
+     */
+    findOccurrence(filePath: string, line: number, character: number): ScipOccurrenceRecord | null;
+    /**
+     * Resolve a SCIP symbol string to its definition location.
+     */
+    getDefinition(symbol: string): ScipDefinitionLocation | null;
+    /**
+     * Get symbol metadata (documentation, signature).
+     */
+    getSymbolInfo(symbol: string): ScipSymbolInfo | null;
+    /** Number of indexed files. */
+    get fileCount(): number;
+    /** Number of unique symbols with known definition locations. */
+    get definitionCount(): number;
+}
+/**
+ * Parse a SCIP protobuf index from raw bytes.
+ *
+ * @param buffer       The raw protobuf bytes (e.g. `fs.readFileSync(path)`).
+ * @param projectRoot  Absolute path to the project root.  Document
+ *                     `relative_path` values are resolved against this.
+ * @returns Populated `ScipIndexData` ready for enrichment queries.
+ */
+export declare function parseScipIndex(buffer: Uint8Array, projectRoot: string): ScipIndexData;
+/**
+ * Extract a human-readable type signature from SCIP symbol documentation.
+ *
+ * Strips markdown code fences and extracts the first meaningful line,
+ * similar to how the LSP enrichment extracts hover text.
+ */
+export declare function extractSignatureFromDocs(info: ScipSymbolInfo): string | null;
+/**
+ * Extract a return type from a type signature string.
+ * Reuses the same heuristics as LSP enrichment.
+ */
+export declare function extractReturnType(signature: string | null): string | null;
+//# sourceMappingURL=index-reader.d.ts.map

package/dist/scip/index-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-reader.d.ts","sourceRoot":"","sources":["../../src/scip/index-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAIL,KAAK,QAAQ,IAAI,YAAY,EAE7B,KAAK,iBAAiB,IAAI,qBAAqB,EAChD,MAAM,cAAc,CAAC;AAItB,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,aAAa;IAUZ,OAAO,CAAC,QAAQ,CAAC,WAAW;IATxC,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6C;IACzE,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqC;IAChE,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6C;IAC7E,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,cAAqB;gBAEV,WAAW,EAAE,MAAM;IAEhD,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IA0CpC,iBAAiB,CAAC,GAAG,EAAE,qBAAqB,GAAG,IAAI;IAMnD;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI;IAmC9F;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI;IAI5D;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAIpD,+BAA+B;IAC/B,IAAI,SAAS,IAAI,MAAM,CAAsC;IAE7D,gEAAgE;IAChE,IAAI,eAAe,IAAI,MAAM,CAAkC;CAChE;AAeD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,aAAa,CAYrF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAqB5E;AAWD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAgBzE"}

package/dist/scip/index-reader.js

@@ -0,0 +1,225 @@
+/**
+ * @module indexer/scip/index-reader
+ *
+ * Parses a SCIP index (protobuf binary) into in-memory lookup structures
+ * that the enrichment coordinator can query by file + position.
+ *
+ * Uses the official SCIP protobuf schema (vendored `scip_pb.ts`) with
+ * `@bufbuild/protobuf` for decoding — no manual wire-format parsing.
+ *
+ * ## SCIP data model (relevant subset)
+ *
+ * - `Index.documents[]` — per-file occurrences and symbol definitions
+ * - `Index.external_symbols[]` — hover docs for symbols from other packages
+ * - `Occurrence.range` — `[startLine, startChar, endChar]` (3-elem) or
+ *   `[startLine, startChar, endLine, endChar]` (4-elem), 0-based
+ * - `Occurrence.symbol_roles` — bitset; bit 0 = Definition
+ * - `SymbolInformation.documentation` — markdown hover text
+ * - `SymbolInformation.signature_documentation` — structured signature
+ */
+import { resolve } from 'node:path';
+import { fromBinary } from '@bufbuild/protobuf';
+import { IndexSchema, SymbolRole, } from './scip_pb.js';
+/**
+ * In-memory SCIP index optimised for enrichment lookups.
+ *
+ * Given a file path + position, returns the definition location and
+ * type signature for the symbol at that position.
+ */
+export class ScipIndexData {
+    projectRoot;
+    /** symbol → definition location */
+    definitions = new Map();
+    /** symbol → metadata (docs, display name, signature) */
+    symbolInfo = new Map();
+    /** absolute file path → sorted occurrences */
+    fileOccurrences = new Map();
+    /** Set of languages present in this index */
+    languages = new Set();
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    addDocument(doc) {
+        const absPath = resolve(this.projectRoot, doc.relativePath);
+        if (doc.language)
+            this.languages.add(doc.language.toLowerCase());
+        const records = [];
+        for (const occ of doc.occurrences) {
+            const range = occ.range;
+            if (range.length < 3)
+                continue;
+            const startLine = range[0];
+            const startChar = range[1];
+            const endLine = range.length >= 4 ? range[2] : startLine;
+            const endChar = range.length >= 4 ? range[3] : range[2];
+            const isDefinition = (occ.symbolRoles & SymbolRole.Definition) !== 0;
+            records.push({
+                startLine,
+                startCharacter: startChar,
+                endLine,
+                endCharacter: endChar,
+                symbol: occ.symbol,
+                isDefinition,
+            });
+            // Register definition locations.
+            if (isDefinition && occ.symbol && !occ.symbol.startsWith('local ')) {
+                if (!this.definitions.has(occ.symbol)) {
+                    this.definitions.set(occ.symbol, { filePath: absPath, line: startLine, character: startChar });
+                }
+            }
+        }
+        // Sort by (startLine, startCharacter) for binary search.
+        records.sort((a, b) => a.startLine - b.startLine || a.startCharacter - b.startCharacter);
+        this.fileOccurrences.set(absPath, records);
+        // Index symbol info from document-level symbols.
+        for (const sym of doc.symbols) {
+            if (sym.symbol) {
+                this.symbolInfo.set(sym.symbol, toScipSymbolInfo(sym));
+            }
+        }
+    }
+    addExternalSymbol(sym) {
+        if (sym.symbol) {
+            this.symbolInfo.set(sym.symbol, toScipSymbolInfo(sym));
+        }
+    }
+    /**
+     * Look up the occurrence at (or nearest to) the given position in a file.
+     */
+    findOccurrence(filePath, line, character) {
+        const occs = this.fileOccurrences.get(filePath);
+        if (!occs || occs.length === 0)
+            return null;
+        // Binary search for the first occurrence on this line.
+        let lo = 0;
+        let hi = occs.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            if (occs[mid].startLine < line)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        // Scan forward through occurrences on this line to find the best match.
+        let best = null;
+        let bestDistance = Infinity;
+        for (let i = lo; i < occs.length && occs[i].startLine === line; i++) {
+            const occ = occs[i];
+            // Exact containment: character is within the occurrence range.
+            if (character >= occ.startCharacter && (occ.endLine > line || character <= occ.endCharacter)) {
+                return occ;
+            }
+            // Nearest on the same line.
+            const dist = Math.abs(occ.startCharacter - character);
+            if (dist < bestDistance) {
+                bestDistance = dist;
+                best = occ;
+            }
+        }
+        // Allow a nearby match (within 5 characters) on the same line.
+        return bestDistance <= 5 ? best : null;
+    }
+    /**
+     * Resolve a SCIP symbol string to its definition location.
+     */
+    getDefinition(symbol) {
+        return this.definitions.get(symbol) ?? null;
+    }
+    /**
+     * Get symbol metadata (documentation, signature).
+     */
+    getSymbolInfo(symbol) {
+        return this.symbolInfo.get(symbol) ?? null;
+    }
+    /** Number of indexed files. */
+    get fileCount() { return this.fileOccurrences.size; }
+    /** Number of unique symbols with known definition locations. */
+    get definitionCount() { return this.definitions.size; }
+}
+// ─── Protobuf → internal type conversion ──────────────────────────────────────
+function toScipSymbolInfo(sym) {
+    return {
+        symbol: sym.symbol,
+        documentation: [...sym.documentation],
+        displayName: sym.displayName,
+        signatureText: sym.signatureDocumentation?.text || null,
+    };
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Parse a SCIP protobuf index from raw bytes.
+ *
+ * @param buffer       The raw protobuf bytes (e.g. `fs.readFileSync(path)`).
+ * @param projectRoot  Absolute path to the project root.  Document
+ *                     `relative_path` values are resolved against this.
+ * @returns Populated `ScipIndexData` ready for enrichment queries.
+ */
+export function parseScipIndex(buffer, projectRoot) {
+    const decoded = fromBinary(IndexSchema, buffer);
+    const index = new ScipIndexData(projectRoot);
+    for (const doc of decoded.documents) {
+        index.addDocument(doc);
+    }
+    for (const sym of decoded.externalSymbols) {
+        index.addExternalSymbol(sym);
+    }
+    return index;
+}
+/**
+ * Extract a human-readable type signature from SCIP symbol documentation.
+ *
+ * Strips markdown code fences and extracts the first meaningful line,
+ * similar to how the LSP enrichment extracts hover text.
+ */
+export function extractSignatureFromDocs(info) {
+    // Prefer signature_documentation text.
+    if (info.signatureText) {
+        const cleaned = info.signatureText
+            .replace(/```[a-z0-9_+-]*\n/giu, '')
+            .replace(/```/gu, '')
+            .trim();
+        return cleaned || null;
+    }
+    // Fall back to first documentation entry that looks like a signature.
+    for (const doc of info.documentation) {
+        const cleaned = doc
+            .replace(/```[a-z0-9_+-]*\n/giu, '')
+            .replace(/```/gu, '')
+            .trim();
+        if (cleaned && looksLikeSignature(cleaned)) {
+            return cleaned;
+        }
+    }
+    return null;
+}
+/** Heuristic: does this text look like a code signature? */
+function looksLikeSignature(text) {
+    const firstLine = text.split('\n')[0] ?? '';
+    return /(?:function|def|fn|func|class|interface|type|const|let|var|pub|export|public|private|protected)\s/u.test(firstLine)
+        || /\(.*\)/u.test(firstLine)
+        || /:\s*\w/u.test(firstLine)
+        || /->\s*\w/u.test(firstLine);
+}
+/**
+ * Extract a return type from a type signature string.
+ * Reuses the same heuristics as LSP enrichment.
+ */
+export function extractReturnType(signature) {
+    if (!signature)
+        return null;
+    const lines = signature.split('\n').map((l) => l.trim()).filter(Boolean);
+    if (lines.length === 0)
+        return null;
+    const firstLine = lines[0];
+    const functionStyle = firstLine.match(/\)\s*:\s*([^={]+)$/u);
+    if (functionStyle?.[1])
+        return functionStyle[1].trim();
+    const arrowStyle = firstLine.match(/->\s*([^={]+)$/u);
+    if (arrowStyle?.[1])
+        return arrowStyle[1].trim();
+    const colonStyle = firstLine.match(/:\s*([^={]+)$/u);
+    if (colonStyle?.[1])
+        return colonStyle[1].trim();
+    return null;
+}
+//# sourceMappingURL=index-reader.js.map