@dommaker/harness 0.13.0 → 0.13.2

package/src/cli/commands/validate.ts

@@ -0,0 +1,222 @@
+/**
+ * harness validate 命令
+ * 
+ * 验证检查点是否满足
+ */
+
+import chalk from 'chalk';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { CheckpointValidator } from '../../core/validators/checkpoint';
+import type { Checkpoint, CheckpointContext } from '../../types/checkpoint';
+import { detectSourceRoots } from '../../utils/detect-source-roots';
+
+export interface ValidateOptions {
+  /** 检查点文件路径 */
+  file?: string;
+  /** 项目路径 */
+  projectPath?: string;
+  /** 是否严格模式 */
+  strict?: boolean;
+}
+
+/**
+ * 默认检查点文件路径
+ */
+const DEFAULT_CHECKPOINT_FILE = '.harness/checkpoints.yml';
+
+/**
+ * 加载检查点配置
+ */
+async function loadCheckpoints(filePath: string): Promise<Checkpoint[]> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    const data = yaml.load(content) as { checkpoints?: Checkpoint[] };
+    return data.checkpoints || [];
+  } catch (error) {
+    console.log(chalk.yellow(`⚠️  未找到检查点文件: ${filePath}`));
+    return [];
+  }
+}
+
+/**
+ * 执行检查点验证
+ */
+export async function validate(options: ValidateOptions): Promise<void> {
+  console.log(chalk.blue('🔍 验证检查点...'));
+
+  const projectPath = options.projectPath || process.cwd();
+  const checkpointFile = options.file || path.join(projectPath, DEFAULT_CHECKPOINT_FILE);
+
+  // 加载检查点
+  const checkpoints = await loadCheckpoints(checkpointFile);
+
+  if (checkpoints.length === 0) {
+    console.log(chalk.gray('没有定义检查点，跳过验证'));
+    return;
+  }
+
+  console.log(chalk.gray(`检查点文件: ${checkpointFile}`));
+  console.log(chalk.gray(`检查点数量: ${checkpoints.length}`));
+  console.log();
+
+  // 构建上下文
+  const context: CheckpointContext = {
+    projectPath,
+    workdir: projectPath,
+  };
+
+  // 执行验证
+  const validator = CheckpointValidator.getInstance();
+  const results = [];
+
+  for (const checkpoint of checkpoints) {
+    const result = await validator.validate(checkpoint, context);
+    results.push(result);
+
+    if (result.passed) {
+      console.log(chalk.green(`✅ ${checkpoint.id}: 通过`));
+    } else {
+      console.log(chalk.red(`❌ ${checkpoint.id}: 失败`));
+      result.checks.forEach(check => {
+        if (!check.passed) {
+          console.log(chalk.red(`   - ${check.checkId}: ${check.message || check.error}`));
+        }
+      });
+    }
+  }
+
+  // 统计结果
+  const passed = results.filter(r => r.passed).length;
+  const failed = results.filter(r => !r.passed).length;
+
+  console.log();
+  console.log(chalk.gray(`通过: ${passed}/${results.length}`));
+
+  if (failed > 0) {
+    console.log(chalk.red(`\n🛑 ${failed} 个检查点未通过`));
+    if (options.strict) {
+      process.exit(1);
+    }
+  } else {
+    console.log(chalk.green('\n✅ 所有检查点验证通过'));
+  }
+}
+
+/**
+ * 默认检查点列表（供 init 和 upgrade 共用）
+ */
+export const DEFAULT_CHECKPOINTS: Checkpoint[] = [
+  {
+    id: 'build-success',
+    name: '构建成功',
+    checks: [
+      {
+        id: 'build-command',
+        type: 'command_success',
+        config: { command: 'npm run build' },
+        message: '构建命令必须成功执行',
+      },
+    ],
+  },
+  {
+    id: 'test-pass',
+    name: '测试通过',
+    checks: [
+      {
+        id: 'test-command',
+        type: 'command_success',
+        config: { command: 'npm test' },
+        message: '测试命令必须成功执行',
+      },
+    ],
+  },
+  {
+    id: 'no-console',
+    name: '无 console.log',
+    checks: [
+      {
+        id: 'check-console',
+        type: 'output_not_contains',
+        config: {
+          command: 'grep -r "console.log" src/ || true',
+          expected: '',
+        },
+        message: '源代码中不应包含 console.log',
+      },
+    ],
+  },
+];
+
+/**
+ * 创建示例检查点文件
+ */
+export async function createExampleCheckpoint(projectPath: string): Promise<void> {
+  const filePath = path.join(projectPath, DEFAULT_CHECKPOINT_FILE);
+  const dir = path.dirname(filePath);
+
+  await fs.mkdir(dir, { recursive: true });
+
+  // 动态替换 no-console 检查点的源目录
+  const roots = detectSourceRoots(projectPath);
+  let checkpoints = DEFAULT_CHECKPOINTS;
+  if (roots.length > 0) {
+    checkpoints = DEFAULT_CHECKPOINTS.map(cp => {
+      if (cp.id === 'no-console') {
+        return {
+          ...cp,
+          checks: cp.checks.map(c => {
+            if (c.id === 'check-console') {
+              return { ...c, config: { command: `grep -r "console.log" ${roots.join(' ')} || true` } };
+            }
+            return c;
+          }),
+        };
+      }
+      return cp;
+    });
+  }
+
+  const content = yaml.dump({ checkpoints }, { indent: 2 });
+  await fs.writeFile(filePath, content, 'utf-8');
+
+  console.log(chalk.green(`✅ 已创建示例检查点文件: ${filePath}`));
+}
+
+/**
+ * 默认 Resolutions（RKB — 约束 → 已知解法映射）
+ */
+const DEFAULT_RESOLUTIONS = {
+  no_claim_without_evidence: {
+    title: 'commit message 缺少验证证据',
+    fix: '在 commit message body 中附上验证输出:\n`npx harness check --staged` | `npx harness validate` | `npm test -- --coverage`\n确认全部通过后重新 commit。',
+  },
+  capability_sync: {
+    title: '缺少 CAPABILITIES.md',
+    fix: '在项目根目录创建 CAPABILITIES.md，列出所有模块能力清单。运行 `npx harness sync-docs` 可自动生成模板。',
+  },
+  context_doc_sync: {
+    title: '关键目录缺少 CONTEXT.md',
+    fix: '在 required_dirs 目录下创建 CONTEXT.md。运行 `npx harness sync-docs` 可自动生成模板。',
+  },
+  no_coverage_decrease: {
+    title: '测试覆盖率下降',
+    fix: '运行 `npm test -- --coverage` 查看当前覆盖率。新增文件必须有对应的测试文件。',
+  },
+};
+
+/**
+ * 创建示例 Resolutions 文件（RKB dogfood）
+ */
+export async function createExampleResolutions(projectPath: string): Promise<void> {
+  const harnessDir = path.join(projectPath, '.harness');
+  const filePath = path.join(harnessDir, 'resolutions.json');
+
+  await fs.mkdir(harnessDir, { recursive: true });
+
+  const content = JSON.stringify(DEFAULT_RESOLUTIONS, null, 2);
+  await fs.writeFile(filePath, content, 'utf-8');
+
+  console.log(chalk.green(`✅ 已创建 Resolutions 文件: ${filePath}`));
+}

