@dommaker/harness 0.13.0 → 0.13.2

package/src/__tests__/failure-recorder.test.ts

@@ -0,0 +1,335 @@
+/**
+ * FailureRecorder 测试
+ */
+
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/globals';
+import { FailureRecorder, createFailureRecorder } from '../failure/recorder';
+import { ErrorType, FailureLevel } from '../failure/types';
+import * as fs from 'fs';
+import * as path from 'path';
+import type { FailureRecord } from '../failure/types';
+
+describe('FailureRecorder', () => {
+  const tempDir = path.join(process.cwd(), 'temp-test-recorder');
+  const logFile = path.join(tempDir, 'failures.log');
+  let recorder: FailureRecorder;
+
+  beforeAll(() => {
+    fs.mkdirSync(tempDir, { recursive: true });
+  });
+
+  afterAll(() => {
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  beforeEach(() => {
+    // 每个测试前清空日志文件
+    fs.writeFileSync(logFile, '');
+    recorder = new FailureRecorder({ logFile });
+  });
+
+  describe('record', () => {
+    it('应该记录失败', async () => {
+      const record: FailureRecord = {
+        type: ErrorType.TEST_FAILED,
+        level: FailureLevel.L1,
+        message: 'Test failed',
+        timestamp: Date.now(),
+      };
+
+      await recorder.record(record);
+
+      const content = fs.readFileSync(logFile, 'utf-8');
+      expect(content).toContain('TEST_FAILED');
+      expect(content).toContain('Test failed');
+    });
+
+    it('应该追加多条记录', async () => {
+      const record1: FailureRecord = {
+        type: ErrorType.NETWORK_ERROR,
+        level: FailureLevel.L1,
+        message: 'Network failed',
+        timestamp: Date.now(),
+      };
+      const record2: FailureRecord = {
+        type: ErrorType.TIMEOUT,
+        level: FailureLevel.L2,
+        message: 'Timeout occurred',
+        timestamp: Date.now(),
+      };
+
+      await recorder.record(record1);
+      await recorder.record(record2);
+
+      const content = fs.readFileSync(logFile, 'utf-8');
+      expect(content).toContain('NETWORK_ERROR');
+      expect(content).toContain('TIMEOUT');
+    });
+
+    it('应该记录完整字段', async () => {
+      const record: FailureRecord = {
+        type: ErrorType.VALIDATION_ERROR,
+        level: FailureLevel.L3,
+        message: 'Validation error with details',
+        timestamp: 1234567890,
+        metadata: { 
+          file: 'test.ts', 
+          line: 42,
+          stack: 'Error at line 42',
+          userId: 'user-001' 
+        },
+      };
+
+      await recorder.record(record);
+
+      const content = fs.readFileSync(logFile, 'utf-8');
+      expect(content).toContain('VALIDATION_ERROR');
+      expect(content).toContain('L3');
+      expect(content).toContain('test.ts');
+      expect(content).toContain('user-001');
+    });
+  });
+
+  describe('recordBatch', () => {
+    it('应该批量记录', async () => {
+      const records: FailureRecord[] = [
+        { type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'Test 1', timestamp: Date.now() },
+        { type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'Test 2', timestamp: Date.now() },
+        { type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'Test 3', timestamp: Date.now() },
+      ];
+
+      await recorder.recordBatch(records);
+
+      const history = await recorder.getHistory();
+      expect(history.length).toBe(3);
+    });
+  });
+
+  describe('getHistory', () => {
+    it('应该读取所有记录', async () => {
+      await recorder.record({ type: ErrorType.VALIDATION_ERROR, level: FailureLevel.L2, message: 'V1', timestamp: Date.now() });
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'T1', timestamp: Date.now() });
+
+      const records = await recorder.getHistory();
+      expect(records.length).toBe(2);
+    });
+
+    it('应该支持 limit 参数', async () => {
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'T1', timestamp: Date.now() });
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'T2', timestamp: Date.now() });
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'T3', timestamp: Date.now() });
+
+      const records = await recorder.getHistory(2);
+      expect(records.length).toBe(2);
+      // 应该返回最后 2 条
+      expect(records[0].message).toBe('T2');
+      expect(records[1].message).toBe('T3');
+    });
+
+    it('空文件应该返回空数组', async () => {
+      const emptyLogFile = path.join(tempDir, 'empty.log');
+      fs.writeFileSync(emptyLogFile, '');
+
+      const emptyRecorder = new FailureRecorder({ logFile: emptyLogFile });
+      const records = await emptyRecorder.getHistory();
+
+      expect(records).toEqual([]);
+    });
+
+    it('文件不存在应该返回空数组', async () => {
+      const nonexistentRecorder = new FailureRecorder({ logFile: path.join(tempDir, 'nonexistent.log') });
+      const records = await nonexistentRecorder.getHistory();
+      expect(records).toEqual([]);
+    });
+  });
+
+  describe('getByType', () => {
+    it('应该按类型过滤记录', async () => {
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'Test 1', timestamp: Date.now() });
+      await recorder.record({ type: ErrorType.NETWORK_ERROR, level: FailureLevel.L1, message: 'Network 1', timestamp: Date.now() });
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'Test 2', timestamp: Date.now() });
+
+      const testRecords = await recorder.getByType(ErrorType.TEST_FAILED);
+      expect(testRecords.length).toBe(2);
+
+      const networkRecords = await recorder.getByType(ErrorType.NETWORK_ERROR);
+      expect(networkRecords.length).toBe(1);
+    });
+
+    it('应该支持 limit 参数', async () => {
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'T1', timestamp: Date.now() });
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'T2', timestamp: Date.now() });
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'T3', timestamp: Date.now() });
+
+      const records = await recorder.getByType(ErrorType.TEST_FAILED, 2);
+      expect(records.length).toBe(2);
+    });
+  });
+
+  describe('getByLevel', () => {
+    it('应该按等级过滤记录', async () => {
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'L1 error', timestamp: Date.now() });
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L2, message: 'L2 error', timestamp: Date.now() });
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'Another L1', timestamp: Date.now() });
+
+      const l1Records = await recorder.getByLevel(FailureLevel.L1);
+      expect(l1Records.length).toBe(2);
+
+      const l2Records = await recorder.getByLevel(FailureLevel.L2);
+      expect(l2Records.length).toBe(1);
+    });
+
+    it('应该支持 limit 参数', async () => {
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'L1-1', timestamp: Date.now() });
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'L1-2', timestamp: Date.now() });
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'L1-3', timestamp: Date.now() });
+
+      const records = await recorder.getByLevel(FailureLevel.L1, 2);
+      expect(records.length).toBe(2);
+    });
+  });
+
+  describe('getStats', () => {
+    it('应该返回统计信息', async () => {
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'T1', timestamp: Date.now() });
+      await recorder.record({ type: ErrorType.NETWORK_ERROR, level: FailureLevel.L2, message: 'N1', timestamp: Date.now() });
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'T2', timestamp: Date.now() });
+
+      const stats = await recorder.getStats();
+
+      expect(stats.total).toBe(3);
+      expect(stats.byType[ErrorType.TEST_FAILED]).toBe(2);
+      expect(stats.byType[ErrorType.NETWORK_ERROR]).toBe(1);
+      expect(stats.byLevel[FailureLevel.L1]).toBe(2);
+      expect(stats.byLevel[FailureLevel.L2]).toBe(1);
+    });
+
+    it('空记录应该返回零统计', async () => {
+      const stats = await recorder.getStats();
+      expect(stats.total).toBe(0);
+      expect(Object.keys(stats.byType).length).toBe(0);
+      expect(Object.keys(stats.byLevel).length).toBe(0);
+    });
+  });
+
+  describe('clear', () => {
+    it('应该清空记录', async () => {
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'Test', timestamp: Date.now() });
+      await recorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: 'Test 2', timestamp: Date.now() });
+
+      await recorder.clear();
+
+      const records = await recorder.getHistory();
+      expect(records).toEqual([]);
+    });
+
+    it('文件不存在时清空不应报错', async () => {
+      const newRecorder = new FailureRecorder({ logFile: path.join(tempDir, 'new.log') });
+      await expect(newRecorder.clear()).resolves.not.toThrow();
+    });
+  });
+
+  describe('文件滚动', () => {
+    it('文件超过大小限制时应该滚动', async () => {
+      const smallLogFile = path.join(tempDir, 'small.log');
+      const smallRecorder = new FailureRecorder({
+        logFile: smallLogFile,
+        maxFileSize: 100, // 100 bytes
+        maxHistoryFiles: 3,
+      });
+
+      // 写入超过 100 bytes 的数据
+      const largeMessage = 'x'.repeat(150);
+      await smallRecorder.record({ type: ErrorType.TEST_FAILED, level: FailureLevel.L1, message: largeMessage, timestamp: Date.now() });
+
+      // 检查是否创建了历史文件
+      const historyFile1 = smallLogFile.replace('.log', '.1.log');
+      const fileExists = fs.existsSync(historyFile1) || !fs.existsSync(smallLogFile);
+      // 滚动可能发生也可能不发生，取决于写入顺序
+      expect(fileExists || fs.existsSync(smallLogFile)).toBe(true);
+    });
+
+    it('应该限制历史文件数量', async () => {
+      const rotateLogFile = path.join(tempDir, 'rotate.log');
+      const rotateRecorder = new FailureRecorder({
+        logFile: rotateLogFile,
+        maxFileSize: 50,
+        maxHistoryFiles: 2,
+      });
+
+      // 多次写入触发滚动
+      for (let i = 0; i < 5; i++) {
+        await rotateRecorder.record({
+          type: ErrorType.TEST_FAILED,
+          level: FailureLevel.L1,
+          message: 'x'.repeat(100),
+          timestamp: Date.now(),
+        });
+      }
+
+      // 检查历史文件数量不超过 maxHistoryFiles
+      const dir = path.dirname(rotateLogFile);
+      const base = path.basename(rotateLogFile, '.log');
+      const historyFiles = fs.readdirSync(dir).filter(f => f.startsWith(base) && f !== path.basename(rotateLogFile));
+      expect(historyFiles.length).toBeLessThanOrEqual(2);
+    });
+  });
+
+  describe('配置', () => {
+    it('应该支持自定义最大文件大小', () => {
+      const customRecorder = new FailureRecorder({
+        logFile: path.join(tempDir, 'custom.log'),
+        maxFileSize: 1024 * 1024, // 1MB
+      });
+      expect(customRecorder).toBeDefined();
+    });
+
+    it('应该支持自定义历史文件数', () => {
+      const customRecorder = new FailureRecorder({
+        logFile: path.join(tempDir, 'custom.log'),
+        maxHistoryFiles: 10,
+      });
+      expect(customRecorder).toBeDefined();
+    });
+
+    it('应该自动创建目录', () => {
+      const nestedLogFile = path.join(tempDir, 'nested', 'dir', 'failures.log');
+      const nestedRecorder = new FailureRecorder({ logFile: nestedLogFile });
+      expect(nestedRecorder).toBeDefined();
+      expect(fs.existsSync(path.dirname(nestedLogFile))).toBe(true);
+    });
+  });
+
+  describe('元数据', () => {
+    it('应该记录元数据', async () => {
+      const record: FailureRecord = {
+        type: ErrorType.GATE_FAILED,
+        level: FailureLevel.L2,
+        message: 'Gate failed',
+        timestamp: Date.now(),
+        metadata: {
+          gate: 'passes-gate',
+          taskId: 'TASK-001',
+        },
+      };
+
+      await recorder.record(record);
+
+      const content = fs.readFileSync(logFile, 'utf-8');
+      expect(content).toContain('passes-gate');
+      expect(content).toContain('TASK-001');
+    });
+  });
+
+  describe('createFailureRecorder', () => {
+    it('便捷函数应该创建 recorder', () => {
+      const r = createFailureRecorder({ logFile: path.join(tempDir, 'create.log') });
+      expect(r).toBeDefined();
+      expect(r).toBeInstanceOf(FailureRecorder);
+    });
+  });
+});

