@dommaker/harness 0.13.0 → 0.13.2

package/src/knowledge/__tests__/lint.test.ts

@@ -0,0 +1,401 @@
+/**
+ * KnowledgeLinter 测试
+ */
+
+import { KnowledgeLinter } from '../lint';
+import { KnowledgeStore } from '../store';
+import { ReferenceTracker } from '../reference-tracker';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+describe('KnowledgeLinter', () => {
+  let store: KnowledgeStore;
+  let tracker: ReferenceTracker;
+  let linter: KnowledgeLinter;
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'linter-test-'));
+    store = new KnowledgeStore({ baseDir: path.join(tmpDir, 'knowledge') });
+    tracker = new ReferenceTracker(store);
+    linter = new KnowledgeLinter(store, tracker);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function saveEntry(overrides: any = {}) {
+    store.save({
+      id: overrides.id || `test-${Math.random().toString(36).slice(2, 6)}`,
+      type: 'decision',
+      title: 'Test Decision',
+      content: 'Some content',
+      maturity: 'draft',
+      layer: 'project',
+      created: new Date().toISOString(),
+      lastReferenced: '',
+      contributors: [],
+      projects: [],
+      tags: [],
+      applicablePhases: [],
+      sourceReferences: [],
+      referencedBy: [],
+      ...overrides,
+    });
+  }
+
+  describe('run', () => {
+    it('应该返回空报告当无条目', () => {
+      const report = linter.run();
+      expect(report.totalEntries).toBe(0);
+      expect(report.issues.length).toBe(0);
+      expect(report.fixed).toBe(0);
+    });
+
+    it('应该检测所有问题类型', () => {
+      // 孤儿条目
+      saveEntry({ id: 'orphan-1', title: 'Orphan', maturity: 'draft', contributors: [], projects: [] });
+      // 过时条目
+      saveEntry({
+        id: 'outdated-1',
+        title: 'Old',
+        maturity: 'draft',
+        created: '2020-01-01T00:00:00.000Z',
+        lastReferenced: '',
+      });
+      // 重复条目
+      saveEntry({ id: 'dup-1', title: 'Same Title', type: 'decision' });
+      saveEntry({ id: 'dup-2', title: 'Same Title', type: 'decision' });
+
+      const report = linter.run();
+      expect(report.summary.orphan).toBeGreaterThan(0);
+      expect(report.summary.outdated).toBeGreaterThan(0);
+      expect(report.summary.duplicate).toBeGreaterThan(0);
+    });
+  });
+
+  describe('checkIndexConsistency', () => {
+    it('应该检测索引中有但文件不存在的条目', () => {
+      saveEntry({ id: 'entry-1' });
+      // 手动删除文件但保留索引
+      const files = fs.readdirSync(path.join(tmpDir, 'knowledge'));
+      for (const f of files) {
+        if (f.endsWith('.md')) {
+          fs.unlinkSync(path.join(tmpDir, 'knowledge', f));
+        }
+      }
+
+      const report = linter.run();
+      expect(report.summary.index_inconsistent).toBeGreaterThan(0);
+      expect(report.issues.some(i => i.description.includes('无对应文件'))).toBe(true);
+    });
+
+    it('应该检测文件存在但不在索引中的条目', () => {
+      // 先保存条目（会同时创建文件和索引）
+      saveEntry({ id: 'entry-2' });
+      // 手动删除索引中该条目，但保留文件
+      const indexPath = path.join(tmpDir, 'knowledge', 'index.json');
+      const index = JSON.parse(fs.readFileSync(indexPath, 'utf-8'));
+      const filtered = index.filter((e: any) => e.id !== 'entry-2');
+      fs.writeFileSync(indexPath, JSON.stringify(filtered), 'utf-8');
+
+      const report = linter.run();
+      expect(report.summary.index_inconsistent).toBeGreaterThan(0);
+      expect(report.issues.some(i => i.description.includes('不在索引中'))).toBe(true);
+    });
+  });
+
+  describe('checkOrphans', () => {
+    it('应该检测孤儿条目', () => {
+      saveEntry({ id: 'orphan-1', maturity: 'draft', contributors: [], projects: [] });
+      const issues = linter.checkOrphans(store.list({ excludeArchived: false }));
+      expect(issues.some(i => i.type === 'orphan')).toBe(true);
+    });
+
+    it('不应该标记有贡献者的条目', () => {
+      saveEntry({ id: 'not-orphan', contributors: ['user-1'], projects: [] });
+      const issues = linter.checkOrphans(store.list({ excludeArchived: false }));
+      expect(issues.filter(i => i.entryId === 'not-orphan').length).toBe(0);
+    });
+
+    it('不应该标记 archived 条目', () => {
+      saveEntry({ id: 'archived-1', maturity: 'archived', contributors: [], projects: [] });
+      const issues = linter.checkOrphans(store.list({ excludeArchived: false }));
+      expect(issues.filter(i => i.entryId === 'archived-1').length).toBe(0);
+    });
+  });
+
+  describe('checkOutdated', () => {
+    it('应该检测超过 6 个月未引用的 draft', () => {
+      saveEntry({
+        id: 'old-draft',
+        maturity: 'draft',
+        created: '2020-01-01T00:00:00.000Z',
+        lastReferenced: '',
+      });
+      const issues = linter.checkOutdated(store.list({ excludeArchived: false }));
+      expect(issues.some(i => i.type === 'outdated')).toBe(true);
+    });
+
+    it('不应该标记最近引用的条目', () => {
+      saveEntry({
+        id: 'recent',
+        maturity: 'draft',
+        lastReferenced: new Date().toISOString(),
+      });
+      const issues = linter.checkOutdated(store.list({ excludeArchived: false }));
+      expect(issues.filter(i => i.entryId === 'recent').length).toBe(0);
+    });
+
+    it('不应该标记 proven 条目即使很久未引用', () => {
+      saveEntry({
+        id: 'old-proven',
+        maturity: 'proven',
+        created: '2020-01-01T00:00:00.000Z',
+        lastReferenced: '',
+      });
+      const issues = linter.checkOutdated(store.list({ excludeArchived: false }));
+      expect(issues.filter(i => i.entryId === 'old-proven').length).toBe(0);
+    });
+
+    it('应该跳过 archived 条目', () => {
+      saveEntry({
+        id: 'archived-outdated',
+        maturity: 'archived',
+        created: '2020-01-01T00:00:00.000Z',
+        lastReferenced: '',
+      });
+      const issues = linter.checkOutdated(store.list({ excludeArchived: false }));
+      expect(issues.filter(i => i.entryId === 'archived-outdated').length).toBe(0);
+    });
+  });
+
+  describe('checkDuplicates', () => {
+    it('应该检测同类型同标题的重复条目', () => {
+      saveEntry({ id: 'dup-1', title: 'Same', type: 'decision' });
+      saveEntry({ id: 'dup-2', title: 'Same', type: 'decision' });
+      const issues = linter.checkDuplicates(store.list({ excludeArchived: false }));
+      expect(issues.filter(i => i.type === 'duplicate').length).toBe(2);
+    });
+
+    it('不应该标记不同类型同标题的条目', () => {
+      saveEntry({ id: 'a-1', title: 'Same', type: 'decision' });
+      saveEntry({ id: 'b-1', title: 'Same', type: 'guideline' });
+      const issues = linter.checkDuplicates(store.list({ excludeArchived: false }));
+      expect(issues.filter(i => i.type === 'duplicate').length).toBe(0);
+    });
+
+    it('应该忽略大小写', () => {
+      saveEntry({ id: 'c-1', title: 'My Title', type: 'decision' });
+      saveEntry({ id: 'c-2', title: 'my title', type: 'decision' });
+      const issues = linter.checkDuplicates(store.list({ excludeArchived: false }));
+      expect(issues.filter(i => i.type === 'duplicate').length).toBe(2);
+    });
+
+    it('应该跳过 archived 条目', () => {
+      saveEntry({ id: 'd-1', title: 'Archived Dup', type: 'decision', maturity: 'archived' });
+      saveEntry({ id: 'd-2', title: 'Archived Dup', type: 'decision', maturity: 'archived' });
+      const issues = linter.checkDuplicates(store.list({ excludeArchived: false }));
+      expect(issues.filter(i => i.type === 'duplicate').length).toBe(0);
+    });
+  });
+
+  describe('checkContradictions', () => {
+    it('应该检测同标签成熟度差异大的条目', () => {
+      saveEntry({ id: 'high-1', title: 'High', maturity: 'proven', tags: ['auth'] });
+      saveEntry({ id: 'low-1', title: 'Low', maturity: 'draft', tags: ['auth'] });
+      const issues = linter.checkContradictions(store.list({ excludeArchived: false }));
+      expect(issues.some(i => i.type === 'contradiction')).toBe(true);
+    });
+
+    it('不应该标记同成熟度的条目', () => {
+      saveEntry({ id: 'eq-1', title: 'A', maturity: 'verified', tags: ['db'] });
+      saveEntry({ id: 'eq-2', title: 'B', maturity: 'verified', tags: ['db'] });
+      const issues = linter.checkContradictions(store.list({ excludeArchived: false }));
+      expect(issues.filter(i => i.type === 'contradiction').length).toBe(0);
+    });
+
+    it('应该忽略无标签的条目', () => {
+      saveEntry({ id: 'no-tag-1', maturity: 'proven', tags: [] });
+      saveEntry({ id: 'no-tag-2', maturity: 'draft', tags: [] });
+      const issues = linter.checkContradictions(store.list({ excludeArchived: false }));
+      expect(issues.filter(i => i.type === 'contradiction').length).toBe(0);
+    });
+
+    it('应该跳过 archived 条目', () => {
+      saveEntry({ id: 'archived-contra', maturity: 'archived', tags: ['auth'], type: 'decision' });
+      saveEntry({ id: 'active-contra', maturity: 'proven', tags: ['auth'], type: 'decision' });
+      const issues = linter.checkContradictions(store.list({ excludeArchived: false }));
+      expect(issues.filter(i => i.entryId === 'archived-contra').length).toBe(0);
+    });
+  });
+
+  describe('validateEntry', () => {
+    it('rejects content shorter than 20 characters', () => {
+      const issues = linter.validateEntry({ title: 'Short', content: 'tiny', tags: [], type: 'decision' });
+      expect(issues).toHaveLength(1);
+      expect(issues[0].type).toBe('orphan');
+      expect(issues[0].severity).toBe('high');
+    });
+
+    it('flags vague Chinese titles', () => {
+      const issues = linter.validateEntry({
+        title: '错误',
+        content: 'This is a sufficiently long content for the test.',
+        tags: [],
+        type: 'decision',
+      });
+      expect(issues).toHaveLength(1);
+      expect(issues[0].type).toBe('contradiction');
+    });
+
+    it('flags vague English titles', () => {
+      const issues = linter.validateEntry({
+        title: 'bug',
+        content: 'This is a sufficiently long content for the test to pass length check.',
+        tags: [],
+        type: 'decision',
+      });
+      expect(issues).toHaveLength(1);
+      expect(issues[0].severity).toBe('medium');
+    });
+
+    it('passes valid entries without issues', () => {
+      const issues = linter.validateEntry({
+        title: 'Specific Root Cause Analysis for performance',
+        content: 'This is a sufficiently long content for the test to pass all checks.',
+        tags: ['performance'],
+        type: 'decision',
+      });
+      expect(issues).toHaveLength(0);
+    });
+
+    it('detects contradictions with proven entries sharing 2+ tags', () => {
+      saveEntry({
+        id: 'proven-validate',
+        title: 'Proven Fact',
+        maturity: 'proven',
+        tags: ['database', 'performance', 'optimization'],
+      });
+
+      const issues = linter.validateEntry({
+        title: 'New Claim',
+        content: 'This is a valid length content for testing purposes here.',
+        tags: ['database', 'performance', 'indexing'],
+        type: 'decision',
+      });
+      expect(issues).toHaveLength(1);
+      expect(issues[0].type).toBe('contradiction');
+    });
+
+    it('does not detect contradiction when sharing only 1 tag', () => {
+      saveEntry({
+        id: 'proven-single-tag',
+        title: 'Proven',
+        maturity: 'proven',
+        tags: ['database'],
+      });
+
+      const issues = linter.validateEntry({
+        title: 'New Claim',
+        content: 'This is a valid length content for testing purposes.',
+        tags: ['database', 'caching'],
+        type: 'decision',
+      });
+      expect(issues.filter(i => i.type === 'contradiction')).toHaveLength(0);
+    });
+
+    it('detects exact title duplicates', () => {
+      saveEntry({ id: 'existing-entry', title: 'Unique Title', maturity: 'verified' });
+
+      const issues = linter.validateEntry({
+        title: 'Unique Title',
+        content: 'This is a sufficiently long content for the duplicate check test case.',
+        tags: [],
+        type: 'decision',
+      });
+      expect(issues.filter(i => i.type === 'duplicate')).toHaveLength(1);
+    });
+
+    it('skips non-proven entries in contradiction check', () => {
+      saveEntry({ id: 'non-proven', title: 'Non Proven', maturity: 'draft', tags: ['auth'] });
+
+      const issues = linter.validateEntry({
+        title: 'New Claim Check',
+        content: 'This is a sufficiently long content for testing here.',
+        tags: ['auth'],
+        type: 'decision',
+      });
+      expect(issues.filter(i => i.type === 'contradiction')).toHaveLength(0);
+    });
+
+    it('skips different type in contradiction check', () => {
+      saveEntry({ id: 'proven-diff-type', title: 'Proven Fact', maturity: 'proven', tags: ['database'], type: 'guideline' });
+
+      const issues = linter.validateEntry({
+        title: 'New Database Claim',
+        content: 'This is a sufficiently long content for testing purposes here.',
+        tags: ['database'],
+        type: 'decision',
+      });
+      expect(issues.filter(i => i.type === 'contradiction')).toHaveLength(0);
+    });
+
+    it('skips entry when title matches existing id', () => {
+      saveEntry({ id: 'New Feature Implementation', title: 'Existing Feature', maturity: 'verified' });
+
+      const issues = linter.validateEntry({
+        title: 'New Feature Implementation',
+        content: 'This is a sufficiently long content for testing purposes here.',
+        tags: [],
+        type: 'decision',
+      });
+      // Should not produce duplicate issue by matching against itself via id
+      expect(issues.filter(i => i.type === 'duplicate')).toHaveLength(0);
+    });
+
+    it('detects title containment similarity', () => {
+      saveEntry({ id: 'base-entry', title: 'My Feature', maturity: 'verified' });
+
+      const issues = linter.validateEntry({
+        title: 'Add My Feature Implementation',
+        content: 'This is a sufficiently long content for the containment check test case.',
+        tags: [],
+        type: 'decision',
+      });
+      expect(issues.some(i => i.type === 'duplicate')).toBe(true);
+    });
+  });
+
+  describe('autoFix', () => {
+    it('应该修复索引不一致', () => {
+      saveEntry({ id: 'entry-1' });
+      // 删除文件
+      const files = fs.readdirSync(path.join(tmpDir, 'knowledge'));
+      for (const f of files) {
+        if (f.endsWith('.md')) {
+          fs.unlinkSync(path.join(tmpDir, 'knowledge', f));
+        }
+      }
+
+      const report = linter.run(true);
+      expect(report.fixed).toBeGreaterThan(0);
+    });
+
+    it('应该归档过时条目', () => {
+      saveEntry({
+        id: 'old-1',
+        maturity: 'draft',
+        created: '2020-01-01T00:00:00.000Z',
+        lastReferenced: '',
+      });
+
+      const report = linter.run(true);
+      expect(report.fixed).toBeGreaterThan(0);
+      const entry = store.get('old-1');
+      expect(entry?.maturity).toBe('archived');
+    });
+  });
+});

