This repository has been archived on 2026-11-17. You can view files and clone it, but cannot push or open issues or pull requests.
gitgram-ai/aitimemachine/gitnexus/test/unit/embedding-runtime-support.test.ts
caelum0x 49b183818c Unify gitgram + aitimemachine into the monorepo (de-submodule) and merge vendored engines
Convert gitgram/ and aitimemachine/ from embedded git repos (which showed as
opaque submodule gitlinks on GitHub) into fully-tracked first-party content.

AITM now merges its 7 vendored repos as first-party engines:
- memory: beads (Go task DAG) + context7 (docs SDK), unified into saved_contexts
- git: vendored C git (bundled binary) + gitnexus (in-process code intelligence)
- agentic: a2a (@a2a-js/sdk) + pal (AITM-managed Python subprocess)

Includes the full session's product build: Gitgram web/mobile/backend features,
AITM website/CLI/MCP, the unified memory layer, engine build tooling
(scripts/build-engines.sh, Dockerfile, CI), docs (README, ENGINES.md, ARCHITECTURE.md),
and extensive test suites.

Build artifacts, node_modules, external/, and gemini-cli are gitignored.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-23 14:14:09 +03:00

273 lines
10 KiB
TypeScript

import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import {
getLocalEmbeddingRuntimeBlocker,
isLocalEmbeddingRuntimeBlockerMessage,
} from '../../src/core/embeddings/runtime-support.js';
/**
* Spy that fires whenever @huggingface/transformers is actually imported.
* Hoisted so the vi.mock factory below can reference it. The mock replaces the
* real module entirely, so this suite never loads onnxruntime-node — it is safe
* to run on any platform, including hosts without the native binding.
*/
const { transformersImported } = vi.hoisted(() => ({ transformersImported: vi.fn() }));
vi.mock('@huggingface/transformers', () => {
transformersImported();
const fakePipeline: any = async () => ({ data: new Float32Array(384) });
return {
pipeline: vi.fn(async () => fakePipeline),
env: { allowLocalModels: true, cacheDir: '', remoteHost: '' },
};
});
const EMBED_ENV_KEYS = [
'GITNEXUS_EMBEDDING_URL',
'GITNEXUS_EMBEDDING_MODEL',
'GITNEXUS_EMBEDDING_API_KEY',
'GITNEXUS_EMBEDDING_DIMS',
] as const;
const savedEnv = Object.fromEntries(EMBED_ENV_KEYS.map((k) => [k, process.env[k]]));
/** Stub process.platform/arch via DI-friendly defineProperty; returns a restore fn. */
const stubPlatform = (platform: NodeJS.Platform, arch: NodeJS.Architecture): (() => void) => {
const orig = { platform: process.platform, arch: process.arch };
Object.defineProperty(process, 'platform', { value: platform, configurable: true });
Object.defineProperty(process, 'arch', { value: arch, configurable: true });
return () => {
Object.defineProperty(process, 'platform', { value: orig.platform, configurable: true });
Object.defineProperty(process, 'arch', { value: orig.arch, configurable: true });
};
};
beforeEach(() => {
vi.resetModules();
transformersImported.mockClear();
for (const key of EMBED_ENV_KEYS) delete process.env[key];
});
afterEach(() => {
vi.unstubAllGlobals();
for (const key of EMBED_ENV_KEYS) {
if (savedEnv[key] === undefined) delete process.env[key];
else process.env[key] = savedEnv[key];
}
});
describe('getLocalEmbeddingRuntimeBlocker', () => {
it('blocks darwin/x64 (macOS Intel)', () => {
expect(getLocalEmbeddingRuntimeBlocker({ platform: 'darwin', arch: 'x64' })).not.toBeNull();
});
it('returns null for darwin/arm64, linux/x64, and win32/x64', () => {
expect(getLocalEmbeddingRuntimeBlocker({ platform: 'darwin', arch: 'arm64' })).toBeNull();
expect(getLocalEmbeddingRuntimeBlocker({ platform: 'linux', arch: 'x64' })).toBeNull();
expect(getLocalEmbeddingRuntimeBlocker({ platform: 'win32', arch: 'x64' })).toBeNull();
});
it('explains macOS Intel, local embeddings, the ONNX native binding, and safe alternatives', () => {
const msg = getLocalEmbeddingRuntimeBlocker({ platform: 'darwin', arch: 'x64' });
expect(msg).not.toBeNull();
const text = msg as string;
// What failed
expect(text).toMatch(/macOS Intel/);
expect(text).toMatch(/local semantic embeddings/i);
expect(text).toMatch(/ONNX/);
expect(text).toMatch(/native binding/i);
// Does NOT imply wasm rescues it, and does NOT leak the raw native error
expect(text).toMatch(/wasm does not help/i);
expect(text).not.toMatch(/Cannot find module/);
// Safe alternatives
expect(text).toMatch(/without --embeddings/);
expect(text).toContain('GITNEXUS_EMBEDDING_URL');
expect(text).toMatch(/Linux or in Docker/);
expect(text).toMatch(/Apple Silicon/);
// Addresses the GitNexus device knob too, not only ONNX_WEB_BACKEND (R3 / #1987)
expect(text).toContain('GITNEXUS_EMBEDDING_DEVICE');
});
it('reads platform/arch from process when no options are given', () => {
// Stub the process so the no-arg call must consult process.platform/arch —
// this falsifiably exercises the `?? process.platform` / `?? process.arch`
// fallback (a plain null === null on the CI host would not).
const restoreBlocked = stubPlatform('darwin', 'x64');
try {
expect(getLocalEmbeddingRuntimeBlocker()).not.toBeNull();
expect(getLocalEmbeddingRuntimeBlocker()).toBe(
getLocalEmbeddingRuntimeBlocker({ platform: 'darwin', arch: 'x64' }),
);
} finally {
restoreBlocked();
}
const restoreSupported = stubPlatform('linux', 'x64');
try {
expect(getLocalEmbeddingRuntimeBlocker()).toBeNull();
} finally {
restoreSupported();
}
});
});
describe('isLocalEmbeddingRuntimeBlockerMessage', () => {
it('recognises the blocker message and rejects unrelated errors', () => {
const blocker = getLocalEmbeddingRuntimeBlocker({ platform: 'darwin', arch: 'x64' }) as string;
expect(isLocalEmbeddingRuntimeBlockerMessage(blocker)).toBe(true);
expect(isLocalEmbeddingRuntimeBlockerMessage('ECONNREFUSED while downloading model')).toBe(
false,
);
expect(
isLocalEmbeddingRuntimeBlockerMessage(
"Cannot find module '../bin/.../onnxruntime_binding.node'",
),
).toBe(false);
});
});
describe('lazy transformers.js import', () => {
it('control: the spy fires when transformers.js is actually imported', async () => {
expect(transformersImported).not.toHaveBeenCalled();
await import('@huggingface/transformers');
expect(transformersImported).toHaveBeenCalled();
});
it('importing the guard module does not import transformers.js', async () => {
await import('../../src/core/embeddings/runtime-support.js');
expect(transformersImported).not.toHaveBeenCalled();
});
it('importing the core embedder does not import transformers.js at module load', async () => {
await import('../../src/core/embeddings/embedder.js');
expect(transformersImported).not.toHaveBeenCalled();
});
it('importing the MCP embedder does not import transformers.js at module load', async () => {
await import('../../src/mcp/core/embedder.js');
expect(transformersImported).not.toHaveBeenCalled();
});
});
describe('initEmbedder local-runtime guard (darwin/x64)', () => {
it('rejects the core initEmbedder before importing transformers.js', async () => {
const restore = stubPlatform('darwin', 'x64');
try {
const { initEmbedder } = await import('../../src/core/embeddings/embedder.js');
await expect(initEmbedder()).rejects.toThrow(/macOS Intel/);
// The guard must short-circuit before the lazy transformers.js import.
expect(transformersImported).not.toHaveBeenCalled();
} finally {
restore();
}
});
it('rejects with a clean GitNexus message, not the raw native module error', async () => {
const restore = stubPlatform('darwin', 'x64');
try {
const { initEmbedder } = await import('../../src/core/embeddings/embedder.js');
const err = (await initEmbedder().catch((e) => e)) as Error;
expect(err.message).toMatch(/native binding/i);
expect(err.message).not.toMatch(/Cannot find module/);
expect(err.message).not.toMatch(/onnxruntime_binding/);
} finally {
restore();
}
});
it('rejects the MCP initEmbedder before importing transformers.js', async () => {
const restore = stubPlatform('darwin', 'x64');
try {
const { initEmbedder } = await import('../../src/mcp/core/embedder.js');
await expect(initEmbedder()).rejects.toThrow(/macOS Intel/);
expect(transformersImported).not.toHaveBeenCalled();
} finally {
restore();
}
});
});
describe('HTTP embedding mode on darwin/x64', () => {
it('is not blocked by the local-runtime guard and never touches the native runtime', async () => {
process.env.GITNEXUS_EMBEDDING_URL = 'http://test:8080/v1';
process.env.GITNEXUS_EMBEDDING_MODEL = 'test-model';
const mockVec = Array.from({ length: 384 }, (_, i) => i / 384);
// Size the response to the request's `input` length so both the single
// (embedText) and batched (embedBatch) calls get matching vector counts.
vi.stubGlobal(
'fetch',
vi.fn(async (_url: string, init: { body: string }) => {
const n = (JSON.parse(init.body) as { input: string[] }).input.length;
return {
ok: true,
json: async () => ({ data: Array.from({ length: n }, () => ({ embedding: mockVec })) }),
};
}),
);
const restore = stubPlatform('darwin', 'x64');
try {
const { embedText, embedBatch, isEmbedderReady } =
await import('../../src/core/embeddings/embedder.js');
// HTTP mode is ready without any local/native initialization.
expect(isEmbedderReady()).toBe(true);
const single = await embedText('hello from macOS Intel');
expect(single).toBeInstanceOf(Float32Array);
expect(single.length).toBe(384);
const batch = await embedBatch(['a', 'b']);
expect(batch).toHaveLength(2);
// HTTP embeddings must route through fetch, never the local ONNX runtime.
expect(fetch).toHaveBeenCalled();
expect(transformersImported).not.toHaveBeenCalled();
} finally {
restore();
}
});
});
describe('MCP embedQuery on darwin/x64', () => {
it('routes HTTP mode through httpEmbedQuery without importing transformers.js', async () => {
process.env.GITNEXUS_EMBEDDING_URL = 'http://test:8080/v1';
process.env.GITNEXUS_EMBEDDING_MODEL = 'test-model';
const mockVec = Array.from({ length: 384 }, (_, i) => i / 384);
vi.stubGlobal(
'fetch',
vi.fn(async () => ({
ok: true,
json: async () => ({ data: [{ embedding: mockVec }] }),
})),
);
const restore = stubPlatform('darwin', 'x64');
try {
const { embedQuery } = await import('../../src/mcp/core/embedder.js');
const vec = await embedQuery('query from macOS Intel');
// httpEmbedQuery validates against the default 384 dims (no GITNEXUS_EMBEDDING_DIMS
// set), so the reused stub stays 384-length; resize the stub + DIMS together to vary it.
expect(Array.isArray(vec)).toBe(true);
expect(vec).toHaveLength(384);
expect(fetch).toHaveBeenCalled();
expect(transformersImported).not.toHaveBeenCalled();
} finally {
restore();
}
});
it('rejects local mode before importing transformers.js', async () => {
// No GITNEXUS_EMBEDDING_* env (cleared in beforeEach) → local mode → embedQuery
// calls initEmbedder, which throws the guard before the lazy transformers import.
const restore = stubPlatform('darwin', 'x64');
try {
const { embedQuery } = await import('../../src/mcp/core/embedder.js');
await expect(embedQuery('query from macOS Intel')).rejects.toThrow(/macOS Intel/);
expect(transformersImported).not.toHaveBeenCalled();
} finally {
restore();
}
});
});