package/src/__tests__/hooks-pipeline.test.ts

@@ -0,0 +1,214 @@
+/**
+ * HookRegistry + HookPipeline 测试（Phase 1）
+ */
+import { describe, it, expect, beforeEach } from '@jest/globals';
+import { HookRegistry } from '../hooks/registry';
+import { HookPipeline } from '../hooks/pipeline';
+import type { HookDefinition } from '../hooks/types';
+
+interface TestContext {
+  value: string;
+  calls: string[];
+}
+
+function makeHook(
+  name: string,
+  opts: Partial<HookDefinition<TestContext, unknown>> = {}
+): HookDefinition<TestContext, unknown> {
+  return {
+    name,
+    phase: 'before',
+    priority: 100,
+    errorStrategy: 'block',
+    execute: async (ctx) => {
+      ctx.calls.push(name);
+      return { passed: true };
+    },
+    ...opts,
+  };
+}
+
+describe('HookRegistry', () => {
+  let registry: HookRegistry<TestContext, unknown>;
+
+  beforeEach(() => {
+    registry = new HookRegistry();
+  });
+
+  it('应注册 hook', () => {
+    registry.register(makeHook('test'));
+    expect(registry.get('test')).toBeDefined();
+  });
+
+  it('同名注册应覆盖', () => {
+    registry.register(makeHook('test', { priority: 50 }));
+    registry.register(makeHook('test', { priority: 90 }));
+    expect(registry.get('test')?.priority).toBe(90);
+  });
+
+  it('应获取已启用的 hook 按优先级排序', () => {
+    registry.register(makeHook('low', { priority: 200 }));
+    registry.register(makeHook('high', { priority: 10 }));
+    registry.register(makeHook('mid', { priority: 100 }));
+    registry.register(makeHook('disabled', { enabled: false }));
+
+    const enabled = registry.getEnabled('before');
+    expect(enabled.map(h => h.name)).toEqual(['high', 'mid', 'low']);
+  });
+
+  it('应注销 hook', () => {
+    registry.register(makeHook('test'));
+    expect(registry.unregister('test')).toBe(true);
+    expect(registry.get('test')).toBeUndefined();
+  });
+
+  it('应设置启用/禁用', () => {
+    registry.register(makeHook('test'));
+    expect(registry.setEnabled('test', false)).toBe(true);
+    expect(registry.getEnabled('before').length).toBe(0);
+    expect(registry.setEnabled('test', true)).toBe(true);
+    expect(registry.getEnabled('before').length).toBe(1);
+  });
+
+  it('应正确统计数量', () => {
+    expect(registry.size).toBe(0);
+    registry.register(makeHook('a'));
+    registry.register(makeHook('b'));
+    expect(registry.size).toBe(2);
+  });
+});
+
+describe('HookPipeline', () => {
+  let registry: HookRegistry<TestContext, unknown>;
+  let pipeline: HookPipeline<TestContext>;
+
+  beforeEach(() => {
+    registry = new HookRegistry();
+    pipeline = new HookPipeline(registry);
+  });
+
+  it('应执行所有 before hook', async () => {
+    const ctx: TestContext = { value: '', calls: [] };
+    registry.register(makeHook('h1'));
+    registry.register(makeHook('h2'));
+
+    const result = await pipeline.run('before', ctx);
+
+    expect(result.passed).toBe(true);
+    expect(ctx.calls).toEqual(['h1', 'h2']);
+    expect(result.records.length).toBe(2);
+  });
+
+  it('blocking hook 失败应停止后续', async () => {
+    const ctx: TestContext = { value: '', calls: [] };
+    registry.register(makeHook('pass1'));
+    registry.register(makeHook('block', {
+      execute: async () => ({ passed: false, error: 'blocked' }),
+      errorStrategy: 'block',
+    }));
+    registry.register(makeHook('never_runs'));
+
+    const result = await pipeline.run('before', ctx);
+
+    expect(result.passed).toBe(false);
+    expect(result.blockedBy).toEqual(['block']);
+    // block hook 的 execute 被覆盖，不 push calls
+    expect(ctx.calls).toEqual(['pass1']);
+    expect(ctx.calls).not.toContain('never_runs');
+  });
+
+  it('warn hook 失败应继续但记录警告', async () => {
+    const ctx: TestContext = { value: '', calls: [] };
+    registry.register(makeHook('warn_hook', {
+      execute: async () => ({ passed: false, error: 'warning' }),
+      errorStrategy: 'warn',
+    }));
+    registry.register(makeHook('should_still_run'));
+
+    const result = await pipeline.run('before', ctx);
+
+    expect(result.passed).toBe(true);
+    expect(result.warnings).toEqual(['warn_hook']);
+    expect(ctx.calls).toContain('should_still_run');
+  });
+
+  it('ignore hook 失败应静默继续', async () => {
+    const ctx: TestContext = { value: '', calls: [] };
+    registry.register(makeHook('ignore_hook', {
+      execute: async () => ({ passed: false, error: 'ignored' }),
+      errorStrategy: 'ignore',
+    }));
+    registry.register(makeHook('still_runs'));
+
+    const result = await pipeline.run('before', ctx);
+
+    expect(result.passed).toBe(true);
+    expect(result.warnings).toEqual([]);
+    expect(ctx.calls).toContain('still_runs');
+  });
+
+  it('hook 抛异常应被捕获', async () => {
+    const ctx: TestContext = { value: '', calls: [] };
+    registry.register(makeHook('throws', {
+      execute: async () => { throw new Error('crash'); },
+      errorStrategy: 'warn',
+    }));
+    registry.register(makeHook('after_crash', { priority: 200 }));
+
+    const result = await pipeline.run('before', ctx);
+
+    expect(result.records[0].error).toContain('crash');
+    expect(ctx.calls).toContain('after_crash');
+  });
+
+  it('runFull 应在 before/after 之间执行操作', async () => {
+    const ctx: TestContext = { value: '', calls: [] };
+    registry.register(makeHook('before_hook'));
+
+    const afterHook = makeHook('after_hook', { phase: 'after' });
+    registry.register(afterHook);
+
+    const { pipelineResult, operationResult } = await pipeline.runFull(ctx, async () => {
+      ctx.calls.push('operation');
+      return 'done';
+    });
+
+    expect(pipelineResult.passed).toBe(true);
+    expect(operationResult).toBe('done');
+    expect(ctx.calls).toEqual(['before_hook', 'operation', 'after_hook']);
+  });
+
+  it('before hook 失败不应执行操作', async () => {
+    const ctx: TestContext = { value: '', calls: [] };
+    registry.register(makeHook('block', {
+      execute: async () => ({ passed: false }),
+      errorStrategy: 'block',
+    }));
+
+    const { pipelineResult, operationResult } = await pipeline.runFull(ctx, async () => {
+      ctx.calls.push('should_not_run');
+      return 'nope';
+    });
+
+    expect(pipelineResult.passed).toBe(false);
+    expect(operationResult).toBeUndefined();
+    expect(ctx.calls).not.toContain('should_not_run');
+  });
+
+  it('空注册表应返回通过', async () => {
+    const result = await pipeline.run('before', { value: '', calls: [] });
+    expect(result.passed).toBe(true);
+    expect(result.records).toEqual([]);
+  });
+
+  it('应忽略 disabled hook', async () => {
+    const ctx: TestContext = { value: '', calls: [] };
+    registry.register(makeHook('enabled'));
+    registry.register(makeHook('disabled', { enabled: false }));
+
+    const result = await pipeline.run('before', ctx);
+
+    expect(ctx.calls).toEqual(['enabled']);
+    expect(ctx.calls).not.toContain('disabled');
+  });
+});

