@dommaker/harness 0.13.0 → 0.13.2

package/src/verification/__tests__/loop.test.ts

@@ -0,0 +1,303 @@
+/**
+ * VerificationLoop 测试
+ */
+
+import { VerificationLoop } from '../loop';
+import type { VerificationLoopConfig, GatherState, VerificationResult } from '../types';
+
+describe('VerificationLoop', () => {
+  const baseConfig: VerificationLoopConfig = {
+    maxRetries: 3,
+    rules: [
+      {
+        id: 'test-rule',
+        type: 'custom',
+        name: 'Test Rule',
+        description: 'Test',
+        verify: async () => ({ passed: true, ruleId: 'test-rule', duration: 0 }),
+      },
+    ],
+  };
+
+  describe('run', () => {
+    it('应该在首次通过时返回 passed', async () => {
+      const loop = new VerificationLoop(baseConfig);
+      const gather = async (): Promise<GatherState> => ({
+        changedFiles: [],
+        metadata: {},
+      });
+
+      const snapshot = await loop.run({ projectRoot: '.' }, gather);
+      expect(snapshot.status).toBe('passed');
+      expect(snapshot.attempt).toBe(1);
+      expect(snapshot.results.every(r => r.passed)).toBe(true);
+    });
+
+    it('应该在验证失败时重试', async () => {
+      let callCount = 0;
+      const config: VerificationLoopConfig = {
+        maxRetries: 3,
+        rules: [
+          {
+            id: 'flaky',
+            type: 'custom',
+            name: 'Flaky',
+            description: '',
+            verify: async () => {
+              callCount++;
+              return {
+                passed: callCount >= 2,
+                ruleId: 'flaky',
+                message: callCount < 2 ? 'not yet' : 'ok',
+                duration: 0,
+              };
+            },
+          },
+        ],
+      };
+
+      const loop = new VerificationLoop(config);
+      const gather = async (): Promise<GatherState> => ({
+        changedFiles: [],
+        metadata: {},
+      });
+
+      const snapshot = await loop.run({ projectRoot: '.' }, gather);
+      expect(snapshot.status).toBe('passed');
+      expect(snapshot.attempt).toBe(2);
+    });
+
+    it('应该在达到最大重试次数后失败', async () => {
+      const config: VerificationLoopConfig = {
+        maxRetries: 2,
+        rules: [
+          {
+            id: 'always-fail',
+            type: 'custom',
+            name: 'Always Fail',
+            description: '',
+            verify: async () => ({
+              passed: false,
+              ruleId: 'always-fail',
+              message: 'nope',
+              duration: 0,
+            }),
+          },
+        ],
+      };
+
+      const loop = new VerificationLoop(config);
+      const gather = async (): Promise<GatherState> => ({
+        changedFiles: [],
+        metadata: {},
+      });
+
+      const snapshot = await loop.run({ projectRoot: '.' }, gather);
+      expect(snapshot.status).toBe('failed');
+      expect(snapshot.attempt).toBe(2);
+      expect(snapshot.lastError).toContain('最大重试次数');
+    });
+
+    it('failFast 应该在首次失败时立即停止', async () => {
+      let verifyCount = 0;
+      const config: VerificationLoopConfig = {
+        maxRetries: 5,
+        failFast: true,
+        rules: [
+          {
+            id: 'fail-fast-rule',
+            type: 'custom',
+            name: 'Fail Fast',
+            description: '',
+            verify: async () => {
+              verifyCount++;
+              return {
+                passed: false,
+                ruleId: 'fail-fast-rule',
+                duration: 0,
+              };
+            },
+          },
+        ],
+      };
+
+      const loop = new VerificationLoop(config);
+      const snapshot = await loop.run(
+        { projectRoot: '.' },
+        async () => ({ changedFiles: [], metadata: {} }),
+      );
+
+      expect(snapshot.status).toBe('failed');
+      expect(snapshot.attempt).toBe(1);
+      expect(verifyCount).toBe(1);
+    });
+
+    it('应该在 gather 失败时返回 failed', async () => {
+      const loop = new VerificationLoop(baseConfig);
+      const gather = async (): Promise<GatherState> => {
+        throw new Error('gather failed');
+      };
+
+      const snapshot = await loop.run({ projectRoot: '.' }, gather);
+      expect(snapshot.status).toBe('failed');
+      expect(snapshot.lastError).toContain('Gather 失败');
+    });
+
+    it('应该在 act 返回 abort 时中止', async () => {
+      let verifyCount = 0;
+      const config: VerificationLoopConfig = {
+        maxRetries: 3,
+        rules: [
+          {
+            id: 'fail-rule',
+            type: 'custom',
+            name: 'Fail',
+            description: '',
+            verify: async () => {
+              verifyCount++;
+              return { passed: false, ruleId: 'fail-rule', duration: 0 };
+            },
+          },
+        ],
+      };
+
+      const loop = new VerificationLoop(config);
+      const snapshot = await loop.run(
+        { projectRoot: '.' },
+        async () => ({ changedFiles: [], metadata: {} }),
+        async () => ({ type: 'abort', description: '无法修复' }),
+      );
+
+      expect(snapshot.status).toBe('failed');
+      expect(snapshot.lastError).toContain('中止');
+      // 只执行了 1 次 verify（第 2 轮 act 返回 abort 后未进入 verify）
+      expect(verifyCount).toBe(1);
+    });
+
+    it('应该在 act 返回 skip 时跳过', async () => {
+      const config: VerificationLoopConfig = {
+        maxRetries: 3,
+        rules: [
+          {
+            id: 'fail-rule',
+            type: 'custom',
+            name: 'Fail',
+            description: '',
+            verify: async () => ({ passed: false, ruleId: 'fail-rule', duration: 0 }),
+          },
+        ],
+      };
+
+      const loop = new VerificationLoop(config);
+      const snapshot = await loop.run(
+        { projectRoot: '.' },
+        async () => ({ changedFiles: [], metadata: {} }),
+        async () => ({ type: 'skip', description: '跳过' }),
+      );
+
+      expect(snapshot.status).toBe('passed');
+    });
+
+    it('第 1 轮不应该调用 act', async () => {
+      let actCalled = false;
+      const loop = new VerificationLoop(baseConfig);
+
+      const snapshot = await loop.run(
+        { projectRoot: '.' },
+        async () => ({ changedFiles: [], metadata: {} }),
+        async () => {
+          actCalled = true;
+          return { type: 'retry', description: 'retry' };
+        },
+      );
+
+      expect(snapshot.status).toBe('passed');
+      expect(actCalled).toBe(false);
+    });
+
+    it('应该在 act 抛出异常时返回 failed', async () => {
+      const config: VerificationLoopConfig = {
+        maxRetries: 3,
+        rules: [
+          {
+            id: 'fail-rule',
+            type: 'custom',
+            name: 'Fail',
+            description: '',
+            verify: async () => ({ passed: false, ruleId: 'fail-rule', duration: 0 }),
+          },
+        ],
+      };
+
+      const loop = new VerificationLoop(config);
+      const snapshot = await loop.run(
+        { projectRoot: '.' },
+        async () => ({ changedFiles: [], metadata: {} }),
+        async () => { throw new Error('act crashed'); },
+      );
+
+      expect(snapshot.status).toBe('failed');
+      expect(snapshot.lastError).toContain('Act 失败');
+      expect(snapshot.lastError).toContain('act crashed');
+    });
+
+    it('应该在 verify 函数抛出异常时视为失败并重试', async () => {
+      const config: VerificationLoopConfig = {
+        maxRetries: 2,
+        rules: [
+          {
+            id: 'throw-rule',
+            type: 'custom',
+            name: 'Throw',
+            description: '',
+            verify: async () => { throw new Error('verify crashed'); },
+          },
+        ],
+      };
+
+      const loop = new VerificationLoop(config);
+      const snapshot = await loop.run(
+        { projectRoot: '.' },
+        async () => ({ changedFiles: [], metadata: {} }),
+      );
+
+      // verifyRule 内部 catch 了异常，返回 passed: false
+      // 循环重试 maxRetries 次后失败
+      expect(snapshot.status).toBe('failed');
+      expect(snapshot.attempt).toBe(2);
+      expect(snapshot.results[0].message).toContain('verify crashed');
+    });
+  });
+
+  describe('snapshot', () => {
+    it('应该包含完整快照信息', async () => {
+      const loop = new VerificationLoop(baseConfig);
+      const snapshot = await loop.run(
+        { projectRoot: '.' },
+        async () => ({ changedFiles: [], metadata: {} }),
+      );
+
+      expect(snapshot.timestamp).toBeDefined();
+      expect(snapshot.maxRetries).toBe(3);
+      expect(Array.isArray(snapshot.results)).toBe(true);
+    });
+  });
+
+  describe('getters', () => {
+    it('应该返回当前状态', async () => {
+      const loop = new VerificationLoop(baseConfig);
+      expect(loop.getStatus()).toBe('idle');
+      expect(loop.getAttempt()).toBe(0);
+      expect(loop.getResults()).toEqual([]);
+
+      await loop.run(
+        { projectRoot: '.' },
+        async () => ({ changedFiles: [], metadata: {} }),
+      );
+
+      expect(loop.getStatus()).toBe('passed');
+      expect(loop.getAttempt()).toBe(1);
+      expect(loop.getResults().length).toBeGreaterThan(0);
+    });
+  });
+});

