@dommaker/harness 0.13.0 → 0.13.2

package/src/dashboard/__tests__/data.test.ts

@@ -0,0 +1,115 @@
+/**
+ * DashboardDataProvider 测试
+ */
+
+import { DashboardDataProvider } from '../data';
+import type { KnowledgeEntry } from '../../knowledge/types';
+import type { ConstraintStats } from '../../constraints/types';
+
+function makeEntry(overrides: Partial<KnowledgeEntry> = {}): KnowledgeEntry {
+  return {
+    id: `test-${Math.random().toString(36).slice(2, 6)}`,
+    type: 'decision',
+    title: 'Test',
+    content: '',
+    maturity: 'verified',
+    layer: 'project',
+    created: new Date().toISOString(),
+    lastReferenced: new Date().toISOString(),
+    contributors: [],
+    projects: [],
+    tags: [],
+    applicablePhases: [],
+    sourceReferences: [],
+    referencedBy: [],
+    ...overrides,
+  };
+}
+
+describe('DashboardDataProvider', () => {
+  let provider: DashboardDataProvider;
+
+  beforeEach(() => {
+    provider = new DashboardDataProvider();
+  });
+
+  describe('generate', () => {
+    it('应该生成完整 Dashboard 数据', () => {
+      const entries = [makeEntry(), makeEntry({ type: 'guideline', maturity: 'proven' })];
+      const data = provider.generate(entries);
+
+      expect(data.timestamp).toBeDefined();
+      expect(data.knowledgeOverview.total).toBe(2);
+      expect(data.constraintHeatmap).toBeDefined();
+      expect(data.knowledgeFlow).toBeDefined();
+      expect(data.feedbackLoop).toBeDefined();
+    });
+
+    it('应该接受约束统计', () => {
+      const stats: ConstraintStats[] = [{
+        constraintId: 'no_any_type',
+        triggerCount: 100,
+        passCount: 78,
+        interceptCount: 22,
+        interceptRate: 22,
+        lastTriggered: new Date().toISOString(),
+      }];
+
+      const data = provider.generate([], stats);
+      const heatmap = data.constraintHeatmap;
+      const entry = heatmap.constraints.find(c => c.id === 'no_any_type');
+      expect(entry?.trigger).toBe(100);
+      expect(entry?.intercept).toBe(22);
+    });
+  });
+
+  describe('getKnowledgeOverview', () => {
+    it('应该返回知识概览', () => {
+      const overview = provider.getKnowledgeOverview([makeEntry()]);
+      expect(overview.total).toBe(1);
+    });
+  });
+
+  describe('getConstraintHeatmap', () => {
+    it('应该包含所有约束', () => {
+      const heatmap = provider.getConstraintHeatmap([]);
+      expect(heatmap.constraints.length).toBeGreaterThan(0);
+      expect(heatmap.period).toBe('近 30 天');
+    });
+
+    it('应该标记从未触发的约束', () => {
+      const heatmap = provider.getConstraintHeatmap([]);
+      expect(heatmap.neverTriggered.length).toBeGreaterThan(0);
+    });
+
+    it('应该检测拦截率下降的约束', () => {
+      const stats: ConstraintStats[] = [{
+        constraintId: 'no_any_type',
+        triggerCount: 100,
+        passCount: 90,
+        interceptCount: 10,
+        interceptRate: 10,
+      }];
+
+      const heatmap = provider.getConstraintHeatmap(stats);
+      expect(heatmap.decliningInterceptRate.some(c => c.id === 'no_any_type')).toBe(true);
+    });
+  });
+
+  describe('getFeedbackLoop', () => {
+    it('应该返回反馈环状态', () => {
+      const loop = provider.getFeedbackLoop();
+      expect(loop.local).toBeDefined();
+      expect(loop.push).toBeDefined();
+      expect(loop.external).toBeDefined();
+      expect(loop.feedbackToKnowledge).toBeDefined();
+    });
+  });
+
+  describe('getRegistry', () => {
+    it('应该返回约束注册表', () => {
+      expect(provider.getRegistry()).toBeDefined();
+      expect(provider.getRegistry().getAll().length).toBeGreaterThan(0);
+    });
+  });
+});

