arceus-s 1.6.4

package/dist/core/augmentation/engine.js

@@ -0,0 +1,272 @@
+/**
+ * Augmentation Engine
+ *
+ * Lightweight, fast-path enrichment of search patterns with knowledge graph context.
+ * Designed to be called from platform hooks (Claude Code PreToolUse, Cursor postToolUse)
+ * when an agent runs grep/glob/read/search.
+ *
+ * Performance target: <500ms cold start, <200ms warm.
+ *
+ * Design decisions:
+ * - Uses only BM25 search (no semantic/embedding) for speed
+ * - Clusters used internally for ranking, NEVER in output
+ * - Output is pure relationships: callers, callees, process participation
+ * - Graceful failure: any error → return empty string
+ */
+import path from 'path';
+import { listRegisteredRepos } from '../../storage/repo-manager.js';
+/**
+ * Find the best matching repo for a given working directory.
+ * Matches by checking if cwd is within the repo's path.
+ */
+async function findRepoForCwd(cwd) {
+    try {
+        const entries = await listRegisteredRepos({ validate: true });
+        const resolved = path.resolve(cwd);
+        // Normalize to lowercase on Windows (drive letters can differ: D: vs d:)
+        const isWindows = process.platform === 'win32';
+        const normalizedCwd = isWindows ? resolved.toLowerCase() : resolved;
+        const sep = path.sep;
+        // Find the LONGEST matching repo path (most specific match wins)
+        let bestMatch = null;
+        let bestLen = 0;
+        for (const entry of entries) {
+            const repoResolved = path.resolve(entry.path);
+            const normalizedRepo = isWindows ? repoResolved.toLowerCase() : repoResolved;
+            // Check if cwd is inside repo OR repo is inside cwd
+            // Must match at a path separator boundary to avoid false positives
+            // (e.g. /projects/arcv2 should NOT match /projects/arc)
+            let matched = false;
+            if (normalizedCwd === normalizedRepo) {
+                matched = true;
+            }
+            else if (normalizedCwd.startsWith(normalizedRepo + sep)) {
+                matched = true;
+            }
+            else if (normalizedRepo.startsWith(normalizedCwd + sep)) {
+                matched = true;
+            }
+            if (matched && normalizedRepo.length > bestLen) {
+                bestMatch = entry;
+                bestLen = normalizedRepo.length;
+            }
+        }
+        if (!bestMatch)
+            return null;
+        return {
+            name: bestMatch.name,
+            storagePath: bestMatch.storagePath,
+            lbugPath: path.join(bestMatch.storagePath, 'lbug'),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Augment a search pattern with knowledge graph context.
+ *
+ * 1. BM25 search for the pattern
+ * 2. For top matches, fetch callers/callees/processes
+ * 3. Rank by internal cluster cohesion (not exposed)
+ * 4. Format as structured text block
+ *
+ * Returns empty string on any error (graceful failure).
+ */
+export async function augment(pattern, cwd) {
+    if (!pattern || pattern.length < 3)
+        return '';
+    const patternFirstWord = pattern.trim().replace(/'/g, "''").split(/\s+/)[0];
+    if (!patternFirstWord || patternFirstWord.length < 2)
+        return '';
+    const workDir = cwd || process.cwd();
+    try {
+        const repo = await findRepoForCwd(workDir);
+        if (!repo)
+            return '';
+        // Lazy-load lbug adapter (skip unnecessary init)
+        const { initLbug, executeQuery, isLbugReady } = await import('../lbug/pool-adapter.js');
+        const { searchFTSFromLbug } = await import('../search/bm25-index.js');
+        const repoId = repo.name.toLowerCase();
+        // Init LadybugDB if not already
+        if (!isLbugReady(repoId)) {
+            await initLbug(repoId, repo.lbugPath);
+        }
+        // Step 1: BM25 search (fast, no embeddings)
+        const { results: bm25Results, ftsAvailable } = await searchFTSFromLbug(pattern, 10, repoId);
+        // Step 2: Map BM25 file results to symbols
+        const symbolMatches = [];
+        for (const result of bm25Results.slice(0, 5)) {
+            const escaped = result.filePath.replace(/'/g, "''");
+            try {
+                const symbols = await executeQuery(repoId, `
+          MATCH (n) WHERE n.filePath = '${escaped}'
+          AND n.name CONTAINS '${patternFirstWord}'
+          RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
+          LIMIT 3
+        `);
+                for (const sym of symbols) {
+                    symbolMatches.push({
+                        nodeId: sym.id || sym[0],
+                        name: sym.name || sym[1],
+                        type: sym.type || sym[2],
+                        filePath: sym.filePath || sym[3],
+                        score: result.score,
+                    });
+                }
+            }
+            catch {
+                /* skip */
+            }
+        }
+        // When FTS indexes are unavailable (read-only DB, first run before indexes are built),
+        // fall back to a direct name CONTAINS query so enrichment still works.
+        if (symbolMatches.length === 0 && !ftsAvailable) {
+            const fallbackRows = await executeQuery(repoId, `
+        MATCH (n)
+        WHERE n.name CONTAINS '${patternFirstWord}'
+        RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
+        LIMIT 5
+      `).catch(() => []);
+            for (const sym of fallbackRows) {
+                symbolMatches.push({
+                    nodeId: sym.id || sym[0],
+                    name: sym.name || sym[1],
+                    type: sym.type || sym[2],
+                    filePath: sym.filePath || sym[3],
+                    score: 1.0,
+                });
+            }
+        }
+        if (symbolMatches.length === 0)
+            return '';
+        // Step 3: Batch-fetch callers/callees/processes/cohesion for top matches
+        // Uses batched WHERE n.id IN [...] queries instead of per-symbol queries
+        const uniqueSymbols = symbolMatches
+            .slice(0, 5)
+            .filter((sym, i, arr) => arr.findIndex((s) => s.nodeId === sym.nodeId) === i);
+        if (uniqueSymbols.length === 0)
+            return '';
+        const idList = uniqueSymbols.map((s) => `'${s.nodeId.replace(/'/g, "''")}'`).join(', ');
+        // Batch fetch callers
+        const callersMap = new Map();
+        try {
+            const rows = await executeQuery(repoId, `
+        MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(n)
+        WHERE n.id IN [${idList}]
+        RETURN n.id AS targetId, caller.name AS name
+        LIMIT 15
+      `);
+            for (const r of rows) {
+                const tid = r.targetId || r[0];
+                const name = r.name || r[1];
+                if (tid && name) {
+                    if (!callersMap.has(tid))
+                        callersMap.set(tid, []);
+                    callersMap.get(tid).push(name);
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+        // Batch fetch callees
+        const calleesMap = new Map();
+        try {
+            const rows = await executeQuery(repoId, `
+        MATCH (n)-[:CodeRelation {type: 'CALLS'}]->(callee)
+        WHERE n.id IN [${idList}]
+        RETURN n.id AS sourceId, callee.name AS name
+        LIMIT 15
+      `);
+            for (const r of rows) {
+                const sid = r.sourceId || r[0];
+                const name = r.name || r[1];
+                if (sid && name) {
+                    if (!calleesMap.has(sid))
+                        calleesMap.set(sid, []);
+                    calleesMap.get(sid).push(name);
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+        // Batch fetch processes
+        const processesMap = new Map();
+        try {
+            const rows = await executeQuery(repoId, `
+        MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+        WHERE n.id IN [${idList}]
+        RETURN n.id AS nodeId, p.heuristicLabel AS label, r.step AS step, p.stepCount AS stepCount
+      `);
+            for (const r of rows) {
+                const nid = r.nodeId || r[0];
+                const label = r.label || r[1];
+                const step = r.step || r[2];
+                const stepCount = r.stepCount || r[3];
+                if (nid && label) {
+                    if (!processesMap.has(nid))
+                        processesMap.set(nid, []);
+                    processesMap.get(nid).push(`${label} (step ${step}/${stepCount})`);
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+        // Batch fetch cohesion
+        const cohesionMap = new Map();
+        try {
+            const rows = await executeQuery(repoId, `
+        MATCH (n)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+        WHERE n.id IN [${idList}]
+        RETURN n.id AS nodeId, c.cohesion AS cohesion
+      `);
+            for (const r of rows) {
+                const nid = r.nodeId || r[0];
+                const coh = r.cohesion ?? r[1] ?? 0;
+                if (nid)
+                    cohesionMap.set(nid, coh);
+            }
+        }
+        catch {
+            /* skip */
+        }
+        // Assemble enriched results
+        const enriched = [];
+        for (const sym of uniqueSymbols) {
+            enriched.push({
+                name: sym.name,
+                filePath: sym.filePath,
+                callers: (callersMap.get(sym.nodeId) || []).slice(0, 3),
+                callees: (calleesMap.get(sym.nodeId) || []).slice(0, 3),
+                processes: processesMap.get(sym.nodeId) || [],
+                cohesion: cohesionMap.get(sym.nodeId) || 0,
+            });
+        }
+        if (enriched.length === 0)
+            return '';
+        // Step 4: Rank by cohesion (internal signal) and format
+        enriched.sort((a, b) => b.cohesion - a.cohesion);
+        const lines = [`[Arceus] ${enriched.length} related symbols found:`, ''];
+        for (const item of enriched) {
+            lines.push(`${item.name} (${item.filePath})`);
+            if (item.callers.length > 0) {
+                lines.push(`  Called by: ${item.callers.join(', ')}`);
+            }
+            if (item.callees.length > 0) {
+                lines.push(`  Calls: ${item.callees.join(', ')}`);
+            }
+            if (item.processes.length > 0) {
+                lines.push(`  Flows: ${item.processes.join(', ')}`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n').trim();
+    }
+    catch {
+        // Graceful failure — never break the original tool
+        return '';
+    }
+}

package/dist/core/embedding-mode.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure derivation of the embedding-mode flags for `runFullAnalysis`.
+ *
+ * Lives in its own module (no native imports) so the branching contract can
+ * be unit-tested without spinning up LadybugDB, tree-sitter, or any of the
+ * other side-effecting dependencies pulled in by `run-analyze.ts`.
+ *
+ * Semantics:
+ *   --drop-embeddings         -> wipe (skip cache load entirely)
+ *   --embeddings              -> load cache, restore, then generate
+ *   --force + existing>0      -> load cache, restore, then generate (regenerate top-up)
+ *   (default) + existing>0    -> preserve only (load + restore, no generation)
+ *   any path with existing=0  -> no cache work, no preservation
+ */
+export interface EmbeddingModeInput {
+    force?: boolean;
+    embeddings?: boolean;
+    dropEmbeddings?: boolean;
+}
+export interface EmbeddingMode {
+    /** True when phase 4 should run the embedding generation pipeline. */
+    shouldGenerateEmbeddings: boolean;
+    /** True when we should load the cache to re-insert vectors after rebuild without generating new ones. */
+    preserveExistingEmbeddings: boolean;
+    /** True when `--force` upgraded a default analyze into a regeneration because the repo was already embedded. */
+    forceRegenerateEmbeddings: boolean;
+    /** True when we need to load cached embeddings from the existing DB before the rebuild. */
+    shouldLoadCache: boolean;
+}
+/** Default safety cap on graph node count for embedding generation. */
+export declare const DEFAULT_EMBEDDING_NODE_LIMIT = 50000;
+export interface EmbeddingCapDecision {
+    /** True when the node-count cap blocks generation for this graph. */
+    skipForCap: boolean;
+    /** True when the user explicitly disabled the cap (`--embeddings 0`). */
+    capDisabled: boolean;
+    /** Effective node limit applied (`0` means disabled). */
+    nodeLimit: number;
+}
+/**
+ * Decide whether the node-count safety cap blocks embedding generation.
+ *
+ * - `embeddingsNodeLimit === undefined` → use {@link DEFAULT_EMBEDDING_NODE_LIMIT}
+ * - `embeddingsNodeLimit === 0` → cap disabled, generation always proceeds
+ * - any positive integer → custom cap (skip if `nodeCount > limit`)
+ *
+ * Lives in `embedding-mode.ts` (not `run-analyze.ts`) so the branching
+ * contract is unit-testable without spinning up LadybugDB or the pipeline.
+ */
+export declare function deriveEmbeddingCap(nodeCount: number, embeddingsNodeLimit: number | undefined): EmbeddingCapDecision;
+export declare function deriveEmbeddingMode(options: EmbeddingModeInput, existingEmbeddingCount: number): EmbeddingMode;

package/dist/core/embedding-mode.js

@@ -0,0 +1,48 @@
+/**
+ * Pure derivation of the embedding-mode flags for `runFullAnalysis`.
+ *
+ * Lives in its own module (no native imports) so the branching contract can
+ * be unit-tested without spinning up LadybugDB, tree-sitter, or any of the
+ * other side-effecting dependencies pulled in by `run-analyze.ts`.
+ *
+ * Semantics:
+ *   --drop-embeddings         -> wipe (skip cache load entirely)
+ *   --embeddings              -> load cache, restore, then generate
+ *   --force + existing>0      -> load cache, restore, then generate (regenerate top-up)
+ *   (default) + existing>0    -> preserve only (load + restore, no generation)
+ *   any path with existing=0  -> no cache work, no preservation
+ */
+/** Default safety cap on graph node count for embedding generation. */
+export const DEFAULT_EMBEDDING_NODE_LIMIT = 50_000;
+/**
+ * Decide whether the node-count safety cap blocks embedding generation.
+ *
+ * - `embeddingsNodeLimit === undefined` → use {@link DEFAULT_EMBEDDING_NODE_LIMIT}
+ * - `embeddingsNodeLimit === 0` → cap disabled, generation always proceeds
+ * - any positive integer → custom cap (skip if `nodeCount > limit`)
+ *
+ * Lives in `embedding-mode.ts` (not `run-analyze.ts`) so the branching
+ * contract is unit-testable without spinning up LadybugDB or the pipeline.
+ */
+export function deriveEmbeddingCap(nodeCount, embeddingsNodeLimit) {
+    const nodeLimit = embeddingsNodeLimit ?? DEFAULT_EMBEDDING_NODE_LIMIT;
+    const capDisabled = nodeLimit === 0;
+    const skipForCap = !capDisabled && nodeCount > nodeLimit;
+    return { skipForCap, capDisabled, nodeLimit };
+}
+export function deriveEmbeddingMode(options, existingEmbeddingCount) {
+    const hasExisting = existingEmbeddingCount > 0;
+    const drop = !!options.dropEmbeddings;
+    const explicit = !!options.embeddings;
+    const force = !!options.force;
+    const forceRegenerateEmbeddings = force && !explicit && !drop && hasExisting;
+    const preserveExistingEmbeddings = !explicit && !drop && !forceRegenerateEmbeddings && hasExisting;
+    const shouldGenerateEmbeddings = explicit || forceRegenerateEmbeddings;
+    const shouldLoadCache = !drop && (shouldGenerateEmbeddings || preserveExistingEmbeddings);
+    return {
+        shouldGenerateEmbeddings,
+        preserveExistingEmbeddings,
+        forceRegenerateEmbeddings,
+        shouldLoadCache,
+    };
+}

package/dist/core/embeddings/ast-utils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared AST utilities for the embedding pipeline.
+ * Centralizes parser caching and tree-sitter node lookups
+ * used by both chunker.ts and structural-extractor.ts.
+ */
+/**
+ * Ensure parser is initialized and language is loaded, then parse content.
+ * Returns null if language is unavailable or parsing fails.
+ */
+export declare const ensureAndParse: (content: string, filePath: string) => Promise<any | null>;
+/**
+ * Find the first function/method-like declaration in a snippet AST.
+ * Used by the chunker when parsing node.content where absolute line
+ * numbers don't apply.
+ */
+export declare const findFunctionNode: (root: any) => any | null;
+/**
+ * Find the first class/struct/interface/enum-like declaration in an AST.
+ * Used when parsing node.content (a snippet, not a full file) where
+ * absolute line numbers don't apply.
+ */
+export declare const findDeclarationNode: (root: any) => any | null;

package/dist/core/embeddings/ast-utils.js

@@ -0,0 +1,106 @@
+/**
+ * Shared AST utilities for the embedding pipeline.
+ * Centralizes parser caching and tree-sitter node lookups
+ * used by both chunker.ts and structural-extractor.ts.
+ */
+import { getLanguageFromFilename } from '../../_shared/index.js';
+import { createParserForLanguage, isLanguageAvailable, resolveLanguageKey, } from '../tree-sitter/parser-loader.js';
+import { parseSourceSafe } from '../tree-sitter/safe-parse.js';
+const parserCache = new Map();
+/**
+ * Ensure parser is initialized and language is loaded, then parse content.
+ * Returns null if language is unavailable or parsing fails.
+ */
+export const ensureAndParse = async (content, filePath) => {
+    const language = getLanguageFromFilename(filePath);
+    if (!language)
+        return null;
+    if (!isLanguageAvailable(language))
+        return null;
+    const parserKey = resolveLanguageKey(language, filePath);
+    let parserInstance = parserCache.get(parserKey);
+    if (!parserInstance) {
+        parserInstance = await createParserForLanguage(language, filePath);
+        parserCache.set(parserKey, parserInstance);
+    }
+    return parseSourceSafe(parserInstance, content);
+};
+const FUNCTION_LIKE_TYPES = new Set([
+    'function_declaration',
+    'function_definition',
+    'method_declaration',
+    'method_definition',
+    'function_item',
+    'function_signature_item',
+    'arrow_function',
+    'function_expression',
+    'generator_function_declaration',
+    'generator_function',
+    'async_function_declaration',
+    'async_arrow_function',
+    'constructor_declaration',
+    'constructor_definition',
+    'compact_constructor_declaration',
+    'short_function_declaration',
+    'proc_declaration',
+    'func_literal',
+    'local_function_statement',
+    'anonymous_function',
+    'lambda_literal',
+    'init_declaration',
+    'deinit_declaration',
+]);
+/**
+ * Find the first function/method-like declaration in a snippet AST.
+ * Used by the chunker when parsing node.content where absolute line
+ * numbers don't apply.
+ */
+export const findFunctionNode = (root) => {
+    // Iterative DFS — avoids stack overflow on deeply nested ASTs.
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (FUNCTION_LIKE_TYPES.has(node.type))
+            return node;
+        for (let i = node.namedChildCount - 1; i >= 0; i--) {
+            const child = node.namedChild(i);
+            if (child)
+                stack.push(child);
+        }
+    }
+    return null;
+};
+/**
+ * Find the first class/struct/interface/enum-like declaration in an AST.
+ * Used when parsing node.content (a snippet, not a full file) where
+ * absolute line numbers don't apply.
+ */
+export const findDeclarationNode = (root) => {
+    const CLASS_LIKE_TYPES = new Set([
+        'class_declaration',
+        'class_definition',
+        'struct_declaration',
+        'struct_item',
+        'interface_declaration',
+        'interface_definition',
+        'enum_declaration',
+        'enum_item',
+        'type_declaration', // Go: type X struct
+        'declaration', // Go: type X struct
+        'object_declaration', // Kotlin: object
+        'impl_item', // Rust: impl
+    ]);
+    // Iterative DFS — avoids stack overflow on deeply nested ASTs.
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (CLASS_LIKE_TYPES.has(node.type))
+            return node;
+        for (let i = node.namedChildCount - 1; i >= 0; i--) {
+            const child = node.namedChild(i);
+            if (child)
+                stack.push(child);
+        }
+    }
+    return null;
+};

package/dist/core/embeddings/character-chunk.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Character-based sliding window chunking (pure, no tree-sitter dependency)
+ */
+export interface Chunk {
+    text: string;
+    chunkIndex: number;
+    startOffset: number;
+    endOffset: number;
+    startLine: number;
+    endLine: number;
+}
+export declare const characterChunk: (content: string, startLine: number, endLine: number, chunkSize?: number, overlap?: number) => Chunk[];

package/dist/core/embeddings/character-chunk.js

@@ -0,0 +1,43 @@
+/**
+ * Character-based sliding window chunking (pure, no tree-sitter dependency)
+ */
+import { buildLineIndex, resolveChunkLines } from './line-index.js';
+export const characterChunk = (content, startLine, endLine, chunkSize = 1200, overlap = 120) => {
+    if (content.length <= chunkSize) {
+        return [
+            {
+                text: content,
+                chunkIndex: 0,
+                startOffset: 0,
+                endOffset: content.length,
+                startLine,
+                endLine,
+            },
+        ];
+    }
+    const chunks = [];
+    let offset = 0;
+    const lineOffsets = buildLineIndex(content);
+    while (offset < content.length) {
+        const end = Math.min(offset + chunkSize, content.length);
+        const chunkText = content.slice(offset, end);
+        const lineRange = resolveChunkLines(lineOffsets, offset, end, startLine);
+        chunks.push({
+            text: chunkText,
+            chunkIndex: chunks.length,
+            startOffset: offset,
+            endOffset: end,
+            startLine: lineRange.startLine,
+            endLine: lineRange.endLine,
+        });
+        offset = end - overlap;
+        if (offset >= content.length)
+            break;
+        if (end >= content.length)
+            break;
+        if (offset <= (chunks.length > 1 ? end - chunkSize : 0)) {
+            offset = end;
+        }
+    }
+    return chunks;
+};

package/dist/core/embeddings/chunker.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Chunker Module
+ *
+ * Splits code nodes into chunks for embedding.
+ * - Function/Method: AST-aware chunking by statement boundaries
+ * - Other types: character-based sliding window fallback
+ * - Short content (≤ chunkSize): no chunking
+ */
+export { type Chunk, characterChunk } from './character-chunk.js';
+import type { Chunk } from './character-chunk.js';
+/**
+ * Main chunkNode function: dispatches by label
+ */
+export declare const chunkNode: (label: string, content: string, filePath: string, startLine: number, endLine: number, chunkSize?: number, overlap?: number) => Promise<Chunk[]>;