package/src/constraints/__tests__/lifecycle-runner.test.ts

@@ -0,0 +1,246 @@
+/**
+ * ConstraintLifecycleRunner 测试
+ */
+
+import { describe, it, expect, beforeEach } from '@jest/globals';
+import { ConstraintLifecycleRunner, type ExecutionResult } from '../lifecycle-runner';
+import { ConstraintRegistry } from '../registry';
+import type { ConstraintProposal } from '../../monitoring/constraint-evolver';
+
+function makeProposal(overrides: Partial<ConstraintProposal> = {}): ConstraintProposal {
+  return {
+    id: 'test-proposal-1',
+    proposedAt: Date.now(),
+    diagnosisId: 'diag-1',
+    constraintId: 'no_fix_without_root_cause',
+    type: 'change_level',
+    content: { proposed: 'tip', description: '降级为 tip' },
+    reasoning: 'low intercept rate',
+    expectedOutcome: 'fewer interruptions',
+    risk: { level: 'low', description: 'safe' },
+    implementation: { files: [], linesChanged: 0, testsRequired: false },
+    status: 'accepted',
+    ...overrides,
+  };
+}
+
+describe('ConstraintLifecycleRunner', () => {
+  let runner: ConstraintLifecycleRunner;
+  let registry: ConstraintRegistry;
+
+  beforeEach(() => {
+    registry = new ConstraintRegistry();
+    runner = new ConstraintLifecycleRunner(registry);
+  });
+
+  describe('execute - change_level', () => {
+    it('应该成功降级质量层约束', () => {
+      const proposal = makeProposal({
+        constraintId: 'no_fix_without_root_cause',
+        type: 'change_level',
+        content: { proposed: 'tip', description: '降级' },
+      });
+
+      const result = runner.execute(proposal);
+
+      expect(result.success).toBe(true);
+      expect(result.action).toBe('degrade');
+      expect(result.details).toContain('Degraded');
+
+      // 验证 registry 状态已改变
+      const constraint = registry.get('no_fix_without_root_cause');
+      expect(constraint?.deprecationStatus).toBe('deprecated');
+    });
+
+    it('应该拒绝安全层约束的 level 变更', () => {
+      const proposal = makeProposal({
+        constraintId: 'no_bypass_checkpoint',
+        type: 'change_level',
+        content: { proposed: 'guideline', description: '降级' },
+      });
+
+      const result = runner.execute(proposal);
+
+      expect(result.success).toBe(false);
+      expect(result.details).toContain('safety-layer');
+    });
+
+    it('应该返回失败当约束不存在', () => {
+      const proposal = makeProposal({
+        constraintId: 'nonexistent_constraint',
+        type: 'change_level',
+        content: { proposed: 'tip', description: '降级' },
+      });
+
+      const result = runner.execute(proposal);
+
+      expect(result.success).toBe(false);
+      expect(result.details).toContain('not found');
+    });
+  });
+
+  describe('execute - add_exception', () => {
+    it('应该成功添加例外', () => {
+      const proposal = makeProposal({
+        constraintId: 'no_fix_without_root_cause',
+        type: 'add_exception',
+        content: { proposed: 'new_exception', description: '新增例外' },
+      });
+
+      const result = runner.execute(proposal);
+
+      expect(result.success).toBe(true);
+      expect(result.action).toBe('add_exception');
+      expect(result.details).toContain('new_exception');
+
+      const constraint = registry.get('no_fix_without_root_cause');
+      expect(constraint?.exceptions).toContain('new_exception');
+    });
+
+    it('应该拒绝重复的例外', () => {
+      const proposal = makeProposal({
+        constraintId: 'no_fix_without_root_cause',
+        type: 'add_exception',
+        content: { proposed: 'simple_typo', description: '重复例外' },
+      });
+
+      const result = runner.execute(proposal);
+
+      expect(result.success).toBe(false);
+      expect(result.details).toContain('already exists');
+    });
+  });
+
+  describe('execute - adjust_trigger', () => {
+    it('应该成功修改触发条件', () => {
+      const proposal = makeProposal({
+        constraintId: 'no_fix_without_root_cause',
+        type: 'adjust_trigger',
+        content: { proposed: ['code_implementation', 'code_implementation'], description: '扩展触发' },
+      });
+
+      const result = runner.execute(proposal);
+
+      expect(result.success).toBe(true);
+      expect(result.action).toBe('adjust_trigger');
+
+      const constraint = registry.get('no_fix_without_root_cause');
+      expect(constraint?.trigger).toEqual(['code_implementation', 'code_implementation']);
+    });
+  });
+
+  describe('execute - modify_message', () => {
+    it('应该成功修改消息', () => {
+      const proposal = makeProposal({
+        constraintId: 'no_fix_without_root_cause',
+        type: 'modify_message',
+        content: { proposed: '新的消息', description: '更新消息' },
+      });
+
+      const result = runner.execute(proposal);
+
+      expect(result.success).toBe(true);
+      expect(result.action).toBe('modify_message');
+
+      const constraint = registry.get('no_fix_without_root_cause');
+      expect(constraint?.message).toBe('新的消息');
+    });
+  });
+
+  describe('execute - unsupported type', () => {
+    it('应该拒绝不支持的提案类型', () => {
+      const proposal = makeProposal({
+        type: 'new_constraint' as any,
+      });
+
+      const result = runner.execute(proposal);
+
+      expect(result.success).toBe(false);
+      expect(result.details).toContain('Unsupported');
+    });
+  });
+
+  describe('executeBatch', () => {
+    it('应该批量执行多个提案', () => {
+      const proposals = [
+        makeProposal({
+          id: 'p1',
+          constraintId: 'no_fix_without_root_cause',
+          type: 'modify_message',
+          content: { proposed: '消息1', description: '更新' },
+        }),
+        makeProposal({
+          id: 'p2',
+          constraintId: 'no_code_without_test',
+          type: 'modify_message',
+          content: { proposed: '消息2', description: '更新' },
+        }),
+      ];
+
+      const results = runner.executeBatch(proposals);
+
+      expect(results).toHaveLength(2);
+      expect(results[0].success).toBe(true);
+      expect(results[1].success).toBe(true);
+    });
+  });
+
+  describe('rollbackConstraint', () => {
+    it('应该成功回滚已降级的约束', () => {
+      // 先降级
+      const proposal = makeProposal({
+        constraintId: 'no_fix_without_root_cause',
+        type: 'change_level',
+        content: { proposed: 'tip', description: '降级' },
+      });
+      runner.execute(proposal);
+
+      const constraint = registry.get('no_fix_without_root_cause');
+      expect(constraint?.deprecationStatus).toBe('deprecated');
+
+      // 回滚
+      const success = runner.rollbackConstraint('no_fix_without_root_cause', 'guideline');
+      expect(success).toBe(true);
+
+      const after = registry.get('no_fix_without_root_cause');
+      expect(after?.deprecationStatus).toBe('active');
+      expect(after?.level).toBe('guideline');
+    });
+  });
+
+  describe('scheduleDeprecation', () => {
+    it('应该成功设置弃用计划', () => {
+      const success = runner.scheduleDeprecation('no_fix_without_root_cause', {
+        targetLevel: 'tip',
+        reason: 'low usage',
+        rollbackable: true,
+      });
+
+      expect(success).toBe(true);
+
+      const constraint = registry.get('no_fix_without_root_cause');
+      expect(constraint?.deprecationStatus).toBe('scheduled');
+    });
+
+    it('应该拒绝安全层约束的弃用计划', () => {
+      const success = runner.scheduleDeprecation('no_bypass_checkpoint', {
+        targetLevel: 'guideline',
+        reason: 'test',
+        rollbackable: false,
+      });
+
+      expect(success).toBe(false);
+    });
+  });
+
+  describe('getRegistry', () => {
+    it('应该返回内部 registry 实例', () => {
+      expect(runner.getRegistry()).toBe(registry);
+    });
+
+    it('应该在无参数时创建默认 registry', () => {
+      const defaultRunner = new ConstraintLifecycleRunner();
+      expect(defaultRunner.getRegistry()).toBeDefined();
+    });
+  });
+});

