@dommaker/harness 1.1.0 → 1.2.0

package/src/monitoring/__tests__/performance-collector.test.ts

@@ -1,331 +0,0 @@
-/**
- * PerformanceCollector 测试
- */
-
-import { describe, it, expect, beforeEach } from '@jest/globals';
-import { PerformanceCollector } from '../performance-collector';
-import * as fs from 'fs';
-
-// Mock fs
-jest.mock('fs', () => ({
-  existsSync: jest.fn(),
-  mkdirSync: jest.fn(),
-  appendFileSync: jest.fn(),
-  statSync: jest.fn().mockReturnValue({ size: 100 }),
-  renameSync: jest.fn(),
-  writeFileSync: jest.fn(),
-  readdirSync: jest.fn().mockReturnValue([]),
-  readFileSync: jest.fn().mockReturnValue(''),
-}));
-
-const mockFs = fs as jest.Mocked<typeof fs>;
-
-describe('PerformanceCollector', () => {
-  let collector: PerformanceCollector;
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-    mockFs.existsSync.mockReturnValue(true);
-    mockFs.statSync.mockReturnValue({ size: 100 } as any);
-    collector = new PerformanceCollector();
-  });
-
-  describe('constructor', () => {
-    it('should create log directory if not exists', () => {
-      mockFs.existsSync.mockReturnValueOnce(false);
-      new PerformanceCollector();
-      expect(mockFs.mkdirSync).toHaveBeenCalled();
-    });
-
-    it('should be disabled when enabled=false', () => {
-      const disabledCollector = new PerformanceCollector({ enabled: false });
-      disabledCollector.recordOk('test', 100);
-      expect(mockFs.appendFileSync).not.toHaveBeenCalled();
-    });
-
-    it('should accept custom config', () => {
-      const customCollector = new PerformanceCollector({
-        enabled: true,
-        logFile: '.harness/perf.log',
-        maxFileSize: 5 * 1024 * 1024,
-      });
-      expect(customCollector).toBeDefined();
-    });
-
-    it('should use default config', () => {
-      const defaultCollector = new PerformanceCollector();
-      expect(defaultCollector).toBeDefined();
-    });
-  });
-
-  describe('record()', () => {
-    it('should append trace to file', () => {
-      collector.record({
-        operation: 'test',
-        timestamp: Date.now(),
-        duration: 100,
-        result: 'ok',
-      });
-      expect(mockFs.appendFileSync).toHaveBeenCalled();
-    });
-
-    it('should not record when disabled', () => {
-      const disabledCollector = new PerformanceCollector({ enabled: false });
-      disabledCollector.record({
-        operation: 'test',
-        timestamp: Date.now(),
-        duration: 100,
-        result: 'ok',
-      });
-      expect(mockFs.appendFileSync).not.toHaveBeenCalled();
-    });
-
-    it('should record with all fields', () => {
-      collector.record({
-        operation: 'full-test',
-        timestamp: 1234567890,
-        duration: 500,
-        result: 'exceeded',
-        threshold: 300,
-        metadata: { key: 'value' },
-      });
-      expect(mockFs.appendFileSync).toHaveBeenCalled();
-      const call = mockFs.appendFileSync.mock.calls[0];
-      const content = call[1] as string;
-      expect(content).toContain('full-test');
-      expect(content).toContain('exceeded');
-    });
-  });
-
-  describe('recordOk()', () => {
-    it('should record ok trace', () => {
-      collector.recordOk('test', 150);
-      const call = mockFs.appendFileSync.mock.calls[0];
-      const content = call[1] as string;
-      const trace = JSON.parse(content.trim());
-      expect(trace.result).toBe('ok');
-      expect(trace.operation).toBe('test');
-      expect(trace.duration).toBe(150);
-    });
-
-    it('should record with metadata', () => {
-      collector.recordOk('test', 100, { key: 'value' });
-      const call = mockFs.appendFileSync.mock.calls[0];
-      const content = call[1] as string;
-      const trace = JSON.parse(content.trim());
-      expect(trace.metadata).toEqual({ key: 'value' });
-    });
-
-    it('should auto-generate timestamp', () => {
-      collector.recordOk('test', 100);
-      const call = mockFs.appendFileSync.mock.calls[0];
-      const content = call[1] as string;
-      const trace = JSON.parse(content.trim());
-      expect(trace.timestamp).toBeDefined();
-      expect(typeof trace.timestamp).toBe('number');
-    });
-
-    it('should not record when disabled', () => {
-      const disabledCollector = new PerformanceCollector({ enabled: false });
-      disabledCollector.recordOk('test', 100);
-      expect(mockFs.appendFileSync).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('recordExceeded()', () => {
-    it('should record exceeded trace', () => {
-      collector.recordExceeded('test', 35000, 30000);
-      const call = mockFs.appendFileSync.mock.calls[0];
-      const content = call[1] as string;
-      const trace = JSON.parse(content.trim());
-      expect(trace.result).toBe('exceeded');
-      expect(trace.threshold).toBe(30000);
-    });
-
-    it('should include duration', () => {
-      collector.recordExceeded('test', 35000, 30000);
-      const call = mockFs.appendFileSync.mock.calls[0];
-      const content = call[1] as string;
-      const trace = JSON.parse(content.trim());
-      expect(trace.duration).toBe(35000);
-    });
-
-    it('should not record when disabled', () => {
-      const disabledCollector = new PerformanceCollector({ enabled: false });
-      disabledCollector.recordExceeded('test', 35000, 30000);
-      expect(mockFs.appendFileSync).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('recordError()', () => {
-    it('should record error trace', () => {
-      collector.recordError('test', 100, 'Test error');
-      const call = mockFs.appendFileSync.mock.calls[0];
-      const content = call[1] as string;
-      const trace = JSON.parse(content.trim());
-      expect(trace.result).toBe('error');
-      expect(trace.metadata.error).toBe('Test error');
-    });
-
-    it('should include duration', () => {
-      collector.recordError('test', 100, 'Test error');
-      const call = mockFs.appendFileSync.mock.calls[0];
-      const content = call[1] as string;
-      const trace = JSON.parse(content.trim());
-      expect(trace.duration).toBe(100);
-    });
-
-    it('should not record when disabled', () => {
-      const disabledCollector = new PerformanceCollector({ enabled: false });
-      disabledCollector.recordError('test', 100, 'Test error');
-      expect(mockFs.appendFileSync).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('read()', () => {
-    it('should return empty array if file not exists', () => {
-      mockFs.existsSync.mockReturnValueOnce(false);
-      const c = new PerformanceCollector();
-      const traces = c.read();
-      expect(traces).toEqual([]);
-    });
-
-    it('should return traces from file', () => {
-      mockFs.existsSync.mockReturnValue(true);
-      mockFs.readFileSync.mockReturnValueOnce(
-        JSON.stringify({ operation: 'test1', duration: 100, result: 'ok', timestamp: 1 }) + '\n' +
-        JSON.stringify({ operation: 'test2', duration: 200, result: 'ok', timestamp: 2 }) + '\n'
-      );
-      
-      const c = new PerformanceCollector();
-      const traces = c.read();
-      expect(traces.length).toBe(2);
-      expect(traces[0].operation).toBe('test1');
-      expect(traces[1].operation).toBe('test2');
-    });
-
-    it('should handle empty file', () => {
-      mockFs.existsSync.mockReturnValue(true);
-      mockFs.readFileSync.mockReturnValueOnce('');
-      
-      const c = new PerformanceCollector();
-      const traces = c.read();
-      expect(traces).toEqual([]);
-    });
-
-    it('should filter by period', () => {
-      mockFs.existsSync.mockReturnValue(true);
-      mockFs.readFileSync.mockReturnValueOnce(
-        JSON.stringify({ operation: 'test1', duration: 100, result: 'ok', timestamp: Date.now() - 100000 }) + '\n' +
-        JSON.stringify({ operation: 'test2', duration: 200, result: 'ok', timestamp: Date.now() }) + '\n'
-      );
-      
-      const c = new PerformanceCollector();
-      const traces = c.read({ timeRange: { start: Date.now() - 50000, end: Date.now() } });
-      expect(traces.length).toBe(1);
-      expect(traces[0].operation).toBe('test2');
-    });
-
-    it('should filter by operation', () => {
-      mockFs.existsSync.mockReturnValue(true);
-      mockFs.readFileSync.mockReturnValueOnce(
-        JSON.stringify({ operation: 'test1', duration: 100, result: 'ok', timestamp: Date.now() }) + '\n' +
-        JSON.stringify({ operation: 'test2', duration: 200, result: 'ok', timestamp: Date.now() }) + '\n'
-      );
-      
-      const c = new PerformanceCollector();
-      const traces = c.read({ operation: 'test1' });
-      expect(traces.length).toBe(1);
-      expect(traces[0].operation).toBe('test1');
-    });
-
-    it('should filter by result', () => {
-      mockFs.existsSync.mockReturnValue(true);
-      mockFs.readFileSync.mockReturnValueOnce(
-        JSON.stringify({ operation: 'test1', duration: 100, result: 'ok', timestamp: Date.now() }) + '\n' +
-        JSON.stringify({ operation: 'test2', duration: 200, result: 'exceeded', timestamp: Date.now() }) + '\n'
-      );
-      
-      const c = new PerformanceCollector();
-      const traces = c.read({ result: 'exceeded' });
-      expect(traces.length).toBe(1);
-      expect(traces[0].result).toBe('exceeded');
-    });
-  });
-
-  describe('getStats()', () => {
-    it('should return stats', () => {
-      mockFs.existsSync.mockReturnValue(true);
-      mockFs.statSync.mockReturnValue({ size: 1024 } as any);
-      
-      const stats = collector.getStats();
-      expect(stats).toHaveProperty('fileExists');
-    });
-
-    it('should return stats when file not exists', () => {
-      // 先让目录检查通过，再让文件检查失败
-      mockFs.existsSync
-        .mockReturnValueOnce(true) // 目录检查
-        .mockReturnValueOnce(false); // 文件检查
-      
-      const c = new PerformanceCollector();
-      mockFs.existsSync.mockReturnValue(false); // getStats 检查
-      const stats = c.getStats();
-      expect(stats.fileExists).toBe(false);
-    });
-
-    it('should include file size', () => {
-      mockFs.existsSync.mockReturnValue(true);
-      mockFs.statSync.mockReturnValue({ size: 2048 } as any);
-      
-      const stats = collector.getStats();
-      expect(stats.fileSize).toBe(2048);
-    });
-  });
-
-  describe('file rolling', () => {
-    it('should roll file when size exceeds limit', () => {
-      mockFs.statSync.mockReturnValue({ size: 15 * 1024 * 1024 } as any); // 15MB
-      
-      collector.recordOk('test', 100);
-      expect(mockFs.renameSync).toHaveBeenCalled();
-    });
-
-    it('should not roll when under limit', () => {
-      mockFs.statSync.mockReturnValue({ size: 5 * 1024 * 1024 } as any); // 5MB
-      
-      collector.recordOk('test', 100);
-      expect(mockFs.renameSync).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('clear()', () => {
-    it('should exist if implemented', () => {
-      // Check if method exists
-      const hasClear = typeof (collector as any).clear === 'function';
-      if (hasClear) {
-        mockFs.existsSync.mockReturnValue(true);
-        (collector as any).clear();
-        expect(mockFs.writeFileSync).toHaveBeenCalled();
-      }
-    });
-  });
-
-  describe('getRecentTraces()', () => {
-    it('should return recent traces', () => {
-      mockFs.existsSync.mockReturnValue(true);
-      mockFs.readFileSync.mockReturnValueOnce(
-        JSON.stringify({ operation: 'test1', duration: 100, result: 'ok', timestamp: Date.now() }) + '\n' +
-        JSON.stringify({ operation: 'test2', duration: 200, result: 'ok', timestamp: Date.now() }) + '\n' +
-        JSON.stringify({ operation: 'test3', duration: 300, result: 'ok', timestamp: Date.now() }) + '\n'
-      );
-      
-      // Check if method exists
-      const hasRecent = typeof (collector as any).getRecentTraces === 'function';
-      if (hasRecent) {
-        const traces = (collector as any).getRecentTraces(2);
-        expect(traces.length).toBe(2);
-      }
-    });
-  });
-});

package/src/monitoring/constraint-doctor.ts

@@ -1,239 +0,0 @@
-/**
- * 约束诊断器
- *
- * 当检测到异常时，基于预设规则分析 traces 给出诊断（零 Token，不调用 LLM）。
- */
-
-import type {
-  ExecutionTrace,
-  TraceAnomaly,
-  TraceSummary,
-} from '../types/trace';
-import type { Diagnosis } from '../types/monitoring-types';
-import { DIAGNOSIS_RULES } from './diagnosis-rules';
-
-// 类型定义已归位 types 层（工单 14），此处再导出保持模块公开面不变
-export type { Diagnosis };
-
-/**
- * 诊断配置
- */
-export interface ConstraintDoctorConfig {
-  /** 是否启用 Agent 诊断（默认 false，需要显式启用） */
-  enabled?: boolean;
-
-  /** Agent 类型（预留，后续对接） */
-  agentType?: 'claude-code' | 'codex' | 'openai';
-
-  /** 最大 traces 数量（用于构造 prompt） */
-  maxTracesInPrompt?: number;
-
-  /** 是否自动生成提案 */
-  autoGenerateProposal?: boolean;
-}
-
-/**
- * Constraint Doctor - 约束诊断器
- *
- * 使用方式：
- * ```typescript
- * const doctor = new ConstraintDoctor(analyzer);
- * const diagnosis = await doctor.diagnose(anomaly);
- *
- * if (diagnosis.needsChange) {
- *   const proposal = await evolver.propose(diagnosis);
- * }
- * ```
- */
-export class ConstraintDoctor {
-  private config: ConstraintDoctorConfig;
-  private traces: ExecutionTrace[];
-
-  constructor(config?: ConstraintDoctorConfig) {
-    this.config = {
-      enabled: false,
-      maxTracesInPrompt: 20,
-      autoGenerateProposal: false,
-      ...config,
-    };
-    this.traces = [];
-  }
-
-  /**
-   * 设置诊断数据
-   */
-  setData(traces: ExecutionTrace[], _summary?: TraceSummary): void {
-    this.traces = traces;
-  }
-
-  /**
-   * 诊断异常
- *
-   * 如果 Agent 未启用，返回基于规则的诊断
-   */
-  async diagnose(anomaly: TraceAnomaly): Promise<Diagnosis> {
-    // 过滤相关 traces
-    const relevantTraces = this.filterRelevantTraces(anomaly);
-
-    // 基于规则的诊断（不消耗 Token）
-    return this.ruleBasedDiagnose(anomaly, relevantTraces);
-  }
-
-  /**
-   * 基于规则的诊断（零 Token）
- *
-   * 根据异常类型应用预设的诊断规则
-   */
-  private ruleBasedDiagnose(
-    anomaly: TraceAnomaly,
-    traces: ExecutionTrace[]
-  ): Diagnosis {
-    const diagnosis: Diagnosis = {
-      anomalyId: `${anomaly.constraintId}-${anomaly.type}-${Date.now()}`,
-      constraintId: anomaly.constraintId,
-      diagnosedAt: Date.now(),
-      rootCause: {
-        primary: '',
-        secondary: [],
-        evidence: traces.slice(0, this.config.maxTracesInPrompt!),
-      },
-      impact: {
-        severity: 'medium',
-        scope: 'single_project',
-        userImpact: '',
-      },
-      recommendations: [],
-      needsChange: false,
-      urgency: 'low',
-    };
-
-    // 根据异常类型诊断（工单 23-B：规则数据化，见 diagnosis-rules.ts）
-    const rule = DIAGNOSIS_RULES[anomaly.type];
-    if (rule) {
-      diagnosis.rootCause.primary = rule.primary;
-      diagnosis.rootCause.secondary = rule.secondary;
-      diagnosis.impact.userImpact = rule.userImpact;
-      diagnosis.recommendations = rule.recommendations(anomaly);
-      diagnosis.needsChange = rule.needsChange;
-      diagnosis.urgency = rule.urgency(anomaly);
-    }
-
-    // 根据约束层级调整严重性
-    if (anomaly.level === 'iron_law') {
-      diagnosis.impact.severity = 'high';
-      diagnosis.urgency = 'medium'; // Iron law 总是至少 medium
-    }
-
-    return diagnosis;
-  }
-
-  /**
-   * 过滤相关 traces
-   *
-   * 只保留与异常相关的 traces，减少 prompt 内容
-   */
-  private filterRelevantTraces(anomaly: TraceAnomaly): ExecutionTrace[] {
-    return this.traces.filter(t => {
-      // 必须是同一个约束
-      if (t.constraintId !== anomaly.constraintId) return false;
-
-      // 失败或绕过的更有诊断价值
-      if (t.result === 'fail' || t.result === 'bypassed') return true;
-
-      // 保留少量通过的作为对比
-      return true;
-    });
-  }
-
-  /**
-   * 批量诊断多个异常
-   */
-  async diagnoseBatch(anomalies: TraceAnomaly[]): Promise<Diagnosis[]> {
-    return Promise.all(anomalies.map(a => this.diagnose(a)));
-  }
-
-  /**
-   * 生成诊断报告（文本格式）
-   */
-  generateReport(diagnosis: Diagnosis): string {
-    const lines: string[] = [];
-
-    lines.push(`# Diagnosis Report`);
-    lines.push(`Constraint: ${diagnosis.constraintId}`);
-    lines.push(`Anomaly: ${diagnosis.anomalyId}`);
-    lines.push(`Diagnosed: ${new Date(diagnosis.diagnosedAt).toISOString()}`);
-    lines.push('');
-
-    // 根因
-    lines.push(`## Root Cause`);
-    lines.push('');
-    lines.push(`**Primary**: ${diagnosis.rootCause.primary}`);
-    if (diagnosis.rootCause.secondary?.length) {
-      lines.push('');
-      lines.push('**Secondary**:');
-      for (const s of diagnosis.rootCause.secondary) {
-        lines.push(`- ${s}`);
-      }
-    }
-    lines.push('');
-
-    // 影响
-    lines.push(`## Impact`);
-    lines.push('');
-    lines.push(`- Severity: ${diagnosis.impact.severity}`);
-    lines.push(`- Scope: ${diagnosis.impact.scope}`);
-    lines.push(`- User Impact: ${diagnosis.impact.userImpact}`);
-    lines.push('');
-
-    // 建议
-    lines.push(`## Recommendations`);
-    lines.push('');
-
-    for (const r of diagnosis.recommendations) {
-      lines.push(`### ${r.type}`);
-      lines.push(`- Content: ${r.content}`);
-      lines.push(`- Expected: ${r.expectedOutcome}`);
-      lines.push(`- Cost: ${r.implementationCost}`);
-      lines.push('');
-    }
-
-    // 决策
-    lines.push(`## Decision`);
-    lines.push('');
-    lines.push(`- Needs Change: ${diagnosis.needsChange ? '✅ Yes' : '❌ No'}`);
-    lines.push(`- Urgency: ${diagnosis.urgency}`);
-
-    return lines.join('\n');
-  }
-
-  /**
-   * 保存诊断结果
-   */
-  saveDiagnosis(diagnosis: Diagnosis, outputPath: string): void {
-    const fs = require('fs');
-    const path = require('path');
-
-    const dir = path.dirname(outputPath);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-
-    fs.writeFileSync(outputPath, JSON.stringify(diagnosis, null, 2), 'utf-8');
-  }
-
-  /**
-   * 加载诊断结果
-   */
-  loadDiagnosis(inputPath: string): Diagnosis {
-    const fs = require('fs');
-    const content = fs.readFileSync(inputPath, 'utf-8');
-    return JSON.parse(content) as Diagnosis;
-  }
-}
-
-/**
- * 创建诊断器
- */
-export function createDoctor(config?: ConstraintDoctorConfig): ConstraintDoctor {
-  return new ConstraintDoctor(config);
-}

package/src/monitoring/diagnosis-rules.ts

@@ -1,132 +0,0 @@
-/**
- * 诊断规则表（工单 23-B）
- *
- * constraint-doctor.ruleBasedDiagnose 的巨型 switch 数据化：
- * 每种异常类型一条规则（根因/影响/建议/紧急度），新增异常类型只需加表项。
- */
-
-import type { TraceAnomaly } from '../types/trace';
-import type { Diagnosis } from '../types/monitoring-types';
-
-export interface DiagnosisRule {
-  primary: string;
-  secondary: string[];
-  userImpact: string;
-  recommendations: (anomaly: TraceAnomaly) => Diagnosis['recommendations'];
-  needsChange: boolean;
-  urgency: (anomaly: TraceAnomaly) => Diagnosis['urgency'];
-}
-
-export const DIAGNOSIS_RULES: Record<string, DiagnosisRule> = {
-  high_bypass_rate: {
-    primary: '约束过于严格，用户频繁绕过',
-    secondary: [
-      '约束触发条件过于宽泛',
-      '缺乏必要的例外条件',
-      '约束定义与实际场景不匹配',
-    ],
-    userImpact: '用户被迫绕过约束，降低信任度',
-    recommendations: (anomaly) => [
-      {
-        type: 'add_exception',
-        content: `为约束 ${anomaly.constraintId} 添加常见例外条件`,
-        expectedOutcome: '绕过率降低至 20% 以下',
-        implementationCost: 'low',
-      },
-      {
-        type: 'adjust_threshold',
-        content: '调整触发条件，减少误触发',
-        expectedOutcome: '减少不必要的约束检查',
-        implementationCost: 'medium',
-      },
-    ],
-    needsChange: true,
-    urgency: (anomaly) => ((anomaly.data.currentRate as number) > 0.5 ? 'high' : 'medium'),
-  },
-
-  rising_fail_rate: {
-    primary: '约束失败率呈上升趋势',
-    secondary: [
-      '代码质量下降',
-      '约束检查逻辑存在 bug',
-      '环境变化导致约束不再适用',
-    ],
-    userImpact: '开发效率下降，约束频繁阻止正常操作',
-    recommendations: () => [
-      {
-        type: 'modify_constraint',
-        content: '审查约束逻辑，确认是否符合预期',
-        expectedOutcome: '恢复正常的失败率水平',
-        implementationCost: 'medium',
-      },
-      {
-        type: 'user_training',
-        content: '指导用户正确理解约束要求',
-        expectedOutcome: '减少因误解导致的失败',
-        implementationCost: 'low',
-      },
-    ],
-    needsChange: true,
-    urgency: () => 'medium',
-  },
-
-  rising_bypass_rate: {
-    primary: '绕过率呈上升趋势',
-    secondary: [
-      '用户对约束的接受度下降',
-      '约束规则逐渐不适应新的开发模式',
-      '用户发现了绕过约束的"捷径"',
-    ],
-    userImpact: '约束逐渐失去约束力',
-    recommendations: () => [
-      {
-        type: 'modify_constraint',
-        content: '重新评估约束的必要性',
-        expectedOutcome: '恢复约束的权威性',
-        implementationCost: 'high',
-      },
-    ],
-    needsChange: true,
-    urgency: () => 'high',
-  },
-
-  low_pass_rate: {
-    primary: '约束通过率过低',
-    secondary: [
-      '约束要求过于严格',
-      '实际代码质量不达标',
-      '约束定义存在歧义',
-    ],
-    userImpact: '几乎所有操作都被阻止，开发受阻',
-    recommendations: () => [
-      {
-        type: 'adjust_threshold',
-        content: '放宽约束要求，设置合理阈值',
-        expectedOutcome: '通过率提升至 50% 以上',
-        implementationCost: 'low',
-      },
-    ],
-    needsChange: true,
-    urgency: () => 'high',
-  },
-
-  exception_overuse: {
-    primary: '例外条件被过度使用',
-    secondary: [
-      '例外条件过于宽泛',
-      '例外条件定义不够精确',
-      '用户习惯性申请例外',
-    ],
-    userImpact: '例外成为常态，约束失去意义',
-    recommendations: () => [
-      {
-        type: 'modify_constraint',
-        content: '缩小例外条件范围，提高例外门槛',
-        expectedOutcome: '例外使用率降低至 20% 以下',
-        implementationCost: 'medium',
-      },
-    ],
-    needsChange: true,
-    urgency: () => 'medium',
-  },
-};