@nomos-arc/arc 0.1.0

package/src/core/worktree-coordinator.ts

@@ -0,0 +1,77 @@
+import type { Logger } from 'winston';
+import type { NomosConfig } from '../types/index.js';
+import { GitAdapter } from '../adapters/git.js';
+import { NomosError } from './errors.js';
+
+/**
+ * Coordinates the Git worktree lifecycle: creation, validation,
+ * recovery, diff extraction, commits, and merges.
+ * The Orchestrator delegates ALL git operations to this class.
+ */
+export class WorktreeCoordinator {
+  constructor(
+    private gitAdapter: GitAdapter,
+    private config: NomosConfig,
+    private logger: Logger,
+  ) {}
+
+  async createWorktree(taskId: string) {
+    return this.gitAdapter.createWorktree(taskId);
+  }
+
+  async ensureWorktreeExists(taskId: string, branch: string): Promise<void> {
+    if (!this.gitAdapter.worktreeExists(taskId)) {
+      try {
+        await this.gitAdapter.recoverWorktree(taskId, branch);
+        this.logger.info(`Worktree recovered for task "${taskId}".`);
+      } catch {
+        throw new NomosError('worktree_missing',
+          `Worktree for task "${taskId}" is missing and unrecoverable. ` +
+          `Run: arc discard ${taskId} && arc init ${taskId}`);
+      }
+    }
+  }
+
+  async getDiff(taskId: string, baseCommit: string): Promise<string> {
+    return this.gitAdapter.getDiff(taskId, baseCommit);
+  }
+
+  async commitPlanFiles(taskId: string, version: number, files: string[]): Promise<void> {
+    if (this.config.git.auto_commit) {
+      await this.gitAdapter.commitToShadowBranch(
+        taskId,
+        `${this.config.git.commit_prefix} plan(${taskId}): v${version}`,
+        files,
+      );
+    }
+  }
+
+  async commitReviewFiles(taskId: string, version: number, files: string[]): Promise<void> {
+    if (this.config.git.auto_commit) {
+      await this.gitAdapter.commitToShadowBranch(
+        taskId,
+        `${this.config.git.commit_prefix} review(${taskId}): v${version}`,
+        files,
+      );
+    }
+  }
+
+  async mergeToMain(taskId: string, version: number) {
+    return this.gitAdapter.mergeToMain(
+      taskId, version, this.config.git.commit_prefix,
+    );
+  }
+
+  async removeWorktree(taskId: string, force: boolean) {
+    return this.gitAdapter.removeWorktree(taskId, force);
+  }
+
+  worktreeExists(taskId: string): boolean {
+    return this.gitAdapter.worktreeExists(taskId);
+  }
+
+  /** Search for files matching a pattern. Used by context injection. */
+  async grep(pattern: string, cwd: string, timeoutMs?: number): Promise<string[]> {
+    return this.gitAdapter.grep(pattern, cwd, timeoutMs);
+  }
+}

package/src/search/__tests__/chunk-extractor.test.ts

