gitnexus 1.6.3-rc.2 → 1.6.3-rc.21

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

@@ -18,6 +18,7 @@ import { listRegisteredRepos, cleanupOldKuzuFiles, } from '../../storage/repo-ma
 import { GroupService } from '../../core/group/service.js';
 import { collectBestChunks } from '../../core/embeddings/types.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
+import { PhaseTimer } from '../../core/search/phase-timer.js';
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';
 /**
@@ -134,6 +135,25 @@ function logQueryError(context, err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`GitNexus [${context}]: ${msg}`);
 }
+/**
+ * Structured per-query latency log for production aggregation (#553).
+ *
+ * Emitted on stderr — NOT stdout — because the MCP stdio transport uses
+ * stdout exclusively for JSON-RPC responses (#324), and the CLI e2e test
+ * `tool output goes to stdout via fd 1` asserts that stdout parses cleanly
+ * as JSON. Any `console.log` from inside a tool handler would corrupt the
+ * protocol. Matches the existing `logQueryError` convention above, which
+ * uses stderr for the same reason.
+ *
+ * The `GitNexus [query:timing] …` prefix keeps lines greppable; the
+ * `phases` payload is JSON so log-scraping pipelines can parse it
+ * without custom format knowledge.
+ */
+function logQueryTiming(query, phases) {
+    const totalMs = phases.wall ?? Object.values(phases).reduce((a, b) => a + b, 0);
+    const truncated = query.length > 80 ? `${query.slice(0, 80)}…` : query;
+    console.error(`GitNexus [query:timing] query=${JSON.stringify(truncated)} totalMs=${totalMs} phases=${JSON.stringify(phases)}`);
+}
 export class LocalBackend {
     repos = new Map();
     contextCache = new Map();
@@ -259,12 +279,20 @@ export class LocalBackend {
         if (this.repos.size === 0) {
             throw new Error('No indexed repositories. Run: gitnexus analyze');
         }
+        // Build a disambiguated "Available: …" list (#829). When two handles
+        // share a name, annotate each colliding label with its path so the
+        // caller can actually pick the right one. Single-name entries render
+        // identically to pre-#829 output.
+        const nameCounts = new Map();
+        for (const h of this.repos.values()) {
+            const key = h.name.toLowerCase();
+            nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);
+        }
+        const labels = [...this.repos.values()].map((h) => (nameCounts.get(h.name.toLowerCase()) ?? 0) > 1 ? `${h.name} (${h.repoPath})` : h.name);
         if (repoParam) {
-            const names = [...this.repos.values()].map((h) => h.name);
-            throw new Error(`Repository "${repoParam}" not found. Available: ${names.join(', ')}`);
+            throw new Error(`Repository "${repoParam}" not found. Available: ${labels.join(', ')}`);
         }
-        const names = [...this.repos.values()].map((h) => h.name);
-        throw new Error(`Multiple repositories indexed. Specify which one with the "repo" parameter. Available: ${names.join(', ')}`);
+        throw new Error(`Multiple repositories indexed. Specify which one with the "repo" parameter. Available: ${labels.join(', ')}`);
     }
     /**
      * Try to resolve a repo from the in-memory cache. Returns null on miss.
@@ -449,15 +477,26 @@ export class LocalBackend {
         const maxSymbolsPerProcess = params.max_symbols || 10;
         const includeContent = params.include_content ?? false;
         const searchQuery = params.query.trim();
-        // Step 1: Run hybrid search to get matching symbols
+        // Per-phase timing instrumentation (#553). Records wall time for each
+        // observable sub-step of the search pipeline so production latency can
+        // be aggregated offline for Pareto analysis and bottleneck detection.
+        // Overhead is <0.1 ms per phase; the timer is passive and never alters
+        // query behaviour.
+        const timer = new PhaseTimer();
+        const wallStart = performance.now();
+        // Step 1: Run hybrid search to get matching symbols. BM25 and vector
+        // search run concurrently via Promise.all — use `timer.time()` for
+        // each so both get independent wall-time records without fighting
+        // over a single `current` phase slot.
         const searchLimit = processLimit * maxSymbolsPerProcess; // fetch enough raw results
         const [bm25SearchResult, semanticResults] = await Promise.all([
-            this.bm25Search(repo, searchQuery, searchLimit),
-            this.semanticSearch(repo, searchQuery, searchLimit),
+            timer.time('bm25', this.bm25Search(repo, searchQuery, searchLimit)),
+            timer.time('vector', this.semanticSearch(repo, searchQuery, searchLimit)),
         ]);
         const bm25Results = bm25SearchResult.results;
         const ftsUsed = bm25SearchResult.ftsUsed;
         // Merge via reciprocal rank fusion
+        timer.start('merge');
         const scoreMap = new Map();
         for (let i = 0; i < bm25Results.length; i++) {
             const result = bm25Results[i];
@@ -486,7 +525,9 @@ export class LocalBackend {
         const merged = Array.from(scoreMap.entries())
             .sort((a, b) => b[1].score - a[1].score)
             .slice(0, searchLimit);
+        timer.stop(); // merge
         // Step 2: For each match with a nodeId, trace to process(es)
+        timer.start('symbol_lookup');
         const processMap = new Map();
         const definitions = []; // standalone symbols not in any process
         for (const [_, item] of merged) {
@@ -590,7 +631,9 @@ export class LocalBackend {
                 }
             }
         }
+        timer.stop(); // symbol_lookup
         // Step 3: Rank processes by aggregate score + internal cohesion boost
+        timer.start('ranking');
         const rankedProcesses = Array.from(processMap.values())
             .map((p) => ({
             ...p,
@@ -598,7 +641,9 @@ export class LocalBackend {
         }))
             .sort((a, b) => b.priority - a.priority)
             .slice(0, processLimit);
+        timer.stop(); // ranking
         // Step 4: Build response
+        timer.start('formatting');
         const processes = rankedProcesses.map((p) => ({
             id: p.id,
             summary: p.heuristicLabel || p.label,
@@ -619,10 +664,18 @@ export class LocalBackend {
             seen.add(s.id);
             return true;
         });
+        timer.stop(); // formatting
+        // End-to-end wall time — deliberately a separate mark so callers can
+        // compare sum(phases) vs wall to see how much Promise.all concurrency
+        // saved. Must come before summary() so it's included.
+        timer.mark('wall', performance.now() - wallStart);
+        const timing = timer.summary();
+        logQueryTiming(searchQuery, timing);
         return {
             processes,
             process_symbols: dedupedSymbols,
             definitions: definitions.slice(0, 20), // cap standalone definitions
+            timing,
             ...(!ftsUsed && {
                 warning: 'FTS extension unavailable - keyword search degraded. Run: gitnexus analyze --force to rebuild indexes.',
             }),
@@ -1447,7 +1500,14 @@ export class LocalBackend {
         }
         let diffOutput;
         try {
-            diffOutput = execFileSync('git', diffArgs, { cwd: repo.repoPath, encoding: 'utf-8' });
+            // maxBuffer raised from Node's 1MB default to 256MB to avoid ENOBUFS on
+            // repos with large unstaged/untracked diffs (e.g. unignored build folders).
+            // See issue: spawnSync git ENOBUFS in detect_changes(scope="unstaged").
+            diffOutput = execFileSync('git', diffArgs, {
+                cwd: repo.repoPath,
+                encoding: 'utf-8',
+                maxBuffer: 256 * 1024 * 1024,
+            });
         }
         catch (err) {
             return { error: `Git diff failed: ${err.message}` };
@@ -1662,6 +1722,8 @@ export class LocalBackend {
                 cwd: repo.repoPath,
                 encoding: 'utf-8',
                 timeout: 5000,
+                // Avoid ENOBUFS on large repos: rg -l can list many files.
+                maxBuffer: 256 * 1024 * 1024,
             });
             const files = output
                 .trim()

package/dist/storage/git.d.ts

@@ -16,6 +16,31 @@ export declare const getGitRoot: (fromPath: string) => string | null;
  * @returns `true` when `.git` is present, `false` otherwise.
  */
 export declare const hasGitDir: (dirPath: string) => boolean;
