@dommaker/harness 0.13.0 → 0.13.2

package/src/cli/commands/spec.ts

@@ -0,0 +1,158 @@
+/**
+ * harness spec validate 命令
+ * 
+ * 验证 Spec 文件格式
+ * 
+ * 设计原则：
+ * - 框架不包含具体 Schema 定义
+ * - 项目需要定义自己的 Spec Schema
+ * - 支持动态加载项目的 Schema
+ */
+
+import chalk from 'chalk';
+import * as path from 'path';
+import { SpecValidator, validateAllSpecs } from '../../core/spec/validator';
+import type { BatchSpecValidationResult, SpecValidationResult } from '../../types/spec';
+
+export interface SpecValidateOptions {
+  /** Schema 路径（项目定义） */
+  schema?: string;
+  /** 只验证暂存文件 */
+  staged?: boolean;
+  /** 验证指定文件 */
+  file?: string;
+  /** 项目路径 */
+  projectPath?: string;
+  /** 详细输出 */
+  verbose?: boolean;
+}
+
+/**
+ * 执行 Spec 验证
+ */
+export async function specValidate(options: SpecValidateOptions): Promise<void> {
+  console.log(chalk.blue('📋 验证 Spec 文件...'));
+
+  const projectPath = options.projectPath || process.cwd();
+  const validator = SpecValidator.getInstance();
+
+  // 设置 Schema 路径
+  if (options.schema) {
+    const absoluteSchemaPath = path.resolve(projectPath, options.schema);
+    validator.setConfig({ schemaPath: absoluteSchemaPath });
+    console.log(chalk.gray(`Schema 路径: ${absoluteSchemaPath}`));
+  }
+
+  let result: BatchSpecValidationResult | SpecValidationResult;
+
+  // 单文件验证
+  if (options.file) {
+    const absoluteFilePath = path.resolve(projectPath, options.file);
+    console.log(chalk.gray(`验证文件: ${absoluteFilePath}`));
+    result = await validator.validateFile(absoluteFilePath);
+    printSingleResult(result, options.verbose);
+    return;
+  }
+
+  // 批量验证
+  console.log(chalk.gray(`项目路径: ${projectPath}`));
+  console.log(chalk.gray(`仅暂存: ${options.staged ? '是' : '否'}`));
+  console.log();
+
+  result = await validateAllSpecs(projectPath, options.staged);
+
+  // 打印结果
+  printBatchResult(result, options.verbose);
+
+  // 根据失败级别决定退出码
+  if (!options.staged && result.failed > 0) {
+    process.exitCode = 1;
+  }
+}
+
+/**
+ * 打印单个文件验证结果
+ */
+function printSingleResult(result: SpecValidationResult, verbose?: boolean): void {
+  if (result.valid) {
+    console.log(chalk.green(`✅ ${result.file} 验证通过`));
+  } else {
+    console.log(chalk.red(`❌ ${result.file} 验证失败`));
+  }
+
+  if (result.errors.length > 0) {
+    console.log();
+    console.log(chalk.red('错误:'));
+    for (const error of result.errors) {
+      console.log(chalk.red(`  - ${error.path ? error.path + ': ' : ''}${error.message}`));
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    console.log();
+    console.log(chalk.yellow('警告:'));
+    for (const warning of result.warnings) {
+      console.log(chalk.yellow(`  - ${warning.path ? warning.path + ': ' : ''}${warning.message}`));
+    }
+  }
+
+  if (verbose && result.metrics) {
+    console.log();
+    console.log(chalk.gray('指标:'));
+    for (const [key, value] of Object.entries(result.metrics)) {
+      console.log(chalk.gray(`  - ${key}: ${value}`));
+    }
+  }
+}
+
+/**
+ * 打印批量验证结果
+ */
+function printBatchResult(result: BatchSpecValidationResult, verbose?: boolean): void {
+  // 汇总
+  console.log(chalk.bold('验证结果:'));
+  console.log(chalk.gray(`  总文件数: ${result.total}`));
+  console.log(chalk.green(`  通过: ${result.passed}`));
+  console.log(chalk.red(`  失败: ${result.failed}`));
+  console.log(chalk.yellow(`  警告: ${result.warnings}`));
+  console.log();
+
+  // 详细结果
+  if (verbose || result.failed > 0) {
+    for (const r of result.results) {
+      if (!r.valid || verbose) {
+        printSingleResult(r, verbose);
+        console.log();
+      }
+    }
+  }
+
+  // 成功提示
+  if (result.failed === 0 && result.total > 0) {
+    console.log(chalk.green('✅ 所有 Spec 文件验证通过'));
+  } else if (result.total === 0) {
+    console.log(chalk.gray('没有找到 Spec 文件，跳过验证'));
+    console.log();
+    console.log(chalk.gray('提示: Spec 文件包括:'));
+    console.log(chalk.gray('  - ARCHITECTURE.md'));
+    console.log(chalk.gray('  - specs/ 目录下的 .yml/.yaml 文件'));
+    console.log();
+    console.log(chalk.gray('要定义自己的 Schema，请在项目中创建:'));
+    console.log(chalk.gray('  src/specs/schemas/index.ts'));
+    console.log(chalk.gray('  导出 validate 函数'));
+  }
+}
+
+/**
+ * 列出支持的 Spec 类型
+ */
+export function listSpecTypes(): void {
+  console.log(chalk.blue('📋 支持的 Spec 类型:'));
+  console.log();
+  console.log('  architecture  - ARCHITECTURE.md 架构文档');
+  console.log('  module        - 模块定义（specs/modules/*.yml）');
+  console.log('  api           - API 定义（specs/apis/*.yml）');
+  console.log('  custom        - 自定义 Spec');
+  console.log();
+  console.log(chalk.gray('提示: 项目可以定义自己的 Schema 进行验证'));
+}

package/src/cli/commands/status.ts

@@ -0,0 +1,169 @@
+/**
+ * harness status 命令
+ *
+ * 显示 Harness 状态、统计、异常检测 + 智能建议
+ */
+
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+import { TraceCollector } from '../../monitoring/traces';
+import { TraceAnalyzer } from '../../monitoring/trace-analyzer';
+import type { TraceSummary, TraceAnomaly } from '../../types/trace';
+
+export interface StatusOptions {
+  /** 项目路径 */
+  projectPath?: string;
+  /** 详细模式 */
+  detail?: boolean;
+  /** 只显示异常 */
+  anomalies?: boolean;
+  /** 时间范围（小时） */
+  hours?: number;
+}
+
+/**
+ * 显示 Harness 状态
+ */
+export async function status(options: StatusOptions): Promise<void> {
+  const projectPath = options.projectPath || process.cwd();
+  const harnessDir = path.join(projectPath, '.harness');
+  const tracesPath = path.join(harnessDir, 'traces', 'execution.log');
+  const statePath = path.join(harnessDir, '.state.json');
+
+  console.log(chalk.blue('📊 Harness 状态'));
+  console.log();
+
+  // 检查是否初始化
+  if (!fs.existsSync(harnessDir)) {
+    console.log(chalk.yellow('⚠️  未初始化'));
+    console.log(chalk.gray('💡 运行 harness init 初始化项目'));
+    return;
+  }
+
+  // 检查 trace 文件
+  if (!fs.existsSync(tracesPath)) {
+    console.log(chalk.yellow('⚠️  暂无 Trace 记录'));
+    console.log(chalk.gray('💡 运行 harness check 开始记录'));
+    return;
+  }
+
+  // 读取 trace 文件
+  const tracesContent = fs.readFileSync(tracesPath, 'utf-8');
+  const lines = tracesContent.trim().split('\n').filter(Boolean);
+  const traceCount = lines.length;
+
+  // 解析 traces
+  const traces = lines.map(line => {
+    try {
+      return JSON.parse(line);
+    } catch {
+      return null;
+    }
+  }).filter(Boolean);
+
+  // 创建收集器和分析器
+  const collector = new TraceCollector({ traceFile: tracesPath });
+  const analyzer = new TraceAnalyzer(collector);
+
+  // 生成统计
+  const summaries = analyzer.summarize(traces);
+  const anomalies = analyzer.detectAnomalies(summaries);
+
+  // 基本统计
+  console.log(chalk.gray(`记录数: ${traceCount} 条`));
+  console.log();
+
+  if (options.anomalies) {
+    // 只显示异常
+    if (anomalies.length === 0) {
+      console.log(chalk.green('✅ 未发现异常'));
+    } else {
+      console.log(chalk.yellow(`⚠️  发现 ${anomalies.length} 个异常:`));
+      console.log();
+      anomalies.forEach((a: TraceAnomaly) => {
+        console.log(chalk.yellow(`  ${a.constraintId}`));
+        console.log(chalk.gray(`    类型: ${a.type}`));
+        console.log(chalk.gray(`    当前值: ${a.data?.currentRate ?? (a as any).current ?? 'N/A'}`));
+        console.log(chalk.gray(`    阈值: ${a.data?.threshold ?? (a as any).threshold ?? 'N/A'}`));
+        console.log();
+      });
+
+      // 下一步建议
+      console.log(chalk.blue('💡 下一步建议:'));
+      console.log(chalk.gray('  1. 运行 harness flow 一键诊断 + 提案'));
+      console.log(chalk.gray('  2. 运行 harness status --detail 查看详情'));
+    }
+    return;
+  }
+
+  // 显示约束统计
+  console.log(chalk.blue('📈 约束统计:'));
+  console.log();
+
+  // Iron Laws
+  const ironLawSummaries = summaries.filter((s: TraceSummary) => s.level === 'iron_law');
+  if (ironLawSummaries.length > 0) {
+    console.log(chalk.red('🔴 Iron Laws:'));
+    ironLawSummaries.forEach((s: TraceSummary) => {
+      const status = s.passRate >= 1 ? '✅' : '❌';
+      console.log(`  ${status} ${s.constraintId}`);
+      if (options.detail) {
+        console.log(chalk.gray(`     检查: ${s.totalChecks} | 通过: ${(s.passRate * 100).toFixed(0)}% | 绕过: ${(s.bypassRate * 100).toFixed(0)}%`));
+      }
+    });
+    console.log();
+  }
+
+  // Guidelines
+  const guidelineSummaries = summaries.filter((s: TraceSummary) => s.level === 'guideline');
+  if (guidelineSummaries.length > 0) {
+    console.log(chalk.yellow('🟡 Guidelines:'));
+    guidelineSummaries.forEach((s: TraceSummary) => {
+      const status = s.passRate >= 0.8 ? '✅' : s.passRate >= 0.5 ? '⚠️' : '❌';
+      console.log(`  ${status} ${s.constraintId}`);
+      if (options.detail) {
+        console.log(chalk.gray(`     检查: ${s.totalChecks} | 通过: ${(s.passRate * 100).toFixed(0)}% | 绕过: ${(s.bypassRate * 100).toFixed(0)}%`));
+      }
+    });
+    console.log();
+  }
+
+  // Tips
+  const tipSummaries = summaries.filter((s: TraceSummary) => s.level === 'tip');
+  if (tipSummaries.length > 0) {
+    console.log(chalk.blue('🔵 Tips:'));
+    tipSummaries.forEach((s: TraceSummary) => {
+      console.log(`  💡 ${s.constraintId}`);
+    });
+    console.log();
+  }
+
+  // 异常检测
+  if (anomalies.length > 0) {
+    console.log(chalk.yellow(`⚠️  发现 ${anomalies.length} 个异常`));
+    console.log();
+    anomalies.slice(0, 3).forEach((a: TraceAnomaly) => {
+      console.log(chalk.yellow(`  - ${a.constraintId}: ${a.type}`));
+    });
+    console.log();
+  }
+
+  // 更新状态文件
+  const state = {
+    lastStatusRun: new Date().toISOString(),
+  };
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+
+  // 下一步建议
+  console.log(chalk.blue('💡 下一步建议:'));
+  if (anomalies.length > 0) {
+    console.log(chalk.gray('  harness flow            # 一键执行诊断+提案'));
+    console.log(chalk.gray('  harness status --detail # 查看详细状态'));
+  } else if (traceCount >= 100) {
+    console.log(chalk.gray('  • 状态良好，继续保持！'));
+  } else {
+    console.log(chalk.gray('  • 继续积累数据，记录越多分析越准确'));
+  }
+}