@vinaes/succ 1.4.0 → 1.5.42

package/dist/lib/search/late-chunking.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Late Chunking — embed full file context, pool per AST chunk boundaries.
+ *
+ * Traditional chunking: chunk first → embed each chunk independently.
+ * Late chunking: embed full file → get per-token hidden states → pool by AST boundaries.
+ *
+ * Each chunk embedding "knows about" the whole file context for free.
+ * No extra LLM calls. Requires a long-context embedding model (e.g., jina 8192 tokens).
+ *
+ * Reference: Jina AI "Late Chunking" (2024)
+ * https://jina.ai/news/late-chunking-in-long-context-embedding-models/
+ */
+import { type Chunk } from '../chunker.js';
+export interface LateChunkResult {
+    /** Original chunk metadata */
+    chunk: Chunk;
+    /** Embedding generated via late chunking (context-aware) */
+    embedding: number[];
+}
+export interface LateChunkingResult {
+    /** Per-chunk embeddings with file-level context baked in */
+    chunks: LateChunkResult[];
+    /** Whether late chunking was used (false = fell back to standard) */
+    usedLateChunking: boolean;
+    /** Reason for fallback if not used */
+    fallbackReason?: string;
+}
+/**
+ * Generate embeddings for code chunks using late chunking.
+ *
+ * Pipeline:
+ * 1. Parse file into AST chunks (tree-sitter)
+ * 2. Concatenate full file content
+ * 3. Run embedding model on full file → get per-token hidden states
+ * 4. Map AST chunk character boundaries to token positions
+ * 5. Mean-pool hidden states within each chunk's token range
+ * 6. L2-normalize each chunk embedding
+ *
+ * Falls back to standard chunking if:
+ * - Model max_length < 512 (short-context model won't benefit)
+ * - File exceeds model's max token length
+ * - Token offset mapping unavailable
+ *
+ * @param content - Full file content
+ * @param filePath - File path for AST parsing
+ * @returns Per-chunk embeddings with file-level context
+ */
+export declare function lateChunkEmbed(content: string, filePath: string): Promise<LateChunkingResult>;
+/**
+ * Check if the current embedding model supports late chunking.
+ */
+export declare function isLateChunkingSupported(): boolean;
+//# sourceMappingURL=late-chunking.d.ts.map

package/dist/lib/search/late-chunking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"late-chunking.d.ts","sourceRoot":"","sources":["../../../src/lib/search/late-chunking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAkB,KAAK,KAAK,EAAE,MAAM,eAAe,CAAC;AAQ3D,MAAM,WAAW,eAAe;IAC9B,8BAA8B;IAC9B,KAAK,EAAE,KAAK,CAAC;IACb,4DAA4D;IAC5D,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,qEAAqE;IACrE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,sCAAsC;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AASD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,kBAAkB,CAAC,CAkH7B;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAKjD"}

package/dist/lib/search/late-chunking.js

