@dommaker/harness 0.13.0 → 0.13.2

package/src/cli/commands/__tests__/sync-docs.test.ts

@@ -0,0 +1,335 @@
+/**
+ * sync-docs 命令测试
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { syncDocs } from '../sync-docs';
+
+describe('sync-docs command', () => {
+  const tempDir = path.join(process.cwd(), 'temp-test-sync-docs');
+
+  beforeAll(() => {
+    fs.mkdirSync(tempDir, { recursive: true });
+  });
+
+  afterAll(() => {
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  let consoleSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    consoleSpy = jest.spyOn(console, 'log').mockImplementation();
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+  });
+
+  describe('generateModuleTable', () => {
+    it('空模块列表应该跳过表格生成', async () => {
+      const testDir = path.join(tempDir, 'empty-table');
+      fs.mkdirSync(testDir, { recursive: true });
+
+      // No src dir → no modules → nothing to report
+      const result = await syncDocs({ projectPath: testDir });
+
+      expect(result).toBe(true);
+      // When no modules and no changes, all docs are current
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('所有文档'));
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('有模块时应该生成完整表格', async () => {
+      const testDir = path.join(tempDir, 'with-table');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      // Create a source file with JSDoc comment
+      fs.writeFileSync(path.join(srcDir, 'mymodule.ts'), '/**\n * My test module\n */\nexport const x = 1;');
+
+      await syncDocs({ projectPath: testDir });
+
+      const capPath = path.join(testDir, 'CAPABILITIES.md');
+      const content = fs.readFileSync(capPath, 'utf-8');
+      expect(content).toContain('| 模块 | 文件 | 说明 |');
+      expect(content).toContain('mymodule');
+      expect(content).toContain('My test module');
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+  });
+
+  describe('extractFirstComment', () => {
+    it('JSDoc 注释应该被提取为模块描述', async () => {
+      const testDir = path.join(tempDir, 'jsdoc-extract');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      fs.writeFileSync(path.join(srcDir, 'jsdoc-mod.ts'), '/**\n * JSDoc module description\n */\nexport const y = 2;');
+
+      await syncDocs({ projectPath: testDir });
+
+      const capPath = path.join(testDir, 'CAPABILITIES.md');
+      const content = fs.readFileSync(capPath, 'utf-8');
+      expect(content).toContain('JSDoc module description');
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('单行 // 注释应该被提取为模块描述', async () => {
+      const testDir = path.join(tempDir, 'linecomment-extract');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      // Create a file with // style comment
+      const filePath = path.join(srcDir, 'line-mod.ts');
+      fs.writeFileSync(filePath, '// Line comment module\nexport const z = 3;');
+
+      await syncDocs({ projectPath: testDir });
+
+      const capPath = path.join(testDir, 'CAPABILITIES.md');
+      const content = fs.readFileSync(capPath, 'utf-8');
+      expect(content).toContain('Line comment module');
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('无注释文件应该使用文件名作为描述', async () => {
+      const testDir = path.join(tempDir, 'no-comment');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      fs.writeFileSync(path.join(srcDir, 'bare.ts'), 'export const a = 1;');
+
+      await syncDocs({ projectPath: testDir });
+
+      const capPath = path.join(testDir, 'CAPABILITIES.md');
+      const content = fs.readFileSync(capPath, 'utf-8');
+      // Should use file basename as description when no comment
+      expect(content).toContain('bare');
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+  });
+
+
+  describe('syncDocs', () => {
+    it('无 src/ 目录应该跳过模块扫描', async () => {
+      const emptyDir = path.join(tempDir, 'empty');
+      fs.mkdirSync(emptyDir, { recursive: true });
+
+      const result = await syncDocs({ projectPath: emptyDir });
+      expect(result).toBe(true);
+      // 无 src/ 目录，模块扫描返回空，无差异
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('所有文档都是最新的'));
+
+      fs.rmSync(emptyDir, { recursive: true, force: true });
+    });
+
+    it('所有文档都是最新的应该返回 true', async () => {
+      const testDir = path.join(tempDir, 'up-to-date');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      // 创建 CAPABILITIES.md，无表格
+      fs.writeFileSync(path.join(testDir, 'CAPABILITIES.md'), '# Capabilities\n\nNo table.');
+
+      const result = await syncDocs({ projectPath: testDir });
+      expect(result).toBe(true);
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('--check 模式应该检测新增文件', async () => {
+      const testDir = path.join(tempDir, 'check-mode');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      // 创建源文件
+      fs.writeFileSync(path.join(srcDir, 'new-module.ts'), 'export const x = 1;');
+
+      // CAPABILITIES.md 有表格但不包含新文件
+      fs.writeFileSync(
+        path.join(testDir, 'CAPABILITIES.md'),
+        '# Capabilities\n\n| 模块 | 文件 | 说明 |\n|------|------|------|\n| old | src/old.ts | old |'
+      );
+
+      const result = await syncDocs({ projectPath: testDir, check: true });
+      expect(result).toBe(false);
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('文档不是最新的'));
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('应该检查 CONTEXT.md 是否存在', async () => {
+      const testDir = path.join(tempDir, 'context-check');
+      const harnessDir = path.join(testDir, '.harness');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(harnessDir, { recursive: true });
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      // 写入 governance 配置
+      const yaml = require('js-yaml');
+      fs.writeFileSync(
+        path.join(harnessDir, 'config.yml'),
+        yaml.dump({
+          governance: {
+            context_files: {
+              enabled: true,
+              required_dirs: ['src'],
+            },
+          },
+        })
+      );
+
+      // 不创建 CONTEXT.md
+
+      const result = await syncDocs({ projectPath: testDir });
+      expect(result).toBe(false);
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('缺少 CONTEXT.md'));
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('CONTEXT.md 已存在应该通过', async () => {
+      const testDir = path.join(tempDir, 'context-exists');
+      const harnessDir = path.join(testDir, '.harness');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(harnessDir, { recursive: true });
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      const yaml = require('js-yaml');
+      fs.writeFileSync(
+        path.join(harnessDir, 'config.yml'),
+        yaml.dump({
+          governance: {
+            context_files: {
+              enabled: true,
+              required_dirs: ['src'],
+            },
+          },
+        })
+      );
+
+      // 创建 CONTEXT.md
+      fs.writeFileSync(path.join(srcDir, 'CONTEXT.md'), '# src\n\nTest context');
+
+      const result = await syncDocs({ projectPath: testDir });
+      expect(result).toBe(true);
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('无 governance 配置不应该检查 CONTEXT.md', async () => {
+      const testDir = path.join(tempDir, 'no-governance');
+      fs.mkdirSync(testDir, { recursive: true });
+
+      // 无 .harness/config.yml
+
+      const result = await syncDocs({ projectPath: testDir });
+      expect(result).toBe(true);
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('应该创建缺失的 CONTEXT.md', async () => {
+      const testDir = path.join(tempDir, 'create-context');
+      const harnessDir = path.join(testDir, '.harness');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(harnessDir, { recursive: true });
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      const yaml = require('js-yaml');
+      fs.writeFileSync(
+        path.join(harnessDir, 'config.yml'),
+        yaml.dump({
+          governance: {
+            context_files: {
+              enabled: true,
+              required_dirs: ['src'],
+            },
+          },
+        })
+      );
+
+      await syncDocs({ projectPath: testDir });
+
+      // 验证 CONTEXT.md 被创建
+      const contextPath = path.join(srcDir, 'CONTEXT.md');
+      expect(fs.existsSync(contextPath)).toBe(true);
+      const content = fs.readFileSync(contextPath, 'utf-8');
+      expect(content).toContain('职责');
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('CAPABILITIES.md 不存在时应该创建', async () => {
+      const testDir = path.join(tempDir, 'no-cap');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      // 创建源文件
+      fs.writeFileSync(path.join(srcDir, 'module.ts'), 'export const x = 1;');
+
+      await syncDocs({ projectPath: testDir });
+
+      // 验证 CAPABILITIES.md 被创建
+      const capPath = path.join(testDir, 'CAPABILITIES.md');
+      expect(fs.existsSync(capPath)).toBe(true);
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('--json 模式应该输出结构化 JSON', async () => {
+      const testDir = path.join(tempDir, 'json-output');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      fs.writeFileSync(path.join(srcDir, 'new.ts'), 'export const x = 1;');
+      fs.writeFileSync(
+        path.join(testDir, 'CAPABILITIES.md'),
+        '# Capabilities\n\n| 模块 | 文件 | 说明 |\n|------|------|------|\n| old | src/old.ts | old |'
+      );
+
+      const result = await syncDocs({ projectPath: testDir, check: true, json: true });
+      expect(result).toBe(false);
+
+      // 验证 console.log 被调用了 JSON
+      const jsonCall = consoleSpy.mock.calls.find(
+        (call: unknown[]) => typeof call[0] === 'string' && call[0].startsWith('{')
+      );
+      expect(jsonCall).toBeDefined();
+      const parsed = JSON.parse(jsonCall![0]);
+      expect(parsed.stale).toBe(true);
+      expect(parsed.added.length).toBeGreaterThan(0);
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('--json 模式无差异应该输出 stale:false', async () => {
+      const testDir = path.join(tempDir, 'json-ok');
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(path.join(testDir, 'CAPABILITIES.md'), '# Capabilities\n\nNo table.');
+
+      const result = await syncDocs({ projectPath: testDir, check: true, json: true });
+      expect(result).toBe(true);
+
+      const jsonCall = consoleSpy.mock.calls.find(
+        (call: unknown[]) => typeof call[0] === 'string' && call[0].startsWith('{')
+      );
+      expect(jsonCall).toBeDefined();
+      const parsed = JSON.parse(jsonCall![0]);
+      expect(parsed.stale).toBe(false);
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+  });
+});

package/src/cli/commands/__tests__/validate.test.ts

@@ -0,0 +1,139 @@
+/**
+ * validate 命令测试
+ */
+
+import { validate, createExampleCheckpoint } from '../validate';
+import * as fs from 'fs/promises';
+import { CheckpointValidator } from '../../../core/validators/checkpoint';
+import * as yaml from 'js-yaml';
+
+// Mock fs/promises
+jest.mock('fs/promises', () => ({
+  readFile: jest.fn(),
+  writeFile: jest.fn(),
+  mkdir: jest.fn(),
+}));
+
+// Mock CheckpointValidator
+jest.mock('../../../core/validators/checkpoint', () => ({
+  CheckpointValidator: {
+    getInstance: jest.fn(),
+  },
+}));
+
+// Mock yaml
+jest.mock('js-yaml', () => ({
+  load: jest.fn(),
+  dump: jest.fn(),
+}));
+
+// Mock chalk
+jest.mock('chalk', () => ({
+  blue: jest.fn((str: string) => str),
+  yellow: jest.fn((str: string) => str),
+  green: jest.fn((str: string) => str),
+  gray: jest.fn((str: string) => str),
+  red: jest.fn((str: string) => str),
+}));
+
+const mockFs = fs as jest.Mocked<typeof fs>;
+const MockCheckpointValidator = CheckpointValidator as jest.Mocked<typeof CheckpointValidator>;
+const mockYaml = yaml as jest.Mocked<typeof yaml>;
+
+describe('validate command', () => {
+  let consoleSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    consoleSpy = jest.spyOn(console, 'log').mockImplementation();
+    process.exitCode = 0;
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+    process.exitCode = 0;
+  });
+
+  describe('validate', () => {
+    it('应该跳过无检查点的情况', async () => {
+      mockFs.readFile.mockRejectedValue(new Error('file not found'));
+      
+      await validate({});
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('没有定义检查点'));
+    });
+
+    it('应该通过所有检查点', async () => {
+      const mockCheckpoints = [
+        { id: 'test-1', checks: [{ id: 'check-1', type: 'test' }] },
+      ];
+      
+      mockFs.readFile.mockResolvedValue('checkpoints content');
+      mockYaml.load.mockReturnValue({ checkpoints: mockCheckpoints });
+
+      const mockValidator = {
+        validate: jest.fn().mockResolvedValue({ passed: true, checks: [] }),
+      };
+      (MockCheckpointValidator.getInstance as jest.Mock).mockReturnValue(mockValidator);
+
+      await validate({});
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('所有检查点验证通过'));
+    });
+
+    it('应该显示失败的检查点', async () => {
+      const mockCheckpoints = [
+        { id: 'test-1', checks: [{ id: 'check-1', type: 'test' }] },
+      ];
+      
+      mockFs.readFile.mockResolvedValue('checkpoints content');
+      mockYaml.load.mockReturnValue({ checkpoints: mockCheckpoints });
+
+      const mockValidator = {
+        validate: jest.fn().mockResolvedValue({
+          passed: false,
+          checks: [{ checkId: 'check-1', passed: false, message: 'failed' }],
+        }),
+      };
+      (MockCheckpointValidator.getInstance as jest.Mock).mockReturnValue(mockValidator);
+
+      await validate({});
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('失败'));
+    });
+
+    it('应该在严格模式下退出', async () => {
+      const mockCheckpoints = [
+        { id: 'test-1', checks: [{ id: 'check-1', type: 'test' }] },
+      ];
+      
+      mockFs.readFile.mockResolvedValue('checkpoints content');
+      mockYaml.load.mockReturnValue({ checkpoints: mockCheckpoints });
+
+      const mockValidator = {
+        validate: jest.fn().mockResolvedValue({
+          passed: false,
+          checks: [{ checkId: 'check-1', passed: false, message: 'failed' }],
+        }),
+      };
+      (MockCheckpointValidator.getInstance as jest.Mock).mockReturnValue(mockValidator);
+
+      const mockExit = jest.spyOn(process, 'exit').mockImplementation(() => undefined as never);
+
+      await validate({ strict: true });
+      expect(mockExit).toHaveBeenCalledWith(1);
+      mockExit.mockRestore();
+    });
+  });
+
+  describe('createExampleCheckpoint', () => {
+    it('应该创建示例检查点文件', async () => {
+      mockFs.mkdir.mockResolvedValue(undefined);
+      mockFs.writeFile.mockResolvedValue(undefined);
+      mockYaml.dump.mockReturnValue('yaml content');
+
+      await createExampleCheckpoint('/project');
+      
+      expect(mockFs.mkdir).toHaveBeenCalled();
+      expect(mockFs.writeFile).toHaveBeenCalled();
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('已创建示例检查点'));
+    });
+  });
+});

package/src/cli/commands/acceptance.ts

@@ -0,0 +1,111 @@
+/**
+ * harness acceptance 命令
+ *
+ * 验收标准门控，检查任务是否满足验收标准
+ */
+
+import chalk from 'chalk';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { SpecAcceptanceGate } from '../../gates/acceptance';
+
+export interface AcceptanceOptions {
+  /** 任务 ID */
+  taskId?: string;
+  /** tasks.yml 路径 */
+  tasksPath?: string;
+  /** 项目路径 */
+  projectPath?: string;
+  /** 是否检查所有任务 */
+  checkAll?: boolean;
+  /** 是否运行 E2E 测试 */
+  runE2e?: boolean;
+}
+
+/**
+ * 执行验收门控
+ */
+export async function acceptance(options: AcceptanceOptions): Promise<void> {
+  console.log(chalk.blue('📋 验收标准门控检查...'));
+
+  const projectPath = options.projectPath || process.cwd();
+
+  // 创建验收门控实例
+  const gate = new SpecAcceptanceGate({
+    tasksPath: options.tasksPath,
+    checkAllTasks: options.checkAll,
+    e2eTestCommand: options.runE2e ? 'npx playwright test' : undefined,
+  });
+
+  try {
+    // 执行检查
+    const context = {
+      projectPath,
+      taskId: options.taskId,
+    };
+
+    const result = await gate.check(context as any);
+
+    if (result.passed) {
+      console.log();
+      console.log(chalk.green('✅ 验收标准检查通过'));
+      if (result.details) {
+        console.log(chalk.gray(`   通过项: ${result.details.checkedCriteria ?? 0}`));
+        console.log(chalk.gray(`   总项数: ${result.details.totalCriteria ?? 0}`));
+      }
+    } else {
+      console.log();
+      console.log(chalk.red('❌ 验收标准检查失败'));
+      console.log(chalk.red(`   ${result.message}`));
+      if (result.details?.uncheckedCriteria) {
+        (result.details.uncheckedCriteria as string[]).forEach((criteria: string) => {
+          console.log(chalk.red(`   - ${criteria}`));
+        });
+      }
+      process.exit(1);
+    }
+  } catch (error: any) {
+    console.log();
+    console.log(chalk.red('❌ 验收标准检查出错'));
+    console.log(chalk.red(`   ${error.message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * 列出所有任务及其验收标准
+ */
+export async function listAcceptanceCriteria(options: AcceptanceOptions): Promise<void> {
+  console.log(chalk.blue('📋 任务验收标准列表...\n'));
+
+  const projectPath = options.projectPath || process.cwd();
+  const tasksPath = options.tasksPath || path.join(projectPath, 'tasks.yml');
+
+  try {
+    const content = await fs.readFile(tasksPath, 'utf-8');
+    const yaml = await import('js-yaml');
+    const tasks = yaml.load(content) as any;
+
+    if (!tasks || typeof tasks !== 'object') {
+      console.log(chalk.yellow('⚠️  未找到任务定义'));
+      return;
+    }
+
+    for (const [taskId, task] of Object.entries(tasks)) {
+      if (typeof task === 'object' && task !== null) {
+        console.log(chalk.cyan(`${taskId}:`));
+        const taskObj = task as any;
+        if (taskObj.acceptanceCriteria) {
+          taskObj.acceptanceCriteria.forEach((criteria: string, i: number) => {
+            console.log(chalk.gray(`  ${i + 1}. ${criteria}`));
+          });
+        } else {
+          console.log(chalk.gray('  (无验收标准)'));
+        }
+        console.log();
+      }
+    }
+  } catch (error: any) {
+    console.log(chalk.red(`❌ 读取 tasks.yml 失败: ${error.message}`));
+  }
+}