@dommaker/harness 1.8.0 → 1.9.0

package/src/__tests__/hooks-pipeline.test.ts

@@ -1,201 +0,0 @@
-/**
- * HookRegistry + HookPipeline 测试（Phase 1）
- *
- * #159 起 `enabled` / `errorStrategy` 由 HookConfig 唯一声明，
- * 注册时以配置填充有效值；HookDefinition 不再携带这两个字段。
- */
-import { describe, it, expect, beforeEach } from '@jest/globals';
-import { HookRegistry } from '../hooks/registry';
-import { HookPipeline } from '../hooks/pipeline';
-import type { HookConfig, HookDefinition } from '../hooks/types';
-
-interface TestContext {
-  value: string;
-  calls: string[];
-}
-
-function makeHook(
-  name: string,
-  opts: Partial<HookDefinition<TestContext, unknown>> = {}
-): HookDefinition<TestContext, unknown> {
-  return {
-    name,
-    phase: 'before',
-    priority: 100,
-    execute: async (ctx) => {
-      ctx.calls.push(name);
-      return { passed: true };
-    },
-    ...opts,
-  };
-}
-
-function makeConfig(name: string, overrides: Partial<HookConfig> = {}): HookConfig {
-  return { name, enabled: true, errorStrategy: 'block', ...overrides };
-}
-
-describe('HookRegistry', () => {
-  let registry: HookRegistry<TestContext, unknown>;
-
-  beforeEach(() => {
-    registry = new HookRegistry();
-  });
-
-  it('应注册 hook', () => {
-    registry.register(makeHook('test'), makeConfig('test'));
-    expect(registry.get('test')).toBeDefined();
-  });
-
-  it('同名注册应覆盖', () => {
-    registry.register(makeHook('test', { priority: 50 }), makeConfig('test'));
-    registry.register(makeHook('test', { priority: 90 }), makeConfig('test'));
-    expect(registry.get('test')?.priority).toBe(90);
-  });
-
-  it('应获取已启用的 hook 按优先级排序', () => {
-    registry.register(makeHook('low', { priority: 200 }), makeConfig('low'));
-    registry.register(makeHook('high', { priority: 10 }), makeConfig('high'));
-    registry.register(makeHook('mid', { priority: 100 }), makeConfig('mid'));
-    registry.register(makeHook('disabled'), makeConfig('disabled', { enabled: false }));
-
-    const enabled = registry.getEnabled('before');
-    expect(enabled.map(h => h.name)).toEqual(['high', 'mid', 'low']);
-  });
-
-  it('应注销 hook', () => {
-    registry.register(makeHook('test'), makeConfig('test'));
-    expect(registry.unregister('test')).toBe(true);
-    expect(registry.get('test')).toBeUndefined();
-  });
-
-  it('应设置启用/禁用', () => {
-    registry.register(makeHook('test'), makeConfig('test'));
-    expect(registry.setEnabled('test', false)).toBe(true);
-    expect(registry.getEnabled('before').length).toBe(0);
-    expect(registry.setEnabled('test', true)).toBe(true);
-    expect(registry.getEnabled('before').length).toBe(1);
-  });
-
-  it('应正确统计数量', () => {
-    expect(registry.size).toBe(0);
-    registry.register(makeHook('a'), makeConfig('a'));
-    registry.register(makeHook('b'), makeConfig('b'));
-    expect(registry.size).toBe(2);
-  });
-});
-
-describe('HookPipeline', () => {
-  let registry: HookRegistry<TestContext, unknown>;
-  let pipeline: HookPipeline<TestContext>;
-
-  beforeEach(() => {
-    registry = new HookRegistry();
-    pipeline = new HookPipeline(registry);
-  });
-
-  it('应执行所有 before hook', async () => {
-    const ctx: TestContext = { value: '', calls: [] };
-    registry.register(makeHook('h1'), makeConfig('h1'));
-    registry.register(makeHook('h2'), makeConfig('h2'));
-
-    const result = await pipeline.run('before', ctx);
-
-    expect(result.passed).toBe(true);
-    expect(ctx.calls).toEqual(['h1', 'h2']);
-    expect(result.records.length).toBe(2);
-  });
-
-  it('blocking hook 失败应停止后续', async () => {
-    const ctx: TestContext = { value: '', calls: [] };
-    registry.register(makeHook('pass1'), makeConfig('pass1'));
-    registry.register(makeHook('block', {
-      execute: async () => ({ passed: false, error: 'blocked' }),
-    }), makeConfig('block', { errorStrategy: 'block' }));
-    registry.register(makeHook('never_runs'), makeConfig('never_runs'));
-
-    const result = await pipeline.run('before', ctx);
-
-    expect(result.passed).toBe(false);
-    expect(result.blockedBy).toEqual(['block']);
-    // block hook 的 execute 被覆盖，不 push calls
-    expect(ctx.calls).toEqual(['pass1']);
-    expect(ctx.calls).not.toContain('never_runs');
-  });
-
-  it('warn hook 失败应继续但记录警告', async () => {
-    const ctx: TestContext = { value: '', calls: [] };
-    registry.register(makeHook('warn_hook', {
-      execute: async () => ({ passed: false, error: 'warning' }),
-    }), makeConfig('warn_hook', { errorStrategy: 'warn' }));
-    registry.register(makeHook('should_still_run'), makeConfig('should_still_run'));
-
-    const result = await pipeline.run('before', ctx);
-
-    expect(result.passed).toBe(true);
-    expect(result.warnings).toEqual(['warn_hook']);
-    expect(ctx.calls).toContain('should_still_run');
-  });
-
-  it('hook 抛异常应被捕获', async () => {
-    const ctx: TestContext = { value: '', calls: [] };
-    registry.register(makeHook('throws', {
-      execute: async () => { throw new Error('crash'); },
-    }), makeConfig('throws', { errorStrategy: 'warn' }));
-    registry.register(makeHook('after_crash', { priority: 200 }), makeConfig('after_crash'));
-
-    const result = await pipeline.run('before', ctx);
-
-    expect(result.records[0].error).toContain('crash');
-    expect(ctx.calls).toContain('after_crash');
-  });
-
-  it('runFull 应在 before/after 之间执行操作', async () => {
-    const ctx: TestContext = { value: '', calls: [] };
-    registry.register(makeHook('before_hook'), makeConfig('before_hook'));
-
-    const afterHook = makeHook('after_hook', { phase: 'after' });
-    registry.register(afterHook, makeConfig('after_hook'));
-
-    const { pipelineResult, operationResult } = await pipeline.runFull(ctx, async () => {
-      ctx.calls.push('operation');
-      return 'done';
-    });
-
-    expect(pipelineResult.passed).toBe(true);
-    expect(operationResult).toBe('done');
-    expect(ctx.calls).toEqual(['before_hook', 'operation', 'after_hook']);
-  });
-
-  it('before hook 失败不应执行操作', async () => {
-    const ctx: TestContext = { value: '', calls: [] };
-    registry.register(makeHook('block', {
-      execute: async () => ({ passed: false }),
-    }), makeConfig('block', { errorStrategy: 'block' }));
-
-    const { pipelineResult, operationResult } = await pipeline.runFull(ctx, async () => {
-      ctx.calls.push('should_not_run');
-      return 'nope';
-    });
-
-    expect(pipelineResult.passed).toBe(false);
-    expect(operationResult).toBeUndefined();
-    expect(ctx.calls).not.toContain('should_not_run');
-  });
-
-  it('空注册表应返回通过', async () => {
-    const result = await pipeline.run('before', { value: '', calls: [] });
-    expect(result.passed).toBe(true);
-    expect(result.records).toEqual([]);
-  });
-
-  it('应忽略配置禁用的 hook', async () => {
-    const ctx: TestContext = { value: '', calls: [] };
-    registry.register(makeHook('enabled'), makeConfig('enabled'));
-    registry.register(makeHook('disabled'), makeConfig('disabled', { enabled: false }));
-
-    await pipeline.run('before', ctx);
-
-    expect(ctx.calls).toEqual(['enabled']);
-    expect(ctx.calls).not.toContain('disabled');
-  });
-});

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

