@dommaker/harness 0.16.0 → 0.16.2

package/src/knowledge/__tests__/index-generator.test.ts

@@ -0,0 +1,335 @@
+/**
+ * KnowledgeIndexGenerator tests
+ *
+ * Covers:
+ * - Frontmatter extraction (id, type, title, maturity, tags)
+ * - Files without frontmatter (best-effort from filename/H1)
+ * - Excluded directories (.archive, .snapshots, resolutions)
+ * - H2 heading extraction as search terms
+ * - Index file format (header + data lines)
+ * - Overwrite behavior
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { KnowledgeIndexGenerator } from '../index-generator';
+
+function makeTmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'idx-gen-test-'));
+}
+
+function writeEntry(dir: string, filename: string, frontmatter: Record<string, unknown> | null, body: string = 'Content here'): void {
+  const lines: string[] = [];
+  if (frontmatter) {
+    lines.push('---');
+    for (const [k, v] of Object.entries(frontmatter)) {
+      if (Array.isArray(v)) {
+        lines.push(`${k}:`);
+        for (const item of v) lines.push(`  - ${item}`);
+      } else {
+        lines.push(`${k}: ${JSON.stringify(v)}`);
+      }
+    }
+    lines.push('---');
+    lines.push('');
+  }
+  lines.push(body);
+  fs.writeFileSync(path.join(dir, filename), lines.join('\n'));
+}
+
+describe('KnowledgeIndexGenerator', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('generateIndexLines', () => {
+    it('extracts metadata from frontmatter', () => {
+      writeEntry(tmpDir, 'architecture-ARC-011.md', {
+        id: 'ARC-011',
+        type: 'architecture',
+        title: 'JWT认证系统',
+        maturity: 'verified',
+        tags: ['jwt', 'auth'],
+      });
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+
+      expect(lines).toHaveLength(1);
+      const fields = lines[0].split('|');
+      expect(fields[0]).toBe('architecture-ARC-011.md');
+      expect(fields[1]).toBe('ARC-011');
+      expect(fields[2]).toBe('architecture');
+      expect(fields[3]).toBe('JWT认证系统');
+      expect(fields[4]).toBe('verified');
+      expect(fields[5]).toBe('jwt;auth');
+    });
+
+    it('includes H2 headings as search terms', () => {
+      writeEntry(tmpDir, 'pitfall-001.md', {
+        id: 'PIT-001',
+        type: 'pitfall',
+        title: 'Test Pitfall',
+        maturity: 'verified',
+        tags: [],
+      }, `# Title
+
+## 问题根因
+Some text
+
+## 修复方案
+More text
+
+## 注意事项
+Extra text
+`);
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+      const terms = lines[0].split('|')[6];
+
+      expect(terms).toContain('问题根因');
+      expect(terms).toContain('修复方案');
+      expect(terms).toContain('注意事项');
+    });
+
+    it('handles files without frontmatter via best-effort', () => {
+      fs.writeFileSync(
+        path.join(tmpDir, 'agent-network-core-concepts.md'),
+        '# Agent Network 核心概念\n\n## WorkUnit\nBody\n'
+      );
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+
+      expect(lines).toHaveLength(1);
+      const fields = lines[0].split('|');
+      expect(fields[0]).toBe('agent-network-core-concepts.md');
+      // agent-network-* prefix maps to architecture
+      expect(fields[2]).toBe('architecture');
+      // H2 terms should still be extracted
+      expect(fields[6]).toContain('WorkUnit');
+    });
+
+    it('excludes .archive directory', () => {
+      fs.mkdirSync(path.join(tmpDir, '.archive'));
+      writeEntry(tmpDir, 'top.md', { id: 'T1', type: 'pitfall', title: 'Top', maturity: 'verified', tags: [] });
+      writeEntry(tmpDir, '.archive/archived.md', { id: 'A1', type: 'pitfall', title: 'Archived', maturity: 'archived', tags: [] });
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+
+      expect(lines).toHaveLength(1);
+      expect(lines[0]).toContain('top.md');
+      expect(lines.join('')).not.toContain('archived.md');
+    });
+
+    it('excludes resolutions directory', () => {
+      fs.mkdirSync(path.join(tmpDir, 'resolutions'));
+      writeEntry(tmpDir, 'top.md', { id: 'T1', type: 'pitfall', title: 'Top', maturity: 'verified', tags: [] });
+      writeEntry(tmpDir, 'resolutions/res-001.md', { id: 'R1', type: 'decision', title: 'Res', maturity: 'verified', tags: [] });
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+
+      expect(lines).toHaveLength(1);
+      expect(lines.join('')).not.toContain('res-001.md');
+    });
+
+    it('excludes .snapshots directory', () => {
+      fs.mkdirSync(path.join(tmpDir, '.snapshots'));
+      writeEntry(tmpDir, 'top.md', { id: 'T1', type: 'pitfall', title: 'Top', maturity: 'verified', tags: [] });
+      writeEntry(tmpDir, '.snapshots/snap.md', { id: 'S1', type: 'pitfall', title: 'Snap', maturity: 'verified', tags: [] });
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+
+      expect(lines).toHaveLength(1);
+      expect(lines.join('')).not.toContain('snap.md');
+    });
+
+    it('excludes _index.md from index', () => {
+      writeEntry(tmpDir, '_index.md', { id: 'IDX', type: 'pitfall', title: 'Index', maturity: 'verified', tags: [] });
+      writeEntry(tmpDir, 'real.md', { id: 'R1', type: 'pitfall', title: 'Real', maturity: 'verified', tags: [] });
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+
+      expect(lines).toHaveLength(1);
+      expect(lines[0]).toContain('real.md');
+      expect(lines.join('')).not.toContain('_index.md');
+    });
+
+    it('generates header with stats', () => {
+      writeEntry(tmpDir, 'a.md', { id: 'A1', type: 'pitfall', title: 'A', maturity: 'verified', tags: [] });
+      writeEntry(tmpDir, 'b.md', { id: 'B1', type: 'architecture', title: 'B', maturity: 'draft', tags: [] });
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const output = gen.generate();
+
+      expect(output).toContain('# Knowledge Base Index');
+      expect(output).toContain('Total: 2');
+      expect(output).toContain('# filename|id|type|title|maturity|tags|terms');
+    });
+  });
+
+  describe('regenerate', () => {
+    it('writes _index.md to baseDir', () => {
+      writeEntry(tmpDir, 'test.md', { id: 'T1', type: 'guideline', title: 'Test', maturity: 'verified', tags: ['tdd'] });
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      gen.regenerate();
+
+      const indexPath = path.join(tmpDir, '_index.md');
+      expect(fs.existsSync(indexPath)).toBe(true);
+
+      const content = fs.readFileSync(indexPath, 'utf-8');
+      expect(content).toContain('test.md');
+      expect(content).toContain('T1');
+      expect(content).toContain('guideline');
+    });
+
+    it('overwrites existing index', () => {
+      fs.writeFileSync(path.join(tmpDir, '_index.md'), 'old content');
+      writeEntry(tmpDir, 'new.md', { id: 'N1', type: 'pitfall', title: 'New', maturity: 'verified', tags: [] });
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      gen.regenerate();
+
+      const content = fs.readFileSync(path.join(tmpDir, '_index.md'), 'utf-8');
+      expect(content).toContain('new.md');
+      expect(content).not.toContain('old content');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('handles empty directory', () => {
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+      expect(lines).toHaveLength(0);
+    });
+
+    it('handles subdirectories (arch-patterns, skills)', () => {
+      fs.mkdirSync(path.join(tmpDir, 'arch-patterns'));
+      writeEntry(tmpDir, 'arch-patterns/event.md', {
+        id: 'AP-event', type: 'architecture', title: 'Event Pattern', maturity: 'verified', tags: [],
+      });
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+
+      expect(lines).toHaveLength(1);
+      expect(lines[0]).toContain('event.md');
+    });
+
+    it('handles missing tags array gracefully', () => {
+      writeEntry(tmpDir, 'no-tags.md', {
+        id: 'NT1', type: 'pitfall', title: 'No Tags', maturity: 'verified',
+      });
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+
+      expect(lines).toHaveLength(1);
+      const fields = lines[0].split('|');
+      expect(fields[5]).toBe('');
+    });
+
+    it('sanitizes newlines in title to preserve single-line format', () => {
+      // Simulates YAML block scalar: title: |\n  Line 1\n  Line 2
+      fs.writeFileSync(
+        path.join(tmpDir, 'guideline-GUI-007.md'),
+        '---\nid: GUI-007\ntype: guideline\ntitle: |\n  Line one\n  Line two\nmaturity: archived\ntags: []\n---\nBody\n'
+      );
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+
+      expect(lines).toHaveLength(1);
+      expect(lines[0]).not.toContain('\n');
+      const fields = lines[0].split('|');
+      expect(fields).toHaveLength(7);
+      expect(fields[3]).toBe('Line one Line two');
+    });
+
+    it('sanitizes pipe characters in fields', () => {
+      writeEntry(tmpDir, 'test.md', {
+        id: 'T1', type: 'pitfall', title: 'A | B', maturity: 'verified', tags: ['x|y'],
+      });
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+
+      expect(lines).toHaveLength(1);
+      const fields = lines[0].split('|');
+      expect(fields).toHaveLength(7);
+      expect(fields[3]).toBe('A / B');
+      expect(fields[5]).toBe('x/y');
+    });
+
+    it('detects skill schema (name/description instead of id/type)', () => {
+      fs.mkdirSync(path.join(tmpDir, 'skills'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpDir, 'skills', 'proxy.md'),
+        '---\nname: proxy\ndescription: "Proxy skill for testing"\ntrigger: manual\nstatus: active\n---\n## Steps\nDo things\n',
+      );
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+
+      expect(lines).toHaveLength(1);
+      const fields = lines[0].split('|');
+      expect(fields[1]).toBe('proxy');
+      expect(fields[2]).toBe('skill');
+      expect(fields[3]).toContain('Proxy skill');
+    });
+
+    it('infers type from directory (skills/ → skill, arch-patterns/ → architecture)', () => {
+      fs.mkdirSync(path.join(tmpDir, 'arch-patterns'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpDir, 'arch-patterns', 'event.md'),
+        '# Event Pattern\n\n## Lifecycle\nBody\n',
+      );
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+
+      expect(lines).toHaveLength(1);
+      const fields = lines[0].split('|');
+      expect(fields[2]).toBe('architecture');
+    });
+
+    it('infers pattern type from suffix (*-pattern.md)', () => {
+      fs.writeFileSync(
+        path.join(tmpDir, 'knowledge-quality-pattern.md'),
+        '# Quality Pattern\n\n## Dimensions\nBody\n',
+      );
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+
+      expect(lines).toHaveLength(1);
+      const fields = lines[0].split('|');
+      expect(fields[2]).toBe('pattern');
+    });
+
+    it('skips ghost files named .md', () => {
+      fs.mkdirSync(path.join(tmpDir, 'skills'), { recursive: true });
+      fs.writeFileSync(path.join(tmpDir, 'skills', '.md'), '# Ghost\n');
+      writeEntry(tmpDir, 'real.md', { id: 'R1', type: 'pitfall', title: 'Real', maturity: 'verified', tags: [] });
+
+      const gen = new KnowledgeIndexGenerator(tmpDir);
+      const lines = gen.generateIndexLines();
+
+      expect(lines).toHaveLength(1);
+      expect(lines[0]).toContain('real.md');
+    });
+  });
+});

package/src/knowledge/audit.ts

@@ -30,11 +30,14 @@ export type AuditRuleName =
   // D3: 去重有效性
   | 'title-duplicate'
   | 'source-refs-bloat'
+  | 'fragment-cluster'
   // D4: 成熟度健康
   | 'promotion-blocked'
   | 'orphan-draft'
   // D5: 新鲜度
-  | 'stale-entry';
+  | 'stale-entry'
+  // D2: 领域相关性
+  | 'deprecated-domain';
 
 export type AuditAction = 'archive' | 'demote' | 'flag' | 'reject' | 'trim';
 
@@ -96,6 +99,12 @@ const EVENT_NOISE_PATTERNS = [
   /^\[Session Feature\]\s/,
 ];
 const REQUIRED_FRONTMATTER = ['id', 'type', 'title', 'maturity'];
+const SYNTHETIC_REF_PATTERN = /^(search|test-agent|prompt-inject|monitor|analyst|auditor|triage|executor|session|trend|incident):\d{4}-\d{2}-\d{2}/;
+
+/** Filter out synthetic references (automated search/ops records, not genuine consumption) */
+function genuineRefs(refs: string[]): string[] {
+  return refs.filter(r => !SYNTHETIC_REF_PATTERN.test(r));
+}
 
 // ── Per-Entry Rules ───────────────────────────────────────
 
