@dommaker/harness 0.13.0 → 0.13.2

package/src/types/session.ts

@@ -0,0 +1,132 @@
+/**
+ * Session 相关类型定义
+ */
+
+/**
+ * Session Startup 检查点配置
+ */
+export interface StartupCheckpoints {
+  required: StartupCheckpointType[];
+  optional?: StartupCheckpointType[];
+  timeout?: number;          // 检查点超时（毫秒）
+  contextFiles?: string[];   // 启动时加载的上下文文件
+}
+
+export type StartupCheckpointType = 
+  | 'pwd'
+  | 'git_log'
+  | 'git_status'
+  | 'read_progress'
+  | 'read_task_list'
+  | 'init_sh'
+  | 'basic_verification'
+  | 'load_context';
+
+/**
+ * Startup 检查点结果
+ */
+export interface StartupCheckpointResult {
+  type: StartupCheckpointType;
+  success: boolean;
+  data?: any;
+  error?: string;
+  duration: number;  // 执行时长（毫秒）
+}
+
+/**
+ * Clean State 配置
+ */
+export interface CleanStateConfig {
+  enabled: boolean;
+  autoCommit?: boolean;       // 是否自动提交未提交的变更
+  detectBugs?: boolean;       // 是否检测 bug
+  updateProgress?: boolean;   // 是否更新 progress 文件
+  commitMessageTemplate?: string;  // 提交消息模板
+}
+
+/**
+ * Clean State 结果
+ */
+export interface CleanStateResult {
+  isClean: boolean;
+  hasUncommittedChanges: boolean;
+  committedFiles?: string[];
+  bugs?: DetectedBug[];
+  progressUpdated: boolean;
+  errors?: string[];
+}
+
+/**
+ * 检测到的 Bug
+ */
+export interface DetectedBug {
+  file: string;
+  line?: number;
+  message: string;
+  severity: 'low' | 'medium' | 'high' | 'critical';
+  type: 'syntax' | 'runtime' | 'logic' | 'security' | 'performance';
+}
+
+/**
+ * Task List JSON 格式（扩展自 tasks.yml）
+ */
+export interface TaskListJson {
+  tasks: DynamicTask[];
+  metadata?: {
+    created_at?: string;
+    updated_at?: string;
+    workflow_id?: string;
+    project_name?: string;
+  };
+}
+
+/**
+ * 动态任务定义
+ */
+export interface DynamicTask {
+  id: string;
+  name?: string;
+  category?: string;
+  description?: string;
+  type?: string;
+  priority?: number;
+  steps?: string[];
+  
+  // 约束机制字段
+  passes?: boolean;              // 任务是否通过（只能由测试结果修改）
+  test_result?: TaskTestResult;  // 测试证据
+  step_status?: Record<string, TaskStepStatus>;  // 步骤状态跟踪
+  current_step?: string;         // 当前执行的步骤
+  current_step_index?: number;   // 当前步骤索引
+}
+
+/**
+ * 测试结果
+ */
+export interface TaskTestResult {
+  passed: boolean;
+  command: string;
+  output?: string;
+  failures?: string[];
+  coverage?: number;
+  timestamp: Date;
+  evidence?: string;
+}
+
+/**
+ * 步骤状态
+ */
+export interface TaskStepStatus {
+  completed: boolean;
+  result?: string;
+  timestamp?: string;
+}
+
+/**
+ * Session 信息
+ */
+export interface SessionInfo {
+  sessionId: string;
+  workflowId: string;
+  task?: DynamicTask;
+}

package/src/types/spec.ts

