@dommaker/harness 0.19.0 → 1.1.0

package/src/gates/__tests__/gate-interface.test.ts

@@ -0,0 +1,202 @@
+/**
+ * 6 门禁统一接口行为测试（G1）
+ *
+ * 每个门禁的 evaluate(ctx) 收敛到统一 Gate 接口：
+ * 执行细节私有，报告 GateResult → 三态 GateDecision（passed → abstain，失败 → deny），
+ * 决策浅冻结。契约门禁（contract）的测试在 contract.test.ts。
+ */
+
+import { exec } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { ReviewGate } from '../review';
+import { SecurityGate } from '../security';
+import { PerformanceGate } from '../performance';
+import { SpecAcceptanceGate } from '../acceptance';
+import { CommandGate } from '../command';
+
+// Mock exec（ReviewGate/SecurityGate 走 execAsync）
+jest.mock('child_process', () => ({
+  exec: jest.fn(),
+}));
+
+const mockExec = exec as unknown as jest.Mock;
+
+function callExec(cmd: string, _opts: unknown, callback: (err: unknown, res: { stdout: string }) => void): void {
+  callback(null, { stdout: cmd.includes('@{u}') ? '' : 'abc123 commit msg' });
+}
+
+describe('ReviewGate 统一接口', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('本地模式 requireApproval=true → deny（三态映射 + 冻结）', async () => {
+    mockExec.mockImplementation(callExec);
+    const decision = await new ReviewGate().evaluate({
+      projectId: 'p',
+      projectPath: '/test/project',
+    });
+    expect(decision.status).toBe('deny');
+    expect(decision.result.gate).toBe('review');
+    expect(decision.result.passed).toBe(false);
+    expect(Object.isFrozen(decision)).toBe(true);
+  });
+
+  it('本地模式 requireApproval=false → abstain', async () => {
+    mockExec.mockImplementation(callExec);
+    const decision = await new ReviewGate({ requireApproval: false }).evaluate({
+      projectId: 'p',
+      projectPath: '/test/project',
+    });
+    expect(decision.status).toBe('abstain');
+    expect(decision.result.passed).toBe(true);
+  });
+
+  it('id/order 字段齐备', () => {
+    const gate = new ReviewGate();
+    expect(gate.id).toBe('review');
+    expect(gate.order).toBe(0);
+  });
+});
+
+describe('SecurityGate 统一接口', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('npm audit 零漏洞 → abstain', async () => {
+    mockExec.mockImplementation((_cmd, _opts, callback) =>
+      callback(null, { stdout: JSON.stringify({ audit: { advisories: {} } }) })
+    );
+    const decision = await new SecurityGate().evaluate({
+      projectId: 'p',
+      projectPath: '/test/project',
+    });
+    expect(decision.status).toBe('abstain');
+    expect(decision.result.passed).toBe(true);
+  });
+
+  it('发现 critical 漏洞 → deny', async () => {
+    mockExec.mockImplementation((_cmd, _opts, callback) =>
+      callback(null, {
+        stdout: JSON.stringify({
+          audit: {
+            advisories: {
+              '1': { severity: 'critical', name: 'bad-lib', via: [{ title: 'RCE' }] },
+            },
+          },
+        }),
+      })
+    );
+    const decision = await new SecurityGate().evaluate({
+      projectId: 'p',
+      projectPath: '/test/project',
+    });
+    expect(decision.status).toBe('deny');
+    expect(decision.result.details?.critical).toBe(1);
+  });
+
+  it('id/order 字段齐备', () => {
+    const gate = new SecurityGate();
+    expect(gate.id).toBe('security');
+    expect(gate.order).toBe(0);
+  });
+});
+
+describe('PerformanceGate 统一接口', () => {
+  it('enabled=false → abstain（禁用即放行）', async () => {
+    const decision = await new PerformanceGate({ enabled: false }).evaluate({
+      projectId: 'p',
+      projectPath: '/test/project',
+    });
+    expect(decision.status).toBe('abstain');
+    expect(decision.result.passed).toBe(true);
+  });
+
+  it('id/order 字段齐备', () => {
+    const gate = new PerformanceGate();
+    expect(gate.id).toBe('performance');
+    expect(gate.order).toBe(0);
+  });
+});
+
+describe('SpecAcceptanceGate 统一接口', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-gate-acc-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('tasks.yml 不存在 → abstain（跳过）', async () => {
+    const decision = await new SpecAcceptanceGate().evaluate({
+      projectId: 'p',
+      projectPath: dir,
+      tasksPath: path.join(dir, 'no-such-tasks.yml'),
+    });
+    expect(decision.status).toBe('abstain');
+    expect(decision.result.passed).toBe(true);
+    expect(decision.result.gate).toBe('acceptance');
+  });
+
+  it('已完成任务验收标准未勾选 → deny', async () => {
+    const tasksPath = path.join(dir, 'tasks.yml');
+    fs.writeFileSync(
+      tasksPath,
+      [
+        'tasks:',
+        '  - id: TASK-001',
+        '    status: done',
+        '    acceptance_criteria:',
+        '      - id: AC-001',
+        '        description: Test',
+        '        type: manual',
+        '        required: true',
+        '        checked: false',
+      ].join('\n')
+    );
+    const decision = await new SpecAcceptanceGate().evaluate({
+      projectId: 'p',
+      projectPath: dir,
+      tasksPath,
+    });
+    expect(decision.status).toBe('deny');
+    expect(decision.result.passed).toBe(false);
+    expect(Object.isFrozen(decision)).toBe(true);
+  });
+
+  it('id/order 字段齐备', () => {
+    const gate = new SpecAcceptanceGate();
+    expect(gate.id).toBe('acceptance');
+    expect(gate.order).toBe(0);
+  });
+});
+
+describe('CommandGate 统一接口', () => {
+  it('黑名单命令 → deny', async () => {
+    const decision = await new CommandGate().evaluate({
+      projectId: 'p',
+      projectPath: '/test/project',
+      command: 'rm -rf /',
+    });
+    expect(decision.status).toBe('deny');
+    expect(decision.result.passed).toBe(false);
+  });
+
+  it('安全命令 → abstain', async () => {
+    const decision = await new CommandGate().evaluate({
+      projectId: 'p',
+      projectPath: '/test/project',
+      command: 'echo hello',
+    });
+    expect(decision.status).toBe('abstain');
+    expect(decision.result.passed).toBe(true);
+  });
+
+  it('id/order 字段齐备', () => {
+    const gate = new CommandGate();
+    expect(gate.id).toBe('command');
+    expect(gate.order).toBe(0);
+  });
+});

