@dommaker/harness 0.13.3 → 0.16.0

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

@@ -3,7 +3,7 @@
  */
 
 import { KnowledgeLinter } from '../lint';
-import { KnowledgeStore } from '../store';
+import { FileKnowledgeStore as KnowledgeStore } from '../store';
 import { ReferenceTracker } from '../reference-tracker';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -42,6 +42,9 @@ describe('KnowledgeLinter', () => {
       applicablePhases: [],
       sourceReferences: [],
       referencedBy: [],
+      executionResults: [],
+      consumptionMode: 'reference',
+      origin: 'agent',
       ...overrides,
     });
   }
@@ -397,5 +400,53 @@ describe('KnowledgeLinter', () => {
       const entry = store.get('old-1');
       expect(entry?.maturity).toBe('archived');
     });
+
+    it('A3: 应该归档重复条目，保留最新，合并 sourceReferences', () => {
+      // Create 3 entries with same title/type, different lastReferenced dates
+      saveEntry({
+        id: 'dup-old',
+        title: 'Duplicate Title',
+        type: 'decision',
+        lastReferenced: '2026-01-01T00:00:00.000Z',
+        sourceReferences: [{ workflow: 'old-wf', timestamp: '2026-01-01T00:00:00.000Z' }],
+      });
+      saveEntry({
+        id: 'dup-mid',
+        title: 'Duplicate Title',
+        type: 'decision',
+        lastReferenced: '2026-03-01T00:00:00.000Z',
+        sourceReferences: [{ workflow: 'mid-wf', timestamp: '2026-03-01T00:00:00.000Z' }],
+      });
+      saveEntry({
+        id: 'dup-new',
+        title: 'Duplicate Title',
+        type: 'decision',
+        lastReferenced: '2026-05-01T00:00:00.000Z',
+        sourceReferences: [{ workflow: 'new-wf', timestamp: '2026-05-01T00:00:00.000Z' }],
+      });
+
+      const report = linter.run(true);
+
+      // Should have fixed 2 duplicates (archived old and mid)
+      const dupFixes = report.issues.filter(i => i.type === 'duplicate');
+      expect(dupFixes.length).toBe(3); // all 3 reported as duplicates
+      expect(report.fixed).toBeGreaterThanOrEqual(2);
+
+      // Newest should be kept
+      const kept = store.get('dup-new');
+      expect(kept).toBeDefined();
+      expect(kept!.maturity).not.toBe('archived');
+
+      // Old and mid should be archived
+      expect(store.get('dup-old')!.maturity).toBe('archived');
+      expect(store.get('dup-mid')!.maturity).toBe('archived');
+
+      // SourceReferences from archived entries should be merged into kept entry
+      expect(kept!.sourceReferences.length).toBeGreaterThanOrEqual(3);
+      const workflows = kept!.sourceReferences.map(r => r.workflow);
+      expect(workflows).toContain('old-wf');
+      expect(workflows).toContain('mid-wf');
+      expect(workflows).toContain('new-wf');
+    });
   });
 });

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

