@zuvia-software-solutions/code-mapper 1.4.0

package/dist/core/embeddings/text-generator.js

@@ -0,0 +1,159 @@
+// code-mapper/src/core/embeddings/text-generator.ts
+/**
+ * @file text-generator.ts
+ * @description Pure functions to generate embedding text from code nodes,
+ * combining node metadata with code snippets for semantic matching
+ */
+import { DEFAULT_EMBEDDING_CONFIG } from './types.js';
+/** Extract filename from a file path */
+const getFileName = (filePath) => {
+    const parts = filePath.split('/');
+    return parts[parts.length - 1] || filePath;
+};
+/** Extract directory path from a file path */
+const getDirectory = (filePath) => {
+    const parts = filePath.split('/');
+    parts.pop();
+    return parts.join('/') || '';
+};
+/** Truncate content to max length, preserving word boundaries */
+const truncateContent = (content, maxLength) => {
+    if (content.length <= maxLength) {
+        return content;
+    }
+    // Find last space before maxLength to avoid cutting words
+    const truncated = content.slice(0, maxLength);
+    const lastSpace = truncated.lastIndexOf(' ');
+    if (lastSpace > maxLength * 0.8) {
+        return truncated.slice(0, lastSpace) + '...';
+    }
+    return truncated + '...';
+};
+/** Clean code content — remove excessive whitespace while preserving structure */
+const cleanContent = (content) => {
+    return content
+        // Normalize line endings
+        .replace(/\r\n/g, '\n')
+        // Remove excessive blank lines (more than 2)
+        .replace(/\n{3,}/g, '\n\n')
+        // Trim each line
+        .split('\n')
+        .map(line => line.trimEnd())
+        .join('\n')
+        .trim();
+};
+/** Generate embedding text for a Function node */
+const generateFunctionText = (node, maxSnippetLength) => {
+    const parts = [
+        `Function: ${node.name}`,
+        `File: ${getFileName(node.filePath)}`,
+    ];
+    const dir = getDirectory(node.filePath);
+    if (dir) {
+        parts.push(`Directory: ${dir}`);
+    }
+    if (node.content) {
+        const cleanedContent = cleanContent(node.content);
+        const snippet = truncateContent(cleanedContent, maxSnippetLength);
+        parts.push('', snippet);
+    }
+    return parts.join('\n');
+};
+/** Generate embedding text for a Class node */
+const generateClassText = (node, maxSnippetLength) => {
+    const parts = [
+        `Class: ${node.name}`,
+        `File: ${getFileName(node.filePath)}`,
+    ];
+    const dir = getDirectory(node.filePath);
+    if (dir) {
+        parts.push(`Directory: ${dir}`);
+    }
+    if (node.content) {
+        const cleanedContent = cleanContent(node.content);
+        const snippet = truncateContent(cleanedContent, maxSnippetLength);
+        parts.push('', snippet);
+    }
+    return parts.join('\n');
+};
+/** Generate embedding text for a Method node */
+const generateMethodText = (node, maxSnippetLength) => {
+    const parts = [
+        `Method: ${node.name}`,
+        `File: ${getFileName(node.filePath)}`,
+    ];
+    const dir = getDirectory(node.filePath);
+    if (dir) {
+        parts.push(`Directory: ${dir}`);
+    }
+    if (node.content) {
+        const cleanedContent = cleanContent(node.content);
+        const snippet = truncateContent(cleanedContent, maxSnippetLength);
+        parts.push('', snippet);
+    }
+    return parts.join('\n');
+};
+/** Generate embedding text for an Interface node */
+const generateInterfaceText = (node, maxSnippetLength) => {
+    const parts = [
+        `Interface: ${node.name}`,
+        `File: ${getFileName(node.filePath)}`,
+    ];
+    const dir = getDirectory(node.filePath);
+    if (dir) {
+        parts.push(`Directory: ${dir}`);
+    }
+    if (node.content) {
+        const cleanedContent = cleanContent(node.content);
+        const snippet = truncateContent(cleanedContent, maxSnippetLength);
+        parts.push('', snippet);
+    }
+    return parts.join('\n');
+};
+/** Generate embedding text for a File node (uses shorter snippet) */
+const generateFileText = (node, maxSnippetLength) => {
+    const parts = [
+        `File: ${node.name}`,
+        `Path: ${node.filePath}`,
+    ];
+    if (node.content) {
+        const cleanedContent = cleanContent(node.content);
+        // Files can be very long — cap at 300 chars
+        const snippet = truncateContent(cleanedContent, Math.min(maxSnippetLength, 300));
+        parts.push('', snippet);
+    }
+    return parts.join('\n');
+};
+/**
+ * Generate embedding text for any embeddable node (dispatches by label)
+ * @param node - The node to generate text for
+ * @param config - Optional configuration for max snippet length
+ * @returns Text suitable for embedding
+ */
+export const generateEmbeddingText = (node, config = {}) => {
+    const maxSnippetLength = config.maxSnippetLength ?? DEFAULT_EMBEDDING_CONFIG.maxSnippetLength;
+    switch (node.label) {
+        case 'Function':
+            return generateFunctionText(node, maxSnippetLength);
+        case 'Class':
+            return generateClassText(node, maxSnippetLength);
+        case 'Method':
+            return generateMethodText(node, maxSnippetLength);
+        case 'Interface':
+            return generateInterfaceText(node, maxSnippetLength);
+        case 'File':
+            return generateFileText(node, maxSnippetLength);
+        default:
+            // Fallback for any other embeddable type
+            return `${node.label}: ${node.name}\nPath: ${node.filePath}`;
+    }
+};
+/**
+ * Generate embedding texts for a batch of nodes
+ * @param nodes - Nodes to generate text for
+ * @param config - Optional configuration
+ * @returns Texts in the same order as input nodes
+ */
+export const generateBatchEmbeddingTexts = (nodes, config = {}) => {
+    return nodes.map(node => generateEmbeddingText(node, config));
+};

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