+/**
+ * Read `remote.origin.url` from a git repository, or `null` if not a
+ * git repo, has no `origin` remote, or git is unavailable.
+ *
+ * Used by the registry-name inference path (#979) to recover a
+ * meaningful repo name when `path.basename(repoPath)` is generic
+ * (e.g. monorepo subprojects, git worktrees, Gas-Town-style
+ * `<rig>/refinery/rig/` layouts).
+ */
+export declare const getRemoteOriginUrl: (repoPath: string) => string | null;
+/**
+ * Parse a repository name out of a git remote URL. Handles the common
+ * SSH (`git@host:owner/repo.git`), HTTPS (`https://host/owner/repo.git`),
+ * `git://`, `ssh://`, and `file://` shapes. Returns `null` for empty /
+ * unparseable input.
+ *
+ * The heuristic: strip a trailing `.git` and trailing slashes, then
+ * take the segment after the last `/` or `:`.
+ */
+export declare const parseRepoNameFromUrl: (url: string | null | undefined) => string | null;
+/**
+ * Convenience wrapper: derive a registry-friendly name from the repo's
+ * `origin` remote, or `null` when it cannot be inferred.
+ */
+export declare const getInferredRepoName: (repoPath: string) => string | null;
 export interface DiffHunk {
     startLine: number;
     endLine: number;

package/dist/storage/git.js

@@ -52,6 +52,58 @@ export const hasGitDir = (dirPath) => {
         return false;
     }
 };
