@dommaker/harness 0.13.0 → 0.13.2

package/src/types/passes-gate.ts

@@ -0,0 +1,185 @@
+/**
+ * 测试门控类型定义
+ */
+
+/**
+ * 测试门控配置
+ */
+export interface PassesGateConfig {
+  /** 是否启用 */
+  enabled?: boolean;
+  
+  /** 测试命令 */
+  testCommand?: string;
+  
+  /** 是否需要证据 */
+  requireEvidence?: boolean;
+  
+  /** 是否允许部分通过 */
+  allowPartialPass?: boolean;
+  
+  /** 最大重试次数 */
+  maxRetries?: number;
+  
+  /** 重试延迟（毫秒） */
+  retryDelay?: number;
+}
+
+/**
+ * 测试结果
+ */
+export interface TaskTestResult {
+  /** 是否通过 */
+  passed: boolean;
+  
+  /** 测试命令 */
+  command: string;
+  
+  /** 输出 */
+  output?: string;
+  
+  /** 错误 */
+  error?: string;
+  
+  /** 执行时间（毫秒） */
+  duration?: number;
+  
+  /** 时间戳 */
+  timestamp?: Date;
+  
+  /** 失败的测试列表 */
+  failures?: string[];
+  
+  /** 覆盖率 */
+  coverage?: number;
+  
+  /** 证据路径 */
+  evidence?: string;
+}
+
+/**
+ * 测试门控结果
+ */
+export interface PassesGateResult {
+  /** 任务 ID */
+  taskId: string;
+  
+  /** 是否允许设置 */
+  allowed: boolean;
+  
+  /** 测试结果 */
+  testResult?: TaskTestResult;
+  
+  /** 尝试次数 */
+  attempts: number;
+  
+  /** 错误信息 */
+  error?: string;
+}
+
+/**
+ * 动态任务（用于 passes-gate）
+ */
+export interface DynamicTask {
+  /** 任务 ID */
+  id: string;
+  
+  /** 任务名称 */
+  name?: string;
+  
+  /** 是否通过 */
+  passes?: boolean;
+  
+  /** 测试结果 */
+  testResult?: TaskTestResult;
+}
+
+/**
+ * PassesGate 扩展接口
+ * 
+ * 用于注册额外的测试类型（如 Puppeteer E2E）
+ */
+export interface PassesGateExtension {
+  /** 扩展名称 */
+  name: string;
+  
+  /** 扩展描述 */
+  description?: string;
+  
+  /** 运行测试 */
+  run(workDir: string, task?: DynamicTask): Promise<TaskTestResult>;
+}
+
+/**
+ * 扩展测试结果（包含类型标识）
+ */
+export interface ExtensionTestResult extends TaskTestResult {
+  /** 测试类型（扩展名称） */
+  type?: string;
+}
+
+// ========================================
+// AS-006: 纯约束验证接口
+// ========================================
+
+/**
+ * 测试结果输入（用于 check() 方法）
+ * 
+ * 业务层运行测试后传入，harness 只验证结果
+ */
+export interface TestResult {
+  /** 是否通过（必填） */
+  passed: boolean;
+
+  /** 测试命令（可选，用于记录） */
+  command?: string;
+
+  /** 覆盖率（可选） */
+  coverage?: number;
+
+  /** 证据路径（可选） */
+  evidence?: string;
+
+  /** 失败列表（可选） */
+  failures?: string[];
+
+  /** 测试输出（可选） */
+  output?: string;
+
+  /** 错误信息（可选） */
+  error?: string;
+
+  /** 执行时间（可选） */
+  duration?: number;
+}
+
+/**
+ * PassesGate 验证违规
+ */
+export interface PassesGateViolation {
+  /** Iron Law ID */
+  id: string;
+
+  /** Iron Law 规则 */
+  rule: string;
+
+  /** 中文消息 */
+  message: string;
+
+  /** 约束层级 */
+  level: 'iron_law';
+}
+
+/**
+ * PassesGate check() 结果
+ */
+export interface PassesGateCheckResult {
+  /** 是否允许标记完成 */
+  allowed: boolean;
+
+  /** Iron Law 违规列表 */
+  violations?: PassesGateViolation[];
+
+  /** 原始测试结果 */
+  testResult?: TestResult;
+}

package/src/types/performance.ts