@@ -0,0 +1,60 @@
+/** @file types.ts @description Type definitions for embedding generation and semantic search */
+export declare const EMBEDDABLE_LABELS: readonly ["Function", "Class", "Method", "Interface"];
+export type EmbeddableLabel = typeof EMBEDDABLE_LABELS[number];
+/** Check if a label is embeddable */
+export declare const isEmbeddableLabel: (label: string) => label is EmbeddableLabel;
+/** Embedding pipeline lifecycle phases */
+export type EmbeddingPhase = 'idle' | 'loading-model' | 'embedding' | 'indexing' | 'ready' | 'error';
+/** Progress state emitted during embedding pipeline execution */
+export interface EmbeddingProgress {
+    phase: EmbeddingPhase;
+    percent: number;
+    modelDownloadPercent?: number;
+    nodesProcessed?: number;
+    totalNodes?: number;
+    currentBatch?: number;
+    totalBatches?: number;
+    error?: string;
+}
+/** Configuration for the embedding pipeline */
+export interface EmbeddingConfig {
+    /** Model identifier for transformers.js */
+    modelId: string;
+    /** Nodes to embed per batch */
+    batchSize: number;
+    /** Embedding vector dimensions */
+    dimensions: number;
+    /** Inference device — 'auto' tries GPU first (DirectML on Windows, CUDA on Linux), falls back to CPU */
+    device: 'auto' | 'dml' | 'cuda' | 'cpu' | 'wasm';
+    /** Max characters of code snippet to include */
+    maxSnippetLength: number;
+}
+export declare const DEFAULT_EMBEDDING_CONFIG: EmbeddingConfig;
+/** Result from a semantic vector search */
+export interface SemanticSearchResult {
+    nodeId: string;
+    name: string;
+    label: string;
+    filePath: string;
+    distance: number;
+    startLine?: number;
+    endLine?: number;
+}
+/** Minimal node data for embedding (from LadybugDB query) */
+export interface EmbeddableNode {
+    id: string;
+    name: string;
+    label: string;
+    filePath: string;
+    content: string;
+    startLine?: number;
+    endLine?: number;
+}
+/** Model download progress from transformers.js */
+export interface ModelProgress {
+    status: 'initiate' | 'download' | 'progress' | 'done' | 'ready';
+    file?: string;
+    progress?: number;
+    loaded?: number;
+    total?: number;
+}

package/dist/core/embeddings/types.js

