@dommaker/harness 0.13.0 → 0.13.2

package/src/governance/executor.ts

@@ -0,0 +1,229 @@
+/**
+ * 治理执行器
+ *
+ * 检测差异 → 返回结果 → LLM 自行修复
+ * harness 只做检测，不做修复
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { detectSourceRoots } from '../utils/detect-source-roots';
+import type {
+  GovernanceDiff,
+  GovernanceResult,
+} from './types';
+
+export class GovernanceExecutor {
+  /**
+   * 执行治理检查
+   *
+   * 检测差异并返回结果，不调用 hook，不执行修复
+   * LLM 拿到结果后自行决定如何处理
+   */
+  async check(projectPath: string): Promise<GovernanceResult> {
+    const diffs = await this.detectDiffs(projectPath);
+
+    return {
+      hasDiffs: diffs.length > 0,
+      diffs,
+    };
+  }
+
+  /**
+   * 检测项目中的治理差异
+   */
+  async detectDiffs(projectPath: string): Promise<GovernanceDiff[]> {
+    const diffs: GovernanceDiff[] = [];
+
+    // 1. 检查 CAPABILITIES.md 与源码的差异
+    const capDiffs = await this.checkCapabilitiesSync(projectPath);
+    diffs.push(...capDiffs);
+
+    // 2. 检查 CONTEXT.md
+    const contextDiffs = await this.checkContextFiles(projectPath);
+    diffs.push(...contextDiffs);
+
+    return diffs;
+  }
+
+  /**
+   * 检查 CAPABILITIES.md 与源码是否同步
+   */
+  private async checkCapabilitiesSync(projectPath: string): Promise<GovernanceDiff[]> {
+    const diffs: GovernanceDiff[] = [];
+    const capabilitiesPath = path.join(projectPath, 'CAPABILITIES.md');
+
+    // 读取 CAPABILITIES.md
+    let capContent: string;
+    try {
+      capContent = await fs.readFile(capabilitiesPath, 'utf-8');
+    } catch {
+      // CAPABILITIES.md 不存在
+      return [];
+    }
+
+    // 解析表格中的文件路径
+    const listedFiles = this.parseCapabilitiesFiles(capContent);
+
+    // 如果没有表格，跳过
+    if (listedFiles.length === 0) return [];
+
+    // 扫描所有源码目录中的实际文件
+    const sourceRoots = detectSourceRoots(projectPath);
+    const actualFiles: string[] = [];
+    for (const root of sourceRoots) {
+      const rootDir = path.join(projectPath, root);
+      const files = await this.findSourceFiles(rootDir, projectPath);
+      actualFiles.push(...files);
+    }
+
+    // 找出新增但未列出的文件
+    const missing = actualFiles.filter(f => !listedFiles.includes(f));
+
+    // 找出已列出但已删除的文件
+    const removed = listedFiles.filter(f => !actualFiles.includes(f));
+
+    if (missing.length > 0) {
+      diffs.push({
+        type: 'doc_mismatch',
+        projectPath,
+        details: {
+          file: capabilitiesPath,
+          current: capContent,
+          expected: `新增文件未在 CAPABILITIES.md 中列出: ${missing.join(', ')}`,
+          files: missing,
+          context: { missing, listedFiles, actualFiles },
+        },
+      });
+    }
+
+    if (removed.length > 0) {
+      diffs.push({
+        type: 'doc_mismatch',
+        projectPath,
+        details: {
+          file: capabilitiesPath,
+          current: capContent,
+          expected: `CAPABILITIES.md 中列出的文件已不存在: ${removed.join(', ')}`,
+          files: removed,
+          context: { removed, listedFiles, actualFiles },
+        },
+      });
+    }
+
+    return diffs;
+  }
+
+  /**
+   * 检查 CONTEXT.md 文件
+   */
+  private async checkContextFiles(projectPath: string): Promise<GovernanceDiff[]> {
+    const diffs: GovernanceDiff[] = [];
+    const requiredDirs = await this.getRequiredContextDirs(projectPath);
+
+    for (const dir of requiredDirs) {
+      const contextPath = path.join(projectPath, dir, 'CONTEXT.md');
+
+      try {
+        const content = await fs.readFile(contextPath, 'utf-8');
+
+        // 检查内容是否只是模板（没有实际填写）
+        const isTemplate = content.includes('<!-- 本目录')
+          || content.includes('<!-- 此文件描述');
+
+        if (isTemplate) {
+          diffs.push({
+            type: 'context_outdated',
+            projectPath,
+            details: {
+              file: contextPath,
+              current: content,
+              moduleName: dir,
+              context: { reason: 'CONTEXT.md 仍为模板，未填写实际内容' },
+            },
+          });
+        }
+      } catch {
+        // CONTEXT.md 不存在
+        diffs.push({
+          type: 'context_missing',
+          projectPath,
+          details: {
+            file: contextPath,
+            moduleName: dir,
+            context: { requiredDir: dir },
+          },
+        });
+      }
+    }
+
+    return diffs;
+  }
+
+  /**
+   * 从治理配置获取需要 CONTEXT.md 的目录
+   */
+  private async getRequiredContextDirs(projectPath: string): Promise<string[]> {
+    const configPath = path.join(projectPath, '.harness', 'config.yml');
+    try {
+      const content = await fs.readFile(configPath, 'utf-8');
+      const config = yaml.load(content) as Record<string, unknown>;
+      const governance = config.governance as Record<string, unknown> | undefined;
+      const contextFiles = governance?.context_files as Record<string, unknown> | undefined;
+      if (contextFiles?.enabled && Array.isArray(contextFiles.required_dirs)) {
+        return contextFiles.required_dirs as string[];
+      }
+    } catch {
+      // 配置不存在
+    }
+    return [];
+  }
+
+  /**
+   * 解析 CAPABILITIES.md 中的文件路径
+   */
+  private parseCapabilitiesFiles(content: string): string[] {
+    const files: string[] = [];
+    const tableRowRegex = /^\|[^|]+\|\s*([^|]+?\.(?:ts|tsx|js|jsx))\s*\|/gm;
+    let match;
+    while ((match = tableRowRegex.exec(content)) !== null) {
+      files.push(match[1].trim());
+    }
+    return files;
+  }
+
+  /**
+   * 递归查找源文件
+   */
+  private async findSourceFiles(dir: string, projectPath: string): Promise<string[]> {
+    const results: string[] = [];
+    let entries: string[];
+    try {
+      entries = await fs.readdir(dir);
+    } catch {
+      return [];
+    }
+
+    for (const entry of entries) {
+      if (entry === 'node_modules' || entry === '__tests__' || entry === 'dist') continue;
+      const entryPath = path.join(dir, entry);
+      try {
+        const stat = await fs.stat(entryPath);
+        if (stat.isDirectory()) {
+          results.push(...await this.findSourceFiles(entryPath, projectPath));
+        } else if (entry.endsWith('.ts') && !entry.endsWith('.d.ts') && entry !== 'index.ts') {
+          results.push(path.relative(projectPath, entryPath));
+        }
+      } catch {
+        // ignore
+      }
+    }
+    return results;
+  }
+}
+
+/**
+ * 全局治理执行器单例
+ */
+export const governanceExecutor = new GovernanceExecutor();