@@ -0,0 +1,115 @@
+/**
+ * Knowledge Migration 测试
+ */
+
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/globals';
+import { migrateKnowledgeEntries } from '../migration';
+import * as fs from 'fs';
+import * as path from 'path';
+
+describe('migrateKnowledgeEntries', () => {
+  const tempDir = path.join(process.cwd(), 'temp-test-migration');
+
+  beforeAll(() => {
+    fs.mkdirSync(tempDir, { recursive: true });
+  });
+
+  afterAll(() => {
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  beforeEach(() => {
+    // Clean directory
+    for (const f of fs.readdirSync(tempDir)) {
+      fs.unlinkSync(path.join(tempDir, f));
+    }
+  });
+
+  function writeEntry(filename: string, meta: Record<string, unknown>, content = 'Body content') {
+    const frontmatter = Object.entries(meta)
+      .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+      .join('\n');
+    const raw = `---\n${frontmatter}\n---\n\n${content}`;
+    fs.writeFileSync(path.join(tempDir, filename), raw, 'utf-8');
+  }
+
+  function readMeta(filename: string): Record<string, unknown> {
+    const raw = fs.readFileSync(path.join(tempDir, filename), 'utf-8');
+    const match = raw.match(/^---\n([\s\S]*?)\n---/)!;
+    return JSON.parse(JSON.stringify(eval(`(${match[1].replace(/(\w+):/g, '"$1":').replace(/'/g, '"')})`)));
+  }
+
+  it('should add consumptionMode and origin to entries missing them', () => {
+    writeEntry('DEC-001.md', {
+      id: 'DEC-001', type: 'decision', title: 'Test', maturity: 'draft',
+      layer: 'project', created: '2026-05-01', lastReferenced: '',
+      contributors: [], projects: [], tags: [], applicablePhases: [],
+      sourceReferences: [], referencedBy: [], executionResults: [],
+    });
+
+    const result = migrateKnowledgeEntries(tempDir);
+    expect(result.total).toBe(1);
+    expect(result.migrated).toBe(1);
+    expect(result.skipped).toBe(0);
+    expect(result.errors).toHaveLength(0);
+
+    // Verify the file was updated
+    const raw = fs.readFileSync(path.join(tempDir, 'DEC-001.md'), 'utf-8');
+    expect(raw).toContain('consumptionMode');
+    expect(raw).toContain('origin');
+  });
+
+  it('should skip entries that already have both fields', () => {
+    writeEntry('DEC-002.md', {
+      id: 'DEC-002', type: 'decision', title: 'Test', maturity: 'draft',
+      layer: 'project', created: '2026-05-01', lastReferenced: '',
+      contributors: [], projects: [], tags: [], applicablePhases: [],
+      sourceReferences: [], referencedBy: [], executionResults: [],
+      consumptionMode: 'rule', origin: 'human',
+    });
+
+    const result = migrateKnowledgeEntries(tempDir);
+    expect(result.total).toBe(1);
+    expect(result.migrated).toBe(0);
+    expect(result.skipped).toBe(1);
+  });
+
+  it('should handle empty directory', () => {
+    const result = migrateKnowledgeEntries(path.join(tempDir, 'nonexistent'));
+    expect(result.total).toBe(0);
+    expect(result.migrated).toBe(0);
+  });
+
+  it('should handle non-markdown files gracefully', () => {
+    fs.writeFileSync(path.join(tempDir, 'index.json'), '{}', 'utf-8');
+    writeEntry('DEC-003.md', {
+      id: 'DEC-003', type: 'decision', title: 'Test', maturity: 'draft',
+      layer: 'project', created: '2026-05-01', lastReferenced: '',
+      contributors: [], projects: [], tags: [], applicablePhases: [],
+      sourceReferences: [], referencedBy: [], executionResults: [],
+    });
+
+    const result = migrateKnowledgeEntries(tempDir);
+    expect(result.total).toBe(1); // only .md files counted
+    expect(result.migrated).toBe(1);
+  });
+
+  it('should be idempotent', () => {
+    writeEntry('DEC-004.md', {
+      id: 'DEC-004', type: 'decision', title: 'Test', maturity: 'draft',
+      layer: 'project', created: '2026-05-01', lastReferenced: '',
+      contributors: [], projects: [], tags: [], applicablePhases: [],
+      sourceReferences: [], referencedBy: [], executionResults: [],
+    });
+
+    const first = migrateKnowledgeEntries(tempDir);
+    const second = migrateKnowledgeEntries(tempDir);
+    expect(first.migrated).toBe(1);
+    expect(second.migrated).toBe(0);
+    expect(second.skipped).toBe(1);
+  });
+});

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

@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/globals';
-import { KnowledgeStore } from '../store';
+import { FileKnowledgeStore as KnowledgeStore } from '../store';
 import { KnowledgeQuery } from '../query';
 import type { KnowledgeEntry, QueryBudget } from '../types';
 import * as fs from 'fs';
@@ -29,6 +29,9 @@ describe('KnowledgeQuery', () => {
     applicablePhases: [],
     sourceReferences: [],
     referencedBy: [],
+    executionResults: [],
+    consumptionMode: 'reference',
+    origin: 'agent',
     ...overrides,
   });
 
@@ -182,4 +185,87 @@ describe('KnowledgeQuery', () => {
       expect(result.fromCache).toBe(false);
     });
   });