@@ -0,0 +1,23 @@
+// code-mapper/src/core/embeddings/types.ts
+/** @file types.ts @description Type definitions for embedding generation and semantic search */
+// Node labels eligible for semantic embedding
+// File nodes removed — their embeddings were low quality (import headers, license text)
+// and polluted semantic search. BM25 FTS already searches file content effectively.
+export const EMBEDDABLE_LABELS = [
+    'Function',
+    'Class',
+    'Method',
+    'Interface',
+];
+/** Check if a label is embeddable */
+export const isEmbeddableLabel = (label) => EMBEDDABLE_LABELS.includes(label);
+// Jina Code 1.5B MLX — 1.54B params on Apple Silicon Metal
+// Matryoshka truncation to 256 dims (trained at this dim, <1% quality loss vs 1536)
+// Task-specific prefixes: nl2code queries, code passages
+export const DEFAULT_EMBEDDING_CONFIG = {
+    modelId: 'jinaai/jina-code-embeddings-1.5b-mlx',
+    batchSize: 48,
+    dimensions: 256, // Matryoshka — 6x smaller vectors, 3x faster search vs 768
+    device: 'auto',
+    maxSnippetLength: 16000, // 32K token context — embed much more code for better understanding
+};

package/dist/core/graph/graph.d.ts

@@ -0,0 +1,4 @@
+/** @file graph.ts @description Factory for creating in-memory knowledge graphs backed by Maps for O(1) lookups */
+import { KnowledgeGraph } from './types.js';
+/** Create a new empty KnowledgeGraph instance */
+export declare const createKnowledgeGraph: () => KnowledgeGraph;

package/dist/core/graph/graph.js

@@ -0,0 +1,65 @@
+// code-mapper/src/core/graph/graph.ts
+/** @file graph.ts @description Factory for creating in-memory knowledge graphs backed by Maps for O(1) lookups */
+/** Create a new empty KnowledgeGraph instance */
+export const createKnowledgeGraph = () => {
+    const nodeMap = new Map();
+    const relationshipMap = new Map();
+    const addNode = (node) => {
+        if (!nodeMap.has(node.id)) {
+            nodeMap.set(node.id, node);
+        }
+    };
+    const addRelationship = (relationship) => {
+        if (!relationshipMap.has(relationship.id)) {
+            relationshipMap.set(relationship.id, relationship);
+        }
+    };
+    /** Remove a single node and all relationships involving it */
+    const removeNode = (nodeId) => {
+        if (!nodeMap.has(nodeId))
+            return false;
+        nodeMap.delete(nodeId);
+        // Remove all relationships referencing this node
+        for (const [relId, rel] of relationshipMap) {
+            if (rel.sourceId === nodeId || rel.targetId === nodeId) {
+                relationshipMap.delete(relId);
+            }
+        }
+        return true;
+    };
+    /** Remove all nodes (and their relationships) belonging to a file */
+    const removeNodesByFile = (filePath) => {
+        let removed = 0;
+        for (const [nodeId, node] of nodeMap) {
+            if (node.properties?.filePath === filePath) {
+                removeNode(nodeId);
+                removed++;
+            }
+        }
+        return removed;
+    };
+    return {
+        get nodes() {
+            return Array.from(nodeMap.values());
+        },
+        get relationships() {
+            return Array.from(relationshipMap.values());
+        },
+        iterNodes: () => nodeMap.values(),
+        iterRelationships: () => relationshipMap.values(),
+        forEachNode(fn) { nodeMap.forEach(fn); },
+        forEachRelationship(fn) { relationshipMap.forEach(fn); },
+        getNode: (id) => nodeMap.get(id),
+        // O(1) count getters
+        get nodeCount() {
+            return nodeMap.size;
+        },
+        get relationshipCount() {
+            return relationshipMap.size;
+        },
+        addNode,
+        addRelationship,
+        removeNode,
+        removeNodesByFile,
+    };
+};

package/dist/core/graph/types.d.ts