@@ -0,0 +1,91 @@
+/**
+ * Spec 验证类型
+ * 
+ * 框架提供验证机制，项目定义自己的 Spec Schema
+ */
+
+/**
+ * Spec 类型
+ */
+export type SpecType = 'architecture' | 'module' | 'api' | 'custom';
+
+/**
+ * Spec 验证错误
+ */
+export interface SpecValidationError {
+  /** 错误路径 */
+  path: string;
+  /** 错误消息 */
+  message: string;
+  /** 严重程度 */
+  severity: 'error' | 'warning';
+}
+
+/**
+ * Spec 验证结果
+ */
+export interface SpecValidationResult {
+  /** 是否通过 */
+  valid: boolean;
+  /** 文件路径 */
+  file: string;
+  /** Spec 类型 */
+  type: SpecType;
+  /** 错误列表 */
+  errors: SpecValidationError[];
+  /** 警告列表 */
+  warnings: SpecValidationError[];
+  /** 指标（可选） */
+  metrics?: Record<string, number>;
+}
+
+/**
+ * Spec 验证配置
+ */
+export interface SpecValidatorConfig {
+  /** 是否启用 */
+  enabled: boolean;
+  /** Schema 路径（项目定义） */
+  schemaPath: string;
+  /** 要验证的文件模式 */
+  files: string[];
+  /** 验证失败的级别 */
+  failureLevel: 'error' | 'warning';
+}
+
+/**
+ * Schema 加载器函数类型
+ * 
+ * 项目可以自定义 Schema 加载逻辑
+ */
+export type SchemaLoader = (schemaPath: string) => Promise<SpecSchemaDefinition>;
+
+/**
+ * Schema 定义（通用接口）
+ * 
+ * 项目需要实现这个接口
+ */
+export interface SpecSchemaDefinition {
+  /** Schema 名称 */
+  name: string;
+  /** Schema 版本 */
+  version?: string;
+  /** 验证函数 */
+  validate: (content: string, filePath: string) => Promise<SpecValidationResult>;
+}
+
+/**
+ * 批量验证结果
+ */
+export interface BatchSpecValidationResult {
+  /** 总文件数 */
+  total: number;
+  /** 通过数 */
+  passed: number;
+  /** 失败数 */
+  failed: number;
+  /** 警告数 */
+  warnings: number;
+  /** 详细结果 */
+  results: SpecValidationResult[];
+}

package/src/types/trace.ts

