@dommaker/harness 0.13.0 → 0.13.2

package/src/failure/constraint-handler.ts

@@ -0,0 +1,173 @@
+/**
+ * ConstraintViolationHandler — 约束违规统一处理（S4）
+ *
+ * 问题：ConstraintViolationError 在 4 个调用点有 4 种行为：
+ *   1. 抛异常阻断（checker.ts / interceptor.ts）
+ *   2. 返回 null（report.ts catch 后返回空数据）
+ *   3. 返回 403 HTTP 状态
+ *   4. console.warn 静默吞掉
+ *
+ * 解决：提供 3 种标准化处理策略，消除 ad-hoc catch 行为。
+ */
+
+import type { ConstraintCheckResult } from '../types/constraint';
+
+/**
+ * 违规处理策略
+ */
+export type ViolationStrategy = 'BLOCK' | 'COLLECT' | 'SAFE_BOOLEAN';
+
+/**
+ * 违规处理结果
+ */
+export interface ViolationHandlingResult {
+  /** 策略 */
+  strategy: ViolationStrategy;
+  /** 检查结果（COLLECT 策略时总是有值） */
+  checkResult?: ConstraintCheckResult;
+  /** 是否有违规（SAFE_BOOLEAN 策略时为 false） */
+  hasViolation: boolean;
+  /** 违规数量 */
+  violationCount: number;
+}
+
+/**
+ * 约束违规处理器
+ *
+ * 用法：
+ * ```typescript
+ * const handler = new ConstraintViolationHandler();
+ *
+ * // 策略 1: BLOCK — 抛异常阻断（Iron Laws 默认）
+ * await handler.execute(checkFn, 'BLOCK');
+ *
+ * // 策略 2: COLLECT — 收集违规不抛异常（用于报告生成）
+ * const result = await handler.execute(checkFn, 'COLLECT');
+ * // result.checkResult 总是有值
+ *
+ * // 策略 3: SAFE_BOOLEAN — 返回真/假（用于 canProceed 类方法）
+ * const ok = await handler.execute(checkFn, 'SAFE_BOOLEAN');
+ * // ok.hasViolation 为 true/false
+ * ```
+ */
+export class ConstraintViolationHandler {
+  /**
+   * 执行约束检查并统一处理结果
+   *
+   * @param checkFn 约束检查函数（可能抛出 ConstraintViolationError）
+   * @param strategy 处理策略
+   * @returns 标准化结果
+   */
+  async execute(
+    checkFn: () => Promise<ConstraintCheckResult>,
+    strategy: ViolationStrategy
+  ): Promise<ViolationHandlingResult> {
+    switch (strategy) {
+      case 'BLOCK':
+        return this.handleBlock(checkFn);
+      case 'COLLECT':
+        return this.handleCollect(checkFn);
+      case 'SAFE_BOOLEAN':
+        return this.handleSafeBoolean(checkFn);
+    }
+  }
+
+  /**
+   * BLOCK 策略：违规即抛出，无违规返回结果
+   */
+  private async handleBlock(
+    checkFn: () => Promise<ConstraintCheckResult>
+  ): Promise<ViolationHandlingResult> {
+    const result = await checkFn();
+    return {
+      strategy: 'BLOCK',
+      checkResult: result,
+      hasViolation: !result.passed,
+      violationCount: result.ironLaws.filter(r => !r.satisfied).length,
+    };
+  }
+
+  /**
+   * COLLECT 策略：捕获异常，收集所有违规，不抛出
+   */
+  private async handleCollect(
+    checkFn: () => Promise<ConstraintCheckResult>
+  ): Promise<ViolationHandlingResult> {
+    try {
+      const result = await checkFn();
+      const ironViolations = result.ironLaws.filter(r => !r.satisfied).length;
+      const guideViolations = result.warningCount;
+      return {
+        strategy: 'COLLECT',
+        checkResult: result,
+        hasViolation: !result.passed || guideViolations > 0,
+        violationCount: ironViolations + guideViolations,
+      };
+    } catch {
+      // 捕获 ConstraintViolationError，返回失败结果
+      const empty: ConstraintCheckResult = {
+        ironLaws: [],
+        guidelines: [],
+        tips: [],
+        passed: false,
+        warningCount: 0,
+        tipCount: 0,
+      };
+      return {
+        strategy: 'COLLECT',
+        checkResult: empty,
+        hasViolation: true,
+        violationCount: 1,
+      };
+    }
+  }
+
+  /**
+   * SAFE_BOOLEAN 策略：不抛异常，只返回 boolean
+   */
+  private async handleSafeBoolean(
+    checkFn: () => Promise<ConstraintCheckResult>
+  ): Promise<ViolationHandlingResult> {
+    try {
+      const result = await checkFn();
+      return {
+        strategy: 'SAFE_BOOLEAN',
+        hasViolation: !result.passed,
+        violationCount: result.ironLaws.filter(r => !r.satisfied).length,
+      };
+    } catch {
+      return {
+        strategy: 'SAFE_BOOLEAN',
+        hasViolation: true,
+        violationCount: 1,
+      };
+    }
+  }
+}
+
+/**
+ * 快捷：BLOCK 策略执行检查
+ */
+export async function executeWithBlock(
+  checkFn: () => Promise<ConstraintCheckResult>
+): Promise<ViolationHandlingResult> {
+  return new ConstraintViolationHandler().execute(checkFn, 'BLOCK');
+}
+
+/**
+ * 快捷：COLLECT 策略执行检查
+ */
+export async function executeWithCollect(
+  checkFn: () => Promise<ConstraintCheckResult>
+): Promise<ViolationHandlingResult> {
+  return new ConstraintViolationHandler().execute(checkFn, 'COLLECT');
+}
+
+/**
+ * 快捷：SAFE_BOOLEAN 策略执行检查
+ */
+export async function executeWithSafeBoolean(
+  checkFn: () => Promise<ConstraintCheckResult>
+): Promise<ViolationHandlingResult> {
+  return new ConstraintViolationHandler().execute(checkFn, 'SAFE_BOOLEAN');
+}

