@dommaker/harness 1.8.1 → 1.10.0

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

package/src/hooks/pipeline.ts

@@ -1,202 +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 };
-  }
-
-  /**
-   * 按名执行单个 hook（#167）
-   *
-   * 与 run() 共用 executeOne 的采样与错误隔离路径（判定与错误策略的实现体
-   * 只有一份）；enabled / errorStrategy 的值来源仍是注册环节填充的
-   * EffectiveHook（唯一声明点 HookConfig，#159）。
-   *
-   * - enabled:false → 实现体零调用，返回 skipped:true / passed:true 记录
-   *   （镜像 sampled 先例：未执行 = 记录上一面旗，不是异常）
-   * - errorStrategy 'block' 且失败 → 抛 Error（message 含 hook 名与原文）；
-   *   'warn' 且失败 → resolve，返回 passed:false 带 error 的记录
-   * - 未知名 → 抛错（与 assertHookRegistryClosed 闭环口径一致，拒绝静默缺失）
-   *
-   * @param name hook 名称（须已注册）
-   * @param context 传递给 hook 的上下文
-   * @returns 管线观测记录
-   */
-  async runOne(name: string, context: C): Promise<HookExecutionRecord> {
-    const hook = this.registry.get(name);
-    if (!hook) {
-      throw new Error(
-        `[harness] hook 执行失败：hook "${name}" 未注册。请注册同名 HookDefinition 与 HookConfig 声明。`
-      );
-    }
-
-    if (!hook.enabled) {
-      const now = Date.now();
-      return {
-        hookName: hook.name,
-        phase: hook.phase,
-        startedAt: now,
-        completedAt: now,
-        durationMs: 0,
-        passed: true,
-        skipped: true,
-      };
-    }
-
-    const record = await this.executeOne(hook, context);
-    if (!record.passed && hook.errorStrategy === 'block') {
-      throw new Error(
-        `[harness] hook "${hook.name}" blocked: ${record.error ?? '未知错误'}`
-      );
-    }
-    return record;
-  }
-
-  /**
-   * 执行 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,
-      };
-    }
-  }
-}