package/src/dashboard/__tests__/stats.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Dashboard stats 测试
+ */
+
+import { computeKnowledgeOverview, computeKnowledgeFlow, computeInterceptRate } from '../stats';
+import type { KnowledgeEntry } from '../../knowledge/types';
+
+function makeEntry(overrides: Partial<KnowledgeEntry> = {}): KnowledgeEntry {
+  return {
+    id: `test-${Math.random().toString(36).slice(2, 6)}`,
+    type: 'decision',
+    title: 'Test',
+    content: '',
+    maturity: 'verified',
+    layer: 'project',
+    created: new Date().toISOString(),
+    lastReferenced: new Date().toISOString(),
+    contributors: [],
+    projects: [],
+    tags: [],
+    applicablePhases: [],
+    sourceReferences: [],
+    referencedBy: [],
+    ...overrides,
+  };
+}
+
+describe('computeKnowledgeOverview', () => {
+  it('应该返回空概览当无条目', () => {
+    const overview = computeKnowledgeOverview([]);
+    expect(overview.total).toBe(0);
+    expect(overview.maturityDistribution.provenPercent).toBe(0);
+  });
+
+  it('应该按类型统计', () => {
+    const entries = [
+      makeEntry({ type: 'decision', maturity: 'proven' }),
+      makeEntry({ type: 'decision', maturity: 'verified' }),
+      makeEntry({ type: 'guideline', maturity: 'draft' }),
+    ];
+
+    const overview = computeKnowledgeOverview(entries);
+    expect(overview.total).toBe(3);
+    expect(overview.byType.length).toBe(2);
+
+    const decisions = overview.byType.find(b => b.type === 'decision')!;
+    expect(decisions.total).toBe(2);
+    expect(decisions.proven).toBe(1);
+    expect(decisions.verified).toBe(1);
+  });
+
+  it('应该计算成熟度分布百分比', () => {
+    const entries = [
+      makeEntry({ maturity: 'proven' }),
+      makeEntry({ maturity: 'proven' }),
+      makeEntry({ maturity: 'verified' }),
+      makeEntry({ maturity: 'draft' }),
+    ];
+
+    const overview = computeKnowledgeOverview(entries);
+    expect(overview.maturityDistribution.provenPercent).toBe(50);
+    expect(overview.maturityDistribution.verifiedPercent).toBe(25);
+    expect(overview.maturityDistribution.draftPercent).toBe(25);
+  });
+
+  it('应该计算衰减预警', () => {
+    const oldDate = '2020-01-01T00:00:00.000Z';
+    const entries = [
+      makeEntry({ maturity: 'proven', lastReferenced: oldDate }),
+      makeEntry({ maturity: 'verified', lastReferenced: oldDate }),
+      makeEntry({ maturity: 'verified', lastReferenced: new Date().toISOString() }),
+    ];
+
+    const overview = computeKnowledgeOverview(entries);
+    expect(overview.decayWarning.provenUnused6m).toBe(1);
+    expect(overview.decayWarning.verifiedUnused3m).toBe(1);
+  });
+
+  it('应该用 created 日期当 lastReferenced 为空', () => {
+    const oldDate = '2020-01-01T00:00:00.000Z';
+    const entries = [
+      makeEntry({ maturity: 'proven', lastReferenced: '', created: oldDate }),
+    ];
+
+    const overview = computeKnowledgeOverview(entries);
+    expect(overview.decayWarning.provenUnused6m).toBe(1);
+  });
+});
+
+describe('computeKnowledgeFlow', () => {
+  it('应该计算基本流转统计', () => {
+    const entries = [
+      makeEntry({ id: 'a', maturity: 'verified', lastReferenced: new Date().toISOString() }),
+      makeEntry({ id: 'b', maturity: 'proven' }),
+      makeEntry({ id: 'c', maturity: 'draft', lastReferenced: '' }),
+    ];
+
+    const refCounts = new Map<string, number>();
+    refCounts.set('a', 10);
+    refCounts.set('b', 5);
+
+    const flow = computeKnowledgeFlow(entries, refCounts);
+    expect(flow.period).toBe('近 30 天');
+    expect(flow.pipeline.referenced).toBe(2);
+    expect(flow.topReferenced.length).toBe(2);
+    expect(flow.topReferenced[0].id).toBe('a');
+    expect(flow.topReferenced[0].referenceCount).toBe(10);
+  });
+
+  it('应该限制 topN', () => {
+    const entries = [
+      makeEntry({ id: 'a' }),
+      makeEntry({ id: 'b' }),
+      makeEntry({ id: 'c' }),
+    ];
+    const refCounts = new Map<string, number>([
+      ['a', 3], ['b', 2], ['c', 1],
+    ]);
+
+    const flow = computeKnowledgeFlow(entries, refCounts, 2);
+    expect(flow.topReferenced.length).toBe(2);
+  });
+
+  it('应该用 created 日期当 lastReferenced 为空', () => {
+    const entries = [
+      makeEntry({ id: 'a', maturity: 'verified', lastReferenced: '' }),
+    ];
+    const flow = computeKnowledgeFlow(entries, new Map());
+    // lastReferenced 为空字符串，不计入 referenced
+    expect(flow.pipeline.referenced).toBe(0);
+  });
+
+  it('应该处理引用了不存在条目的 referenceCount', () => {
+    const entries = [makeEntry({ id: 'a' })];
+    const refCounts = new Map<string, number>([
+      ['a', 5],
+      ['nonexistent', 3],
+    ]);
+
+    const flow = computeKnowledgeFlow(entries, refCounts, 5);
+    const missing = flow.topReferenced.find(t => t.id === 'nonexistent');
+    expect(missing).toBeDefined();
+    expect(missing?.title).toBe('nonexistent'); // fallback to id
+  });
+});
+
+describe('computeInterceptRate', () => {
+  it('应该计算拦截率', () => {
+    expect(computeInterceptRate(100, 22)).toBe(22);
+    expect(computeInterceptRate(10, 0)).toBe(0);
+  });
+
+  it('应该处理零触发', () => {
+    expect(computeInterceptRate(0, 0)).toBe(0);
+  });
+});