package/src/knowledge/__tests__/query.test.ts

@@ -0,0 +1,185 @@
+/**
+ * KnowledgeQuery 测试
+ */
+
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/globals';
+import { KnowledgeStore } from '../store';
+import { KnowledgeQuery } from '../query';
+import type { KnowledgeEntry, QueryBudget } from '../types';
+import * as fs from 'fs';
+import * as path from 'path';
+
+describe('KnowledgeQuery', () => {
+  const tempDir = path.join(process.cwd(), 'temp-test-query');
+  let store: KnowledgeStore;
+  let query: KnowledgeQuery;
+
+  const makeEntry = (overrides?: Partial<KnowledgeEntry>): KnowledgeEntry => ({
+    id: 'DEC-001',
+    type: 'decision',
+    title: 'Test Decision',
+    content: 'Short content.',
+    maturity: 'draft',
+    layer: 'project',
+    created: '2026-05-01T00:00:00.000Z',
+    lastReferenced: '',
+    contributors: [],
+    projects: [],
+    tags: [],
+    applicablePhases: [],
+    sourceReferences: [],
+    referencedBy: [],
+    ...overrides,
+  });
+
+  beforeAll(() => {
+    fs.mkdirSync(tempDir, { recursive: true });
+  });
+
+  afterAll(() => {
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  beforeEach(() => {
+    const files = fs.readdirSync(tempDir);
+    for (const f of files) {
+      fs.unlinkSync(path.join(tempDir, f));
+    }
+    store = new KnowledgeStore({ baseDir: tempDir });
+    query = new KnowledgeQuery(store);
+  });
+
+  describe('query', () => {
+    it('should return entries matching focus types', () => {
+      store.save(makeEntry({ id: 'DEC-001', type: 'decision' }));
+      store.save(makeEntry({ id: 'PIT-001', type: 'pitfall', title: 'Pitfall' }));
+
+      const budget: QueryBudget = {
+        phase: 'ARCHITECT',
+        maxTokens: 10000,
+        maxEntries: 10,
+        focusTypes: ['decision'],
+      };
+
+      const result = query.query(budget);
+      expect(result.entries).toHaveLength(1);
+      expect(result.entries[0].type).toBe('decision');
+    });
+
+    it('should sort by maturity descending', () => {
+      store.save(makeEntry({ id: 'DEC-001', maturity: 'draft' }));
+      store.save(makeEntry({ id: 'DEC-002', maturity: 'proven', title: 'Proven' }));
+      store.save(makeEntry({ id: 'DEC-003', maturity: 'verified', title: 'Verified' }));
+
+      const budget: QueryBudget = {
+        phase: 'test',
+        maxTokens: 100000,
+        maxEntries: 10,
+        focusTypes: ['decision'],
+      };
+
+      const result = query.query(budget);
+      expect(result.entries[0].maturity).toBe('proven');
+      expect(result.entries[1].maturity).toBe('verified');
+      expect(result.entries[2].maturity).toBe('draft');
+    });
+
+    it('should respect maxEntries budget', () => {
+      for (let i = 1; i <= 5; i++) {
+        store.save(makeEntry({ id: `DEC-${String(i).padStart(3, '0')}`, title: `D${i}` }));
+      }
+
+      const budget: QueryBudget = {
+        phase: 'test',
+        maxTokens: 100000,
+        maxEntries: 2,
+        focusTypes: ['decision'],
+      };
+
+      const result = query.query(budget);
+      expect(result.entries).toHaveLength(2);
+      expect(result.truncated).toBe(true);
+    });
+
+    it('should respect maxTokens budget', () => {
+      store.save(makeEntry({
+        id: 'DEC-001',
+        content: 'A'.repeat(1000), // ~250 tokens
+      }));
+      store.save(makeEntry({
+        id: 'DEC-002',
+        content: 'B'.repeat(1000),
+        title: 'Second',
+      }));
+
+      const budget: QueryBudget = {
+        phase: 'test',
+        maxTokens: 300, // only room for one entry
+        maxEntries: 10,
+        focusTypes: ['decision'],
+      };
+
+      const result = query.query(budget);
+      expect(result.entries).toHaveLength(1);
+      expect(result.truncated).toBe(true);
+    });
+
+    it('should cache results within TTL', () => {
+      store.save(makeEntry());
+
+      const budget: QueryBudget = {
+        phase: 'test',
+        maxTokens: 10000,
+        maxEntries: 10,
+        focusTypes: ['decision'],
+      };
+
+      const first = query.query(budget);
+      expect(first.fromCache).toBe(false);
+
+      const second = query.query(budget);
+      expect(second.fromCache).toBe(true);
+    });
+  });
+
+  describe('estimateTokens', () => {
+    it('should estimate CJK characters at ~2 tokens', () => {
+      const tokens = query.estimateTokens('你好世界'); // 4 CJK chars
+      expect(tokens).toBe(8);
+    });
+
+    it('should estimate ASCII characters at ~0.25 tokens', () => {
+      const tokens = query.estimateTokens('hello'); // 5 ASCII chars
+      expect(tokens).toBe(2); // ceil(1.25)
+    });
+
+    it('should handle mixed content', () => {
+      const tokens = query.estimateTokens('hello你好');
+      // 5 ASCII * 0.25 = 1.25, 2 CJK * 2 = 4, total = 5.25, ceil = 6
+      expect(tokens).toBe(6);
+    });
+  });
+
+  describe('clearCache', () => {
+    it('should clear the cache', () => {
+      store.save(makeEntry());
+
+      const budget: QueryBudget = {
+        phase: 'test',
+        maxTokens: 10000,
+        maxEntries: 10,
+        focusTypes: ['decision'],
+      };
+
+      query.query(budget);
+      query.clearCache();
+
+      const result = query.query(budget);
+      expect(result.fromCache).toBe(false);
+    });
+  });
+});