gitnexus 1.4.5 → 1.4.6

package/dist/core/ingestion/type-extractors/shared.js

@@ -132,7 +132,7 @@ export function resolveIterableElementType(iterableName, node, scopeEnv, declara
 /** Known single-arg nullable wrapper types that unwrap to their inner type
  *  for receiver resolution. Optional<User> → "User", Option<User> → "User".
  *  Only nullable wrappers — NOT containers (List, Vec) or async wrappers (Promise, Future).
- *  See call-processor.ts WRAPPER_GENERICS for the full set used in return-type inference. */
+ *  See WRAPPER_GENERICS below for the full set used in return-type inference. */
 const NULLABLE_WRAPPER_TYPES = new Set([
     'Optional', // Java
     'Option', // Rust, Scala
@@ -569,3 +569,135 @@ export function extractElementTypeFromString(typeStr, pos = 'last') {
     }
     return undefined;
 }
+// ── Return type text helpers ─────────────────────────────────────────────
+// extractReturnTypeName works on raw return-type text already stored in
+// SymbolDefinition (e.g. "User", "Promise<User>", "User | null", "*User").
+// Extracts the base user-defined type name.
+/** Primitive / built-in types that should NOT produce a receiver binding. */
+const PRIMITIVE_TYPES = new Set([
+    'string', 'number', 'boolean', 'void', 'int', 'float', 'double', 'long',
+    'short', 'byte', 'char', 'bool', 'str', 'i8', 'i16', 'i32', 'i64',
+    'u8', 'u16', 'u32', 'u64', 'f32', 'f64', 'usize', 'isize',
+    'undefined', 'null', 'None', 'nil',
+]);
+/**
+ * Extract a simple type name from raw return-type text.
+ * Handles common patterns:
+ *   "User"                → "User"
+ *   "Promise<User>"       → "User"   (unwrap wrapper generics)
+ *   "Option<User>"        → "User"
+ *   "Result<User, Error>" → "User"   (first type arg)
+ *   "User | null"         → "User"   (strip nullable union)
+ *   "User?"               → "User"   (strip nullable suffix)
+ *   "*User"               → "User"   (Go pointer)
+ *   "&User"               → "User"   (Rust reference)
+ * Returns undefined for complex types or primitives.
+ */
+const WRAPPER_GENERICS = new Set([
+    'Promise', 'Observable', 'Future', 'CompletableFuture', 'Task', 'ValueTask', // async wrappers
+    'Option', 'Some', 'Optional', 'Maybe', // nullable wrappers
+    'Result', 'Either', // result wrappers
+    // Rust smart pointers (Deref to inner type)
+    'Rc', 'Arc', 'Weak', // pointer types
+    'MutexGuard', 'RwLockReadGuard', 'RwLockWriteGuard', // guard types
+    'Ref', 'RefMut', // RefCell guards
+    'Cow', // copy-on-write
+    // Containers (List, Array, Vec, Set, etc.) are intentionally excluded —
+    // methods are called on the container, not the element type.
+    // Non-wrapper generics return the base type (e.g., List) via the else branch.
+]);
+/**
+ * Extracts the first type argument from a comma-separated generic argument string,
+ * respecting nested angle brackets. For example:
+ *   "Result<User, Error>"  → "Result<User, Error>"  (no top-level comma)
+ *   "User, Error"          → "User"
+ *   "Map<K, V>, string"    → "Map<K, V>"
+ */
+function extractFirstGenericArg(args) {
+    let depth = 0;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '<')
+            depth++;
+        else if (args[i] === '>')
+            depth--;
+        else if (args[i] === ',' && depth === 0)
+            return args.slice(0, i).trim();
+    }
+    return args.trim();
+}
+/**
+ * Extract the first non-lifetime type argument from a generic argument string.
+ * Skips Rust lifetime parameters (e.g., `'a`, `'_`) to find the actual type.
+ *   "'_, User"       → "User"
+ *   "'a, User"       → "User"
+ *   "User, Error"    → "User"  (no lifetime — delegates to extractFirstGenericArg)
+ */
+function extractFirstTypeArg(args) {
+    let remaining = args;
+    while (remaining) {
+        const first = extractFirstGenericArg(remaining);
+        if (!first.startsWith("'"))
+            return first;
+        // Skip past this lifetime arg + the comma separator
+        const commaIdx = remaining.indexOf(',', first.length);
+        if (commaIdx < 0)
+            return first; // only lifetimes — fall through
+        remaining = remaining.slice(commaIdx + 1).trim();
+    }
+    return args.trim();
+}
+const MAX_RETURN_TYPE_INPUT_LENGTH = 2048;
+const MAX_RETURN_TYPE_LENGTH = 512;
+export const extractReturnTypeName = (raw, depth = 0) => {
+    if (depth > 10)
+        return undefined;
+    if (raw.length > MAX_RETURN_TYPE_INPUT_LENGTH)
+        return undefined;
+    let text = raw.trim();
+    if (!text)
+        return undefined;
+    // Strip pointer/reference prefixes: *User, &User, &mut User
+    text = text.replace(/^[&*]+\s*(mut\s+)?/, '');
+    // Strip nullable suffix: User?
+    text = text.replace(/\?$/, '');
+    // Handle union types: "User | null" → "User"
+    if (text.includes('|')) {
+        const parts = text.split('|').map(p => p.trim()).filter(p => p !== 'null' && p !== 'undefined' && p !== 'void' && p !== 'None' && p !== 'nil');
+        if (parts.length === 1)
+            text = parts[0];
+        else
+            return undefined; // genuine union — too complex
+    }
+    // Handle generics: Promise<User> → unwrap if wrapper, else take base
+    const genericMatch = text.match(/^(\w+)\s*<(.+)>$/);
+    if (genericMatch) {
+        const [, base, args] = genericMatch;
+        if (WRAPPER_GENERICS.has(base)) {
+            // Take the first non-lifetime type argument, using bracket-balanced splitting
+            // so that nested generics like Result<User, Error> are not split at the inner
+            // comma. Lifetime parameters (Rust 'a, '_) are skipped.
+            const firstArg = extractFirstTypeArg(args);
+            return extractReturnTypeName(firstArg, depth + 1);
+        }
+        // Non-wrapper generic: return the base type (e.g., Map<K,V> → Map)
+        return PRIMITIVE_TYPES.has(base.toLowerCase()) ? undefined : base;
+    }
+    // Bare wrapper type without generic argument (e.g. Task, Promise, Option)
+    // should not produce a binding — these are meaningless without a type parameter
+    if (WRAPPER_GENERICS.has(text))
+        return undefined;
+    // Handle qualified names: models.User → User, Models::User → User, \App\Models\User → User
+    if (text.includes('::') || text.includes('.') || text.includes('\\')) {
+        text = text.split(/::|[.\\]/).pop();
+    }
+    // Final check: skip primitives
+    if (PRIMITIVE_TYPES.has(text) || PRIMITIVE_TYPES.has(text.toLowerCase()))
+        return undefined;
+    // Must start with uppercase (class/type convention) or be a valid identifier
+    if (!/^[A-Z_]\w*$/.test(text))
+        return undefined;
+    // If the final extracted type name is too long, reject it
+    if (text.length > MAX_RETURN_TYPE_LENGTH)
+        return undefined;
+    return text;
+};

