gitnexus 1.6.10-rc.136 → 1.6.10-rc.138

package/README.md

@@ -311,6 +311,31 @@ validates the returned vector's length):
 
 Works with Infinity, vLLM, TEI, llama.cpp, Ollama, LM Studio, or OpenAI. Retry and pacing settings are provider-neutral; provider-specific limits should be supplied through configuration. When unset, local embeddings are used unchanged.
 
+## JVM Package Sibling Injection
+
+Java and Kotlin files in the same package receive implicit sibling class bindings
+to resolve same-package references. By default, GitNexus injects at most 200
+siblings per module scope, nearest first by path. Set
+`GITNEXUS_MAX_INJECTED_SIBLINGS=0` to remove that per-file limit; this can
+substantially increase indexing work for large packages.
+
+```bash
+export GITNEXUS_MAX_INJECTED_SIBLINGS=200
+gitnexus analyze .
+```
+
+When the limit truncates a file's sibling set, that file is marked
+visibility-incomplete: same-package references still resolve through the
+injected siblings, but wildcard-import attribution (used by the Spring
+bean/DI/config passes) is disabled for it rather than resolved against a
+partial view. Analyze logs a `sibling injection truncated` warning naming how
+many files were affected.
+
+Packages with more than 500 files are a separate, fixed limit: they are skipped
+entirely (logged as `skipping package with N files`) and every file in them is
+marked visibility-incomplete. `GITNEXUS_MAX_INJECTED_SIBLINGS` does not lift
+that skip — including at `0`.
+
 ## Multi-Repo Support
 
 GitNexus supports indexing multiple repositories. Each `gitnexus analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically.

package/dist/core/ingestion/languages/jvm/package-siblings.js

@@ -1,6 +1,17 @@
 import { logger } from '../../../logger.js';
 import { isClassLike } from '../../scope-resolution/scope/walkers.js';
+/** Packages larger than this get no implicit sibling visibility at all — every
+ *  file in them is marked incomplete. `GITNEXUS_MAX_INJECTED_SIBLINGS` bounds
+ *  injection *within* a package and does not lift this skip. */
 const MAX_PACKAGE_FILES = 500;
+const DEFAULT_MAX_INJECTED_SIBLINGS = 200;
+function getMaxInjectedSiblings() {
+    const raw = process.env.GITNEXUS_MAX_INJECTED_SIBLINGS;
+    if (raw === undefined || raw === '')
+        return DEFAULT_MAX_INJECTED_SIBLINGS;
+    const parsed = Number(raw);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : DEFAULT_MAX_INJECTED_SIBLINGS;
+}
 export function createJvmPackageSiblingVisibility(options) {
     const incompleteFiles = new Set();
     function populateNamespaceSiblings(parsedFiles, indexes, ctx) {
@@ -40,6 +51,8 @@ export function createJvmPackageSiblingVisibility(options) {
             logger.warn(`[${options.languageLabel}-package-siblings] ${unknownPackageFiles.size} file(s) lacked reliable package facts; wildcard attribution disabled for this language workspace`);
         }
         const augmentations = indexes.bindingAugmentations;
+        const maxInjectedSiblings = getMaxInjectedSiblings();
+        let truncatedFiles = 0;
         for (const bucket of buckets.values()) {
             if (bucket.moduleScopes.length < 2)
                 continue;
@@ -60,25 +73,53 @@ export function createJvmPackageSiblingVisibility(options) {
                         classDefs.push({ def, filePath: parsed.filePath });
                 }
             }
+            // Per-bucket lookups: the per-file loop below is O(files²) over these,
+            // so split each path into segments once here instead of re-splitting it
+            // on every pairwise proximity comparison, and address siblings by path
+            // so a truncated scope can merge its bounded set without rescanning the
+            // whole package.
+            const segmentsByPath = new Map();
+            const moduleScopeByPath = new Map();
+            const parsedByPath = new Map();
+            for (const parsed of bucket.parsed) {
+                segmentsByPath.set(parsed.filePath, pathSegments(parsed.filePath));
+                parsedByPath.set(parsed.filePath, parsed);
+            }
+            for (const sibling of bucket.moduleScopes)
+                moduleScopeByPath.set(sibling.filePath, sibling);
+            const allSiblingPaths = [...parsedByPath.keys()];
             for (const { filePath, scope } of bucket.moduleScopes) {
                 let scopeAug = augmentations.get(scope.id);
                 if (scopeAug === undefined) {
                     scopeAug = new Map();
                     augmentations.set(scope.id, scopeAug);
                 }
+                const ownSegments = segmentsByPath.get(filePath) ?? pathSegments(filePath);
                 const proximityCache = new Map();
                 const candidates = classDefs.filter((candidate) => candidate.filePath !== filePath);
                 for (const candidate of candidates) {
                     if (!proximityCache.has(candidate.filePath)) {
-                        proximityCache.set(candidate.filePath, sharedSegmentCount(candidate.filePath, filePath));
+                        proximityCache.set(candidate.filePath, sharedSegmentCount(segmentsByPath.get(candidate.filePath) ?? [], ownSegments));
                     }
                 }
+                // Nearest-first by shared path prefix. Ties (the common case in a flat
+                // package, where every sibling shares the same directory) keep the
+                // walker's traversal order, so the retained set is deterministic but
+                // arbitrary among equally-near candidates — which is why truncation
+                // marks the file incomplete below rather than being treated as exact.
                 candidates.sort((a, b) => (proximityCache.get(b.filePath) ?? 0) - (proximityCache.get(a.filePath) ?? 0));
                 const injectedIds = new Set();
-                for (const { def } of candidates) {
+                const injectedPaths = new Set();
+                let truncated = false;
+                for (const { def, filePath: defPath } of candidates) {
                     if (injectedIds.has(def.nodeId) || def.qualifiedName === undefined)
                         continue;
+                    if (maxInjectedSiblings > 0 && injectedIds.size >= maxInjectedSiblings) {
+                        truncated = true;
+                        break;
+                    }
                     injectedIds.add(def.nodeId);
+                    injectedPaths.add(defPath);
                     const simpleName = def.qualifiedName.includes('.')
                         ? def.qualifiedName.slice(def.qualifiedName.lastIndexOf('.') + 1)
                         : def.qualifiedName;
@@ -87,17 +128,40 @@ export function createJvmPackageSiblingVisibility(options) {
                         scopeAug.set(simpleName, bindings);
                     bindings.push({ def, origin: 'namespace' });
                 }
+                if (truncated) {
+                    // Sibling visibility for this file is now partial, and downstream
+                    // Spring attribution treats a complete flag as "this package's names
+                    // are fully known". Marking it incomplete keeps wildcard attribution
+                    // conservative instead of silently resolving against a truncated set.
+                    incompleteFiles.add(filePath);
+                    truncatedFiles++;
+                }
+                // Keep the two halves of "what this file can see" in agreement: when
+                // the cap truncated the binding set, merge type bindings from the same
+                // bounded sibling set only — and iterate that set directly, so the cap
+                // bounds the merge work too instead of just filtering a full scan. An
+                // untruncated scope merges every sibling as before, including ones that
+                // contribute no class-like def.
                 const typeBindings = scope.typeBindings;
-                for (const sibling of bucket.moduleScopes) {
-                    if (sibling.filePath === filePath)
+                const mergePaths = truncated ? injectedPaths : allSiblingPaths;
+                // Module scopes first, then class scopes: module-level bindings win on
+                // a name collision, which the two-pass order (not file order) encodes.
+                for (const siblingPath of mergePaths) {
+                    if (siblingPath === filePath)
+                        continue;
+                    const sibling = moduleScopeByPath.get(siblingPath);
+                    if (sibling === undefined)
                         continue;
                     for (const [name, ref] of sibling.scope.typeBindings) {
                         if (!typeBindings.has(name))
                             typeBindings.set(name, ref);
                     }
                 }
-                for (const sibling of bucket.parsed) {
-                    if (sibling.filePath === filePath)
+                for (const siblingPath of mergePaths) {
+                    if (siblingPath === filePath)
+                        continue;
+                    const sibling = parsedByPath.get(siblingPath);
+                    if (sibling === undefined)
                         continue;
                     for (const siblingScope of sibling.scopes) {
                         if (siblingScope.kind !== 'Class')
@@ -110,15 +174,19 @@ export function createJvmPackageSiblingVisibility(options) {
                 }
             }
         }
+        if (truncatedFiles > 0) {
+            logger.warn(`[${options.languageLabel}-package-siblings] sibling injection truncated at ${maxInjectedSiblings} per file for ${truncatedFiles} file(s); wildcard attribution disabled for those files (raise or unset GITNEXUS_MAX_INJECTED_SIBLINGS to widen, 0 for unbounded)`);
+        }
     }
     return {
         populateNamespaceSiblings,
         isVisibilityIncomplete: (filePath) => incompleteFiles.has(filePath),
     };
 }
-function sharedSegmentCount(a, b) {
-    const aSegments = a.replace(/\\/g, '/').split('/');
-    const bSegments = b.replace(/\\/g, '/').split('/');
+function pathSegments(filePath) {
+    return filePath.replace(/\\/g, '/').split('/');
+}
+function sharedSegmentCount(aSegments, bSegments) {
     let index = 0;
     while (index < aSegments.length &&
         index < bSegments.length &&

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

@@ -837,44 +837,8 @@ export declare class RegistryNameCollisionError extends Error {
     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, opts?: RegisterRepoOptions) => Promise<string>;
-/**
- * Remove a repo from the global registry.
- * Called after `gitnexus clean`.
- */
 export declare const unregisterRepo: (repoPath: string) => Promise<void>;
-/**
- * Remove a single non-primary branch's summary from a repo's registry entry
- * (#2106 R7). Called by `gitnexus clean --branch`. Returns `true` when a
- * matching `branches[]` summary was found and removed; `false` otherwise (so
- * the CLI can report "no such indexed branch" without crashing). The top-level
- * primary entry is left intact; an empty `branches[]` is dropped to keep the
- * registry shape legacy-clean.
- */
 export declare const removeBranchIndex: (repoPath: string, branch: string) => Promise<boolean>;
 /**
  * Record that the flat workspace slot now serves `branch` (#2354).
@@ -892,6 +856,12 @@ export declare const removeBranchIndex: (repoPath: string, branch: string) => Pr
  * a no-op — including the sub-index deletion, which only runs for registered
  * repos (never self-heals an unregistered repo, per #2264/#1169; the registry
  * check precedes the rm per #2364 review F2) — and no subprocess is spawned.
+ *
+ * Only the closing re-read/mutate/write runs under the registry lock. The
+ * recursive `rm` stays outside it — mirroring `clean.ts`, which deletes the
+ * branch directory before calling the (locked) `removeBranchIndex` — so a slow
+ * delete (large sub-index, AV scan, network mount) never blocks every other
+ * registry operation on the machine.
  */
 export declare const adoptFlatBranchLabel: (repoPath: string, branch: string) => Promise<void>;
 /**

package/dist/storage/repo-manager.js

@@ -22,6 +22,7 @@ import { getInferredRepoName, resolveRepoIdentityRoot } from './git.js';
 import { stripWindowsLongPathPrefix } from '../lib/utils.js';
 import { retryRename } from './fs-atomic.js';
 import { logger } from '../core/logger.js';
+import { acquireIndexLock, IndexLockTimeoutError } from './index-lock.js';
 import { branchSlug, BRANCHES_DIR, resolveBranchPlacement, } from './branch-index.js';
 // Re-export the #2106 branch primitives (extracted to branch-index.ts, R10) so
 // existing `repo-manager` import sites and tests keep working unchanged.
@@ -753,6 +754,65 @@ export const getGlobalDir = () => {
 export const getGlobalRegistryPath = () => {
     return path.join(getGlobalDir(), 'registry.json');
 };
+/**
+ * Lock namespace for the global registry.
+ *
+ * Deliberately a dedicated sub-directory rather than {@link getGlobalDir}
+ * itself: an index slot's lock dir is always `<repo>/.gitnexus` (or
+ * `<repo>/.gitnexus/branches/<slug>`), so for a repository rooted at the
+ * user's home directory — dotfiles-at-`$HOME` is a real layout — the per-repo
+ * analyze lock and the global-dir lock would resolve to the SAME directory.
+ * `acquireIndexLock` is not reentrant, so `runFullAnalysis` (which holds the
+ * per-repo lock across its whole pipeline) would then self-deadlock the moment
+ * it reached `registerRepo`/`adoptFlatBranchLabel`. No repo's index slot can
+ * ever be named `registry-lock`, so this namespace cannot collide.
+ */
+const getRegistryLockDir = () => path.join(getGlobalDir(), 'registry-lock');
+/**
+ * Wait ceiling for the registry lock. A registry transaction is a sub-second
+ * JSON read/merge/write, so it must NOT inherit the index lock's 10-minute
+ * default (sized for multi-minute analyze runs): `gitnexus augment` runs on
+ * every editor/agent tool call with a documented sub-500ms cold-start budget
+ * and reaches this lock via `listRegisteredRepos({ validate: true })`.
+ */
+const REGISTRY_LOCK_TIMEOUT_MS = 5_000;
+/**
+ * Serialize global registry read/merge/write transactions across processes.
+ *
+ * The registry is shared by every indexed repository, so per-index locks do
+ * not protect this file. Reuse the cross-platform index lock primitive with a
+ * registry-private lock namespace; the handle is kernel-owned on supported
+ * platforms and crash-reclaimable by the existing fallback.
+ *
+ * On timeout the transaction proceeds UNLOCKED rather than throwing: the lock
+ * closes a lost-update race that existed unguarded before #2716, so degrading
+ * to the old best-effort behaviour is strictly better than failing an
+ * `analyze`/`list`/`augment` outright on a wedged lock (a stale pid-reuse
+ * ghost on platforms without start-time verification can look live forever).
+ */
+const withRegistryLock = async (operation) => {
+    let lock = null;
+    try {
+        lock = await acquireIndexLock(getRegistryLockDir(), {
+            timeoutMs: REGISTRY_LOCK_TIMEOUT_MS,
+            // Registry contention was previously invisible: `acquireIndexLock`'s own
+            // `log` texts name an "analyze" holder, which misattributes a registry
+            // wait, so surface a registry-specific line instead (#2716 review).
+            onWaitStart: () => logger.info('Waiting for another GitNexus process to finish a registry update…'),
+        });
+    }
+    catch (err) {
+        if (!(err instanceof IndexLockTimeoutError))
+            throw err;
+        logger.warn({ timeoutMs: REGISTRY_LOCK_TIMEOUT_MS }, 'Timed out waiting for the global registry lock; proceeding without it. A concurrent registry write may be lost.');
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        lock?.release();
+    }
+};
 /**
  * Read the global registry. Returns empty array if not found.
  */
@@ -859,7 +919,7 @@ const hasCustomAlias = (entry, inferredName) => {
  * 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, opts) => {
+const registerRepoUnlocked = async (repoPath, meta, opts) => {
     // Preserve the caller's chosen path form in the registry — don't
     // canonicalise at write time. This matters for two reasons:
     //   1. `list` and error messages show the path the user actually
@@ -1017,11 +1077,12 @@ export const registerRepo = async (repoPath, meta, opts) => {
     await writeRegistry(fresh);
     return name;
 };
+export const registerRepo = async (repoPath, meta, opts) => withRegistryLock(() => registerRepoUnlocked(repoPath, meta, opts));
 /**
  * Remove a repo from the global registry.
  * Called after `gitnexus clean`.
  */
-export const unregisterRepo = async (repoPath) => {
+const unregisterRepoUnlocked = async (repoPath) => {
     // Canonicalise BOTH sides so an unregister call issued with the
     // symlink form (`/var/folders/.../repo`) still matches an entry
     // written with the realpath form (`/private/var/folders/.../repo`),
@@ -1032,6 +1093,7 @@ export const unregisterRepo = async (repoPath) => {
     const filtered = entries.filter((e) => !registryPathEquals(canonicalizePath(e.path), resolved));
     await writeRegistry(filtered);
 };
+export const unregisterRepo = async (repoPath) => withRegistryLock(() => unregisterRepoUnlocked(repoPath));
 /**
  * Remove a single non-primary branch's summary from a repo's registry entry
  * (#2106 R7). Called by `gitnexus clean --branch`. Returns `true` when a
@@ -1040,7 +1102,7 @@ export const unregisterRepo = async (repoPath) => {
  * primary entry is left intact; an empty `branches[]` is dropped to keep the
  * registry shape legacy-clean.
  */
-export const removeBranchIndex = async (repoPath, branch) => {
+const removeBranchIndexUnlocked = async (repoPath, branch) => {
     const resolved = canonicalizePath(repoPath);
     const entries = await readRegistry();
     const idx = entries.findIndex((e) => registryPathEquals(canonicalizePath(e.path), resolved));
@@ -1061,6 +1123,7 @@ export const removeBranchIndex = async (repoPath, branch) => {
     await writeRegistry(entries);
     return true;
 };
+export const removeBranchIndex = async (repoPath, branch) => withRegistryLock(() => removeBranchIndexUnlocked(repoPath, branch));
 /**
  * Record that the flat workspace slot now serves `branch` (#2354).
  *
@@ -1077,6 +1140,12 @@ export const removeBranchIndex = async (repoPath, branch) => {
  * a no-op — including the sub-index deletion, which only runs for registered
  * repos (never self-heals an unregistered repo, per #2264/#1169; the registry
  * check precedes the rm per #2364 review F2) — and no subprocess is spawned.
+ *
+ * Only the closing re-read/mutate/write runs under the registry lock. The
+ * recursive `rm` stays outside it — mirroring `clean.ts`, which deletes the
+ * branch directory before calling the (locked) `removeBranchIndex` — so a slow
+ * delete (large sub-index, AV scan, network mount) never blocks every other
+ * registry operation on the machine.
  */
 export const adoptFlatBranchLabel = async (repoPath, branch) => {
     const canonicalInput = canonicalizePath(repoPath);
@@ -1121,26 +1190,28 @@ export const adoptFlatBranchLabel = async (repoPath, branch) => {
             logger.warn({ path: branchDir, code: rmError?.code }, 'Could not remove the shadowed branch sub-index; keeping its registry summary so `gitnexus clean --branch` can still target it.');
         }
     }
-    // Re-read AFTER the potentially slow recursive rm: the registry is a
-    // multi-writer whole-file overwrite, and writing a pre-rm snapshot would
-    // silently clobber concurrent registerRepo/removeBranchIndex writers —
-    // the #2106 R9 re-read-before-write discipline registerRepo follows.
-    const entries = await readRegistry();
-    const idx = isRegistered(entries);
-    if (idx < 0)
-        return; // unregistered concurrently → still a no-op
-    const entry = entries[idx];
-    const remaining = dirGone ? entry.branches?.filter((b) => b.branch !== branch) : entry.branches;
-    const droppedSummary = (entry.branches?.length ?? 0) !== (remaining?.length ?? 0);
-    if (entry.branch === branch && !droppedSummary)
-        return; // already coherent
-    entry.branch = branch;
-    if (remaining && remaining.length > 0)
-        entry.branches = remaining;
-    else
-        delete entry.branches;
-    entries[idx] = entry;
-    await writeRegistry(entries);
+    // Re-read AFTER the potentially slow recursive rm, and under the lock: the
+    // registry is a multi-writer whole-file overwrite, and writing a pre-rm
+    // snapshot would silently clobber concurrent registerRepo/removeBranchIndex
+    // writers — the #2106 R9 re-read-before-write discipline registerRepo follows.
+    await withRegistryLock(async () => {
+        const entries = await readRegistry();
+        const idx = isRegistered(entries);
+        if (idx < 0)
+            return; // unregistered concurrently → still a no-op
+        const entry = entries[idx];
+        const remaining = dirGone ? entry.branches?.filter((b) => b.branch !== branch) : entry.branches;
+        const droppedSummary = (entry.branches?.length ?? 0) !== (remaining?.length ?? 0);
+        if (entry.branch === branch && !droppedSummary)
+            return; // already coherent
+        entry.branch = branch;
+        if (remaining && remaining.length > 0)
+            entry.branches = remaining;
+        else
+            delete entry.branches;
+        entries[idx] = entry;
+        await writeRegistry(entries);
+    });
 };
 /**
  * Thrown by {@link resolveRegistryEntry} when no registered repo matches
@@ -1454,9 +1525,19 @@ export const listRegisteredRepos = async (opts) => {
             valid.push(entry);
         }
     }
-    // If we pruned any entries, save the cleaned registry
+    // If we pruned any entries, save the cleaned registry — under the lock, and
+    // only then. The validation walk above is read-only (an fs.access per entry,
+    // slow on a network mount or a large registry) and the common case prunes
+    // nothing, so holding the global lock across it would serialize every
+    // `gitnexus augment` behind unrelated registry work for no benefit. Re-read
+    // inside the lock and drop the provably-absent paths from that fresh
+    // snapshot, so a concurrent registration in the validation window survives.
     if (valid.length !== entries.length) {
-        await writeRegistry(valid);
+        const pruned = new Set(entries.filter((entry) => !valid.includes(entry)).map((entry) => entry.path));
+        await withRegistryLock(async () => {
+            const fresh = await readRegistry();
+            await writeRegistry(fresh.filter((entry) => !pruned.has(entry.path)));
+        });
     }
     return valid;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.10-rc.136",
+  "version": "1.6.10-rc.138",
   "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",

package/scripts/cross-platform-tests.ts

@@ -63,6 +63,9 @@ const PLATFORM_LOGIC = [
   'test/unit/lbug-config-pagesize.test.ts',
   'test/unit/worker-pool-windows-quarantine.test.ts',
   'test/unit/lbug-pool-fts-load.test.ts',
+  // Global registry writes use the platform-specific index-lock backend
+  // (Windows named pipe, Linux socket, or macOS file lock). This includes the
+  // overlapping-registration regression from #2716 on every OS matrix.
   'test/unit/repo-manager.test.ts',
   'test/unit/repo-manager-finalize-invariant.test.ts',
   'test/unit/git-utils.test.ts',