@@ -1,19 +0,0 @@
-/**
- * Hook 配置归一映射语义测试（G7）
- *
- * blocking → errorStrategy 无损映射：
- * - blocking=true → 'block'（失败阻断管线）
- * - blocking=false → 'warn'（记录警告继续）
- */
-
-import { toErrorStrategy } from '../config';
-
-describe('toErrorStrategy（blocking → errorStrategy 无损映射，G7）', () => {
-  it('blocking=true → block（失败阻断管线）', () => {
-    expect(toErrorStrategy(true)).toBe('block');
-  });
-
-  it('blocking=false → warn（记录警告继续）', () => {
-    expect(toErrorStrategy(false)).toBe('warn');
-  });
-});

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

@@ -1,90 +0,0 @@
-/**
- * HookPipeline errorStrategy 语义测试（G7 映射语义确认）
- *
- * block/warn 行为是 studio safeCallHook 语义在管线侧的无损承载面：
- * - 'block'：hook 失败 → passed=false、blockedBy 记名、停止执行后续 hook
- * - 'warn'：hook 失败 → 记录警告、继续执行后续 hook、passed 不受影响
- *
- * #159 起 `enabled` / `errorStrategy` 的唯一声明点是 HookConfig：
- * HookDefinition 不再携带这两个字段，有效值在注册环节由配置表填充。
- */
-
-import { HookPipeline } from '../pipeline';
-import { HookRegistry } from '../registry';
-import type { HookConfig, HookDefinition } from '../types';
-
-function makeConfig(name: string, overrides: Partial<HookConfig> = {}): HookConfig {
-  return { name, enabled: true, errorStrategy: 'warn', ...overrides };
-}
-
-function makeRegistry(
-  entries: Array<{ hook: HookDefinition; config?: Partial<HookConfig> }>
-): { registry: HookRegistry; pipeline: HookPipeline } {
-  const registry = new HookRegistry();
-  for (const { hook, config } of entries) {
-    registry.register(hook, makeConfig(hook.name, config));
-  }
-  return { registry, pipeline: new HookPipeline(registry) };
-}
-
-describe('HookPipeline errorStrategy 语义', () => {
-  it('block：失败阻断管线（passed=false、blockedBy 记名、停止后续 hook）', async () => {
-    const second = jest.fn().mockResolvedValue({ passed: true });
-    const { pipeline } = makeRegistry([
-      { hook: { name: 'first', phase: 'before', execute: async () => ({ passed: false, error: 'boom' }) }, config: { errorStrategy: 'block' } },
-      { hook: { name: 'second', phase: 'before', execute: second } },
-    ]);
-
-    const result = await pipeline.run('before', {});
-
-    expect(result.passed).toBe(false);
-    expect(result.blockedBy).toEqual(['first']);
-    expect(second).not.toHaveBeenCalled();
-  });
-
-  it('warn：失败记录警告并继续（passed 不受影响、后续 hook 照常执行）', async () => {
-    const second = jest.fn().mockResolvedValue({ passed: true });
-    const { pipeline } = makeRegistry([
-      { hook: { name: 'first', phase: 'before', execute: async () => ({ passed: false, error: 'soft' }) }, config: { errorStrategy: 'warn' } },
-      { hook: { name: 'second', phase: 'before', execute: second } },
-    ]);
-
-    const result = await pipeline.run('before', {});
-
-    expect(result.passed).toBe(true);
-    expect(result.warnings).toEqual(['first']);
-    expect(result.blockedBy).toEqual([]);
-    expect(second).toHaveBeenCalled();
-  });
-
-  it('block 失败停在当前 phase，不改变其它 phase 的 hook', async () => {
-    const afterHook = jest.fn().mockResolvedValue({ passed: true });
-    const { pipeline } = makeRegistry([
-      { hook: { name: 'blocker', phase: 'before', execute: async () => ({ passed: false }) }, config: { errorStrategy: 'block' } },
-      { hook: { name: 'afterHook', phase: 'after', execute: afterHook } },
-    ]);
-
-    const before = await pipeline.run('before', {});
-    expect(before.passed).toBe(false);
-
-    const after = await pipeline.run('after', {});
-    expect(after.passed).toBe(true);
-    expect(afterHook).toHaveBeenCalled();
-  });
-
-  it('配置 enabled:false 的 hook 不进入管线执行（配置表是唯一声明点）', async () => {
-    const disabledHook = jest.fn().mockResolvedValue({ passed: true });
-    const enabledHook = jest.fn().mockResolvedValue({ passed: true });
-    const { pipeline } = makeRegistry([
-      { hook: { name: 'disabled', phase: 'before', execute: disabledHook }, config: { enabled: false } },
-      { hook: { name: 'enabled', phase: 'before', execute: enabledHook } },
-    ]);
-
-    const result = await pipeline.run('before', {});
-
-    expect(result.passed).toBe(true);
-    expect(disabledHook).not.toHaveBeenCalled();
-    expect(enabledHook).toHaveBeenCalled();
-    expect(result.records.map(r => r.hookName)).toEqual(['enabled']);
-  });
-});

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