@@ -222,11 +231,12 @@ const perEntryRules: AuditRule[] = [
     detect: (entry, ctx) => {
       if (entry.maturity === 'archived') return null;
       if (!ctx.allEntries) return null;
+      if (!entry.title) return null;
       const dupes = ctx.allEntries.filter(e =>
         e.id !== entry.id &&
         e.maturity !== 'archived' &&
         e.type === entry.type &&
-        e.title.toLowerCase().trim() === entry.title.toLowerCase().trim()
+        e.title?.toLowerCase().trim() === entry.title.toLowerCase().trim()
       );
       if (dupes.length > 0) {
         return `与 ${dupes.map(e => e.id).join(', ')} 标题重复`;
@@ -245,6 +255,31 @@ const perEntryRules: AuditRule[] = [
       return null;
     },
   },
+  {
+    name: 'fragment-cluster',
+    severity: 'medium',
+    action: 'flag',
+    detect: (entry, ctx) => {
+      if (entry.maturity === 'archived') return null;
+      if (!ctx.allEntries || entry.content.trim().length >= 100) return null;
+      if (!entry.tags?.length) return null;
+
+      // Find peers: same type, short body, shared tags ≥2
+      const entryTags = new Set(entry.tags);
+      const peers = ctx.allEntries.filter(e =>
+        e.id !== entry.id &&
+        e.maturity !== 'archived' &&
+        e.type === entry.type &&
+        e.content.trim().length < 100 &&
+        e.tags?.filter(t => entryTags.has(t)).length >= 2
+      );
+
+      if (peers.length >= 2) {
+        return `碎片集群：与 ${peers.map(e => e.id).join(', ')} 同 type+tags 且 body 均 <100 字符，建议合并`;
+      }
+      return null;
+    },
+  },
 
   // D4: 成熟度健康
   {
@@ -267,7 +302,7 @@ const perEntryRules: AuditRule[] = [
     action: 'flag',
     detect: (entry) => {
       if (entry.maturity !== 'draft') return null;
-      if (entry.contributors.length === 0 && entry.projects.length === 0 && entry.referencedBy.length === 0) {
+      if (entry.contributors.length === 0 && entry.projects.length === 0 && genuineRefs(entry.referencedBy).length === 0) {
         return `draft 无贡献者/项目/引用`;
       }
       return null;
@@ -290,6 +325,27 @@ const perEntryRules: AuditRule[] = [
       return null;
     },
   },
+
+  // D2b: 领域相关性 — 检测已废弃领域的残留条目
+  {
+    name: 'deprecated-domain',
+    severity: 'high',
+    action: 'archive',
+    detect: (entry) => {
+      if (entry.maturity === 'archived') return null;
+      const tags = (entry.tags ?? []).map(t => t.toLowerCase());
+      // Tag-level: "pipeline" tag is deprecated (Studio Pipeline superseded by Agent Network)
+      if (tags.includes('pipeline')) {
+        return `标签 "pipeline" 属于已废弃领域（已被 Agent Network 取代）`;
+      }
+      // Title-level: strong domain-specific terms
+      const title = entry.title || '';
+      if (/pipeline|管线|GoalExecution|DeployAgent|Integration step/i.test(title)) {
+        return `标题引用已废弃领域: "${title}"`;
+      }
+      return null;
+    },
+  },
 ];
 
 // ── Audit Engine ──────────────────────────────────────────
@@ -337,7 +393,7 @@ export class KnowledgeAudit {
    * 全量扫描（日兜底 / 手动模式）
    */
   run(options?: { autoFix?: boolean }): AuditReport {
-    const entries = this.store.list({ excludeArchived: false });
+    const entries = this.store.list({ excludeArchived: false }).filter(e => e.title && e.type && e.content != null);
     const ctx: AuditContext = {
       shortContentThreshold: this.shortContentThreshold,
       staleDays: this.staleDays,
@@ -407,12 +463,12 @@ export class KnowledgeAudit {
     const d1Score = entries.length === 0 ? 100 : Math.max(0, 100 - (d1Issues.length / entries.length) * 100);
 
     // D2: 内容质量
-    const d2Rules: AuditRuleName[] = ['test-data-pollution', 'daily-audit-noise', 'event-noise', 'zero-content-proven', 'short-content', 'maturity-inflation'];
+    const d2Rules: AuditRuleName[] = ['test-data-pollution', 'daily-audit-noise', 'event-noise', 'zero-content-proven', 'short-content', 'maturity-inflation', 'deprecated-domain'];
     const d2Issues = issues.filter(i => d2Rules.includes(i.rule));
     const d2Score = active.length === 0 ? 100 : Math.max(0, 100 - (d2Issues.length / active.length) * 100);
 
     // D3: 去重有效性
-    const d3Rules: AuditRuleName[] = ['title-duplicate', 'source-refs-bloat'];
+    const d3Rules: AuditRuleName[] = ['title-duplicate', 'source-refs-bloat', 'fragment-cluster'];
     const d3Issues = issues.filter(i => d3Rules.includes(i.rule));
     const d3Score = active.length === 0 ? 100 : Math.max(0, 100 - (d3Issues.length / active.length) * 100);
 
@@ -441,10 +497,10 @@ export class KnowledgeAudit {
     const d5Score = active.length === 0 ? 100 : Math.max(0, 100 - (staleRatio * 100));
 
     // D6: 飞轮验证
-    const withRefs = active.filter(e => e.referencedBy.length > 0).length;
+    const withRefs = active.filter(e => genuineRefs(e.referencedBy).length > 0).length;
     const refCoverage = active.length > 0 ? withRefs / active.length : 0;
     const avgRefs = active.length > 0
-      ? active.reduce((sum, e) => sum + e.referencedBy.length, 0) / active.length
+      ? active.reduce((sum, e) => sum + genuineRefs(e.referencedBy).length, 0) / active.length
       : 0;
 
     // Consumption hit rate from aggregated stats file (written by MonitorAgent)