package/src/governance/index.ts

@@ -0,0 +1,13 @@
+/**
+ * 治理模块
+ *
+ * harness 检测差异，LLM 自行修复
+ * 只提供检测能力，不提供修复机制
+ */
+
+export { GovernanceExecutor, governanceExecutor } from './executor';
+export type {
+  DiffType,
+  GovernanceDiff,
+  GovernanceResult,
+} from './types';

package/src/governance/types.ts

@@ -0,0 +1,53 @@
+/**
+ * 治理类型定义
+ *
+ * harness 检测差异，LLM 自行决定如何修复
+ * 不需要 hook 返回内容、不需要 apply 机制
+ */
+
+/**
+ * 差异类型
+ */
+export type DiffType =
+  | 'doc_mismatch'       // 文档内容与代码不一致
+  | 'context_missing'    // 缺少 CONTEXT.md
+  | 'context_outdated'   // CONTEXT.md 内容过时
+  | 'test_gap'           // 新代码缺少测试
+  | 'constraint_violation'; // 约束违规
+
+/**
+ * 治理检查结果（harness 检测到的差异）
+ */
+export interface GovernanceDiff {
+  /** 差异类型 */
+  type: DiffType;
+  /** 项目路径 */
+  projectPath: string;
+  /** 差异详情 */
+  details: {
+    /** 目标文件 */
+    file?: string;
+    /** 现有内容 */
+    current?: string;
+    /** 期望内容（代码实际情况） */
+    expected?: string;
+    /** 相关文件列表 */
+    files?: string[];
+    /** 模块名 */
+    moduleName?: string;
+    /** 约束 ID */
+    constraintId?: string;
+    /** 额外上下文 */
+    context?: Record<string, unknown>;
+  };
+}
+
+/**
+ * 治理执行结果
+ */
+export interface GovernanceResult {
+  /** 是否有差异 */
+  hasDiffs: boolean;
+  /** 检测到的差异 */
+  diffs: GovernanceDiff[];
+}

