gitnexus 1.6.3-rc.17 → 1.6.3-rc.19

package/dist/cli/analyze.d.ts

@@ -18,5 +18,20 @@ export interface AnalyzeOptions {
     noStats?: boolean;
     /** Index the folder even when no .git directory is present. */
     skipGit?: boolean;
+    /**
+     * Override the default basename-derived registry `name` with a
+     * user-supplied alias (#829). Disambiguates repos whose paths share a
+     * basename. Persisted — subsequent re-analyses of the same path without
+     * `--name` preserve the alias.
+     */
+    name?: string;
+    /**
+     * Allow registration even when another path already uses the same
+     * `--name` alias (#829). Intentionally a distinct flag from `--force`
+     * because the user may want to coexist under the same name WITHOUT
+     * paying the cost of a pipeline re-index. Maps to registerRepo's
+     * `allowDuplicateName` option end-to-end.
+     */
+    allowDuplicateName?: boolean;
 }
 export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;

package/dist/cli/analyze.js

@@ -12,7 +12,7 @@ import { execFileSync } from 'child_process';
 import v8 from 'v8';
 import cliProgress from 'cli-progress';
 import { closeLbug } from '../core/lbug/lbug-adapter.js';
-import { getStoragePaths, getGlobalRegistryPath } from '../storage/repo-manager.js';
+import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, } from '../storage/repo-manager.js';
 import { getGitRoot, hasGitDir } from '../storage/git.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
 import fs from 'fs/promises';
