@dommaker/harness 0.13.0 → 0.13.2

package/src/knowledge/__tests__/reference-tracker.test.ts

@@ -0,0 +1,129 @@
+/**
+ * ReferenceTracker 测试
+ */
+
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/globals';
+import { KnowledgeStore } from '../store';
+import { ReferenceTracker } from '../reference-tracker';
+import type { KnowledgeEntry } from '../types';
+import * as fs from 'fs';
+import * as path from 'path';
+
+describe('ReferenceTracker', () => {
+  const tempDir = path.join(process.cwd(), 'temp-test-refs');
+  let store: KnowledgeStore;
+  let tracker: ReferenceTracker;
+
+  const makeEntry = (overrides?: Partial<KnowledgeEntry>): KnowledgeEntry => ({
+    id: 'DEC-001',
+    type: 'decision',
+    title: 'Test Decision',
+    content: '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 });
+    tracker = new ReferenceTracker(store, tempDir);
+  });
+
+  describe('record', () => {
+    it('should append a reference record', () => {
+      tracker.record('decision-1', ['entry-1', 'entry-2']);
+      const filePath = path.join(tempDir, 'references.jsonl');
+      const content = fs.readFileSync(filePath, 'utf-8');
+      expect(content).toContain('decision-1');
+      expect(content).toContain('entry-1');
+    });
+
+    it('should append multiple records', () => {
+      tracker.record('decision-1', ['entry-1']);
+      tracker.record('decision-2', ['entry-2']);
+      const filePath = path.join(tempDir, 'references.jsonl');
+      const lines = fs.readFileSync(filePath, 'utf-8').split('\n').filter(Boolean);
+      expect(lines).toHaveLength(2);
+    });
+  });
+
+  describe('getReferencesForEntry', () => {
+    it('should return decisions referencing an entry', () => {
+      tracker.record('decision-1', ['entry-1', 'entry-2']);
+      tracker.record('decision-2', ['entry-2', 'entry-3']);
+
+      const refs = tracker.getReferencesForEntry('entry-2');
+      expect(refs).toEqual(['decision-1', 'decision-2']);
+    });
+
+    it('should return empty array for unreferenced entry', () => {
+      tracker.record('decision-1', ['entry-1']);
+      expect(tracker.getReferencesForEntry('entry-999')).toEqual([]);
+    });
+  });
+
+  describe('getReferencesForDecision', () => {
+    it('should return entries referenced by a decision', () => {
+      tracker.record('decision-1', ['entry-1', 'entry-2']);
+      const entries = tracker.getReferencesForDecision('decision-1');
+      expect(entries).toEqual(['entry-1', 'entry-2']);
+    });
+
+    it('should return empty array for unknown decision', () => {
+      expect(tracker.getReferencesForDecision('unknown')).toEqual([]);
+    });
+  });
+
+  describe('updateReferencedBy', () => {
+    it('should populate referencedBy on entries', () => {
+      store.save(makeEntry({ id: 'entry-1' }));
+      store.save(makeEntry({ id: 'entry-2' }));
+
+      tracker.record('decision-1', ['entry-1']);
+      tracker.record('decision-2', ['entry-1', 'entry-2']);
+      tracker.updateReferencedBy();
+
+      const e1 = store.get('entry-1');
+      const e2 = store.get('entry-2');
+      expect(e1!.referencedBy).toContain('decision-1');
+      expect(e1!.referencedBy).toContain('decision-2');
+      expect(e2!.referencedBy).toEqual(['decision-2']);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle corrupt references file gracefully', () => {
+      const filePath = path.join(tempDir, 'references.jsonl');
+      fs.writeFileSync(filePath, 'NOT VALID JSON\n', 'utf-8');
+      expect(tracker.getReferencesForEntry('any')).toEqual([]);
+    });
+
+    it('should return empty when file does not exist', () => {
+      expect(tracker.getReferencesForDecision('any')).toEqual([]);
+    });
+  });
+});

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