package/src/verification/__tests__/rules-based.test.ts

@@ -0,0 +1,240 @@
+/**
+ * RulesBasedVerification 测试
+ */
+
+import { RulesBasedVerification } from '../rules-based';
+import type { VerificationRule, VerificationContext } from '../types';
+
+describe('RulesBasedVerification', () => {
+  const context: VerificationContext = {
+    projectRoot: process.cwd(),
+  };
+
+  describe('verifyAll', () => {
+    it('应该通过空规则列表', async () => {
+      const verifier = new RulesBasedVerification([]);
+      const results = await verifier.verifyAll(context);
+      expect(results.length).toBe(0);
+    });
+
+    it('应该执行所有规则', async () => {
+      const rules: VerificationRule[] = [
+        {
+          id: 'rule-1',
+          type: 'custom',
+          name: 'Rule 1',
+          description: 'Always pass',
+          verify: async () => ({ passed: true, ruleId: 'rule-1', duration: 0 }),
+        },
+        {
+          id: 'rule-2',
+          type: 'custom',
+          name: 'Rule 2',
+          description: 'Always pass',
+          verify: async () => ({ passed: true, ruleId: 'rule-2', duration: 0 }),
+        },
+      ];
+
+      const verifier = new RulesBasedVerification(rules);
+      const results = await verifier.verifyAll(context);
+      expect(results.length).toBe(2);
+      expect(results.every(r => r.passed)).toBe(true);
+    });
+
+    it('应该收集失败结果', async () => {
+      const rules: VerificationRule[] = [
+        {
+          id: 'pass',
+          type: 'custom',
+          name: 'Pass',
+          description: '',
+          verify: async () => ({ passed: true, ruleId: 'pass', duration: 0 }),
+        },
+        {
+          id: 'fail',
+          type: 'custom',
+          name: 'Fail',
+          description: '',
+          verify: async () => ({ passed: false, ruleId: 'fail', message: 'failed', duration: 0 }),
+        },
+      ];
+
+      const verifier = new RulesBasedVerification(rules);
+      const results = await verifier.verifyAll(context);
+      expect(results.some(r => r.passed)).toBe(true);
+      expect(results.some(r => !r.passed)).toBe(true);
+    });
+  });
+
+  describe('command rules', () => {
+    it('应该执行成功的命令', async () => {
+      const rules: VerificationRule[] = [
+        {
+          id: 'echo',
+          type: 'test',
+          name: 'Echo Test',
+          description: 'Run echo',
+          command: 'echo "hello"',
+        },
+      ];
+
+      const verifier = new RulesBasedVerification(rules);
+      const results = await verifier.verifyAll(context);
+      expect(results[0].passed).toBe(true);
+      expect(results[0].details).toContain('hello');
+    });
+
+    it('应该处理失败的命令', async () => {
+      const rules: VerificationRule[] = [
+        {
+          id: 'fail-cmd',
+          type: 'test',
+          name: 'Fail Test',
+          description: 'Run failing command',
+          command: 'exit 1',
+        },
+      ];
+
+      const verifier = new RulesBasedVerification(rules);
+      const results = await verifier.verifyAll(context);
+      expect(results[0].passed).toBe(false);
+    });
+
+    it('应该处理缺少 command 的规则', async () => {
+      const rules: VerificationRule[] = [
+        {
+          id: 'no-cmd',
+          type: 'lint',
+          name: 'No Command',
+          description: 'Missing command',
+        },
+      ];
+
+      const verifier = new RulesBasedVerification(rules);
+      const results = await verifier.verifyAll(context);
+      expect(results[0].passed).toBe(false);
+      expect(results[0].message).toContain('缺少 command');
+    });
+  });
+
+  describe('custom rules', () => {
+    it('应该执行自定义验证函数', async () => {
+      const rules: VerificationRule[] = [
+        {
+          id: 'custom',
+          type: 'custom',
+          name: 'Custom Check',
+          description: 'Check changed files',
+          verify: async (ctx) => ({
+            passed: (ctx.changedFiles?.length ?? 0) > 0,
+            ruleId: 'custom',
+            message: '需要变更文件',
+            duration: 0,
+          }),
+        },
+      ];
+
+      const verifier = new RulesBasedVerification(rules);
+
+      // 没有变更文件 -> 失败
+      const failResults = await verifier.verifyAll(context);
+      expect(failResults[0].passed).toBe(false);
+
+      // 有变更文件 -> 通过
+      const passResults = await verifier.verifyAll({ ...context, changedFiles: ['a.ts'] });
+      expect(passResults[0].passed).toBe(true);
+    });
+
+    it('应该处理缺少 verify 的 custom 规则', async () => {
+      const rules: VerificationRule[] = [
+        {
+          id: 'no-verify',
+          type: 'custom',
+          name: 'No Verify',
+          description: 'Missing verify function',
+        },
+      ];
+
+      const verifier = new RulesBasedVerification(rules);
+      const results = await verifier.verifyAll(context);
+      expect(results[0].passed).toBe(false);
+      expect(results[0].message).toContain('缺少 verify');
+    });
+  });
+
+  describe('rule management', () => {
+    it('应该添加规则', () => {
+      const verifier = new RulesBasedVerification([]);
+      verifier.addRule({
+        id: 'new',
+        type: 'custom',
+        name: 'New',
+        description: '',
+        verify: async () => ({ passed: true, ruleId: 'new', duration: 0 }),
+      });
+      expect(verifier.getRules().length).toBe(1);
+    });
+
+    it('应该移除规则', () => {
+      const verifier = new RulesBasedVerification([
+        { id: 'a', type: 'custom', name: 'A', description: '' },
+        { id: 'b', type: 'custom', name: 'B', description: '' },
+      ]);
+      verifier.removeRule('a');
+      expect(verifier.getRules().length).toBe(1);
+      expect(verifier.getRules()[0].id).toBe('b');
+    });
+  });
+
+  describe('error handling', () => {
+    it('应该处理验证函数抛出异常', async () => {
+      const rules: VerificationRule[] = [
+        {
+          id: 'throw',
+          type: 'custom',
+          name: 'Throw',
+          description: '',
+          verify: async () => { throw new Error('boom'); },
+        },
+      ];
+
+      const verifier = new RulesBasedVerification(rules);
+      const results = await verifier.verifyAll(context);
+      expect(results[0].passed).toBe(false);
+      expect(results[0].message).toContain('boom');
+    });
+
+    it('应该处理未知规则类型', async () => {
+      const rules: VerificationRule[] = [
+        {
+          id: 'unknown',
+          type: 'unknown' as any,
+          name: 'Unknown',
+          description: '',
+        },
+      ];
+
+      const verifier = new RulesBasedVerification(rules);
+      const results = await verifier.verifyAll(context);
+      expect(results[0].passed).toBe(false);
+      expect(results[0].message).toContain('未知');
+    });
+
+    it('应该处理命令执行超时', async () => {
+      const rules: VerificationRule[] = [
+        {
+          id: 'timeout',
+          type: 'test',
+          name: 'Timeout Test',
+          description: '',
+          command: 'sleep 10',
+          timeout: 100,
+        },
+      ];
+
+      const verifier = new RulesBasedVerification(rules);
+      const results = await verifier.verifyAll(context);
+      expect(results[0].passed).toBe(false);
+    }, 10000);
+  });
+});