package/src/dashboard/data.ts

@@ -0,0 +1,113 @@
+/**
+ * Dashboard 数据聚合
+ *
+ * 从各模块收集数据，生成 HarnessDashboardData
+ * 纯文件读取，零 token 开销
+ */
+
+import type {
+  HarnessDashboardData,
+  KnowledgeOverview,
+  ConstraintHeatmap,
+  KnowledgeFlow,
+  FeedbackLoopStatus,
+} from './types';
+import type { KnowledgeEntry } from '../knowledge/types';
+import type { ConstraintStats } from '../constraints/types';
+import { computeKnowledgeOverview, computeKnowledgeFlow, computeInterceptRate } from './stats';
+import { ConstraintRegistry } from '../constraints/registry';
+
+export class DashboardDataProvider {
+  private registry: ConstraintRegistry;
+
+  constructor(registry?: ConstraintRegistry) {
+    this.registry = registry ?? new ConstraintRegistry();
+  }
+
+  /**
+   * 生成完整 Dashboard 数据
+   */
+  generate(
+    entries: KnowledgeEntry[],
+    constraintStats: ConstraintStats[] = [],
+    referenceCounts: Map<string, number> = new Map(),
+  ): HarnessDashboardData {
+    return {
+      timestamp: new Date().toISOString(),
+      knowledgeOverview: this.getKnowledgeOverview(entries),
+      constraintHeatmap: this.getConstraintHeatmap(constraintStats),
+      knowledgeFlow: this.getKnowledgeFlow(entries, referenceCounts),
+      feedbackLoop: this.getFeedbackLoop(),
+    };
+  }
+
+  /**
+   * 知识库全景
+   */
+  getKnowledgeOverview(entries: KnowledgeEntry[]): KnowledgeOverview {
+    return computeKnowledgeOverview(entries);
+  }
+
+  /**
+   * 约束执行热力图
+   */
+  getConstraintHeatmap(stats: ConstraintStats[]): ConstraintHeatmap {
+    const allConstraints = this.registry.getAll();
+
+    const constraints = allConstraints.map(c => {
+      const stat = stats.find(s => s.constraintId === c.id);
+      return {
+        id: c.id,
+        layer: c.layer,
+        trigger: stat?.triggerCount ?? 0,
+        pass: stat?.passCount ?? 0,
+        intercept: stat?.interceptCount ?? 0,
+        interceptRate: stat ? computeInterceptRate(stat.triggerCount, stat.interceptCount) : 0,
+        deprecationStatus: c.deprecationStatus,
+        permanent: c.permanent,
+      };
+    });
+
+    const neverTriggered = constraints.filter(c => c.trigger === 0).map(c => c.id);
+
+    const decliningInterceptRate = constraints
+      .filter(c => c.interceptRate > 0 && c.interceptRate < 15)
+      .map(c => ({ id: c.id, from: c.interceptRate, to: c.interceptRate }));
+
+    return {
+      period: '近 30 天',
+      constraints,
+      neverTriggered,
+      decliningInterceptRate,
+    };
+  }
+
+  /**
+   * 知识流转路径
+   */
+  getKnowledgeFlow(
+    entries: KnowledgeEntry[],
+    referenceCounts: Map<string, number>,
+  ): KnowledgeFlow {
+    return computeKnowledgeFlow(entries, referenceCounts);
+  }
+
+  /**
+   * 反馈环状态（基础实现，需要外部数据源补充）
+   */
+  getFeedbackLoop(): FeedbackLoopStatus {
+    return {
+      local: { active: 0 },
+      push: { active: 0 },
+      external: { active: 0 },
+      feedbackToKnowledge: { total: 0, pending: 0 },
+    };
+  }
+
+  /**
+   * 获取约束注册表
+   */
+  getRegistry(): ConstraintRegistry {
+    return this.registry;
+  }
+}

