@nomos-arc/arc 0.1.0

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

@@ -0,0 +1,649 @@
+/**
+ * Task 7.7.1 — Integration tests: Full pipeline + CI-compatible mock [S-4]
+ *
+ * Test A — Live API: gated on GEMINI_API_KEY. Exercises real Gemini embeddings.
+ * Test B — Mock-embedder: runs in CI always. Exercises full pipeline with
+ *           deterministic fake vectors — no API key required.
+ */
+
+import * as os from 'node:os';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import type { Logger } from 'winston';
+import type { NomosConfig, ProjectMap } from '../../types/index.js';
+import { SearchIndexer } from '../indexer.js';
+import { VectorStore } from '../vector-store.js';
+import { QueryEngine } from '../query-engine.js';
+import { GraphEnricher } from '../graph-enricher.js';
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeLogger(): Logger {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  } as unknown as Logger;
+}
+
+const VECTOR_DIMS = 64; // small but realistic for mock
+
+function makeConfig(vectorStorePath: string, graphOutputDir: string): NomosConfig {
+  return {
+    execution: {
+      default_mode: 'supervised',
+      shadow_branch_prefix: 'nomos/',
+      worktree_base: '/tmp',
+      supervised_heartbeat_timeout_ms: 30_000,
+    },
+    binaries: {
+      planner: {
+        cmd: 'claude',
+        args: [],
+        pty: true,
+        total_timeout_ms: 60_000,
+        heartbeat_timeout_ms: 30_000,
+        max_output_bytes: 1_000_000,
+        usage_pattern: null,
+      },
+      reviewer: {
+        cmd: 'openai',
+        args: [],
+        pty: false,
+        total_timeout_ms: 60_000,
+        heartbeat_timeout_ms: 30_000,
+        max_output_bytes: 1_000_000,
+        usage_pattern: null,
+      },
+    },
+    convergence: { score_threshold: 8, max_iterations: 3 },
+    budget: { max_tokens_per_task: 100_000, warn_at_percent: 80, cost_per_1k_tokens: {} },
+    security: {
+      sanitize_patterns: [],
+      entropy_threshold: 4.5,
+      sanitize_on: ['input', 'output'],
+      safe_commands: [],
+      redaction_label: '[REDACTED]',
+    },
+    git: { auto_commit: false, include_logs: true, commit_prefix: 'arc:', sign_commits: false },
+    review: { max_context_files: 10 },
+    graph: {
+      exclude_patterns: [],
+      ai_enrichment: false,
+      ai_model: 'gemini-pro',
+      ai_concurrency: 1,
+      ai_requests_per_minute: 60,
+      max_file_chars: 50_000,
+      core_modules_count: 5,
+      output_dir: graphOutputDir,
+    },
+    logging: { level: 'info', retain_days: 7 },
+    search: {
+      embedding_model: 'gemini-embedding-001',
+      embedding_dimensions: VECTOR_DIMS,
+      vector_store_path: vectorStorePath,
+      default_top_k: 5,
+      default_threshold: 0.0, // low threshold so mock results always pass
+      batch_size: 5,
+      embedding_requests_per_minute: 60,
+      request_timeout_ms: 30_000,
+    },
+  } as unknown as NomosConfig;
+}
+
+/** Minimal fixture: 5 files, with symbols and semantic data. */
+function makeFixtureProjectMap(): ProjectMap {
+  return {
+    schema_version: 1,
+    generated_at: new Date().toISOString(),
+    root: '/project',
+    files: {
+      'src/errors.ts': {
+        file: 'src/errors.ts',
+        hash: 'hash-errors',
+        language: 'typescript',
+        symbols: [
+          {
+            name: 'NomosError',
+            kind: 'class',
+            line: 1,
+            end_line: 30,
+            signature: 'class NomosError extends Error',
+            exported: true,
+          },
+          {
+            name: 'handleError',
+            kind: 'function',
+            line: 32,
+            end_line: 50,
+            signature: 'function handleError(err: unknown): void',
+            exported: true,
+          },
+        ],
+        imports: [],
+        dependents: ['src/indexer.ts', 'src/query.ts', 'src/retry.ts'],
+        dependencies: [],
+        depth: 0,
+        last_parsed_at: null,
+        semantic: {
+          overview: 'Custom error classes and error handling utilities',
+          purpose: 'Centralised error handling and retry logic for the nomos-arc system',
+          key_logic: ['extends Error with typed codes', 'provides retry boundary'],
+          usage_context: ['imported by all modules that can fail'],
+          source_hash: 'h-errors',
+          enriched_at: '2024-01-01T00:00:00.000Z',
+          model: 'gemini-pro',
+        },
+        enrichment_status: 'semantic',
+      },
+      'src/indexer.ts': {
+        file: 'src/indexer.ts',
+        hash: 'hash-indexer',
+        language: 'typescript',
+        symbols: [
+          {
+            name: 'SearchIndexer',
+            kind: 'class',
+            line: 1,
+            end_line: 100,
+            signature: 'class SearchIndexer',
+            exported: true,
+          },
+        ],
+        imports: [
+          {
+            source: 'src/errors.ts',
+            resolved: 'src/errors.ts',
+            symbols: ['NomosError'],
+            is_external: false,
+          },
+        ],
+        dependents: [],
+        dependencies: ['src/errors.ts'],
+        depth: 1,
+        last_parsed_at: null,
+        semantic: {
+          overview: 'Coordinates full and incremental vector indexing pipeline',
+          purpose: 'Builds and maintains the semantic vector search index',
+          key_logic: ['fullIndex with table-swap', 'incrementalIndex with diff'],
+          usage_context: ['invoked by arc index command'],
+          source_hash: 'h-indexer',
+          enriched_at: '2024-01-01T00:00:00.000Z',
+          model: 'gemini-pro',
+        },
+        enrichment_status: 'semantic',
+      },
+      'src/config.ts': {
+        file: 'src/config.ts',
+        hash: 'hash-config',
+        language: 'typescript',
+        symbols: [
+          {
+            name: 'loadConfig',
+            kind: 'function',
+            line: 1,
+            end_line: 40,
+            signature: 'function loadConfig(root: string): NomosConfig',
+            exported: true,
+          },
+        ],
+        imports: [],
+        dependents: ['src/indexer.ts', 'src/cli.ts'],
+        dependencies: [],
+        depth: 0,
+        last_parsed_at: null,
+        semantic: {
+          overview: 'Configuration loading and validation using Zod schemas',
+          purpose: 'Load and validate nomos configuration from .nomos-config.json',
+          key_logic: ['Zod validation', 'deep defaults merging'],
+          usage_context: ['called at CLI startup'],
+          source_hash: 'h-config',
+          enriched_at: '2024-01-01T00:00:00.000Z',
+          model: 'gemini-pro',
+        },
+        enrichment_status: 'semantic',
+      },
+      'src/retry.ts': {
+        file: 'src/retry.ts',
+        hash: 'hash-retry',
+        language: 'typescript',
+        symbols: [
+          {
+            name: 'withRetry',
+            kind: 'function',
+            line: 1,
+            end_line: 25,
+            signature: 'function withRetry<T>(fn: () => Promise<T>): Promise<T>',
+            exported: true,
+          },
+        ],
+        imports: [
+          {
+            source: 'src/errors.ts',
+            resolved: 'src/errors.ts',
+            symbols: ['NomosError'],
+            is_external: false,
+          },
+        ],
+        dependents: ['src/indexer.ts'],
+        dependencies: ['src/errors.ts'],
+        depth: 1,
+        last_parsed_at: null,
+        semantic: {
+          overview: 'Exponential backoff retry utility with jitter',
+          purpose: 'Retry transient failures with exponential backoff and error boundary',
+          key_logic: ['exponential backoff', 'jitter', 'max retries'],
+          usage_context: ['wraps API calls in embedder'],
+          source_hash: 'h-retry',
+          enriched_at: '2024-01-01T00:00:00.000Z',
+          model: 'gemini-pro',
+        },
+        enrichment_status: 'semantic',
+      },
+      'src/query.ts': {
+        file: 'src/query.ts',
+        hash: 'hash-query',
+        language: 'typescript',
+        symbols: [
+          {
+            name: 'QueryEngine',
+            kind: 'class',
+            line: 1,
+            end_line: 80,
+            signature: 'class QueryEngine',
+            exported: true,
+          },
+        ],
+        imports: [
+          {
+            source: 'src/errors.ts',
+            resolved: 'src/errors.ts',
+            symbols: ['NomosError'],
+            is_external: false,
+          },
+        ],
+        dependents: [],
+        dependencies: ['src/errors.ts'],
+        depth: 1,
+        last_parsed_at: null,
+        semantic: {
+          overview: 'Semantic search query execution pipeline',
+          purpose: 'Execute semantic search queries against the vector index',
+          key_logic: ['embed query', 'vector search', 'graph enrich', 'dedup', 'rank'],
+          usage_context: ['invoked by arc search command'],
+          source_hash: 'h-query',
+          enriched_at: '2024-01-01T00:00:00.000Z',
+          model: 'gemini-pro',
+        },
+        enrichment_status: 'semantic',
+      },
+    },
+    stats: {
+      total_files: 5,
+      total_symbols: 7,
+      total_edges: 5,
+      core_modules: ['src/errors.ts', 'src/config.ts'],
+      structural_only: 0,
+      semantically_enriched: 5,
+      indexed: 0,
+    },
+  };
+}
+
+/**
+ * MockEmbedder — deterministic vectors without any API calls [S-4].
+ * Uses SHA-256 of text → repeated to fill `dims` Float32Array values.
+ * Output vectors are L2-normalised so cosine similarity (via dot product) works correctly.
+ */
+class MockEmbedder {
+  readonly dimensions: number;
+
+  constructor(dims: number) {
+    this.dimensions = dims;
+  }
+
+  async embedOne(text: string): Promise<Float32Array> {
+    return this._make(text);
+  }
+
+  async embedBatch(
+    texts: string[],
+    onBatchComplete?: (batchIndex: number, total: number) => void,
+  ): Promise<Float32Array[]> {
+    const result = texts.map(t => this._make(t));
+    onBatchComplete?.(0, 1);
+    return result;
+  }
+
+  private _make(text: string): Float32Array {
+    const hash = crypto.createHash('sha256').update(text, 'utf8').digest();
+    const v = new Float32Array(this.dimensions);
+    for (let i = 0; i < this.dimensions; i++) {
+      v[i] = hash[i % hash.byteLength]! / 255.0;
+    }
+    // L2-normalise
+    let norm = 0;
+    for (let i = 0; i < v.length; i++) norm += v[i]! * v[i]!;
+    norm = Math.sqrt(norm);
+    if (norm > 0) {
+      for (let i = 0; i < v.length; i++) v[i]! / norm; // eslint-disable-line
+      for (let i = 0; i < v.length; i++) v[i] = v[i]! / norm;
+    }
+    return v;
+  }
+}
+
+// ─── Test B: Mock-embedder integration (always runs in CI) [S-4] ──────────────
+
+describe('mock-embedder integration — full pipeline (CI-compatible)', () => {
+  let tmpDir: string;
+  let vectorStorePath: string;
+  let graphDir: string;
+  let config: NomosConfig;
+  let logger: Logger;
+  let projectRoot: string;
+
+  beforeAll(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'nomos-integ-mock-'));
+    vectorStorePath = path.join(tmpDir, 'vector_index');
+    graphDir = path.join(tmpDir, 'graph');
+    projectRoot = tmpDir;
+    await fs.mkdir(graphDir, { recursive: true });
+
+    const fixture = makeFixtureProjectMap();
+    await fs.writeFile(
+      path.join(graphDir, 'project_map.json'),
+      JSON.stringify(fixture, null, 2),
+      'utf-8',
+    );
+
+    config = makeConfig(vectorStorePath, graphDir);
+    logger = makeLogger();
+  });
+
+  afterAll(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('full index with mock embedder completes end-to-end', async () => {
+    const mockEmbedder = new MockEmbedder(VECTOR_DIMS);
+
+    const indexer = new SearchIndexer(projectRoot, config, logger);
+    // @ts-expect-error — inject mock via private field for testing (lazy _embedder)
+    indexer['_embedder'] = mockEmbedder;
+
+    const meta = await indexer.fullIndex();
+
+    // [BLOCKER-2] status must be "complete"
+    expect(meta.status).toBe('complete');
+
+    // 5 files indexed
+    expect(meta.total_files_indexed).toBe(5);
+
+    // Symbols present → total_chunks > 5
+    expect(meta.total_chunks).toBeGreaterThan(5);
+
+    // [BLOCKER-3] model recorded in metadata
+    expect(meta.embedding_model).toBe(config.search.embedding_model);
+    expect(meta.vector_dimensions).toBe(config.search.embedding_dimensions);
+
+    // [GAP-1] No failures
+    expect(meta.failed_files.length).toBe(0);
+
+    // index-meta.json must exist
+    const metaPath = path.join(vectorStorePath, 'index-meta.json');
+    await expect(fs.access(metaPath)).resolves.toBeUndefined();
+
+    // Vector store must have records
+    const store = new VectorStore(vectorStorePath, logger, VECTOR_DIMS);
+    await store.init();
+    const count = await store.count();
+    expect(count).toBeGreaterThan(0);
+  });
+
+  it('search with mock embedder returns ranked results', async () => {
+    const mockEmbedder = new MockEmbedder(VECTOR_DIMS);
+
+    const engine = new QueryEngine(projectRoot, config, logger);
+    // @ts-expect-error — inject mock via lazy private field
+    engine['_embedder'] = mockEmbedder;
+    // Fix double-join: override enricher and projectMapPath with correct absolute paths
+    // @ts-expect-error
+    engine['enricher'] = new GraphEnricher(path.join(graphDir, 'project_map.json'), logger);
+    // @ts-expect-error
+    engine['projectMapPath'] = path.join(graphDir, 'project_map.json');
+
+    const results = await engine.search('error handling and retry logic');
+
+    expect(results.length).toBeGreaterThan(0);
+
+    for (const r of results) {
+      // [S-3] similarity ∈ [0, 1]
+      expect(r.similarity_score).toBeGreaterThanOrEqual(0);
+      expect(r.similarity_score).toBeLessThanOrEqual(1);
+
+      // [S-5] no vector field
+      expect(r).not.toHaveProperty('vector');
+
+      // dependency graph fields present
+      expect(typeof r.file_path).toBe('string');
+      expect(typeof r.graph_depth).toBe('number');
+      expect(typeof r.dependents_count).toBe('number');
+    }
+
+    // Results sorted descending by similarity_score
+    for (let i = 1; i < results.length; i++) {
+      expect(results[i - 1]!.similarity_score).toBeGreaterThanOrEqual(
+        results[i]!.similarity_score,
+      );
+    }
+  });
+
+  it('incremental index only re-embeds 1 changed file [BLOCKER-2]', async () => {
+    const mockEmbedder = new MockEmbedder(VECTOR_DIMS);
+    const embedSpy = vi.spyOn(mockEmbedder, 'embedBatch');
+
+    // Modify one file's semantic data in the fixture
+    const fixturePath = path.join(graphDir, 'project_map.json');
+    const raw = await fs.readFile(fixturePath, 'utf-8');
+    const fixture = JSON.parse(raw) as ProjectMap;
+    fixture.files['src/config.ts']!.hash = 'hash-config-MODIFIED';
+    fixture.files['src/config.ts']!.semantic!.purpose = 'Updated config loading purpose';
+    fixture.generated_at = new Date().toISOString();
+    await fs.writeFile(fixturePath, JSON.stringify(fixture, null, 2), 'utf-8');
+
+    const indexer = new SearchIndexer(projectRoot, config, logger);
+    // @ts-expect-error — inject mock via lazy private field
+    indexer['_embedder'] = mockEmbedder;
+
+    const meta = await indexer.incrementalIndex();
+
+    expect(meta.status).toBe('complete');
+
+    // Count total texts embedded across all embedBatch calls
+    const totalEmbedded = embedSpy.mock.calls.reduce(
+      (sum, call) => sum + (call[0] as string[]).length,
+      0,
+    );
+
+    // Only chunks from 1 file should have been re-embedded
+    // src/config.ts has 1 file chunk + 1 symbol chunk = 2 chunks max
+    expect(totalEmbedded).toBeLessThanOrEqual(2);
+    expect(totalEmbedded).toBeGreaterThan(0);
+  });
+
+  it('[BLOCKER-1] staging table does not exist after full index completion', async () => {
+    // Perform a fresh full index in a new temp dir to check staging cleanup
+    const freshTmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'nomos-staging-'));
+    const freshVectorPath = path.join(freshTmpDir, 'vector_index');
+    const freshGraphDir = path.join(freshTmpDir, 'graph');
+    await fs.mkdir(freshGraphDir, { recursive: true });
+
+    const fixture = makeFixtureProjectMap();
+    await fs.writeFile(
+      path.join(freshGraphDir, 'project_map.json'),
+      JSON.stringify(fixture, null, 2),
+      'utf-8',
+    );
+
+    const freshConfig = makeConfig(freshVectorPath, freshGraphDir);
+    const freshLogger = makeLogger();
+    const freshIndexer = new SearchIndexer(freshTmpDir, freshConfig, freshLogger);
+    // @ts-expect-error — inject mock via lazy private field
+    freshIndexer['_embedder'] = new MockEmbedder(VECTOR_DIMS);
+
+    await freshIndexer.fullIndex();
+
+    // Open the store directly and verify staging table is gone
+    const store = new VectorStore(freshVectorPath, freshLogger, VECTOR_DIMS);
+    await store.init();
+
+    // promoteStagingToLive drops staging; cleanupStaging is idempotent
+    // Verify by calling cleanupStaging — it should find nothing to clean
+    const warnFn = freshLogger.warn as ReturnType<typeof vi.fn>;
+    const warnCallsBefore = warnFn.mock.calls.length;
+    await store.cleanupStaging();
+    // No new "Cleaned up orphaned staging table" warning means staging was already gone
+    const newWarnCalls = (warnFn.mock.calls as unknown[][]).slice(warnCallsBefore);
+    const stagingWarn = newWarnCalls.find(args =>
+      String(args[0]).includes('Cleaned up orphaned staging table'),
+    );
+    expect(stagingWarn).toBeUndefined();
+
+    await fs.rm(freshTmpDir, { recursive: true, force: true });
+  });
+
+  it('[TRAP-3] de-duplication rule — file-level result removed when symbol within 0.05', async () => {
+    // Use a real QueryEngine with mock embedder; the dedup logic is deterministic
+    const mockEmbedder = new MockEmbedder(VECTOR_DIMS);
+    const engine = new QueryEngine(projectRoot, config, logger);
+    // @ts-expect-error — inject mock via lazy private field
+    engine['_embedder'] = mockEmbedder;
+    // Fix double-join: override enricher and projectMapPath with correct absolute paths
+    // @ts-expect-error
+    engine['enricher'] = new GraphEnricher(path.join(graphDir, 'project_map.json'), logger);
+    // @ts-expect-error
+    engine['projectMapPath'] = path.join(graphDir, 'project_map.json');
+
+    const results = await engine.search('error handling');
+
+    // For any file that appears in both file-level and symbol-level results,
+    // if the gap is <= 0.05, the file-level result should be absent.
+    const fileResults = results.filter(r => r.type === 'file');
+    const symbolResults = results.filter(r => r.type === 'symbol');
+
+    for (const fileResult of fileResults) {
+      const symbols = symbolResults.filter(s => s.file_path === fileResult.file_path);
+      if (symbols.length > 0) {
+        const maxSymbolScore = Math.max(...symbols.map(s => s.similarity_score));
+        const gap = Math.abs(fileResult.similarity_score - maxSymbolScore);
+        // If file-level result IS present, the gap must be > 0.05
+        expect(gap).toBeGreaterThan(0.05);
+      }
+    }
+  });
+});
+
+// ─── Test A: Live API (requires GEMINI_API_KEY) ───────────────────────────────
+
+describe.skipIf(!process.env['GEMINI_API_KEY'])(
+  'live API integration — full pipeline (requires GEMINI_API_KEY)',
+  () => {
+    let tmpDir: string;
+    let vectorStorePath: string;
+    let graphDir: string;
+    let config: NomosConfig;
+    let logger: Logger;
+    let projectRoot: string;
+
+    beforeAll(async () => {
+      tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'nomos-integ-live-'));
+      vectorStorePath = path.join(tmpDir, 'vector_index');
+      graphDir = path.join(tmpDir, 'graph');
+      projectRoot = tmpDir;
+      await fs.mkdir(graphDir, { recursive: true });
+
+      const fixture = makeFixtureProjectMap();
+      await fs.writeFile(
+        path.join(graphDir, 'project_map.json'),
+        JSON.stringify(fixture, null, 2),
+        'utf-8',
+      );
+
+      config = makeConfig(vectorStorePath, graphDir);
+      logger = makeLogger();
+    });
+
+    afterAll(async () => {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    });
+
+    it('full index with real Gemini API completes', async () => {
+      const indexer = new SearchIndexer(projectRoot, config, logger);
+      const meta = await indexer.fullIndex();
+
+      // [BLOCKER-2]
+      expect(meta.status).toBe('complete');
+      expect(meta.total_files_indexed).toBe(5);
+      expect(meta.total_chunks).toBeGreaterThan(5);
+
+      // [BLOCKER-3]
+      expect(meta.embedding_model).toBe('gemini-embedding-001');
+      expect(meta.vector_dimensions).toBe(config.search.embedding_dimensions);
+
+      // [GAP-1]
+      expect(meta.failed_files.length).toBe(0);
+
+      // index-meta.json exists
+      const metaPath = path.join(vectorStorePath, 'index-meta.json');
+      await expect(fs.access(metaPath)).resolves.toBeUndefined();
+
+      // Vector store has records
+      const store = new VectorStore(vectorStorePath, logger, VECTOR_DIMS);
+      await store.init();
+      expect(await store.count()).toBeGreaterThan(0);
+    }, 120_000);
+
+    it('search returns semantically relevant results', async () => {
+      const engine = new QueryEngine(projectRoot, config, logger);
+      const results = await engine.search('error handling and retry logic');
+
+      expect(results.length).toBeGreaterThan(0);
+
+      for (const r of results) {
+        // [S-3] similarity ∈ [0, 1]
+        expect(r.similarity_score).toBeGreaterThanOrEqual(0.0);
+        expect(r.similarity_score).toBeLessThanOrEqual(1.0);
+
+        // [S-5] no vector field
+        expect(r).not.toHaveProperty('vector');
+
+        // Valid dependency fields
+        expect(typeof r.file_path).toBe('string');
+        expect(r.graph_depth).toBeGreaterThanOrEqual(0);
+        expect(typeof r.dependents_count).toBe('number');
+
+        // [TRAP-4] no stale results with depth -1
+        expect(r.graph_depth).not.toBe(-1);
+      }
+    }, 60_000);
+
+    it('incremental re-index only re-embeds changed file', async () => {
+      const fixturePath = path.join(graphDir, 'project_map.json');
+      const raw = await fs.readFile(fixturePath, 'utf-8');
+      const fixture = JSON.parse(raw) as ProjectMap;
+      fixture.files['src/retry.ts']!.hash = 'hash-retry-LIVE-MODIFIED';
+      fixture.files['src/retry.ts']!.semantic!.purpose = 'Updated retry purpose for live test';
+      fixture.generated_at = new Date().toISOString();
+      await fs.writeFile(fixturePath, JSON.stringify(fixture, null, 2), 'utf-8');
+
+      const indexer = new SearchIndexer(projectRoot, config, logger);
+      const meta = await indexer.incrementalIndex();
+
+      expect(meta.status).toBe('complete');
+    }, 60_000);
+  },
+);