@nomos-arc/arc 0.1.0

package/src/search/__tests__/embedder.test.ts

@@ -0,0 +1,267 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Embedder } from '../embedder.js';
+import { NomosError } from '../../core/errors.js';
+import type { Logger } from 'winston';
+import type { NomosConfig } from '../../types/index.js';
+
+// ─── Mocks ────────────────────────────────────────────────────────────────────
+// vi.mock() is hoisted to the top of the file before any variable declarations.
+// vi.hoisted() ensures mock references are created at hoist-time so the factory
+// can close over them.
+
+const { mockEmbedContent, mockBatchEmbedContents, mockGetGenerativeModel } = vi.hoisted(() => {
+  const mockEmbedContent = vi.fn();
+  const mockBatchEmbedContents = vi.fn();
+  const mockGetGenerativeModel = vi.fn(() => ({
+    embedContent: mockEmbedContent,
+    batchEmbedContents: mockBatchEmbedContents,
+  }));
+  return { mockEmbedContent, mockBatchEmbedContents, mockGetGenerativeModel };
+});
+
+vi.mock('@google/generative-ai', () => ({
+  // Regular function required: arrow functions cannot be called with `new`
+  GoogleGenerativeAI: vi.fn(function () {
+    return { getGenerativeModel: mockGetGenerativeModel };
+  }),
+}));
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+const DIMS = 768;
+
+function makeConfig(overrides: Partial<NomosConfig['search']> = {}): NomosConfig['search'] {
+  return {
+    embedding_model: 'gemini-embedding-001',
+    embedding_dimensions: DIMS,
+    vector_store_path: '.nomos/vectors',
+    default_top_k: 10,
+    default_threshold: 0.7,
+    batch_size: 3,
+    embedding_requests_per_minute: 60,
+    request_timeout_ms: 30_000,
+    ...overrides,
+  };
+}
+
+function makeLogger(): Logger {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  } as unknown as Logger;
+}
+
+function makeVector(dims = DIMS, fill = 0): number[] {
+  return Array.from({ length: dims }, (_, i) => fill || i * 0.001);
+}
+
+function makeEmbedResponse(dims = DIMS) {
+  return { embedding: { values: makeVector(dims) } };
+}
+
+function makeBatchResponse(count: number, dims = DIMS) {
+  return { embeddings: Array.from({ length: count }, () => ({ values: makeVector(dims) })) };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('Embedder', () => {
+  let config: NomosConfig['search'];
+  let logger: Logger;
+
+  beforeEach(() => {
+    config = makeConfig();
+    logger = makeLogger();
+    vi.stubEnv('GEMINI_API_KEY', 'test-api-key-12345');
+    mockEmbedContent.mockReset();
+    mockBatchEmbedContents.mockReset();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllEnvs();
+  });
+
+  // ── Test 7: API key missing ──────────────────────────────────────────────────
+
+  it('throws search_api_key_missing when GEMINI_API_KEY is unset', () => {
+    vi.unstubAllEnvs();
+    delete process.env['GEMINI_API_KEY'];
+
+    expect(() => new Embedder(config, logger)).toThrow(
+      expect.objectContaining({ code: 'search_api_key_missing' }),
+    );
+  });
+
+  // ── Test 1: embedOne() calls Gemini and returns Float32Array ─────────────────
+
+  it('embedOne() calls Gemini API with correct model and returns Float32Array', async () => {
+    mockEmbedContent.mockResolvedValueOnce(makeEmbedResponse());
+    const embedder = new Embedder(config, logger);
+
+    const runPromise = embedder.embedOne('hello world');
+    await vi.runAllTimersAsync();
+    const result = await runPromise;
+
+    expect(mockGetGenerativeModel).toHaveBeenCalledWith({
+      model: 'gemini-embedding-001',
+    }, undefined);
+    expect(mockEmbedContent).toHaveBeenCalledTimes(1);
+    expect(result).toBeInstanceOf(Float32Array);
+    expect(result.length).toBe(DIMS);
+  });
+
+  // ── Test 9: dimensions match config ─────────────────────────────────────────
+
+  it('dimensions getter returns config.embedding_dimensions and vector matches', async () => {
+    mockEmbedContent.mockResolvedValueOnce(makeEmbedResponse(DIMS));
+    const embedder = new Embedder(config, logger);
+
+    expect(embedder.dimensions).toBe(DIMS);
+    expect(embedder.dimensions).toBe(config.embedding_dimensions);
+
+    const runPromise = embedder.embedOne('test');
+    await vi.runAllTimersAsync();
+    const vector = await runPromise;
+    expect(vector.length).toBe(DIMS);
+  });
+
+  // ── Test 2: embedBatch() splits into chunks and processes sequentially ───────
+
+  it('embedBatch() splits texts into batch_size chunks and processes sequentially', async () => {
+    const texts = ['a', 'b', 'c', 'd', 'e'];  // batch_size=3 → 2 batches
+    // First batch: 3 texts, second batch: 2 texts
+    mockBatchEmbedContents
+      .mockResolvedValueOnce(makeBatchResponse(3))
+      .mockResolvedValueOnce(makeBatchResponse(2));
+
+    const embedder = new Embedder(config, logger);
+    const runPromise = embedder.embedBatch(texts);
+    await vi.runAllTimersAsync();
+    const results = await runPromise;
+
+    expect(mockBatchEmbedContents).toHaveBeenCalledTimes(2);
+    expect(results).toHaveLength(5);
+    results.forEach(v => expect(v).toBeInstanceOf(Float32Array));
+  });
+
+  // ── Test 3: embedBatch() respects rate-limit delay between batches ───────────
+
+  it('embedBatch() inserts rate-limit delay between batches', async () => {
+    const rpm = 60;
+    const expectedDelay = Math.ceil(60_000 / rpm); // 1000ms
+    const cfg = makeConfig({ embedding_requests_per_minute: rpm });
+
+    const texts = ['a', 'b', 'c', 'd'];  // 2 batches of 3
+    mockBatchEmbedContents
+      .mockResolvedValueOnce(makeBatchResponse(3))
+      .mockResolvedValueOnce(makeBatchResponse(1));
+
+    const embedder = new Embedder(cfg, logger);
+    const runPromise = embedder.embedBatch(texts);
+
+    // First batch completes immediately; second needs the delay to pass
+    await vi.advanceTimersByTimeAsync(expectedDelay + 100);
+    await runPromise;
+
+    expect(mockBatchEmbedContents).toHaveBeenCalledTimes(2);
+  });
+
+  // ── Test 4: rate-limit delay is logged [S-8] ─────────────────────────────────
+
+  it('embedBatch() logs rate-limit wait message between batches [S-8]', async () => {
+    const texts = ['a', 'b', 'c', 'd'];  // 2 batches with batch_size=3
+    mockBatchEmbedContents
+      .mockResolvedValueOnce(makeBatchResponse(3))
+      .mockResolvedValueOnce(makeBatchResponse(1));
+
+    const embedder = new Embedder(config, logger);
+    const runPromise = embedder.embedBatch(texts);
+    await vi.runAllTimersAsync();
+    await runPromise;
+
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringMatching(/\[nomos:search:warn\] Rate limiting\. Waiting \d+ms before batch 2\/2/),
+    );
+  });
+
+  // ── Test 10: onBatchComplete callback fires after each batch ─────────────────
+
+  it('onBatchComplete callback fires after each batch', async () => {
+    const texts = ['a', 'b', 'c', 'd', 'e'];
+    mockBatchEmbedContents
+      .mockResolvedValueOnce(makeBatchResponse(3))
+      .mockResolvedValueOnce(makeBatchResponse(2));
+
+    const onBatchComplete = vi.fn();
+    const embedder = new Embedder(config, logger);
+    const runPromise = embedder.embedBatch(texts, onBatchComplete);
+    await vi.runAllTimersAsync();
+    await runPromise;
+
+    expect(onBatchComplete).toHaveBeenCalledTimes(2);
+    expect(onBatchComplete).toHaveBeenNthCalledWith(1, 0, 2);
+    expect(onBatchComplete).toHaveBeenNthCalledWith(2, 1, 2);
+  });
+
+  // ── Test 5: retries on 429 with exponential backoff ──────────────────────────
+
+  it('embedOne() retries on 429 error with exponential backoff', async () => {
+    const error429 = new Error('Request failed with status 429');
+    mockEmbedContent
+      .mockRejectedValueOnce(error429)
+      .mockRejectedValueOnce(error429)
+      .mockResolvedValueOnce(makeEmbedResponse());
+
+    const embedder = new Embedder(config, logger);
+    const runPromise = embedder.embedOne('hello');
+    await vi.runAllTimersAsync();
+    const result = await runPromise;
+
+    expect(mockEmbedContent).toHaveBeenCalledTimes(3);
+    expect(result).toBeInstanceOf(Float32Array);
+  });
+
+  // ── Test 6: throws after max retries ─────────────────────────────────────────
+
+  it('embedOne() throws search_embedding_failed after max retries exceeded', async () => {
+    const error429 = new Error('Rate limit 429');
+    mockEmbedContent.mockRejectedValue(error429);
+
+    const embedder = new Embedder(config, logger);
+    const runPromise = embedder.embedOne('hello');
+    // Attach rejection handler BEFORE advancing timers to prevent
+    // "unhandled rejection" warnings from the window between timer fire and handler attach.
+    const assertion = expect(runPromise).rejects.toMatchObject({
+      code: 'search_embedding_failed',
+    });
+    await vi.runAllTimersAsync();
+    await assertion;
+    // 1 initial + 3 retries = 4 calls
+    expect(mockEmbedContent).toHaveBeenCalledTimes(4);
+  });
+
+  // ── Test 8: timeout throws search_embedding_failed [GAP-4] ──────────────────
+
+  it('embedOne() throws search_embedding_failed with "timed out" when API hangs past request_timeout_ms [GAP-4]', async () => {
+    const cfg = makeConfig({ request_timeout_ms: 1_000 });
+    // Never-resolving promise simulates a hung API
+    mockEmbedContent.mockReturnValueOnce(new Promise(() => {}));
+
+    const embedder = new Embedder(cfg, logger);
+    const runPromise = embedder.embedOne('hang');
+    // Attach rejection handler BEFORE advancing timers to prevent
+    // "unhandled rejection" warnings from the window between timer fire and handler attach.
+    const assertion = expect(runPromise).rejects.toMatchObject({
+      code: 'search_embedding_failed',
+      message: expect.stringMatching(/timed out/),
+    });
+
+    // Advance past the timeout
+    await vi.advanceTimersByTimeAsync(cfg.request_timeout_ms + 100);
+    await assertion;
+  });
+});

