gitnexus 1.4.7 → 1.4.8

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/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';
 import { SupportedLanguages } from '../../config/supported-languages.js';
 export type NodeProperties = {
     name: string;
@@ -23,6 +23,7 @@ export type NodeProperties = {
     entryPointScore?: number;
     entryPointReason?: string;
     parameterCount?: number;
+    level?: 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';

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

@@ -0,0 +1,80 @@
+import type Parser from 'tree-sitter';
+import { SupportedLanguages } from '../../config/supported-languages.js';
+import type { NodeLabel } from '../graph/types.js';
+/** Tree-sitter AST node. Re-exported for use across ingestion modules. */
+export type SyntaxNode = Parser.SyntaxNode;
+/**
+ * Ordered list of definition capture keys for tree-sitter query matches.
+ * Used to extract the definition node from a capture map.
+ */
+export declare const DEFINITION_CAPTURE_KEYS: readonly ["definition.function", "definition.class", "definition.interface", "definition.method", "definition.struct", "definition.enum", "definition.namespace", "definition.module", "definition.trait", "definition.impl", "definition.type", "definition.const", "definition.static", "definition.typedef", "definition.macro", "definition.union", "definition.property", "definition.record", "definition.delegate", "definition.annotation", "definition.constructor", "definition.template"];
+/** Extract the definition node from a tree-sitter query capture map. */
+export declare const getDefinitionNodeFromCaptures: (captureMap: Record<string, any>) => SyntaxNode | null;
+/**
+ * Node types that represent function/method definitions across languages.
+ * Used to find the enclosing function for a call site.
+ */
+export declare const FUNCTION_NODE_TYPES: Set<string>;
+/**
+ * Node types for standard function declarations that need C/C++ declarator handling.
+ * Used by extractFunctionName to determine how to extract the function name.
+ */
+export declare const FUNCTION_DECLARATION_TYPES: Set<string>;
+/** AST node types that represent a class-like container (for HAS_METHOD edge extraction) */
+export declare const CLASS_CONTAINER_TYPES: Set<string>;
+export declare const CONTAINER_TYPE_TO_LABEL: Record<string, string>;
+/** Check if a Kotlin function_declaration capture is inside a class_body (i.e., a method).
+ *  Kotlin grammar uses function_declaration for both top-level functions and class methods.
+ *  Returns true when the captured definition node has a class_body ancestor. */
+export declare function isKotlinClassMethod(captureNode: {
+    parent?: any;
+} | null | undefined): boolean;
+/**
+ * C/C++: check if a Function capture is inside a class/struct body.
+ * If true, the function is already captured by @definition.method and should be skipped
+ * to prevent double-indexing in globalIndex.
+ */
+export declare function isCppDuplicateClassFunction(functionNode: {
+    parent?: any;
+} | null | undefined, nodeLabel: string, language: SupportedLanguages): boolean;
+/**
+ * Determine the graph node label from a tree-sitter capture map.
+ * Handles language-specific reclassification (C/C++ duplicate skipping, Kotlin Method promotion).
+ * Returns null if the capture should be skipped (import, call, C/C++ duplicate, missing name).
+ */
+export declare function getLabelFromCaptures(captureMap: Record<string, any>, language: SupportedLanguages): NodeLabel | null;
+/** Walk up AST to find enclosing class/struct/interface/impl, return its generateId or null.
+ *  For Go method_declaration nodes, extracts receiver type (e.g. `func (u *User) Save()` → User struct). */
+export declare const findEnclosingClassId: (node: any, filePath: string) => string | null;
+/**
+ * Find a child of `childType` within a sibling node of `siblingType`.
+ * Used for Kotlin AST traversal where visibility_modifier lives inside a modifiers sibling.
+ */
+export declare const findSiblingChild: (parent: any, siblingType: string, childType: string) => any | null;
+/**
+ * Extract function name and label from a function_definition or similar AST node.
+ * Handles C/C++ qualified_identifier (ClassName::MethodName) and other language patterns.
+ */
+export declare const extractFunctionName: (node: SyntaxNode) => {
+    funcName: string | null;
+    label: string;
+};
+export interface MethodSignature {
+    parameterCount: number | undefined;
+    /** Number of required (non-optional, non-default) parameters.
+     *  Only set when fewer than parameterCount — enables range-based arity filtering.
+     *  undefined means all parameters are required (or metadata unavailable). */
+    requiredParameterCount: number | undefined;
+    /** Per-parameter type names extracted via extractSimpleTypeName.
+     *  Only populated for languages with method overloading (Java, Kotlin, C#, C++).
+     *  undefined (not []) when no types are extractable — avoids empty array allocations. */
+    parameterTypes: string[] | undefined;
+    returnType: string | undefined;
+}
+/** Argument list node types shared between extractMethodSignature and countCallArguments. */
+export declare const CALL_ARGUMENT_LIST_TYPES: Set<string>;
+/**
+ * Extract parameter count and return type text from an AST method/function node.
+ * Works across languages by looking for common AST patterns.
+ */
+export declare const extractMethodSignature: (node: SyntaxNode | null | undefined) => MethodSignature;