@@ -0,0 +1,228 @@
+/**
+ * Execution Trace 类型定义
+ *
+ * 轻量设计：只记录核心信息，零 Token 成本
+ */
+
+/**
+ * 约束执行 Trace
+ *
+ * 设计原则：
+ * - 只记录核心字段（零 Token）
+ * - 不记录代码片段（需要时从 git diff 获取）
+ * - 不记录决策路径（需要时从 execution logs 获取）
+ */
+export interface ExecutionTrace {
+  // ========================================
+  // 核心字段（必须）
+  // ========================================
+
+  /** 约束 ID */
+  constraintId: string;
+
+  /** 约束层级 */
+  level: 'iron_law' | 'guideline' | 'tip';
+
+  /** 检查时间（Unix timestamp） */
+  timestamp: number;
+
+  /** 检查结果 */
+  result: 'pass' | 'fail' | 'bypassed';
+
+  // ========================================
+  // 轻量上下文（可选）
+  // ========================================
+
+  /** 操作类型（触发条件） */
+  operation?: string;
+
+  /** 严重性（从约束定义继承） */
+  severity?: 'error' | 'warning' | 'info';
+
+  /** 例外类型（如果适用了例外） */
+  exceptionApplied?: string;
+
+  /** 项目路径（用于区分多项目） */
+  projectPath?: string;
+
+  /** 会话 ID（用于追踪同一会话的多次检查） */
+  sessionId?: string;
+
+  // ========================================
+  // 用户响应（可选，用于诊断）
+  // ========================================
+
+  /** 用户如何响应失败 */
+  userAction?: 'bypass' | 'fix' | 'ignore' | 'request_help';
+
+  /** 用户绕过理由（如果用户绕过） */
+  bypassReason?: string;
+}
+
+/**
+ * Trace 统计汇总
+ *
+ * 纯计算结果，零 Token 成本
+ */
+export interface TraceSummary {
+  /** 约束 ID */
+  constraintId: string;
+
+  /** 约束层级 */
+  level: 'iron_law' | 'guideline' | 'tip';
+
+  /** 统计时间范围 */
+  timeRange: {
+    start: number;
+    end: number;
+  };
+
+  // ========================================
+  // 核心统计
+  // ========================================
+
+  /** 总检查次数 */
+  totalChecks: number;
+
+  /** 通过次数 */
+  passCount: number;
+
+  /** 失败次数 */
+  failCount: number;
+
+  /** 绕过次数 */
+  bypassCount: number;
+
+  /** 用户忽略次数 */
+  ignoreCount: number;
+
+  // ========================================
+  // 比率统计
+  // ========================================
+
+  /** 通过率 (0-1) */
+  passRate: number;
+
+  /** 失败率 (0-1) */
+  failRate: number;
+
+  /** 绕过率 (0-1) */
+  bypassRate: number;
+
+  // ========================================
+  // 趋势分析
+  // ========================================
+
+  /** 最近趋势 */
+  recentTrend: 'stable' | 'rising' | 'falling';
+
+  /** 对比上一周期的变化 */
+  changeFromLastPeriod?: {
+    passRateDelta: number;
+    failRateDelta: number;
+    bypassRateDelta: number;
+  };
+
+  // ========================================
+  // 例外统计
+  // ========================================
+
+  /** 例外应用次数 */
+  exceptionCount: number;
+
+  /** 最常见例外 */
+  mostCommonException?: string;
+}
+
+/**
+ * 异常检测结果
+ */
+export interface TraceAnomaly {
+  /** 异常类型 */
+  type:
+    | 'high_bypass_rate'      // 绕过率过高
+    | 'rising_fail_rate'      // 失败率上升
+    | 'rising_bypass_rate'    // 绕过率上升
+    | 'low_pass_rate'         // 通过率过低
+    | 'exception_overuse';    // 例外滥用
+
+  /** 约束 ID */
+  constraintId: string;
+
+  /** 约束层级 */
+  level: 'iron_law' | 'guideline' | 'tip';
+
+  /** 异常描述 */
+  message: string;
+
+  /** 相关数据 */
+  data: {
+    currentRate: number;
+    threshold: number;
+    trend?: 'rising' | 'falling' | 'stable';
+  };
+
+  /** 检测时间 */
+  detectedAt: number;
+
+  /** 建议的下一步 */
+  suggestedAction?: 'diagnose' | 'adjust_threshold' | 'add_exception' | 'notify_user';
+}
+
+/**
+ * Trace 过滤条件
+ */
+export interface TraceFilter {
+  /** 约束 ID（可选，不指定则查全部） */
+  constraintId?: string;
+
+  /** 约束层级（可选） */
+  level?: 'iron_law' | 'guideline' | 'tip';
+
+  /** 结果类型（可选） */
+  result?: 'pass' | 'fail' | 'bypassed';
+
+  /** 时间范围（可选） */
+  timeRange?: {
+    start: number;
+    end: number;
+  };
+
+  /** 项目路径（可选） */
+  projectPath?: string;
+
+  /** 会话 ID（可选） */
+  sessionId?: string;
+}
+
+/**
+ * Trace 收集器配置
+ */
+export interface TraceCollectorConfig {
+  /** Trace 文件路径 */
+  traceFile?: string;
+
+  /** 最大文件大小（字节），超出则滚动 */
+  maxFileSize?: number;
+
+  /** 是否启用（默认 true） */
+  enabled?: boolean;
+}
+
+/**
+ * 分析器配置
+ */
+export interface TraceAnalyzerConfig {
+  /** Summary 文件路径 */
+  summaryFile?: string;
+
+  /** 周期长度（毫秒），默认 1 小时 */
+  periodMs?: number;
+
+  /** 异常阈值 */
+  thresholds?: {
+    bypassRate?: number;     // 绕过率阈值，默认 0.3
+    failRate?: number;       // 失败率阈值，默认 0.5
+    exceptionRate?: number;  // 例外率阈值，默认 0.4
+  };
+}

package/src/utils/detect-source-roots.ts