@@ -1,115 +0,0 @@
-/**
- * Hook 注册表闭环双向校验测试（H5，复制 checker 闭环模式）
- *
- * 两个失败方向 + 重复声明/注册都必须抛错；闭环通过时不抛错。
- *
- * #159 起注册即配对：`register(hook, config)` 以 HookConfig 填充有效
- * `enabled` / `errorStrategy`——配置表是这两个语义的唯一声明点，
- * HookDefinition 类型上不再存在同名字段（矛盾在构造上不可能出现）。
- */
-
-import { assertHookRegistryClosed, HookRegistry } from '../registry';
-import type { HookConfig, HookDefinition } from '../types';
-
-function makeHook(name: string): HookDefinition {
-  return {
-    name,
-    phase: 'before',
-    execute: async () => ({ passed: true }),
-  };
-}
-
-function makeConfig(name: string, overrides: Partial<HookConfig> = {}): HookConfig {
-  return { name, enabled: true, errorStrategy: 'block', ...overrides };
-}
-
-describe('assertHookRegistryClosed', () => {
-  it('声明与注册一一对应时通过', () => {
-    const configs = [makeConfig('beforeAgentExecute'), makeConfig('afterReview')];
-    const hooks = [makeHook('beforeAgentExecute'), makeHook('afterReview')];
-    expect(() => assertHookRegistryClosed(configs, hooks)).not.toThrow();
-  });
-
-  it('空声明 + 空注册通过（无 hook 的 consumer 合法）', () => {
-    expect(() => assertHookRegistryClosed([], [])).not.toThrow();
-  });
-
-  it('引用未注册 → 抛错：声明了配置但没有注册实现', () => {
-    const configs = [makeConfig('beforeAgentExecute'), makeConfig('ghostHook')];
-    const hooks = [makeHook('beforeAgentExecute')];
-    expect(() => assertHookRegistryClosed(configs, hooks)).toThrow(
-      /hook 配置 "ghostHook" 引用的实现未注册/
-    );
-  });
-
-  it('注册无定义 → 抛错：注册了实现但没有配置声明', () => {
-    const configs = [makeConfig('beforeAgentExecute')];
-    const hooks = [makeHook('beforeAgentExecute'), makeHook('orphanHook')];
-    expect(() => assertHookRegistryClosed(configs, hooks)).toThrow(
-      /hook "orphanHook" 注册了实现但没有对应配置声明/
-    );
-  });
-
-  it('重复声明 → 抛错', () => {
-    const configs = [makeConfig('dup'), makeConfig('dup')];
-    const hooks = [makeHook('dup')];
-    expect(() => assertHookRegistryClosed(configs, hooks)).toThrow(/重复声明/);
-  });
-
-  it('重复注册 → 抛错', () => {
-    const configs = [makeConfig('dup')];
-    const hooks = [makeHook('dup'), makeHook('dup')];
-    expect(() => assertHookRegistryClosed(configs, hooks)).toThrow(/重复注册/);
-  });
-
-  it('与 HookRegistry.listAll 组合可用（consumer 注册点用法）', () => {
-    const registry = new HookRegistry();
-    registry.registerAll([makeHook('beforeAgentExecute')], [makeConfig('beforeAgentExecute')]);
-    expect(() => assertHookRegistryClosed([makeConfig('beforeAgentExecute')], registry.listAll()))
-      .not.toThrow();
-  });
-});
-
-describe('HookRegistry 注册即配对（#159 配置表唯一化）', () => {
-  it('register 以 HookConfig 填充有效 enabled / errorStrategy', () => {
-    const registry = new HookRegistry();
-    registry.register(makeHook('a'), makeConfig('a', { enabled: false, errorStrategy: 'block' }));
-
-    const effective = registry.get('a');
-    expect(effective?.enabled).toBe(false);
-    expect(effective?.errorStrategy).toBe('block');
-    // 配置 enabled:false → 不进 enabled 列表
-    expect(registry.getEnabled('before')).toEqual([]);
-  });
-
-  it('register 定义与配置名称不一致 → 抛错', () => {
-    const registry = new HookRegistry();
-    expect(() => registry.register(makeHook('a'), makeConfig('b'))).toThrow(/名称不一致/);
-  });
-
-  it('registerAll 有实现缺配置声明 → 抛错', () => {
-    const registry = new HookRegistry();
-    expect(() =>
-      registry.registerAll([makeHook('a'), makeHook('orphan')], [makeConfig('a')])
-    ).toThrow(/hook "orphan" 没有对应的 HookConfig 声明/);
-  });
-
-  it('HookDefinition 类型上不再存在 enabled / errorStrategy（编译期钉）', () => {
-    const withStrategy: HookDefinition = {
-      name: 'x',
-      phase: 'before',
-      // @ts-expect-error HookDefinition 不再存在 errorStrategy 字段（#159）
-      errorStrategy: 'block',
-      execute: async () => ({ passed: true }),
-    };
-    const withEnabled: HookDefinition = {
-      name: 'y',
-      phase: 'before',
-      // @ts-expect-error HookDefinition 不再存在 enabled 字段（#159）
-      enabled: false,
-      execute: async () => ({ passed: true }),
-    };
-    expect(withStrategy.name).toBe('x');
-    expect(withEnabled.name).toBe('y');
-  });
-});

