@dommaker/harness 0.19.0 → 1.0.0

package/src/gates/definitions.ts

@@ -0,0 +1,207 @@
+/**
+ * 门禁定义表（G1：定义即注册的单一定义源）
+ *
+ * - 每个门禁在此声明 id / description / 默认 order / CLI 元数据；
+ *   registry.ts 按此表做「定义↔实现」双向闭环校验（复制 checker 闭环模式）。
+ * - CLI 元数据被 bin/harness.js 消费，注册表驱动生成 6 个门禁命令：
+ *   命令名/别名/选项/子命令路由与历史手工块完全兼容；实现引用为
+ *   module+export（CommandImplRef），bin 按需 per-command 懒加载（H5/O2）。
+ * - 本模块禁止 import 任何门禁/命令实现（仅 type import，运行时零依赖）——
+ *   bin 启动期只加载本纯数据模块（保持 --help/--version 懒加载，
+ *   闭环校验在 registry 加载期执行）。
+ */
+
+import type { CommandImplRef } from '../cli/commands/definitions';
+
+/**
+ * 门禁 CLI 选项元数据（直接映射 commander `.option()`）
+ */
+export interface GateCliOption {
+  /** commander option flags，如 '-p, --project-path <path>' */
+  flags: string;
+  /** 选项描述 */
+  description: string;
+  /** commander 缺省值；negated option（如 --no-strict）不设，由 commander 默认 true */
+  defaultValue?: string | boolean;
+}
+
+/**
+ * 门禁 CLI 命令元数据（bin/harness.js 注册表驱动生成）
+ */
+export interface GateCliDefinition {
+  /** 命令名（历史命令名兼容保留） */
+  command: string;
+  /** 命令别名 */
+  alias?: string;
+  /** 位置参数声明，如 '[subcommand]' / '[cmd]' */
+  argument?: string;
+  /** 命令描述 */
+  description: string;
+  /** 命令选项 */
+  options: GateCliOption[];
+  /** 子命令名 → 命令实现引用（module+export）；命中后按 [options] 透传 */
+  subcommands?: Record<string, CommandImplRef>;
+  /** 默认 action 命令实现引用（module+export） */
+  action: CommandImplRef;
+  /** 默认 action 实参构造：arg = 位置参数（无位置参数时为 undefined），options = commander 选项对象 */
+  mapActionArgs: (arg: string | undefined, options: Record<string, unknown>) => unknown[];
+}
+
+/**
+ * 门禁定义
+ */
+export interface GateDefinition {
+  /** 门禁 id（与实现 Gate.id 一致） */
+  id: string;
+  /** 一句话描述 */
+  description: string;
+  /** 默认顺序（config.yml `gates.order` 可覆盖），小者先执行 */
+  order: number;
+  /** CLI 元数据（bin/harness.js 注册表驱动生成） */
+  cli: GateCliDefinition;
+}
+
+/**
+ * 6 门禁定义（默认 order 按字母序，与历史 bin 块顺序一致）
+ */
+export const GATE_DEFINITIONS: GateDefinition[] = [
+  {
+    id: 'acceptance',
+    description: '验收标准门控，检查任务是否满足验收标准',
+    order: 0,
+    cli: {
+      command: 'acceptance',
+      alias: 'acc',
+      argument: '[subcommand]',
+      description: '验收标准门控，检查任务是否满足验收标准',
+      options: [
+        { flags: '-t, --task-id <id>', description: '任务 ID' },
+        { flags: '--tasks-path <path>', description: 'tasks.yml 路径' },
+        { flags: '-p, --project-path <path>', description: '项目路径' },
+        { flags: '--check-all', description: '检查所有任务', defaultValue: false },
+        { flags: '--run-e2e', description: '运行 E2E 测试', defaultValue: false },
+      ],
+      subcommands: { list: { module: 'acceptance', export: 'listAcceptanceCriteria' } },
+      action: { module: 'acceptance', export: 'acceptance' },
+      mapActionArgs: (_arg, options) => [options],
+    },
+  },
+  {
+    id: 'command',
+    description: '命令黑名单门控，检查命令是否在禁用列表',
+    order: 1,
+    cli: {
+      command: 'command',
+      alias: 'cmd',
+      argument: '[cmd]',
+      description: '检查命令是否在黑名单中',
+      options: [
+        { flags: '-l, --level', description: '显示风险等级' },
+        { flags: '--list', description: '列出所有黑名单规则' },
+        { flags: '--json', description: 'JSON 格式输出' },
+        { flags: '--strict', description: '严格模式（warn 也阻止）' },
+      ],
+      action: { module: 'command', export: 'executeCommand' },
+      mapActionArgs: (arg, options) => [arg, options],
+    },
+  },
+  {
+    id: 'contract',
+    description: 'API 契约门控，检查 OpenAPI Schema',
+    order: 2,
+    cli: {
+      command: 'contract',
+      argument: '[subcommand]',
+      description: 'API 契约门控，检查 OpenAPI Schema',
+      options: [
+        { flags: '-p, --project-path <path>', description: '项目路径' },
+        { flags: '--contract-path <path>', description: '契约文件路径', defaultValue: 'openapi.yaml' },
+        { flags: '--no-strict', description: '关闭严格模式' },
+        { flags: '--allow-breaking', description: '允许破坏性变更', defaultValue: false },
+      ],
+      subcommands: { validate: { module: 'contract', export: 'validateSchema' } },
+      action: { module: 'contract', export: 'contract' },
+      mapActionArgs: (_arg, options) => [options],
+    },
+  },
+  {
+    id: 'performance',
+    description: '性能门控，检查性能指标',
+    order: 3,
+    cli: {
+      command: 'performance',
+      alias: 'perf',
+      description: '性能门控，检查性能指标',
+      options: [
+        { flags: '-p, --project-path <path>', description: '项目路径' },
+        { flags: '--coverage', description: '检查测试覆盖率', defaultValue: false },
+        { flags: '--coverage-threshold <n>', description: '覆盖率阈值', defaultValue: '80' },
+        { flags: '--bundle', description: '检查打包大小', defaultValue: false },
+        { flags: '--bundle-threshold <n>', description: '打包大小阈值 (KB)', defaultValue: '500' },
+        { flags: '--benchmark', description: '运行基准测试', defaultValue: false },
+        { flags: '--benchmark-timeout <n>', description: '基准测试超时（秒）', defaultValue: '60' },
+      ],
+      action: { module: 'performance', export: 'performance' },
+      mapActionArgs: (_arg, options) => [
+        {
+          projectPath: options.projectPath,
+          coverage: options.coverage,
+          coverageThreshold: parseInt(String(options.coverageThreshold), 10),
+          bundle: options.bundle,
+          bundleThreshold: parseInt(String(options.bundleThreshold), 10),
+          benchmark: options.benchmark,
+          benchmarkTimeout: parseInt(String(options.benchmarkTimeout), 10),
+        },
+      ],
+    },
+  },
+  {
+    id: 'review',
+    description: '代码审查门控，检查审查状态',
+    order: 4,
+    cli: {
+      command: 'review',
+      argument: '[subcommand]',
+      description: '代码审查门控，检查审查状态',
+      options: [
+        { flags: '-p, --project-path <path>', description: '项目路径' },
+        { flags: '--min-reviewers <n>', description: '最少审查人数', defaultValue: '1' },
+        { flags: '--no-require-approval', description: '不要求审批' },
+        { flags: '--no-block-on-changes', description: '不阻止变更请求' },
+        { flags: '--allowed-reviewers <list>', description: '允许的审查者（逗号分隔）' },
+      ],
+      subcommands: { status: { module: 'review', export: 'reviewStatus' } },
+      action: { module: 'review', export: 'review' },
+      mapActionArgs: (_arg, options) => [
+        {
+          projectPath: options.projectPath,
+          minReviewers: parseInt(String(options.minReviewers), 10),
+          requireApproval: options.requireApproval,
+          blockOnChangesRequested: options.blockOnChanges,
+          allowedReviewers: options.allowedReviewers,
+        },
+      ],
+    },
+  },
+  {
+    id: 'security',
+    description: '安全门控，检查安全漏洞',
+    order: 5,
+    cli: {
+      command: 'security',
+      alias: 'sec',
+      argument: '[subcommand]',
+      description: '安全门控，检查安全漏洞',
+      options: [
+        { flags: '-p, --project-path <path>', description: '项目路径' },
+        { flags: '--severity <level>', description: '严重性阈值 (low/moderate/high/critical)', defaultValue: 'high' },
+        { flags: '--ignore-warnings', description: '忽略警告', defaultValue: false },
+        { flags: '--ignore-dev-deps', description: '忽略开发依赖', defaultValue: false },
+        { flags: '--scan-command <cmd>', description: '自定义扫描命令' },
+      ],
+      subcommands: { audit: { module: 'security', export: 'auditDetails' } },
+      action: { module: 'security', export: 'security' },
+      mapActionArgs: (_arg, options) => [options],
+    },
+  },
+];