@@ -0,0 +1,295 @@
+/**
+ * Performance Trace 类型定义
+ *
+ * 轻量设计：只记录核心信息，零 Token 成本
+ *
+ * 与 ExecutionTrace 的区别：
+ * - ExecutionTrace: 记录约束检查结果（业务行为）
+ * - PerformanceTrace: 记录操作耗时（性能指标）
+ */
+
+/**
+ * 性能追踪记录
+ *
+ * 设计原则：
+ * - 只记录核心字段（零 Token）
+ * - 文件存储，追加写入
+ * - 支持多种操作类型
+ */
+export interface PerformanceTrace {
+  // ========================================
+  // 核心字段（必须）
+  // ========================================
+
+  /** 操作类型 */
+  operation: string;
+
+  /** 时间戳（Unix timestamp） */
+  timestamp: number;
+
+  /** 耗时（毫秒） */
+  duration: number;
+
+  /** 结果 */
+  result: 'ok' | 'exceeded' | 'error';
+
+  // ========================================
+  // 上下文（可选）
+  // ========================================
+
+  /** 阈值（毫秒），用于计算是否超阈值 */
+  threshold?: number;
+
+  /** 项目路径（用于区分多项目） */
+  projectPath?: string;
+
+  /** 会话 ID（用于追踪同一会话的多次操作） */
+  sessionId?: string;
+
+  /** 任务 ID */
+  taskId?: string;
+
+  /** 角色ID（用于角色相关操作） */
+  roleId?: string;
+
+  /** 额外元数据 */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * 性能统计汇总
+ */
+export interface PerformanceSummary {
+  /** 操作类型 */
+  operation: string;
+
+  /** 统计时间范围 */
+  timeRange: {
+    start: number;
+    end: number;
+  };
+
+  // ========================================
+  // 核心统计
+  // ========================================
+
+  /** 总执行次数 */
+  totalCalls: number;
+
+  /** 成功次数 */
+  okCount: number;
+
+  /** 超阈值次数 */
+  exceededCount: number;
+
+  /** 错误次数 */
+  errorCount: number;
+
+  // ========================================
+  // 耗时统计
+  // ========================================
+
+  /** 平均耗时（毫秒） */
+  avgDuration: number;
+
+  /** 最大耗时 */
+  maxDuration: number;
+
+  /** 最小耗时 */
+  minDuration: number;
+
+  /** P95 耗时 */
+  p95Duration: number;
+
+  /** P99 耗时 */
+  p99Duration: number;
+
+  // ========================================
+  // 比率统计
+  // ========================================
+
+  /** 成功率 (0-1) */
+  okRate: number;
+
+  /** 超阈值率 (0-1) */
+  exceededRate: number;
+
+  /** 错误率 (0-1) */
+  errorRate: number;
+
+  // ========================================
+  // 趋势分析
+  // ========================================
+
+  /** 最近趋势 */
+  recentTrend: 'stable' | 'rising' | 'falling';
+
+  /** 对比上一周期的变化 */
+  changeFromLastPeriod?: {
+    avgDurationDelta: number;
+    exceededRateDelta: number;
+  };
+}
+
+/**
+ * 性能异常
+ */
+export interface PerformanceAnomaly {
+  /** 异常类型 */
+  type:
+    | 'high_avg_duration'      // 平均耗时过高
+    | 'rising_duration'        // 耗时趋势上升
+    | 'high_exceeded_rate'     // 超阈值率过高
+    | 'rising_exceeded_rate'   // 超阈值率上升
+    | 'high_error_rate';       // 错误率过高
+
+  /** 操作类型 */
+  operation: string;
+
+  /** 异常描述 */
+  message: string;
+
+  /** 相关数据 */
+  data: {
+    currentValue: number;
+    threshold: number;
+    trend?: 'rising' | 'falling' | 'stable';
+  };
+
+  /** 检测时间 */
+  detectedAt: number;
+
+  /** 建议的下一步 */
+  suggestedAction?: 'optimize' | 'adjust_threshold' | 'notify_user';
+}
+
+/**
+ * 性能追踪过滤条件
+ */
+export interface PerformanceTraceFilter {
+  /** 操作类型（可选） */
+  operation?: string;
+
+  /** 结果类型（可选） */
+  result?: 'ok' | 'exceeded' | 'error';
+
+  /** 时间范围（可选） */
+  timeRange?: {
+    start: number;
+    end: number;
+  };
+
+  /** 项目路径（可选） */
+  projectPath?: string;
+
+  /** 会话 ID（可选） */
+  sessionId?: string;
+
+  /** 任务 ID（可选） */
+  taskId?: string;
+
+  /** 角色 ID（可选） */
+  roleId?: string;
+}
+
+/**
+ * PerformanceCollector 配置
+ */
+export interface PerformanceCollectorConfig {
+  /** 日志文件路径，默认 .harness/logs/performance.log */
+  logFile?: string;
+
+  /** 最大文件大小（字节），超出则滚动，默认 10MB */
+  maxFileSize?: number;
+
+  /** 是否启用（默认 true） */
+  enabled?: boolean;
+}
+
+/**
+ * PerformanceAnalyzer 配置
+ */
+export interface PerformanceAnalyzerConfig {
+  /** Summary 文件路径 */
+  summaryFile?: string;
+
+  /** 周期长度（毫秒），默认 1 小时 */
+  periodMs?: number;
+
+  /** 异常阈值 */
+  thresholds?: {
+    /** 平均耗时阈值（毫秒），超过则告警 */
+    avgDuration?: number;
+    /** 超阈值率阈值，默认 0.3 */
+    exceededRate?: number;
+    /** 错误率阈值，默认 0.1 */
+    errorRate?: number;
+  };
+}
+
+/**
+ * Token 使用记录
+ */
+export interface TokenUsageRecord {
+  /** 时间戳 */
+  timestamp: number;
+
+  /** 会话/会议 ID */
+  sessionId: string;
+
+  /** 任务 ID（可选） */
+  taskId?: string;
+
+  /** 角色 ID（可选） */
+  roleId?: string;
+
+  /** 上下文 Token 数 */
+  contextTokens: number;
+
+  /** 执行 Token 数 */
+  executionTokens: number;
+
+  /** 总 Token 数 */
+  totalTokens: number;
+
+  /** 预算 */
+  budget: number;
+
+  /** 是否超预算 */
+  exceeded: boolean;
+
+  /** 项目路径 */
+  projectPath?: string;
+}
+
+/**
+ * Token 使用统计
+ */
+export interface TokenUsageSummary {
+  /** 会话 ID */
+  sessionId: string;
+
+  /** 时间范围 */
+  timeRange: {
+    start: number;
+    end: number;
+  };
+
+  /** 总 Token 使用 */
+  totalTokens: number;
+
+  /** 平均每次 Token 使用 */
+  avgTokensPerCall: number;
+
+  /** 超预算次数 */
+  exceededCount: number;
+
+  /** 超预算率 */
+  exceededRate: number;
+
+  /** 按任务统计 */
+  byTask?: Map<string, number>;
+
+  /** 按角色统计 */
+  byRole?: Map<string, number>;
+}

package/src/types/project-config.ts

@@ -0,0 +1,251 @@
+/**
+ * 项目级自定义约束配置
+ *
+ * 允许项目定义自己的约束，扩展或覆盖 harness 内置约束
+ */
+
+import type { Constraint, ConstraintLevel } from './constraint';
+
+/**
+ * 自定义约束定义
+ */
+export interface CustomConstraintDefinition {
+  /** 约束 ID */
+  id: string;
+
+  /** 约束层级（扩展例外时可省略，自动使用内置约束层级） */
+  level?: ConstraintLevel;
+
+  /** 约束规则（扩展例外时可省略） */
+  rule?: string;
+
+  /** 约束消息（扩展例外时可省略） */
+  message?: string;
+
+  /** 触发条件（扩展例外时可省略） */
+  trigger?: string | string[];
+
+  /** 例外条件（可选，完全覆盖内置例外） */
+  exceptions?: string[];
+
+  /** 扩展例外（可选，追加到内置例外） */
+  extend_exceptions?: string[];
+
+  /** 描述（可选） */
+  description?: string;
+
+  /** 是否启用（可选，默认 true） */
+  enabled?: boolean;
+}
+
+/**
+ * 文档同步配置
+ */
+export interface DocsSyncConfig {
+  /** 同步命令（默认: harness sync-docs） */
+  sync_command?: string;
+  /** CI 中是否检查文档新鲜度 */
+  check_on_ci?: boolean;
+  /** 需要同步的文件列表 */
+  files?: string[];
+}
+
+/**
+ * CONTEXT.md 配置
+ */
+export interface ContextFilesConfig {
+  /** 是否启用 CONTEXT.md 检查 */
+  enabled?: boolean;
+  /** 必须包含 CONTEXT.md 的目录列表 */
+  required_dirs?: string[];
+}
+
+/**
+ * CHANGELOG 配置
+ */
+export interface ChangelogConfig {
+  /** 格式 */
+  format?: 'keep-a-changelog' | 'conventional';
+}
+
+/**
+ * 文档新鲜度配置
+ *
+ * 配置驱动的文档新鲜度检查。每个检查类型是纯文件系统操作，零 LLM 调用。
+ */
+export interface DocFreshnessConfig {
+  /** 是否启用文档新鲜度检查 */
+  enabled?: boolean;
+  /** 检查列表 */
+  checks?: DocFreshnessCheck[];
+}
+
+export type DocFreshnessCheck =
+  | ChangelogVersionCheck
+  | ContextDocsCheck
+  | DocDirCheck
+  | DocRegexCountCheck;
+
+/** CHANGELOG 版本 vs package.json 版本一致性 */
+export interface ChangelogVersionCheck {
+  type: 'changelog_version';
+  /** CHANGELOG 文件路径（默认: CHANGELOG.md） */
+  changelog?: string;
+  /** package.json 路径（默认: package.json） */
+  package_json?: string;
+}
+
+/** 关键目录是否有 CONTEXT.md */
+export interface ContextDocsCheck {
+  type: 'context_docs';
+  /** 需要检查的目录列表（默认: governance.context_files.required_dirs） */
+  dirs?: string[];
+  /** 文档名称（默认: CONTEXT.md） */
+  doc_name?: string;
+}
+
+/** 文档中的目录表 vs 实际目录双向检查 */
+export interface DocDirCheck {
+  type: 'doc_dir_check';
+  /** 文档文件路径 */
+  doc: string;
+  /** 章节标题（如 "Key Subsystems"） */
+  section: string;
+  /** 目录提取正则（默认: `([^`]+)`，匹配反引号内的目录路径） */
+  dir_pattern?: string;
+  /** 反向检查时要跳过的目录 */
+  exclude?: string[];
+  /** 跳过反向检查（fs→doc），仅做 doc→fs */
+  skip_reverse_check?: boolean;
+}
+
+/** 文档中正则计数 vs 文件系统实际计数 */
+export interface DocRegexCountCheck {
+  type: 'doc_regex_count';
+  /** 文档文件路径 */
+  doc: string;
+  /** 人类可读标签（错误消息用） */
+  label: string;
+  /** 正则模式，需包含 (\d+) 捕获组 */
+  pattern: string;
+  /** 实际计数的获取方式 */
+  actual: DirCountActual | GrepCountActual | ConstCountActual;
+}
+
+/** 通过扫描目录获取实际计数 */
+export interface DirCountActual {
+  kind: 'dir_count';
+  /** 目录路径 */
+  path: string;
+  /** 文件扩展名过滤（如 ".ts"） */
+  extension?: string;
+  /** 排除的文件/目录名 */
+  exclude?: string[];
+}
+
+/** 通过 grep 匹配获取实际计数 */
+export interface GrepCountActual {
+  kind: 'grep_count';
+  /** glob 模式匹配文件 */
+  glob: string;
+  /** 在每个匹配文件中计数的正则 */
+  pattern: string;
+}
+
+/** 通过常量值获取实际计数（用于内存中的对象计数，如约束数量） */
+export interface ConstCountActual {
+  kind: 'const_count';
+  value: number;
+}
+
+/**
+ * 测试治理配置
+ */
+export interface TestingGovernanceConfig {
+  /** 新代码必须有测试（Guideline 提醒） */
+  test_first?: boolean;
+  /** 覆盖率阈值 */
+  coverage_threshold?: number;
+  /** 增量覆盖率检查（只检查新增代码） */
+  incremental_coverage?: boolean;
+}
+
+/**
+ * 治理配置
+ */
+export interface GovernanceConfig {
+  /** 治理级别 */
+  level?: 'minimal' | 'standard' | 'strict';
+
+  /** 文档同步 */
+  docs?: DocsSyncConfig;
+
+  /** CONTEXT.md 配置 */
+  context_files?: ContextFilesConfig;
+
+  /** CHANGELOG 配置 */
+  changelog?: ChangelogConfig;
+
+  /** 文档新鲜度检查配置 */
+  doc_freshness?: DocFreshnessConfig;
+
+  /** 测试治理 */
+  testing?: TestingGovernanceConfig;
+}
+
+/**
+ * 项目配置
+ */
+export interface ProjectConfig {
+  /** harness 版本 */
+  harness?: {
+    version?: string;
+  };
+
+  /** 使用预设 */
+  preset?: 'strict' | 'standard' | 'relaxed';
+
+  /** 治理配置 */
+  governance?: GovernanceConfig;
+
+  /** 内置约束启用/禁用配置 */
+  constraints?: Record<string, { enabled?: boolean }>;
+
+  /** 自定义约束文件路径 */
+  custom_constraints_file?: string;
+
+  /** 自定义约束（直接定义） */
+  custom_constraints?: Record<string, CustomConstraintDefinition>;
+
+  /** Spec 验证配置 */
+  spec?: {
+    /** 是否启用 Spec 验证 */
+    enabled?: boolean;
+    /** Schema 路径（项目定义） */
+    schemaPath?: string;
+    /** 要验证的文件模式 */
+    files?: string[];
+    /** 验证失败的级别 */
+    failureLevel?: 'error' | 'warning';
+  };
+}
+
+/**
+ * 完整的约束配置（合并内置 + 自定义）
+ */
+export interface MergedConstraintsConfig {
+  /** Iron Laws（合并后） */
+  ironLaws: Record<string, Constraint>;
+
+  /** Guidelines（合并后） */
+  guidelines: Record<string, Constraint>;
+
+  /** Tips（合并后） */
+  tips: Record<string, Constraint>;
+
+  /** 禁用的约束 ID */
+  disabled: string[];
+
+  /** 自定义约束 ID */
+  custom: string[];
+}