@vinaes/succ 1.4.0 → 1.5.42

package/dist/lib/search/hierarchical-summaries.js

@@ -0,0 +1,423 @@
+/**
+ * Hierarchical Summaries — RAPTOR-style multi-level abstraction.
+ *
+ * Generates zoom-level summaries: file → directory → module → repo.
+ * Different query granularity needs different zoom levels:
+ *   "What does hashPassword do?" → file-level
+ *   "What does the auth module do?" → directory-level
+ *   "Describe this project" → repo-level
+ *
+ * Summaries are stored as memory nodes with level metadata,
+ * enabling search at the appropriate zoom based on query specificity.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { logInfo, logWarn } from '../fault-logger.js';
+import { getProjectRoot } from '../config.js';
+import { callLLM } from '../llm.js';
+import { EXTENSION_TO_LANGUAGE } from '../tree-sitter/types.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_EXCLUDES = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.next',
+    '.nuxt',
+    'coverage',
+    '__pycache__',
+    '.pytest_cache',
+    'target',
+    'vendor',
+    '.succ',
+    '.claude',
+]);
+const CODE_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.py',
+    '.go',
+    '.rs',
+    '.rb',
+    '.java',
+    '.kt',
+    '.cs',
+    '.cpp',
+    '.c',
+    '.h',
+]);
+// Max chars to send to LLM for summarization
+const MAX_FILE_CONTENT_CHARS = 6000;
+const MAX_DIR_CONTENT_CHARS = 8000;
+function extractExportedSymbols(content, ext) {
+    const symbols = [];
+    if (['.ts', '.tsx', '.js', '.jsx'].includes(ext)) {
+        const patterns = [
+            /export\s+(?:default\s+)?(?:async\s+)?function\s+(\w+)/g,
+            /export\s+(?:const|let|var)\s+(\w+)/g,
+            /export\s+(?:default\s+)?class\s+(\w+)/g,
+            /export\s+interface\s+(\w+)/g,
+            /export\s+type\s+(\w+)/g,
+            /export\s+enum\s+(\w+)/g,
+        ];
+        for (const pattern of patterns) {
+            let match;
+            while ((match = pattern.exec(content)) !== null) {
+                symbols.push(match[1]);
+            }
+        }
+    }
+    else if (ext === '.py') {
+        let match;
+        const defPat = /^def\s+(\w+)/gm;
+        while ((match = defPat.exec(content)) !== null) {
+            if (!match[1].startsWith('_'))
+                symbols.push(match[1]);
+        }
+        const classPat = /^class\s+(\w+)/gm;
+        while ((match = classPat.exec(content)) !== null) {
+            symbols.push(match[1]);
+        }
+    }
+    else if (ext === '.go') {
+        const patterns = [/^func\s+(\w+)/gm, /^type\s+(\w+)\s+(?:struct|interface)/gm];
+        for (const pattern of patterns) {
+            let match;
+            while ((match = pattern.exec(content)) !== null) {
+                if (match[1][0] === match[1][0].toUpperCase())
+                    symbols.push(match[1]);
+            }
+        }
+    }
+    else if (ext === '.rs') {
+        const patterns = [/pub\s+(?:async\s+)?fn\s+(\w+)/g, /pub\s+(?:struct|enum|trait)\s+(\w+)/g];
+        for (const pattern of patterns) {
+            let match;
+            while ((match = pattern.exec(content)) !== null) {
+                symbols.push(match[1]);
+            }
+        }
+    }
+    return [...new Set(symbols)];
+}
+async function summarizeFile(file) {
+    const truncated = file.content.slice(0, MAX_FILE_CONTENT_CHARS);
+    const symbolList = file.symbols.length > 0 ? `\nExported symbols: ${file.symbols.join(', ')}` : '';
+    const prompt = `Summarize this source file in 2-3 sentences. Focus on its purpose, what it provides, and its role in the project. Be specific about functionality, not generic.
+
+File: ${file.relativePath} (${file.lineCount} lines)${symbolList}
+
+\`\`\`
+${truncated}
+\`\`\`
+
+Summary:`;
+    return callLLM(prompt);
+}
+// ============================================================================
+// Directory-level summary
+// ============================================================================
+async function summarizeDirectory(dirPath, fileSummaries) {
+    const fileDescriptions = fileSummaries
+        .map((s) => `- ${path.basename(s.path)}: ${s.summary}`)
+        .join('\n')
+        .slice(0, MAX_DIR_CONTENT_CHARS);
+    const prompt = `Summarize what this directory/module does in 2-3 sentences based on its files. Focus on the module's overall responsibility and how its parts work together.
+
+Directory: ${dirPath}
+Files (${fileSummaries.length}):
+${fileDescriptions}
+
+Summary:`;
+    return callLLM(prompt);
+}
+// ============================================================================
+// Main generation pipeline
+// ============================================================================
+/**
+ * Generate hierarchical summaries for a codebase.
+ *
+ * Builds summaries bottom-up: files → directories → module groups → repo.
+ *
+ * @param rootPath - Project root (default: getProjectRoot())
+ * @param options - Generation options
+ */
+export async function generateHierarchicalSummaries(rootPath, options) {
+    const root = rootPath ?? getProjectRoot();
+    const extensions = options?.extensions ?? CODE_EXTENSIONS;
+    const excludes = options?.excludes ?? DEFAULT_EXCLUDES;
+    const maxFiles = options?.maxFiles ?? 200;
+    const rawConcurrency = options?.concurrency;
+    const concurrency = typeof rawConcurrency === 'number' && Number.isFinite(rawConcurrency) && rawConcurrency > 0
+        ? Math.floor(rawConcurrency)
+        : 3;
+    const includeRepo = options?.includeRepo ?? true;
+    const summaries = [];
+    const levels = { file: 0, directory: 0, module: 0, repo: 0 };
+    // 1. Collect all code files
+    const files = [];
+    collectFiles(root, root, extensions, excludes, files, maxFiles);
+    logInfo('hierarchical', `Collected ${files.length} files for summarization`);
+    // 2. Generate file-level summaries (with concurrency control)
+    const fileSummaries = [];
+    for (let i = 0; i < files.length; i += concurrency) {
+        const batch = files.slice(i, i + concurrency);
+        const results = await Promise.all(batch.map(async (file) => {
+            try {
+                const summary = await summarizeFile(file);
+                return {
+                    path: file.relativePath,
+                    level: 'file',
+                    summary,
+                    symbols: file.symbols,
+                    fileCount: 1,
+                    lineCount: file.lineCount,
+                };
+            }
+            catch (error) {
+                logWarn('hierarchical', `Failed to summarize ${file.relativePath}`, {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return null;
+            }
+        }));
+        for (const result of results) {
+            if (result) {
+                fileSummaries.push(result);
+                summaries.push(result);
+                levels.file++;
+            }
+        }
+    }
+    // 3. Group by directory and generate directory-level summaries
+    const dirGroups = new Map();
+    for (const fileSummary of fileSummaries) {
+        const dir = path.dirname(fileSummary.path);
+        const group = dirGroups.get(dir) ?? [];
+        group.push(fileSummary);
+        dirGroups.set(dir, group);
+    }
+    const dirSummaries = [];
+    const dirEntries = [...dirGroups.entries()].filter(([, files]) => files.length >= 1);
+    for (let i = 0; i < dirEntries.length; i += concurrency) {
+        const batch = dirEntries.slice(i, i + concurrency);
+        const results = await Promise.all(batch.map(async ([dir, dirFiles]) => {
+            try {
+                const summary = await summarizeDirectory(dir, dirFiles);
+                const totalLines = dirFiles.reduce((sum, f) => sum + f.lineCount, 0);
+                return {
+                    path: dir,
+                    level: 'directory',
+                    summary,
+                    fileCount: dirFiles.length,
+                    lineCount: totalLines,
+                    children: dirFiles.map((f) => f.path),
+                };
+            }
+            catch (error) {
+                logWarn('hierarchical', `Failed to summarize directory ${dir}`, {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return null;
+            }
+        }));
+        for (const result of results) {
+            if (result) {
+                dirSummaries.push(result);
+                summaries.push(result);
+                levels.directory++;
+            }
+        }
+    }
+    // 4. Group directories into modules (top-level src/* directories)
+    const moduleGroups = new Map();
+    for (const dirSummary of dirSummaries) {
+        // Extract module: first 2 path segments (e.g., "src/lib", "src/mcp")
+        const parts = dirSummary.path.split('/');
+        // Guard against root paths creating a cycle with the repo node
+        const moduleKey = dirSummary.path === '.' || dirSummary.path === ''
+            ? '__root__'
+            : parts.length >= 2
+                ? parts.slice(0, 2).join('/')
+                : parts[0];
+        const group = moduleGroups.get(moduleKey) ?? [];
+        group.push(dirSummary);
+        moduleGroups.set(moduleKey, group);
+    }
+    const moduleSummaries = [];
+    const moduleEntries = [...moduleGroups.entries()].filter(([, dirs]) => dirs.length >= 1);
+    for (const [moduleKey, moduleDirs] of moduleEntries) {
+        try {
+            const dirDescriptions = moduleDirs
+                .map((d) => `- ${d.path}: ${d.summary}`)
+                .join('\n')
+                .slice(0, MAX_DIR_CONTENT_CHARS);
+            const totalFiles = moduleDirs.reduce((sum, d) => sum + d.fileCount, 0);
+            const totalLines = moduleDirs.reduce((sum, d) => sum + d.lineCount, 0);
+            const prompt = `Summarize this code module in 2-3 sentences. Focus on its architectural role, major subsystems, and how they fit together.
+
+Module: ${moduleKey}
+Sub-directories (${moduleDirs.length}):
+${dirDescriptions}
+
+Summary:`;
+            const summary = await callLLM(prompt);
+            const moduleSummary = {
+                path: moduleKey,
+                level: 'module',
+                summary,
+                fileCount: totalFiles,
+                lineCount: totalLines,
+                children: moduleDirs.map((d) => d.path),
+            };
+            moduleSummaries.push(moduleSummary);
+            summaries.push(moduleSummary);
+            levels.module++;
+        }
+        catch (error) {
+            logWarn('hierarchical', `Failed to summarize module ${moduleKey}`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    // 5. Generate repo-level summary
+    if (includeRepo && moduleSummaries.length > 0) {
+        try {
+            const moduleDescriptions = moduleSummaries
+                .map((m) => `- ${m.path} (${m.fileCount} files): ${m.summary}`)
+                .join('\n')
+                .slice(0, MAX_DIR_CONTENT_CHARS);
+            const totalFiles = files.length;
+            const totalLines = files.reduce((sum, f) => sum + f.lineCount, 0);
+            const prompt = `Summarize this entire codebase in 3-4 sentences. What does it do? What are its major components? What technologies does it use?
+
+Project root: ${path.basename(root)}
+Modules (${moduleSummaries.length}):
+${moduleDescriptions}
+
+Total: ${totalFiles} files, ~${totalLines} lines of code
+
+Summary:`;
+            const summary = await callLLM(prompt);
+            summaries.push({
+                path: '.',
+                level: 'repo',
+                summary,
+                fileCount: totalFiles,
+                lineCount: totalLines,
+                children: moduleSummaries.map((m) => m.path),
+            });
+            levels.repo++;
+        }
+        catch (error) {
+            logWarn('hierarchical', `Failed to generate repo summary`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    logInfo('hierarchical', `Generated ${summaries.length} summaries: ${levels.file} file, ${levels.directory} dir, ${levels.module} module, ${levels.repo} repo`);
+    return {
+        summaries,
+        totalFiles: files.length,
+        totalDirectories: dirGroups.size,
+        levels,
+    };
+}
+/**
+ * Get the appropriate summary level for a query based on specificity.
+ *
+ * Heuristic: specific symbol/file queries → file level first,
+ * then explicit scope keywords, then broad repo phrases.
+ * Symbol checks must precede generic repo phrases so that
+ * "what does myFunction do" resolves to file, not repo.
+ */
+export function inferSummaryLevel(query) {
+    const lower = query.toLowerCase();
+    // File path detection — tokens containing a recognized code extension route to file scope
+    const tokens = query.split(/\s+/);
+    for (const token of tokens) {
+        const ext = path.extname(token).slice(1).toLowerCase(); // strip leading dot
+        if (ext && ext in EXTENSION_TO_LANGUAGE)
+            return 'file';
+    }
+    // Specific symbol name check (camelCase, snake_case) — precise signal
+    if (/[a-z][A-Z]/.test(query) || /[a-zA-Z]{2,}_[a-zA-Z]{2,}/.test(query))
+        return 'file';
+    // Directory-level indicators (checked before repo to handle "describe this folder")
+    const dirWords = ['directory', 'folder', 'namespace', 'dir '];
+    if (dirWords.some((w) => lower.includes(w)))
+        return 'directory';
+    // Module-level indicators (checked before repo — "describe auth module" → module)
+    const moduleWords = ['module', 'subsystem', 'component', 'layer', 'package'];
+    if (moduleWords.some((w) => lower.includes(w)))
+        return 'module';
+    // Repo-level indicators — broad phrases that only match repo-scope queries
+    const repoWords = [
+        'project',
+        'codebase',
+        'repository',
+        'overview',
+        'architecture',
+        'describe this',
+        'what does this do',
+    ];
+    if (repoWords.some((w) => lower.includes(w)))
+        return 'repo';
+    // Default to directory (good middle ground)
+    return 'directory';
+}
+// ============================================================================
+// File Collection
+// ============================================================================
+function collectFiles(dir, root, extensions, excludes, result, maxFiles) {
+    if (result.length >= maxFiles)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        logWarn('hierarchical', `Failed to read directory: ${dir}`, {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return;
+    }
+    for (const entry of entries) {
+        if (result.length >= maxFiles)
+            return;
+        if (excludes.has(entry.name) || entry.name.startsWith('.'))
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            collectFiles(fullPath, root, extensions, excludes, result, maxFiles);
+        }
+        else if (entry.isFile()) {
+            const ext = path.extname(entry.name).toLowerCase();
+            if (!extensions.has(ext))
+                continue;
+            try {
+                const content = fs.readFileSync(fullPath, 'utf-8');
+                const lineCount = content.split('\n').length;
+                const symbols = extractExportedSymbols(content, ext);
+                const relativePath = path.relative(root, fullPath).replace(/\\/g, '/');
+                result.push({
+                    relativePath,
+                    absolutePath: fullPath,
+                    content,
+                    lineCount,
+                    symbols,
+                });
+            }
+            catch (error) {
+                logWarn('hierarchical', `Failed to read file: ${fullPath}`, {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+}
+//# sourceMappingURL=hierarchical-summaries.js.map

package/dist/lib/search/hierarchical-summaries.js.map

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

package/dist/lib/search/hyde.d.ts

@@ -0,0 +1,27 @@
+/**
+ * HyDE (Hypothetical Document Embeddings) for Code Search.
+ *
+ * For natural language queries, generates a hypothetical code snippet
+ * via LLM, then embeds the code (not the query) to bridge the
+ * NL↔code embedding space gap.
+ *
+ * "how to debounce" → LLM generates `function debounce(fn, delay) {...}`
+ * → embed the code → find real implementations.
+ */
+export interface HyDEResult {
+    /** Averaged embedding from hypothetical documents */
+    embedding: number[];
+    /** The generated hypothetical code snippets */
+    hypotheticals: string[];
+    /** Whether HyDE was used (vs. fallback to direct query embedding) */
+    used: boolean;
+}
+/**
+ * Generate hypothetical code embeddings for a natural language query.
+ *
+ * @param query - Natural language search query
+ * @param numHypotheticals - Number of hypothetical docs to generate (default: 3)
+ * @returns Averaged embedding from hypothetical documents
+ */
+export declare function generateHyDE(query: string, numHypotheticals?: number): Promise<HyDEResult>;
+//# sourceMappingURL=hyde.d.ts.map

package/dist/lib/search/hyde.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hyde.d.ts","sourceRoot":"","sources":["../../../src/lib/search/hyde.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,MAAM,WAAW,UAAU;IACzB,qDAAqD;IACrD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,qEAAqE;IACrE,IAAI,EAAE,OAAO,CAAC;CACf;AAiBD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,gBAAgB,GAAE,MAAU,GAC3B,OAAO,CAAC,UAAU,CAAC,CA0ErB"}

package/dist/lib/search/hyde.js

@@ -0,0 +1,141 @@
+/**
+ * HyDE (Hypothetical Document Embeddings) for Code Search.
+ *
+ * For natural language queries, generates a hypothetical code snippet
+ * via LLM, then embeds the code (not the query) to bridge the
+ * NL↔code embedding space gap.
+ *
+ * "how to debounce" → LLM generates `function debounce(fn, delay) {...}`
+ * → embed the code → find real implementations.
+ */
+import { callLLM } from '../llm.js';
+import { getEmbedding, getEmbeddings } from '../embeddings.js';
+import { logInfo, logWarn } from '../fault-logger.js';
+import { parseCode } from '../tree-sitter/index.js';
+// ============================================================================
+// HyDE
+// ============================================================================
+const HYDE_SYSTEM = `You are a code generation assistant. Given a natural language query about code, generate a realistic code snippet that would answer the query. Output ONLY the code, no explanations.`;
+const HYDE_PROMPT = `Generate a code snippet that answers this query:
+"{query}"
+
+Requirements:
+- Write realistic, production-quality code
+- Use common patterns and naming conventions
+- Include function signature, types, and core logic
+- Output ONLY the code (no markdown, no explanations)`;
+/**
+ * Generate hypothetical code embeddings for a natural language query.
+ *
+ * @param query - Natural language search query
+ * @param numHypotheticals - Number of hypothetical docs to generate (default: 3)
+ * @returns Averaged embedding from hypothetical documents
+ */
+export async function generateHyDE(query, numHypotheticals = 3) {
+    // Reject blank or whitespace-only queries early — they produce nonsense hypotheticals
+    if (!query || !query.trim()) {
+        throw new Error('generateHyDE: query must not be blank');
+    }
+    // Clamp to prevent excessive LLM fan-out / rate limiting
+    numHypotheticals = Math.max(1, Math.min(numHypotheticals, 10));
+    // Use tree-sitter AST to detect if query is already code — skip HyDE if so
+    if (await looksLikeCodeAST(query)) {
+        const embedding = await getEmbedding(query);
+        return { embedding, hypotheticals: [], used: false };
+    }
+    try {
+        // Generate hypothetical code snippets in parallel
+        const promises = Array.from({ length: numHypotheticals }, () => callLLM(HYDE_PROMPT.replace('{query}', query), {
+            maxTokens: 500,
+            systemPrompt: HYDE_SYSTEM,
+            timeout: 15000,
+        }));
+        const responses = await Promise.allSettled(promises);
+        const hypotheticals = responses
+            .filter((r) => r.status === 'fulfilled')
+            .map((r) => r.value.trim())
+            .filter((code) => code.length > 20); // Filter empty/tiny responses
+        if (hypotheticals.length === 0) {
+            logWarn('hyde', 'All hypothetical generations failed, falling back to query embedding');
+            const embedding = await getEmbedding(query);
+            return { embedding, hypotheticals: [], used: false };
+        }
+        // Embed only the hypothetical code snippets — not the original NL query.
+        // Mixing the query back in pulls the averaged vector toward natural-language
+        // space and weakens the code-space bridge HyDE is meant to create.
+        const allTexts = hypotheticals;
+        const embeddings = await getEmbeddings(allTexts);
+        // Average all embeddings
+        const dim = embeddings[0].length;
+        const averaged = new Array(dim).fill(0);
+        for (const emb of embeddings) {
+            for (let i = 0; i < dim; i++) {
+                averaged[i] += emb[i];
+            }
+        }
+        for (let i = 0; i < dim; i++) {
+            averaged[i] /= embeddings.length;
+        }
+        // Normalize
+        const norm = Math.sqrt(averaged.reduce((sum, v) => sum + v * v, 0));
+        if (norm > 0) {
+            for (let i = 0; i < dim; i++) {
+                averaged[i] /= norm;
+            }
+        }
+        logInfo('hyde', `Generated ${hypotheticals.length} hypothetical embeddings for query`);
+        return { embedding: averaged, hypotheticals, used: true };
+    }
+    catch (error) {
+        logWarn('hyde', 'HyDE generation failed, falling back to query embedding', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        const embedding = await getEmbedding(query);
+        return { embedding, hypotheticals: [], used: false };
+    }
+}
+// Languages to try when checking if a query is code
+const CODE_DETECT_LANGUAGES = ['typescript', 'python', 'go', 'rust'];
+/**
+ * Detect if a query is code using tree-sitter AST parsing.
+ *
+ * Tries parsing the query as several common languages. If any language
+ * produces a clean AST (no ERROR nodes), the query is code.
+ * Falls back to false if tree-sitter is unavailable.
+ */
+async function looksLikeCodeAST(query) {
+    // Short strings (< 3 chars) cannot form valid code constructs
+    if (query.length < 3)
+        return false;
+    for (const lang of CODE_DETECT_LANGUAGES) {
+        try {
+            const tree = await parseCode(query, lang);
+            if (!tree)
+                continue;
+            try {
+                const root = tree.rootNode;
+                // Clean parse with at least one named child = definitely code
+                if (!root.hasError && root.namedChildCount > 0) {
+                    return true;
+                }
+                // Mostly clean: few errors relative to named children = likely code
+                if (root.namedChildCount >= 2) {
+                    const errorNodes = root.descendantsOfType('ERROR');
+                    if (errorNodes.length / root.namedChildCount < 0.3) {
+                        return true;
+                    }
+                }
+            }
+            finally {
+                tree.delete();
+            }
+        }
+        catch (err) {
+            logWarn('hyde', `Tree-sitter parse failed for ${lang}`, {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=hyde.js.map

package/dist/lib/search/hyde.js.map

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