package/src/search/__tests__/graph-enricher.test.ts

@@ -0,0 +1,178 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { GraphEnricher } from '../graph-enricher.js';
+import type { RawSearchResult } from '../graph-enricher.js';
+import type { Logger } from 'winston';
+import type { ProjectMap } from '../../types/index.js';
+
+// ─── Mocks ────────────────────────────────────────────────────────────────────
+
+vi.mock('node:fs/promises', () => ({
+  default: { readFile: vi.fn() },
+}));
+
+import fs from 'node:fs/promises';
+const mockReadFile = vi.mocked(fs.readFile);
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+function makeLogger(): Logger {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  } as unknown as Logger;
+}
+
+function makeProjectMap(overrides: Partial<ProjectMap> = {}): ProjectMap {
+  return {
+    schema_version: 1,
+    generated_at: '2026-04-01T00:00:00.000Z',
+    root: '/project',
+    files: {
+      'src/core.ts': {
+        file: 'src/core.ts',
+        hash: 'abc123',
+        language: 'typescript',
+        symbols: [],
+        imports: [],
+        dependents: ['src/a.ts', 'src/b.ts', 'src/c.ts'],
+        dependencies: [],
+        depth: 2,
+        last_parsed_at: null,
+        semantic: null,
+        enrichment_status: 'structural',
+      },
+      'src/utils.ts': {
+        file: 'src/utils.ts',
+        hash: 'def456',
+        language: 'typescript',
+        symbols: [],
+        imports: [],
+        dependents: ['src/a.ts'],
+        dependencies: [],
+        depth: 5,
+        last_parsed_at: null,
+        semantic: null,
+        enrichment_status: 'structural',
+      },
+    },
+    stats: {
+      total_files: 2,
+      total_symbols: 0,
+      total_edges: 4,
+      core_modules: ['src/core.ts'],
+      structural_only: 2,
+      semantically_enriched: 0,
+      indexed: 0,
+    },
+    ...overrides,
+  };
+}
+
+function makeRaw(overrides: Partial<RawSearchResult> = {}): RawSearchResult {
+  return {
+    id: 'src/core.ts',
+    type: 'file',
+    file_path: 'src/core.ts',
+    symbol_name: null,
+    symbol_type: null,
+    line_start: null,
+    line_end: null,
+    purpose: 'Core module',
+    similarity_score: 0.9,
+    ...overrides,
+  };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('GraphEnricher', () => {
+  let logger: Logger;
+  let enricher: GraphEnricher;
+
+  beforeEach(() => {
+    logger = makeLogger();
+    enricher = new GraphEnricher('/project/project_map.json', logger);
+    vi.clearAllMocks();
+  });
+
+  it('enriches results with correct graph_depth and dependents_count from project map', async () => {
+    const projectMap = makeProjectMap();
+    mockReadFile.mockResolvedValueOnce(JSON.stringify(projectMap));
+
+    const results = await enricher.enrich([
+      makeRaw({ file_path: 'src/core.ts', similarity_score: 0.9 }),
+      makeRaw({ id: 'src/utils.ts', file_path: 'src/utils.ts', similarity_score: 0.8 }),
+    ]);
+
+    const core = results.find((r) => r.file_path === 'src/core.ts')!;
+    expect(core.graph_depth).toBe(2);
+    expect(core.dependents_count).toBe(3);
+    expect(core.is_stale).toBe(false);
+
+    const utils = results.find((r) => r.file_path === 'src/utils.ts')!;
+    expect(utils.graph_depth).toBe(5);
+    expect(utils.dependents_count).toBe(1);
+    expect(utils.is_stale).toBe(false);
+  });
+
+  it('flags core modules correctly (is_core_module = true)', async () => {
+    const projectMap = makeProjectMap();
+    mockReadFile.mockResolvedValueOnce(JSON.stringify(projectMap));
+
+    const results = await enricher.enrich([
+      makeRaw({ file_path: 'src/core.ts' }),
+      makeRaw({ id: 'src/utils.ts', file_path: 'src/utils.ts' }),
+    ]);
+
+    const core = results.find((r) => r.file_path === 'src/core.ts')!;
+    expect(core.is_core_module).toBe(true);
+
+    const utils = results.find((r) => r.file_path === 'src/utils.ts')!;
+    expect(utils.is_core_module).toBe(false);
+  });
+
+  it('marks missing file as is_stale = true with graph_depth = -1 [TRAP-4]', async () => {
+    const projectMap = makeProjectMap();
+    mockReadFile.mockResolvedValueOnce(JSON.stringify(projectMap));
+
+    const results = await enricher.enrich([
+      makeRaw({ id: 'src/deleted.ts', file_path: 'src/deleted.ts', similarity_score: 0.75 }),
+    ]);
+
+    expect(results).toHaveLength(1);
+    expect(results[0]!.is_stale).toBe(true);
+    expect(results[0]!.graph_depth).toBe(-1);
+    expect(results[0]!.dependents_count).toBe(0);
+    expect(results[0]!.is_core_module).toBe(false);
+  });
+
+  it('maintains similarity_score ranking after enrichment', async () => {
+    const projectMap = makeProjectMap();
+    mockReadFile.mockResolvedValueOnce(JSON.stringify(projectMap));
+
+    // Input in non-sorted order
+    const results = await enricher.enrich([
+      makeRaw({ id: 'src/utils.ts', file_path: 'src/utils.ts', similarity_score: 0.7 }),
+      makeRaw({ file_path: 'src/core.ts', similarity_score: 0.95 }),
+    ]);
+
+    expect(results[0]!.file_path).toBe('src/core.ts');
+    expect(results[0]!.similarity_score).toBe(0.95);
+    expect(results[1]!.file_path).toBe('src/utils.ts');
+    expect(results[1]!.similarity_score).toBe(0.7);
+  });
+
+  it('calls loadMap only once across multiple enrich() calls [GAP-5]', async () => {
+    const projectMap = makeProjectMap();
+    mockReadFile.mockResolvedValue(JSON.stringify(projectMap));
+
+    await enricher.enrich([makeRaw()]);
+    await enricher.enrich([makeRaw()]);
+    await enricher.enrich([makeRaw()]);
+
+    // fs.readFile should only be called ONCE — map is cached
+    expect(mockReadFile).toHaveBeenCalledTimes(1);
+  });
+});