+
+  describe('queryByMode', () => {
+    it('should filter by consumptionMode', () => {
+      store.save(makeEntry({ id: 'RUL-001', consumptionMode: 'rule', title: 'Rule' }));
+      store.save(makeEntry({ id: 'REF-001', consumptionMode: 'reference', title: 'Ref' }));
+      store.save(makeEntry({ id: 'SIG-001', consumptionMode: 'signal', title: 'Signal' }));
+
+      const rules = query.queryByMode('rule');
+      expect(rules).toHaveLength(1);
+      expect(rules[0].id).toBe('RUL-001');
+    });
+
+    it('should combine with additional filter', () => {
+      store.save(makeEntry({ id: 'REF-001', consumptionMode: 'reference', tags: ['arch'] }));
+      store.save(makeEntry({ id: 'REF-002', consumptionMode: 'reference', tags: ['api'] }));
+
+      const refs = query.queryByMode('reference', { tags: ['arch'] });
+      expect(refs).toHaveLength(1);
+      expect(refs[0].id).toBe('REF-001');
+    });
+  });
+
+  describe('consume', () => {
+    it('should return rules, references, and context', () => {
+      store.save(makeEntry({ id: 'RUL-001', consumptionMode: 'rule', title: 'Port Rule' }));
+      store.save(makeEntry({
+        id: 'REF-001', consumptionMode: 'reference', title: 'Architecture',
+        content: 'The API uses TypeScript and REST endpoints',
+      }));
+      store.save(makeEntry({
+        id: 'CTX-001', consumptionMode: 'context', title: 'Env',
+        applicablePhases: ['build'],
+      }));
+
+      const result = query.consume({ requirementText: 'API TypeScript', phase: 'build' });
+      expect(result.rules).toHaveLength(1);
+      expect(result.rules[0].id).toBe('RUL-001');
+      expect(result.references.length).toBeGreaterThanOrEqual(1);
+      expect(result.context).toHaveLength(1);
+      expect(result.context[0].id).toBe('CTX-001');
+    });
+
+    it('should filter context by phase', () => {
+      store.save(makeEntry({
+        id: 'CTX-001', consumptionMode: 'context', title: 'Build Config',
+        applicablePhases: ['build'],
+      }));
+      store.save(makeEntry({
+        id: 'CTX-002', consumptionMode: 'context', title: 'Deploy Config',
+        applicablePhases: ['deploy'],
+      }));
+
+      const result = query.consume({ phase: 'build' });
+      expect(result.context).toHaveLength(1);
+      expect(result.context[0].id).toBe('CTX-001');
+    });
+
+    it('should return empty references when no requirementText', () => {
+      store.save(makeEntry({ id: 'REF-001', consumptionMode: 'reference' }));
+      const result = query.consume({});
+      // With no text filter, returns up to 3
+      expect(result.references.length).toBeLessThanOrEqual(3);
+    });
+  });
+
+  describe('formatForPrompt', () => {
+    it('should add External Source prefix for external origin', () => {
+      const { KnowledgeQuery: KQ } = require('../query');
+      const entry = makeEntry({ origin: 'external', title: 'GitHub Doc', content: 'Architecture' });
+      const result = KQ.formatForPrompt(entry);
+      expect(result).toContain('[External Source');
+      expect(result).toContain('GitHub Doc');
+      expect(result).toContain('Architecture');
+    });
+
+    it('should not add prefix for agent origin', () => {
+      const { KnowledgeQuery: KQ } = require('../query');
+      const entry = makeEntry({ origin: 'agent', title: 'Internal', content: 'Details' });
+      const result = KQ.formatForPrompt(entry);
+      expect(result).not.toContain('[External Source');
+      expect(result).toBe('Internal: Details');
+    });
+  });
 });

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

@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/globals';
-import { KnowledgeStore } from '../store';
+import { FileKnowledgeStore as KnowledgeStore } from '../store';
 import { ReferenceTracker } from '../reference-tracker';
 import type { KnowledgeEntry } from '../types';
 import * as fs from 'fs';
@@ -29,6 +29,9 @@ describe('ReferenceTracker', () => {
     applicablePhases: [],
     sourceReferences: [],
     referencedBy: [],
+    executionResults: [],
+    consumptionMode: 'reference',
+    origin: 'agent',
     ...overrides,
   });
 

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

@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/globals';
-import { KnowledgeStore } from '../store';
+import { FileKnowledgeStore as KnowledgeStore } from '../store';
 import type { KnowledgeEntry } from '../types';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -27,6 +27,9 @@ describe('KnowledgeStore', () => {
     applicablePhases: ['ARCHITECT'],
     sourceReferences: [],
     referencedBy: [],
+    executionResults: [],
+    consumptionMode: 'reference',
+    origin: 'agent',
     ...overrides,
   });
 
