@dommaker/harness 0.16.0 → 0.16.2

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

@@ -0,0 +1,168 @@
+/**
+ * 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/__tests__/knowledge.test.ts

@@ -2,7 +2,7 @@
  * knowledge 命令测试 — knowledgeAudit
  */
 
-import { knowledgeAudit, knowledgeStats } from '../knowledge';
+import { knowledgeAudit, knowledgeStats, knowledgeHealth } from '../knowledge';
 
 // Mock chalk
 jest.mock('chalk', () => ({
@@ -22,6 +22,13 @@ jest.mock('../../../knowledge/audit', () => ({
   })),
 }));
 
+// Mock KnowledgeIndexGenerator (avoids real fs writes in CLI tests)
+jest.mock('../../../knowledge/index-generator', () => ({
+  KnowledgeIndexGenerator: jest.fn().mockImplementation(() => ({
+    regenerate: jest.fn(),
+  })),
+}));
+
 const MOCK_REPORT = {
   timestamp: '2026-06-02T00:00:00.000Z',
   totalEntries: 100,
@@ -165,3 +172,64 @@ describe('knowledgeAudit CLI', () => {
     }));
   });
 });
+
+describe('knowledgeHealth CLI', () => {
+  const storeModule = require('../../../knowledge/store');
+  let consoleSpy: jest.SpyInstance;
+  let storeSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    consoleSpy = jest.spyOn(console, 'log').mockImplementation();
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+    if (storeSpy) storeSpy.mockRestore();
+  });
+
+  it('should output health score and summary in JSON mode', async () => {
+    storeSpy = jest.spyOn(storeModule, 'FileKnowledgeStore').mockImplementation(() => ({
+      list: jest.fn().mockReturnValue([
+        { id: 'GUI-001', maturity: 'verified', sourceReferences: [], referencedBy: ['GUI-002'], created: new Date().toISOString() },
+        { id: 'GUI-002', maturity: 'draft', sourceReferences: [], referencedBy: [], created: new Date().toISOString() },
+      ]),
+      getBaseDir: jest.fn().mockReturnValue('/tmp/knowledge'),
+    }));
+
+    await knowledgeHealth({ json: true });
+    const output = consoleSpy.mock.calls.map((c: any[]) => c[0]).join('\n');
+    const parsed = JSON.parse(output);
+    expect(parsed).toHaveProperty('healthScore');
+    expect(parsed.summary).toHaveProperty('total', 2);
+  });
+
+  it('should detect low-reference verified entries', async () => {
+    storeSpy = jest.spyOn(storeModule, 'FileKnowledgeStore').mockImplementation(() => ({
+      list: jest.fn().mockReturnValue([
+        { id: 'GUI-001', maturity: 'verified', sourceReferences: [], referencedBy: [], created: new Date().toISOString() },
+      ]),
+      getBaseDir: jest.fn().mockReturnValue('/tmp/knowledge'),
+    }));
+
+    await knowledgeHealth({ json: true });
+    const output = consoleSpy.mock.calls.map((c: any[]) => c[0]).join('\n');
+    const parsed = JSON.parse(output);
+    expect(parsed.summary.lowRefEntries).toBe(1);
+  });
+
+  it('should detect stale draft entries', async () => {
+    const oldDate = new Date(Date.now() - 100 * 24 * 60 * 60 * 1000).toISOString(); // 100 days ago
+    storeSpy = jest.spyOn(storeModule, 'FileKnowledgeStore').mockImplementation(() => ({
+      list: jest.fn().mockReturnValue([
+        { id: 'GUI-001', maturity: 'draft', sourceReferences: [], referencedBy: [], created: oldDate },
+      ]),
+      getBaseDir: jest.fn().mockReturnValue('/tmp/knowledge'),
+    }));
+
+    await knowledgeHealth({ json: true });
+    const output = consoleSpy.mock.calls.map((c: any[]) => c[0]).join('\n');
+    const parsed = JSON.parse(output);
+    expect(parsed.summary.staleEntries).toBe(1);
+  });
+});

package/src/cli/commands/__tests__/spec-baseline-check.test.ts

