@dommaker/harness 1.8.1 → 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,195 +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']);
-  });
-});
-
-describe('HookPipeline.runOne 按名执行单个 hook（#167）', () => {
-  it('按名执行并返回观测记录，不连带其它 hook', async () => {
-    const other = jest.fn().mockResolvedValue({ passed: true });
-    const target = jest.fn().mockResolvedValue({ passed: true });
-    const { pipeline } = makeRegistry([
-      { hook: { name: 'target', phase: 'before', execute: target } },
-      { hook: { name: 'other', phase: 'before', execute: other } },
-    ]);
-
-    const record = await pipeline.runOne('target', {});
-
-    expect(record.hookName).toBe('target');
-    expect(record.phase).toBe('before');
-    expect(record.passed).toBe(true);
-    expect(record.skipped).toBeUndefined();
-    expect(typeof record.durationMs).toBe('number');
-    expect(target).toHaveBeenCalledTimes(1);
-    expect(other).not.toHaveBeenCalled();
-  });
-
-  it('enabled:false → 实现体零调用，返回 skipped:true / passed:true 记录', async () => {
-    const disabled = jest.fn().mockResolvedValue({ passed: true });
-    const { pipeline } = makeRegistry([
-      { hook: { name: 'disabled', phase: 'before', execute: disabled }, config: { enabled: false } },
-    ]);
-
-    const record = await pipeline.runOne('disabled', {});
-
-    expect(disabled).not.toHaveBeenCalled();
-    expect(record.skipped).toBe(true);
-    expect(record.passed).toBe(true);
-    expect(record.hookName).toBe('disabled');
-  });
-
-  it('block + 实现体抛错 → 抛错，message 含 hook 名与原文', async () => {
-    const { pipeline } = makeRegistry([
-      {
-        hook: { name: 'guard', phase: 'before', execute: async () => { throw new Error('iron-law violated'); } },
-        config: { errorStrategy: 'block' },
-      },
-    ]);
-
-    await expect(pipeline.runOne('guard', {})).rejects.toThrow('iron-law violated');
-    await expect(pipeline.runOne('guard', {})).rejects.toThrow('[harness] hook "guard" blocked:');
-  });
-
-  it('block + 实现体返回 passed:false → 抛错，message 含 result.error 原文', async () => {
-    const { pipeline } = makeRegistry([
-      { hook: { name: 'guard', phase: 'before', execute: async () => ({ passed: false, error: 'boom' }) }, config: { errorStrategy: 'block' } },
-    ]);
-
-    await expect(pipeline.runOne('guard', {})).rejects.toThrow('[harness] hook "guard" blocked: boom');
-  });
-
-  it('warn + 失败 → resolve，返回 passed:false 带 error 的记录', async () => {
-    const { pipeline } = makeRegistry([
-      {
-        hook: { name: 'soft', phase: 'before', execute: async () => { throw new Error('soft-fail'); } },
-        config: { errorStrategy: 'warn' },
-      },
-    ]);
-
-    const record = await pipeline.runOne('soft', {});
-
-    expect(record.passed).toBe(false);
-    expect(record.error).toBe('soft-fail');
-    expect(record.skipped).toBeUndefined();
-  });
-
-  it('未知 hook 名 → 抛错（与注册表闭环口径一致，不静默跳过）', async () => {
-    const { pipeline } = makeRegistry([
-      { hook: { name: 'known', phase: 'before', execute: async () => ({ passed: true }) } },
-    ]);
-
-    await expect(pipeline.runOne('no_such_hook', {})).rejects.toThrow('no_such_hook');
-    await expect(pipeline.runOne('no_such_hook', {})).rejects.toThrow('未注册');
-  });
-
-  it('sampleRate < 1 时采样语义与 run 路径一致（未抽中 → 零调用 + sampled 记录）', async () => {
-    const execute = jest.fn().mockResolvedValue({ passed: true });
-    const { pipeline } = makeRegistry([
-      { hook: { name: 'sampled', phase: 'before', sampleRate: 0.5, execute } },
-    ]);
-
-    const randomSpy = jest.spyOn(Math, 'random').mockReturnValue(0.9);
-    try {
-      const record = await pipeline.runOne('sampled', {});
-      expect(execute).not.toHaveBeenCalled();
-      expect(record.sampled).toBe(true);
-      expect(record.passed).toBe(true);
-    } finally {
-      randomSpy.mockRestore();
-    }
-
-    const hitSpy = jest.spyOn(Math, 'random').mockReturnValue(0.1);
-    try {
-      const record = await pipeline.runOne('sampled', {});
-      expect(execute).toHaveBeenCalledTimes(1);
-      expect(record.sampled).toBeUndefined();
-    } finally {
-      hitSpy.mockRestore();
-    }
-  });
-});

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';
-}