@nomos-arc/arc 0.1.0

package/src/core/graph/drift/__tests__/drift.test.ts

@@ -0,0 +1,453 @@
+import { describe, it, expect } from 'vitest';
+import { compare } from '../comparator.js';
+import { classify } from '../classifier.js';
+import { render } from '../reporter.js';
+import type {
+  FileNode,
+  ProjectMap,
+  SymbolEntry,
+  ImportEntry,
+  SemanticInfo,
+} from '../../../../types/index.js';
+
+// ─── Factory helpers (mirrored from comparator.test.ts pattern) ───────────────
+
+function makeSymbol(
+  overrides: Pick<SymbolEntry, 'name'> & Partial<SymbolEntry>,
+): SymbolEntry {
+  return {
+    kind: 'function',
+    line: 1,
+    end_line: null,
+    signature: null,
+    exported: false,
+    ...overrides,
+  };
+}
+
+function makeImport(
+  overrides: Pick<ImportEntry, 'source'> & Partial<ImportEntry>,
+): ImportEntry {
+  return {
+    resolved: null,
+    symbols: [],
+    is_external: false,
+    ...overrides,
+  };
+}
+
+function makeSemanticInfo(sourceHash: string): SemanticInfo {
+  return {
+    overview: 'test overview',
+    purpose: 'test purpose',
+    key_logic: [],
+    usage_context: [],
+    source_hash: sourceHash,
+    enriched_at: '2026-01-01T00:00:00.000Z',
+    model: 'gemini-1.5-pro',
+  };
+}
+
+function makeFileNode(
+  file: string,
+  hash: string,
+  overrides: Partial<Omit<FileNode, 'file' | 'hash'>> = {},
+): FileNode {
+  return {
+    file,
+    hash,
+    language: 'typescript',
+    symbols: [],
+    imports: [],
+    dependents: [],
+    dependencies: [],
+    depth: 0,
+    last_parsed_at: null,
+    semantic: null,
+    enrichment_status: 'structural',
+    ...overrides,
+  };
+}
+
+function makeMap(
+  files: Record<string, FileNode>,
+  statsOverrides: Partial<ProjectMap['stats']> = {},
+  generatedAt = '2026-01-01T00:00:00.000Z',
+): ProjectMap {
+  return {
+    schema_version: 1,
+    generated_at: generatedAt,
+    root: '/project',
+    files,
+    stats: {
+      total_files: Object.keys(files).length,
+      total_symbols: 0,
+      total_edges: 0,
+      core_modules: [],
+      structural_only: Object.keys(files).length,
+      semantically_enriched: 0,
+      indexed: 0,
+      ...statsOverrides,
+    },
+  };
+}
+
+// ─── Integration Tests ────────────────────────────────────────────────────────
+
+describe('arc drift — full pipeline integration (compare → classify → render)', () => {
+  it('1. full happy path — mixed changes produce correct DriftReport, ClassifiedDrift, and terminal output', () => {
+    // Baseline: 3 files
+    const baseline = makeMap(
+      {
+        'src/auth.ts': makeFileNode('src/auth.ts', 'hash-auth-v1', {
+          dependents: ['src/cli.ts'],
+          depth: 1,
+          symbols: [
+            makeSymbol({ name: 'login', exported: true, signature: '(): void' }),
+            makeSymbol({ name: 'logout', exported: true, signature: '(): void' }),
+          ],
+          imports: [
+            makeImport({ source: 'src/config.ts', resolved: 'src/config.ts', is_external: false }),
+          ],
+        }),
+        'src/config.ts': makeFileNode('src/config.ts', 'hash-config-v1', {
+          depth: 0,
+          symbols: [makeSymbol({ name: 'loadConfig', exported: true })],
+        }),
+        'src/old-utils.ts': makeFileNode('src/old-utils.ts', 'hash-old', {
+          dependents: ['src/auth.ts'],
+          symbols: [makeSymbol({ name: 'helper', exported: false })],
+        }),
+      },
+      { core_modules: ['src/config.ts'] },
+      '2026-01-01T00:00:00.000Z',
+    );
+
+    // Current: auth.ts modified (symbol signature changed, import added),
+    //          config.ts unchanged, old-utils.ts removed, new-logger.ts added,
+    //          depth change on auth.ts
+    const current = makeMap(
+      {
+        'src/auth.ts': makeFileNode('src/auth.ts', 'hash-auth-v2', {
+          dependents: ['src/cli.ts'],
+          depth: 3, // depth change of 2
+          symbols: [
+            makeSymbol({ name: 'login', exported: true, signature: '(opts: LoginOpts): void' }), // signature_changed
+            makeSymbol({ name: 'logout', exported: true, signature: '(): void' }),
+            makeSymbol({ name: 'refresh', exported: false, signature: '(): Promise<void>' }), // added
+          ],
+          imports: [
+            makeImport({ source: 'src/config.ts', resolved: 'src/config.ts', is_external: false }),
+            makeImport({ source: 'src/logger.ts', resolved: 'src/logger.ts', is_external: false }), // added
+          ],
+        }),
+        'src/config.ts': makeFileNode('src/config.ts', 'hash-config-v1', {
+          depth: 0,
+          symbols: [makeSymbol({ name: 'loadConfig', exported: true })],
+        }),
+        'src/new-logger.ts': makeFileNode('src/new-logger.ts', 'hash-logger', {
+          depth: 0,
+          symbols: [makeSymbol({ name: 'createLogger', exported: true })],
+        }),
+      },
+      { core_modules: ['src/config.ts', 'src/auth.ts'] }, // auth.ts promoted to core
+      '2026-04-11T00:00:00.000Z',
+    );
+
+    // ── compare ───────────────────────────────────────────────────────────────
+    const report = compare(baseline, current);
+
+    // Files: auth.ts modified, old-utils.ts removed, new-logger.ts added
+    expect(report.files).toHaveLength(3);
+    const authFileDiff = report.files.find((f) => f.file === 'src/auth.ts');
+    expect(authFileDiff?.status).toBe('modified');
+    const removedFileDiff = report.files.find((f) => f.file === 'src/old-utils.ts');
+    expect(removedFileDiff?.status).toBe('removed');
+    const addedFileDiff = report.files.find((f) => f.file === 'src/new-logger.ts');
+    expect(addedFileDiff?.status).toBe('added');
+
+    // Symbols: login signature_changed (exported, has dependents → breaking)
+    //          refresh added (info), helper removed (from old-utils.ts removal)
+    const loginDiff = report.symbols.find((s) => s.name === 'login');
+    expect(loginDiff?.status).toBe('signature_changed');
+    expect(loginDiff?.exported).toBe(true);
+    expect(loginDiff?.dependents_affected).toContain('src/cli.ts');
+
+    const refreshDiff = report.symbols.find((s) => s.name === 'refresh');
+    expect(refreshDiff?.status).toBe('added');
+
+    const helperDiff = report.symbols.find((s) => s.name === 'helper');
+    expect(helperDiff?.status).toBe('removed');
+    expect(helperDiff?.exported).toBe(false);
+
+    // Imports: src/logger.ts added to auth.ts
+    expect(report.imports).toHaveLength(1);
+    expect(report.imports[0].source).toBe('src/logger.ts');
+    expect(report.imports[0].status).toBe('added');
+
+    // Graph: depth change on auth.ts (1 → 3), core_modules_added: auth.ts
+    expect(report.graph.depth_changes).toHaveLength(1);
+    expect(report.graph.depth_changes[0].file).toBe('src/auth.ts');
+    expect(report.graph.depth_changes[0].before).toBe(1);
+    expect(report.graph.depth_changes[0].after).toBe(3);
+    expect(report.graph.core_modules_added).toContain('src/auth.ts');
+    expect(report.graph.core_modules_removed).toHaveLength(0);
+
+    // Summary
+    expect(report.summary.files_added).toBe(1);
+    expect(report.summary.files_removed).toBe(1);
+    expect(report.summary.files_modified).toBe(1);
+    expect(report.summary.symbols_changed).toBe(1);
+    expect(report.summary.symbols_added).toBe(1);
+    expect(report.summary.imports_added).toBe(1);
+    expect(report.summary.depth_changes).toBe(1);
+
+    // ── classify ──────────────────────────────────────────────────────────────
+    const classified = classify(report);
+
+    // login signature_changed, exported, has dependents → breaking
+    const breakingChange = classified.changes.find(
+      (c) => c.severity === 'breaking' && c.message.includes('login'),
+    );
+    expect(breakingChange).toBeDefined();
+    expect(classified.has_breaking).toBe(true);
+
+    // old-utils.ts removed → warning (file)
+    const fileWarning = classified.changes.find(
+      (c) => c.severity === 'warning' && c.message.includes('old-utils.ts'),
+    );
+    expect(fileWarning).toBeDefined();
+
+    // auth.ts promoted to core → info (graph)
+    const corePromoted = classified.changes.find(
+      (c) => c.severity === 'info' && c.message.includes('promoted to core'),
+    );
+    expect(corePromoted).toBeDefined();
+
+    // depth change on auth.ts (delta 2) → warning
+    const depthWarning = classified.changes.find(
+      (c) => c.severity === 'warning' && c.message.includes('depth change'),
+    );
+    expect(depthWarning).toBeDefined();
+
+    // Severity counts
+    const breakingCount = classified.changes.filter((c) => c.severity === 'breaking').length;
+    expect(breakingCount).toBeGreaterThanOrEqual(1);
+
+    // ── render (terminal) ─────────────────────────────────────────────────────
+    const output = render(classified, baseline.generated_at, current.generated_at, {
+      json: false,
+      breakingOnly: false,
+    });
+
+    expect(output).toContain('Drift Report: baseline');
+    expect(output).toContain('2026-01-01T00:00:00.000Z');
+    expect(output).toContain('2026-04-11T00:00:00.000Z');
+    expect(output).toContain('BREAKING');
+    expect(output).toContain('→');
+    expect(output).toContain('Summary:');
+  });
+
+  it('2. no changes — same map as baseline and current produces zero-count DriftReport', () => {
+    const map = makeMap({
+      'src/foo.ts': makeFileNode('src/foo.ts', 'hash-foo', {
+        symbols: [makeSymbol({ name: 'doFoo', exported: true })],
+      }),
+      'src/bar.ts': makeFileNode('src/bar.ts', 'hash-bar'),
+    });
+
+    const report = compare(map, map);
+
+    // All counters zero
+    expect(report.files).toHaveLength(0);
+    expect(report.symbols).toHaveLength(0);
+    expect(report.imports).toHaveLength(0);
+    expect(report.graph.depth_changes).toHaveLength(0);
+    expect(report.graph.core_modules_added).toHaveLength(0);
+    expect(report.graph.core_modules_removed).toHaveLength(0);
+    expect(report.stale_enrichments).toHaveLength(0);
+    Object.values(report.summary).forEach((v) => expect(v).toBe(0));
+
+    const classified = classify(report);
+    expect(classified.changes).toHaveLength(0);
+    expect(classified.has_breaking).toBe(false);
+
+    const output = render(classified, map.generated_at, map.generated_at, {
+      json: false,
+      breakingOnly: false,
+    });
+    expect(output).toContain('No drift detected');
+  });
+
+  it('3. breakingOnly — render() with breakingOnly=true only includes breaking changes', () => {
+    const baseline = makeMap({
+      'src/api.ts': makeFileNode('src/api.ts', 'hash-v1', {
+        dependents: ['src/consumer.ts'],
+        symbols: [
+          makeSymbol({ name: 'fetchUser', exported: true, signature: '(id: string): User' }),
+          makeSymbol({ name: 'fetchList', exported: false, signature: '(): User[]' }),
+        ],
+      }),
+    });
+
+    const current = makeMap({
+      'src/api.ts': makeFileNode('src/api.ts', 'hash-v2', {
+        dependents: ['src/consumer.ts'],
+        symbols: [
+          makeSymbol({
+            name: 'fetchUser',
+            exported: true,
+            signature: '(id: string, opts: Options): User', // signature_changed
+          }),
+          // fetchList removed (not exported → info)
+        ],
+      }),
+      'src/helpers.ts': makeFileNode('src/helpers.ts', 'hash-helpers'), // added → info
+    });
+
+    const report = compare(baseline, current);
+    const classified = classify(report);
+
+    // Confirm there are both breaking and non-breaking changes
+    const severities = new Set(classified.changes.map((c) => c.severity));
+    expect(severities.has('breaking')).toBe(true);
+
+    const breakingOnlyOutput = render(classified, baseline.generated_at, current.generated_at, {
+      json: false,
+      breakingOnly: true,
+    });
+
+    expect(breakingOnlyOutput).toContain('BREAKING');
+    // WARNING and INFO sections should not appear
+    expect(breakingOnlyOutput).not.toContain('WARNING (');
+    expect(breakingOnlyOutput).not.toContain('INFO (');
+  });
+
+  it('4. --json — render() with json=true produces valid JSON matching ClassifiedDrift schema', () => {
+    const baseline = makeMap({
+      'src/mod.ts': makeFileNode('src/mod.ts', 'hash-a', {
+        symbols: [makeSymbol({ name: 'go', exported: true })],
+      }),
+    });
+    const current = makeMap({
+      'src/mod.ts': makeFileNode('src/mod.ts', 'hash-b', {
+        symbols: [makeSymbol({ name: 'go', exported: true, signature: '(): void' })],
+      }),
+      'src/new.ts': makeFileNode('src/new.ts', 'hash-new'),
+    });
+
+    const report = compare(baseline, current);
+    const classified = classify(report);
+
+    const jsonOutput = render(classified, baseline.generated_at, current.generated_at, {
+      json: true,
+      breakingOnly: false,
+    });
+
+    // Must be valid JSON
+    let parsed: ReturnType<JSON['parse']>;
+    expect(() => {
+      parsed = JSON.parse(jsonOutput);
+    }).not.toThrow();
+
+    // Must match the expected schema
+    expect(parsed).toHaveProperty('baseline_generated_at', baseline.generated_at);
+    expect(parsed).toHaveProperty('current_generated_at', current.generated_at);
+    expect(parsed).toHaveProperty('has_breaking');
+    expect(Array.isArray(parsed.changes)).toBe(true);
+    expect(parsed).toHaveProperty('summary');
+
+    // Each change entry must have the required shape
+    for (const change of parsed.changes) {
+      expect(change).toHaveProperty('severity');
+      expect(change).toHaveProperty('category');
+      expect(change).toHaveProperty('message');
+      expect(change).toHaveProperty('file');
+      expect(change).toHaveProperty('detail');
+      expect(change).toHaveProperty('suggestion');
+    }
+  });
+
+  it('4b. --json with breakingOnly filters changes array to breaking severity only', () => {
+    const baseline = makeMap({
+      'src/svc.ts': makeFileNode('src/svc.ts', 'hash-v1', {
+        dependents: ['src/consumer.ts'],
+        symbols: [
+          makeSymbol({ name: 'publicFn', exported: true, signature: '(): void' }),
+          makeSymbol({ name: 'internalFn', exported: false }),
+        ],
+      }),
+    });
+
+    const current = makeMap({
+      'src/svc.ts': makeFileNode('src/svc.ts', 'hash-v2', {
+        dependents: ['src/consumer.ts'],
+        symbols: [
+          makeSymbol({ name: 'publicFn', exported: true, signature: '(opts: Opts): void' }), // breaking
+          // internalFn removed → info
+        ],
+      }),
+      'src/extra.ts': makeFileNode('src/extra.ts', 'hash-extra'), // added → info
+    });
+
+    const report = compare(baseline, current);
+    const classified = classify(report);
+
+    const jsonOutput = render(classified, baseline.generated_at, current.generated_at, {
+      json: true,
+      breakingOnly: true,
+    });
+
+    const parsed = JSON.parse(jsonOutput);
+    expect(parsed.changes.every((c: { severity: string }) => c.severity === 'breaking')).toBe(true);
+  });
+
+  it('5. backward compat — baseline without enrichment_status (defaults to "structural") is handled gracefully', () => {
+    // Simulate a baseline FileNode without enrichment_status (as if loaded from an older schema).
+    // Zod should default enrichment_status to 'structural' during migration.
+    // Here we verify compare() does not crash and stale_enrichments works correctly.
+    const baselineFile = makeFileNode('src/legacy.ts', 'hash-leg-v1', {
+      semantic: makeSemanticInfo('hash-leg-v1'),
+      // enrichment_status defaults to 'structural' — simulates pre-enrichment_status schema
+      enrichment_status: 'structural',
+    });
+
+    const baseline = makeMap({ 'src/legacy.ts': baselineFile });
+
+    // Current: file modified, semantic data is now stale (source_hash doesn't match current hash)
+    const currentFile = makeFileNode('src/legacy.ts', 'hash-leg-v2', {
+      semantic: makeSemanticInfo('hash-leg-v1'), // stale — still points to old hash
+      enrichment_status: 'semantic',
+    });
+    const current = makeMap({ 'src/legacy.ts': currentFile });
+
+    // compare() must not throw
+    let report;
+    expect(() => {
+      report = compare(baseline, current);
+    }).not.toThrow();
+
+    // The file was modified (different hashes)
+    expect(report!.files).toHaveLength(1);
+    expect(report!.files[0].status).toBe('modified');
+
+    // Stale enrichment detected: source_hash ('hash-leg-v1') !== current hash ('hash-leg-v2')
+    expect(report!.stale_enrichments).toHaveLength(1);
+    expect(report!.stale_enrichments[0].file).toBe('src/legacy.ts');
+    expect(report!.stale_enrichments[0].hash_changed).toBe(true);
+
+    // classify() must not throw and must return stale severity
+    const classified = classify(report!);
+    const staleChange = classified.changes.find((c) => c.severity === 'stale');
+    expect(staleChange).toBeDefined();
+    expect(staleChange?.file).toBe('src/legacy.ts');
+
+    // render() must not throw
+    expect(() =>
+      render(classified, baseline.generated_at, current.generated_at, {
+        json: false,
+        breakingOnly: false,
+      }),
+    ).not.toThrow();
+  });
+});

