@dommaker/harness 0.13.0 → 0.13.2

package/src/gates/security.ts

@@ -0,0 +1,244 @@
+/**
+ * 安全门禁
+ * 
+ * 检查安全漏洞：
+ * - npm audit
+ * - 依赖漏洞
+ * - 敏感信息泄露
+ */
+
+import { execAsync } from '../utils/exec';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import type { GateResult, GateContext, SecurityGateConfig } from './types';
+
+/**
+ * 安全门禁
+ */
+export class SecurityGate {
+  private config: Required<SecurityGateConfig>;
+
+  constructor(config: Partial<SecurityGateConfig> = {}) {
+    this.config = {
+      enabled: config.enabled ?? true,
+      scanCommand: config.scanCommand ?? '',
+      ignoreWarnings: config.ignoreWarnings ?? false,
+      ignoreDevDependencies: config.ignoreDevDependencies ?? false,
+      severityThreshold: config.severityThreshold ?? 'high',
+    };
+  }
+
+  /**
+   * 扫描安全漏洞
+   */
+  async scan(context: GateContext): Promise<GateResult> {
+    const startTime = Date.now();
+
+    if (!this.config.enabled) {
+      return {
+        gate: 'security',
+        passed: true,
+        message: '安全门禁已禁用',
+        timestamp: new Date().toISOString(),
+        duration: Date.now() - startTime,
+      };
+    }
+
+    try {
+      // 使用自定义命令或默认 npm audit
+      const scanCommand = context.securityScanCommand ?? 
+        this.config.scanCommand ?? 
+        this.detectScanCommand(context.projectPath);
+
+      const result = await this.runScan(scanCommand, context.projectPath);
+
+      // 分析结果
+      const analysis = this.analyzeResult(result);
+
+      const passed = this.isPassed(analysis);
+
+      return {
+        gate: 'security',
+        passed,
+        message: passed
+          ? '安全扫描通过'
+          : `发现 ${analysis.critical} 个严重漏洞, ${analysis.high} 个高危漏洞`,
+        details: {
+          critical: analysis.critical,
+          high: analysis.high,
+          moderate: analysis.moderate,
+          low: analysis.low,
+          total: analysis.total,
+          vulnerabilities: analysis.vulnerabilities.slice(0, 10), // 只返回前 10 个
+          scanCommand,
+        },
+        timestamp: new Date().toISOString(),
+        duration: Date.now() - startTime,
+      };
+    } catch (error: any) {
+      return {
+        gate: 'security',
+        passed: false,
+        message: `安全扫描失败: ${error.message}`,
+        timestamp: new Date().toISOString(),
+        duration: Date.now() - startTime,
+      };
+    }
+  }
+
+  /**
+   * 检测扫描命令
+   */
+  private detectScanCommand(projectPath: string): string {
+    // 默认使用 npm audit
+    return 'npm audit --json';
+  }
+
+  /**
+   * 运行扫描
+   */
+  private async runScan(command: string, projectPath: string): Promise<string> {
+    try {
+      const { stdout } = await execAsync(command, {
+        cwd: projectPath,
+        maxBuffer: 10 * 1024 * 1024,
+      });
+      return stdout;
+    } catch (error: any) {
+      // npm audit 发现漏洞时会返回非零退出码
+      // 但 stdout 仍然包含结果
+      if (error.stdout) {
+        return error.stdout;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * 分析扫描结果
+   */
+  private analyzeResult(output: string): {
+    critical: number;
+    high: number;
+    moderate: number;
+    low: number;
+    total: number;
+    vulnerabilities: Array<{
+      name: string;
+      severity: string;
+      via: string;
+    }>;
+  } {
+    let critical = 0;
+    let high = 0;
+    let moderate = 0;
+    let low = 0;
+    const vulnerabilities: Array<{ name: string; severity: string; via: string }> = [];
+
+    try {
+      const result = JSON.parse(output);
+
+      // npm audit 格式
+      if (result.audit) {
+        const advisories = result.audit.advisories || {};
+        for (const key of Object.keys(advisories)) {
+          const advisory = advisories[key];
+          const severity = advisory.severity?.toLowerCase() || 'low';
+
+          switch (severity) {
+            case 'critical': critical++; break;
+            case 'high': high++; break;
+            case 'moderate': moderate++; break;
+            default: low++;
+          }
+
+          vulnerabilities.push({
+            name: advisory.name || key,
+            severity,
+            via: advisory.via?.[0]?.title || advisory.title || 'Unknown',
+          });
+        }
+      }
+
+      // 新版 npm audit 格式
+      if (result.vulnerabilities) {
+        for (const [name, vuln] of Object.entries(result.vulnerabilities)) {
+          const v = vuln as any;
+          const severity = v.severity?.toLowerCase() || 'low';
+
+          switch (severity) {
+            case 'critical': critical++; break;
+            case 'high': high++; break;
+            case 'moderate': moderate++; break;
+            default: low++;
+          }
+
+          vulnerabilities.push({
+            name,
+            severity,
+            via: v.via?.[0]?.title || v.name || 'Unknown',
+          });
+        }
+      }
+    } catch {
+      // 解析失败，尝试从文本提取
+      const criticalMatch = output.match(/(\d+) critical/i);
+      const highMatch = output.match(/(\d+) high/i);
+      const moderateMatch = output.match(/(\d+) moderate/i);
+      const lowMatch = output.match(/(\d+) low/i);
+
+      critical = criticalMatch ? parseInt(criticalMatch[1], 10) : 0;
+      high = highMatch ? parseInt(highMatch[1], 10) : 0;
+      moderate = moderateMatch ? parseInt(moderateMatch[1], 10) : 0;
+      low = lowMatch ? parseInt(lowMatch[1], 10) : 0;
+    }
+
+    return {
+      critical,
+      high,
+      moderate,
+      low,
+      total: critical + high + moderate + low,
+      vulnerabilities,
+    };
+  }
+
+  /**
+   * 判断是否通过
+   */
+  private isPassed(analysis: {
+    critical: number;
+    high: number;
+    moderate: number;
+    low: number;
+    total: number;
+  }): boolean {
+    // 根据严重程度阈值判断
+    switch (this.config.severityThreshold) {
+      case 'critical':
+        return analysis.critical === 0;
+      case 'high':
+        return analysis.critical === 0 && analysis.high === 0;
+      case 'moderate':
+        return analysis.critical === 0 && analysis.high === 0 && analysis.moderate === 0;
+      case 'low':
+        return analysis.total === 0;
+      default:
+        return analysis.critical === 0 && analysis.high === 0;
+    }
+  }
+
+  /**
+   * 设置严重程度阈值
+   */
+  setSeverityThreshold(threshold: 'low' | 'moderate' | 'high' | 'critical'): void {
+    this.config.severityThreshold = threshold;
+  }
+
+  /**
+   * 获取配置
+   */
+  getConfig(): Required<SecurityGateConfig> {
+    return { ...this.config };
+  }
+}

package/src/gates/types.ts

@@ -0,0 +1,159 @@
+/**
+ * 门禁类型定义
+ */
+
+/**
+ * 门禁结果
+ */
+export interface GateResult {
+  gate: string;
+  passed: boolean;
+  message: string;
+  details?: Record<string, any>;
+  timestamp: string;
+  duration?: number;
+}
+
+/**
+ * 门禁上下文
+ */
+export interface GateContext {
+  projectId: string;
+  taskId?: string;
+  projectPath: string;
+  
+  // Review Gate
+  prNumber?: number;
+  minReviewers?: number;
+  reviewers?: string[];
+  
+  // Security Gate
+  securityScanCommand?: string;
+  ignoreWarnings?: boolean;
+  
+  // Performance Gate
+  performanceThresholds?: PerformanceThresholds;
+  benchmarkCommand?: string;
+  
+  // Contract Gate
+  oldContractPath?: string;
+  newContractPath?: string;
+  openApiSpec?: string;
+  
+  // 通用
+  timeout?: number;
+}
+
+/**
+ * 性能阈值
+ */
+export interface PerformanceThresholds {
+  maxResponseTime?: number;   // ms
+  maxMemoryUsage?: number;    // MB
+  minCoverage?: number;       // %
+  maxBundleSize?: number;     // KB
+  minThroughput?: number;     // req/s
+}
+
+/**
+ * 审查门禁配置
+ */
+export interface ReviewGateConfig {
+  minReviewers: number;
+  requireApproval: boolean;
+  blockOnChangesRequested: boolean;
+  allowedReviewers?: string[];
+}
+
+/**
+ * 安全门禁配置
+ */
+export interface SecurityGateConfig {
+  enabled: boolean;
+  scanCommand?: string;
+  ignoreWarnings: boolean;
+  ignoreDevDependencies: boolean;
+  severityThreshold: 'low' | 'moderate' | 'high' | 'critical';
+}
+
+/**
+ * 性能门禁配置
+ */
+export interface PerformanceGateConfig {
+  enabled: boolean;
+  benchmarkCommand?: string;
+  thresholds: PerformanceThresholds;
+  warmupRuns: number;
+  measureRuns: number;
+}
+
+/**
+ * 契约门禁配置
+ */
+export interface ContractGateConfig {
+  enabled: boolean;
+  strict: boolean;
+  allowBreakingChanges: boolean;
+  contractPath?: string;
+}
+
+/**
+ * 验收标准门禁配置
+ */
+export interface SpecAcceptanceGateConfig {
+  /** tasks.yml 路径 */
+  tasksPath?: string;
+  /** 是否检查所有任务 */
+  checkAllTasks?: boolean;
+  /** 自定义验收条件 */
+  customAcceptanceCriteria?: Record<string, (task: any) => Promise<boolean>>;
+}
+
+/**
+ * 验收标准门禁上下文
+ */
+export interface AcceptanceGateContext {
+  /** 项目路径 */
+  projectPath: string;
+  /** 任务 ID */
+  taskId?: string;
+  /** tasks.yml 路径 */
+  tasksPath?: string;
+}
+
+/**
+ * 验收标准
+ */
+export interface AcceptanceCriteria {
+  id: string;
+  description: string;
+  type: 'manual' | 'automated' | 'test';
+  required: boolean;
+  checked?: boolean;
+  notes?: string;
+}
+
+/**
+ * 命令黑名单规则
+ */
+export interface CommandBlacklistRule {
+  id: string;
+  pattern: RegExp;
+  level: 'block' | 'warn' | 'audit';
+  message: string;
+  category: string;
+}
+
+/**
+ * 命令门禁配置
+ */
+export interface CommandGateConfig {
+  /** 是否启用 */
+  enabled?: boolean;
+  /** 严格模式（warn 也阻止） */
+  strict?: boolean;
+  /** 自定义黑名单规则 */
+  customBlacklist?: CommandBlacklistRule[];
+  /** 忽略的类别 */
+  ignoreCategories?: string[];
+}

package/src/governance/CONTEXT.md

@@ -0,0 +1,22 @@
+# governance/
+
+## 职责
+AI 治理：检测文档/配置/约束与代码的差异，输出差异报告。只检测不修复，由 LLM 自行修复。
+
+## 核心导出
+- `GovernanceExecutor` — 治理执行器: 运行所有检查、生成差异报告
+- `types.ts` — DiffType / GovernanceDiff / GovernanceResult 类型
+
+## 依赖关系
+- 依赖 `src/core/constraints/` 约束检查
+- 依赖 `src/monitoring/` 追踪/诊断数据
+- 被 CLI 治理相关命令消费
+
+## 约定
+- "harness 检测差异，LLM 自行修复" — 不提供自动修复
+- 差异类型(DiffType)可扩展
+- 治理检查在 check / sync-docs 命令中触发
+
+## 注意事项
+- AI 治理简化(2026-05-03)：移除冗余 hook/apply
+- GovernanceExecutor 是单例

package/src/governance/__tests__/executor.test.ts

@@ -0,0 +1,249 @@
+/**
+ * GovernanceExecutor 测试
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { GovernanceExecutor } from '../executor';
+
+describe('GovernanceExecutor', () => {
+  const tempDir = path.join(process.cwd(), 'temp-test-governance');
+
+  beforeAll(() => {
+    fs.mkdirSync(tempDir, { recursive: true });
+  });
+
+  afterAll(() => {
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  describe('detectDiffs', () => {
+    it('无 CAPABILITIES.md 应该返回空差异', async () => {
+      const testDir = path.join(tempDir, 'no-cap');
+      fs.mkdirSync(testDir, { recursive: true });
+
+      const executor = new GovernanceExecutor();
+      const diffs = await executor.detectDiffs(testDir);
+      expect(diffs).toEqual([]);
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('CAPABILITIES.md 无表格应该返回空差异', async () => {
+      const testDir = path.join(tempDir, 'no-table');
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(path.join(testDir, 'CAPABILITIES.md'), '# Capabilities\n\nNo table here.');
+
+      const executor = new GovernanceExecutor();
+      const diffs = await executor.detectDiffs(testDir);
+      expect(diffs).toEqual([]);
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('新增文件未在 CAPABILITIES.md 中列出应该检测到 doc_mismatch', async () => {
+      const testDir = path.join(tempDir, 'missing-in-cap');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      fs.writeFileSync(path.join(srcDir, 'new-module.ts'), 'export const x = 1;');
+      fs.writeFileSync(path.join(srcDir, 'old.ts'), 'export const y = 2;');
+
+      fs.writeFileSync(
+        path.join(testDir, 'CAPABILITIES.md'),
+        '# Capabilities\n\n| 模块 | 文件 | 说明 |\n|------|------|------|\n| old | src/old.ts | old |'
+      );
+
+      const executor = new GovernanceExecutor();
+      const diffs = await executor.detectDiffs(testDir);
+
+      expect(diffs.length).toBe(1);
+      expect(diffs[0].type).toBe('doc_mismatch');
+      expect(diffs[0].details.files).toContain('src/new-module.ts');
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('CAPABILITIES.md 中列出已删除文件应该检测到 doc_mismatch', async () => {
+      const testDir = path.join(tempDir, 'removed-from-disk');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      fs.writeFileSync(
+        path.join(testDir, 'CAPABILITIES.md'),
+        '# Capabilities\n\n| 模块 | 文件 | 说明 |\n|------|------|------|\n| old | src/old.ts | old |'
+      );
+
+      const executor = new GovernanceExecutor();
+      const diffs = await executor.detectDiffs(testDir);
+
+      expect(diffs.length).toBe(1);
+      expect(diffs[0].type).toBe('doc_mismatch');
+      expect(diffs[0].details.files).toContain('src/old.ts');
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('CAPABILITIES.md 与源码同步应该无差异', async () => {
+      const testDir = path.join(tempDir, 'in-sync');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      fs.writeFileSync(path.join(srcDir, 'module.ts'), 'export const x = 1;');
+      fs.writeFileSync(
+        path.join(testDir, 'CAPABILITIES.md'),
+        '# Capabilities\n\n| 模块 | 文件 | 说明 |\n|------|------|------|\n| module | src/module.ts | module |'
+      );
+
+      const executor = new GovernanceExecutor();
+      const diffs = await executor.detectDiffs(testDir);
+
+      expect(diffs).toEqual([]);
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('CONTEXT.md 缺失应该检测到 context_missing', async () => {
+      const testDir = path.join(tempDir, 'ctx-missing');
+      const harnessDir = path.join(testDir, '.harness');
+      fs.mkdirSync(harnessDir, { recursive: true });
+
+      const yaml = require('js-yaml');
+      fs.writeFileSync(
+        path.join(harnessDir, 'config.yml'),
+        yaml.dump({
+          governance: {
+            context_files: {
+              enabled: true,
+              required_dirs: ['src'],
+            },
+          },
+        })
+      );
+
+      const executor = new GovernanceExecutor();
+      const diffs = await executor.detectDiffs(testDir);
+
+      expect(diffs.length).toBe(1);
+      expect(diffs[0].type).toBe('context_missing');
+      expect(diffs[0].details.moduleName).toBe('src');
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('CONTEXT.md 是模板应该检测到 context_outdated', async () => {
+      const testDir = path.join(tempDir, 'ctx-template');
+      const harnessDir = path.join(testDir, '.harness');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(harnessDir, { recursive: true });
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      const yaml = require('js-yaml');
+      fs.writeFileSync(
+        path.join(harnessDir, 'config.yml'),
+        yaml.dump({
+          governance: {
+            context_files: {
+              enabled: true,
+              required_dirs: ['src'],
+            },
+          },
+        })
+      );
+
+      fs.writeFileSync(
+        path.join(srcDir, 'CONTEXT.md'),
+        '# src\n\n<!-- 此文件描述 src 目录的职责和上下文 -->\n\n## 职责\n\n<!-- 本目录的核心职责是什么 -->'
+      );
+
+      const executor = new GovernanceExecutor();
+      const diffs = await executor.detectDiffs(testDir);
+
+      expect(diffs.length).toBe(1);
+      expect(diffs[0].type).toBe('context_outdated');
+      expect(diffs[0].details.moduleName).toBe('src');
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('CONTEXT.md 已填写应该无差异', async () => {
+      const testDir = path.join(tempDir, 'ctx-filled');
+      const harnessDir = path.join(testDir, '.harness');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(harnessDir, { recursive: true });
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      const yaml = require('js-yaml');
+      fs.writeFileSync(
+        path.join(harnessDir, 'config.yml'),
+        yaml.dump({
+          governance: {
+            context_files: {
+              enabled: true,
+              required_dirs: ['src'],
+            },
+          },
+        })
+      );
+
+      fs.writeFileSync(
+        path.join(srcDir, 'CONTEXT.md'),
+        '# src\n\n源代码目录，包含所有核心模块。'
+      );
+
+      const executor = new GovernanceExecutor();
+      const diffs = await executor.detectDiffs(testDir);
+
+      expect(diffs).toEqual([]);
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+  });
+
+  describe('check', () => {
+    it('有差异时 should return hasDiffs=true', async () => {
+      const testDir = path.join(tempDir, 'check-diffs');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      fs.writeFileSync(path.join(srcDir, 'new.ts'), 'export const x = 1;');
+      fs.writeFileSync(
+        path.join(testDir, 'CAPABILITIES.md'),
+        '# Capabilities\n\n| 模块 | 文件 | 说明 |\n|------|------|------|\n| old | src/old.ts | old |'
+      );
+
+      const executor = new GovernanceExecutor();
+      const result = await executor.check(testDir);
+
+      expect(result.hasDiffs).toBe(true);
+      expect(result.diffs.length).toBeGreaterThan(0);
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('无差异时 should return hasDiffs=false', async () => {
+      const testDir = path.join(tempDir, 'check-no-diffs');
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(path.join(testDir, 'CAPABILITIES.md'), '# Capabilities\n\nNo table.');
+
+      const executor = new GovernanceExecutor();
+      const result = await executor.check(testDir);
+
+      expect(result.hasDiffs).toBe(false);
+      expect(result.diffs).toEqual([]);
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+  });
+
+  describe('global singleton', () => {
+    it('应该导出全局单例', () => {
+      const { governanceExecutor } = require('../executor');
+      expect(governanceExecutor).toBeInstanceOf(GovernanceExecutor);
+    });
+  });
+});