gitnexus 1.4.7 → 1.4.9

package/dist/core/embeddings/http-client.js

@@ -0,0 +1,179 @@
+/**
+ * HTTP Embedding Client
+ *
+ * Shared fetch+retry logic for OpenAI-compatible /v1/embeddings endpoints.
+ * Imported by both the core embedder (batch) and MCP embedder (query).
+ */
+const HTTP_TIMEOUT_MS = 30_000;
+const HTTP_MAX_RETRIES = 2;
+const HTTP_RETRY_BACKOFF_MS = 1_000;
+const HTTP_BATCH_SIZE = 64;
+const DEFAULT_DIMS = 384;
+/**
+ * Build config from the current process.env snapshot.
+ * Returns null when GITNEXUS_EMBEDDING_URL + GITNEXUS_EMBEDDING_MODEL are unset.
+ * Not cached — env vars are read fresh so late configuration takes effect.
+ */
+const readConfig = () => {
+    const baseUrl = process.env.GITNEXUS_EMBEDDING_URL;
+    const model = process.env.GITNEXUS_EMBEDDING_MODEL;
+    if (!baseUrl || !model)
+        return null;
+    const rawDims = process.env.GITNEXUS_EMBEDDING_DIMS;
+    let dimensions;
+    if (rawDims !== undefined) {
+        const parsed = parseInt(rawDims, 10);
+        if (Number.isNaN(parsed) || parsed <= 0) {
+            throw new Error(`GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${rawDims}"`);
+        }
+        dimensions = parsed;
+    }
+    return {
+        baseUrl: baseUrl.replace(/\/+$/, ''),
+        model,
+        apiKey: process.env.GITNEXUS_EMBEDDING_API_KEY ?? 'unused',
+        dimensions,
+    };
+};
+/**
+ * Check whether HTTP embedding mode is active (env vars are set).
+ */
+export const isHttpMode = () => readConfig() !== null;
+/**
+ * Return the configured embedding dimensions for HTTP mode, or undefined
+ * if HTTP mode is not active or no explicit dimensions are set.
+ */
+export const getHttpDimensions = () => readConfig()?.dimensions;
+/**
+ * Return a safe representation of a URL for error messages.
+ * Strips query string (may contain tokens) and userinfo.
+ */
+const safeUrl = (url) => {
+    try {
+        const u = new URL(url);
+        return `${u.protocol}//${u.host}${u.pathname}`;
+    }
+    catch {
+        return '<invalid-url>';
+    }
+};
+/**
+ * Send a single batch of texts to the embedding endpoint with retry.
+ *
+ * @param url - Full endpoint URL (e.g. https://host/v1/embeddings)
+ * @param batch - Texts to embed
+ * @param model - Model name for the request body
+ * @param apiKey - Bearer token (only used in Authorization header)
+ * @param batchIndex - Logical batch number (for error context)
+ * @param attempt - Current retry attempt (internal)
+ */
+const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, attempt = 0) => {
+    let resp;
+    try {
+        resp = await fetch(url, {
+            method: 'POST',
+            signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({ input: batch, model }),
+        });
+    }
+    catch (err) {
+        // Timeouts should not be retried — the server is unresponsive.
+        // AbortSignal.timeout() throws DOMException with name 'TimeoutError'.
+        const isTimeout = err instanceof DOMException && err.name === 'TimeoutError';
+        if (isTimeout) {
+            throw new Error(`Embedding request timed out after ${HTTP_TIMEOUT_MS}ms (${safeUrl(url)}, batch ${batchIndex})`);
+        }
+        // DNS, connection errors — retry with backoff
+        if (attempt < HTTP_MAX_RETRIES) {
+            const delay = HTTP_RETRY_BACKOFF_MS * (attempt + 1);
+            await new Promise(r => setTimeout(r, delay));
+            return httpEmbedBatch(url, batch, model, apiKey, batchIndex, attempt + 1);
+        }
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`Embedding request failed (${safeUrl(url)}, batch ${batchIndex}): ${reason}`);
+    }
+    if (!resp.ok) {
+        const status = resp.status;
+        if ((status === 429 || status >= 500) && attempt < HTTP_MAX_RETRIES) {
+            const delay = HTTP_RETRY_BACKOFF_MS * (attempt + 1);
+            await new Promise(r => setTimeout(r, delay));
+            return httpEmbedBatch(url, batch, model, apiKey, batchIndex, attempt + 1);
+        }
+        throw new Error(`Embedding endpoint returned ${status} (${safeUrl(url)}, batch ${batchIndex})`);
+    }
+    const data = (await resp.json());
+    return data.data;
+};
+/**
+ * Embed texts via the HTTP backend, splitting into batches.
+ * Reads config from env vars on every call.
+ *
+ * @param texts - Array of texts to embed
+ * @returns Array of Float32Array embedding vectors
+ */
+export const httpEmbed = async (texts) => {
+    if (texts.length === 0)
+        return [];
+    const config = readConfig();
+    if (!config)
+        throw new Error('HTTP embedding not configured');
+    const url = `${config.baseUrl}/embeddings`;
+    const allVectors = [];
+    for (let i = 0; i < texts.length; i += HTTP_BATCH_SIZE) {
+        const batch = texts.slice(i, i + HTTP_BATCH_SIZE);
+        const batchIndex = Math.floor(i / HTTP_BATCH_SIZE);
+        const items = await httpEmbedBatch(url, batch, config.model, config.apiKey, batchIndex);
+        if (items.length !== batch.length) {
+            throw new Error(`Embedding endpoint returned ${items.length} vectors for ${batch.length} texts ` +
+                `(${safeUrl(url)}, batch ${batchIndex})`);
+        }
+        for (const item of items) {
+            const vec = new Float32Array(item.embedding);
+            // Fail fast on dimension mismatch rather than inserting bad vectors
+            // into the FLOAT[N] column which would cause a cryptic Kuzu error.
+            const expected = config.dimensions ?? DEFAULT_DIMS;
+            if (vec.length !== expected) {
+                const hint = config.dimensions
+                    ? 'Update GITNEXUS_EMBEDDING_DIMS to match your model output.'
+                    : `Set GITNEXUS_EMBEDDING_DIMS=${vec.length} to match your model output.`;
+                throw new Error(`Embedding dimension mismatch: endpoint returned ${vec.length}d vector, ` +
+                    `but expected ${expected}d. ${hint}`);
+            }
+            allVectors.push(vec);
+        }
+    }
+    return allVectors;
+};
+/**
+ * Embed a single query text via the HTTP backend.
+ * Convenience for MCP search where only one vector is needed.
+ *
+ * @param text - Query text to embed
+ * @returns Embedding vector as number array
+ */
+export const httpEmbedQuery = async (text) => {
+    const config = readConfig();
+    if (!config)
+        throw new Error('HTTP embedding not configured');
+    const url = `${config.baseUrl}/embeddings`;
+    const items = await httpEmbedBatch(url, [text], config.model, config.apiKey);
+    if (!items.length) {
+        throw new Error(`Embedding endpoint returned empty response (${safeUrl(url)})`);
+    }
+    const embedding = items[0].embedding;
+    // Same dimension checks as httpEmbed — catch mismatches before they
+    // reach the Kuzu FLOAT[N] cast in search queries.
+    const expected = config.dimensions ?? DEFAULT_DIMS;
+    if (embedding.length !== expected) {
+        const hint = config.dimensions
+            ? 'Update GITNEXUS_EMBEDDING_DIMS to match your model output.'
+            : `Set GITNEXUS_EMBEDDING_DIMS=${embedding.length} to match your model output.`;
+        throw new Error(`Embedding dimension mismatch: endpoint returned ${embedding.length}d vector, ` +
+            `but expected ${expected}d. ${hint}`);
+    }
+    return embedding;
+};

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

