gitnexus 1.6.6-rc.99 → 1.6.6

package/dist/storage/scope-index-store.js

@@ -0,0 +1,236 @@
+/**
+ * Disk-backed scope store + lazy `ScopeTree` (out-of-core scope index — kernel scope-resolution
+ * out-of-core index).
+ *
+ * ## Why this exists
+ *
+ * The scope-resolution resident floor is dominated by the per-`Scope` binding
+ * payload (`Scope.bindings` / `typeBindings` / `ownedDefs`) — ~17-20 GB for one
+ * language on the Linux kernel — held in `preExtractedByPath` AND aliased by the
+ * finalize `scopeTree` through the whole emit phase. The emit passes never read
+ * `parsed.scopes` directly; they reach scopes EXCLUSIVELY through
+ * `scopeTree.getScope(id)` (a point lookup) and `getChildren(id)`. So the heavy
+ * scope payload can move to disk behind that point lookup without changing what
+ * any consumer observes: every consumer reads a `Scope` BY VALUE (its `bindings`
+ * / `ownedDefs` contents, `parent`, `range`), never by object identity.
+ *
+ * {@link persistScopeShards} writes the scopes to per-file JSON shards (one file
+ * = one shard, so a file's whole parent-chain — which never crosses filePath —
+ * stays within one shard) using the same `mapReplacer` + def-interning reviver
+ * the ParsedFile store proved byte-identical (#1983 / def-object interning). {@link DiskBackedScopeTree}
+ * serves `getScope` from a bounded LRU of decoded shards plus a small resident
+ * skeleton (`scopeId -> {shard, childIds, parent}`), so only the working set of
+ * scopes is resident, not all of them.
+ *
+ * Default-off: only constructed when `GITNEXUS_DISK_SCOPE_INDEX` is set. The
+ * resident `buildScopeTree` path is untouched otherwise.
+ */
+import { mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { buildScopeTree } from '../_shared/index.js';
+import { mapReplacer } from './parse-cache.js';
+import { makeInterningReviver } from './parsedfile-store.js';
+const STORE_DIRNAME = 'scope-index-store';
+export const getScopeIndexStoreDir = (storagePath) => path.join(storagePath, STORE_DIRNAME);
+/**
+ * Remove any prior seal's scope shards so a fresh seal starts clean. The shard
+ * names are sequential (`s<n>.json`) and the index resets per `persistScopeShards`
+ * call, so without this a seal that writes FEWER shards than a previous one (a
+ * later language with fewer files, or a later run of a shrunken repo) would leave
+ * stale tail shards on disk indefinitely — pure garbage the disk-backed tree
+ * never reads, but multi-GB on kernel-scale repos. Idempotent; synchronous to
+ * fit the main-thread seal path. Safe to call before each seal: the previously
+ * sealed language has finished emit and been released before the next seal runs,
+ * so its `DiskBackedScopeTree` never reads these shards again.
+ */
+export const clearScopeIndexStore = (storagePath) => {
+    rmSync(getScopeIndexStoreDir(storagePath), { recursive: true, force: true });
+};
+const EMPTY = Object.freeze([]);
+/**
+ * Persist `scopes` to per-file shards under `<storagePath>/scope-index-store/`
+ * and return the resident skeleton the {@link DiskBackedScopeTree} needs. Sharded
+ * by `filePath` (sequential `s<n>.json` names — no filePath→filename encoding),
+ * so one file's full scope subtree round-trips together. Synchronous: pass-A runs
+ * on the main thread and this replaces an in-heap `buildScopeTree`.
+ */
+export const persistScopeShards = (storagePath, scopes) => {
+    const dir = getScopeIndexStoreDir(storagePath);
+    // Clear first so a seal that writes fewer shards than the previous one (a
+    // later language with fewer files, or a shrunken repo on re-run) leaves no
+    // stale `s<n>.json` tail behind. See {@link clearScopeIndexStore}.
+    clearScopeIndexStore(storagePath);
+    mkdirSync(dir, { recursive: true });
+    // Group scope objects by filePath, preserving input order within a file.
+    const byFile = new Map();
+    for (const s of scopes) {
+        const bucket = byFile.get(s.filePath);
+        if (bucket)
+            bucket.push(s);
+        else
+            byFile.set(s.filePath, [s]);
+    }
+    // childIds in input order (mirrors buildScopeTree's children buckets).
+    const childIds = new Map();
+    for (const s of scopes) {
+        if (s.parent !== null) {
+            const b = childIds.get(s.parent);
+            if (b)
+                b.push(s.id);
+            else
+                childIds.set(s.parent, [s.id]);
+        }
+    }
+    const skeleton = new Map();
+    let shardIndex = 0;
+    for (const [, fileScopes] of byFile) {
+        const shard = `s${shardIndex++}.json`;
+        writeFileSync(path.join(dir, shard), JSON.stringify(fileScopes, mapReplacer), 'utf-8');
+        for (const s of fileScopes) {
+            skeleton.set(s.id, {
+                shard,
+                parent: s.parent,
+                childIds: childIds.get(s.id) ?? [],
+            });
+        }
+    }
+    return skeleton;
+};
+/**
+ * A `ScopeTree` that serves `getScope` from disk shards via a bounded LRU,
+ * holding only `maxResidentShards` decoded shards + the resident skeleton. Drop-in
+ * for the in-heap `buildScopeTree` result for the methods scope-resolution
+ * actually calls — `getScope` (the hot one), `getChildren`, `getParent`,
+ * `getAncestors`, `has`, `size`. `byId` (a full materialization) is only used by
+ * the `INGESTION_EMIT_SCOPES=1` debug path and is unsupported here — the two flags
+ * are mutually exclusive.
+ */
+export class DiskBackedScopeTree {
+    dir;
+    skeleton;
+    maxResidentShards;
+    /** Decoded shards, most-recently-used last (Map preserves insertion order). */
+    lru = new Map();
+    constructor(storagePath, skeleton, maxResidentShards = 64) {
+        this.dir = getScopeIndexStoreDir(storagePath);
+        this.skeleton = skeleton;
+        this.maxResidentShards = Math.max(1, maxResidentShards);
+    }
+    get size() {
+        return this.skeleton.size;
+    }
+    get byId() {
+        throw new Error('DiskBackedScopeTree.byId is unsupported (INGESTION_EMIT_SCOPES is incompatible with GITNEXUS_DISK_SCOPE_INDEX).');
+    }
+    has(id) {
+        return this.skeleton.has(id);
+    }
+    getChildren(id) {
+        return this.skeleton.get(id)?.childIds ?? EMPTY;
+    }
+    getScope(id) {
+        const meta = this.skeleton.get(id);
+        if (meta === undefined)
+            return undefined;
+        return this.loadShard(meta.shard).get(id);
+    }
+    getParent(id) {
+        const parent = this.skeleton.get(id)?.parent;
+        return parent === null || parent === undefined ? undefined : this.getScope(parent);
+    }
+    getAncestors(id) {
+        const out = [];
+        let cur = this.skeleton.get(id)?.parent ?? null;
+        const seen = new Set();
+        while (cur !== null && !seen.has(cur)) {
+            seen.add(cur);
+            out.push(cur);
+            cur = this.skeleton.get(cur)?.parent ?? null;
+        }
+        return out;
+    }
+    /** Load + decode a shard, touch it as MRU, evict the LRU tail past the cap. */
+    loadShard(shard) {
+        const cached = this.lru.get(shard);
+        if (cached !== undefined) {
+            // Touch: move to MRU end.
+            this.lru.delete(shard);
+            this.lru.set(shard, cached);
+            return cached;
+        }
+        const pool = new Map();
+        const defPool = new Map();
+        const raw = readFileSync(path.join(this.dir, shard), 'utf-8');
+        const fileScopes = JSON.parse(raw, makeInterningReviver(pool, defPool));
+        const decoded = new Map();
+        for (const s of fileScopes)
+            decoded.set(s.id, s);
+        this.lru.set(shard, decoded);
+        if (this.lru.size > this.maxResidentShards) {
+            const oldest = this.lru.keys().next().value;
+            if (oldest !== undefined)
+                this.lru.delete(oldest);
+        }
+        return decoded;
+    }
+}
+/**
+ * A `ScopeTree` that starts fully resident (validated by `buildScopeTree`, used
+ * by finalize / propagate / resolve, which may mutate `Scope.typeBindings` in
+ * place) and then {@link seal}s to a {@link DiskBackedScopeTree} just before emit.
+ *
+ * Sealing is what actually frees the ~17-20 GB of `Scope.bindings`: the resident
+ * tree is held BY THE MODEL'S frozen index bundle, so it cannot be swapped out
+ * from the outside. This wrapper IS that held object — `seal()` mutates its own
+ * (non-frozen) internal field to null the resident tree from the inside, after
+ * persisting it, so the model's reference now points at the disk-backed serving
+ * path and the heavy scopes become collectible (once the emit-side ParsedFiles
+ * also drop their `scopes`). Idempotent; a no-op before `seal()` keeps today's
+ * fully-resident behavior byte-identical.
+ */
+export class TransitionalScopeTree {
+    resident;
+    disk = null;
+    constructor(scopes) {
+        this.resident = buildScopeTree(scopes); // validates invariants + serves the resident phase
+    }
+    /** Persist the resident scopes, switch to disk-backed serving, and drop the
+     *  resident tree so its scope/binding payload can be reclaimed. Idempotent. */
+    seal(storagePath, maxResidentShards) {
+        if (this.disk !== null || this.resident === null)
+            return;
+        const skeleton = persistScopeShards(storagePath, [...this.resident.byId.values()]);
+        this.disk = new DiskBackedScopeTree(storagePath, skeleton, maxResidentShards);
+        this.resident = null;
+    }
+    get sealed() {
+        return this.disk !== null;
+    }
+    get active() {
+        const t = this.disk ?? this.resident;
+        if (t === null)
+            throw new Error('TransitionalScopeTree has no active backing (resident dropped without seal).');
+        return t;
+    }
+    get size() {
+        return this.active.size;
+    }
+    get byId() {
+        return this.active.byId; // throws in disk mode (DiskBackedScopeTree.byId)
+    }
+    has(id) {
+        return this.active.has(id);
+    }
+    getScope(id) {
+        return this.active.getScope(id);
+    }
+    getParent(id) {
+        return this.active.getParent(id);
+    }
+    getChildren(id) {
+        return this.active.getChildren(id);
+    }
+    getAncestors(id) {
+        return this.active.getAncestors(id);
+    }
+}

package/dist/types/pipeline.d.ts

@@ -17,9 +17,12 @@ export interface PipelineResult {
      */
     resolutionOutcomes: readonly ResolutionOutcome[];
     /**
-     * True if the parse phase spawned a worker pool for this run. False means
-     * the sequential fallback handled every chunk. Primarily a test affordance
-     * so regression suites can prove which path executed.
+     * True if a worker pool was actually constructed for this run. The worker
+     * pool is the sole parse path (sequential parsing was removed). False means
+     * no pool was needed: either there were no parseable files, or every chunk
+     * was a parse-cache hit and the cached worker output was replayed without
+     * spawning workers (a warm all-cache-hit run, #2038). Primarily a test
+     * affordance so regression suites can prove the pool engaged.
      */
     usedWorkerPool: boolean;
 }

package/hooks/antigravity/gitnexus-antigravity-hook.cjs

@@ -25,6 +25,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const { acquireHookSlot } = require('./hook-lock.cjs');
 const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs');
+const { formatAnalyzeCommand } = require('./resolve-analyze-cmd.cjs');
 
 function readInput() {
   try {
@@ -315,7 +316,7 @@ function buildStaleIndexHint(gitNexusDir, cwd) {
 
   if (currentHead === lastCommit) return '';
 
-  const analyzeCmd = `npx gitnexus analyze${hadEmbeddings ? ' --embeddings' : ''}`;
+  const analyzeCmd = formatAnalyzeCommand({ embeddings: hadEmbeddings });
   return (
     `[GitNexus] index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +
     `Run \`${analyzeCmd}\` to refresh the knowledge graph.`

package/hooks/claude/gitnexus-hook.cjs

@@ -16,6 +16,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const { acquireHookSlot } = require('./hook-lock.cjs');
 const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs');
+const { formatAnalyzeCommand } = require('./resolve-analyze-cmd.cjs');
 
 /**
  * Read JSON input from stdin synchronously.
@@ -340,7 +341,7 @@ function handlePostToolUse(input) {
   // If HEAD matches last indexed commit, no reindex needed
   if (currentHead && currentHead === lastCommit) return;
 
-  const analyzeCmd = `npx gitnexus analyze${hadEmbeddings ? ' --embeddings' : ''}`;
+  const analyzeCmd = formatAnalyzeCommand({ embeddings: hadEmbeddings });
   sendHookResponse(
     'PostToolUse',
     `GitNexus index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +

package/hooks/claude/resolve-analyze-cmd.cjs

@@ -0,0 +1,323 @@
+/**
+ * Single source of truth for how docs, hooks, and warnings invoke gitnexus.
+ *
+ * Automatically selects a working invocation path:
+ * 1. Global `gitnexus` on PATH (best — no install step)
+ * 2. npm 11+ with pnpm on PATH → `pnpm --allow-build=… dlx` (avoids the npx
+ *    arborist crash *and* pnpm 10+ ignored-build-script failures, #1939)
+ * 3. npm < 11 with npm on PATH → `npx` (works; simpler than pnpm dlx)
+ * 4. pnpm-only → `pnpm --allow-build=… dlx`
+ * 5. Last resort → `npx` (warned on npm 11+ from analyze.ts)
+ *
+ * The `--allow-build` flags MUST precede the `dlx` token. pnpm < 10.14 keeps
+ * `dlx` in its argv escape list, so flags placed *after* `dlx` are parsed as
+ * package specs (ERR_PNPM_SPEC_NOT_SUPPORTED). The pre-`dlx` position parses
+ * into dlx's allow-build option and has been honored since pnpm 10.2.0 (#1939).
+ *
+ * This stays self-contained CJS because the Claude/Antigravity hooks run as
+ * standalone files copied into the user's hook dir, where no package import is
+ * available. The CLI reuses this module from src/cli/resolve-invocation.ts via
+ * createRequire rather than re-implementing it. Two committed copies must stay
+ * byte-identical (enforced by resolve-invocation.test.ts) — edit both together:
+ * gitnexus/hooks/claude/ (the canonical copy the CLI and `gitnexus setup` read)
+ * and gitnexus-claude-plugin/hooks/. A THIRD copy is written at runtime to
+ * `<repo>/.gitnexus/run.cjs` by `gitnexus analyze` (ai-context.ts) so docs can
+ * reference it directly via the `require.main === module` exec tail below; that
+ * copy is gitignored and refreshed on every analyze, so it cannot drift for long.
+ */
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const NPX_REF = 'gitnexus@latest';
+
+// Native packages whose postinstall must run under pnpm 10+ (blocked by default).
+const PNPM_ALLOW_BUILD_BASE = ['@ladybugdb/core', 'gitnexus', 'tree-sitter'];
+const PNPM_ALLOW_BUILD_EMBEDDINGS = ['onnxruntime-node'];
+
+// Version-probe timeout, kept under Claude Code's 10s hook budget. PATH presence
+// detection is now spawn-free (resolveOnPath scans PATH directly), so the only
+// subprocesses left are the version probes: in a linked worktree the stale-index
+// hook first runs `git rev-parse --git-common-dir` (~2s) and `git rev-parse HEAD`
+// (~3s); the pnpm path then adds up to two 1s `--version` probes (npm, pnpm), so
+// the worst case is ~7s — within budget. A healthy `--version` returns in well
+// under a second, so the realistic cost is far lower.
+const PROBE_TIMEOUT_MS = 1000;
+
+/**
+ * Absolute path to `command` on PATH, or null — a pure-Node, spawn-free lookup
+ * that mirrors how a shell resolves a bare command name: each PATH dir × the
+ * platform's executable extensions (PATHEXT on Windows; the bare name + X_OK on
+ * POSIX). This replaces the former `where`/`which` subprocess (#1938 "Option A"):
+ * it is byte-for-byte identical on every OS, with no dependency on the probe
+ * binary being reachable (a sanitized PATH that drops System32 / `/usr/bin` no
+ * longer defeats detection), no shell-spawn surface (CVE-2024-27980), and no
+ * spawn timeout to tune. On Windows it matches PATHEXT extensions ONLY — exactly
+ * what `where`/cmd.exe resolve — so neither an un-spawnable `.ps1`-only shim (not
+ * in default PATHEXT) nor a bare extensionless file (which the shell cannot launch
+ * as `command`) is a false positive. `preferExecExt` returns a recognized
+ * `.cmd`/`.bat`/`.exe` shim ahead of an exotic PATHEXT hit (e.g. `.COM`) when both
+ * match, matching what a user would actually launch. Pure (platform/env injectable)
+ * so it is unit-testable without touching the host PATH.
+ */
+function resolveOnPath(
+  command,
+  preferExecExt = false,
+  { platform = process.platform, env = process.env } = {},
+) {
+  const pathValue = env.PATH || env.Path || env.path || '';
+  if (!pathValue) return null;
+  const isWin = platform === 'win32';
+  const exts = isWin
+    ? (env.PATHEXT || '.COM;.EXE;.BAT;.CMD')
+        .split(';')
+        .map((e) => e.trim())
+        .filter(Boolean)
+        .map((e) => (e.startsWith('.') ? e : `.${e}`))
+    : [''];
+  let weakHit = null;
+  // Split on the host's PATH delimiter. `platform` is injected only to choose the
+  // extension/exec-bit rules; the PATH string is always host-format, so it must
+  // split on the host delimiter (`path.delimiter`) — in production `platform` IS
+  // the host, so they coincide. (Deriving the delimiter from an injected platform
+  // would split a Windows drive-letter path `C:\…` at its colon under a POSIX
+  // injection.)
+  for (const dir of pathValue.split(path.delimiter).filter(Boolean)) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, `${command}${ext}`);
+      try {
+        if (!fs.statSync(candidate).isFile()) continue;
+        if (!isWin) fs.accessSync(candidate, fs.constants.X_OK);
+        // Prefer a runnable .cmd/.bat/.exe shim; remember an exotic PATHEXT hit
+        // (e.g. .COM) only as a last resort if nothing better turns up.
+        if (isWin && preferExecExt && !/\.(cmd|bat|exe)$/i.test(ext)) {
+          weakHit = weakHit || candidate;
+          continue;
+        }
+        return candidate;
+      } catch {
+        /* not a runnable file here — try the next candidate */
+      }
+    }
+  }
+  return weakHit;
+}
+
+// One spawn of `<command> --version` → { major, minor } (each null when
+// unreadable). Version injection happens at the resolver seam (getNpmMajorVersion
+// / formatPnpmAllowBuildArgs), so this stays a pure real-process probe.
+function probeVersion(command) {
+  try {
+    const output = execFileSync(command, ['--version'], {
+      encoding: 'utf-8',
+      timeout: PROBE_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+      // On Windows, npm/pnpm resolve to `.cmd` shims; execFileSync does no
+      // PATHEXT resolution and Node refuses to spawn `.cmd`/`.bat` without a
+      // shell (CVE-2024-27980), so a bare `<command> --version` ENOENTs and the
+      // probe would wrongly report a present tool as absent. A shell lets the OS
+      // resolve the shim. POSIX needs no shell (direct PATH lookup works).
+      shell: process.platform === 'win32',
+    });
+    // Find the first line that starts with a version token (`MAJOR.MINOR`,
+    // optional `v` prefix) rather than splitting the whole output — pnpm/npm
+    // under Corepack or with an update notice can print a banner line on stdout
+    // before the version (stderr is already dropped via the stdio config).
+    const versionLine = output
+      .split('\n')
+      .map((l) => l.trim())
+      .find((l) => /^v?\d+\.\d+/.test(l));
+    const match = versionLine ? versionLine.match(/^v?(\d+)\.(\d+)/) : null;
+    return {
+      major: match ? Number(match[1]) : null,
+      minor: match ? Number(match[2]) : null,
+    };
+  } catch {
+    return { major: null, minor: null };
+  }
+}
+
+// `deps` is the single injection seam: an explicitly provided key — including a
+// `null` value, detected via `in` — is honored as-is so tests can simulate an
+// absent tool without spawning; an absent key falls through to the real probe.
+function getNpmMajorVersion(deps = {}) {
+  return 'npmMajor' in deps ? deps.npmMajor : probeVersion('npm').major;
+}
+
+/**
+ * `--allow-build` flags for the pre-`dlx` position. Emitted for pnpm >= 10.2
+ * (where the flag exists, and pnpm 10+ blocks build scripts by default). Omitted
+ * below 10.2: pnpm < 10 runs build scripts anyway, and pnpm 10.0/10.1 lack the
+ * flag (it would be rejected as an unknown option). `alwaysAllowBuild` forces the
+ * flags for committed documentation, which cannot probe the reader's pnpm.
+ */
+function formatPnpmAllowBuildArgs(options = {}, deps = {}) {
+  if (!options.alwaysAllowBuild) {
+    const { major, minor } =
+      'pnpmMajor' in deps
+        ? { major: deps.pnpmMajor, minor: 'pnpmMinor' in deps ? deps.pnpmMinor : null }
+        : probeVersion('pnpm');
+    const lacksAllowBuild =
+      major !== null && (major < 10 || (major === 10 && minor !== null && minor < 2));
+    if (lacksAllowBuild) return [];
+  }
+  const pkgs = [...PNPM_ALLOW_BUILD_BASE];
+  if (options.embeddings) pkgs.push(...PNPM_ALLOW_BUILD_EMBEDDINGS);
+  return pkgs.map((p) => `--allow-build=${p}`);
+}
+
+/** Fixed install-free command for committed AGENTS.md / SKILL.md (pnpm >= 10.2). */
+function formatDocumentationDlxCommand(gitnexusArgs, options = {}) {
+  const flags = formatPnpmAllowBuildArgs({ ...options, alwaysAllowBuild: true }).join(' ');
+  const prefix = flags ? `${flags} ` : '';
+  return `pnpm ${prefix}dlx ${NPX_REF} ${gitnexusArgs}`;
+}
+
+/**
+ * Resolve `gitnexus` | `pnpm` | `npx`. `GITNEXUS_INVOCATION` forces a mode
+ * (test/escape hatch). `probe` is injectable so the preference order can be
+ * unit-tested without spawning; it defaults to the real PATH probe. `deps` can
+ * inject `{ npmMajor, pnpmMajor }` for tests.
+ */
+function resolveInvocationMode(probe = resolveOnPath, deps = {}) {
+  const forced = process.env.GITNEXUS_INVOCATION?.trim().toLowerCase();
+  if (forced === 'gitnexus' || forced === 'pnpm' || forced === 'npx') {
+    return forced;
+  }
+  if (probe('gitnexus', true)) return 'gitnexus';
+
+  const npmMajor = getNpmMajorVersion(deps);
+  // pnpm presence: prefer an explicit `pnpmPresent` flag (set by
+  // formatAnalyzeCommand, which falls back to a PATH probe when the version is
+  // unreadable) so a present-but-unparseable pnpm — slow probe, Corepack
+  // banner — still selects pnpm instead of the npx crash path. Otherwise an
+  // injected version (a successful `pnpm --version` proves presence)
+  // short-circuits the `which pnpm` probe; failing both, fall back to PATH.
+  const hasPnpm =
+    'pnpmPresent' in deps
+      ? deps.pnpmPresent
+      : 'pnpmMajor' in deps
+        ? deps.pnpmMajor !== null
+        : Boolean(probe('pnpm'));
+
+  // npm 11+ npx install crash (#1939) — prefer pnpm dlx when available.
+  if (hasPnpm && npmMajor !== null && npmMajor >= 11) return 'pnpm';
+  // npm 10 and earlier: npx works; prefer it over pnpm dlx when npm is present.
+  if (npmMajor !== null && npmMajor < 11) return 'npx';
+  // npm absent or unreadable — use pnpm if present (with allow-build flags).
+  if (hasPnpm) return 'pnpm';
+
+  return 'npx';
+}
+
+function formatPnpmDlxCommand(gitnexusArgs, options = {}, deps = {}) {
+  const flags = formatPnpmAllowBuildArgs(options, deps).join(' ');
+  const prefix = flags ? `${flags} ` : '';
+  return `pnpm ${prefix}dlx ${NPX_REF} ${gitnexusArgs}`;
+}
+
+function formatAnalyzeCommand(options = {}, deps = {}) {
+  const suffix = options.embeddings ? ' --embeddings' : '';
+  // Keep the stale-index hook budget tight by querying each tool at most once.
+  // The memoized `probe` is a spawn-free PATH scan (resolveOnPath) shared with
+  // resolveInvocationMode, so `gitnexus` is scanned only once and no subprocess
+  // is spawned for presence. pnpm's *version* is still captured by a single
+  // `pnpm --version` (the allow-build gate needs the number), which also proves
+  // presence; the memoized scan only re-checks pnpm when that version is
+  // unreadable. Injected deps (tests) and forced/global modes skip the pnpm probe.
+  const cache = new Map();
+  const probe = (command, gitnexusWrapper) => {
+    const key = `${command}:${gitnexusWrapper ? 1 : 0}`;
+    if (!cache.has(key)) cache.set(key, resolveOnPath(command, gitnexusWrapper));
+    return cache.get(key);
+  };
+  let resolved = deps;
+  if (!('pnpmMajor' in deps)) {
+    const forced = process.env.GITNEXUS_INVOCATION?.trim().toLowerCase();
+    // pnpm is only consulted when no non-pnpm mode is already certain: forced
+    // gitnexus/npx never use pnpm, and a present global gitnexus wins outright.
+    const mightUsePnpm = forced === 'pnpm' || (forced !== 'gitnexus' && forced !== 'npx');
+    if (mightUsePnpm && (forced === 'pnpm' || !probe('gitnexus', true))) {
+      const { major, minor } = probeVersion('pnpm');
+      // Carry presence separately from version: when the version probe fails
+      // (timeout, Corepack banner) but pnpm is on PATH, still treat it as
+      // present so mode resolution picks pnpm over the npx crash path. The
+      // PATH probe is memoized and only runs when the version is unreadable.
+      const pnpmPresent = major !== null || Boolean(probe('pnpm'));
+      resolved = { ...deps, pnpmMajor: major, pnpmMinor: minor, pnpmPresent };
+    }
+  }
+  const mode = resolveInvocationMode(probe, resolved);
+  if (mode === 'gitnexus') return `gitnexus analyze${suffix}`;
+  if (mode === 'pnpm') return `${formatPnpmDlxCommand(`analyze${suffix}`, options, resolved)}`;
+  return `npx ${NPX_REF} analyze${suffix}`;
+}
+
+/**
+ * Resolve `mode` into a concrete { program, args } pair for a set of gitnexus
+ * subcommand arguments. Shared by the direct-exec entrypoint below; pure (no
+ * spawn) so it is unit-testable. `--embeddings` widens the pnpm allow-build set.
+ */
+function buildRunnerArgv(mode, gitnexusArgs, deps = {}) {
+  // Match both the space form (`--embeddings`) and the equals form
+  // (`--embeddings=5000`) Commander accepts, so the pnpm allow-build set still
+  // widens to onnxruntime-node when a user hand-types the equals form.
+  const embeddings = gitnexusArgs.some(
+    (a) => a === '--embeddings' || a.startsWith('--embeddings='),
+  );
+  if (mode === 'gitnexus') return { program: 'gitnexus', args: [...gitnexusArgs] };
+  if (mode === 'pnpm') {
+    return {
+      program: 'pnpm',
+      args: [...formatPnpmAllowBuildArgs({ embeddings }, deps), 'dlx', NPX_REF, ...gitnexusArgs],
+    };
+  }
+  return { program: 'npx', args: [NPX_REF, ...gitnexusArgs] };
+}
+
+module.exports = {
+  formatAnalyzeCommand,
+  formatDocumentationDlxCommand,
+  formatPnpmAllowBuildArgs,
+  formatPnpmDlxCommand,
+  resolveInvocationMode,
+  buildRunnerArgv,
+  resolveOnPath,
+  getNpmMajorVersion,
+  NPX_REF,
+  PNPM_ALLOW_BUILD_BASE,
+};
+
+// Direct-exec entrypoint (#1945): `node run.cjs <gitnexus args…>` resolves the
+// best available runner (global `gitnexus` → `pnpm dlx` → `npx`) at call time and
+// runs it, inheriting stdio and propagating the child's exit code. This lets the
+// committed skills and generated AGENTS.md/CLAUDE.md reference ONE stable,
+// CLI-neutral command without baking in a package-manager assumption. `gitnexus
+// analyze` drops a copy of this file at `.gitnexus/run.cjs`. Skipped on require()
+// (the CLI and tests reuse the exports above), so it runs only when invoked as a
+// script.
+if (require.main === module) {
+  const gitnexusArgs = process.argv.slice(2);
+  const { program, args } = buildRunnerArgv(resolveInvocationMode(), gitnexusArgs);
+  try {
+    execFileSync(program, args, {
+      stdio: 'inherit',
+      windowsHide: true,
+      // On Windows, `npx`/`pnpm`/`gitnexus` resolve to `.cmd`/`.ps1`/`.exe`
+      // shims (npm, Volta, Corepack, scoop). execFileSync does not do PATHEXT
+      // resolution and Node refuses to spawn `.cmd`/`.bat` without a shell
+      // (CVE-2024-27980), so a bare program name ENOENTs. A shell lets the OS
+      // resolve the shim; POSIX needs no shell (direct PATH lookup works).
+      shell: process.platform === 'win32',
+    });
+  } catch (err) {
+    // Make spawn failures (resolved program absent from PATH) self-explanatory
+    // instead of a silent exit 1, then propagate the runner's own exit code.
+    if (typeof err.status !== 'number') {
+      process.stderr.write(`gitnexus runner: could not launch \`${program}\` — ${err.message}\n`);
+    }
+    process.exit(typeof err.status === 'number' ? err.status : 1);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.6-rc.99",
+  "version": "1.6.6",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -48,7 +48,6 @@
     "test:integration": "vitest run test/integration",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "test:parity": "tsx scripts/run-parity.ts",
     "test:cross-platform": "tsx scripts/run-cross-platform.ts",
     "postinstall": "node scripts/materialize-vendor-grammars.cjs && node scripts/build-tree-sitter-dart.cjs && node scripts/build-tree-sitter-proto.cjs && node scripts/build-tree-sitter-swift.cjs",
     "prepare": "node scripts/build.js",
@@ -56,7 +55,7 @@
   },
   "dependencies": {
     "@huggingface/transformers": "^4.1.0",
-    "@ladybugdb/core": "^0.16.1",
+    "@ladybugdb/core": "^0.17.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@scarf/scarf": "^1.4.0",
     "cli-progress": "^3.12.0",
@@ -71,13 +70,13 @@
     "ignore": "^7.0.5",
     "js-yaml": "^4.1.1",
     "jsonc-parser": "^3.3.1",
-    "lru-cache": "^11.0.0",
     "mnemonist": "^0.40.3",
+    "onnxruntime-common": "^1.26.0",
     "onnxruntime-node": "^1.24.0",
     "pandemonium": "^2.4.0",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
-    "tree-sitter": "^0.21.1",
+    "tree-sitter": "0.21.1",
     "tree-sitter-c": "0.21.4",
     "tree-sitter-c-sharp": "0.23.1",
     "tree-sitter-cpp": "0.23.2",

package/scripts/bench-scope-resolution.ts

@@ -4,10 +4,8 @@
  * isolating the resolution cost from parse / heritage / pipeline
  * overhead.
  *
- * Usage: REGISTRY_PRIMARY_PYTHON=1 npx tsx scripts/bench-scope-resolution.ts
+ * Usage: 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';