package/src/gates/effective-gates.ts

@@ -0,0 +1,106 @@
+/**
+ * 生效门禁集（G1）：对齐 getEffectiveConstraints 的 config 裁剪模式
+ *
+ * 单一来源：注册表（默认 order）→ config.yml `gates.order` 声明式重排 →
+ * `gates.<id>.enabled:false` 裁剪移除。
+ *
+ * 闭环：config.yml gates 配置引用了未注册的门禁 id → 抛错
+ * （与注册表「引用未注册」同款闭环；gates 配置段为新增面，
+ * 不存在历史残留配置，故不需静默忽略）。
+ */
+
+import type { Gate } from './types';
+import { listRegisteredGates } from './registry';
+import { loadRawProjectConfig } from '../core/project-config-loader';
+
+/**
+ * config.yml `gates` 段
+ */
+export interface GatesConfig {
+  /** 声明式顺序（门禁 id 列表）；未列出的按默认顺序排后 */
+  order?: string[];
+  /** 每个门禁的启用开关（gates.<id>.enabled: false = 裁剪） */
+  [gateId: string]: { enabled?: boolean } | string[] | undefined;
+}
+
+/**
+ * 获取项目当前生效的门禁集（按 order 升序）
+ *
+ * @param projectRoot 项目根路径（缺省 process.cwd()）
+ * @throws config.yml gates 段引用未注册门禁 id 时抛错
+ */
+export function getEffectiveGates(projectRoot: string = process.cwd()): Gate[] {
+  const raw = loadRawProjectConfig(projectRoot);
+  const config = raw?.gates as GatesConfig | undefined;
+  const gates = listRegisteredGates();
+  const known = new Set(gates.map(g => g.id));
+
+  if (!config) {
+    return sortByOrder(gates);
+  }
+
+  // ========================================
+  // 闭环校验：引用未注册 → 抛错
+  // ========================================
+  const orderIds = Array.isArray(config.order) ? (config.order as string[]) : undefined;
+  if (orderIds) {
+    const seen = new Set<string>();
+    for (const id of orderIds) {
+      if (!known.has(id)) {
+        throw new Error(
+          `[harness] config.yml gates.order 引用了未注册的门禁 "${id}"。` +
+          `可用门禁: ${[...known].join(', ')}。`
+        );
+      }
+      if (seen.has(id)) {
+        throw new Error(
+          `[harness] config.yml gates.order 中门禁 "${id}" 重复。`
+        );
+      }
+      seen.add(id);
+    }
+  }
+  for (const key of Object.keys(config)) {
+    if (key === 'order') continue;
+    if (!known.has(key)) {
+      throw new Error(
+        `[harness] config.yml gates.${key} 引用了未注册的门禁。` +
+        `可用门禁: ${[...known].join(', ')}。`
+      );
+    }
+  }
+
+  // ========================================
+  // enabled 裁剪（与 getEffectiveConstraints 的 enabled:false 删除同效）
+  // ========================================
+  const disabled = new Set<string>();
+  for (const gate of gates) {
+    const entry = config[gate.id];
+    if (
+      entry &&
+      typeof entry === 'object' &&
+      !Array.isArray(entry) &&
+      entry.enabled === false
+    ) {
+      disabled.add(gate.id);
+    }
+  }
+  const effective = gates.filter(g => !disabled.has(g.id));
+
+  // ========================================
+  // order 重排：列出的按列表顺序，未列出的按默认顺序排后
+  // ========================================
+  if (orderIds) {
+    const position = new Map(orderIds.map((id, i) => [id, i]));
+    return effective.sort((a, b) => {
+      const pa = position.has(a.id) ? position.get(a.id)! : orderIds.length + a.order;
+      const pb = position.has(b.id) ? position.get(b.id)! : orderIds.length + b.order;
+      return pa - pb;
+    });
+  }
+  return sortByOrder(effective);
+}
+
+function sortByOrder(gates: Gate[]): Gate[] {
+  return gates.sort((a, b) => a.order - b.order);
+}

