gitnexus 1.6.3-rc.8 → 1.6.3

package/dist/storage/repo-manager.js

@@ -6,8 +6,49 @@
  * so the MCP server can discover indexed repos from any cwd.
  */
 import fs from 'fs/promises';
+import { realpathSync } from 'fs';
 import path from 'path';
 import os from 'os';
+import { getInferredRepoName } from './git.js';
+/**
+ * Normalise a repo path for registry comparison across platforms
+ * (#664 review feedback from @evander-wang).
+ *
+ * Why this exists: `path.resolve` alone is NOT enough for
+ * cross-platform registry stability.
+ *   - **macOS**: tmpdirs and `/var` are symlinks to `/private/var`.
+ *     A child process that stored `/private/var/folders/.../repo` in
+ *     the registry cannot later be matched by an outer caller that
+ *     supplies the symlink form `/var/folders/.../repo`. `path.resolve`
+ *     does not follow symlinks; `realpathSync.native` does.
+ *   - **Windows**: GitHub runners surface tmpdirs in 8.3 short-name
+ *     form (`RUNNERA~1\...`), but `process.cwd()` often returns the
+ *     long form (`runneradmin\...`). `realpathSync.native` normalises
+ *     both sides to the long-name canonical path.
+ *
+ * Fallback behaviour: if the path does not exist on disk (e.g. a user
+ * passed `gitnexus remove some-alias` and the alias misses every
+ * registry entry, or the caller is resolving a path that was deleted
+ * after registration), we return `path.resolve(p)` rather than
+ * throwing. This preserves the idempotent-on-missing semantics of
+ * `resolveRegistryEntry` / `remove`.
+ *
+ * Backwards compatibility: this function is applied to BOTH the
+ * caller-supplied input AND each stored `entry.path` at compare time
+ * inside `resolveRegistryEntry`, so registries written by older
+ * versions (where `registerRepo` only ran `path.resolve`) still match
+ * correctly. Newly-written entries are canonicalised at write time too
+ * so the registry stabilises over analyze/re-analyze cycles.
+ */
+export const canonicalizePath = (p) => {
+    const resolved = path.resolve(p);
+    try {
+        return realpathSync.native(resolved);
+    }
+    catch {
+        return resolved;
+    }
+};
 const GITNEXUS_DIR = '.gitnexus';
 // ─── Local Storage Helpers ─────────────────────────────────────────────
 /**
@@ -196,46 +237,352 @@ 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) => {
+    // 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
+    //      knows (e.g. the 8.3 short form they typed), not a runtime-
+    //      resolved long form they've never seen.
+    //   2. Keeps pre-existing #829 test assertions that compare
+    //      `err.existingPath` against `path.resolve(tmpPath)` stable.
+    // Canonicalisation is applied at COMPARE points only (see below),
+    // which is where the cross-platform divergence actually matters.
     const resolved = path.resolve(repoPath);
-    const name = path.basename(resolved);
     const { storagePath } = getStoragePaths(resolved);
+    // Canonical form used strictly for comparison — `realpathSync.native`
+    // expands macOS /var → /private/var and Windows 8.3 → long-name,
+    // falling back to `path.resolve` when the path doesn't exist.
+    const canonicalInput = canonicalizePath(repoPath);
     const entries = await readRegistry();
-    const existing = entries.findIndex((e) => {
-        const a = path.resolve(e.path);
-        const b = resolved;
+    const existingIdx = entries.findIndex((e) => {
+        // Canonicalise the STORED entry too so pre-canonicalisation
+        // registries (written by older versions, or paths passed in a
+        // different form) still match correctly. `canonicalizePath` falls
+        // back to `path.resolve` when the path no longer exists on disk,
+        // so stale entries that have been rm'd externally still resolve
+        // to a stable key instead of throwing.
+        const a = canonicalizePath(e.path);
+        const b = canonicalInput;
         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) {
+        // Compare canonical-vs-canonical here too so `/var/foo` and
+        // `/private/var/foo` (same repo, different form) aren't treated as
+        // two colliding paths.
+        const collidingEntry = entries.find((e, i) => i !== existingIdx &&
+            e.name.toLowerCase() === name.toLowerCase() &&
+            canonicalizePath(e.path) !== canonicalInput);
+        if (collidingEntry) {
+            throw new RegistryNameCollisionError(name, collidingEntry.path, resolved);
+        }
+    }
     const entry = {
         name,
         path: resolved,
         storagePath,
         indexedAt: meta.indexedAt,
         lastCommit: meta.lastCommit,
+        remoteUrl: meta.remoteUrl,
         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.
  * Called after `gitnexus clean`.
  */
 export const unregisterRepo = async (repoPath) => {
-    const resolved = path.resolve(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`),
+    // and vice versa. Matches the semantics of `registerRepo` and
+    // `resolveRegistryEntry` post-#1003 review.
+    const resolved = canonicalizePath(repoPath);
     const entries = await readRegistry();
-    const filtered = entries.filter((e) => path.resolve(e.path) !== resolved);
+    const matches = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+    const filtered = entries.filter((e) => !matches(canonicalizePath(e.path), resolved));
     await writeRegistry(filtered);
 };
+/**
+ * Thrown by {@link resolveRegistryEntry} when no registered repo matches
+ * the caller's target string (by alias, basename, remote-inferred name,
+ * or resolved path). CLI callers that want idempotent "remove" semantics
+ * should catch this and exit 0 with a warning; non-idempotent callers
+ * (e.g. MCP tools) can surface the error directly.
+ */
+export class RegistryNotFoundError extends Error {
+    target;
+    availableNames;
+    kind = 'RegistryNotFoundError';
+    constructor(target, availableNames) {
+        const hint = availableNames.length > 0
+            ? ` Available: ${availableNames.join(', ')}.`
+            : ' No repositories are currently registered.';
+        super(`No registered repo matches "${target}".${hint}`);
+        this.target = target;
+        this.availableNames = availableNames;
+        this.name = 'RegistryNotFoundError';
+    }
+}
+/**
+ * Thrown by {@link resolveRegistryEntry} when the target string matches
+ * the `name` of two or more entries — only possible when the user
+ * previously registered duplicates via `analyze --name X
+ * --allow-duplicate-name` (#829). The error carries enough information
+ * for the caller to render an actionable disambiguation hint without
+ * string-matching on `.message`.
+ *
+ * `kind` is a string literal discriminant (same pattern as
+ * {@link RegistryNameCollisionError}) so callers can narrow via
+ * `err.kind === 'RegistryAmbiguousTargetError'` without importing the
+ * class.
+ */
+export class RegistryAmbiguousTargetError extends Error {
+    target;
+    matches;
+    kind = 'RegistryAmbiguousTargetError';
+    constructor(target, matches) {
+        const listing = matches.map((m) => `  - ${m.name}  (${m.path})`).join('\n');
+        super(`Multiple registered repos match "${target}":\n${listing}\n` +
+            `Pass the absolute path instead to disambiguate.`);
+        this.target = target;
+        this.matches = matches;
+        this.name = 'RegistryAmbiguousTargetError';
+    }
+}
+/**
+ * Thrown by {@link assertSafeStoragePath} when a registry entry's
+ * `storagePath` does NOT point at the expected `<entry.path>/.gitnexus`
+ * subfolder. CLI destructive commands (`remove`, `clean --all`) should
+ * catch this and exit non-zero without deleting anything — the usual
+ * cause is a corrupted or hand-edited `~/.gitnexus/registry.json`, and
+ * proceeding would mean `fs.rm(recursive: true)` on whatever odd path
+ * the entry is pointing at.
+ */
+export class UnsafeStoragePathError extends Error {
+    entry;
+    expectedStoragePath;
+    actualStoragePath;
+    kind = 'UnsafeStoragePathError';
+    constructor(entry, expectedStoragePath, actualStoragePath) {
+        super(`Refusing to remove storage path for safety: expected ` +
+            `"${expectedStoragePath}" under the repo's .gitnexus subfolder, ` +
+            `but the registry entry has "${actualStoragePath}". ` +
+            `This usually means the registry entry is corrupted or was ` +
+            `hand-edited. Delete the entry manually from ~/.gitnexus/registry.json ` +
+            `and re-run analyze.`);
+        this.entry = entry;
+        this.expectedStoragePath = expectedStoragePath;
+        this.actualStoragePath = actualStoragePath;
+        this.name = 'UnsafeStoragePathError';
+    }
+}
+/**
+ * Guard rail for destructive CLI paths (`remove` #664,
+ * `clean --all` #258, future MCP `remove` tool): verify that a
+ * registry entry's `storagePath` is the canonical `<repo>/.gitnexus`
+ * subfolder of its `path`. If not, throw {@link UnsafeStoragePathError}
+ * so the caller exits without touching disk.
+ *
+ * Why this exists (#1003 review — @magyargergo):
+ *   - `~/.gitnexus/registry.json` is a plain-text user-writable file.
+ *     A corrupted, hand-edited, or downgrade/upgrade-racing entry
+ *     could plausibly end up with `storagePath === ""` (resolves to
+ *     cwd), `storagePath === path` (the repo root!), `storagePath`
+ *     equal to a parent/sibling of the repo, or simply any arbitrary
+ *     filesystem path.
+ *   - `fs.rm(recursive: true, force: true)` on ANY of those would be
+ *     a runtime disaster — at best delete the user's working tree, at
+ *     worst nuke an unrelated directory tree they happen to own.
+ *   - `clean` (default, cwd-scoped) is safe by construction — it
+ *     re-derives storagePath from `findRepo(cwd)` and never trusts
+ *     the registry field. But `clean --all` DOES iterate the registry
+ *     and trust each entry's stored storagePath (same shape as
+ *     `remove`), so this helper must be wired into that loop too.
+ *   - `server/api.ts` recomputes storagePath from `getStoragePath(entry.path)`
+ *     and so is likewise safe-by-construction.
+ *
+ * Pure string check — does NOT require the paths to exist on disk.
+ * Windows: case-insensitive; POSIX: case-sensitive. Matches the
+ * comparison shape used elsewhere in this module.
+ */
+export const assertSafeStoragePath = (entry) => {
+    const expected = path.join(path.resolve(entry.path), '.gitnexus');
+    const actual = path.resolve(entry.storagePath);
+    const matches = process.platform === 'win32'
+        ? expected.toLowerCase() === actual.toLowerCase()
+        : expected === actual;
+    if (!matches) {
+        throw new UnsafeStoragePathError(entry, expected, actual);
+    }
+};
+/**
+ * Resolve a user-supplied target string (from `gitnexus remove <target>`
+ * or equivalent MCP tool argument) to a single registry entry.
+ *
+ * Match precedence (first hit wins, subsequent tiers are only tried if
+ * the prior tier produces zero matches):
+ *   1. Exact resolved-path match (Windows: case-insensitive).
+ *      Paths are unique by registry construction, so a path match can
+ *      never be ambiguous.
+ *   2. Exact `name` match (case-insensitive). If ≥ 2 entries share the
+ *      name — only possible via `--allow-duplicate-name` (#829) —
+ *      throws {@link RegistryAmbiguousTargetError}.
+ *
+ * No fuzzy / partial matching — unambiguous, scriptable behaviour is
+ * more important than convenience for destructive commands.
+ *
+ * Throws {@link RegistryNotFoundError} if no entry matches.
+ *
+ * `entries` is passed in (rather than re-read) so callers that already
+ * hold the registry snapshot (e.g. to print a "before" state) can avoid
+ * a second disk read, and so tests can inject fixtures without touching
+ * `GITNEXUS_HOME`.
+ */
+export const resolveRegistryEntry = (entries, target) => {
+    // Tier 1: path match. Canonicalise BOTH sides so symlink and
+    // Windows-8.3 quirks don't cause a false miss — e.g. the caller
+    // passes `/var/folders/.../repo` while the registry has
+    // `/private/var/folders/.../repo` (both resolve to the same
+    // `realpath.native`). See `canonicalizePath` for the rationale.
+    //
+    // Canonicalising the STORED entry (not just the input) is what gives
+    // us backward-compat for registries written by versions that only
+    // ran `path.resolve` — both get canonicalised here at compare time.
+    const canonicalTarget = canonicalizePath(target);
+    const pathMatch = entries.find((e) => {
+        const a = canonicalizePath(e.path);
+        const b = canonicalTarget;
+        return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+    });
+    if (pathMatch)
+        return pathMatch;
+    // Tier 2: name match. Case-insensitive on all platforms — registry
+    // name collisions are already filtered case-insensitively in
+    // `registerRepo`, so "APP" vs "app" are considered the same key.
+    const targetLower = target.toLowerCase();
+    const nameMatches = entries.filter((e) => e.name.toLowerCase() === targetLower);
+    if (nameMatches.length === 1)
+        return nameMatches[0];
+    if (nameMatches.length > 1) {
+        throw new RegistryAmbiguousTargetError(target, nameMatches);
+    }
+    // Tier 3: miss. Build the available-names hint ONCE; resolveRepo-style
+    // disambiguated labels (`app (/path)`) are applied when the same name
+    // appears in multiple entries so the user sees the same hint shape as
+    // `-r <name>` errors.
+    const nameCounts = new Map();
+    for (const e of entries) {
+        const key = e.name.toLowerCase();
+        nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);
+    }
+    const availableNames = entries.map((e) => (nameCounts.get(e.name.toLowerCase()) ?? 0) > 1 ? `${e.name} (${e.path})` : e.name);
+    throw new RegistryNotFoundError(target, availableNames);
+};
 /**
  * List all registered repos from the global registry.
  * Optionally validates that each entry's .gitnexus/ still exists.
@@ -297,3 +644,38 @@ export const saveCLIConfig = async (config) => {
         }
     }
 };
+// ─── Sibling-clone detection ─────────────────────────────────────────────
+//
+// A "sibling clone" is a different on-disk path that points at the same
+// logical repository (same `origin` remote URL) as a registered index.
+// This shows up in three operationally important shapes (see issue):
+//
+//   1. The same repo is checked out under multiple paths (worktrees,
+//      multi-agent workspaces). Only one is indexed; the others silently
+//      diverge from the graph.
+//   2. The indexed clone is itself behind its own HEAD (the existing
+//      `checkStaleness` already handles this case).
+//   3. A query is issued from a `cwd` that lives inside a sibling clone
+//      whose HEAD has drifted from the indexed `lastCommit`.
+//
+// Detection is intentionally remote-URL-based and does NOT walk the
+// filesystem hunting for unregistered clones — only registered entries
+// are considered. The `cwd`-driven branch ({@link checkSiblingDrift})
+// also accepts an unregistered cwd, because the live caller's working
+// directory is the one place we can cheaply learn about an
+// unregistered clone.
+/**
+ * Find other registered entries whose `remoteUrl` matches the given
+ * one, excluding `selfPath` (case-insensitive on Windows). Entries
+ * without a `remoteUrl` are ignored — we cannot prove sibling-ness
+ * without a fingerprint.
+ */
+export const findSiblingClones = async (remoteUrl, selfPath) => {
+    if (!remoteUrl)
+        return [];
+    const entries = await readRegistry();
+    const isWin = process.platform === 'win32';
+    const norm = (p) => (isWin ? path.resolve(p).toLowerCase() : path.resolve(p));
+    const self = norm(selfPath);
+    return entries.filter((e) => e.remoteUrl === remoteUrl && norm(e.path) !== self);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.3-rc.8",
+  "version": "1.6.3",
   "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",
@@ -60,11 +60,12 @@
     "cors": "^2.8.5",
     "express": "^4.19.2",
     "glob": "^13.0.6",
-    "graphology": "^0.25.4",
+    "graphology": "^0.26.0",
     "graphology-indices": "^0.17.0",
     "graphology-utils": "^2.3.0",
     "ignore": "^7.0.5",
     "js-yaml": "^4.1.1",
+    "jsonc-parser": "^3.3.1",
     "lru-cache": "^11.0.0",
     "mnemonist": "^0.40.3",
     "onnxruntime-node": "^1.24.0",
@@ -81,7 +82,7 @@
     "tree-sitter-ruby": "^0.23.1",
     "tree-sitter-rust": "0.23.1",
     "tree-sitter-typescript": "^0.23.2",
-    "uuid": "^13.0.0"
+    "uuid": "^14.0.0"
   },
   "optionalDependencies": {
     "node-addon-api": "^8.0.0",
@@ -92,14 +93,14 @@
     "tree-sitter-swift": "^0.6.0"
   },
   "devDependencies": {
-    "gitnexus-shared": "file:../gitnexus-shared",
     "@types/cli-progress": "^3.11.6",
     "@types/cors": "^2.8.17",
     "@types/express": "^4.17.21",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^20.0.0",
-    "@types/uuid": "^10.0.0",
+    "@types/node": "^25.6.0",
+    "@types/uuid": "^11.0.0",
     "@vitest/coverage-v8": "^4.0.18",
+    "gitnexus-shared": "file:../gitnexus-shared",
     "tsx": "^4.0.0",
     "typescript": "^5.4.5",
     "vitest": "^4.0.18"

package/scripts/bench-scope-resolution.ts

@@ -0,0 +1,134 @@
+/**
+ * Synthetic benchmark for scope-resolution. Builds a large in-memory
+ * Python workspace and times runScopeResolution against it directly,
+ * isolating the resolution cost from parse / heritage / pipeline
+ * overhead.
+ *
+ * Usage: REGISTRY_PRIMARY_PYTHON=1 npx tsx scripts/bench-scope-resolution.ts
+ */
+process.env.REGISTRY_PRIMARY_PYTHON = '1';
+
+import { generateId } from '../src/lib/utils.js';
+import { createKnowledgeGraph } from '../src/core/graph/graph.js';
+import { runScopeResolution } from '../src/core/ingestion/scope-resolution/index.js';
+import { pythonScopeResolver } from '../src/core/ingestion/languages/python/scope-resolver.js';
+
+const N_CLASSES = Number(process.env.BENCH_CLASSES ?? '60');
+const N_USERS = Number(process.env.BENCH_USERS ?? '40');
+const ITERS = Number(process.env.BENCH_ITERS ?? '5');
+
+function buildWorkspace(): { path: string; content: string }[] {
+  const files: { path: string; content: string }[] = [];
+
+  // Build N_CLASSES "model" files, each defining a class with a few methods.
+  for (let i = 0; i < N_CLASSES; i++) {
+    const lines: string[] = [];
+    for (let j = 0; j < 5; j++) {
+      lines.push(`class Model${i}_${j}:`);
+      lines.push(`    name: str`);
+      lines.push(`    def save(self) -> bool:`);
+      lines.push(`        return True`);
+      lines.push(`    def update(self, name: str) -> "Model${i}_${j}":`);
+      lines.push(`        self.name = name`);
+      lines.push(`        return self`);
+      lines.push(`    def get_other(self) -> "Model${i}_${(j + 1) % 5}":`);
+      lines.push(`        return Model${i}_${(j + 1) % 5}()`);
+      lines.push('');
+    }
+    files.push({ path: `models/m${i}.py`, content: lines.join('\n') });
+  }
+
+  // Build N_USERS "user" files that import from a few model files
+  // and exercise the receiver-bound dispatcher heavily.
+  for (let u = 0; u < N_USERS; u++) {
+    const targets = [u % N_CLASSES, (u + 1) % N_CLASSES, (u + 2) % N_CLASSES];
+    const imports = targets
+      .map((t) => `from models.m${t} import Model${t}_0, Model${t}_1, Model${t}_2`)
+      .join('\n');
+    const calls: string[] = [];
+    for (let k = 0; k < 30; k++) {
+      const t = targets[k % 3]!;
+      const j = k % 3;
+      calls.push(`    m${k} = Model${t}_${j}()`);
+      calls.push(`    m${k}.save()`);
+      calls.push(`    m${k}.update("x").save()`);
+      calls.push(`    m${k}.get_other().save()`);
+    }
+    const content = `${imports}\n\ndef use_${u}() -> None:\n${calls.join('\n')}\n`;
+    files.push({ path: `app/u${u}.py`, content });
+  }
+
+  return files;
+}
+
+function buildGraph(files: { path: string; content: string }[]) {
+  const graph = createKnowledgeGraph();
+  // Pre-populate File / Class / Function nodes the resolver expects.
+  for (const f of files) {
+    const fileId = generateId('File', f.path);
+    graph.addNode({
+      id: fileId,
+      label: 'File',
+      properties: { name: f.path, filePath: f.path },
+    });
+
+    // Lightweight regex-extract class & def names so the lookup index
+    // has something to find. Real pipeline builds these via parse phase;
+    // for the bench this stand-in is enough to exercise the resolver.
+    const classRe = /^class (\w+)/gm;
+    const defRe = /^\s*def (\w+)/gm;
+    let m: RegExpExecArray | null;
+    while ((m = classRe.exec(f.content)) !== null) {
+      const name = m[1]!;
+      const id = generateId('Class', `${f.path}:${name}`);
+      graph.addNode({
+        id,
+        label: 'Class',
+        properties: { name, filePath: f.path, qualifiedName: name },
+      });
+    }
+    while ((m = defRe.exec(f.content)) !== null) {
+      const name = m[1]!;
+      const id = generateId('Function', `${f.path}:${name}`);
+      graph.addNode({
+        id,
+        label: 'Function',
+        properties: { name, filePath: f.path, qualifiedName: name },
+      });
+    }
+  }
+  return graph;
+}
+
+async function main() {
+  const files = buildWorkspace();
+  console.log(`bench: ${files.length} files (${N_CLASSES} models × 5 classes + ${N_USERS} users)`);
+  console.log(`       × ${ITERS} iterations\n`);
+
+  // Warmup
+  for (let i = 0; i < 2; i++) {
+    const graph = buildGraph(files);
+    runScopeResolution({ graph, files, onWarn: () => {} }, pythonScopeResolver);
+  }
+
+  const samples: number[] = [];
+  for (let i = 0; i < ITERS; i++) {
+    const graph = buildGraph(files);
+    const start = process.hrtime.bigint();
+    runScopeResolution({ graph, files, onWarn: () => {} }, pythonScopeResolver);
+    const end = process.hrtime.bigint();
+    const ms = Number(end - start) / 1_000_000;
+    samples.push(ms);
+    console.log(`  iter ${i + 1}: ${ms.toFixed(0)} ms`);
+  }
+
+  samples.sort((a, b) => a - b);
+  const median = samples[Math.floor(samples.length / 2)]!;
+  const min = samples[0]!;
+  console.log(`\nmin: ${min.toFixed(0)} ms · median: ${median.toFixed(0)} ms`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/scripts/ci-list-migrated-languages.ts

@@ -0,0 +1,24 @@
+/**
+ * CI helper — emits the `MIGRATED_LANGUAGES` set as a JSON matrix array for
+ * GitHub Actions (`.github/workflows/ci-scope-parity.yml`).
+ *
+ * Consumed by the `discover` job in that workflow. Each entry has:
+ *   - `slug`: lowercase language id, matching `test/integration/resolvers/<slug>.test.ts`.
+ *   - `envvar`: uppercase suffix used to build the `REGISTRY_PRIMARY_<envvar>` toggle.
+ *
+ * Run with `npx tsx scripts/ci-list-migrated-languages.ts`. The script
+ * writes a single JSON array to stdout (no wrapper object) so the
+ * workflow can pipe it straight into `$GITHUB_OUTPUT`.
+ */
+
+import { MIGRATED_LANGUAGES } from '../src/core/ingestion/registry-primary-flag.js';
+
+const entries = [...MIGRATED_LANGUAGES].map((slug) => {
+  const s = String(slug);
+  return {
+    slug: s,
+    envvar: s.toUpperCase().replace(/-/g, '_'),
+  };
+});
+
+process.stdout.write(JSON.stringify(entries));

package/skills/gitnexus-cli.md

@@ -21,6 +21,7 @@ Run from the project root. This parses all source files, builds the knowledge gr
 | -------------- | ---------------------------------------------------------------- |
 | `--force`      | Force full re-index even if up to date                           |
 | `--embeddings` | Enable embedding generation for semantic search (off by default) |
+| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. |
 
 **When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.