@@ -0,0 +1,114 @@
+/**
+ * detectSourceRoots — 自动检测工程源码根目录
+ *
+ * 统一所有源码目录发现逻辑:
+ *   1. monorepo: packages/下各包的 src 或 lib 子目录
+ *   2. monorepo: apps/下各应用的 src/modules 子目录
+ *   3. 单 repo: src/ lib/ 目录
+ *
+ * 返回相对 projectPath 的路径数组。全都不存在时返回空数组。
+ */
+
+import { existsSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+
+export function detectSourceRoots(projectPath: string): string[] {
+  const roots: string[] = [];
+
+  // 1. monorepo: packages/*
+  const packagesDir = join(projectPath, 'packages');
+  if (existsSync(packagesDir)) {
+    try {
+      const entries = readdirSync(packagesDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name.startsWith('__')) continue;
+        const pkgDir = join(packagesDir, entry.name);
+        // 检查常见的源码子目录
+        let hasSubDir = false;
+        for (const sub of ['src', 'lib']) {
+          const subDir = join(pkgDir, sub);
+          if (existsSync(subDir) && hasSourceFiles(subDir)) {
+            roots.push(`packages/${entry.name}/${sub}`);
+            hasSubDir = true;
+          }
+        }
+        // 仅当无 src/lib 子目录时，包根目录才作为源码目录
+        if (!hasSubDir && hasSourceFiles(pkgDir)) {
+          roots.push(`packages/${entry.name}`);
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  // 2. monorepo: apps/*
+  const appsDir = join(projectPath, 'apps');
+  if (existsSync(appsDir)) {
+    try {
+      const entries = readdirSync(appsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name.startsWith('__')) continue;
+        const appDir = join(appsDir, entry.name);
+
+        // apps/api/src/modules/* 的子目录
+        const modulesDir = join(appDir, 'src', 'modules');
+        if (existsSync(modulesDir)) {
+          try {
+            const modEntries = readdirSync(modulesDir, { withFileTypes: true });
+            for (const mod of modEntries) {
+              if (!mod.isDirectory() || mod.name.startsWith('.') || mod.name.startsWith('__')) continue;
+              const modPath = join(modulesDir, mod.name);
+              if (hasSourceFiles(modPath)) {
+                roots.push(`apps/${entry.name}/src/modules/${mod.name}`);
+              }
+            }
+          } catch { /* skip */ }
+        }
+
+        // apps/xxx/src 本身
+        const appSrcDir = join(appDir, 'src');
+        if (existsSync(appSrcDir) && hasSourceFiles(appSrcDir)) {
+          // 避免重复（modules 已覆盖子目录）
+          if (!roots.some(r => r.startsWith(`apps/${entry.name}/src/`))) {
+            roots.push(`apps/${entry.name}/src`);
+          }
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  // 3. 单 repo: src/, lib/
+  for (const dir of ['src', 'lib']) {
+    const absDir = join(projectPath, dir);
+    if (existsSync(absDir) && hasSourceFiles(absDir)) {
+      roots.push(dir);
+    }
+  }
+
+  return roots;
+}
+
+/**
+ * 检查目录（递归）中是否包含 .ts 源文件（排除 __tests__, node_modules, dist）
+ */
+function hasSourceFiles(dir: string): boolean {
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const name = entry.name;
+      if (name.startsWith('.') || name === 'node_modules' || name === 'dist') continue;
+      if (name === '__tests__' || name === '__mocks__') continue;
+
+      const fullPath = join(dir, name);
+      if (entry.isFile()) {
+        if (name.endsWith('.ts') && !name.endsWith('.d.ts')) {
+          return true;
+        }
+      } else if (entry.isDirectory()) {
+        if (hasSourceFiles(fullPath)) return true;
+      }
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}

package/src/utils/exec.ts

@@ -0,0 +1,61 @@
+/**
+ * 通用工具模块
+ *
+ * 提供命令执行、数组规范化、延迟等公共函数，减少各子系统重复代码。
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+/**
+ * Promisified exec
+ */
+export const execAsync = promisify(exec);
+
+/**
+ * 执行命令并返回 stdout（忽略 stderr）
+ */
+export async function runCommand(command: string, cwd?: string): Promise<string> {
+  try {
+    const { stdout } = await execAsync(command, {
+      cwd,
+      maxBuffer: 1024 * 1024, // 1MB buffer
+    });
+    return stdout.trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * 检查命令是否可用
+ */
+export async function isCommandAvailable(command: string): Promise<boolean> {
+  try {
+    // 使用 execFile 避免命令注入（不通过 shell 解析）
+    const { execFile: execFileCb } = await import('child_process');
+    const execFileAsync = promisify(execFileCb);
+    await execFileAsync('which', [command]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 将单值或数组统一为数组（用于 trigger 等字段）
+ */
+export function normalizeTriggers<T>(
+  value: T | T[] | undefined,
+  fallback: T[] = []
+): T[] {
+  if (value === undefined || value === null) return fallback;
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * 异步延迟
+ */
+export function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/verification/CONTEXT.md

@@ -0,0 +1,23 @@
+# verification/
+
+## 职责
+验证引擎：基于规则的验证 + 循环验证(loop verification)。
+
+## 核心导出
+- `types.ts` — 验证类型定义
+- `rules-based.ts` — 基于规则的验证引擎
+- `loop.ts` — 循环验证引擎
+
+## 依赖关系
+- 依赖 `src/core/constraints/` 约束检查
+- 依赖 `src/core/validators/` 验证器
+- 被 CLI flow 命令消费
+
+## 约定
+- 验证规则可配置
+- loop 验证用于持续监控场景
+- 验证结果包含 pass/fail + 详细信息
+
+## 注意事项
+- 与 core/validators 配合使用
+- loop 验证适用于长期运行的 Agent 会话