package/src/hooks/config.ts

@@ -1,33 +0,0 @@
-/**
- * Hook 配置归一（G7）
- *
- * studio 侧 per-hook 运行时配置（`blocking: boolean`）与 harness 侧
- * `HookConfig.errorStrategy` 双轨归一：以 errorStrategy 为唯一真相，
- * `blocking` → errorStrategy 为无损映射。
- *
- * 映射语义（确认于 H5）：
- * - blocking=true  → 'block'：hook 失败阻断管线（停止执行后续 hook，
- *   管线结果 passed=false、blockedBy 记名）——对应 studio safeCallHook 抛错
- * - blocking=false → 'warn'：hook 失败记录警告并继续执行后续 hook
- *   （管线结果 warnings 记名，passed 不受影响）——对应 studio safeCallHook
- *   console.warn 继续
- *
- * #159 起 `HookConfig` 是 `enabled` / `errorStrategy` 的唯一声明点：
- * HookDefinition 不再携带这两个字段，注册环节以配置表填充有效值，
- * 有效策略集合收敛为 'block' | 'warn'（原 'ignore' 退出有效面）。
- *
- * studio 侧随动（studio #150 A4）：hooks/config.ts 删 DEFAULTS/safeCallHook，
- * blocking→errorStrategy 无损映射进 toHookDef；HARNESS_HOOK_DISABLE 保留 studio。
- */
-
-import type { HookErrorStrategy } from './types';
-
-/**
- * blocking 布尔 → errorStrategy 无损映射（block/warn）
- *
- * @param blocking studio 侧「失败是否阻断」语义
- * @returns 'block'（阻断）| 'warn'（警告继续）
- */
-export function toErrorStrategy(blocking: boolean): HookErrorStrategy {
-  return blocking ? 'block' : 'warn';
-}