@@ -125,6 +128,23 @@ describe('KnowledgeStore', () => {
       const list = store.list({ excludeArchived: false });
       expect(list).toHaveLength(2);
     });
+
+    it('should filter by consumptionMode', () => {
+      store.save(makeEntry({ id: 'DEC-001', consumptionMode: 'reference' }));
+      store.save(makeEntry({ id: 'DEC-002', consumptionMode: 'rule', title: 'Rule' }));
+      store.save(makeEntry({ id: 'DEC-003', consumptionMode: 'signal', title: 'Signal' }));
+      const list = store.list({ consumptionModes: ['rule', 'signal'] });
+      expect(list).toHaveLength(2);
+      expect(list.map(e => e.id).sort()).toEqual(['DEC-002', 'DEC-003']);
+    });
+
+    it('should filter by origin', () => {
+      store.save(makeEntry({ id: 'DEC-001', origin: 'agent' }));
+      store.save(makeEntry({ id: 'DEC-002', origin: 'human', title: 'Human' }));
+      const list = store.list({ origins: ['human'] });
+      expect(list).toHaveLength(1);
+      expect(list[0].origin).toBe('human');
+    });
   });
 
   describe('delete', () => {
@@ -164,6 +184,32 @@ describe('KnowledgeStore', () => {
   });
 
   describe('edge cases', () => {
+    it('should round-trip consumptionMode and origin through save/load', () => {
+      store.save(makeEntry({
+        id: 'DEC-001',
+        consumptionMode: 'rule',
+        origin: 'human',
+        fullContentPath: 'https://example.com/doc',
+        skillId: 'skill-001',
+      }));
+      const loaded = store.get('DEC-001');
+      expect(loaded?.consumptionMode).toBe('rule');
+      expect(loaded?.origin).toBe('human');
+      expect(loaded?.fullContentPath).toBe('https://example.com/doc');
+      expect(loaded?.skillId).toBe('skill-001');
+    });
+
+    it('should default consumptionMode to reference and origin to agent', () => {
+      store.save(makeEntry({ id: 'DEC-001' }));
+      const loaded = store.get('DEC-001');
+      expect(loaded?.consumptionMode).toBe('reference');
+      expect(loaded?.origin).toBe('agent');
+    });
+
+    it('getBaseDir() returns configured baseDir', () => {
+      expect(store.getBaseDir()).toBe(tempDir);
+    });
+
     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 });
@@ -235,4 +281,165 @@ describe('KnowledgeStore', () => {
       expect(retrieved!.decayAt).toBeUndefined();
     });
   });