package/src/failure/index.ts

@@ -0,0 +1,35 @@
+/**
+ * 失败处理模块
+ *
+ * 提供通用的错误分类和记录能力
+ * 不包含业务逻辑
+ */
+
+// 类型
+export * from './types';
+
+// 分类器
+export {
+  ErrorClassifier,
+  createErrorClassifier,
+  classifyError,
+  getFailureLevel,
+  type ErrorClassifierConfig,
+} from './classifier';
+
+// 记录器
+export {
+  FailureRecorder,
+  createFailureRecorder,
+  type FailureRecorderConfig,
+} from './recorder';
+
+// 约束违规处理（S4：统一处理策略）
+export {
+  ConstraintViolationHandler,
+  executeWithBlock,
+  executeWithCollect,
+  executeWithSafeBoolean,
+  type ViolationStrategy,
+  type ViolationHandlingResult,
+} from './constraint-handler';

package/src/failure/recorder.ts

@@ -0,0 +1,201 @@
+/**
+ * 失败记录器
+ *
+ * 文件存储，追加写入，零 Token 成本
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { FailureRecord } from './types';
+
+/**
+ * 失败记录器配置
+ */
+export interface FailureRecorderConfig {
+  /** 日志文件路径 */
+  logFile: string;
+  /** 单文件最大大小（字节），默认 10MB */
+  maxFileSize?: number;
+  /** 保留历史文件数，默认 5 */
+  maxHistoryFiles?: number;
+}
+
+/**
+ * 失败记录器
+ *
+ * 用法：
+ * ```typescript
+ * const recorder = new FailureRecorder({ logFile: '.harness/logs/failures.log' });
+ * await recorder.record({
+ *   type: ErrorType.TEST_FAILED,
+ *   level: FailureLevel.L1,
+ *   message: 'Test failed',
+ *   timestamp: Date.now(),
+ * });
+ * ```
+ */
+export class FailureRecorder {
+  private logFile: string;
+  private maxFileSize: number;
+  private maxHistoryFiles: number;
+
+  constructor(config: FailureRecorderConfig) {
+    this.logFile = config.logFile;
+    this.maxFileSize = config.maxFileSize ?? 10 * 1024 * 1024; // 10MB
+    this.maxHistoryFiles = config.maxHistoryFiles ?? 5;
+
+    // 确保目录存在
+    const dir = path.dirname(this.logFile);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  /**
+   * 记录失败
+   */
+  async record(record: FailureRecord): Promise<void> {
+    // 检查文件大小，必要时滚动
+    await this.rotateIfNeeded();
+
+    // 追加写入（单行 JSON）
+    const line = JSON.stringify(record) + '\n';
+    fs.appendFileSync(this.logFile, line, 'utf-8');
+  }
+
+  /**
+   * 批量记录
+   */
+  async recordBatch(records: FailureRecord[]): Promise<void> {
+    for (const record of records) {
+      await this.record(record);
+    }
+  }
+
+  /**
+   * 获取历史记录
+   */
+  async getHistory(limit?: number): Promise<FailureRecord[]> {
+    if (!fs.existsSync(this.logFile)) {
+      return [];
+    }
+
+    const content = fs.readFileSync(this.logFile, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+
+    const records = lines.map((line) => JSON.parse(line) as FailureRecord);
+
+    if (limit && limit > 0) {
+      return records.slice(-limit);
+    }
+
+    return records;
+  }
+
+  /**
+   * 按类型获取记录
+   */
+  async getByType(type: string, limit?: number): Promise<FailureRecord[]> {
+    return this.getFiltered((r) => r.type === type, limit);
+  }
+
+  /**
+   * 按等级获取记录
+   */
+  async getByLevel(level: string, limit?: number): Promise<FailureRecord[]> {
+    return this.getFiltered((r) => r.level === level, limit);
+  }
+
+  /**
+   * 按条件过滤记录
+   */
+  private async getFiltered(
+    predicate: (r: FailureRecord) => boolean,
+    limit?: number
+  ): Promise<FailureRecord[]> {
+    const records = await this.getHistory();
+    const filtered = records.filter(predicate);
+    return limit && limit > 0 ? filtered.slice(-limit) : filtered;
+  }
+
+  /**
+   * 获取统计信息
+   */
+  async getStats(): Promise<{
+    total: number;
+    byType: Record<string, number>;
+    byLevel: Record<string, number>;
+  }> {
+    const records = await this.getHistory();
+
+    const byType: Record<string, number> = {};
+    const byLevel: Record<string, number> = {};
+
+    for (const record of records) {
+      byType[record.type] = (byType[record.type] ?? 0) + 1;
+      byLevel[record.level] = (byLevel[record.level] ?? 0) + 1;
+    }
+
+    return {
+      total: records.length,
+      byType,
+      byLevel,
+    };
+  }
+
+  /**
+   * 清空记录
+   */
+  async clear(): Promise<void> {
+    if (fs.existsSync(this.logFile)) {
+      fs.writeFileSync(this.logFile, '', 'utf-8');
+    }
+  }
+
+  /**
+   * 文件滚动
+   */
+  private async rotateIfNeeded(): Promise<void> {
+    if (!fs.existsSync(this.logFile)) {
+      return;
+    }
+
+    const stats = fs.statSync(this.logFile);
+    if (stats.size < this.maxFileSize) {
+      return;
+    }
+
+    // 滚动文件
+    const dir = path.dirname(this.logFile);
+    const ext = path.extname(this.logFile);
+    const base = path.basename(this.logFile, ext);
+
+    // 删除最旧的历史文件
+    const oldestHistory = path.join(dir, `${base}.${this.maxHistoryFiles}${ext}`);
+    if (fs.existsSync(oldestHistory)) {
+      fs.unlinkSync(oldestHistory);
+    }
+
+    // 重命名现有历史文件
+    for (let i = this.maxHistoryFiles - 1; i >= 1; i--) {
+      const oldFile = path.join(dir, `${base}.${i}${ext}`);
+      const newFile = path.join(dir, `${base}.${i + 1}${ext}`);
+      if (fs.existsSync(oldFile)) {
+        fs.renameSync(oldFile, newFile);
+      }
+    }
+
+    // 重命名当前文件
+    const firstHistory = path.join(dir, `${base}.1${ext}`);
+    fs.renameSync(this.logFile, firstHistory);
+  }
+}
+
+/**
+ * 创建失败记录器
+ */
+export function createFailureRecorder(
+  config: FailureRecorderConfig
+): FailureRecorder {
+  return new FailureRecorder(config);
+}

package/src/failure/types.ts

@@ -0,0 +1,165 @@
+/**
+ * 失败处理类型定义
+ *
+ * 提供通用的错误分类和失败记录类型
+ * 不包含业务逻辑，只定义数据结构
+ */
+
+/**
+ * 错误类型枚举
+ */
+export enum ErrorType {
+  TEST_FAILED = 'TEST_FAILED',
+  GATE_FAILED = 'GATE_FAILED',
+  DEPENDENCY_BLOCKED = 'DEPENDENCY_BLOCKED',
+  CONTEXT_OVERFLOW = 'CONTEXT_OVERFLOW',
+  TIMEOUT = 'TIMEOUT',
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  AGENT_ERROR = 'AGENT_ERROR',
+  TOOL_ERROR = 'TOOL_ERROR',
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  UNKNOWN = 'UNKNOWN',
+}
+
+/**
+ * 失败等级
+ *
+ * L1: 自动处理（重试、降级）
+ * L2: 需要干预（人工审核）
+ * L3: 严重问题（开会讨论）
+ * L4: 致命错误（回滚）
+ */
+export enum FailureLevel {
+  L1 = 'L1',
+  L2 = 'L2',
+  L3 = 'L3',
+  L4 = 'L4',
+}
+
+/**
+ * 错误分类规则
+ */
+export interface ErrorClassificationRule {
+  /** 匹配的错误类型 */
+  type: ErrorType;
+  /** 正则匹配模式 */
+  patterns?: RegExp[];
+  /** 关键词匹配（不区分大小写） */
+  keywords?: string[];
+  /** 失败等级 */
+  level?: FailureLevel;
+  /** 规则描述 */
+  description?: string;
+}
+
+/**
+ * 失败记录
+ */
+export interface FailureRecord {
+  /** 错误类型 */
+  type: ErrorType;
+  /** 失败等级 */
+  level: FailureLevel;
+  /** 错误消息 */
+  message: string;
+  /** 时间戳 */
+  timestamp: number;
+  /** 元数据 */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * 分类结果
+ */
+export interface ClassificationResult {
+  /** 错误类型 */
+  type: ErrorType;
+  /** 失败等级 */
+  level: FailureLevel;
+  /** 匹配的规则（如果有） */
+  matchedRule?: ErrorClassificationRule;
+  /** 原始错误 */
+  originalError: Error;
+}
+
+/**
+ * 默认错误分类规则
+ *
+ * 注意：规则按顺序匹配，更具体的规则应该放在前面
+ */
+export const DEFAULT_CLASSIFICATION_RULES: ErrorClassificationRule[] = [
+  // 更具体的规则优先
+  {
+    type: ErrorType.GATE_FAILED,
+    keywords: ['gate', 'checkpoint', 'constraint'],
+    level: FailureLevel.L2,
+    description: '门禁检查失败',
+  },
+  {
+    type: ErrorType.DEPENDENCY_BLOCKED,
+    keywords: ['dependency', 'blocked', 'dependency_fail'],
+    level: FailureLevel.L3,
+    description: '依赖阻塞',
+  },
+  {
+    type: ErrorType.CONTEXT_OVERFLOW,
+    keywords: ['context overflow', 'token limit', 'context exceed'],
+    level: FailureLevel.L2,
+    description: '上下文溢出',
+  },
+  {
+    type: ErrorType.TIMEOUT,
+    keywords: ['timeout', 'timed out', 'deadline'],
+    patterns: [/timeout/i, /timed?\s*out/i],
+    level: FailureLevel.L1,
+    description: '超时',
+  },
+  {
+    type: ErrorType.NETWORK_ERROR,
+    keywords: ['network', 'connection', 'econnrefused', 'enotfound', 'socket'],
+    level: FailureLevel.L1,
+    description: '网络错误',
+  },
+  {
+    type: ErrorType.AGENT_ERROR,
+    keywords: ['agent error', 'model error', 'rate limit', 'quota exceeded'],
+    level: FailureLevel.L2,
+    description: 'Agent 错误',
+  },
+  {
+    type: ErrorType.TOOL_ERROR,
+    keywords: ['tool error', 'skill error', 'executor error'],
+    level: FailureLevel.L1,
+    description: '工具错误',
+  },
+  {
+    type: ErrorType.VALIDATION_ERROR,
+    keywords: ['validation error', 'invalid', 'schema error'],
+    level: FailureLevel.L2,
+    description: '验证错误',
+  },
+  // 通用规则放在后面
+  {
+    type: ErrorType.TEST_FAILED,
+    keywords: ['test', 'assertion', 'expect'],
+    patterns: [/test.*fail/i, /assertion/i, /expect.*fail/i],
+    level: FailureLevel.L1,
+    description: '测试失败',
+  },
+];
+
+/**
+ * 错误类型到失败等级的默认映射
+ */
+export const DEFAULT_LEVEL_MAPPING: Record<ErrorType, FailureLevel> = {
+  [ErrorType.TEST_FAILED]: FailureLevel.L1,
+  [ErrorType.GATE_FAILED]: FailureLevel.L2,
+  [ErrorType.DEPENDENCY_BLOCKED]: FailureLevel.L3,
+  [ErrorType.CONTEXT_OVERFLOW]: FailureLevel.L2,
+  [ErrorType.TIMEOUT]: FailureLevel.L1,
+  [ErrorType.NETWORK_ERROR]: FailureLevel.L1,
+  [ErrorType.AGENT_ERROR]: FailureLevel.L2,
+  [ErrorType.TOOL_ERROR]: FailureLevel.L1,
+  [ErrorType.VALIDATION_ERROR]: FailureLevel.L2,
+  [ErrorType.UNKNOWN]: FailureLevel.L2,
+};

package/src/gates/CONTEXT.md

@@ -0,0 +1,27 @@
+# gates/
+
+## 职责
+质量门禁系统：6 种门禁检查（验收/命令/契约/性能/审查/安全）。
+
+## 核心导出
+- `ReviewGate` — 代码审查门禁
+- `SecurityGate` — 安全检查门禁
+- `PerformanceGate` — 性能门禁
+- `ContractGate` — 契约(OpenAPI)门禁
+- `SpecAcceptanceGate` — Spec 验收门禁
+- `CommandGate` — 命令黑名单门禁
+- `types.ts` — GateResult / GateContext 等公共类型
+- 便捷工厂函数：createReviewGate / createSecurityGate / createPerformanceGate / createContractGate / createSpecAcceptanceGate
+
+## 依赖关系
+- 依赖 `src/core/` 类型(GateResult)
+- 依赖 `src/types/` 公共类型
+
+## 约定
+- 所有门禁实现 GateResult 接口
+- 新门禁必须配 CLI 命令 + 测试文件
+- 工厂函数在 index.ts 中统一导出
+
+## 注意事项
+- 门禁系统不包含业务逻辑，只提供检查能力
+- CommandGate 为命令黑名单检查(SEC-006)