package/src/hooks/pipeline.ts

@@ -1,155 +0,0 @@
-/**
- * HookPipeline — hook 有序执行、错误隔离、采样
- *
- * 执行顺序：before hooks → consumer operation → after hooks
- * 每个 hook 独立 try/catch，单个 hook 失败不影���其他 hook。
- */
-
-import type {
-  EffectiveHook,
-  HookPhase,
-  HookExecutionRecord,
-  PipelineResult,
-} from './types';
-import type { HookRegistry } from './registry';
-
-export class HookPipeline<C = unknown> {
-  private registry: HookRegistry<C, unknown>;
-
-  constructor(registry: HookRegistry<C, unknown>) {
-    this.registry = registry;
-  }
-
-  /**
-   * 执行指定 phase 的所有 enabled hook
-   *
-   * @param phase hook 时机
-   * @param context 传递给每个 hook 的上下文
-   * @returns 管线执行结果
-   */
-  async run(
-    phase: HookPhase,
-    context: C
-  ): Promise<PipelineResult> {
-    const hooks = this.registry.getEnabled(phase);
-    const records: HookExecutionRecord[] = [];
-    const blockedBy: string[] = [];
-    const warnings: string[] = [];
-    let passed = true;
-
-    for (const hook of hooks) {
-      const record = await this.executeOne(hook, context);
-      records.push(record);
-
-      if (!record.passed) {
-        if (hook.errorStrategy === 'block') {
-          passed = false;
-          blockedBy.push(hook.name);
-          break; // blocking hook 失败，停止执行后续 hook
-        }
-        // 'warn'：记录警告继续（有效集合仅 block/warn，策略由 HookConfig 必填声明）
-        warnings.push(hook.name);
-      }
-    }
-
-    return { passed, records, blockedBy, warnings };
-  }
-
-  /**
-   * 执行 before + after 全套管线
-   *
-   * @param context 上下文
-   * @param operation 业务操作（在 before 和 after 之间执行）
-   * @returns 管线结果 + 操作结果
-   */
-  async runFull<R>(
-    context: C,
-    operation: () => Promise<R>
-  ): Promise<{ pipelineResult: PipelineResult; operationResult?: R }> {
-    // 1. Before hooks
-    const beforeResult = await this.run('before', context);
-    if (!beforeResult.passed) {
-      return { pipelineResult: beforeResult };
-    }
-
-    // 2. Execute operation
-    let operationResult: R;
-    try {
-      operationResult = await operation();
-    } catch (err) {
-      // 操作失败：仍执行 after hooks，但传递错误信息
-      const afterResult = await this.run('after', {
-        ...context,
-        _operationError: (err as Error).message,
-      } as unknown as C);
-      return {
-        pipelineResult: {
-          passed: false,
-          records: [...beforeResult.records, ...afterResult.records],
-          blockedBy: [...beforeResult.blockedBy, '_operation'],
-          warnings: [...beforeResult.warnings, ...afterResult.warnings],
-        },
-      };
-    }
-
-    // 3. After hooks
-    const afterResult = await this.run('after', context);
-    return {
-      pipelineResult: {
-        passed: beforeResult.passed && afterResult.passed,
-        records: [...beforeResult.records, ...afterResult.records],
-        blockedBy: [...beforeResult.blockedBy, ...afterResult.blockedBy],
-        warnings: [...beforeResult.warnings, ...afterResult.warnings],
-      },
-      operationResult,
-    };
-  }
-
-  /**
-   * 执行单个 hook（带采样和错误隔离）
-   */
-  private async executeOne(
-    hook: EffectiveHook<C, unknown>,
-    context: C
-  ): Promise<HookExecutionRecord> {
-    const startedAt = Date.now();
-
-    // 采样检查
-    if (hook.sampleRate !== undefined && hook.sampleRate < 1) {
-      if (Math.random() > hook.sampleRate) {
-        return {
-          hookName: hook.name,
-          phase: hook.phase,
-          startedAt,
-          completedAt: Date.now(),
-          durationMs: 0,
-          passed: true,
-          sampled: true,
-        };
-      }
-    }
-
-    try {
-      const result = await hook.execute(context);
-      return {
-        hookName: hook.name,
-        phase: hook.phase,
-        startedAt,
-        completedAt: Date.now(),
-        durationMs: Date.now() - startedAt,
-        passed: result.passed !== false,
-        error: result.error,
-      };
-    } catch (err) {
-      return {
-        hookName: hook.name,
-        phase: hook.phase,
-        startedAt,
-        completedAt: Date.now(),
-        durationMs: Date.now() - startedAt,
-        passed: false,
-        error: (err as Error).message,
-      };
-    }
-  }
-}