@@ -0,0 +1,69 @@
+/** @file types.ts @description Core type definitions for the knowledge graph: nodes, relationships, and the graph interface */
+export type NodeLabel = 'Project' | 'Package' | 'Module' | 'Folder' | 'File' | 'Class' | 'Function' | 'Method' | 'Variable' | 'Interface' | 'Enum' | 'Decorator' | 'Import' | 'Type' | 'CodeElement' | 'Community' | 'Process' | 'Struct' | 'Macro' | 'Typedef' | 'Union' | 'Namespace' | 'Trait' | 'Impl' | 'TypeAlias' | 'Const' | 'Static' | 'Property' | 'Record' | 'Delegate' | 'Annotation' | 'Constructor' | 'Template';
+import { SupportedLanguages } from '../../config/supported-languages.js';
+export type NodeProperties = {
+    name: string;
+    filePath: string;
+    startLine?: number;
+    endLine?: number;
+    language?: SupportedLanguages;
+    isExported?: boolean;
+    astFrameworkMultiplier?: number;
+    astFrameworkReason?: string;
+    heuristicLabel?: string;
+    cohesion?: number;
+    symbolCount?: number;
+    keywords?: string[];
+    description?: string;
+    enrichedBy?: 'heuristic' | 'llm';
+    processType?: 'intra_community' | 'cross_community';
+    stepCount?: number;
+    communities?: string[];
+    entryPointId?: string;
+    terminalId?: string;
+    entryPointScore?: number;
+    entryPointReason?: string;
+    parameterCount?: number;
+    returnType?: string;
+};
+export type RelationshipType = 'CONTAINS' | 'CALLS' | 'INHERITS' | 'OVERRIDES' | 'IMPORTS' | 'USES' | 'DEFINES' | 'DECORATES' | 'IMPLEMENTS' | 'EXTENDS' | 'HAS_METHOD' | 'MEMBER_OF' | 'STEP_IN_PROCESS' | 'DEPENDS_ON' | 'PROVIDES';
+export interface GraphNode {
+    id: string;
+    label: NodeLabel;
+    properties: NodeProperties;
+}
+export interface GraphRelationship {
+    id: string;
+    sourceId: string;
+    targetId: string;
+    type: RelationshipType;
+    /** Confidence score 0-1 (1.0 = certain, lower = uncertain) */
+    confidence: number;
+    /** Resolution reason: 'import-resolved', 'same-file', 'fuzzy-global', or empty for non-CALLS */
+    reason: string;
+    /** Step number for STEP_IN_PROCESS relationships (1-indexed) */
+    step?: number;
+    /** Source line number where the call occurs (for CALLS relationships) */
+    callLine?: number;
+}
+export interface KnowledgeGraph {
+    /** Returns a full array copy — prefer iterNodes() for iteration */
+    nodes: GraphNode[];
+    /** Returns a full array copy — prefer iterRelationships() for iteration */
+    relationships: GraphRelationship[];
+    /** Zero-copy iterator over nodes */
+    iterNodes: () => IterableIterator<GraphNode>;
+    /** Zero-copy iterator over relationships */
+    iterRelationships: () => IterableIterator<GraphRelationship>;
+    /** Zero-copy forEach — avoids iterator protocol overhead in hot loops */
+    forEachNode: (fn: (node: GraphNode) => void) => void;
+    forEachRelationship: (fn: (rel: GraphRelationship) => void) => void;
+    /** Lookup a single node by id — O(1) */
+    getNode: (id: string) => GraphNode | undefined;
+    nodeCount: number;
+    relationshipCount: number;
+    addNode: (node: GraphNode) => void;
+    addRelationship: (relationship: GraphRelationship) => void;
+    removeNode: (nodeId: string) => boolean;
+    removeNodesByFile: (filePath: string) => number;
+}

package/dist/core/graph/types.js

@@ -0,0 +1,3 @@
+// code-mapper/src/core/graph/types.ts
+/** @file types.ts @description Core type definitions for the knowledge graph: nodes, relationships, and the graph interface */
+export {};

package/dist/core/incremental/child-process.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @file child-process.ts
+ * @description Forked child process entry point for incremental DB updates. Opens
+ *   LadybugDB in READ-WRITE mode, deletes stale nodes for changed files, re-parses
+ *   them with tree-sitter, inserts new nodes/edges, resolves imports/calls/heritage,
+ *   and rebuilds FTS indexes. Communicates with the parent via structured IPC messages
+ */
+export {};