package/src/gates/index.ts

@@ -8,6 +8,9 @@
 export type {
   GateResult,
   GateContext,
+  Gate,
+  GateDecision,
+  GateDecisionStatus,
   PerformanceThresholds,
   ReviewGateConfig,
   SecurityGateConfig,
@@ -20,6 +23,41 @@ export type {
   CommandGateConfig,
 } from './types';
 
+// ========================================
+// 统一门禁协议（G1）
+// ========================================
+
+/**
+ * 门禁决策构造：GateResult 报告 → 三态 GateDecision（浅冻结）
+ */
+export { decisionFromResult } from './decision';
+
+/**
+ * 门禁定义表（定义即注册的单一定义源；bin/harness.js 注册表驱动生成 CLI）
+ */
+export { GATE_DEFINITIONS, type GateDefinition, type GateCliDefinition, type GateCliOption } from './definitions';
+
+/**
+ * 门禁注册表（定义↔实现双向闭环，加载期抛错）+ getGate 引用闭环
+ */
+export { getGate, listRegisteredGates, registeredGateCount, assertGateRegistryClosed } from './registry';
+
+/**
+ * 门禁执行器：deny 单调 + ask fail-closed
+ */
+export { runGates, type GateRunResult } from './runner';
+
+/**
+ * 生效门禁集：config.yml gates.order / gates.<id>.enabled 声明式裁剪
+ */
+export { getEffectiveGates, type GatesConfig } from './effective-gates';
+
+/**
+ * checker-as-guard 接线点：ConstraintCheck → Gate（studio #129 随动）
+ */
+export { createCheckerGate } from './checker-gate';
+
+
 // 门禁类导出
 export { ReviewGate } from './review';
 export { SecurityGate } from './security';

package/src/gates/performance.ts

@@ -16,7 +16,8 @@
 import { execAsync } from '../utils/exec';
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import type { GateResult, GateContext, PerformanceGateConfig, PerformanceThresholds } from './types';
+import type { GateResult, GateContext, PerformanceGateConfig, PerformanceThresholds, Gate, GateDecision } from './types';
+import { decisionFromResult } from './decision';
 
 // 默认超时时间（毫秒）
 const DEFAULT_TIMEOUTS = {
@@ -38,7 +39,9 @@ export interface ExtendedPerformanceGateConfig extends PerformanceGateConfig {
 /**
  * 性能门禁
  */
-export class PerformanceGate {
+export class PerformanceGate implements Gate {
+  readonly id = 'performance';
+  order = 0;
   private config: Required<ExtendedPerformanceGateConfig>;
 
   constructor(config: Partial<ExtendedPerformanceGateConfig> = {}) {
@@ -53,6 +56,13 @@ export class PerformanceGate {
     };
   }
 
+  /**
+   * 统一门禁接口（G1）：执行细节私有，决策三态由 check() 报告推导
+   */
+  async evaluate(context: GateContext): Promise<GateDecision> {
+    return decisionFromResult(await this.check(context));
+  }
+
   /**
    * 检查性能
    */

package/src/gates/registry.ts

@@ -0,0 +1,107 @@
+/**
+ * 门禁注册表（G1：复制 checker 的「定义即注册 + 构建期闭环」模式）
+ *
+ * 模块加载期双向校验（任一不满足即抛错，拒绝静默缺失）：
+ * - 定义无实现 → 抛错（definitions.ts 有定义但 registry 未注册实现）
+ * - 实现无定义 → 抛错（registry 注册了实现但 definitions.ts 无定义）
+ * - 重复 id → 抛错
+ *
+ * 引用未注册（getGate / config.yml gates 配置引用）同样抛错——
+ * 与 checker 注册表闭环同款故障类「定义了但没登记」由机制消灭。
+ */
+
+import type { Gate } from './types';
+import { GATE_DEFINITIONS, type GateDefinition } from './definitions';
+import { ReviewGate } from './review';
+import { SecurityGate } from './security';
+import { PerformanceGate } from './performance';
+import { ContractGate } from './contract';
+import { SpecAcceptanceGate } from './acceptance';
+import { CommandGate } from './command';
+
+const IMPLEMENTATIONS: Gate[] = [
+  new SpecAcceptanceGate(),
+  new CommandGate(),
+  new ContractGate(),
+  new PerformanceGate(),
+  new ReviewGate(),
+  new SecurityGate(),
+];
+
+// ========================================
+// 注册表闭环校验（加载期）
+// ========================================
+
+assertGateRegistryClosed(GATE_DEFINITIONS, IMPLEMENTATIONS);
+
+// 默认 order 以定义表为准（config.yml gates.order 在生效集层覆盖，不改注册表单例）
+for (const def of GATE_DEFINITIONS) {
+  IMPLEMENTATIONS.find(g => g.id === def.id)!.order = def.order;
+}
+
+const registry = new Map<string, Gate>(IMPLEMENTATIONS.map(g => [g.id, g]));
+
+/**
+ * 注册表闭环双向校验（加载期调用；测试用坏输入验证两个失败方向）
+ *
+ * @throws 定义无实现 / 实现无定义 / 重复 id 时抛错
+ */
+export function assertGateRegistryClosed(
+  definitions: readonly GateDefinition[],
+  implementations: readonly Gate[]
+): void {
+  const implIds = new Map<string, Gate>();
+  for (const impl of implementations) {
+    if (implIds.has(impl.id)) {
+      throw new Error(
+        `[harness] 门禁注册表闭环校验失败：门禁 "${impl.id}" 重复注册。`
+      );
+    }
+    implIds.set(impl.id, impl);
+  }
+
+  for (const def of definitions) {
+    if (!implIds.has(def.id)) {
+      throw new Error(
+        `[harness] 门禁注册表闭环校验失败：门禁定义 "${def.id}" 未注册实现。` +
+        `请在 src/gates/ 中实现并注册，或删除该定义。`
+      );
+    }
+  }
+
+  for (const impl of implementations) {
+    if (!definitions.some(d => d.id === impl.id)) {
+      throw new Error(
+        `[harness] 门禁注册表闭环校验失败：门禁实现 "${impl.id}" 没有对应定义。` +
+        `请在 src/gates/definitions.ts 中补齐定义，或移除该实现。`
+      );
+    }
+  }
+}
+
+/**
+ * 按 id 查找已注册门禁实现；未注册抛错（闭环，拒绝静默缺失）
+ */
+export function getGate(id: string): Gate {
+  const gate = registry.get(id);
+  if (!gate) {
+    throw new Error(
+      `[harness] 门禁 "${id}" 未注册（注册表闭环）。可用门禁: ${[...registry.keys()].join(', ')}。`
+    );
+  }
+  return gate;
+}
+
+/**
+ * 全部已注册门禁（返回副本，调用方可安全排序/过滤）
+ */
+export function listRegisteredGates(): Gate[] {
+  return [...registry.values()];
+}
+
+/**
+ * 已注册门禁数量（诊断/测试用）
+ */
+export function registeredGateCount(): number {
+  return registry.size;
+}

package/src/gates/review.ts

@@ -8,12 +8,15 @@
  */
 
 import { execAsync } from '../utils/exec';
-import type { GateResult, GateContext, ReviewGateConfig } from './types';
+import type { GateResult, GateContext, ReviewGateConfig, Gate, GateDecision } from './types';
+import { decisionFromResult } from './decision';
 
 /**
  * 审查门禁
  */
-export class ReviewGate {
+export class ReviewGate implements Gate {
+  readonly id = 'review';
+  order = 0;
   private config: Required<ReviewGateConfig>;
 
   constructor(config: Partial<ReviewGateConfig> = {}) {
@@ -25,6 +28,13 @@ export class ReviewGate {
     };
   }
 
+  /**
+   * 统一门禁接口（G1）：执行细节私有，决策三态由 check() 报告推导
+   */
+  async evaluate(context: GateContext): Promise<GateDecision> {
+    return decisionFromResult(await this.check(context));
+  }
+
   /**
    * 检查审查状态
    */

package/src/gates/runner.ts

@@ -0,0 +1,57 @@
+/**
+ * 门禁执行器（G1）
+ *
+ * 按声明式 order 依次 evaluate，聚合语义：
+ * - deny 单调：deny 一旦出现即不可被下游 abstain 改回 allow（接口契约）
+ * - ask fail-closed：ask 枚举预留、无实现 → 聚合按 deny 计
+ * - 决策对象浅冻结：下游不得改写上游决策
+ */
+
+import type { Gate, GateContext, GateDecision } from './types';
+
+/**
+ * 一次门禁链执行的聚合结果
+ */
+export interface GateRunResult {
+  /** 聚合状态：任一 deny（或 ask fail-closed）→ 'deny'；否则 'abstain' */
+  status: 'deny' | 'abstain';
+  /** 按执行顺序的全部决策（浅冻结） */
+  decisions: GateDecision[];
+  /** 显式 deny 的决策（单调不可逆） */
+  denied: GateDecision[];
+  /** ask 决策（fail-closed 已计入聚合 deny，此处单独列出供报告） */
+  asked: GateDecision[];
+}
+
+/**
+ * 依次执行门禁链（按 order 升序，稳定排序）
+ *
+ * @param gates 参与执行的门禁（通常来自 getEffectiveGates）
+ * @param ctx 门禁上下文
+ */
+export async function runGates(
+  gates: readonly Gate[],
+  ctx: GateContext
+): Promise<GateRunResult> {
+  const ordered = [...gates].sort((a, b) => a.order - b.order);
+  const decisions: GateDecision[] = [];
+  const denied: GateDecision[] = [];
+  const asked: GateDecision[] = [];
+
+  for (const gate of ordered) {
+    const decision = Object.freeze(await gate.evaluate(ctx));
+    decisions.push(decision);
+    if (decision.status === 'deny') {
+      denied.push(decision);
+    } else if (decision.status === 'ask') {
+      asked.push(decision);
+    }
+  }
+
+  // 单调语义：deny 一旦出现，后续 abstain 不得改回 allow；
+  // ask 无实现 → fail-closed = deny。
+  const status: GateRunResult['status'] =
+    denied.length > 0 || asked.length > 0 ? 'deny' : 'abstain';
+
+  return { status, decisions, denied, asked };
+}

package/src/gates/security.ts

@@ -8,12 +8,15 @@
  */
 
 import { execAsync } from '../utils/exec';
-import type { GateResult, GateContext, SecurityGateConfig } from './types';
+import type { GateResult, GateContext, SecurityGateConfig, Gate, GateDecision } from './types';
+import { decisionFromResult } from './decision';
 
 /**
  * 安全门禁
  */
-export class SecurityGate {
+export class SecurityGate implements Gate {
+  readonly id = 'security';
+  order = 0;
   private config: Required<SecurityGateConfig>;
 
   constructor(config: Partial<SecurityGateConfig> = {}) {
@@ -26,6 +29,13 @@ export class SecurityGate {
     };
   }
 
+  /**
+   * 统一门禁接口（G1）：执行细节私有，决策三态由 scan() 报告推导
+   */
+  async evaluate(context: GateContext): Promise<GateDecision> {
+    return decisionFromResult(await this.scan(context));
+  }
+
   /**
    * 扫描安全漏洞
    */