@duytransipher/gitnexus 1.4.6-sipher.0

package/dist/core/embeddings/text-generator.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Text Generator Module
+ *
+ * Pure functions to generate embedding text from code nodes.
+ * Combines node metadata with code snippets for semantic matching.
+ */
+import type { EmbeddableNode, EmbeddingConfig } from './types.js';
+/**
+ * Generate embedding text for any embeddable node
+ * Dispatches to the appropriate generator based on node label
+ *
+ * @param node - The node to generate text for
+ * @param config - Optional configuration for max snippet length
+ * @returns Text suitable for embedding
+ */
+export declare const generateEmbeddingText: (node: EmbeddableNode, config?: Partial<EmbeddingConfig>) => string;
+/**
+ * Generate embedding texts for a batch of nodes
+ *
+ * @param nodes - Array of nodes to generate text for
+ * @param config - Optional configuration
+ * @returns Array of texts in the same order as input nodes
+ */
+export declare const generateBatchEmbeddingTexts: (nodes: EmbeddableNode[], config?: Partial<EmbeddingConfig>) => string[];

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

@@ -0,0 +1,182 @@
+/**
+ * Text Generator Module
+ *
+ * Pure functions to generate embedding text from code nodes.
+ * Combines node metadata with code snippets for semantic matching.
+ */
+import { DEFAULT_EMBEDDING_CONFIG } from './types.js';
+/**
+ * Extract the filename from a file path
+ */
+const getFileName = (filePath) => {
+    const parts = filePath.split('/');
+    return parts[parts.length - 1] || filePath;
+};
+/**
+ * Extract the 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 for embedding
+ * Removes 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 file name and first N characters of content
+ */
+const generateFileText = (node, maxSnippetLength) => {
+    const parts = [
+        `File: ${node.name}`,
+        `Path: ${node.filePath}`,
+    ];
+    if (node.content) {
+        const cleanedContent = cleanContent(node.content);
+        // For files, use a shorter snippet since they can be very long
+        const snippet = truncateContent(cleanedContent, Math.min(maxSnippetLength, 300));
+        parts.push('', snippet);
+    }
+    return parts.join('\n');
+};
+/**
+ * Generate embedding text for any embeddable node
+ * Dispatches to the appropriate generator based on node 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 - Array of nodes to generate text for
+ * @param config - Optional configuration
+ * @returns Array of 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,87 @@
+/**
+ * Embedding Pipeline Types
+ *
+ * Type definitions for the embedding generation and semantic search system.
+ */
+/**
+ * Node labels that should be embedded for semantic search
+ * These are code elements that benefit from semantic matching
+ */
+export declare const EMBEDDABLE_LABELS: readonly ["Function", "Class", "Method", "Interface", "File"];
+export type EmbeddableLabel = typeof EMBEDDABLE_LABELS[number];
+/**
+ * Check if a label should be embedded
+ */
+export declare const isEmbeddableLabel: (label: string) => label is EmbeddableLabel;
+/**
+ * Embedding pipeline phases
+ */
+export type EmbeddingPhase = 'idle' | 'loading-model' | 'embedding' | 'indexing' | 'ready' | 'error';
+/**
+ * Progress information for the embedding pipeline
+ */
+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;
+    /** Number of nodes to embed in each batch */
+    batchSize: number;
+    /** Embedding vector dimensions */
+    dimensions: number;
+    /** Device to use for inference: 'auto' tries GPU first (DirectML on Windows, CUDA on Linux), falls back to CPU */
+    device: 'auto' | 'dml' | 'cuda' | 'cpu' | 'wasm';
+    /** Maximum characters of code snippet to include */
+    maxSnippetLength: number;
+}
+/**
+ * Default embedding configuration
+ * Uses snowflake-arctic-embed-xs for browser efficiency
+ * Tries WebGPU first (fast), user can choose WASM fallback if unavailable
+ */
+export declare const DEFAULT_EMBEDDING_CONFIG: EmbeddingConfig;
+/**
+ * Result from semantic search
+ */
+export interface SemanticSearchResult {
+    nodeId: string;
+    name: string;
+    label: string;
+    filePath: string;
+    distance: number;
+    startLine?: number;
+    endLine?: number;
+}
+/**
+ * Node data for embedding (minimal structure 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,32 @@
+/**
+ * Embedding Pipeline Types
+ *
+ * Type definitions for the embedding generation and semantic search system.
+ */
+/**
+ * Node labels that should be embedded for semantic search
+ * These are code elements that benefit from semantic matching
+ */
+export const EMBEDDABLE_LABELS = [
+    'Function',
+    'Class',
+    'Method',
+    'Interface',
+    'File',
+];
+/**
+ * Check if a label should be embedded
+ */
+export const isEmbeddableLabel = (label) => EMBEDDABLE_LABELS.includes(label);
+/**
+ * Default embedding configuration
+ * Uses snowflake-arctic-embed-xs for browser efficiency
+ * Tries WebGPU first (fast), user can choose WASM fallback if unavailable
+ */
+export const DEFAULT_EMBEDDING_CONFIG = {
+    modelId: 'Snowflake/snowflake-arctic-embed-xs',
+    batchSize: 16,
+    dimensions: 384,
+    device: 'auto',
+    maxSnippetLength: 500,
+};

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

