@curl-runner/cli 1.9.0 → 1.11.0

package/src/snapshot/snapshot-formatter.ts

@@ -0,0 +1,170 @@
+import type { SnapshotCompareResult, SnapshotDiff } from '../types/config';
+
+const COLORS = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  dim: '\x1b[2m',
+  bright: '\x1b[1m',
+};
+
+/**
+ * Formats snapshot comparison results for terminal output.
+ */
+export class SnapshotFormatter {
+  private color(text: string, color: keyof typeof COLORS): string {
+    return `${COLORS[color]}${text}${COLORS.reset}`;
+  }
+
+  /**
+   * Formats the snapshot result for display.
+   */
+  formatResult(requestName: string, result: SnapshotCompareResult): string {
+    const lines: string[] = [];
+
+    if (result.isNew && result.updated) {
+      lines.push(
+        `  ${this.color('NEW', 'cyan')} Snapshot created for "${this.color(requestName, 'bright')}"`,
+      );
+      return lines.join('\n');
+    }
+
+    if (result.updated) {
+      lines.push(
+        `  ${this.color('UPDATED', 'yellow')} Snapshot updated for "${this.color(requestName, 'bright')}"`,
+      );
+      return lines.join('\n');
+    }
+
+    if (result.match) {
+      lines.push(
+        `  ${this.color('PASS', 'green')} Snapshot matches for "${this.color(requestName, 'bright')}"`,
+      );
+      return lines.join('\n');
+    }
+
+    // Mismatch
+    lines.push(
+      `  ${this.color('FAIL', 'red')} Snapshot mismatch for "${this.color(requestName, 'bright')}"`,
+    );
+    lines.push('');
+    lines.push(this.formatDiff(result.differences));
+    lines.push('');
+    lines.push(this.color('  Run with --update-snapshots (-u) to update', 'dim'));
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Formats differences for display.
+   */
+  formatDiff(differences: SnapshotDiff[]): string {
+    const lines: string[] = [];
+    lines.push(`  ${this.color('- Expected', 'red')}`);
+    lines.push(`  ${this.color('+ Received', 'green')}`);
+    lines.push('');
+
+    for (const diff of differences) {
+      lines.push(this.formatDifference(diff));
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Formats a single difference.
+   */
+  private formatDifference(diff: SnapshotDiff): string {
+    const lines: string[] = [];
+    const path = diff.path || '(root)';
+
+    switch (diff.type) {
+      case 'added':
+        lines.push(`  ${this.color(path, 'cyan')}:`);
+        lines.push(`    ${this.color(`+ ${this.stringify(diff.received)}`, 'green')}`);
+        break;
+
+      case 'removed':
+        lines.push(`  ${this.color(path, 'cyan')}:`);
+        lines.push(`    ${this.color(`- ${this.stringify(diff.expected)}`, 'red')}`);
+        break;
+
+      case 'changed':
+        lines.push(`  ${this.color(path, 'cyan')}:`);
+        lines.push(`    ${this.color(`- ${this.stringify(diff.expected)}`, 'red')}`);
+        lines.push(`    ${this.color(`+ ${this.stringify(diff.received)}`, 'green')}`);
+        break;
+
+      case 'type_mismatch':
+        lines.push(`  ${this.color(path, 'cyan')} (type mismatch):`);
+        lines.push(
+          `    ${this.color(`- ${this.stringify(diff.expected)} (${typeof diff.expected})`, 'red')}`,
+        );
+        lines.push(
+          `    ${this.color(`+ ${this.stringify(diff.received)} (${typeof diff.received})`, 'green')}`,
+        );
+        break;
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Converts value to display string.
+   */
+  private stringify(value: unknown): string {
+    if (value === undefined) {
+      return 'undefined';
+    }
+    if (value === null) {
+      return 'null';
+    }
+    if (typeof value === 'string') {
+      return `"${value}"`;
+    }
+    if (typeof value === 'object') {
+      const str = JSON.stringify(value);
+      // Truncate long values
+      if (str.length > 80) {
+        return `${str.slice(0, 77)}...`;
+      }
+      return str;
+    }
+    return String(value);
+  }
+
+  /**
+   * Formats summary statistics.
+   */
+  formatSummary(stats: SnapshotStats): string {
+    const parts: string[] = [];
+
+    if (stats.passed > 0) {
+      parts.push(this.color(`${stats.passed} passed`, 'green'));
+    }
+    if (stats.failed > 0) {
+      parts.push(this.color(`${stats.failed} failed`, 'red'));
+    }
+    if (stats.updated > 0) {
+      parts.push(this.color(`${stats.updated} updated`, 'yellow'));
+    }
+    if (stats.created > 0) {
+      parts.push(this.color(`${stats.created} created`, 'cyan'));
+    }
+
+    if (parts.length === 0) {
+      return '';
+    }
+
+    return `Snapshots: ${parts.join(', ')}`;
+  }
+}
+
+export interface SnapshotStats {
+  passed: number;
+  failed: number;
+  updated: number;
+  created: number;
+}

package/src/snapshot/snapshot-manager.test.ts

@@ -0,0 +1,204 @@
+import { describe, expect, test } from 'bun:test';
+import type { ExecutionResult } from '../types/config';
+import { filterSnapshotBody, SnapshotManager } from './snapshot-manager';
+
+describe('SnapshotManager', () => {
+  describe('getSnapshotPath', () => {
+    test('should generate correct snapshot path', () => {
+      const manager = new SnapshotManager({});
+      expect(manager.getSnapshotPath('tests/api.yaml')).toBe('tests/__snapshots__/api.snap.json');
+    });
+
+    test('should use custom directory', () => {
+      const manager = new SnapshotManager({ dir: '.snapshots' });
+      expect(manager.getSnapshotPath('api.yaml')).toBe('.snapshots/api.snap.json');
+    });
+
+    test('should handle nested paths', () => {
+      const manager = new SnapshotManager({});
+      expect(manager.getSnapshotPath('tests/integration/users.yaml')).toBe(
+        'tests/integration/__snapshots__/users.snap.json',
+      );
+    });
+  });
+
+  describe('createSnapshot', () => {
+    const mockResult: ExecutionResult = {
+      request: { url: 'https://api.example.com' },
+      success: true,
+      status: 200,
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Request-Id': 'abc123',
+      },
+      body: {
+        id: 1,
+        name: 'Test',
+        timestamp: '2024-01-01',
+      },
+    };
+
+    test('should create snapshot with body only by default', () => {
+      const manager = new SnapshotManager({});
+      const snapshot = manager.createSnapshot(mockResult, { include: ['body'] });
+
+      expect(snapshot.body).toEqual(mockResult.body);
+      expect(snapshot.status).toBeUndefined();
+      expect(snapshot.headers).toBeUndefined();
+      expect(snapshot.hash).toBeDefined();
+      expect(snapshot.updatedAt).toBeDefined();
+    });
+
+    test('should create snapshot with status', () => {
+      const manager = new SnapshotManager({});
+      const snapshot = manager.createSnapshot(mockResult, { include: ['status'] });
+
+      expect(snapshot.status).toBe(200);
+      expect(snapshot.body).toBeUndefined();
+    });
+
+    test('should create snapshot with headers (normalized)', () => {
+      const manager = new SnapshotManager({});
+      const snapshot = manager.createSnapshot(mockResult, { include: ['headers'] });
+
+      expect(snapshot.headers).toEqual({
+        'content-type': 'application/json',
+        'x-request-id': 'abc123',
+      });
+    });
+
+    test('should create snapshot with all components', () => {
+      const manager = new SnapshotManager({});
+      const snapshot = manager.createSnapshot(mockResult, {
+        include: ['status', 'headers', 'body'],
+      });
+
+      expect(snapshot.status).toBe(200);
+      expect(snapshot.headers).toBeDefined();
+      expect(snapshot.body).toBeDefined();
+    });
+  });
+
+  describe('hash', () => {
+    test('should generate consistent hashes', () => {
+      const manager = new SnapshotManager({});
+      const content = { id: 1, name: 'test' };
+
+      const hash1 = manager.hash(content);
+      const hash2 = manager.hash(content);
+
+      expect(hash1).toBe(hash2);
+    });
+
+    test('should generate different hashes for different content', () => {
+      const manager = new SnapshotManager({});
+
+      const hash1 = manager.hash({ id: 1 });
+      const hash2 = manager.hash({ id: 2 });
+
+      expect(hash1).not.toBe(hash2);
+    });
+  });
+
+  describe('mergeConfig', () => {
+    test('should return null if not enabled', () => {
+      const config = SnapshotManager.mergeConfig({}, undefined);
+      expect(config).toBeNull();
+    });
+
+    test('should handle boolean true', () => {
+      const config = SnapshotManager.mergeConfig({}, true);
+      expect(config).toEqual({
+        enabled: true,
+        include: ['body'],
+        exclude: [],
+        match: {},
+      });
+    });
+
+    test('should merge global and request excludes', () => {
+      const config = SnapshotManager.mergeConfig(
+        { exclude: ['*.timestamp'] },
+        { enabled: true, exclude: ['body.id'] },
+      );
+      expect(config?.exclude).toEqual(['*.timestamp', 'body.id']);
+    });
+
+    test('should override include from request config', () => {
+      const config = SnapshotManager.mergeConfig(
+        { include: ['body'] },
+        { enabled: true, include: ['status', 'body'] },
+      );
+      expect(config?.include).toEqual(['status', 'body']);
+    });
+
+    test('should use global enabled', () => {
+      const config = SnapshotManager.mergeConfig({ enabled: true }, undefined);
+      expect(config?.enabled).toBe(true);
+    });
+  });
+});
+
+describe('filterSnapshotBody', () => {
+  test('should return primitive values unchanged', () => {
+    expect(filterSnapshotBody('string', [])).toBe('string');
+    expect(filterSnapshotBody(123, [])).toBe(123);
+    expect(filterSnapshotBody(null, [])).toBe(null);
+  });
+
+  test('should return body unchanged if no excludes', () => {
+    const body = { id: 1, name: 'test' };
+    expect(filterSnapshotBody(body, [])).toEqual(body);
+  });
+
+  test('should filter exact paths', () => {
+    const body = { id: 1, timestamp: '2024-01-01', name: 'test' };
+    const result = filterSnapshotBody(body, ['body.timestamp']);
+    expect(result).toEqual({ id: 1, name: 'test' });
+  });
+
+  test('should filter wildcard paths', () => {
+    const body = {
+      user: { id: 1, createdAt: '2024-01-01' },
+      post: { id: 2, createdAt: '2024-01-02' },
+    };
+    const result = filterSnapshotBody(body, ['body.*.createdAt']);
+    expect(result).toEqual({
+      user: { id: 1 },
+      post: { id: 2 },
+    });
+  });
+
+  test('should filter array wildcards', () => {
+    const body = {
+      items: [
+        { id: 1, updatedAt: '2024-01-01' },
+        { id: 2, updatedAt: '2024-01-02' },
+      ],
+    };
+    const result = filterSnapshotBody(body, ['body.items[*].updatedAt']);
+    expect(result).toEqual({
+      items: [{ id: 1 }, { id: 2 }],
+    });
+  });
+
+  test('should handle nested objects', () => {
+    const body = {
+      data: {
+        user: {
+          id: 1,
+          meta: { lastLogin: '2024-01-01' },
+        },
+      },
+    };
+    const result = filterSnapshotBody(body, ['body.data.user.meta.lastLogin']);
+    expect(result).toEqual({
+      data: {
+        user: {
+          id: 1,
+          meta: {},
+        },
+      },
+    });
+  });
+});

package/src/snapshot/snapshot-manager.ts

@@ -0,0 +1,342 @@
+import * as path from 'node:path';
+import type {
+  ExecutionResult,
+  GlobalSnapshotConfig,
+  JsonValue,
+  Snapshot,
+  SnapshotCompareResult,
+  SnapshotConfig,
+  SnapshotFile,
+} from '../types/config';
+import { SnapshotDiffer } from './snapshot-differ';
+
+const SNAPSHOT_VERSION = 1;
+const DEFAULT_SNAPSHOT_DIR = '__snapshots__';
+
+/**
+ * Manages snapshot files: reading, writing, comparing, and updating.
+ */
+export class SnapshotManager {
+  private snapshotDir: string;
+  private globalConfig: GlobalSnapshotConfig;
+  private writeLocks: Map<string, Promise<void>> = new Map();
+
+  constructor(globalConfig: GlobalSnapshotConfig = {}) {
+    this.globalConfig = globalConfig;
+    this.snapshotDir = globalConfig.dir || DEFAULT_SNAPSHOT_DIR;
+  }
+
+  /**
+   * Gets the snapshot file path for a YAML file.
+   */
+  getSnapshotPath(yamlPath: string): string {
+    const dir = path.dirname(yamlPath);
+    const basename = path.basename(yamlPath, path.extname(yamlPath));
+    return path.join(dir, this.snapshotDir, `${basename}.snap.json`);
+  }
+
+  /**
+   * Loads snapshot file for a YAML file.
+   */
+  async load(yamlPath: string): Promise<SnapshotFile | null> {
+    const snapshotPath = this.getSnapshotPath(yamlPath);
+    try {
+      const file = Bun.file(snapshotPath);
+      if (!(await file.exists())) {
+        return null;
+      }
+      const content = await file.text();
+      return JSON.parse(content) as SnapshotFile;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Saves snapshot file with write queue for parallel safety.
+   */
+  async save(yamlPath: string, data: SnapshotFile): Promise<void> {
+    const snapshotPath = this.getSnapshotPath(yamlPath);
+
+    // Queue writes to prevent race conditions
+    const existingLock = this.writeLocks.get(snapshotPath);
+    const writePromise = (async () => {
+      if (existingLock) {
+        await existingLock;
+      }
+
+      // Ensure directory exists
+      const dir = path.dirname(snapshotPath);
+      const fs = await import('node:fs/promises');
+      await fs.mkdir(dir, { recursive: true });
+
+      // Write with pretty formatting
+      const content = JSON.stringify(data, null, 2);
+      await Bun.write(snapshotPath, content);
+    })();
+
+    this.writeLocks.set(snapshotPath, writePromise);
+    await writePromise;
+    this.writeLocks.delete(snapshotPath);
+  }
+
+  /**
+   * Gets a single snapshot by request name.
+   */
+  async get(yamlPath: string, requestName: string): Promise<Snapshot | null> {
+    const file = await this.load(yamlPath);
+    return file?.snapshots[requestName] || null;
+  }
+
+  /**
+   * Creates a snapshot from execution result.
+   */
+  createSnapshot(result: ExecutionResult, config: SnapshotConfig): Snapshot {
+    const include = config.include || ['body'];
+    const snapshot: Snapshot = {
+      hash: '',
+      updatedAt: new Date().toISOString(),
+    };
+
+    if (include.includes('status') && result.status !== undefined) {
+      snapshot.status = result.status;
+    }
+
+    if (include.includes('headers') && result.headers) {
+      // Normalize headers: lowercase keys, sorted
+      snapshot.headers = this.normalizeHeaders(result.headers);
+    }
+
+    if (include.includes('body') && result.body !== undefined) {
+      snapshot.body = result.body;
+    }
+
+    // Generate hash from content
+    snapshot.hash = this.hash(snapshot);
+
+    return snapshot;
+  }
+
+  /**
+   * Normalizes headers for consistent comparison.
+   */
+  private normalizeHeaders(headers: Record<string, string>): Record<string, string> {
+    const normalized: Record<string, string> = {};
+    const sortedKeys = Object.keys(headers).sort();
+    for (const key of sortedKeys) {
+      normalized[key.toLowerCase()] = headers[key];
+    }
+    return normalized;
+  }
+
+  /**
+   * Generates a hash for snapshot content.
+   */
+  hash(content: unknown): string {
+    const str = JSON.stringify(content);
+    const hasher = new Bun.CryptoHasher('md5');
+    hasher.update(str);
+    return hasher.digest('hex').slice(0, 8);
+  }
+
+  /**
+   * Compares execution result against stored snapshot and optionally updates.
+   */
+  async compareAndUpdate(
+    yamlPath: string,
+    requestName: string,
+    result: ExecutionResult,
+    config: SnapshotConfig,
+  ): Promise<SnapshotCompareResult> {
+    const snapshotName = config.name || requestName;
+    const existingSnapshot = await this.get(yamlPath, snapshotName);
+    const newSnapshot = this.createSnapshot(result, config);
+
+    // No existing snapshot
+    if (!existingSnapshot) {
+      if (this.globalConfig.ci) {
+        // CI mode: fail on missing snapshot
+        return {
+          match: false,
+          isNew: true,
+          updated: false,
+          differences: [
+            {
+              path: '',
+              expected: 'snapshot',
+              received: 'none',
+              type: 'removed',
+            },
+          ],
+        };
+      }
+
+      // Create new snapshot
+      await this.updateSnapshot(yamlPath, snapshotName, newSnapshot);
+      return {
+        match: true,
+        isNew: true,
+        updated: true,
+        differences: [],
+      };
+    }
+
+    // Compare snapshots
+    const differ = new SnapshotDiffer(config);
+    const diffResult = differ.compare(existingSnapshot, newSnapshot);
+
+    if (diffResult.match) {
+      return {
+        match: true,
+        isNew: false,
+        updated: false,
+        differences: [],
+      };
+    }
+
+    // Handle update modes
+    const updateMode = this.globalConfig.updateMode || 'none';
+    if (updateMode === 'all' || updateMode === 'failing') {
+      await this.updateSnapshot(yamlPath, snapshotName, newSnapshot);
+      return {
+        match: true,
+        isNew: false,
+        updated: true,
+        differences: diffResult.differences,
+      };
+    }
+
+    return {
+      match: false,
+      isNew: false,
+      updated: false,
+      differences: diffResult.differences,
+    };
+  }
+
+  /**
+   * Updates a single snapshot in the file.
+   */
+  private async updateSnapshot(
+    yamlPath: string,
+    snapshotName: string,
+    snapshot: Snapshot,
+  ): Promise<void> {
+    let file = await this.load(yamlPath);
+    if (!file) {
+      file = {
+        version: SNAPSHOT_VERSION,
+        snapshots: {},
+      };
+    }
+
+    file.snapshots[snapshotName] = snapshot;
+    await this.save(yamlPath, file);
+  }
+
+  /**
+   * Merges request-level config with global config.
+   */
+  static mergeConfig(
+    globalConfig: GlobalSnapshotConfig | undefined,
+    requestConfig: SnapshotConfig | boolean | undefined,
+  ): SnapshotConfig | null {
+    // Not enabled
+    if (!requestConfig && !globalConfig?.enabled) {
+      return null;
+    }
+
+    // Simple boolean enable
+    if (requestConfig === true) {
+      return {
+        enabled: true,
+        include: globalConfig?.include || ['body'],
+        exclude: globalConfig?.exclude || [],
+        match: globalConfig?.match || {},
+      };
+    }
+
+    // Detailed config
+    if (typeof requestConfig === 'object' && requestConfig.enabled !== false) {
+      return {
+        enabled: true,
+        name: requestConfig.name,
+        include: requestConfig.include || globalConfig?.include || ['body'],
+        exclude: [...(globalConfig?.exclude || []), ...(requestConfig.exclude || [])],
+        match: { ...(globalConfig?.match || {}), ...(requestConfig.match || {}) },
+      };
+    }
+
+    // Global enabled but request not specified
+    if (globalConfig?.enabled && requestConfig === undefined) {
+      return {
+        enabled: true,
+        include: globalConfig.include || ['body'],
+        exclude: globalConfig.exclude || [],
+        match: globalConfig.match || {},
+      };
+    }
+
+    return null;
+  }
+}
+
+/**
+ * Extracts body content for snapshot, applying exclusions.
+ */
+export function filterSnapshotBody(body: JsonValue, exclude: string[]): JsonValue {
+  if (body === null || typeof body !== 'object') {
+    return body;
+  }
+
+  const bodyExcludes = exclude.filter((p) => p.startsWith('body.')).map((p) => p.slice(5)); // Remove 'body.' prefix
+
+  if (bodyExcludes.length === 0) {
+    return body;
+  }
+
+  return filterObject(body, bodyExcludes, '');
+}
+
+function filterObject(obj: JsonValue, excludes: string[], currentPath: string): JsonValue {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item, index) => {
+      const itemPath = currentPath ? `${currentPath}[${index}]` : `[${index}]`;
+      return filterObject(item, excludes, itemPath);
+    });
+  }
+
+  const result: Record<string, JsonValue> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const fullPath = currentPath ? `${currentPath}.${key}` : key;
+
+    // Check if this path should be excluded
+    const shouldExclude = excludes.some((pattern) => {
+      // Exact match
+      if (pattern === fullPath) {
+        return true;
+      }
+      // Wildcard match (e.g., '*.timestamp' matches 'user.timestamp')
+      if (pattern.startsWith('*.')) {
+        const suffix = pattern.slice(2);
+        return fullPath.endsWith(`.${suffix}`) || fullPath === suffix;
+      }
+      // Array wildcard (e.g., '[*].id')
+      if (pattern.includes('[*]')) {
+        const regex = new RegExp(`^${pattern.replace(/\[\*\]/g, '\\[\\d+\\]')}$`);
+        return regex.test(fullPath);
+      }
+      return false;
+    });
+
+    if (!shouldExclude) {
+      result[key] = filterObject(value, excludes, fullPath);
+    }
+  }
+
+  return result;
+}