+
+  describe('findFile precision (E3)', () => {
+    it('should not collide when one id is a suffix of another', () => {
+      // pitfall with id containing hyphen: file = pitfall-mppq8n44-1829.md
+      const pitfall = makeEntry({
+        id: 'PIT-mppq8n44-1829',
+        type: 'pitfall',
+        title: 'Pitfall Entry',
+        content: 'pitfall content',
+      });
+      // decision with numeric id that is a suffix: file = decision-1829.md
+      const decision = makeEntry({
+        id: '1829',
+        type: 'decision',
+        title: 'Decision Entry',
+        content: 'decision content',
+      });
+      store.save(pitfall);
+      store.save(decision);
+
+      // get('1829') must return the decision, not the pitfall
+      const retrieved = store.get('1829');
+      expect(retrieved).toBeDefined();
+      expect(retrieved!.id).toBe('1829');
+      expect(retrieved!.type).toBe('decision');
+
+      // get('PIT-mppq8n44-1829') must return the pitfall
+      const pit = store.get('PIT-mppq8n44-1829');
+      expect(pit).toBeDefined();
+      expect(pit!.id).toBe('PIT-mppq8n44-1829');
+      expect(pit!.type).toBe('pitfall');
+    });
+
+    it('should not collide when id contains type prefix of another entry', () => {
+      // model with id that contains "GUI" prefix: file = model-GUI-003.md
+      const model = makeEntry({
+        id: 'GUI-003',
+        type: 'model',
+        title: 'Model Entry',
+        content: 'model content',
+      });
+      // guideline with id "003": file = guideline-003.md
+      const guideline = makeEntry({
+        id: '003',
+        type: 'guideline',
+        title: 'Guideline Entry',
+        content: 'guideline content',
+      });
+      store.save(model);
+      store.save(guideline);
+
+      const retrieved = store.get('003');
+      expect(retrieved).toBeDefined();
+      expect(retrieved!.id).toBe('003');
+      expect(retrieved!.type).toBe('guideline');
+    });
+
+    it('should handle delete correctly with colliding ids', () => {
+      const pitfall = makeEntry({
+        id: 'PIT-mppq8n44-1829',
+        type: 'pitfall',
+        title: 'Pitfall Entry',
+        content: 'pitfall content',
+      });
+      const decision = makeEntry({
+        id: '1829',
+        type: 'decision',
+        title: 'Decision Entry',
+        content: 'decision content',
+      });
+      store.save(pitfall);
+      store.save(decision);
+
+      // delete('1829') should only delete the decision
+      expect(store.delete('1829')).toBe(true);
+      expect(store.get('1829')).toBeUndefined();
+      // pitfall should still exist
+      expect(store.get('PIT-mppq8n44-1829')).toBeDefined();
+    });
+  });
+
+  describe('snapshot', () => {
+    it('should create snapshot file in .snapshots/', () => {
+      store.save(makeEntry({ id: 'SNAP-001' }));
+      const snapPath = store.snapshot();
+      expect(fs.existsSync(snapPath)).toBe(true);
+      expect(snapPath).toContain('.snapshots/index-');
+      const content = JSON.parse(fs.readFileSync(snapPath, 'utf-8'));
+      expect(content.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it('should overwrite existing snapshot for same date', () => {
+      store.save(makeEntry({ id: 'SNAP-001' }));
+      store.snapshot();
+      store.save(makeEntry({ id: 'SNAP-002', title: 'Second' }));
+      store.snapshot();
+      const today = new Date().toISOString().slice(0, 10);
+      const snapPath = path.join(tempDir, '.snapshots', `index-${today}.json`);
+      const content = JSON.parse(fs.readFileSync(snapPath, 'utf-8'));
+      expect(content.some((e: any) => e.id === 'SNAP-002')).toBe(true);
+    });
+
+    it('should read snapshot by date', () => {
+      store.save(makeEntry({ id: 'SNAP-001' }));
+      store.snapshot();
+      const today = new Date().toISOString().slice(0, 10);
+      const snapshot = store.getSnapshot(today);
+      expect(snapshot).toBeDefined();
+      expect(snapshot!.some(e => e.id === 'SNAP-001')).toBe(true);
+    });
+
+    it('should return undefined for non-existent snapshot date', () => {
+      expect(store.getSnapshot('2020-01-01')).toBeUndefined();
+    });
+  });
+
+  describe('getSurvivalRate', () => {
+    it('should return undefined when no snapshot exists', () => {
+      expect(store.getSurvivalRate(30)).toBeUndefined();
+    });
+
+    it('should return 100% when all entries still active', () => {
+      store.save(makeEntry({ id: 'SUR-001' }));
+      store.save(makeEntry({ id: 'SUR-002' }));
+      // Create a snapshot with today's date, then check survival against 0 days ago
+      store.snapshot();
+      // Manually copy snapshot to look like 30 days ago
+      const today = new Date().toISOString().slice(0, 10);
+      const pastDate = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+      const snapDir = path.join(tempDir, '.snapshots');
+      fs.copyFileSync(
+        path.join(snapDir, `index-${today}.json`),
+        path.join(snapDir, `index-${pastDate}.json`),
+      );
+      const result = store.getSurvivalRate(30);
+      expect(result).toBeDefined();
+      expect(result!.rate).toBe(100);
+      expect(result!.survived).toBe(2);
+      expect(result!.total).toBe(2);
+    });
+
+    it('should count archived entries as not survived', () => {
+      store.save(makeEntry({ id: 'SUR-001' }));
+      store.save(makeEntry({ id: 'SUR-002' }));
+      store.snapshot();
+      // Archive one entry after snapshot
+      store.update('SUR-002', { maturity: 'archived' });
+      // Copy snapshot to 30 days ago
+      const today = new Date().toISOString().slice(0, 10);
+      const pastDate = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+      const snapDir = path.join(tempDir, '.snapshots');
+      fs.copyFileSync(
+        path.join(snapDir, `index-${today}.json`),
+        path.join(snapDir, `index-${pastDate}.json`),
+      );
+      const result = store.getSurvivalRate(30);
+      expect(result!.rate).toBe(50);
+      expect(result!.survived).toBe(1);
+      expect(result!.total).toBe(2);
+    });
+  });
 });