package/src/gates/__tests__/registry.test.ts

@@ -0,0 +1,87 @@
+/**
+ * 门禁注册表测试（G1 闭环）
+ */
+
+import { GATE_DEFINITIONS, type GateDefinition } from '../definitions';
+import {
+  getGate,
+  listRegisteredGates,
+  registeredGateCount,
+  assertGateRegistryClosed,
+} from '../registry';
+import { decisionFromResult } from '../decision';
+import type { Gate } from '../types';
+
+function fakeGate(id: string): Gate {
+  return {
+    id,
+    order: 0,
+    evaluate: async () =>
+      decisionFromResult({
+        gate: id,
+        passed: true,
+        message: 'ok',
+        timestamp: new Date().toISOString(),
+      }),
+  };
+}
+
+describe('gateRegistry', () => {
+  it('定义即注册：6 个门禁定义全部有实现', () => {
+    expect(registeredGateCount()).toBe(6);
+    for (const def of GATE_DEFINITIONS) {
+      const gate = getGate(def.id);
+      expect(gate).toBeDefined();
+      expect(gate.id).toBe(def.id);
+    }
+  });
+
+  it('注册实现携带定义表默认 order 与统一 evaluate', () => {
+    for (const def of GATE_DEFINITIONS) {
+      const gate = getGate(def.id);
+      expect(gate.order).toBe(def.order);
+      expect(typeof gate.evaluate).toBe('function');
+    }
+  });
+
+  it('listRegisteredGates 返回副本且按定义序', () => {
+    const gates = listRegisteredGates();
+    expect(gates.map(g => g.id)).toEqual(GATE_DEFINITIONS.map(d => d.id));
+    gates.pop();
+    expect(listRegisteredGates()).toHaveLength(6);
+  });
+
+  it('定义无实现 → 抛错（闭环失败方向 1）', () => {
+    const definitions: GateDefinition[] = [
+      { id: 'orphan-def', description: 'x', order: 0, cli: { command: 'x', description: 'x', options: [], action: { module: 'x', export: 'x' }, mapActionArgs: () => [] } },
+    ];
+    const implementations = [fakeGate('other')];
+    expect(() => assertGateRegistryClosed(definitions, implementations)).toThrow(
+      /门禁定义 "orphan-def" 未注册实现/
+    );
+  });
+
+  it('实现无定义 → 抛错（闭环失败方向 2）', () => {
+    const definitions: GateDefinition[] = [
+      { id: 'defined', description: 'x', order: 0, cli: { command: 'x', description: 'x', options: [], action: { module: 'x', export: 'x' }, mapActionArgs: () => [] } },
+    ];
+    const implementations = [fakeGate('defined'), fakeGate('undocumented-impl')];
+    expect(() => assertGateRegistryClosed(definitions, implementations)).toThrow(
+      /门禁实现 "undocumented-impl" 没有对应定义/
+    );
+  });
+
+  it('重复 id → 抛错', () => {
+    const definitions: GateDefinition[] = [
+      { id: 'dup', description: 'x', order: 0, cli: { command: 'x', description: 'x', options: [], action: { module: 'x', export: 'x' }, mapActionArgs: () => [] } },
+    ];
+    const implementations = [fakeGate('dup'), fakeGate('dup')];
+    expect(() => assertGateRegistryClosed(definitions, implementations)).toThrow(
+      /门禁 "dup" 重复注册/
+    );
+  });
+
+  it('引用未注册 → getGate 抛错（闭环）', () => {
+    expect(() => getGate('nonexistent')).toThrow(/门禁 "nonexistent" 未注册/);
+  });
+});