@@ -0,0 +1,2 @@
+import { KnowledgeGraph } from './types.js';
+export declare const createKnowledgeGraph: () => KnowledgeGraph;

package/dist/core/graph/graph.js

@@ -0,0 +1,66 @@
+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 involving 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 - avoid creating arrays just for length
+        get nodeCount() {
+            return nodeMap.size;
+        },
+        get relationshipCount() {
+            return relationshipMap.size;
+        },
+        addNode,
+        addRelationship,
+        removeNode,
+        removeNodesByFile,
+    };
+};

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

@@ -0,0 +1,66 @@
+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' | 'HAS_PROPERTY' | 'ACCESSES' | 'MEMBER_OF' | 'STEP_IN_PROCESS';
+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 resolution) */
+    confidence: number;
+    /** Semantics are edge-type-dependent: CALLS uses resolution tier, ACCESSES uses 'read'/'write', OVERRIDES uses MRO reason */
+    reason: string;
+    /** Step number for STEP_IN_PROCESS relationships (1-indexed) */
+    step?: 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 @@
+export {};

package/dist/core/ingestion/ast-cache.d.ts

@@ -0,0 +1,11 @@
+import Parser from 'tree-sitter';
+export interface ASTCache {
+    get: (filePath: string) => Parser.Tree | undefined;
+    set: (filePath: string, tree: Parser.Tree) => void;
+    clear: () => void;
+    stats: () => {
+        size: number;
+        maxSize: number;
+    };
+}
+export declare const createASTCache: (maxSize?: number) => ASTCache;

package/dist/core/ingestion/ast-cache.js

@@ -0,0 +1,35 @@
+import { LRUCache } from 'lru-cache';
+export const createASTCache = (maxSize = 50) => {
+    const effectiveMax = Math.max(maxSize, 1);
+    // Initialize the cache with a 'dispose' handler
+    // This is the magic: When an item is evicted (dropped), this runs automatically.
+    const cache = new LRUCache({
+        max: effectiveMax,
+        dispose: (tree) => {
+            try {
+                // NOTE: web-tree-sitter has tree.delete(); native tree-sitter trees are GC-managed.
+                // Keep this try/catch so we don't crash on either runtime.
+                tree.delete?.();
+            }
+            catch (e) {
+                console.warn('Failed to delete tree from WASM memory', e);
+            }
+        }
+    });
+    return {
+        get: (filePath) => {
+            const tree = cache.get(filePath);
+            return tree; // Returns undefined if not found
+        },
+        set: (filePath, tree) => {
+            cache.set(filePath, tree);
+        },
+        clear: () => {
+            cache.clear();
+        },
+        stats: () => ({
+            size: cache.size,
+            maxSize: effectiveMax
+        })
+    };
+};

package/dist/core/ingestion/call-processor.d.ts

@@ -0,0 +1,23 @@
+import { KnowledgeGraph } from '../graph/types.js';
+import { ASTCache } from './ast-cache.js';
+import type { ResolutionContext } from './resolution-context.js';
+import type { ExtractedCall, ExtractedAssignment, ExtractedHeritage, ExtractedRoute, FileConstructorBindings } from './workers/parse-worker.js';
+export declare const processCalls: (graph: KnowledgeGraph, files: {
+    path: string;
+    content: string;
+}[], astCache: ASTCache, ctx: ResolutionContext, onProgress?: (current: number, total: number) => void) => Promise<ExtractedHeritage[]>;
+/**
+ * Fast path: resolve pre-extracted call sites from workers.
+ * No AST parsing — workers already extracted calledName + sourceId.
+ */
+export declare const processCallsFromExtracted: (graph: KnowledgeGraph, extractedCalls: ExtractedCall[], ctx: ResolutionContext, onProgress?: (current: number, total: number) => void, constructorBindings?: FileConstructorBindings[]) => Promise<void>;
+/**
+ * Resolve pre-extracted field write assignments to ACCESSES {reason: 'write'} edges.
+ * Accepts optional constructorBindings for return-type-aware receiver inference,
+ * mirroring processCallsFromExtracted's verified binding lookup.
+ */
+export declare const processAssignmentsFromExtracted: (graph: KnowledgeGraph, assignments: ExtractedAssignment[], ctx: ResolutionContext, constructorBindings?: FileConstructorBindings[]) => void;
+/**
+ * Resolve pre-extracted Laravel routes to CALLS edges from route files to controller methods.
+ */
+export declare const processRoutesFromExtracted: (graph: KnowledgeGraph, extractedRoutes: ExtractedRoute[], ctx: ResolutionContext, onProgress?: (current: number, total: number) => void) => Promise<void>;