package/src/dashboard/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './stats';
+export * from './data';

package/src/dashboard/stats.ts

@@ -0,0 +1,127 @@
+/**
+ * Dashboard 统计计算
+ *
+ * 纯函数，从原始数据计算统计指标
+ */
+
+import type { KnowledgeEntry, KnowledgeType, MaturityLevel } from '../knowledge/types';
+import type { KnowledgeOverview, KnowledgeFlow } from './types';
+
+/**
+ * 计算知识库概览
+ */
+export function computeKnowledgeOverview(entries: KnowledgeEntry[]): KnowledgeOverview {
+  const byType = computeByType(entries);
+  const total = entries.length;
+  const proven = entries.filter(e => e.maturity === 'proven').length;
+  const verified = entries.filter(e => e.maturity === 'verified').length;
+  const draft = entries.filter(e => e.maturity === 'draft').length;
+
+  return {
+    byType,
+    total,
+    maturityDistribution: {
+      proven,
+      verified,
+      draft,
+      provenPercent: total > 0 ? Math.round((proven / total) * 100) : 0,
+      verifiedPercent: total > 0 ? Math.round((verified / total) * 100) : 0,
+      draftPercent: total > 0 ? Math.round((draft / total) * 100) : 0,
+    },
+    decayWarning: computeDecayWarning(entries),
+  };
+}
+
+/**
+ * 按类型分组统计
+ */
+function computeByType(entries: KnowledgeEntry[]): KnowledgeOverview['byType'] {
+  const typeMap = new Map<KnowledgeType, { total: number; proven: number; verified: number; draft: number }>();
+
+  for (const entry of entries) {
+    const existing = typeMap.get(entry.type) || { total: 0, proven: 0, verified: 0, draft: 0 };
+    existing.total++;
+    if (entry.maturity === 'proven') existing.proven++;
+    else if (entry.maturity === 'verified') existing.verified++;
+    else if (entry.maturity === 'draft') existing.draft++;
+    typeMap.set(entry.type, existing);
+  }
+
+  return [...typeMap.entries()].map(([type, stats]) => ({ type, ...stats }));
+}
+
+/**
+ * 计算衰减预警
+ */
+function computeDecayWarning(entries: KnowledgeEntry[]): KnowledgeOverview['decayWarning'] {
+  const now = new Date();
+  const sixMonthsAgo = new Date(now);
+  sixMonthsAgo.setMonth(sixMonthsAgo.getMonth() - 6);
+  const threeMonthsAgo = new Date(now);
+  threeMonthsAgo.setMonth(threeMonthsAgo.getMonth() - 3);
+
+  let provenUnused6m = 0;
+  let verifiedUnused3m = 0;
+
+  for (const entry of entries) {
+    const lastRef = entry.lastReferenced ? new Date(entry.lastReferenced) : new Date(entry.created);
+
+    if (entry.maturity === 'proven' && lastRef < sixMonthsAgo) {
+      provenUnused6m++;
+    }
+    if (entry.maturity === 'verified' && lastRef < threeMonthsAgo) {
+      verifiedUnused3m++;
+    }
+  }
+
+  return { provenUnused6m, verifiedUnused3m };
+}
+
+/**
+ * 计算知识流转统计
+ */
+export function computeKnowledgeFlow(
+  entries: KnowledgeEntry[],
+  referenceCounts: Map<string, number>,
+  topN: number = 5,
+): KnowledgeFlow {
+  // 成熟度转换统计（基于当前状态推断）
+  const transitions = {
+    draftToVerified: entries.filter(e => e.maturity === 'verified' && e.lastReferenced).length,
+    verifiedToProven: entries.filter(e => e.maturity === 'proven').length,
+    provenToVerified: 0, // 需要历史数据
+    verifiedToDraft: 0,  // 需要历史数据
+  };
+
+  // Top N 高频引用
+  const topReferenced = [...referenceCounts.entries()]
+    .map(([id, count]) => {
+      const entry = entries.find(e => e.id === id);
+      return { id, title: entry?.title ?? id, referenceCount: count };
+    })
+    .sort((a, b) => b.referenceCount - a.referenceCount)
+    .slice(0, topN);
+
+  const referenced = entries.filter(e => e.lastReferenced).length;
+
+  return {
+    period: '近 30 天',
+    pipeline: {
+      extracted: 0,   // 需要 ingestion 日志
+      ingested: 0,     // 需要 ingestion 日志
+      referenced,
+      upgraded: transitions.draftToVerified + transitions.verifiedToProven,
+      downgraded: transitions.provenToVerified + transitions.verifiedToDraft,
+    },
+    transitions,
+    topReferenced,
+  };
+}
+
+/**
+ * 计算约束拦截率
+ */
+export function computeInterceptRate(triggerCount: number, interceptCount: number): number {
+  if (triggerCount === 0) return 0;
+  return Math.round((interceptCount / triggerCount) * 100);
+}

