@dommaker/harness 1.2.3 → 1.4.0

package/src/cli/commands/__tests__/doc-freshness-check.test.ts

@@ -1,168 +0,0 @@
-/**
- * doc-freshness-check 命令测试
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { extractClaims, verifyClaims, docFreshnessCheck } from '../doc-freshness-check';
-
-describe('doc-freshness-check', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-doc-freshness');
-  let consoleSpy: jest.SpyInstance;
-  let errorSpy: jest.SpyInstance;
-  let originalExitCode: string | number | undefined;
-
-  beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
-  });
-
-  afterAll(() => {
-    try {
-      fs.rmSync(tempDir, { recursive: true, force: true });
-    } catch {
-      // ignore
-    }
-  });
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-    consoleSpy = jest.spyOn(console, 'log').mockImplementation();
-    errorSpy = jest.spyOn(console, 'error').mockImplementation();
-    originalExitCode = process.exitCode;
-    process.exitCode = 0;
-  });
-
-  afterEach(() => {
-    consoleSpy.mockRestore();
-    errorSpy.mockRestore();
-    process.exitCode = originalExitCode;
-  });
-
-  describe('extractClaims', () => {
-    it('应该提取数字声明', () => {
-      const content = '系统包含 9 个 Agent 和 13 条规则';
-      const results = extractClaims(content, 'test.md');
-
-      expect(results.length).toBeGreaterThanOrEqual(2);
-      const numericResults = results.filter(r => r.type === 'numeric');
-      expect(numericResults.length).toBeGreaterThanOrEqual(2);
-      expect(numericResults.some(r => r.expected === '9')).toBe(true);
-      expect(numericResults.some(r => r.expected === '13')).toBe(true);
-    });
-
-    it('应该提取列表声明', () => {
-      const content = '组件包括 Analyst, Executor, Reviewer, Monitor';
-      const results = extractClaims(content, 'test.md');
-
-      const listResults = results.filter(r => r.type === 'list');
-      expect(listResults.length).toBeGreaterThanOrEqual(1);
-      expect(listResults[0].expected).toContain('Analyst');
-      expect(listResults[0].expected).toContain('Executor');
-    });
-
-    it('应该提取状态标记', () => {
-      const content = '✅ 已完成\n❌ 缺失\nDEPRECATED\n待开发';
-      const results = extractClaims(content, 'test.md');
-
-      const statusResults = results.filter(r => r.type === 'status');
-      expect(statusResults.length).toBeGreaterThanOrEqual(3);
-    });
-
-    it('应该忽略不含声明的行', () => {
-      const content = '这是一段普通的描述文字\n没有可验证的内容';
-      const results = extractClaims(content, 'test.md');
-
-      expect(results.length).toBe(0);
-    });
-
-    it('应该处理混合内容', () => {
-      const content = [
-        '# 系统架构',
-        '包含 8 个 Agent，5 大能力',
-        'Agent 列表: Analyst, Executor, Reviewer, Knowledge, Monitor',
-        '✅ 已完成核心功能',
-        '待开发: xxx',
-        '普通段落文字',
-      ].join('\n');
-
-      const results = extractClaims(content, 'test.md');
-      expect(results.length).toBeGreaterThanOrEqual(4);
-    });
-  });
-
-  describe('verifyClaims', () => {
-    it('应该验证数字声明（命令计数）', () => {
-      const claims = extractClaims('包含 22 个 subcommand', 'test.md');
-      const results = verifyClaims(claims, path.join(__dirname, '../../../../'));
-
-      expect(results.length).toBe(1);
-      // harness 实际有很多命令，数字可能不完全匹配但应该有值
-      expect(results[0].actual).not.toBe('');
-    });
-
-    it('应该验证列表声明', () => {
-      const claims = extractClaims('组件: Analyst, Executor, Reviewer', 'test.md');
-      // 用 harness 源码目录作为 projectPath
-      const results = verifyClaims(claims, path.join(__dirname, '../../../../'));
-
-      // 列表验证会检查代码中是否存在这些名称
-      expect(results.length).toBe(1);
-      expect(results[0].type).toBe('list');
-    });
-
-    it('状态标记应该标记为需人工确认', () => {
-      const claims = extractClaims('✅ 已完成', 'test.md');
-      const results = verifyClaims(claims, tempDir);
-
-      expect(results.length).toBe(1);
-      expect(results[0].match).toBe(true); // 不阻断
-    });
-  });
-
-  describe('docFreshnessCheck CLI', () => {
-    it('应该在文件不存在时报错', async () => {
-      await docFreshnessCheck('/nonexistent/file.md');
-
-      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('文件不存在'));
-      expect(process.exitCode).toBe(1);
-    });
-
-    it('应该输出 table 格式', async () => {
-      const docPath = path.join(tempDir, 'test-doc.md');
-      fs.writeFileSync(docPath, '# Test\n系统有 9 个 Agent 和 13 条规则');
-
-      await docFreshnessCheck(docPath, { projectPath: tempDir });
-
-      expect(consoleSpy).toHaveBeenCalled();
-      const output = consoleSpy.mock.calls.map((c: any[]) => c[0]).join('\n');
-      expect(output).toContain('文档新鲜度检查');
-    });
-
-    it('应该输出 JSON 格式', async () => {
-      const docPath = path.join(tempDir, 'test-json.md');
-      fs.writeFileSync(docPath, '# Test\n系统有 5 个 Agent');
-
-      await docFreshnessCheck(docPath, { format: 'json', projectPath: tempDir });
-
-      const jsonCall = consoleSpy.mock.calls.find((c: any[]) => {
-        try {
-          const parsed = JSON.parse(c[0]);
-          return Array.isArray(parsed);
-        } catch {
-          return false;
-        }
-      });
-      expect(jsonCall).toBeTruthy();
-    });
-
-    it('空文档应该输出 0 条声明', async () => {
-      const docPath = path.join(tempDir, 'empty.md');
-      fs.writeFileSync(docPath, '# Empty\n\nNo claims here.');
-
-      await docFreshnessCheck(docPath, { projectPath: tempDir });
-
-      const output = consoleSpy.mock.calls.map((c: any[]) => c[0]).join('\n');
-      expect(output).toContain('未发现可验证的声明');
-    });
-  });
-});

package/src/cli/commands/doc-freshness-check.ts

@@ -1,386 +0,0 @@
-/**
- * harness doc-freshness-check 命令
- *
- * 从文档中提取可验证的声明(claims)，与代码/文件系统对照，输出差异。
- * 纯代码操作，零 LLM 调用。
- */
-
-import chalk from 'chalk';
-import * as fs from 'fs';
-import * as path from 'path';
-import { walkFiles } from '../../utils/file-walk';
-
-export interface DocFreshnessCheckOptions {
-  /** 输出 JSON 格式 */
-  format?: 'json' | 'table';
-  /** 变更文件列表（逗号分隔），用于聚焦检查 */
-  changedFiles?: string;
-  /** 项目路径 */
-  projectPath?: string;
-}
-
-/** 声明类型 */
-export type ClaimType = 'numeric' | 'list' | 'status' | 'narrative';
-
-/** 单条声明 */
-export interface Claim {
-  /** 原始文本片段 */
-  text: string;
-  /** 声明类型 */
-  type: ClaimType;
-  /** 行号 */
-  line: number;
-}
-
-/** 验证结果 */
-export interface ClaimResult {
-  /** 原始声明 */
-  claim: string;
-  /** 声明类型 */
-  type: ClaimType;
-  /** 文档中的期望值 */
-  expected: string;
-  /** 实际值 */
-  actual: string;
-  /** 来源文件 */
-  file: string;
-  /** 是否匹配 */
-  match: boolean;
-}
-
-// ============================================
-// Claim 提取器
-// ============================================
-
-/** 数字声明：N 个/条/项 + 名词 */
-const NUMERIC_PATTERNS = [
-  /(\d+)\s*个\s*(Agent|角色|能力|子系统|模块|端点|命令|组件|层级|阶段|步骤|断点|问题|维度|门|规则|约束)/g,
-  /(\d+)\s*条\s*(知识|规则|约束|命令|铁律|指南|提示|断点|问题|结果|记录)/g,
-  /(\d+)\s*项\s*(检查|任务|功能|变更|修复|优化|指标|配置)/g,
-  /(\d+)\s*(?:大|层)\s*(能力|约束|架构|层级)/g,
-  /(\d+)\s*个\s*(?:CLI\s*)?subcommand/gi,
-];
-
-/** 列表声明：A, B, C, ... (至少 3 项) */
-const LIST_PATTERN = /[A-Z][a-zA-Z]+(?:[,，、]\s*[A-Z][a-zA-Z]+){2,}/g;
-
-/** 状态标记 */
-const STATUS_PATTERNS = [
-  /✅\s*(已完成|已实现|已修复|已部署|已连通|已验证)/g,
-  /❌\s*(缺失|未实现|未完成|失败)/g,
-  /\bDEPRECATED\b/g,
-  /\bTODO\b/g,
-  /待(开发|实现|修复|完善|验证)/g,
-  /已(废弃|弃用|移除|删除)/g,
-];
-
-/**
- * 从 markdown 内容提取 claims
- */
-export function extractClaims(content: string, filePath: string): ClaimResult[] {
-  const lines = content.split('\n');
-  const results: ClaimResult[] = [];
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-
-    // 数字声明
-    for (const pattern of NUMERIC_PATTERNS) {
-      pattern.lastIndex = 0;
-      let match;
-      while ((match = pattern.exec(line)) !== null) {
-        const fullMatch = match[0];
-        const number = match[1];
-        results.push({
-          claim: fullMatch,
-          type: 'numeric',
-          expected: number,
-          actual: '', // 待验证
-          file: filePath,
-          match: false,
-        });
-      }
-    }
-
-    // 列表声明
-    const listMatches = line.match(LIST_PATTERN);
-    if (listMatches) {
-      for (const m of listMatches) {
-        const items = m.split(/[,，、]/).map(s => s.trim()).filter(Boolean);
-        if (items.length >= 3) {
-          results.push({
-            claim: m,
-            type: 'list',
-            expected: items.join(', '),
-            actual: '', // 待验证
-            file: filePath,
-            match: false,
-          });
-        }
-      }
-    }
-
-    // 状态标记
-    for (const pattern of STATUS_PATTERNS) {
-      pattern.lastIndex = 0;
-      let match;
-      while ((match = pattern.exec(line)) !== null) {
-        results.push({
-          claim: match[0],
-          type: 'status',
-          expected: match[0],
-          actual: '', // 待验证
-          file: filePath,
-          match: false,
-        });
-      }
-    }
-  }
-
-  return results;
-}
-
-// ============================================
-// 验证器
-// ============================================
-
-/**
- * 在项目目录中 grep 搜索匹配内容，返回匹配行数
- */
-function countGrepMatches(pattern: string, projectPath: string, fileGlob?: string): number {
-  const searchDir = projectPath || process.cwd();
-  let count = 0;
-  const regex = new RegExp(pattern, 'gi');
-
-  const files = walkFiles(searchDir, {
-    skipDirs: ['node_modules', 'dist'],
-    skipHidden: true,
-    filter: (name) => !fileGlob || matchGlob(name, fileGlob),
-  });
-
-  for (const fullPath of files) {
-    try {
-      const content = fs.readFileSync(fullPath, 'utf-8');
-      const matches = content.match(regex);
-      if (matches) count += matches.length;
-    } catch {
-      // skip unreadable files
-    }
-  }
-
-  return count;
-}
-
-/**
- * 简单 glob 匹配（支持 *.ext 和 *）
- */
-function matchGlob(filename: string, glob: string): boolean {
-  if (glob === '*') return true;
-  if (glob.startsWith('*.')) {
-    const ext = glob.slice(1);
-    return filename.endsWith(ext);
-  }
-  return filename === glob;
-}
-
-/**
- * 验证数字声明：计数相关文件/代码模式
- */
-function verifyNumericClaim(claim: ClaimResult, projectPath: string): ClaimResult {
-  const expected = parseInt(claim.expected, 10);
-
-  // 从声明文本推断搜索模式
-  let searchPattern = '';
-  let fileGlob = '*.ts';
-
-  if (claim.claim.includes('Agent')) {
-    searchPattern = 'export (class|interface|function) \\w*Agent';
-  } else if (claim.claim.includes('命令') || claim.claim.includes('subcommand')) {
-    fileGlob = '*.ts';
-    searchPattern = "program\\.command\\(";
-  } else if (claim.claim.includes('铁律') || claim.claim.includes('约束') || claim.claim.includes('规则')) {
-    searchPattern = "severity:\\s*['\"]?error";
-    fileGlob = '*.ts';
-  } else if (claim.claim.includes('指南')) {
-    searchPattern = "severity:\\s*['\"]?warning";
-    fileGlob = '*.ts';
-  } else if (claim.claim.includes('端点')) {
-    searchPattern = '(router|app)\\.(get|post|put|delete|patch)\\(';
-    fileGlob = '*.ts';
-  } else {
-    // 无法自动验证的数字声明
-    return { ...claim, actual: 'N/A (cannot auto-verify)', match: true };
-  }
-
-  const actual = countGrepMatches(searchPattern, projectPath, fileGlob);
-
-  return {
-    ...claim,
-    actual: String(actual),
-    match: Math.abs(actual - expected) <= Math.max(1, Math.floor(expected * 0.1)), // 10% tolerance
-  };
-}
-
-/**
- * 验证列表声明：检查列表中的每一项是否存在于代码中
- */
-function verifyListClaim(claim: ClaimResult, projectPath: string): ClaimResult {
-  const items = claim.expected.split(',').map(s => s.trim());
-  const found: string[] = [];
-  const missing: string[] = [];
-
-  for (const item of items) {
-    const count = countGrepMatches(item, projectPath);
-    if (count > 0) {
-      found.push(item);
-    } else {
-      missing.push(item);
-    }
-  }
-
-  return {
-    ...claim,
-    actual: missing.length === 0
-      ? `all ${items.length} found`
-      : `missing: ${missing.join(', ')}`,
-    match: missing.length === 0,
-  };
-}
-
-/**
- * 验证状态声明：检查标记是否与代码/文件一致
- */
-function verifyStatusClaim(claim: ClaimResult, _projectPath: string): ClaimResult {
-  // 状态声明的验证较复杂，标记为需要人工确认
-  return {
-    ...claim,
-    actual: 'needs manual verification',
-    match: true, // 不阻断
-  };
-}
-
-/**
- * 验证所有 claims
- */
-export function verifyClaims(
-  claims: ClaimResult[],
-  projectPath: string,
-): ClaimResult[] {
-  return claims.map(claim => {
-    switch (claim.type) {
-      case 'numeric':
-        return verifyNumericClaim(claim, projectPath);
-      case 'list':
-        return verifyListClaim(claim, projectPath);
-      case 'status':
-        return verifyStatusClaim(claim, projectPath);
-      default:
-        return { ...claim, actual: 'N/A', match: true };
-    }
-  });
-}
-
-// ============================================
-// 输出格式化
-// ============================================
-
-function formatTable(results: ClaimResult[]): string {
-  if (results.length === 0) return chalk.yellow('未发现可验证的声明');
-
-  const lines: string[] = [];
-  lines.push(chalk.blue(`文档新鲜度检查 (${results.length} 条声明)\n`));
-
-  // 统计
-  const mismatches = results.filter(r => !r.match);
-  lines.push(chalk.bold(`  匹配: ${results.length - mismatches.length}/${results.length}`));
-  if (mismatches.length > 0) {
-    lines.push(chalk.red(`  不匹配: ${mismatches.length}\n`));
-  } else {
-    lines.push(chalk.green('  全部匹配\n'));
-  }
-
-  // 按类型分组
-  const byType: Record<string, ClaimResult[]> = {};
-  for (const r of results) {
-    if (!byType[r.type]) byType[r.type] = [];
-    byType[r.type].push(r);
-  }
-
-  const typeLabels: Record<string, string> = {
-    numeric: '数字声明',
-    list: '列表声明',
-    status: '状态标记',
-    narrative: '叙述声明',
-  };
-
-  for (const [type, items] of Object.entries(byType)) {
-    lines.push(chalk.bold(`  ${typeLabels[type] || type} (${items.length}):`));
-    for (const item of items) {
-      const icon = item.match ? chalk.green('✓') : chalk.red('✗');
-      lines.push(`    ${icon} ${item.claim}`);
-      if (!item.match) {
-        lines.push(`      期望: ${item.expected}`);
-        lines.push(`      实际: ${chalk.yellow(item.actual)}`);
-      }
-    }
-    lines.push('');
-  }
-
-  return lines.join('\n');
-}
-
-// ============================================
-// 主入口
-// ============================================
-
-/**
- * doc-freshness-check CLI 命令
- */
-export async function docFreshnessCheck(
-  docPath: string,
-  options: DocFreshnessCheckOptions = {},
-): Promise<void> {
-  // 验证文件存在
-  const resolvedPath = path.resolve(docPath);
-  if (!fs.existsSync(resolvedPath)) {
-    console.error(chalk.red(`文件不存在: ${resolvedPath}`));
-    process.exitCode = 1;
-    return;
-  }
-
-  if (!resolvedPath.endsWith('.md')) {
-    console.error(chalk.yellow(`警告: 文件不是 .md 格式，可能无法正确解析`));
-  }
-
-  const projectPath = options.projectPath || path.dirname(resolvedPath);
-
-  // 读取文档
-  const content = fs.readFileSync(resolvedPath, 'utf-8');
-
-  // 提取声明
-  const claims = extractClaims(content, resolvedPath);
-
-  // 如果指定了变更文件，只验证与变更文件相关的声明
-  if (options.changedFiles) {
-    const changed = options.changedFiles.split(',').map(s => s.trim());
-    // 过滤：保留所有 claims，但只验证与变更文件相关的
-    // 实际实现中可以根据声明内容推断相关文件
-    void changed; // 预留
-  }
-
-  // 验证
-  const results = verifyClaims(claims, projectPath);
-
-  // 输出
-  if (options.format === 'json') {
-    console.log(JSON.stringify(results, null, 2));
-  } else {
-    console.log(formatTable(results));
-  }
-
-  // 有不匹配时 exit 1
-  const mismatches = results.filter(r => !r.match);
-  if (mismatches.length > 0) {
-    process.exitCode = 1;
-  }
-}