package/src/gates/__tests__/runner.test.ts

@@ -0,0 +1,81 @@
+/**
+ * 门禁执行器测试（G1：deny 单调 + ask fail-closed + order 排序）
+ */
+
+import { runGates } from '../runner';
+import { decisionFromResult } from '../decision';
+import type { Gate, GateContext, GateDecisionStatus } from '../types';
+
+function fakeGate(id: string, order: number, status: GateDecisionStatus): Gate {
+  return {
+    id,
+    order,
+    evaluate: async () =>
+      decisionFromResult(
+        {
+          gate: id,
+          passed: status !== 'deny',
+          message: id,
+          timestamp: new Date().toISOString(),
+        },
+        status
+      ),
+  };
+}
+
+const ctx: GateContext = { projectId: 'p', projectPath: '/tmp/project' };
+
+describe('runGates', () => {
+  it('deny 单调：先 deny 后 abstain，终态 deny（下游不得改回 allow）', async () => {
+    const result = await runGates(
+      [fakeGate('a', 0, 'deny'), fakeGate('b', 1, 'abstain')],
+      ctx
+    );
+    expect(result.status).toBe('deny');
+    expect(result.denied.map(d => d.result.gate)).toEqual(['a']);
+    expect(result.decisions.map(d => d.result.gate)).toEqual(['a', 'b']);
+  });
+
+  it('deny 单调：先 abstain 后 deny，终态 deny', async () => {
+    const result = await runGates(
+      [fakeGate('a', 0, 'abstain'), fakeGate('b', 1, 'deny')],
+      ctx
+    );
+    expect(result.status).toBe('deny');
+    expect(result.denied).toHaveLength(1);
+  });
+
+  it('全部 abstain → 终态 abstain', async () => {
+    const result = await runGates(
+      [fakeGate('a', 0, 'abstain'), fakeGate('b', 1, 'abstain')],
+      ctx
+    );
+    expect(result.status).toBe('abstain');
+    expect(result.denied).toHaveLength(0);
+    expect(result.asked).toHaveLength(0);
+  });
+
+  it('ask 枚举预留：无实现时 fail-closed = deny', async () => {
+    const result = await runGates([fakeGate('asker', 0, 'ask')], ctx);
+    expect(result.status).toBe('deny');
+    expect(result.asked).toHaveLength(1);
+    expect(result.asked[0].status).toBe('ask');
+    expect(result.denied).toHaveLength(0);
+  });
+
+  it('按声明式 order 升序执行（入参顺序无关）', async () => {
+    const result = await runGates(
+      [fakeGate('c', 3, 'abstain'), fakeGate('a', 1, 'abstain'), fakeGate('b', 2, 'abstain')],
+      ctx
+    );
+    expect(result.decisions.map(d => d.result.gate)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('决策浅冻结：调用方/下游改写决策抛错（单调语义接口契约）', async () => {
+    const result = await runGates([fakeGate('a', 0, 'deny')], ctx);
+    expect(Object.isFrozen(result.decisions[0])).toBe(true);
+    expect(() => {
+      (result.decisions[0] as { status: GateDecisionStatus }).status = 'abstain';
+    }).toThrow(TypeError);
+  });
+});

package/src/gates/acceptance.ts

@@ -21,6 +21,8 @@ import { execAsync } from '../utils/exec';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
+import type { Gate, GateContext, GateDecision } from './types';
+import { decisionFromResult } from './decision';
 
 
 // ==================== 类型定义 ====================
@@ -135,7 +137,9 @@ export interface E2ETestResult {
 /**
  * 验收标准门禁
  */
-export class SpecAcceptanceGate {
+export class SpecAcceptanceGate implements Gate {
+  readonly id = 'acceptance';
+  order = 0;
   private config: SpecAcceptanceGateConfig;
 
   constructor(config?: Partial<SpecAcceptanceGateConfig>) {
@@ -148,6 +152,25 @@ export class SpecAcceptanceGate {
     };
   }
 
+  /**
+   * 统一门禁接口（G1）：执行细节私有，决策三态由 check() 报告推导。
+   * AcceptanceGateResult 无 gate 字段，此处归一化为 GateResult 报告结构。
+   */
+  async evaluate(context: GateContext): Promise<GateDecision> {
+    const result = await this.check({
+      projectPath: context.projectPath,
+      taskId: context.taskId,
+      tasksPath: context.tasksPath,
+    });
+    return decisionFromResult({
+      gate: 'acceptance',
+      passed: result.passed,
+      message: result.message,
+      timestamp: result.timestamp,
+      details: result.details as Record<string, any>,
+    });
+  }
+
   /**
    * 检查验收标准
    */

package/src/gates/checker-gate.ts

@@ -0,0 +1,54 @@
+/**
+ * checker-as-guard 接线点（G1 / studio #129 随动）
+ *
+ * 把已注册的 ConstraintCheck 适配为统一 Gate，供守卫链（如 studio
+ * runCompletionGuards）复用 runGates 的 deny 单调 / ask fail-closed 语义。
+ *
+ * 证据语义：本接线点构造的 CheckEnv 不带 git staged diff / 源码扫描证据
+ * （stagedDiff 空、srcScan 空）——证据 flag 未接线的 checker 按契约返回
+ * 'skip'（不阻断，映射为 abstain）；纯上下文判断的 checker 照常判定。
+ * studio 侧若需 git 证据，在 #129 接线时扩展 CheckEnv 构造。
+ */
+
+import type { CheckEnv, ConstraintCheck } from '../core/constraints/checkers';
+import type { Gate, GateContext, GateDecision } from './types';
+import { decisionFromResult } from './decision';
+
+/**
+ * 将已注册 checker 适配为统一 Gate（checker-as-guard 接线点）
+ *
+ * 判定映射：false（违反）→ deny；true（满足）/ 'skip'（未评估）→ abstain。
+ *
+ * @param check 已注册的 ConstraintCheck（经 checkers 注册表取回）
+ * @param order 门禁顺序（供 guard 链排序）
+ */
+export function createCheckerGate(check: ConstraintCheck, order = 0): Gate {
+  return {
+    id: check.id,
+    order,
+    async evaluate(ctx: GateContext): Promise<GateDecision> {
+      const startTime = Date.now();
+      const projectPath = ctx.projectPath || process.cwd();
+      const env: CheckEnv = {
+        context: { operation: 'manual', projectPath },
+        projectPath,
+        stagedDiff: async () => '',
+        stagedDiffNames: async () => '',
+        srcScan: () => [],
+      };
+      const outcome = await check.evaluate(env);
+      return decisionFromResult({
+        gate: check.id,
+        passed: outcome !== false,
+        message:
+          outcome === false
+            ? `checker "${check.id}" 判定违规`
+            : outcome === 'skip'
+              ? `checker "${check.id}" 跳过（证据未接线）`
+              : `checker "${check.id}" 通过`,
+        timestamp: new Date().toISOString(),
+        duration: Date.now() - startTime,
+      });
+    },
+  };
+}

package/src/gates/command.ts

@@ -5,7 +5,8 @@
  * 检查命令是否安全，防止执行危险操作
  */
 
-import type { GateResult, CommandGateConfig, CommandBlacklistRule } from './types';
+import type { GateResult, CommandGateConfig, CommandBlacklistRule, Gate, GateContext, GateDecision } from './types';
+import { decisionFromResult } from './decision';
 
 /**
  * 黑名单级别
@@ -195,7 +196,9 @@ export const DEFAULT_COMMAND_BLACKLIST: CommandBlacklistRule[] = [
 /**
  * 命令门禁
  */
-export class CommandGate {
+export class CommandGate implements Gate {
+  readonly id = 'command';
+  order = 0;
   private config: Required<CommandGateConfig>;
   private blacklist: CommandBlacklistRule[];
 
@@ -214,6 +217,14 @@ export class CommandGate {
     ];
   }
 
+  /**
+   * 统一门禁接口（G1）：执行细节私有，决策三态由 check() 报告推导。
+   * 待检命令经 GateContext.command 传入。
+   */
+  async evaluate(context: GateContext): Promise<GateDecision> {
+    return decisionFromResult(await this.check(context.command ?? ''));
+  }
+
   /**
    * 检查命令
    */

package/src/gates/contract.ts

@@ -9,12 +9,15 @@
 
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import type { GateResult, GateContext, ContractGateConfig } from './types';
+import type { GateResult, GateContext, ContractGateConfig, Gate, GateDecision } from './types';
+import { decisionFromResult } from './decision';
 
 /**
  * 契约门禁
  */
-export class ContractGate {
+export class ContractGate implements Gate {
+  readonly id = 'contract';
+  order = 0;
   private config: Required<ContractGateConfig>;
 
   constructor(config: Partial<ContractGateConfig> = {}) {
@@ -26,6 +29,13 @@ export class ContractGate {
     };
   }
 
+  /**
+   * 统一门禁接口（G1）：执行细节私有，决策三态由 check() 报告推导
+   */
+  async evaluate(context: GateContext): Promise<GateDecision> {
+    return decisionFromResult(await this.check(context));
+  }
+
   /**
    * 检查契约
    */

package/src/gates/decision.ts

@@ -0,0 +1,27 @@
+/**
+ * 门禁决策构造（G1）
+ *
+ * GateResult（报告结构）→ GateDecision（三态决策）的映射点。
+ */
+
+import type { GateDecision, GateDecisionStatus, GateResult } from './types';
+
+/**
+ * 从报告结构构造决策。
+ *
+ * status 缺省由 `result.passed` 推导：true → 'abstain'（放行），
+ * false → 'deny'（阻断）。'ask' 只能显式指定（枚举预留，暂无实现）。
+ *
+ * 返回值浅冻结（Object.freeze）：决策不可变是 deny 单调语义的接口契约——
+ * 下游门禁不得改写上游决策，deny 不可被改回 allow。
+ */
+export function decisionFromResult(
+  result: GateResult,
+  status?: GateDecisionStatus
+): GateDecision {
+  const decision: GateDecision = {
+    status: status ?? (result.passed ? 'abstain' : 'deny'),
+    result: Object.freeze({ ...result }),
+  };
+  return Object.freeze(decision);
+}