@@ -0,0 +1,238 @@
+/**
+ * KnowledgeStore 测试
+ */
+
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/globals';
+import { KnowledgeStore } from '../store';
+import type { KnowledgeEntry } from '../types';
+import * as fs from 'fs';
+import * as path from 'path';
+
+describe('KnowledgeStore', () => {
+  const tempDir = path.join(process.cwd(), 'temp-test-knowledge');
+  let store: KnowledgeStore;
+
+  const makeEntry = (overrides?: Partial<KnowledgeEntry>): KnowledgeEntry => ({
+    id: 'DEC-001',
+    type: 'decision',
+    title: 'Test Decision',
+    content: 'This is a test decision.',
+    maturity: 'draft',
+    layer: 'project',
+    created: '2026-05-01T00:00:00.000Z',
+    lastReferenced: '',
+    contributors: [],
+    projects: ['test-project'],
+    tags: ['test'],
+    applicablePhases: ['ARCHITECT'],
+    sourceReferences: [],
+    referencedBy: [],
+    ...overrides,
+  });
+
+  beforeAll(() => {
+    fs.mkdirSync(tempDir, { recursive: true });
+  });
+
+  afterAll(() => {
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  beforeEach(() => {
+    // Clean the temp dir before each test
+    const files = fs.readdirSync(tempDir);
+    for (const f of files) {
+      const p = path.join(tempDir, f);
+      const stat = fs.statSync(p);
+      if (stat.isDirectory()) {
+        fs.rmSync(p, { recursive: true, force: true });
+      } else {
+        fs.unlinkSync(p);
+      }
+    }
+    store = new KnowledgeStore({ baseDir: tempDir });
+  });
+
+  describe('save and get', () => {
+    it('should save and retrieve an entry', () => {
+      const entry = makeEntry();
+      store.save(entry);
+      const retrieved = store.get('DEC-001');
+      expect(retrieved).toBeDefined();
+      expect(retrieved!.id).toBe('DEC-001');
+      expect(retrieved!.title).toBe('Test Decision');
+      expect(retrieved!.content).toBe('This is a test decision.');
+    });
+
+    it('should return undefined for non-existent entry', () => {
+      expect(store.get('NON-EXISTENT')).toBeUndefined();
+    });
+
+    it('should preserve all fields through save/load cycle', () => {
+      const entry = makeEntry({
+        contributors: ['alice', 'bob'],
+        tags: ['arch', 'db'],
+        applicablePhases: ['ANALYSE_TECH', 'ARCHITECT'],
+        sourceReferences: [{ workflow: 'test-flow', step: 'step-1', timestamp: '2026-05-01' }],
+      });
+      store.save(entry);
+      const retrieved = store.get('DEC-001');
+      expect(retrieved!.contributors).toEqual(['alice', 'bob']);
+      expect(retrieved!.tags).toEqual(['arch', 'db']);
+      expect(retrieved!.applicablePhases).toEqual(['ANALYSE_TECH', 'ARCHITECT']);
+      expect(retrieved!.sourceReferences).toHaveLength(1);
+    });
+  });
+
+  describe('list', () => {
+    it('should list all entries', () => {
+      store.save(makeEntry({ id: 'DEC-001' }));
+      store.save(makeEntry({ id: 'DEC-002', title: 'Second' }));
+      const list = store.list();
+      expect(list).toHaveLength(2);
+    });
+
+    it('should filter by type', () => {
+      store.save(makeEntry({ id: 'DEC-001', type: 'decision' }));
+      store.save(makeEntry({ id: 'PIT-001', type: 'pitfall', title: 'Pitfall' }));
+      const list = store.list({ types: ['decision'] });
+      expect(list).toHaveLength(1);
+      expect(list[0].type).toBe('decision');
+    });
+
+    it('should filter by maturity', () => {
+      store.save(makeEntry({ id: 'DEC-001', maturity: 'draft' }));
+      store.save(makeEntry({ id: 'DEC-002', maturity: 'proven', title: 'Proven' }));
+      const list = store.list({ maturity: ['proven'] });
+      expect(list).toHaveLength(1);
+      expect(list[0].maturity).toBe('proven');
+    });
+
+    it('should exclude archived by default', () => {
+      store.save(makeEntry({ id: 'DEC-001', maturity: 'draft' }));
+      store.save(makeEntry({ id: 'DEC-002', maturity: 'archived', title: 'Archived' }));
+      const list = store.list();
+      expect(list).toHaveLength(1);
+    });
+
+    it('should include archived when excludeArchived is false', () => {
+      store.save(makeEntry({ id: 'DEC-001', maturity: 'draft' }));
+      store.save(makeEntry({ id: 'DEC-002', maturity: 'archived', title: 'Archived' }));
+      const list = store.list({ excludeArchived: false });
+      expect(list).toHaveLength(2);
+    });
+  });
+
+  describe('delete', () => {
+    it('should delete an entry', () => {
+      store.save(makeEntry());
+      expect(store.delete('DEC-001')).toBe(true);
+      expect(store.get('DEC-001')).toBeUndefined();
+    });
+
+    it('should return false for non-existent entry', () => {
+      expect(store.delete('NON-EXISTENT')).toBe(false);
+    });
+  });
+
+  describe('update', () => {
+    it('should update specific fields', () => {
+      store.save(makeEntry());
+      const updated = store.update('DEC-001', { title: 'Updated Title', maturity: 'verified' });
+      expect(updated!.title).toBe('Updated Title');
+      expect(updated!.maturity).toBe('verified');
+      expect(updated!.content).toBe('This is a test decision.'); // unchanged
+    });
+
+    it('should return undefined for non-existent entry', () => {
+      expect(store.update('NON-EXISTENT', { title: 'x' })).toBeUndefined();
+    });
+  });
+
+  describe('rebuildIndex', () => {
+    it('should rebuild index from files', () => {
+      store.save(makeEntry({ id: 'DEC-001' }));
+      store.save(makeEntry({ id: 'DEC-002', title: 'Second' }));
+      store.rebuildIndex();
+      const list = store.list();
+      expect(list).toHaveLength(2);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should create directory if it does not exist', () => {
+      const newDir = path.join(process.cwd(), 'temp-test-knowledge-nested', 'sub', 'deep');
+      const s = new KnowledgeStore({ baseDir: newDir });
+      expect(fs.existsSync(newDir)).toBe(true);
+      fs.rmSync(path.join(process.cwd(), 'temp-test-knowledge-nested'), { recursive: true, force: true });
+    });
+
+    it('should handle corrupt index.json gracefully', () => {
+      const indexPath = path.join(tempDir, 'index.json');
+      fs.writeFileSync(indexPath, 'NOT VALID JSON{{{', 'utf-8');
+      // Should not throw, returns empty list
+      const list = store.list();
+      expect(list).toHaveLength(0);
+    });
+
+    it('should fallback to indexToEntry when file is missing', () => {
+      store.save(makeEntry());
+      // Delete the .md file but leave index entry
+      const mdFiles = fs.readdirSync(tempDir).filter(f => f.endsWith('.md'));
+      for (const f of mdFiles) {
+        fs.unlinkSync(path.join(tempDir, f));
+      }
+      const list = store.list();
+      expect(list).toHaveLength(1);
+      expect(list[0].content).toBe(''); // indexToEntry returns empty content
+    });
+
+    it('should handle unreadable file gracefully', () => {
+      // Write a valid entry
+      store.save(makeEntry());
+      // Overwrite with content that fails to parse (no frontmatter)
+      const mdPath = path.join(tempDir, 'decision-DEC-001.md');
+      fs.writeFileSync(mdPath, 'no frontmatter here', 'utf-8');
+      const result = store.get('DEC-001');
+      expect(result).toBeUndefined();
+    });
+
+    it('should filter by layer', () => {
+      store.save(makeEntry({ id: 'DEC-001', layer: 'project' }));
+      store.save(makeEntry({ id: 'DEC-002', layer: 'team', title: 'Team' }));
+      const list = store.list({ layers: ['team'] });
+      expect(list).toHaveLength(1);
+      expect(list[0].layer).toBe('team');
+    });
+
+    it('should filter by tags', () => {
+      store.save(makeEntry({ id: 'DEC-001', tags: ['arch', 'db'] }));
+      store.save(makeEntry({ id: 'DEC-002', tags: ['perf'], title: 'Perf' }));
+      const list = store.list({ tags: ['arch'] });
+      expect(list).toHaveLength(1);
+    });
+
+    it('should filter by applicablePhases', () => {
+      store.save(makeEntry({ id: 'DEC-001', applicablePhases: ['ARCHITECT'] }));
+      store.save(makeEntry({ id: 'DEC-002', applicablePhases: ['IMPLEMENT'], title: 'Impl' }));
+      const list = store.list({ applicablePhases: ['IMPLEMENT'] });
+      expect(list).toHaveLength(1);
+    });
+
+    it('should save and read back decayAt field', () => {
+      store.save(makeEntry({ decayAt: '2027-01-01' }));
+      const retrieved = store.get('DEC-001');
+      expect(retrieved!.decayAt).toBe('2027-01-01');
+    });
+
+    it('should exclude decayAt when not set', () => {
+      store.save(makeEntry());
+      const retrieved = store.get('DEC-001');
+      expect(retrieved!.decayAt).toBeUndefined();
+    });
+  });
+});

package/src/knowledge/doctor.ts

@@ -0,0 +1,104 @@
+/**
+ * Knowledge Doctor — 知识库健康评分
+ *
+ * 计算整体健康分数，检测需要关注的问题。
+ * MonitorAgent 周期性调用，低于 60 分触发 Triage 告警。
+ */
+
+import { KnowledgeStore } from './store';
+import { KnowledgeLinter } from './lint';
+import type { LintIssue } from './types';
+
+export interface HealthDetail {
+  category: string;
+  score: number;
+  message: string;
+}
+
+export interface HealthReport {
+  score: number;
+  details: HealthDetail[];
+  totalEntries: number;
+  timestamp: string;
+}
+
+export class KnowledgeHealthScorer {
+  private store: KnowledgeStore;
+  private linter: KnowledgeLinter;
+
+  constructor(store: KnowledgeStore, linter: KnowledgeLinter) {
+    this.store = store;
+    this.linter = linter;
+  }
+
+  /**
+   * Calculate knowledge base health score (0-100).
+   *
+   * Scoring:
+   * - Start at 100
+   * - Orphans > 10% → -20
+   * - Outdated > 5% → -15
+   * - Duplicates > 5% → -25 (high weight)
+   * - Contradictions > 0 → -10 each
+   * - Index inconsistency → -30
+   */
+  healthScore(): HealthReport {
+    const entries = this.store.list({ excludeArchived: false });
+    const totalEntries = entries.length;
+    const report = this.linter.run(false); // don't autoFix, just report
+    const details: HealthDetail[] = [];
+    let penalty = 0;
+
+    if (totalEntries === 0) {
+      return { score: 100, details: [{ category: 'empty', score: 0, message: 'Knowledge base is empty' }], totalEntries: 0, timestamp: new Date().toISOString() };
+    }
+
+    // Orphans
+    const orphanCount = report.summary.orphan;
+    const orphanRate = orphanCount / totalEntries;
+    if (orphanRate > 0.1) {
+      penalty += 20;
+      details.push({ category: 'orphans', score: -20, message: `Orphan rate ${(orphanRate * 100).toFixed(0)}% (>10%): ${orphanCount}/${totalEntries}` });
+    }
+
+    // Outdated
+    const outdatedCount = report.summary.outdated;
+    const outdatedRate = outdatedCount / totalEntries;
+    if (outdatedRate > 0.05) {
+      penalty += 15;
+      details.push({ category: 'outdated', score: -15, message: `Outdated rate ${(outdatedRate * 100).toFixed(0)}% (>5%): ${outdatedCount}/${totalEntries}` });
+    }
+
+    // Duplicates (high weight)
+    const dupCount = report.summary.duplicate;
+    const dupRate = dupCount / totalEntries;
+    if (dupRate > 0.05) {
+      penalty += 25;
+      details.push({ category: 'duplicates', score: -25, message: `Duplicate rate ${(dupRate * 100).toFixed(0)}% (>5%): ${dupCount}/${totalEntries}` });
+    }
+
+    // Contradictions
+    const contradictionCount = report.summary.contradiction;
+    if (contradictionCount > 0) {
+      const contradictionPenalty = Math.min(contradictionCount * 10, 30);
+      penalty += contradictionPenalty;
+      details.push({ category: 'contradictions', score: -contradictionPenalty, message: `${contradictionCount} contradictions found` });
+    }
+
+    // Index inconsistency
+    const indexCount = report.summary.index_inconsistent;
+    if (indexCount > 0) {
+      penalty += 30;
+      details.push({ category: 'index', score: -30, message: `Index inconsistency: ${indexCount} issues` });
+    }
+
+    const score = Math.max(0, 100 - penalty);
+
+    return {
+      score,
+      details,
+      totalEntries,
+      timestamp: new Date().toISOString(),
+    };
+  }
+}