package/src/hooks/CONTEXT.md

@@ -0,0 +1,23 @@
+# hooks/
+
+## 职责
+通用 Hook 管线：注册 → 排序 → 错误隔离 → 采样执行。无业务逻辑，consumer 自行定义 hook 名称和语义。
+
+## 核心导出
+- `HookRegistry` — Hook 注册表
+- `HookPipeline` — Hook 执行管线(注册/排序/错误隔离/采样)
+- `bootstrapHarness` / `bootstrapHarnessSync` — Harness 启动引导
+
+## 依赖关系
+- 依赖 `src/types/` Hook 相关类型
+- 被 `src/core/` 核心引擎消费
+- 被 CLI 初始化流程消费
+
+## 约定
+- 无业务逻辑，只提供管线能力
+- Consumer 自行定义 hook 名称和触发时机
+- 错误隔离：单个 hook 失败不影响其他 hook
+
+## 注意事项
+- 通用管线设计，不绑定特定生命周期
+- 采样执行用于高频 hook(减少性能影响)

package/src/hooks/__tests__/bootstrap.test.ts

@@ -0,0 +1,184 @@
+/**
+ * Tests for bootstrap.ts — bootstrapHarness, bootstrapHarnessSync
+ *
+ * bootstrapHarness uses dynamic import(fs) which is async and can be tricky in tests.
+ * bootstrapHarnessSync uses synchronous fs reads and is more straightforward.
+ *
+ * Uses temp directories to provide harness config.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { bootstrapHarnessSync, bootstrapHarness } from '../bootstrap';
+import type { HookDefinition } from '../types';
+
+function setupTempDir(dir: string): string {
+  const harnessDir = path.join(dir, '.harness');
+  fs.mkdirSync(harnessDir, { recursive: true });
+  const config = {
+    preset: 'standard',
+    custom_constraints_file: 'custom-constraints.yml',
+  };
+  fs.writeFileSync(path.join(harnessDir, 'config.yml'), yaml.dump(config), 'utf-8');
+  return harnessDir;
+}
+
+describe('bootstrapHarness', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync('bootstrap-async-');
+    setupTempDir(tempDir);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('returns a HarnessBootstrap object with all required fields', async () => {
+    const result = await bootstrapHarness(tempDir);
+    expect(result).toHaveProperty('checker');
+    expect(result).toHaveProperty('sessions');
+    expect(result).toHaveProperty('hooks');
+    expect(result).toHaveProperty('pipeline');
+    expect(result).toHaveProperty('projectPath', tempDir);
+    expect(result).toHaveProperty('mergedConstraints');
+  });
+
+  it('initializes with the provided project path', async () => {
+    const result = await bootstrapHarness(tempDir);
+    expect(result.projectPath).toBe(tempDir);
+  });
+
+  it('registers hook definitions when provided', async () => {
+    const hookDef: HookDefinition = {
+      name: 'async-hook',
+      phase: 'before',
+      execute: async () => ({ passed: true }),
+    };
+    const result = await bootstrapHarness(tempDir, [hookDef]);
+    expect(result.hooks.listNames()).toContain('async-hook');
+  });
+
+  it('does not register hooks when no definitions provided', async () => {
+    const result = await bootstrapHarness(tempDir, []);
+    expect(result.hooks.listNames()).toEqual([]);
+  });
+
+  it('uses process.cwd() when no project path is given', async () => {
+    const result = await bootstrapHarness(undefined, []);
+    expect(result).toHaveProperty('projectPath');
+    expect(result.projectPath).toBeDefined();
+  });
+
+  it('creates SessionManager scoped to project path', async () => {
+    const result = await bootstrapHarness(tempDir);
+    result.sessions.createSession('async-session');
+    const sessionDir = path.join(tempDir, '.harness', 'sessions', 'async-session');
+    expect(fs.existsSync(sessionDir)).toBe(true);
+  });
+
+  it('works without .harness/config.yml (uses defaults)', async () => {
+    const noConfigDir = fs.mkdtempSync('bootstrap-noconfig-');
+    try {
+      const result = await bootstrapHarness(noConfigDir);
+      expect(result).toHaveProperty('checker');
+      expect(result).toHaveProperty('projectPath', noConfigDir);
+      expect(result.mergedConstraints).toHaveProperty('ironLaws');
+    } finally {
+      fs.rmSync(noConfigDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('bootstrapHarnessSync', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync('bootstrap-test-');
+    setupTempDir(tempDir);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('returns a HarnessBootstrap object with all required fields', () => {
+    const result = bootstrapHarnessSync(tempDir);
+    expect(result).toHaveProperty('checker');
+    expect(result).toHaveProperty('sessions');
+    expect(result).toHaveProperty('hooks');
+    expect(result).toHaveProperty('pipeline');
+    expect(result).toHaveProperty('projectPath', tempDir);
+    expect(result).toHaveProperty('mergedConstraints');
+  });
+
+  it('initializes with the provided project path', () => {
+    const result = bootstrapHarnessSync(tempDir);
+    expect(result.projectPath).toBe(tempDir);
+  });
+
+  it('initializes ConstraintChecker with merged constraints', () => {
+    const result = bootstrapHarnessSync(tempDir);
+    // Check that mergedConstraints has the expected structure
+    expect(result.mergedConstraints).toHaveProperty('ironLaws');
+    expect(result.mergedConstraints).toHaveProperty('guidelines');
+    expect(result.mergedConstraints).toHaveProperty('tips');
+  });
+
+  it('registers hook definitions when provided', () => {
+    const hookDef: HookDefinition = {
+      name: 'test-hook',
+      phase: 'before',
+      execute: async () => ({ passed: true }),
+    };
+    const result = bootstrapHarnessSync(tempDir, [hookDef]);
+    expect(result.hooks.listNames()).toContain('test-hook');
+  });
+
+  it('does not register hooks when no definitions provided', () => {
+    const result = bootstrapHarnessSync(tempDir, []);
+    expect(result.hooks.listNames()).toEqual([]);
+  });
+
+  it('uses process.cwd() when no project path is given', () => {
+    // We cannot easily test process.cwd() fallback without mocking cwd,
+    // but we can verify the function accepts undefined
+    const result = bootstrapHarnessSync(undefined, []);
+    // Should not throw with process.cwd() — harness directory may not exist
+    expect(result).toHaveProperty('projectPath');
+    expect(result.projectPath).toBeDefined();
+  });
+
+  it('creates SessionManager scoped to project path', () => {
+    const result = bootstrapHarnessSync(tempDir);
+    // SessionManager is created with resolvedPath — we can verify by
+    // creating a session and checking the directory exists
+    result.sessions.createSession('boot-session');
+    const sessionDir = path.join(tempDir, '.harness', 'sessions', 'boot-session');
+    expect(fs.existsSync(sessionDir)).toBe(true);
+  });
+
+  it('creates a working HookPipeline', () => {
+    const hookDef: HookDefinition = {
+      name: 'pipeline-hook',
+      phase: 'after',
+      execute: async () => ({ passed: true, data: 'ok' }),
+    };
+    const result = bootstrapHarnessSync(tempDir, [hookDef]);
+    expect(result.pipeline).toBeDefined();
+  });
+
+  it('loads from .harness/config.yml when present', () => {
+    // Write a custom config with specific settings
+    const harnessDir = path.join(tempDir, '.harness');
+    const config = {
+      preset: 'relaxed',
+    };
+    fs.writeFileSync(path.join(harnessDir, 'config.yml'), yaml.dump(config), 'utf-8');
+    const result = bootstrapHarnessSync(tempDir);
+    // With relaxed preset, the merged constraints should only have iron laws
+    expect(result.mergedConstraints).toBeDefined();
+  });
+});

package/src/hooks/bootstrap.ts

@@ -0,0 +1,144 @@
+/**
+ * Harness Bootstrap — 统一初始化入口（Phase 1）
+ *
+ * 解决：
+ * - S9: ProjectConfigLoader 异步加载，不阻塞事件循环
+ * - S2: 提供单例 SessionManager 生命周期管理
+ *
+ * Consumer 用法：
+ * ```typescript
+ * const harness = await bootstrapHarness('/path/to/project');
+ * // harness.checker, harness.config, harness.hooks, harness.sessions
+ * ```
+ */
+
+import { ConstraintChecker } from '../core/constraints/checker';
+import { SessionManager } from '../context/session-manager';
+import { ProjectConfigLoader } from '../core/project-config-loader';
+import { HookRegistry } from './registry';
+import { HookPipeline } from './pipeline';
+import type { MergedConstraintsConfig } from '../types/project-config';
+import type { HookDefinition } from './types';
+
+/**
+ * 异步加载项目配置（S9：异步 I/O）
+ */
+async function loadConfigAsync(projectPath: string): Promise<{
+  config: ReturnType<ProjectConfigLoader['getConfig']>;
+  mergedConstraints: MergedConstraintsConfig;
+}> {
+  // 使用动态 import 避免同步 readFileSync 阻塞事件循环
+  const { promises: fs } = await import('fs');
+  const path = await import('path');
+  const yaml = await import('js-yaml');
+
+  const loader = new ProjectConfigLoader(projectPath);
+
+  // 异步读取主配置
+  const configPath = path.join(projectPath, '.harness', 'config.yml');
+  try {
+    await fs.access(configPath);
+    const content = await fs.readFile(configPath, 'utf-8');
+    const loaded = yaml.load(content) as Record<string, unknown>;
+    loader.load(); // 同步回退作为 fallback
+  } catch {
+    loader.load(); // 文件不存在，使用默认配置
+  }
+
+  return {
+    config: loader.getConfig(),
+    mergedConstraints: loader.mergeConstraints(),
+  };
+}
+
+/**
+ * Bootstrap 结果
+ */
+export interface HarnessBootstrap {
+  /** 约束检查器 */
+  checker: ConstraintChecker;
+  /** 会话管理器 */
+  sessions: SessionManager;
+  /** Hook 注册表 */
+  hooks: HookRegistry;
+  /** Hook 管线 */
+  pipeline: HookPipeline;
+  /** 项目路径 */
+  projectPath: string;
+  /** 合并后的约束配置 */
+  mergedConstraints: MergedConstraintsConfig;
+}
+
+/**
+ * 初始化 harness 运行环境（异步，不阻塞事件循环）
+ *
+ * @param projectPath 项目根路径
+ * @param hookDefinitions 可选，初始化时注册的 hook
+ */
+export async function bootstrapHarness(
+  projectPath?: string,
+  hookDefinitions?: HookDefinition[]
+): Promise<HarnessBootstrap> {
+  const resolvedPath = projectPath || process.cwd();
+
+  // 1. 异步加载配置（S9 fix）
+  const { config: _config, mergedConstraints } = await loadConfigAsync(resolvedPath);
+
+  // 2. 初始化核心组件
+  const checker = ConstraintChecker.getInstance();
+  checker.setCustomConfig(mergedConstraints);
+
+  const sessions = new SessionManager(resolvedPath);
+  const hooks = new HookRegistry();
+  const pipeline = new HookPipeline(hooks);
+
+  // 3. 注册初始 hook
+  if (hookDefinitions) {
+    hooks.registerAll(hookDefinitions);
+  }
+
+  return {
+    checker,
+    sessions,
+    hooks,
+    pipeline,
+    projectPath: resolvedPath,
+    mergedConstraints,
+  };
+}
+
+/**
+ * 同步 bootstrap（兼容不支持 top-level await 的环境）
+ *
+ * 配置加载仍为同步（readFileSync），其他组件初始化同上。
+ */
+export function bootstrapHarnessSync(
+  projectPath?: string,
+  hookDefinitions?: HookDefinition[]
+): HarnessBootstrap {
+  const resolvedPath = projectPath || process.cwd();
+
+  const loader = new ProjectConfigLoader(resolvedPath);
+  loader.load();
+  const mergedConstraints = loader.mergeConstraints();
+
+  const checker = ConstraintChecker.getInstance();
+  checker.setCustomConfig(mergedConstraints);
+
+  const sessions = new SessionManager(resolvedPath);
+  const hooks = new HookRegistry();
+  const pipeline = new HookPipeline(hooks);
+
+  if (hookDefinitions) {
+    hooks.registerAll(hookDefinitions);
+  }
+
+  return {
+    checker,
+    sessions,
+    hooks,
+    pipeline,
+    projectPath: resolvedPath,
+    mergedConstraints,
+  };
+}

package/src/hooks/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Hooks 模块
+ *
+ * 通用 hook 管线：注册 → 排序 → 错误隔离 → 采样执行。
+ * 无业务逻辑，consumer 自行定义 hook 名称和语义。
+ */
+
+export * from './types';
+export { HookRegistry } from './registry';
+export { HookPipeline } from './pipeline';
+export {
+  bootstrapHarness,
+  bootstrapHarnessSync,
+  type HarnessBootstrap,
+} from './bootstrap';