package/dist/core/ingestion/type-extractors/types.d.ts

@@ -23,17 +23,48 @@ export type ConstructorBindingScanner = (node: SyntaxNode) => {
  *  Used for languages where return types are expressed in comments (e.g. YARD @return [Type])
  *  rather than in AST fields. Returns undefined if no return type can be determined. */
 export type ReturnTypeExtractor = (node: SyntaxNode) => string | undefined;
-/** Extracts loop variable type binding from a for-each statement.
- *  All parameters are required (aligned with PatternBindingExtractor convention)
- *  to prevent new extractors from silently ignoring declarationTypeNodes/scope. */
-export type ForLoopExtractor = (node: SyntaxNode, scopeEnv: Map<string, string>, declarationTypeNodes: ReadonlyMap<string, SyntaxNode>, scope: string) => void;
-/** Extracts a plain-identifier assignment for Tier 2 propagation.
- *  For `const b = a`, returns { lhs: 'b', rhs: 'a' } when the LHS has no resolved type.
- *  Returns undefined if the node is not a plain identifier assignment. */
-export type PendingAssignmentExtractor = (node: SyntaxNode, scopeEnv: ReadonlyMap<string, string>) => {
+/** Narrow lookup interface for resolving a callee name → return type name.
+ *  Backed by SymbolTable.lookupFuzzyCallable; passed via ForLoopExtractorContext.
+ *  Conservative: returns undefined when the callee is ambiguous (0 or 2+ matches). */
+export interface ReturnTypeLookup {
+    /** Processed type name after stripping wrappers (e.g., 'User' from 'Promise<User>').
+     *  Use for call-result variable bindings (`const b = foo()`). */
+    lookupReturnType(callee: string): string | undefined;
+    /** Raw return type as declared in the symbol (e.g., '[]User', 'List<User>').
+     *  Use for iterable-element extraction (`for v := range foo()`). */
+    lookupRawReturnType(callee: string): string | undefined;
+}
+/** Context object passed to ForLoopExtractor.
+ *  Groups the four parameters that were previously positional. */
+export interface ForLoopExtractorContext {
+    /** Mutable type-env for the current scope — extractor writes bindings here */
+    scopeEnv: Map<string, string>;
+    /** Maps `scope\0varName` to the declaration's type annotation AST node */
+    declarationTypeNodes: ReadonlyMap<string, SyntaxNode>;
+    /** Current scope key, e.g. `"process@42"` */
+    scope: string;
+    /** Resolves a callee name to its declared return type (undefined = unknown/ambiguous) */
+    returnTypeLookup: ReturnTypeLookup;
+}
+/** Extracts loop variable type binding from a for-each statement. */
+export type ForLoopExtractor = (node: SyntaxNode, ctx: ForLoopExtractorContext) => void;
+/** Discriminated union for pending Tier-2 propagation items.
+ *  - `copy`       — `const b = a` (identifier alias, propagate a's type to b)
+ *  - `callResult` — `const b = foo()` (bind b to foo's declared return type) */
+export type PendingAssignment = {
+    kind: 'copy';
     lhs: string;
     rhs: string;
-} | undefined;
+} | {
+    kind: 'callResult';
+    lhs: string;
+    callee: string;
+};
+/** Extracts a pending assignment for Tier 2 propagation.
+ *  Returns a PendingAssignment when the RHS is a bare identifier (`copy`) or a
+ *  call expression (`callResult`) and the LHS has no resolved type yet.
+ *  Returns undefined if the node is not a matching assignment. */
+export type PendingAssignmentExtractor = (node: SyntaxNode, scopeEnv: ReadonlyMap<string, string>) => PendingAssignment | undefined;
 /** Extracts a typed variable binding from a pattern-matching construct.
  *  Returns { varName, typeName } for patterns that introduce NEW variables.
  *  Examples: `if let Some(user) = opt` (Rust), `x instanceof User user` (Java).
@@ -82,9 +113,10 @@ export interface LanguageTypeConfig {
     extractReturnType?: ReturnTypeExtractor;
     /** Extract loop variable → type binding from a for-each AST node. */
     extractForLoopBinding?: ForLoopExtractor;
-    /** Extract plain-identifier assignment (e.g. `const b = a`) for Tier 2 chain propagation.
-     *  Called on declaration/assignment nodes; returns {lhs, rhs} when the RHS is a bare identifier
-     *  and the LHS has no resolved type yet. Language-specific because AST shapes differ widely. */
+    /** Extract pending assignment for Tier 2 propagation.
+     *  Called on declaration/assignment nodes; returns a PendingAssignment when the RHS
+     *  is a bare identifier (copy) or call expression (callResult) and the LHS has no
+     *  resolved type yet. Language-specific because AST shapes differ widely. */
     extractPendingAssignment?: PendingAssignmentExtractor;
     /** Extract a typed variable binding from a pattern-matching construct.
      *  Called on every AST node; returns { varName, typeName } when the node introduces a new

package/dist/core/ingestion/type-extractors/typescript.js

@@ -345,7 +345,7 @@ const findTsIterableElementType = (iterableName, startNode, pos = 'last') => {
  *   3. AST walk — walks up to the enclosing function's parameters to read User[] annotations directly
  * Only handles `for...of`; `for...in` produces string keys, not element types.
  */
-const extractForLoopBinding = (node, scopeEnv, declarationTypeNodes, scope) => {
+const extractForLoopBinding = (node, { scopeEnv, declarationTypeNodes, scope, returnTypeLookup }) => {
     if (node.type !== 'for_in_statement')
         return;
     // Confirm this is `for...of`, not `for...in`, by scanning unnamed children for the keyword text.
@@ -359,10 +359,11 @@ const extractForLoopBinding = (node, scopeEnv, declarationTypeNodes, scope) => {
     }
     if (!isForOf)
         return;
-    // The iterable is the `right` field — may be identifier or call_expression.
+    // The iterable is the `right` field — may be identifier, member_expression, or call_expression.
     const rightNode = node.childForFieldName('right');
     let iterableName;
     let methodName;
+    let callExprElementType;
     if (rightNode?.type === 'identifier') {
         iterableName = rightNode.text;
     }
@@ -374,6 +375,7 @@ const extractForLoopBinding = (node, scopeEnv, declarationTypeNodes, scope) => {
     else if (rightNode?.type === 'call_expression') {
         // entries.values() → call_expression > function: member_expression > object + property
         // this.repos.values() → nested member_expression: extract property from inner member
+        // getUsers() → call_expression > function: identifier (Phase 7.3 — return-type path)
         const fn = rightNode.childForFieldName('function');
         if (fn?.type === 'member_expression') {
             const obj = fn.childForFieldName('object');
@@ -390,13 +392,25 @@ const extractForLoopBinding = (node, scopeEnv, declarationTypeNodes, scope) => {
             if (prop?.type === 'property_identifier')
                 methodName = prop.text;
         }
+        else if (fn?.type === 'identifier') {
+            // Direct function call: for (const user of getUsers())
+            const rawReturn = returnTypeLookup.lookupRawReturnType(fn.text);
+            if (rawReturn)
+                callExprElementType = extractElementTypeFromString(rawReturn);
+        }
     }
-    if (!iterableName)
+    if (!iterableName && !callExprElementType)
         return;
-    // Look up the container's base type name for descriptor-aware resolution
-    const containerTypeName = scopeEnv.get(iterableName);
-    const typeArgPos = methodToTypeArgPosition(methodName, containerTypeName);
-    const elementType = resolveIterableElementType(iterableName, node, scopeEnv, declarationTypeNodes, scope, extractTsElementTypeFromAnnotation, findTsIterableElementType, typeArgPos);
+    let elementType;
+    if (callExprElementType) {
+        elementType = callExprElementType;
+    }
+    else {
+        // Look up the container's base type name for descriptor-aware resolution
+        const containerTypeName = scopeEnv.get(iterableName);
+        const typeArgPos = methodToTypeArgPosition(methodName, containerTypeName);
+        elementType = resolveIterableElementType(iterableName, node, scopeEnv, declarationTypeNodes, scope, extractTsElementTypeFromAnnotation, findTsIterableElementType, typeArgPos);
+    }
     if (!elementType)
         return;
     // The loop variable is the `left` field.
@@ -444,7 +458,7 @@ const extractPendingAssignment = (node, scopeEnv) => {
         if (scopeEnv.has(lhs))
             continue;
         if (valueNode.type === 'identifier')
-            return { lhs, rhs: valueNode.text };
+            return { kind: 'copy', lhs, rhs: valueNode.text };
     }
     return undefined;
 };

package/dist/core/ingestion/workers/parse-worker.js

@@ -953,10 +953,13 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                 parameterCount = sig.parameterCount;
                 returnType = sig.returnType;
                 // Language-specific return type fallback (e.g. Ruby YARD @return [Type])
-                if (!returnType && definitionNode) {
+                // Also upgrades uninformative AST types like PHP `array` with PHPDoc `@return User[]`
+                if ((!returnType || returnType === 'array' || returnType === 'iterable') && definitionNode) {
                     const tc = typeConfigs[language];
                     if (tc?.extractReturnType) {
-                        returnType = tc.extractReturnType(definitionNode);
+                        const docReturn = tc.extractReturnType(definitionNode);
+                        if (docReturn)
+                            returnType = docReturn;
                     }
                 }
             }

package/dist/mcp/local/local-backend.d.ts

@@ -144,6 +144,7 @@ export declare class LocalBackend {
      */
     private rename;
     private impact;
+    private _impactImpl;
     /**
      * Query clusters (communities) directly from graph.
      * Used by getClustersResource — avoids legacy overview() dispatch.

package/dist/mcp/local/local-backend.js

@@ -37,7 +37,7 @@ export const VALID_NODE_LABELS = new Set([
     'Record', 'Delegate', 'Annotation', 'Constructor', 'Template', 'Module',
 ]);
 /** Valid relation types for impact analysis filtering */
-export const VALID_RELATION_TYPES = new Set(['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS']);
+export const VALID_RELATION_TYPES = new Set(['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'HAS_METHOD', 'OVERRIDES']);
 /** Regex to detect write operations in user-supplied Cypher queries */
 export const CYPHER_WRITE_RE = /\b(CREATE|DELETE|SET|MERGE|REMOVE|DROP|ALTER|COPY|DETACH)\b/i;
 /** Check if a Cypher query contains write operations */
@@ -1189,6 +1189,22 @@ export class LocalBackend {
         };
     }
     async impact(repo, params) {
+        try {
+            return await this._impactImpl(repo, params);
+        }
+        catch (err) {
+            // Return structured error instead of crashing (#321)
+            return {
+                error: (err instanceof Error ? err.message : String(err)) || 'Impact analysis failed',
+                target: { name: params.target },
+                direction: params.direction,
+                impactedCount: 0,
+                risk: 'UNKNOWN',
+                suggestion: 'The graph query failed — try gitnexus context <symbol> as a fallback',
+            };
+        }
+    }
+    async _impactImpl(repo, params) {
         await this.ensureInitialized(repo.id);
         const { target, direction } = params;
         const maxDepth = params.maxDepth || 3;
@@ -1213,6 +1229,7 @@ export class LocalBackend {
         const impacted = [];
         const visited = new Set([symId]);
         let frontier = [symId];
+        let traversalComplete = true;
         for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
             const nextFrontier = [];
             // Batch frontier nodes into a single Cypher query per depth level
@@ -1244,6 +1261,10 @@ export class LocalBackend {
             }
             catch (e) {
                 logQueryError('impact:depth-traversal', e);
+                // Break out of depth loop on query failure but return partial results
+                // collected so far, rather than silently swallowing the error (#321)
+                traversalComplete = false;
+                break;
             }
             frontier = nextFrontier;
         }
@@ -1321,6 +1342,7 @@ export class LocalBackend {
             direction,
             impactedCount: impacted.length,
             risk,
+            ...(!traversalComplete && { partial: true }),
             summary: {
                 direct: directCount,
                 processes_affected: processCount,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -45,7 +45,8 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "prepare": "npm run build",
-    "postinstall": "node scripts/patch-tree-sitter-swift.cjs"
+    "postinstall": "node scripts/patch-tree-sitter-swift.cjs",
+    "prepack": "npm run build && chmod +x dist/cli/index.js"
   },
   "dependencies": {
     "@huggingface/transformers": "^3.0.0",