package/src/dashboard/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Dashboard 数据类型定义
+ *
+ * harness 提供数据，studio 负责渲染
+ */
+
+import type { KnowledgeType, MaturityLevel } from '../knowledge/types';
+import type { ConstraintLayer, DeprecationStatus } from '../constraints/types';
+
+// ── 知识库全景 ───────────────────────────────────────────
+
+export interface KnowledgeOverview {
+  byType: Array<{
+    type: KnowledgeType;
+    total: number;
+    proven: number;
+    verified: number;
+    draft: number;
+  }>;
+  total: number;
+  maturityDistribution: {
+    proven: number;
+    verified: number;
+    draft: number;
+    provenPercent: number;
+    verifiedPercent: number;
+    draftPercent: number;
+  };
+  decayWarning: {
+    provenUnused6m: number;
+    verifiedUnused3m: number;
+  };
+}
+
+// ── 约束执行热力图 ───────────────────────────────────────
+
+export interface ConstraintHeatmap {
+  period: string; // e.g. "近 30 天"
+  constraints: Array<{
+    id: string;
+    layer: ConstraintLayer;
+    trigger: number;
+    pass: number;
+    intercept: number;
+    interceptRate: number;
+    deprecationStatus: DeprecationStatus;
+    permanent?: boolean;
+  }>;
+  neverTriggered: string[];
+  decliningInterceptRate: Array<{
+    id: string;
+    from: number;
+    to: number;
+  }>;
+}
+
+// ── 知识流转路径 ─────────────────────────────────────────
+
+export interface KnowledgeFlow {
+  period: string;
+  pipeline: {
+    extracted: number;
+    ingested: number;
+    referenced: number;
+    upgraded: number;
+    downgraded: number;
+  };
+  transitions: {
+    draftToVerified: number;
+    verifiedToProven: number;
+    provenToVerified: number;
+    verifiedToDraft: number;
+  };
+  topReferenced: Array<{
+    id: string;
+    title: string;
+    referenceCount: number;
+  }>;
+}
+
+// ── 反馈环状态 ───────────────────────────────────────────
+
+export interface FeedbackLoopStatus {
+  local: {
+    active: number;
+    lastFeedback?: string;
+    lastType?: string;
+  };
+  push: {
+    active: number;
+    lastFeedback?: string;
+    lastType?: string;
+  };
+  external: {
+    active: number;
+    lastFeedback?: string;
+    lastType?: string;
+  };
+  feedbackToKnowledge: {
+    total: number;
+    pending: number;
+  };
+}
+
+// ── 汇总 ────────────────────────────────────────────────
+
+export interface HarnessDashboardData {
+  timestamp: string;
+  knowledgeOverview: KnowledgeOverview;
+  constraintHeatmap: ConstraintHeatmap;
+  knowledgeFlow: KnowledgeFlow;
+  feedbackLoop: FeedbackLoopStatus;
+}

package/src/evolution/CONTEXT.md

@@ -0,0 +1,22 @@
+# evolution/
+
+## 职责
+约束自动进化：基于 trace 分析自动生成约束优化提案(autoEvolve)。
+
+## 核心导出
+- `auto-evolve.ts` — autoEvolve(): 纯计算 API，基于 trace 分析生成进化提案
+
+## 依赖关系
+- 依赖 `src/monitoring/` TraceAnalyzer / ConstraintEvolver
+- 依赖 `src/core/constraints/` 约束定义
+- 被 `src/cli/commands/flow.ts` CLI 消费(auto-apply)
+
+## 约定
+- autoEvolve() 是纯计算函数，不调用 LLM
+- 进化提案由 ConstraintEvolver 生成
+- 低风险提案可自动应用(flow --auto-apply)
+
+## 注意事项
+- 约束退化基于拦截率(不基于日历时间)
+- Iron Law: 拦截率 < 5%(≥100 次检查) → guideline
+- Guideline: 拦截率 < 30%(≥10 次检查) → tip