@@ -0,0 +1,230 @@
+/**
+ * Late Chunking — embed full file context, pool per AST chunk boundaries.
+ *
+ * Traditional chunking: chunk first → embed each chunk independently.
+ * Late chunking: embed full file → get per-token hidden states → pool by AST boundaries.
+ *
+ * Each chunk embedding "knows about" the whole file context for free.
+ * No extra LLM calls. Requires a long-context embedding model (e.g., jina 8192 tokens).
+ *
+ * Reference: Jina AI "Late Chunking" (2024)
+ * https://jina.ai/news/late-chunking-in-long-context-embedding-models/
+ */
+import { logInfo, logWarn } from '../fault-logger.js';
+import { getNativeSession, getModelMaxLength } from '../embeddings.js';
+import { chunkCodeAsync } from '../chunker.js';
+import { getLLMTaskConfig } from '../config.js';
+import { LOCAL_MODEL } from '../config-defaults.js';
+// Minimum max_length to enable late chunking (short-context models can't benefit)
+const MIN_CONTEXT_FOR_LATE_CHUNKING = 512;
+// ============================================================================
+// Core Implementation
+// ============================================================================
+/**
+ * Generate embeddings for code chunks using late chunking.
+ *
+ * Pipeline:
+ * 1. Parse file into AST chunks (tree-sitter)
+ * 2. Concatenate full file content
+ * 3. Run embedding model on full file → get per-token hidden states
+ * 4. Map AST chunk character boundaries to token positions
+ * 5. Mean-pool hidden states within each chunk's token range
+ * 6. L2-normalize each chunk embedding
+ *
+ * Falls back to standard chunking if:
+ * - Model max_length < 512 (short-context model won't benefit)
+ * - File exceeds model's max token length
+ * - Token offset mapping unavailable
+ *
+ * @param content - Full file content
+ * @param filePath - File path for AST parsing
+ * @returns Per-chunk embeddings with file-level context
+ */
+export async function lateChunkEmbed(content, filePath) {
+    // Check if current model supports late chunking
+    const taskCfg = getLLMTaskConfig('embeddings');
+    const model = taskCfg.model || LOCAL_MODEL;
+    const maxLength = getModelMaxLength(model);
+    if (maxLength < MIN_CONTEXT_FOR_LATE_CHUNKING) {
+        return {
+            chunks: [],
+            usedLateChunking: false,
+            fallbackReason: `Model ${model} max_length=${maxLength} too short for late chunking (need ${MIN_CONTEXT_FOR_LATE_CHUNKING}+)`,
+        };
+    }
+    try {
+        // 1. Parse into AST chunks
+        const chunks = await chunkCodeAsync(content, filePath);
+        if (chunks.length === 0) {
+            return { chunks: [], usedLateChunking: true };
+        }
+        const session = await getNativeSession();
+        // 2. Get token offsets for the full file
+        const tokenOffsets = session.getTokenOffsets(content);
+        // Detect tokenizer truncation: if the model's max_length was exceeded the
+        // tokenizer silently truncates the input. We check by finding the last
+        // token whose offset covers real content (non-special tokens have non-zero
+        // offsets) and comparing its end to the content length. If the furthest
+        // character covered is substantially less than the full content length the
+        // file was truncated and late chunking would produce incorrect embeddings
+        // for the trailing chunks.
+        const lastCoveredChar = tokenOffsets.reduce((max, [, tEnd], i) => {
+            // Skip special tokens (offset [0,0] after position 0)
+            if (tEnd === 0 && i > 0)
+                return max;
+            return Math.max(max, tEnd);
+        }, 0);
+        // 0.95 threshold: allow up to 5% character loss from tokenizer rounding
+        // (subword boundaries rarely align exactly with content end). Beyond 5%
+        // the file was genuinely truncated and trailing chunks would be wrong.
+        if (lastCoveredChar > 0 && lastCoveredChar < content.length * 0.95) {
+            return {
+                chunks: [],
+                usedLateChunking: false,
+                fallbackReason: `File exceeds model max_length (covered ${lastCoveredChar}/${content.length} chars); falling back to standard chunking`,
+            };
+        }
+        // 3. Run model on full file → get per-token hidden states
+        const raw = await session.embedRaw(content);
+        // 4. Pre-compute line offsets for O(1) char position lookup
+        const lineOffsets = computeLineOffsets(content);
+        // Map each chunk's character range to token positions
+        const results = [];
+        for (const chunk of chunks) {
+            // Find character range for this chunk in the original content.
+            // chunk.startLine / chunk.endLine are 1-indexed.
+            //
+            // The end boundary is derived from lineOffsets rather than from
+            // chunk.content.length.  chunk.content is assembled with join('\n'),
+            // which omits the trailing newline that exists in the original source.
+            // Using lineOffsets[endLine] (= start-of-next-line) gives the correct
+            // exclusive end that covers the trailing '\n'.  For the very last chunk
+            // we fall back to content.length so we never read past the buffer.
+            const chunkCharStart = getCharOffsetForLine(lineOffsets, chunk.startLine);
+            // lineOffsets is 0-indexed by line (lineOffsets[0] = offset of line 1).
+            // The offset of the line after endLine is lineOffsets[endLine] when it
+            // exists, otherwise the total content length.
+            const chunkCharEnd = chunk.endLine < lineOffsets.length ? lineOffsets[chunk.endLine] : content.length;
+            // Map char range to token range
+            const tokenRange = charRangeToTokenRange(tokenOffsets, chunkCharStart, chunkCharEnd);
+            if (tokenRange.start >= tokenRange.end) {
+                // Chunk mapped to zero tokens — skip
+                continue;
+            }
+            // 5. Mean-pool hidden states within this token range
+            const embedding = poolTokenRange(raw.hiddenStates, raw.attentionMask, raw.hiddenDim, tokenRange.start, tokenRange.end);
+            // 6. L2-normalize
+            l2Normalize(embedding);
+            results.push({ chunk, embedding: Array.from(embedding) });
+        }
+        logInfo('late-chunking', `Generated ${results.length} context-aware embeddings for ${filePath} (${tokenOffsets.length} tokens)`);
+        return { chunks: results, usedLateChunking: true };
+    }
+    catch (error) {
+        logWarn('late-chunking', `Late chunking failed, use standard embedding`, {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return {
+            chunks: [],
+            usedLateChunking: false,
+            fallbackReason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Check if the current embedding model supports late chunking.
+ */
+export function isLateChunkingSupported() {
+    const taskCfg = getLLMTaskConfig('embeddings');
+    const model = taskCfg.model || LOCAL_MODEL;
+    const maxLength = getModelMaxLength(model);
+    return maxLength >= MIN_CONTEXT_FOR_LATE_CHUNKING;
+}
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+/**
+ * Pre-compute character offset for each line (0-indexed).
+ * Returns array where lineOffsets[i] = char offset of line i+1 (1-indexed).
+ */
+function computeLineOffsets(content) {
+    const offsets = [0]; // Line 1 starts at offset 0
+    for (let i = 0; i < content.length; i++) {
+        // Handle CRLF: skip \r before \n so offsets stay consistent
+        if (content[i] === '\r' && content[i + 1] === '\n') {
+            offsets.push(i + 2);
+            i++; // skip the \n
+        }
+        else if (content[i] === '\n') {
+            offsets.push(i + 1);
+        }
+    }
+    return offsets;
+}
+/**
+ * Get character offset for a 1-indexed line number.
+ */
+function getCharOffsetForLine(lineOffsets, line) {
+    const idx = Math.max(0, Math.min(line - 1, lineOffsets.length - 1));
+    return lineOffsets[idx];
+}
+/**
+ * Map character range [charStart, charEnd) to token range [tokenStart, tokenEnd).
+ * Uses token offset mappings from the tokenizer.
+ */
+function charRangeToTokenRange(tokenOffsets, charStart, charEnd) {
+    let tokenStart = tokenOffsets.length;
+    let tokenEnd = 0;
+    for (let i = 0; i < tokenOffsets.length; i++) {
+        const [tStart, tEnd] = tokenOffsets[i];
+        // Skip special tokens (offset [0,0])
+        if (tStart === 0 && tEnd === 0 && i > 0)
+            continue;
+        // Token overlaps with chunk range
+        if (tEnd > charStart && tStart < charEnd) {
+            tokenStart = Math.min(tokenStart, i);
+            tokenEnd = Math.max(tokenEnd, i + 1);
+        }
+    }
+    return { start: tokenStart, end: tokenEnd };
+}
+/**
+ * Mean-pool hidden states for a token range [start, end).
+ * Respects attention mask (skips padding tokens).
+ */
+function poolTokenRange(hiddenStates, attentionMask, hiddenDim, tokenStart, tokenEnd) {
+    const embedding = new Float64Array(hiddenDim);
+    let maskSum = 0;
+    for (let t = tokenStart; t < tokenEnd; t++) {
+        const mask = Number(attentionMask[t]);
+        if (mask === 0)
+            continue;
+        maskSum += mask;
+        const offset = t * hiddenDim;
+        for (let d = 0; d < hiddenDim; d++) {
+            embedding[d] += hiddenStates[offset + d] * mask;
+        }
+    }
+    if (maskSum > 0) {
+        for (let d = 0; d < hiddenDim; d++) {
+            embedding[d] /= maskSum;
+        }
+    }
+    return embedding;
+}
+/**
+ * In-place L2 normalization.
+ */
+function l2Normalize(embedding) {
+    let norm = 0;
+    for (let d = 0; d < embedding.length; d++) {
+        norm += embedding[d] * embedding[d];
+    }
+    norm = Math.sqrt(norm);
+    if (norm > 0) {
+        for (let d = 0; d < embedding.length; d++) {
+            embedding[d] /= norm;
+        }
+    }
+}
+//# sourceMappingURL=late-chunking.js.map

package/dist/lib/search/late-chunking.js.map

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

package/dist/lib/search/ppr-retrieval.d.ts

@@ -0,0 +1,49 @@
+/**
+ * PPR-Enhanced Retrieval — Graph-backed search using Personalized PageRank.
+ *
+ * Pipeline (HippoRAG2/ProPEX-RAG inspired):
+ * 1. Embed query → find top-k semantically similar nodes
+ * 2. Run PPR from those seed nodes across knowledge graph
+ * 3. Expand result set with high-PPR-score neighbors
+ * 4. Re-rank: (embedding_similarity * 0.5) + (ppr_score * 0.3) + (centrality * 0.2)
+ * 5. Return merged, re-ranked results with rank_explain metadata
+ */
+export interface PPRSearchResult {
+    memoryId: number;
+    /** Combined score from all signals */
+    score: number;
+    /** Individual score components */
+    components: {
+        semantic: number;
+        ppr: number;
+        centrality: number;
+        feedback: number;
+    };
+    /** Human-readable explanation of ranking */
+    rankExplain: string;
+}
+export interface PPRSearchOptions {
+    /** Weight for semantic similarity (default: 0.5) */
+    semanticWeight?: number;
+    /** Weight for PPR score (default: 0.3) */
+    pprWeight?: number;
+    /** Weight for centrality (default: 0.1) */
+    centralityWeight?: number;
+    /** Weight for feedback boost (default: 0.1) */
+    feedbackWeight?: number;
+    /** PPR damping factor (default: 0.85) */
+    alpha?: number;
+    /** Max results (default: 20) */
+    limit?: number;
+}
+/**
+ * Re-rank search results using PPR, centrality, and feedback signals.
+ *
+ * @param semanticResults - Initial search results with memory IDs and similarity scores
+ * @param options - Tuning parameters
+ */
+export declare function pprEnhancedRerank(semanticResults: Array<{
+    memoryId: number;
+    similarity: number;
+}>, options?: PPRSearchOptions): Promise<PPRSearchResult[]>;
+//# sourceMappingURL=ppr-retrieval.d.ts.map

package/dist/lib/search/ppr-retrieval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ppr-retrieval.d.ts","sourceRoot":"","sources":["../../../src/lib/search/ppr-retrieval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAUH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,UAAU,EAAE;QACV,QAAQ,EAAE,MAAM,CAAC;QACjB,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,eAAe,EAAE,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,EAChE,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,EAAE,CAAC,CAqH5B"}

package/dist/lib/search/ppr-retrieval.js

@@ -0,0 +1,135 @@
+/**
+ * PPR-Enhanced Retrieval — Graph-backed search using Personalized PageRank.
+ *
+ * Pipeline (HippoRAG2/ProPEX-RAG inspired):
+ * 1. Embed query → find top-k semantically similar nodes
+ * 2. Run PPR from those seed nodes across knowledge graph
+ * 3. Expand result set with high-PPR-score neighbors
+ * 4. Re-rank: (embedding_similarity * 0.5) + (ppr_score * 0.3) + (centrality * 0.2)
+ * 5. Return merged, re-ranked results with rank_explain metadata
+ */
+import { personalizedPageRank, computePageRank } from '../graph/graphology-bridge.js';
+import { getBoostFactors } from '../retrieval-feedback.js';
+import { logWarn } from '../fault-logger.js';
+// ============================================================================
+// PPR-Enhanced Search
+// ============================================================================
+/**
+ * Re-rank search results using PPR, centrality, and feedback signals.
+ *
+ * @param semanticResults - Initial search results with memory IDs and similarity scores
+ * @param options - Tuning parameters
+ */
+export async function pprEnhancedRerank(semanticResults, options) {
+    const raw = options ?? {};
+    // Validate and clamp numeric options — reject non-finite / negative values.
+    const clampWeight = (v, def) => {
+        const n = v ?? def;
+        return Number.isFinite(n) && n >= 0 ? n : def;
+    };
+    const clampAlpha = (v) => {
+        const n = v ?? 0.85;
+        return Number.isFinite(n) && n > 0 && n < 1 ? n : 0.85;
+    };
+    const clampLimit = (v) => {
+        const n = v ?? 20;
+        return Number.isFinite(n) && n > 0 ? Math.floor(n) : 20;
+    };
+    const semanticWeight = clampWeight(raw.semanticWeight, 0.5);
+    const pprWeight = clampWeight(raw.pprWeight, 0.3);
+    const centralityWeight = clampWeight(raw.centralityWeight, 0.1);
+    const feedbackWeight = clampWeight(raw.feedbackWeight, 0.1);
+    const alpha = clampAlpha(raw.alpha);
+    const limit = clampLimit(raw.limit);
+    if (semanticResults.length === 0)
+        return [];
+    // Step 1: Get PPR scores seeded from semantic results
+    const seedIds = semanticResults.map((r) => r.memoryId);
+    const pprScores = new Map();
+    try {
+        const pprResults = await personalizedPageRank(seedIds, limit * 2, alpha);
+        for (const { memoryId, score } of pprResults) {
+            pprScores.set(memoryId, score);
+        }
+    }
+    catch (error) {
+        logWarn('ppr-retrieval', 'PPR failed, using semantic-only ranking', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    // Step 2: Get global PageRank (centrality)
+    let centralityScores = new Map();
+    try {
+        centralityScores = await computePageRank();
+    }
+    catch (error) {
+        logWarn('ppr-retrieval', 'PageRank failed, skipping centrality', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    // Step 3: Get feedback boost factors
+    const allIds = new Set([...seedIds, ...pprScores.keys()]);
+    let feedbackFactors = new Map();
+    try {
+        feedbackFactors = getBoostFactors([...allIds]);
+    }
+    catch (error) {
+        logWarn('ppr-retrieval', 'Feedback boost failed, skipping', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    // Step 4: Normalize scores (avoid spread for large maps — stack overflow risk)
+    // Use 0 as initial max — if all values are 0, normalization yields 0 (no signal)
+    let maxSemantic = 0;
+    for (const r of semanticResults) {
+        if (r.similarity > maxSemantic)
+            maxSemantic = r.similarity;
+    }
+    let maxPPR = 0;
+    for (const v of pprScores.values()) {
+        if (v > maxPPR)
+            maxPPR = v;
+    }
+    let maxCentrality = 0;
+    for (const v of centralityScores.values()) {
+        if (v > maxCentrality)
+            maxCentrality = v;
+    }
+    // Step 5: Merge all candidates (semantic + PPR-discovered)
+    const semanticMap = new Map(semanticResults.map((r) => [r.memoryId, r.similarity]));
+    const candidates = new Set([...semanticMap.keys(), ...pprScores.keys()]);
+    const results = [];
+    for (const memoryId of candidates) {
+        const semantic = maxSemantic > 0 ? (semanticMap.get(memoryId) ?? 0) / maxSemantic : 0;
+        const ppr = maxPPR > 0 ? (pprScores.get(memoryId) ?? 0) / maxPPR : 0;
+        const centrality = maxCentrality > 0 ? (centralityScores.get(memoryId) ?? 0) / maxCentrality : 0;
+        const feedback = feedbackFactors.get(memoryId) ?? 1.0;
+        // Combine scores (weights: semantic + ppr + centrality = linear blend)
+        // feedbackWeight controls the strength of the multiplicative feedback modifier
+        const baseScore = semantic * semanticWeight + ppr * pprWeight + centrality * centralityWeight;
+        // Apply feedback as multiplicative modifier scaled by feedbackWeight
+        // feedback=1.3 with feedbackWeight=0.1 → 1.0 + 0.1*(1.3-1.0) = 1.03x boost
+        const feedbackModifier = feedbackWeight > 0 ? 1.0 + feedbackWeight * (feedback - 1.0) : 1.0;
+        const score = baseScore * feedbackModifier;
+        // Build explanation
+        const parts = [];
+        if (semantic > 0)
+            parts.push(`semantic:${(semantic * semanticWeight).toFixed(3)}`);
+        if (ppr > 0)
+            parts.push(`ppr:${(ppr * pprWeight).toFixed(3)}`);
+        if (centrality > 0)
+            parts.push(`centrality:${(centrality * centralityWeight).toFixed(3)}`);
+        if (feedback !== 1.0)
+            parts.push(`feedback:${feedback.toFixed(2)}x`);
+        results.push({
+            memoryId,
+            score,
+            components: { semantic, ppr, centrality, feedback },
+            rankExplain: parts.join(' + '),
+        });
+    }
+    // Sort by score descending
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, limit);
+}
+//# sourceMappingURL=ppr-retrieval.js.map

package/dist/lib/search/ppr-retrieval.js.map

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

package/dist/lib/search/repo-map.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Repo Map Generation — Aider-style compact repository overview.
+ *
+ * Generates a compact text map: file path + exported symbols, one line per file.
+ * Uses tree-sitter AST for accurate symbol extraction (13 languages).
+ *
+ * Output example:
+ *   src/lib/auth.ts: hashPassword, verifyToken, createSession
+ *   src/lib/config.ts: getConfig, setConfigOverride, SuccConfig
+ */
+export interface RepoMapEntry {
+    filePath: string;
+    symbols: string[];
+    lineCount: number;
+}
+export interface RepoMapResult {
+    entries: RepoMapEntry[];
+    text: string;
+    totalFiles: number;
+    totalSymbols: number;
+}
+/**
+ * Generate a repo map using tree-sitter AST symbol extraction.
+ *
+ * @param rootPath - Project root (default: getProjectRoot())
+ * @param options - Filter options
+ */
+export declare function generateRepoMap(rootPath?: string, options?: {
+    /** Include patterns (glob-like) */
+    include?: string[];
+    /** Exclude patterns */
+    exclude?: string[];
+    /** Max symbols per file (default: 10) */
+    maxSymbolsPerFile?: number;
+    /**
+     * Symbol types to include. Accepted values match tree-sitter SymbolType:
+     * 'function', 'method', 'class', 'interface', 'type_alias', 'enum',
+     * 'struct', 'trait', 'impl', 'module', 'variable', 'constant'.
+     * Plural aliases are also accepted: 'functions'→'function', etc.
+     */
+    symbolTypes?: string[];
+}): Promise<RepoMapResult>;
+//# sourceMappingURL=repo-map.d.ts.map

package/dist/lib/search/repo-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-map.d.ts","sourceRoot":"","sources":["../../../src/lib/search/repo-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAcH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAuBD;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;IACR,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,uBAAuB;IACvB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,yCAAyC;IACzC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,GACA,OAAO,CAAC,aAAa,CAAC,CAkExB"}