package/src/core/graph/drift/__tests__/reporter.test.ts

@@ -0,0 +1,203 @@
+import { describe, it, expect } from 'vitest';
+import { render } from '../reporter.js';
+import type { ClassifiedDrift, DriftReport } from '../../../../types/index.js';
+
+// ─── Fixture helpers ──────────────────────────────────────────────────────────
+
+function emptySummary(): DriftReport['summary'] {
+  return {
+    files_added: 0,
+    files_removed: 0,
+    files_modified: 0,
+    symbols_added: 0,
+    symbols_removed: 0,
+    symbols_changed: 0,
+    imports_added: 0,
+    imports_removed: 0,
+    depth_changes: 0,
+    stale_enrichments: 0,
+  };
+}
+
+function emptyDrift(): ClassifiedDrift {
+  return { changes: [], has_breaking: false, summary: emptySummary() };
+}
+
+function makeDrift(overrides: Partial<ClassifiedDrift> = {}): ClassifiedDrift {
+  return { ...emptyDrift(), ...overrides };
+}
+
+const BASELINE_DATE = '2026-01-01T00:00:00.000Z';
+const CURRENT_DATE = '2026-04-11T00:00:00.000Z';
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('render()', () => {
+  it('1. terminal output includes "Drift Report:" header with both dates', () => {
+    const output = render(emptyDrift(), BASELINE_DATE, CURRENT_DATE, {
+      json: false,
+      breakingOnly: false,
+    });
+    expect(output).toContain('Drift Report:');
+    expect(output).toContain(BASELINE_DATE);
+    expect(output).toContain(CURRENT_DATE);
+  });
+
+  it('2. terminal output groups changes with BREAKING before INFO', () => {
+    const drift = makeDrift({
+      has_breaking: true,
+      changes: [
+        {
+          severity: 'info',
+          category: 'file',
+          message: 'info change',
+          file: 'src/foo.ts',
+          detail: '',
+          suggestion: 'no action',
+        },
+        {
+          severity: 'breaking',
+          category: 'symbol',
+          message: 'breaking change',
+          file: 'src/bar.ts',
+          detail: '',
+          suggestion: 'fix it',
+        },
+      ],
+    });
+    const output = render(drift, BASELINE_DATE, CURRENT_DATE, { json: false, breakingOnly: false });
+    const breakingIndex = output.indexOf('BREAKING');
+    const infoIndex = output.indexOf('INFO');
+    expect(breakingIndex).toBeGreaterThanOrEqual(0);
+    expect(infoIndex).toBeGreaterThanOrEqual(0);
+    expect(breakingIndex).toBeLessThan(infoIndex);
+  });
+
+  it('3. terminal output includes "→" suggestion lines', () => {
+    const drift = makeDrift({
+      changes: [
+        {
+          severity: 'warning',
+          category: 'symbol',
+          message: 'some warning',
+          file: 'src/foo.ts',
+          detail: 'some detail',
+          suggestion: 'do something',
+        },
+      ],
+    });
+    const output = render(drift, BASELINE_DATE, CURRENT_DATE, { json: false, breakingOnly: false });
+    expect(output).toContain('→ do something');
+  });
+
+  it('4. terminal output includes summary footer line with counts', () => {
+    const summary = {
+      ...emptySummary(),
+      files_added: 2,
+      files_removed: 1,
+      files_modified: 3,
+    };
+    const drift = makeDrift({
+      summary,
+      changes: [
+        {
+          severity: 'info',
+          category: 'file',
+          message: 'File added: src/new.ts',
+          file: 'src/new.ts',
+          detail: '',
+          suggestion: 'no action',
+        },
+      ],
+    });
+    const output = render(drift, BASELINE_DATE, CURRENT_DATE, { json: false, breakingOnly: false });
+    expect(output).toContain('Summary:');
+    expect(output).toContain('2 added');
+    expect(output).toContain('1 removed');
+    expect(output).toContain('3 modified');
+  });
+
+  it('5. breakingOnly=true filters to only BREAKING section in terminal output', () => {
+    const drift = makeDrift({
+      has_breaking: true,
+      changes: [
+        {
+          severity: 'breaking',
+          category: 'symbol',
+          message: 'breaking change message',
+          file: 'src/bar.ts',
+          detail: '',
+          suggestion: 'fix it',
+        },
+        {
+          severity: 'info',
+          category: 'file',
+          message: 'info change message',
+          file: 'src/foo.ts',
+          detail: '',
+          suggestion: 'no action',
+        },
+      ],
+    });
+    const output = render(drift, BASELINE_DATE, CURRENT_DATE, { json: false, breakingOnly: true });
+    expect(output).toContain('breaking change message');
+    expect(output).not.toContain('info change message');
+    expect(output).not.toContain('INFO');
+  });
+
+  it('6. JSON output is valid JSON', () => {
+    const output = render(emptyDrift(), BASELINE_DATE, CURRENT_DATE, {
+      json: true,
+      breakingOnly: false,
+    });
+    expect(() => JSON.parse(output)).not.toThrow();
+  });
+
+  it('7. JSON output includes has_breaking, changes[], summary, and date fields', () => {
+    const drift = makeDrift({ has_breaking: false });
+    const output = render(drift, BASELINE_DATE, CURRENT_DATE, { json: true, breakingOnly: false });
+    const parsed = JSON.parse(output) as Record<string, unknown>;
+    expect(parsed).toHaveProperty('has_breaking', false);
+    expect(parsed).toHaveProperty('changes');
+    expect(Array.isArray(parsed['changes'])).toBe(true);
+    expect(parsed).toHaveProperty('summary');
+    expect(parsed).toHaveProperty('baseline_generated_at', BASELINE_DATE);
+    expect(parsed).toHaveProperty('current_generated_at', CURRENT_DATE);
+  });
+
+  it('8. JSON breakingOnly=true filters changes array to breaking only', () => {
+    const drift = makeDrift({
+      has_breaking: true,
+      changes: [
+        {
+          severity: 'breaking',
+          category: 'symbol',
+          message: 'breaking',
+          file: 'src/a.ts',
+          detail: '',
+          suggestion: '',
+        },
+        {
+          severity: 'warning',
+          category: 'file',
+          message: 'warning',
+          file: 'src/b.ts',
+          detail: '',
+          suggestion: '',
+        },
+      ],
+    });
+    const output = render(drift, BASELINE_DATE, CURRENT_DATE, { json: true, breakingOnly: true });
+    const parsed = JSON.parse(output) as { changes: Array<{ severity: string }> };
+    expect(parsed.changes).toHaveLength(1);
+    expect(parsed.changes[0].severity).toBe('breaking');
+  });
+
+  it('9. empty drift (no changes) produces "No drift detected." in terminal output', () => {
+    const output = render(emptyDrift(), BASELINE_DATE, CURRENT_DATE, {
+      json: false,
+      breakingOnly: false,
+    });
+    expect(output).toContain('No drift detected.');
+  });
+});