@@ -0,0 +1,235 @@
+/**
+ * spec-baseline-check 命令测试
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { extractBaselineSection, specBaselineCheck } from '../spec-baseline-check';
+
+describe('spec-baseline-check', () => {
+  const tempDir = path.join(process.cwd(), 'temp-test-spec-baseline');
+  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('extractBaselineSection', () => {
+    it('应该提取 ## Baseline section 中的列表项', () => {
+      const content = [
+        '# Spec Title',
+        '',
+        '## Overview',
+        'Some overview text',
+        '',
+        '## Baseline',
+        '- Node.js >= 18',
+        '- TypeScript 5.x installed',
+        '- `src/core/` directory exists',
+        '',
+        '## Details',
+        'More details here',
+      ].join('\n');
+
+      const results = extractBaselineSection(content);
+      expect(results).toHaveLength(3);
+      expect(results[0]).toBe('Node.js >= 18');
+      expect(results[1]).toBe('TypeScript 5.x installed');
+      expect(results[2]).toBe('`src/core/` directory exists');
+    });
+
+    it('应该提取 ## 前置条件 section', () => {
+      const content = [
+        '# 设计文档',
+        '',
+        '## 前置条件',
+        '- 依赖包 `@dommaker/harness` 已安装',
+        '- `package.json` 存在',
+        '',
+        '## 方案',
+        '方案描述',
+      ].join('\n');
+
+      const results = extractBaselineSection(content);
+      expect(results).toHaveLength(2);
+      expect(results[0]).toContain('@dommaker/harness');
+    });
+
+    it('应该支持编号列表', () => {
+      const content = [
+        '## Baseline',
+        '1. Node.js 18+',
+        '2. pnpm installed',
+        '3. Docker available',
+      ].join('\n');
+
+      const results = extractBaselineSection(content);
+      expect(results).toHaveLength(3);
+      expect(results[0]).toBe('Node.js 18+');
+    });
+
+    it('应该忽略非目标 section', () => {
+      const content = [
+        '## Baseline',
+        '- Item 1',
+        '',
+        '## Other Section',
+        '- Should not be included',
+      ].join('\n');
+
+      const results = extractBaselineSection(content);
+      expect(results).toHaveLength(1);
+      expect(results[0]).toBe('Item 1');
+    });
+
+    it('没有 Baseline section 应返回空数组', () => {
+      const content = [
+        '# Spec',
+        '## Overview',
+        'No baseline here',
+      ].join('\n');
+
+      const results = extractBaselineSection(content);
+      expect(results).toHaveLength(0);
+    });
+
+    it('应该在遇到同级标题时停止', () => {
+      const content = [
+        '## Baseline',
+        '- Item 1',
+        '- Item 2',
+        '## Next Section',
+        '- Should not appear',
+        '### Sub section',
+        '- Also not',
+      ].join('\n');
+
+      const results = extractBaselineSection(content);
+      expect(results).toHaveLength(2);
+    });
+
+    it('应该支持嵌套在更高级标题下', () => {
+      const content = [
+        '# Main',
+        '## Setup',
+        '### Baseline',
+        '- Prereq 1',
+        '- Prereq 2',
+        '### Details',  // 同级标题，应该停止
+        '- Not included',
+        '## More',  // 更高级标题，也应该停止
+        '- Also not',
+      ].join('\n');
+
+      const results = extractBaselineSection(content);
+      expect(results).toHaveLength(2);
+      expect(results[0]).toBe('Prereq 1');
+    });
+  });
+
+  describe('specBaselineCheck CLI', () => {
+    it('应该在文件不存在时报错', async () => {
+      await specBaselineCheck('/nonexistent/spec.md');
+
+      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('文件不存在'));
+      expect(process.exitCode).toBe(1);
+    });
+
+    it('没有 Baseline section 应该提示', async () => {
+      const specPath = path.join(tempDir, 'no-baseline.md');
+      fs.writeFileSync(specPath, '# Spec\n## Overview\nNo baseline here.');
+
+      await specBaselineCheck(specPath, { projectPath: tempDir });
+
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('未找到'));
+    });
+
+    it('应该输出 table 格式结果', async () => {
+      // 创建测试用的文件和目录
+      const subDir = path.join(tempDir, 'test-project');
+      fs.mkdirSync(subDir, { recursive: true });
+      fs.writeFileSync(path.join(subDir, 'package.json'), JSON.stringify({ dependencies: {} }));
+
+      const specPath = path.join(tempDir, 'with-baseline.md');
+      fs.writeFileSync(specPath, [
+        '# Test Spec',
+        '## Baseline',
+        '- `package.json` 文件存在',
+        '- 普通文本描述',
+      ].join('\n'));
+
+      await specBaselineCheck(specPath, { projectPath: subDir });
+
+      const output = consoleSpy.mock.calls.map((c: any[]) => c[0]).join('\n');
+      expect(output).toContain('前置条件检查');
+    });
+
+    it('应该输出 JSON 格式', async () => {
+      const specPath = path.join(tempDir, 'json-test.md');
+      fs.writeFileSync(specPath, [
+        '# JSON Test',
+        '## Baseline',
+        '- `package.json` exists',
+      ].join('\n'));
+
+      await specBaselineCheck(specPath, { json: true, 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();
+      const parsed = JSON.parse(jsonCall[0]);
+      expect(parsed.length).toBe(1);
+      expect(parsed[0]).toHaveProperty('prerequisite');
+      expect(parsed[0]).toHaveProperty('satisfied');
+      expect(parsed[0]).toHaveProperty('evidence');
+    });
+
+    it('空 Baseline section 应该输出空结果', async () => {
+      const specPath = path.join(tempDir, 'empty-baseline.md');
+      fs.writeFileSync(specPath, '# Test\n## Baseline\n\n## Next');
+
+      await specBaselineCheck(specPath, { json: true, projectPath: tempDir });
+
+      const jsonCall = consoleSpy.mock.calls.find((c: any[]) => {
+        try {
+          const parsed = JSON.parse(c[0]);
+          return parsed.prerequisites !== undefined;
+        } catch {
+          return false;
+        }
+      });
+      expect(jsonCall).toBeTruthy();
+      expect(JSON.parse(jsonCall[0]).prerequisites).toHaveLength(0);
+    });
+  });
+});