package/src/constraints/__tests__/registry.test.ts

@@ -0,0 +1,196 @@
+/**
+ * ConstraintRegistry 测试
+ */
+
+import { ConstraintRegistry } from '../registry';
+import { IRON_LAWS, GUIDELINES, TIPS } from '../../core/constraints/definitions';
+
+const SAFETY_COUNT = Object.keys(IRON_LAWS).length;       // 7
+const QUALITY_COUNT = Object.keys(GUIDELINES).length + Object.keys(TIPS).length; // 13
+
+describe('ConstraintRegistry', () => {
+  let registry: ConstraintRegistry;
+
+  beforeEach(() => {
+    registry = new ConstraintRegistry();
+  });
+
+  describe('get', () => {
+    it('应该获取安全层约束', () => {
+      const constraint = registry.get('no_bypass_checkpoint');
+      expect(constraint).toBeDefined();
+      expect(constraint?.layer).toBe('safety');
+      expect(constraint?.permanent).toBe(false); // 所有层级均可退化
+    });
+
+    it('应该获取质量层约束', () => {
+      const constraint = registry.get('no_any_type');
+      expect(constraint).toBeDefined();
+      expect(constraint?.layer).toBe('quality');
+    });
+
+    it('应该返回 undefined 对于不存在的约束', () => {
+      expect(registry.get('nonexistent')).toBeUndefined();
+    });
+  });
+
+  describe('getAll', () => {
+    it('应该返回所有约束', () => {
+      const all = registry.getAll();
+      expect(all.length).toBe(SAFETY_COUNT + QUALITY_COUNT);
+    });
+  });
+
+  describe('getByLayer', () => {
+    it('应该按层过滤', () => {
+      const safety = registry.getByLayer('safety');
+      const quality = registry.getByLayer('quality');
+
+      expect(safety.every(c => c.layer === 'safety')).toBe(true);
+      expect(quality.every(c => c.layer === 'quality')).toBe(true);
+      expect(safety.length).toBe(SAFETY_COUNT);
+    });
+  });
+
+  describe('getByStatus', () => {
+    it('应该按退化状态过滤', () => {
+      const active = registry.getByStatus('active');
+      expect(active.length).toBe(registry.getAll().length);
+
+      const deprecated = registry.getByStatus('deprecated');
+      expect(deprecated.length).toBe(0);
+    });
+  });
+
+  describe('getByTrigger', () => {
+    it('应该按触发条件查找', () => {
+      const constraints = registry.getByTrigger('code_implementation');
+      expect(constraints.length).toBeGreaterThan(0);
+      expect(constraints.every(c => {
+        const triggers = Array.isArray(c.trigger) ? c.trigger : [c.trigger];
+        return triggers.includes('code_implementation');
+      })).toBe(true);
+    });
+  });
+
+  describe('degrade', () => {
+    it('应该降低约束级别', () => {
+      const result = registry.degrade('no_any_type');
+      expect(result).toBe(true);
+
+      const constraint = registry.get('no_any_type');
+      expect(constraint?.level).toBe('tip');
+      expect(constraint?.deprecationStatus).toBe('deprecated');
+    });
+
+    it('安全层约束也可以退化（Iron Law <5% 高阈值）', () => {
+      const result = registry.degrade('no_bypass_checkpoint');
+      expect(result).toBe(true);
+    });
+
+    it('不应该退化非 active 约束', () => {
+      registry.degrade('no_any_type');
+      const result = registry.degrade('no_any_type');
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('rollback', () => {
+    it('应该回滚退化', () => {
+      registry.degrade('no_any_type');
+      const result = registry.rollback('no_any_type', 'guideline');
+      expect(result).toBe(true);
+
+      const constraint = registry.get('no_any_type');
+      expect(constraint?.level).toBe('guideline');
+      expect(constraint?.deprecationStatus).toBe('active');
+    });
+
+    it('不应该回滚不存在的约束', () => {
+      const result = registry.rollback('nonexistent', 'guideline');
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('scheduleDeprecation', () => {
+    it('应该为质量层约束安排退化', () => {
+      const result = registry.scheduleDeprecation('no_skill_without_test', {
+        targetLevel: 'tip',
+        reason: '测试能力提升',
+        rollbackable: true,
+      });
+      expect(result).toBe(true);
+
+      const constraint = registry.get('no_skill_without_test');
+      expect(constraint?.deprecationStatus).toBe('scheduled');
+    });
+
+    it('不应该为安全层约束安排退化', () => {
+      const result = registry.scheduleDeprecation('no_bypass_checkpoint', {
+        targetLevel: 'tip',
+        reason: 'test',
+        rollbackable: true,
+      });
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('getLayerStats', () => {
+    it('应该返回层统计', () => {
+      const stats = registry.getLayerStats();
+      expect(stats.length).toBe(2);
+
+      const safetyStats = stats.find(s => s.layer === 'safety')!;
+      expect(safetyStats.totalConstraints).toBe(SAFETY_COUNT);
+      expect(safetyStats.active).toBe(safetyStats.totalConstraints);
+
+      const qualityStats = stats.find(s => s.layer === 'quality')!;
+      expect(qualityStats.totalConstraints).toBe(QUALITY_COUNT);
+    });
+  });
+
+  describe('toLegacyConstraints', () => {
+    it('应该转换为旧格式', () => {
+      const legacy = registry.toLegacyConstraints();
+      expect(legacy.length).toBe(registry.getAll().length);
+      expect(legacy[0]).toHaveProperty('id');
+      expect(legacy[0]).toHaveProperty('rule');
+      expect(legacy[0]).toHaveProperty('level');
+      expect(legacy[0]).not.toHaveProperty('layer');
+      expect(legacy[0]).not.toHaveProperty('deprecationStatus');
+    });
+  });
+
+  describe('register / remove', () => {
+    it('应该注册自定义约束', () => {
+      registry.register({
+        id: 'custom',
+        rule: 'CUSTOM',
+        message: '自定义约束',
+        level: 'guideline',
+        trigger: 'code_implementation',
+        enforcement: 'custom-check',
+        layer: 'quality',
+        deprecationStatus: 'active',
+      });
+
+      expect(registry.get('custom')).toBeDefined();
+    });
+
+    it('应该移除约束', () => {
+      registry.register({
+        id: 'temp',
+        rule: 'TEMP',
+        message: '临时',
+        level: 'tip',
+        trigger: 'commit',
+        enforcement: 'temp',
+        layer: 'quality',
+        deprecationStatus: 'active',
+      });
+
+      expect(registry.remove('temp')).toBe(true);
+      expect(registry.get('temp')).toBeUndefined();
+    });
+  });
+});

package/src/constraints/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './registry';
+export * from './lifecycle-runner';