@@ -0,0 +1,339 @@
+import crypto from 'node:crypto';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { ChunkExtractor } from '../chunk-extractor.js';
+import type { Logger } from 'winston';
+import type { FileNode, ProjectMap } from '../../types/index.js';
+
+// ─── fs mocks (TRAP-5 verification) ──────────────────────────────────────────
+// ChunkExtractor must NEVER read from the filesystem.
+// We mock node:fs and node:fs/promises at the module level so any accidental
+// call to readFile/readFileSync inside ChunkExtractor will be detectable.
+
+const mockReadFileSync = vi.fn();
+const mockReadFile = vi.fn();
+
+vi.mock('node:fs', () => ({
+  default: { readFileSync: mockReadFileSync },
+  readFileSync: mockReadFileSync,
+}));
+
+vi.mock('node:fs/promises', () => ({
+  default: { readFile: mockReadFile },
+  readFile: mockReadFile,
+}));
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeLogger(): Logger {
+  return {
+    warn: vi.fn(),
+    info: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  } as unknown as Logger;
+}
+
+function makeSemanticNode(overrides: Partial<FileNode> = {}): FileNode {
+  return {
+    file: 'src/services/payment.ts',
+    hash: 'abc123',
+    language: 'typescript',
+    symbols: [
+      {
+        name: 'PaymentService',
+        kind: 'class',
+        line: 10,
+        end_line: 80,
+        signature: 'class PaymentService',
+        exported: true,
+      },
+      {
+        name: 'processPayment',
+        kind: 'function',
+        line: 20,
+        end_line: 40,
+        signature: 'processPayment(amount: number): Promise<void>',
+        exported: true,
+      },
+      {
+        name: '_internalHelper',
+        kind: 'method',
+        line: 50,
+        end_line: 60,
+        signature: '_internalHelper(): void',
+        exported: false,
+      },
+    ],
+    imports: [{ source: 'stripe', resolved: null, symbols: ['Stripe'], is_external: true }],
+    dependents: ['src/api/checkout.ts'],
+    dependencies: ['stripe', 'src/core/logger.ts'],
+    depth: 2,
+    last_parsed_at: '2024-01-01T00:00:00.000Z',
+    semantic: {
+      overview: 'Handles payment processing via Stripe.',
+      purpose: 'Process and validate customer payments.',
+      key_logic: ['Validates card', 'Charges via Stripe API'],
+      usage_context: ['Called from checkout flow', 'Used in subscription renewal'],
+      source_hash: 'def456',
+      enriched_at: '2024-01-01T00:00:00.000Z',
+      model: 'gemini-pro',
+    },
+    enrichment_status: 'semantic',
+    ...overrides,
+  };
+}
+
+function makeNoSemanticNode(): FileNode {
+  return {
+    file: 'src/utils/helpers.ts',
+    hash: 'xyz789',
+    language: 'typescript',
+    symbols: [
+      {
+        name: 'formatDate',
+        kind: 'function',
+        line: 5,
+        end_line: 10,
+        signature: 'formatDate(d: Date): string',
+        exported: true,
+      },
+    ],
+    imports: [{ source: 'date-fns', resolved: null, symbols: ['format'], is_external: true }],
+    dependents: [],
+    dependencies: ['date-fns'],
+    depth: 3,
+    last_parsed_at: null,
+    semantic: null,
+    enrichment_status: 'structural',
+  };
+}
+
+function makeProjectMap(files: Record<string, FileNode>): ProjectMap {
+  return {
+    schema_version: 1,
+    generated_at: '2024-01-01T00:00:00.000Z',
+    root: '/project',
+    files,
+    stats: {
+      total_files: Object.keys(files).length,
+      total_symbols: 0,
+      total_edges: 0,
+      core_modules: [],
+      structural_only: 0,
+      semantically_enriched: 0,
+      indexed: 0,
+    },
+  };
+}
+
+function computeExpectedFileHash(file_path: string, fileNode: FileNode): string {
+  const hashInput = JSON.stringify({
+    file_path,
+    semantic: fileNode.semantic,
+    symbols: fileNode.symbols.map(s => ({
+      name: s.name,
+      kind: s.kind,
+      signature: s.signature,
+    })),
+    dependencies: fileNode.dependencies,
+  });
+  return crypto.createHash('sha256').update(hashInput).digest('hex');
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('ChunkExtractor', () => {
+  let logger: Logger;
+  let extractor: ChunkExtractor;
+  const FILE_PATH = 'src/services/payment.ts';
+  const NO_SEM_PATH = 'src/utils/helpers.ts';
+
+  beforeEach(() => {
+    logger = makeLogger();
+    extractor = new ChunkExtractor('/project', logger);
+  });
+
+  // ─── Test 1: File-level chunk with semantic data ────────────────────────
+
+  it('produces a file-level chunk with all semantic fields concatenated', () => {
+    const fileNode = makeSemanticNode();
+    const map = makeProjectMap({ [FILE_PATH]: fileNode });
+
+    const chunks = extractor.extract(map);
+    const fileChunk = chunks.find(c => c.id === FILE_PATH && c.type === 'file');
+
+    expect(fileChunk).toBeDefined();
+    expect(fileChunk!.text).toContain(`File: ${FILE_PATH}`);
+    expect(fileChunk!.text).toContain('Purpose: Process and validate customer payments.');
+    expect(fileChunk!.text).toContain('Overview: Handles payment processing via Stripe.');
+    expect(fileChunk!.text).toContain('Key Logic: Validates card; Charges via Stripe API');
+    expect(fileChunk!.text).toContain('Usage Context: Called from checkout flow; Used in subscription renewal');
+    expect(fileChunk!.text).toContain('Exports:');
+    expect(fileChunk!.text).toContain('Dependencies: stripe, src/core/logger.ts');
+  });
+
+  // ─── Test 2: Fallback chunk without semantic data ───────────────────────
+
+  it('produces a fallback chunk with file path and symbol names when semantic is null', () => {
+    const fileNode = makeNoSemanticNode();
+    const map = makeProjectMap({ [NO_SEM_PATH]: fileNode });
+
+    const chunks = extractor.extract(map);
+    const fileChunk = chunks.find(c => c.id === NO_SEM_PATH && c.type === 'file');
+
+    expect(fileChunk).toBeDefined();
+    expect(fileChunk!.text).toContain(`File: ${NO_SEM_PATH}`);
+    expect(fileChunk!.text).toContain('Symbols: formatDate');
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining(NO_SEM_PATH),
+    );
+  });
+
+  // ─── Test 3: Exported symbols produce symbol-level chunks ───────────────
+
+  it('produces symbol-level chunks for exported symbols', () => {
+    const fileNode = makeSemanticNode();
+    const map = makeProjectMap({ [FILE_PATH]: fileNode });
+
+    const chunks = extractor.extract(map);
+    const symbolChunks = chunks.filter(c => c.type === 'symbol');
+
+    // PaymentService (class, exported), processPayment (function, exported)
+    // _internalHelper (method, NOT exported, NOT class/function) — skipped
+    expect(symbolChunks.length).toBeGreaterThanOrEqual(2);
+
+    const ids = symbolChunks.map(c => c.id);
+    expect(ids).toContain(`${FILE_PATH}::PaymentService`);
+    expect(ids).toContain(`${FILE_PATH}::processPayment`);
+  });
+
+  // ─── Test 4: Non-exported, non-class, non-function symbols are skipped ──
+
+  it('skips non-exported symbols that are not class or function kind', () => {
+    const fileNode = makeSemanticNode();
+    const map = makeProjectMap({ [FILE_PATH]: fileNode });
+
+    const chunks = extractor.extract(map);
+    const ids = chunks.map(c => c.id);
+
+    // _internalHelper is method + non-exported — must not appear
+    expect(ids).not.toContain(`${FILE_PATH}::_internalHelper`);
+  });
+
+  // ─── Test 5: Correct chunk IDs ─────────────────────────────────────────
+
+  it('assigns correct IDs — file path for file-level, "file::symbol" for symbol-level', () => {
+    const fileNode = makeSemanticNode();
+    const map = makeProjectMap({ [FILE_PATH]: fileNode });
+
+    const chunks = extractor.extract(map);
+
+    const fileChunk = chunks.find(c => c.type === 'file');
+    expect(fileChunk!.id).toBe(FILE_PATH);
+
+    const symbolChunk = chunks.find(c => c.id === `${FILE_PATH}::PaymentService`);
+    expect(symbolChunk).toBeDefined();
+  });
+
+  // ─── Test 6: parent_file_id on symbol chunks ────────────────────────────
+
+  it('sets parent_file_id on symbol chunks to the parent file path', () => {
+    const fileNode = makeSemanticNode();
+    const map = makeProjectMap({ [FILE_PATH]: fileNode });
+
+    const chunks = extractor.extract(map);
+    const symbolChunks = chunks.filter(c => c.type === 'symbol');
+
+    for (const chunk of symbolChunks) {
+      expect(chunk.parent_file_id).toBe(FILE_PATH);
+    }
+  });
+
+  // ─── Test 7: Chunks shorter than 20 chars are skipped ──────────────────
+
+  it('skips chunks whose composed text is shorter than 20 characters', () => {
+    // A node with minimal content that would produce very short text
+    const tinyNode: FileNode = {
+      file: 'x.ts',
+      hash: 'h',
+      language: 'typescript',
+      symbols: [],
+      imports: [],
+      dependents: [],
+      dependencies: [],
+      depth: 0,
+      last_parsed_at: null,
+      semantic: null,
+      enrichment_status: 'structural',
+    };
+    // "File: x.ts" is exactly 10 chars — too short
+    const map = makeProjectMap({ 'x.ts': tinyNode });
+
+    const chunks = extractor.extract(map);
+    expect(chunks.length).toBe(0);
+  });
+
+  // ─── Test 8: content_hash is deterministic ──────────────────────────────
+
+  it('produces the same content_hash for identical inputs (deterministic) [S-6]', () => {
+    const fileNode = makeSemanticNode();
+    const map = makeProjectMap({ [FILE_PATH]: fileNode });
+
+    const chunks1 = new ChunkExtractor('/project', logger).extract(map);
+    const chunks2 = new ChunkExtractor('/project', logger).extract(map);
+
+    const hash1 = chunks1.find(c => c.id === FILE_PATH)!.content_hash;
+    const hash2 = chunks2.find(c => c.id === FILE_PATH)!.content_hash;
+
+    expect(hash1).toBe(hash2);
+    expect(hash1).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  // ─── Test 9: content_hash stable across text composition changes ────────
+
+  it('produces stable content_hash — only raw inputs matter, not composed text [S-6]', () => {
+    const fileNode = makeSemanticNode();
+    const expectedHash = computeExpectedFileHash(FILE_PATH, fileNode);
+
+    const map = makeProjectMap({ [FILE_PATH]: fileNode });
+    const chunks = extractor.extract(map);
+    const fileChunk = chunks.find(c => c.id === FILE_PATH)!;
+
+    // Hash must equal what we compute from raw inputs directly
+    expect(fileChunk.content_hash).toBe(expectedHash);
+
+    // Changing only the composition format (e.g. changing semantic.overview
+    // delimiter) would not change the hash because we hash raw inputs.
+    // We verify that semantic content changes DO change the hash:
+    const modifiedNode = makeSemanticNode({
+      semantic: {
+        ...fileNode.semantic!,
+        overview: 'CHANGED overview',
+      },
+    });
+    const mapModified = makeProjectMap({ [FILE_PATH]: modifiedNode });
+    const chunksModified = extractor.extract(mapModified);
+    const modifiedHash = chunksModified.find(c => c.id === FILE_PATH)!.content_hash;
+
+    expect(modifiedHash).not.toBe(expectedHash);
+  });
+
+  // ─── Test 10: No .semantic.md file reads ───────────────────────────────
+
+  it('performs no filesystem reads — all data from ProjectMap [TRAP-5]', () => {
+    mockReadFileSync.mockClear();
+    mockReadFile.mockClear();
+
+    const fileNode = makeSemanticNode();
+    const noSemNode = makeNoSemanticNode();
+    const map = makeProjectMap({
+      [FILE_PATH]: fileNode,
+      [NO_SEM_PATH]: noSemNode,
+    });
+
+    extractor.extract(map);
+
+    expect(mockReadFileSync).not.toHaveBeenCalled();
+    expect(mockReadFile).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,124 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { Logger } from 'winston';
+import { NomosError } from '../../core/errors.js';
+import type { NomosConfig } from '../../types/index.js';
+
+// ─── Mock google-generative-ai to avoid real API calls ────────────────────────
+
+vi.mock('@google/generative-ai', () => ({
+  // Must use a regular function (not arrow) so it can be called with `new`
+  GoogleGenerativeAI: vi.fn().mockImplementation(function (this: Record<string, unknown>) {
+    this['getGenerativeModel'] = vi.fn();
+  }),
+}));
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeLogger(): Logger {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  } as unknown as Logger;
+}
+
+function makeSearchConfig(): NomosConfig['search'] {
+  return {
+    embedding_model: 'text-embedding-004',
+    embedding_dimensions: 256,
+    vector_store_path: '/tmp/test-vectors',
+    default_top_k: 10,
+    default_threshold: 0.7,
+    batch_size: 100,
+    embedding_requests_per_minute: 60,
+    request_timeout_ms: 30_000,
+  };
+}
+
+function makeMockAuthManager(overrides: { isLoggedIn?: boolean; accessToken?: string } = {}) {
+  return {
+    isLoggedIn: vi.fn().mockReturnValue(overrides.isLoggedIn ?? false),
+    getAccessToken: vi.fn().mockResolvedValue(overrides.accessToken ?? 'fake-oauth-token'),
+    saveCredentials: vi.fn(),
+    loadCredentials: vi.fn(),
+    clearCredentials: vi.fn(),
+    getAuthenticatedClient: vi.fn(),
+  };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('Embedder.create — credential chain', () => {
+  let Embedder: (typeof import('../embedder.js'))['Embedder'];
+  const originalEnv = process.env['GEMINI_API_KEY'];
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    ({ Embedder } = await import('../embedder.js'));
+  });
+
+  afterEach(() => {
+    // Restore the env var after each test
+    if (originalEnv === undefined) {
+      delete process.env['GEMINI_API_KEY'];
+    } else {
+      process.env['GEMINI_API_KEY'] = originalEnv;
+    }
+  });
+
+  // ─── 1. API key takes priority ──────────────────────────────────────────────
+
+  it('uses GEMINI_API_KEY and does NOT call authManager when env var is set', async () => {
+    process.env['GEMINI_API_KEY'] = 'env-api-key';
+    const authManager = makeMockAuthManager({ isLoggedIn: true, accessToken: 'oauth-token' });
+
+    const embedder = await Embedder.create(makeSearchConfig(), makeLogger(), authManager as never);
+
+    expect(embedder).toBeInstanceOf(Embedder);
+    // isLoggedIn and getAccessToken must not be called when env key is present
+    expect(authManager.isLoggedIn).not.toHaveBeenCalled();
+    expect(authManager.getAccessToken).not.toHaveBeenCalled();
+  });
+
+  // ─── 2. OAuth fallback ─────────────────────────────────────────────────────
+
+  it('falls back to OAuth token when GEMINI_API_KEY is unset and user is logged in', async () => {
+    delete process.env['GEMINI_API_KEY'];
+    const authManager = makeMockAuthManager({ isLoggedIn: true, accessToken: 'fake-oauth-token' });
+
+    const embedder = await Embedder.create(makeSearchConfig(), makeLogger(), authManager as never);
+
+    expect(embedder).toBeInstanceOf(Embedder);
+    expect(authManager.isLoggedIn).toHaveBeenCalled();
+    expect(authManager.getAccessToken).toHaveBeenCalled();
+  });
+
+  // ─── 3. Neither available ──────────────────────────────────────────────────
+
+  it('throws search_api_key_missing when neither GEMINI_API_KEY nor OAuth are available', async () => {
+    delete process.env['GEMINI_API_KEY'];
+    const authManager = makeMockAuthManager({ isLoggedIn: false });
+
+    await expect(
+      Embedder.create(makeSearchConfig(), makeLogger(), authManager as never),
+    ).rejects.toSatisfy((err: unknown) => {
+      if (!(err instanceof NomosError)) return false;
+      if (err.code !== 'search_api_key_missing') return false;
+      // Error message must mention both GEMINI_API_KEY and arc auth login
+      return /GEMINI_API_KEY/i.test(err.message) && /arc auth login/i.test(err.message);
+    });
+  });
+
+  // ─── 4. No authManager provided ───────────────────────────────────────────
+
+  it('throws search_api_key_missing when GEMINI_API_KEY is unset and no authManager provided', async () => {
+    delete process.env['GEMINI_API_KEY'];
+
+    await expect(
+      Embedder.create(makeSearchConfig(), makeLogger(), null),
+    ).rejects.toSatisfy(
+      (err: unknown) => err instanceof NomosError && err.code === 'search_api_key_missing',
+    );
+  });
+});