@@ -4,6 +4,7 @@
  * Re-exports for the embedding pipeline system.
  */
 export * from './types.js';
+export * from './http-client.js';
 export * from './embedder.js';
 export * from './text-generator.js';
 export * from './embedding-pipeline.js';

package/dist/core/embeddings/index.js

@@ -4,6 +4,7 @@
  * Re-exports for the embedding pipeline system.
  */
 export * from './types.js';
+export * from './http-client.js';
 export * from './embedder.js';
 export * from './text-generator.js';
 export * from './embedding-pipeline.js';

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

@@ -34,7 +34,7 @@ export interface EmbeddingProgress {
  * Configuration for the embedding pipeline
  */
 export interface EmbeddingConfig {
-    /** Model identifier for transformers.js */
+    /** Model identifier for transformers.js (local) or the HTTP endpoint model name */
     modelId: string;
     /** Number of nodes to embed in each batch */
     batchSize: number;

package/dist/core/graph/graph.js

@@ -27,7 +27,14 @@ export const createKnowledgeGraph = () => {
         return true;
     };
     /**
-     * Remove all nodes (and their relationships) belonging to a file
+     * Remove a single relationship by id.
+     * Returns true if the relationship existed and was removed, false otherwise.
+     */
+    const removeRelationship = (relationshipId) => {
+        return relationshipMap.delete(relationshipId);
+    };
+    /**
+     * Remove all nodes (and their relationships) belonging to a file.
      */
     const removeNodesByFile = (filePath) => {
         let removed = 0;
@@ -62,5 +69,6 @@ export const createKnowledgeGraph = () => {
         addRelationship,
         removeNode,
         removeNodesByFile,
+        removeRelationship,
     };
 };

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

@@ -1,4 +1,4 @@
-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';
+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' | 'Section' | 'Route' | 'Tool';
 import { SupportedLanguages } from '../../config/supported-languages.js';
 export type NodeProperties = {
     name: string;
@@ -23,9 +23,17 @@ export type NodeProperties = {
     entryPointScore?: number;
     entryPointReason?: string;
     parameterCount?: number;
+    level?: number;
     returnType?: string;
+    declaredType?: string;
+    visibility?: string;
+    isStatic?: boolean;
+    isReadonly?: boolean;
+    responseKeys?: string[];
+    errorKeys?: string[];
+    middleware?: 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 type RelationshipType = 'CONTAINS' | 'CALLS' | 'INHERITS' | 'OVERRIDES' | 'IMPORTS' | 'USES' | 'DEFINES' | 'DECORATES' | 'IMPLEMENTS' | 'EXTENDS' | 'HAS_METHOD' | 'HAS_PROPERTY' | 'ACCESSES' | 'MEMBER_OF' | 'STEP_IN_PROCESS' | 'HANDLES_ROUTE' | 'FETCHES' | 'HANDLES_TOOL' | 'ENTRY_POINT_OF' | 'WRAPS' | 'QUERIES';
 export interface GraphNode {
     id: string;
     label: NodeLabel;
@@ -63,4 +71,5 @@ export interface KnowledgeGraph {
     addRelationship: (relationship: GraphRelationship) => void;
     removeNode: (nodeId: string) => boolean;
     removeNodesByFile: (filePath: string) => number;
+    removeRelationship: (relationshipId: string) => boolean;
 }

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

@@ -1,11 +1,58 @@
 import { KnowledgeGraph } from '../graph/types.js';
 import { ASTCache } from './ast-cache.js';
+import type { SymbolTable } from './symbol-table.js';
 import type { ResolutionContext } from './resolution-context.js';
-import type { ExtractedCall, ExtractedAssignment, ExtractedHeritage, ExtractedRoute, FileConstructorBindings } from './workers/parse-worker.js';
+import type { ExtractedCall, ExtractedAssignment, ExtractedHeritage, ExtractedRoute, ExtractedFetchCall, FileConstructorBindings } from './workers/parse-worker.js';
+/** Per-file resolved type bindings for exported symbols.
+ *  Populated during call processing, consumed by Phase 14 re-resolution pass. */
+export type ExportedTypeMap = Map<string, Map<string, string>>;
+/** Build a map of imported callee names → return types for cross-file call-result binding.
+ *  Consulted ONLY when SymbolTable has no unambiguous local match (local-first principle). */
+export declare function buildImportedReturnTypes(filePath: string, namedImportMap: ReadonlyMap<string, ReadonlyMap<string, {
+    sourcePath: string;
+    exportedName: string;
+}>>, symbolTable: {
+    lookupExactFull(filePath: string, name: string): {
+        returnType?: string;
+    } | undefined;
+}): ReadonlyMap<string, string>;
+/** Build cross-file RAW return types for imported callables.
+ *  Unlike buildImportedReturnTypes (which stores extractReturnTypeName output),
+ *  this stores the raw declared return type string (e.g., 'User[]', 'List<User>').
+ *  Used by lookupRawReturnType for for-loop element extraction via extractElementTypeFromString. */
+export declare function buildImportedRawReturnTypes(filePath: string, namedImportMap: ReadonlyMap<string, ReadonlyMap<string, {
+    sourcePath: string;
+    exportedName: string;
+}>>, symbolTable: {
+    lookupExactFull(filePath: string, name: string): {
+        returnType?: string;
+    } | undefined;
+}): ReadonlyMap<string, string>;
+/** Build ExportedTypeMap from graph nodes — used for worker path where TypeEnv
+ *  is not available in the main thread. Collects returnType/declaredType from
+ *  exported symbols that have callables with known return types. */
+export declare function buildExportedTypeMapFromGraph(graph: KnowledgeGraph, symbolTable: SymbolTable): ExportedTypeMap;
+/** Seed cross-file receiver types into pre-extracted call records.
+ *  Fills missing receiverTypeName for single-hop imported variables
+ *  using ExportedTypeMap + namedImportMap — zero disk I/O, zero AST re-parsing.
+ *  Mutates calls in-place. Runs BEFORE processCallsFromExtracted. */
+export declare function seedCrossFileReceiverTypes(calls: ExtractedCall[], namedImportMap: ReadonlyMap<string, ReadonlyMap<string, {
+    sourcePath: string;
+    exportedName: string;
+}>>, exportedTypeMap: ReadonlyMap<string, ReadonlyMap<string, string>>): {
+    enrichedCount: number;
+};
 export declare const processCalls: (graph: KnowledgeGraph, files: {
     path: string;
     content: string;
-}[], astCache: ASTCache, ctx: ResolutionContext, onProgress?: (current: number, total: number) => void) => Promise<ExtractedHeritage[]>;
+}[], astCache: ASTCache, ctx: ResolutionContext, onProgress?: (current: number, total: number) => void, exportedTypeMap?: ExportedTypeMap, 
+/** Phase 14: pre-resolved cross-file bindings to seed into buildTypeEnv. Keyed by filePath → Map<localName, typeName>. */
+importedBindingsMap?: ReadonlyMap<string, ReadonlyMap<string, string>>, 
+/** Phase 14 E3: cross-file return types for imported callables. Keyed by filePath → Map<calleeName, returnType>.
+ *  Consulted ONLY when SymbolTable has no unambiguous match (local-first principle). */
+importedReturnTypesMap?: ReadonlyMap<string, ReadonlyMap<string, string>>, 
+/** Phase 14 E3: cross-file RAW return types for for-loop element extraction. Keyed by filePath → Map<calleeName, rawReturnType>. */
+importedRawReturnTypesMap?: ReadonlyMap<string, ReadonlyMap<string, string>>) => Promise<ExtractedHeritage[]>;
 /**
  * Fast path: resolve pre-extracted call sites from workers.
  * No AST parsing — workers already extracted calledName + sourceId.
@@ -21,3 +68,20 @@ export declare const processAssignmentsFromExtracted: (graph: KnowledgeGraph, as
  * 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>;
+export declare const extractConsumerAccessedKeys: (content: string) => string[];
+/**
+ * Create FETCHES edges from extracted fetch() calls to matching Route nodes.
+ * When consumerContents is provided, extracts property access patterns from
+ * consumer files and encodes them in the edge reason field.
+ */
+export declare const processNextjsFetchRoutes: (graph: KnowledgeGraph, fetchCalls: ExtractedFetchCall[], routeRegistry: Map<string, string>, // routeURL → handlerFilePath
+consumerContents?: Map<string, string>) => void;
+/**
+ * Extract fetch() calls from source files (sequential path).
+ * Workers handle this via tree-sitter captures in parse-worker; this function
+ * provides the same extraction for the sequential fallback path.
+ */
+export declare const extractFetchCallsFromFiles: (files: {
+    path: string;
+    content: string;
+}[], astCache: ASTCache) => Promise<ExtractedFetchCall[]>;