package/src/__tests__/interceptor.test.ts

@@ -0,0 +1,89 @@
+/**
+ * ConstraintInterceptor 测试
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { ConstraintInterceptor } from '../core/constraints/interceptor';
+import type { EnforcementExecutor } from '../types/enforcement';
+
+describe('ConstraintInterceptor', () => {
+  describe('单例模式', () => {
+    it('应该返回单例实例', () => {
+      const instance1 = ConstraintInterceptor.getInstance();
+      const instance2 = ConstraintInterceptor.getInstance();
+      expect(instance1).toBe(instance2);
+    });
+  });
+
+  describe('setEnabled', () => {
+    it('应该能启用/禁用拦截器', () => {
+      const interceptor = ConstraintInterceptor.getInstance();
+      
+      interceptor.setEnabled(false);
+      interceptor.setEnabled(true);
+      
+      expect(interceptor).toBeDefined();
+    });
+  });
+
+  describe('register', () => {
+    it('应该能注册执行器', () => {
+      const interceptor = ConstraintInterceptor.getInstance();
+      
+      const executor: EnforcementExecutor = {
+        execute: async () => ({
+          passed: true,
+          message: 'test',
+        }),
+      };
+      
+      interceptor.register('test_executor', executor);
+      
+      expect(interceptor).toBeDefined();
+    });
+  });
+
+  describe('unregister', () => {
+    it('应该能注销执行器', () => {
+      const interceptor = ConstraintInterceptor.getInstance();
+      
+      const executor: EnforcementExecutor = {
+        execute: async () => ({
+          passed: true,
+          message: 'temp',
+        }),
+      };
+      
+      interceptor.register('temp_executor', executor);
+      
+      const removed = interceptor.unregister('temp_executor');
+      expect(removed).toBe(true);
+    });
+
+    it('注销不存在的执行器应该返回 false', () => {
+      const interceptor = ConstraintInterceptor.getInstance();
+      
+      const removed = interceptor.unregister('nonexistent');
+      expect(removed).toBe(false);
+    });
+  });
+
+  describe('registerBatch', () => {
+    it('应该能批量注册', () => {
+      const interceptor = ConstraintInterceptor.getInstance();
+      
+      interceptor.registerBatch([
+        {
+          enforcementId: 'batch1',
+          executor: { execute: async () => ({ passed: true }) },
+        },
+        {
+          enforcementId: 'batch2',
+          executor: { execute: async () => ({ passed: true }) },
+        },
+      ]);
+      
+      expect(interceptor).toBeDefined();
+    });
+  });
+});