@@ -146,11 +146,20 @@ export const analyzeCommand = async (inputPath, options) => {
     // ── Run shared analysis orchestrator ───────────────────────────────
     try {
         const result = await runFullAnalysis(repoPath, {
+            // Pipeline re-index — OR'd with --skills because skill generation
+            // needs a fresh pipelineResult. Has no bearing on the registry
+            // collision guard (see allowDuplicateName below).
             force: options?.force || options?.skills,
             embeddings: options?.embeddings,
             skipGit: options?.skipGit,
             skipAgentsMd: options?.skipAgentsMd,
             noStats: options?.noStats,
+            registryName: options?.name,
+            // Registry-collision bypass — its own CLI flag, intentionally NOT
+            // overloading --force. A user who hits the collision guard should
+            // be able to accept the duplicate name without also paying the
+            // cost of a full pipeline re-index. See #829 review round 2.
+            allowDuplicateName: options?.allowDuplicateName,
         }, {
             onProgress: (_phase, percent, message) => {
                 updateBar(percent, message);
@@ -234,6 +243,18 @@ export const analyzeCommand = async (inputPath, options) => {
         console.error = origError;
         bar.stop();
         const msg = err.message || String(err);
+        // Registry name-collision from --name (#829) — surface as an
+        // actionable error rather than a generic stack-trace.
+        if (err instanceof RegistryNameCollisionError) {
+            console.error(`\n  Registry name collision:\n`);
+            console.error(`    "${err.registryName}" is already used by "${err.existingPath}".\n`);
+            console.error(`  Options:`);
+            console.error(`    • Pick a different alias:  gitnexus analyze --name <alias>`);
+            console.error(`    • Allow the duplicate:     gitnexus analyze --allow-duplicate-name  (leaves "-r ${err.registryName}" ambiguous)`);
+            console.error('');
+            process.exitCode = 1;
+            return;
+        }
         console.error(`\n  Analysis failed: ${msg}\n`);
         // Provide helpful guidance for known failure modes
         if (msg.includes('Maximum call stack size exceeded') ||

package/dist/cli/index.js

@@ -22,6 +22,10 @@ program
     .option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md')
     .option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')
     .option('--skip-git', 'Index a folder without requiring a .git directory')
+    .option('--name <alias>', 'Register this repo under a custom name in ~/.gitnexus/registry.json ' +
+    '(disambiguates repos whose paths share a basename, e.g. two different .../app folders)')
+    .option('--allow-duplicate-name', 'Register this repo even if another path already uses the same --name alias. ' +
+    'Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.')
     .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
     .addHelpText('after', '\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1  Skip .gitignore parsing (still reads .gitnexusignore)')
     .action(createLazyAction(() => import('./analyze.js'), 'analyzeCommand'));

package/dist/cli/list.js

@@ -12,11 +12,21 @@ export const listCommand = async () => {
         return;
     }
     console.log(`\n  Indexed Repositories (${entries.length})\n`);
+    // Count occurrences of each name so colliding entries can be
+    // disambiguated in the header (#829). Unique-name entries render
+    // identically to pre-#829 output; only collisions gain a suffix.
+    const nameCounts = new Map();
+    for (const e of entries) {
+        const key = e.name.toLowerCase();
+        nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);
+    }
     for (const entry of entries) {
         const indexedDate = new Date(entry.indexedAt).toLocaleString();
         const stats = entry.stats || {};
         const commitShort = entry.lastCommit?.slice(0, 7) || 'unknown';
-        console.log(`  ${entry.name}`);
+        const hasCollision = (nameCounts.get(entry.name.toLowerCase()) ?? 0) > 1;
+        const header = hasCollision ? `${entry.name}  (${entry.path})` : entry.name;
+        console.log(`  ${header}`);
         console.log(`    Path:    ${entry.path}`);
         console.log(`    Indexed: ${indexedDate}`);
         console.log(`    Commit:  ${commitShort}`);

package/dist/core/run-analyze.d.ts

@@ -13,6 +13,12 @@ export interface AnalyzeCallbacks {
     onLog?: (message: string) => void;
 }
 export interface AnalyzeOptions {
+    /**
+     * Force a full re-index of the pipeline. Callers may OR this with
+     * other flags that imply re-analysis (e.g. `--skills`), so the value
+     * here is the PIPELINE-force signal, NOT the registry-collision
+     * bypass. See `allowDuplicateName` below.
+     */
     force?: boolean;
     embeddings?: boolean;
     skipGit?: boolean;
@@ -20,6 +26,21 @@ export interface AnalyzeOptions {
     skipAgentsMd?: boolean;
     /** Omit volatile symbol/relationship counts from AGENTS.md and CLAUDE.md. */
     noStats?: boolean;
+    /**
+     * User-provided alias for the registry `name` (#829). When set,
+     * forwarded to `registerRepo` so the indexed repo is stored under
+     * this alias instead of the path-derived basename.
+     */
+    registryName?: string;
+    /**
+     * Bypass the `RegistryNameCollisionError` guard and allow two paths
+     * to register under the same `name` (#829). Controlled by the
+     * dedicated `--allow-duplicate-name` CLI flag, intentionally
+     * independent from `--force` — users who hit the collision guard
+     * should be able to accept the duplicate without paying the cost
+     * of a pipeline re-index.
+     */
+    allowDuplicateName?: boolean;
 }
 export interface AnalyzeResult {
     repoName: string;

package/dist/core/run-analyze.js

@@ -218,7 +218,15 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             },
         };
         await saveMeta(storagePath, meta);
-        await registerRepo(repoPath, meta);
+        // Forward the --name alias and the registry-collision bypass bit.
+        // `allowDuplicateName` is its own concern — independent from the
+        // pipeline `force` above. The CLI maps it from
+        // `--allow-duplicate-name` only; `--force` and `--skills` both
+        // trigger pipeline re-run but never bypass the registry guard.
+        await registerRepo(repoPath, meta, {
+            name: options.registryName,
+            allowDuplicateName: options.allowDuplicateName,
+        });
         // Only attempt to update .gitignore when a .git directory is present.
         if (hasGitDir(repoPath)) {
             await addToGitignore(repoPath);

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

@@ -279,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.

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

@@ -102,11 +102,72 @@ 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.
- */
-export declare const registerRepo: (repoPath: string, meta: RepoMeta) => Promise<void>;
+ *
+ * Name resolution precedence (#829):
+ *   1. explicit `opts.name` (from `analyze --name <alias>`)
+ *   2. preserved alias on an existing entry for this path
+ *   3. `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.
+ */
+export declare const registerRepo: (repoPath: string, meta: RepoMeta, opts?: RegisterRepoOptions) => Promise<void>;
 /**
  * Remove a repo from the global registry.
  * Called after `gitnexus clean`.

package/dist/storage/repo-manager.js

@@ -196,20 +196,82 @@ 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
+ *  `path.basename(entry.path)` — 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`. */
+const hasCustomAlias = (entry) => {
+    return entry.name !== path.basename(path.resolve(entry.path));
+};
 /**
  * Register (add or update) a repo in the global registry.
  * Called after `gitnexus analyze` completes.
+ *
+ * Name resolution precedence (#829):
+ *   1. explicit `opts.name` (from `analyze --name <alias>`)
+ *   2. preserved alias on an existing entry for this path
+ *   3. `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.
  */
-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 > basename.
+    const name = opts?.name ?? (existing && hasCustomAlias(existing) ? existing.name : 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
+    // 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 this PR also ships).
+    const explicitName = opts?.name !== undefined || (existing && hasCustomAlias(existing));
+    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,8 +280,8 @@ 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);

package/package.json

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