fix(embeddings): resolve onnxruntime-common under pnpm-strict / pnpm dlx (#307)

[magyargergo]

The bug (#307 / #2069)

pnpm dlx gitnexus@latest analyze --embeddings (and pnpm add -g strict installs) crash with:

Cannot find package 'onnxruntime-common' imported from
.../@huggingface/transformers/dist/transformers.node.mjs

@huggingface/transformers@4.2.0 does a bare import 'onnxruntime-common' from its shipped transformers.node.mjs, but never declares onnxruntime-common in its own dependencies (it lists onnxruntime-node / onnxruntime-web / sharp). It's a phantom dependency: npm's flat node_modules — and pnpm with hoisting — place it on transformers' resolution path by accident, so the import resolves. Under pnpm's isolated store a package only sees its declared deps, so the import dies.

Why #2074 didn't fix it for pnpm

#2074 declared onnxruntime-common in gitnexus' own deps. Node resolves the bare specifier from transformers' module scope, not ours, so a sibling-scope declaration is invisible to it under pnpm-strict. Verified empirically against real pnpm installs (10.x and 11.x): under default hoisting the import already resolves (so most users are fine, and #2074 only changes which onnxruntime-common version wins the hoist); under a non-hoisting / strict layout it fails even with #2074.

The fix

Install a synchronous, in-thread ESM resolution hook (module.registerHooks) immediately before the lazy import('@huggingface/transformers'). The hook:

• tries normal resolution first and only redirects onnxruntime-common when the default resolver fails — so on npm / hoisted layouts it never fires and behaviour is unchanged;
• redirects to the copy gitnexus depends on (a direct dep since fix: declare onnxruntime-common runtime dependency #2074; onnxruntime-common is a stable pure-JS package whose Tensor API is unchanged across 1.24–1.26, version-aligned with the onnxruntime-node transformers loads), always resolvable from gitnexus' own scope regardless of how the consumer's package manager linked things;
• only ever touches the exact onnxruntime-common specifier on failure, so it can't mask an unrelated resolution error. onnxruntime-node's native binding still loads normally from transformers' own scope.

Installation is idempotent, best-effort, and lazy — only on the local-embedding code path, so it never affects analysis, the parse workers, or HTTP embedding mode. If anything goes wrong it's swallowed and embeddings proceed exactly as before.

Why registerHooks (and not register, or bundling)

• module.register() (async, off-thread) is deprecated — DEP0205, slated for removal in Node 26 — and would force a separate hook module + cross-thread data plumbing. module.registerHooks() is the supported replacement: one inline synchronous closure, no separate file, no worker thread. It's available on Node ≥ 22.15; gitnexus' engine floor is >=22.0.0, so on older 22.x the helper is a graceful no-op (the import still resolves on hoisted layouts there). I kept the floor at >=22.0.0 rather than bumping the whole package's engines for one best-effort fallback.
• Bundling transformers with esbuild was rejected: the build is tsc-only, and transformers carries a native onnxruntime-node binding + WASM onnxruntime-web assets that bundle poorly.

Validation

• End-to-end with the compiled code: the real dist/ resolver fixes a genuine pnpm hoist=false transformers install — ERR_MODULE_NOT_FOUND → resolved.
• Embedding unit tests pass (tsc --noEmit clean). New unit test covers the resolve closure's redirect / passthrough / rethrow logic, one-shot installation, and graceful degradation when registerHooks is unavailable.

Scope / what this does NOT cover

The separate @ladybugdb/core native-binary failure under pure pnpm dlx/pnpx (its lbugjs.node is staged by a postinstall that ephemeral runners skip) is unchanged — owned upstream in @ladybugdb/core, and #1967 already makes it fail gracefully. This PR restores --embeddings under pnpm-strict / global installs.

Suggested follow-ups (not in this PR)

• Reopen analyze fails under pnpm: transformers@4.2.0 imports undeclared onnxruntime-common #2069 (closed by fix: declare onnxruntime-common runtime dependency #2074, which doesn't cover the pnpm-strict case).
• Short README note for pnpm users.
• The definitive upstream fix is huggingface/transformers.js#1087 (declare onnxruntime-common).

🤖 Generated with Claude Code

[vercel]

@magyargergo is attempting to deploy a commit to the NexusCore Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

✨ PR Autofix

Found fixable formatting / unused-import issues across 16 changed lines. Comment /autofix on this PR to apply them, or run npm run lint:fix && npm run format locally.

{"schema":"gitnexus.pr-autofix/v2","state":"fixes-available","pr_number":2139,"changed_lines":16,"head_sha":"33654364f5dd33410160f991b8c44a3dca0f2c7a","run_id":"27264946037","apply_command":"/autofix"}

[github-actions]

CI Report

✅ All checks passed

Pipeline Status

Stage	Status	Details
✅ Typecheck	success	tsc --noEmit
✅ Tests	success	unit tests, 3 platforms
✅ E2E	success	gitnexus-web changes only

Test Results

Tests	Passed	Failed	Skipped	Duration
10993	10977	0	16	564s

✅ All 10977 tests passed

16 test(s) skipped — expand for details

• COBOL pipeline benchmark > scales with file count
• C++ ADL emit benchmark > emit phase scales sub-quadratically with co-scaled files and sites
• C++ pipeline benchmark > scales with file count
• C# pipeline benchmark > scales with file count — namespaces spread across the solution
• C# pipeline benchmark > scales with file count — all types in one (global) namespace bucket
• C# pipeline benchmark > scales with file count — all types in one (named) namespace bucket
• Go pipeline benchmark > scales with file count (workers enabled)
• Go pipeline benchmark — worker pool (issue Worker idle timeout kills long Go scope extraction and surfaces as Napi::Error during analyze #1848) > does not quarantine the large generated Go file on sub-batch idle timeout
• Go structural interface detection benchmark > scales linearly with interface × struct count
• Go structural interface detection split-phase benchmark > separates index-build and detection time
• PHP pipeline benchmark > scales with file count (workers enabled)
• Ruby pipeline benchmark > scales with file count (workers enabled)
• Rust pipeline benchmark > scales with file count (workers enabled)
• Vue pipeline benchmark > scales with component count
• run.cjs direct-exec entrypoint (fix(cli): steer docs, skills, and hooks through a CLI-neutral project-local runner (#1939) #1945) > resolves a .cmd shim via the Windows shell branch, passing args and exit code
• buildTypeEnv > known limitations (documented skip tests) > Ruby block parameter: users.each { |user| } — closure param inference, different feature

Code Coverage

Tests

Metric	Coverage	Covered	Base	Delta	Status
Statements	75.27%	35909/47702	N/A%	—	🟢 ███████████████░░░░░
Branches	63.05%	22250/35286	N/A%	—	🟢 ████████████░░░░░░░░
Functions	80.98%	3872/4781	N/A%	—	🟢 ████████████████░░░░
Lines	79.07%	32467/41061	N/A%	—	🟢 ███████████████░░░░░

---

_{📋 View full run · Generated by CI}

[magyargergo]

Tri-review of #2139 — onnxruntime-common pnpm-strict fix

3 methods: GitNexus swarm + Compound-Engineering personas + Codex. Engine breakdown: 6 Claude lanes + Codex (the one independent engine; live). Independence is asymmetric — Claude-lane agreement is "consistent across personas," not independent confirmation; the strong signal is Codex agreeing with a Claude lane.

The fix is sound — no P0/P1

The correctness and adversarial lanes empirically executed the redirect on Node 22.16 against the real installed packages and refuted the scariest hypotheses:

• No new dual-instance Tensor identity break — the redirect makes transformers use the same CJS onnxruntime-common build that onnxruntime-node already loads, and the feed path into InferenceSession.run is duck-typed, not instanceof-gated. (Codex raised this as a P2; two Claude lanes ran it and refuted it.)
• The CJS-entry redirect still yields the named Tensor export via cjs-module-lexer; and (correctness lane) omitting format is safe because onnxruntime-common ships a nested dist/cjs/package.json {"type":"commonjs"}.
• The helper is fully wrapped in try/catch, so a failure degrades to a logged no-op rather than throwing into the embedder (that swallow path is itself untested — see Test gaps).

Inline findings (2)

See the two inline comments (:70, :79).

Body / lower-priority (not inlined)

• [P2] Test gap (test/CI + testing lanes): the resolver's outer try/catch swallow path is untested. The reason given for dropping the test (vitest surfaces a throwing mock) applies to a throwing factory, not a throwing spy — verified loadResolver(vi.fn(() => { throw … })) + not.toThrow() passes. Worth adding.
• [P3] Weak test assertion (onnxruntime-common-resolver.test.ts): /^file:\/\/.*onnxruntime-common/ matches loosely; anchor to /node_modules/onnxruntime-common/.
• [P3] __resetOnnxRuntimeCommonResolverForTests is effectively a no-op after vi.resetModules() + a fresh import (maintainability + testing lanes) — consider removing the seam.
• [P3] Comment overstates isolation: "never affects other tools' resolution" — the hook is process-global and fires (cheaply, inert) for every resolution in the long-lived MCP server (adversarial; Codex refuted any real overhead concern).
• [design] Node 22.0–22.14: registerHooks needs ≥22.15 while the engines floor is ≥22.0.0, so the fix is a silent no-op there (documented in the file; registerHooks is also @experimental).
• Refuted/contested: the adversarial lane raised "attempted=true before the try poisons the fallback on a transient require.resolve failure"; Codex refuted it (a failed require.resolve has no valid redirect target to retry anyway).

CI

Real test/build checks pending as of a880f31b; the Vercel fail is deploy-auth, not code. The PR head is a "Merge main" commit (branch updated with main) — verified the net PR diff is exactly the 4 source files (merge-base 7eaeb0a0; 425809cf..HEAD shows no change to those 4 files).

Automated multi-tool digest (GitNexus swarm + CE personas + Codex) — verify before acting.

[magyargergo]

[P2 · code-read · Codex + adversarial converge] Redirect version can skew from the native binding under pnpm dlx, and the comment at :25 is inaccurate.

The comment claims the redirected copy is "version-aligned with the onnxruntime-node transformers loads." But gitnexus' npm-style overrides block (which pins onnxruntime-node) is honored only from the root manifest — so under pnpm dlx/pnpx, where gitnexus is a transitive dep, it does not apply. transformers then loads its own pinned onnxruntime-node@1.24.3 (→ wants onnxruntime-common@1.24.3) while require.resolve('onnxruntime-common') here supplies gitnexus' ^1.26.0.

Not a current bug — it works because the Tensor feed surface is stable/duck-typed across 1.24–1.26 (verified). But the comment's rationale is wrong, and the skew is latent on every onnxruntime-common bump.

• Confirmed defect: correct the :25 comment.
• Recommended hardening: resolve the redirect target from onnxruntime-node's own scope (the version the native binding actually expects), falling back to gitnexus' copy.

[magyargergo]

[P3 · code-read · Codex + correctness + adversarial] catch {} is too broad.

This swallows every error from nextResolve for the onnxruntime-common specifier — not just ERR_MODULE_NOT_FOUND — and redirects. A genuinely present-but-broken install (e.g. ERR_PACKAGE_PATH_NOT_EXPORTED, a corrupt exports map) would be silently papered over with gitnexus' copy instead of surfaced.

Narrow it:

} catch (err) {
  if (err?.code === 'ERR_MODULE_NOT_FOUND' || err?.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
    return { url: redirectUrl, shortCircuit: true };
  }
  throw err;
}