+/**
+ * Read `remote.origin.url` from a git repository, or `null` if not a
+ * git repo, has no `origin` remote, or git is unavailable.
+ *
+ * Used by the registry-name inference path (#979) to recover a
+ * meaningful repo name when `path.basename(repoPath)` is generic
+ * (e.g. monorepo subprojects, git worktrees, Gas-Town-style
+ * `<rig>/refinery/rig/` layouts).
+ */
+export const getRemoteOriginUrl = (repoPath) => {
+    try {
+        const url = execSync('git config --get remote.origin.url', {
+            cwd: repoPath,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .toString()
+            .trim();
+        return url || null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Parse a repository name out of a git remote URL. Handles the common
+ * SSH (`git@host:owner/repo.git`), HTTPS (`https://host/owner/repo.git`),
+ * `git://`, `ssh://`, and `file://` shapes. Returns `null` for empty /
+ * unparseable input.
+ *
+ * The heuristic: strip a trailing `.git` and trailing slashes, then
+ * take the segment after the last `/` or `:`.
+ */
+export const parseRepoNameFromUrl = (url) => {
+    if (!url)
+        return null;
+    const trimmed = url.trim();
+    if (!trimmed)
+        return null;
+    // Strip `.git` suffix (case-insensitive) and any trailing slashes.
+    const withoutSuffix = trimmed.replace(/\.git\/*$/i, '').replace(/\/+$/, '');
+    // Last path segment, splitting on either `/` or `:` (covers SSH form).
+    const m = withoutSuffix.match(/[/:]([^/:]+)$/);
+    const candidate = m ? m[1] : withoutSuffix;
+    return candidate || null;
+};
+/**
+ * Convenience wrapper: derive a registry-friendly name from the repo's
+ * `origin` remote, or `null` when it cannot be inferred.
+ */
+export const getInferredRepoName = (repoPath) => {
+    return parseRepoNameFromUrl(getRemoteOriginUrl(repoPath));
+};
 /**
  * Parse unified diff output (with -U0) into per-file hunk ranges.
  * Extracts the new-file line ranges from @@ hunk headers.

package/dist/storage/repo-manager.d.ts

@@ -102,11 +102,80 @@ export declare const getGlobalRegistryPath: () => string;
  * Read the global registry. Returns empty array if not found.
  */
 export declare const readRegistry: () => Promise<RegistryEntry[]>;
+/**
+ * Options for {@link registerRepo}. All optional — callers without any
+ * disambiguation requirement can keep calling `registerRepo(path, meta)`
+ * unchanged.
+ */
+export interface RegisterRepoOptions {
+    /**
+     * User-provided alias from `analyze --name <alias>` (#829). Overrides
+     * the default basename-derived registry `name`. Persisted — subsequent
+     * re-analyses of the same path without `--name` preserve the alias.
+     */
+    name?: string;
+    /**
+     * Allow two DIFFERENT repo paths to register under the same alias
+     * (#829). Mapped from the `--allow-duplicate-name` CLI flag.
+     *
+     * Scope: this flag governs cross-path alias sharing only — one repo
+     * path always has exactly one registry entry (and therefore exactly
+     * one alias). Re-analyzing the same path with `--name Y` overwrites
+     * a previous `--name X`; it does NOT create a second entry or a
+     * second alias for the same path (see the upsert-by-resolved-path
+     * logic in {@link registerRepo} and the
+     * `re-registerRepo with a different name overrides the previous
+     * alias` test in `test/unit/repo-manager.test.ts`).
+     *
+     * Distinct from `--force` (which only triggers pipeline re-index);
+     * a user accepting a duplicate alias should not be forced to also
+     * re-run the full pipeline.
+     */
+    allowDuplicateName?: boolean;
+}
+/**
+ * Thrown by {@link registerRepo} when a requested name is already in
+ * use by a DIFFERENT path. The CLI layer surfaces this as an actionable
+ * error instead of relying on `.message` string-matching.
+ *
+ * The colliding alias is exposed as `err.registryName` (not `err.name`).
+ * `err.name` keeps its inherited `Error.prototype.name` semantics (the
+ * class name) so downstream code can do the usual `err.name ===
+ * 'RegistryNameCollisionError'` checks; use the `kind` discriminant or
+ * `instanceof RegistryNameCollisionError` for type-safe narrowing.
+ */
+export declare class RegistryNameCollisionError extends Error {
+    readonly registryName: string;
+    readonly existingPath: string;
+    readonly requestedPath: string;
+    readonly kind: "RegistryNameCollisionError";
+    constructor(registryName: string, existingPath: string, requestedPath: string);
+}
 /**
  * Register (add or update) a repo in the global registry.
  * Called after `gitnexus analyze` completes.
+ *
+ * Name resolution precedence (#829, #979):
+ *   1. explicit `opts.name` (from `analyze --name <alias>`)
+ *   2. preserved alias on an existing entry for this path
+ *   3. `git config --get remote.origin.url` repo name (#979 — recovers
+ *      a meaningful name for monorepo subprojects, git worktrees, and
+ *      Gas-Town-style `<rig>/refinery/rig/` layouts where the basename
+ *      is generic)
+ *   4. `path.basename(repoPath)` (the original default)
+ *
+ * Duplicate-name guard: if another path already uses the resolved
+ * `name`, throw {@link RegistryNameCollisionError} unless
+ * `opts.allowDuplicateName` is set. The guard ONLY fires when the user explicitly passed a
+ * `name`; un-aliased basename collisions continue to register silently
+ * so existing users who don't know about `--name` see no behaviour
+ * change.
+ *
+ * Returns the `name` that was actually written to the registry — the
+ * caller can re-use it to keep AGENTS.md / skill files aligned with the
+ * MCP-visible repo name (#979).
  */
-export declare const registerRepo: (repoPath: string, meta: RepoMeta) => Promise<void>;
+export declare const registerRepo: (repoPath: string, meta: RepoMeta, opts?: RegisterRepoOptions) => Promise<string>;
 /**
  * Remove a repo from the global registry.
  * Called after `gitnexus clean`.

package/dist/storage/repo-manager.js

@@ -8,6 +8,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
+import { getInferredRepoName } from './git.js';
 const GITNEXUS_DIR = '.gitnexus';
 // ─── Local Storage Helpers ─────────────────────────────────────────────
 /**
@@ -196,20 +197,120 @@ const writeRegistry = async (entries) => {
     await fs.mkdir(dir, { recursive: true });
     await fs.writeFile(getGlobalRegistryPath(), JSON.stringify(entries, null, 2), 'utf-8');
 };
+/**
+ * Thrown by {@link registerRepo} when a requested name is already in
+ * use by a DIFFERENT path. The CLI layer surfaces this as an actionable
+ * error instead of relying on `.message` string-matching.
+ *
+ * The colliding alias is exposed as `err.registryName` (not `err.name`).
+ * `err.name` keeps its inherited `Error.prototype.name` semantics (the
+ * class name) so downstream code can do the usual `err.name ===
+ * 'RegistryNameCollisionError'` checks; use the `kind` discriminant or
+ * `instanceof RegistryNameCollisionError` for type-safe narrowing.
+ */
+export class RegistryNameCollisionError extends Error {
+    registryName;
+    existingPath;
+    requestedPath;
+    kind = 'RegistryNameCollisionError';
+    constructor(registryName, existingPath, requestedPath) {
+        super(`Registry name "${registryName}" is already used by "${existingPath}".\n` +
+            `Pass --name <alias> to register "${requestedPath}" under a different name, ` +
+            `or --allow-duplicate-name to allow both paths under the same name (leaves -r <name> ambiguous for these two).`);
+        this.registryName = registryName;
+        this.existingPath = existingPath;
+        this.requestedPath = requestedPath;
+        this.name = 'RegistryNameCollisionError';
+    }
+}
+/** Returns true when a previously-registered entry's `name` differs from
+ *  both `path.basename(entry.path)` and the git-remote-derived name —
+ *  i.e. a user explicitly aliased it via `analyze --name <alias>` on a
+ *  prior run. Used to preserve the alias across re-analyses that omit
+ *  `--name`. The remote-derived name is treated as an inference, not a
+ *  custom alias, so re-analyses keep tracking remote renames.
+ *
+ *  `inferredName` is passed in (rather than re-derived) so callers can
+ *  avoid a second `git config` subprocess invocation. */
+const hasCustomAlias = (entry, inferredName) => {
+    const resolved = path.resolve(entry.path);
+    if (entry.name === path.basename(resolved))
+        return false;
+    if (inferredName && entry.name === inferredName)
+        return false;
+    return true;
+};
 /**
  * Register (add or update) a repo in the global registry.
  * Called after `gitnexus analyze` completes.
+ *
+ * Name resolution precedence (#829, #979):
+ *   1. explicit `opts.name` (from `analyze --name <alias>`)
+ *   2. preserved alias on an existing entry for this path
+ *   3. `git config --get remote.origin.url` repo name (#979 — recovers
+ *      a meaningful name for monorepo subprojects, git worktrees, and
+ *      Gas-Town-style `<rig>/refinery/rig/` layouts where the basename
+ *      is generic)
+ *   4. `path.basename(repoPath)` (the original default)
+ *
+ * Duplicate-name guard: if another path already uses the resolved
+ * `name`, throw {@link RegistryNameCollisionError} unless
+ * `opts.allowDuplicateName` is set. The guard ONLY fires when the user explicitly passed a
+ * `name`; un-aliased basename collisions continue to register silently
+ * so existing users who don't know about `--name` see no behaviour
+ * change.
+ *
+ * Returns the `name` that was actually written to the registry — the
+ * caller can re-use it to keep AGENTS.md / skill files aligned with the
+ * MCP-visible repo name (#979).
  */
-export const registerRepo = async (repoPath, meta) => {
+export const registerRepo = async (repoPath, meta, opts) => {
     const resolved = path.resolve(repoPath);
-    const name = path.basename(resolved);
     const { storagePath } = getStoragePaths(resolved);
     const entries = await readRegistry();
-    const existing = entries.findIndex((e) => {
+    const existingIdx = entries.findIndex((e) => {
         const a = path.resolve(e.path);
         const b = resolved;
         return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
     });
+    const existing = existingIdx >= 0 ? entries[existingIdx] : null;
+    // Precedence: explicit --name > preserved alias > remote-inferred > basename.
+    // Skip the `git config` subprocess entirely when --name was passed —
+    // the remote isn't consulted in that case.
+    let name;
+    let isPreservedAlias = false;
+    if (opts?.name !== undefined) {
+        name = opts.name;
+    }
+    else {
+        // Compute the remote-derived name at most once. It feeds both the
+        // alias-preservation check (`hasCustomAlias` needs it to distinguish
+        // a sticky user alias from a previously-stored remote inference) and
+        // the fallback name when neither --name nor a preserved alias apply.
+        const inferred = getInferredRepoName(resolved);
+        if (existing && hasCustomAlias(existing, inferred)) {
+            name = existing.name;
+            isPreservedAlias = true;
+        }
+        else {
+            name = inferred ?? path.basename(resolved);
+        }
+    }
+    // Duplicate-name guard: only fire when the user EXPLICITLY asked for
+    // this name (via opts.name or a preserved alias). Unqualified basename
+    // and remote-inferred collisions are preserved for backward-compat —
+    // they still register, and the user sees the ambiguity at `-r` / `list`
+    // resolution time (which is already improved by the disambiguated error
+    // messages and list output #829 ships).
+    const explicitName = opts?.name !== undefined || isPreservedAlias;
+    if (explicitName && !opts?.allowDuplicateName) {
+        const collidingEntry = entries.find((e, i) => i !== existingIdx &&
+            e.name.toLowerCase() === name.toLowerCase() &&
+            path.resolve(e.path) !== resolved);
+        if (collidingEntry) {
+            throw new RegistryNameCollisionError(name, collidingEntry.path, resolved);
+        }
+    }
     const entry = {
         name,
         path: resolved,
@@ -218,13 +319,14 @@ export const registerRepo = async (repoPath, meta) => {
         lastCommit: meta.lastCommit,
         stats: meta.stats,
     };
-    if (existing >= 0) {
-        entries[existing] = entry;
+    if (existingIdx >= 0) {
+        entries[existingIdx] = entry;
     }
     else {
         entries.push(entry);
     }
     await writeRegistry(entries);
+    return name;
 };
 /**
  * Remove a repo from the global registry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.3-rc.2",
+  "version": "1.6.3-rc.21",
   "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",