package/src/spec/CONTEXT.md

@@ -1,11 +0,0 @@
-# spec/
-
-## 职责
-（空目录）原 @spec 注释规范检查（annotation-checker）已随 ADR-0003 删除。
-
-## 已接线的 spec 故事
-- `src/core/spec/validator.ts` — SpecValidator：spec 文档结构/内容验证（CLI `harness spec` 消费）
-- `src/gates/acceptance.ts` — SpecAcceptanceGate：验收标准门禁
-
-## 注意事项
-- @spec 注释检查若需恢复，应迁移为 ConstraintCheck 注册进闭环注册表（ADR-0003 后续立项），不在本目录重建独立子系统

package/src/types/index.ts

@@ -1,47 +0,0 @@
-/**
- * 类型导出
- */
-
-// 约束类型（三层体系）
-export * from './constraint';
-
-export * from './checkpoint';
-export * from './passes-gate';
-export * from './cso';
-
-// Trace 类型（Execution Trace 系统）
-export * from './trace';
-
-// Session 类型（排除与 passes-gate 冲突的类型）
-export {
-  StartupCheckpoints,
-  StartupCheckpointType,
-  StartupCheckpointResult,
-  CleanStateConfig,
-  CleanStateResult,
-  DetectedBug,
-  TaskListJson,
-  TaskStepStatus,
-  SessionInfo,
-} from './session';
-
-// 从 session 导入 DynamicTask，扩展 passes-gate 的定义
-export { DynamicTask as ExtendedDynamicTask, TaskTestResult as ExtendedTaskTestResult } from './session';
-
-// 项目配置类型
-export * from './project-config';
-
-// Spec 验证类型
-export * from './spec';
-
-// Failure 类型（定义已归位 types/failure.ts，failure 模块经 failure/types.ts 再导出保持兼容）
-// 显式再导出（不用 export *）：根入口同时星导出 ./failure，星-星歧义会静默丢符号
-export {
-  ErrorType,
-  FailureLevel,
-  ErrorClassificationRule,
-  FailureRecord,
-  ClassificationResult,
-  DEFAULT_CLASSIFICATION_RULES,
-  DEFAULT_LEVEL_MAPPING,
-} from './failure';