package/src/verification/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './rules-based';
+export * from './loop';

package/src/verification/loop.ts

@@ -0,0 +1,137 @@
+/**
+ * 验证循环（Gather-Act-Verify）
+ *
+ * 编排验证流程：
+ * 1. Gather：收集当前状态
+ * 2. Act：执行动作
+ * 3. Verify：验证结果
+ * 失败时重试，最多 N 次
+ */
+
+import type {
+  VerificationLoopConfig,
+  LoopSnapshot,
+  LoopStatus,
+  VerificationResult,
+  GatherState,
+  ActAction,
+  VerificationContext,
+} from './types';
+import { RulesBasedVerification } from './rules-based';
+
+export type GatherFn = (attempt: number) => Promise<GatherState>;
+export type ActFn = (state: GatherState, results: VerificationResult[]) => Promise<ActAction>;
+
+export class VerificationLoop {
+  private config: VerificationLoopConfig;
+  private verifier: RulesBasedVerification;
+  private status: LoopStatus = 'idle';
+  private attempt = 0;
+  private results: VerificationResult[] = [];
+  private lastError?: string;
+
+  constructor(config: VerificationLoopConfig) {
+    this.config = config;
+    this.verifier = new RulesBasedVerification(config.rules);
+  }
+
+  /**
+   * 执行验证循环
+   */
+  async run(
+    context: VerificationContext,
+    gather: GatherFn,
+    act?: ActFn,
+  ): Promise<LoopSnapshot> {
+    this.status = 'idle';
+    this.attempt = 0;
+    this.results = [];
+    this.lastError = undefined;
+
+    while (this.attempt < this.config.maxRetries) {
+      this.attempt++;
+
+      // Gather
+      this.status = 'gathering';
+      let gatherState: GatherState;
+      try {
+        gatherState = await gather(this.attempt);
+      } catch (error) {
+        this.lastError = `Gather 失败: ${error instanceof Error ? error.message : String(error)}`;
+        this.status = 'failed';
+        return this.snapshot();
+      }
+
+      // Act（可选）
+      if (act && this.attempt > 1) {
+        this.status = 'acting';
+        try {
+          const action = await act(gatherState, this.results);
+          if (action.type === 'abort') {
+            this.lastError = `Act 中止: ${action.description}`;
+            this.status = 'failed';
+            return this.snapshot();
+          }
+          if (action.type === 'skip') {
+            this.status = 'passed';
+            return this.snapshot();
+          }
+        } catch (error) {
+          this.lastError = `Act 失败: ${error instanceof Error ? error.message : String(error)}`;
+          this.status = 'failed';
+          return this.snapshot();
+        }
+      }
+
+      // Verify
+      this.status = 'verifying';
+      try {
+        this.results = await this.verifier.verifyAll(context);
+      } catch (error) {
+        this.lastError = `Verify 失败: ${error instanceof Error ? error.message : String(error)}`;
+        this.status = 'failed';
+        return this.snapshot();
+      }
+
+      const allPassed = this.results.every(r => r.passed);
+      if (allPassed) {
+        this.status = 'passed';
+        return this.snapshot();
+      }
+
+      // failFast: 首次失败立即停止
+      if (this.config.failFast) {
+        this.lastError = '验证失败 (failFast)';
+        this.status = 'failed';
+        return this.snapshot();
+      }
+    }
+
+    this.lastError = `达到最大重试次数 (${this.config.maxRetries})`;
+    this.status = 'failed';
+    return this.snapshot();
+  }
+
+  private snapshot(): LoopSnapshot {
+    return {
+      status: this.status,
+      attempt: this.attempt,
+      maxRetries: this.config.maxRetries,
+      results: this.results,
+      lastError: this.lastError,
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  getStatus(): LoopStatus {
+    return this.status;
+  }
+
+  getAttempt(): number {
+    return this.attempt;
+  }
+
+  getResults(): VerificationResult[] {
+    return [...this.results];
+  }
+}