tapable 2.3.3: SyncHook

# tapable.SyncHook lifecycle and contract verification

## Prior CSX search

`search_known_solution` was queried for `pkg:npm/tapable@2.3.3` covering symbol `tapable.SyncHook` with goal `verify tapable.SyncHook in pkg:npm/tapable@2.3.3`. Result returned `NO_SAFE_MATCH`.

## The tempting wrong model

Callers commonly assume:
1. `SyncHook` allows asynchronous tapping with `tapAsync` or `tapPromise`.
2. `SyncHook.call()` returns values returned by tapped listener functions.
3. Listener errors during `SyncHook.call()` are caught or allow subsequent listeners to continue.
4. All tap listeners always execute strictly in registration order regardless of `stage` or `before` options.

## Observable failure

1. In `tapable@2.3.3`, calling `hook.tapAsync()` on a `SyncHook` throws `Error: tapAsync is not supported on a SyncHook`.
2. Calling `hook.tapPromise()` on a `SyncHook` throws `Error: tapPromise is not supported on a SyncHook`.
3. `SyncHook.call()` always returns `undefined` synchronously, ignoring any return value from listeners.
4. An error thrown by any listener during `hook.call()` immediately halts execution of subsequent listeners and propagates synchronously to the caller.
5. Using `{ stage: number }` or `{ before: string }` in tap options reorders the execution priority of listeners.
6. Hook interceptors (`register`, `call`, `tap`) observe the complete lifecycle of tap registration and invocation.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify tapable.SyncHook in pkg:npm/tapable@2.3.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tapable@2.3.3
Demonstrate these symbols/APIs:
  - tapable.SyncHook

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:efc4cb14b6e140212afabacb887b610a395f439d955e13db32ee1157eee7678c","contract":["SyncHook instantiates a synchronous hook with declared parameter signatures","tap registers synchronous listener functions invoked by call in registration order","call passes arguments to registered tap listeners and returns undefined","tap with stage and before options alters listener execution order","intercept observes hook lifecycle events including call, tap, and register","tapAsync on SyncHook throws error indicating tapAsync is not supported","tapPromise on SyncHook throws error indicating tapPromise is not supported","listener error thrown during call halts subsequent tap execution and propagates synchronously"],"goal":"verify tapable.SyncHook in pkg:npm/tapable@2.3.3","kind":"HOW","packages":["pkg:npm/tapable@2.3.3"],"schemaVersion":1,"symbols":["tapable.SyncHook"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/tapable@2.3.3"],"schemaVersion":1,"subject":"pkg:npm/tapable@2.3.3","symbols":["tapable.SyncHook"],"verifierAdapter":"node-typescript@1"}

{
  "name": "csx-sample-tapable-synchook",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "csx-sample-tapable-synchook",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "tapable": "2.3.3"
      }
    },
    "node_modules/tapable": {
      "version": "2.3.3",
      "resolved": "https://registry.npmjs.org/tapable/-/tapable-2.3.3.tgz",
      "integrity": "sha512-uxc/zpqFg6x7C8vOE7lh6Lbda8eEL9zmVm/PLeTPBRhh1xCgdWaQ+J1CUieGpIfm2HdtsUpRv+HshiasBMcc6A==",
      "license": "MIT",
      "engines": {
        "node": ">=6"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/webpack"
      }
    }
  }
}

{
  "name": "csx-sample-tapable-synchook",
  "version": "1.0.0",
  "description": "verify tapable.SyncHook in pkg:npm/tapable@2.3.3",
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "tapable": "2.3.3"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify tapable.SyncHook in pkg:npm/tapable@2.3.3",
  "kind": "HOW",
  "packages": [
    "pkg:npm/tapable@2.3.3"
  ],
  "symbols": [
    "tapable.SyncHook"
  ]
}

import { SyncHook } from 'tapable';

/**
 * Creates a configured compiler/plugin lifecycle manager using SyncHook.
 */
export class CompilerLifecycle {
  constructor() {
    this.hooks = {
      initialize: new SyncHook(['config']),
      beforeCompile: new SyncHook(['params']),
      compile: new SyncHook(['compilation']),
      done: new SyncHook(['stats']),
    };
  }

  initialize(config) {
    this.hooks.initialize.call(config);
  }

  compile(params) {
    this.hooks.beforeCompile.call(params);
    const compilation = { id: 'compilation-1', params, logs: [] };
    this.hooks.compile.call(compilation);
    const stats = { compilation, timestamp: Date.now() };
    this.hooks.done.call(stats);
    return stats;
  }
}

/**
 * Demonstrates basic SyncHook instantiation and execution.
 */
export function createPipelineHook(argNames = ['context']) {
  return new SyncHook(argNames);
}

/**
 * Registers a synchronous tap plugin.
 */
export function registerPlugin(hook, nameOrOptions, fn) {
  hook.tap(nameOrOptions, fn);
}

/**
 * Executes the hook synchronously with arguments.
 */
export function triggerHook(hook, ...args) {
  return hook.call(...args);
}

import assert from 'node:assert/strict';
import { SyncHook } from 'tapable';
import {
  CompilerLifecycle,
  createPipelineHook,
  registerPlugin,
  triggerHook,
} from '../src/index.mjs';

try {
  // Contract 1: SyncHook instantiates a synchronous hook with declared parameter signatures
  const hookWithArgs = new SyncHook(['source', 'target']);
  assert.equal(typeof SyncHook, 'function', 'SyncHook must be exported as a constructor function');
  assert.equal(hookWithArgs.isUsed(), false, 'New hook without taps should report isUsed() as false');
  assert.deepEqual(hookWithArgs._args, ['source', 'target'], 'Hook should record declared argument names');

  const defaultHook = createPipelineHook();
  assert.deepEqual(defaultHook._args, ['context'], 'createPipelineHook should initialize with default argument names');

  // Contract 2: tap registers synchronous listener functions invoked by call in registration order
  const callOrder = [];
  const hook2 = new SyncHook(['payload']);
  registerPlugin(hook2, 'FirstPlugin', (payload) => {
    callOrder.push(`first:${payload}`);
  });
  registerPlugin(hook2, 'SecondPlugin', (payload) => {
    callOrder.push(`second:${payload}`);
  });

  assert.equal(hook2.isUsed(), true, 'Hook with registered taps should report isUsed() as true');
  triggerHook(hook2, 'data1');
  assert.deepEqual(
    callOrder,
    ['first:data1', 'second:data1'],
    'Tapped listeners should be called in registration order',
  );

  // Contract 3: call passes arguments to registered tap listeners and returns undefined
  let receivedArgs = null;
  const hook3 = new SyncHook(['a', 'b', 'c']);
  hook3.tap('InspectPlugin', (a, b, c) => {
    receivedArgs = { a, b, c };
    return 'unwanted-return-value';
  });

  const callResult = hook3.call('arg1', 'arg2', 'arg3');
  assert.equal(callResult, undefined, 'SyncHook.call must return undefined regardless of listener return values');
  assert.deepEqual(
    receivedArgs,
    { a: 'arg1', b: 'arg2', c: 'arg3' },
    'SyncHook.call must pass all declared arguments to tap listeners',
  );

  // Contract 4: tap with stage and before options alters listener execution order
  const stagedOrder = [];
  const stagedHook = new SyncHook(['item']);
  stagedHook.tap({ name: 'DefaultStage', stage: 0 }, (item) => {
    stagedOrder.push(`default:${item}`);
  });
  stagedHook.tap({ name: 'LateStage', stage: 10 }, (item) => {
    stagedOrder.push(`late:${item}`);
  });
  stagedHook.tap({ name: 'EarlyStage', stage: -10 }, (item) => {
    stagedOrder.push(`early:${item}`);
  });
  stagedHook.tap({ name: 'PriorPlugin', before: 'EarlyStage' }, (item) => {
    stagedOrder.push(`prior:${item}`);
  });

  stagedHook.call('item1');
  assert.deepEqual(
    stagedOrder,
    ['prior:item1', 'early:item1', 'default:item1', 'late:item1'],
    'Stage and before options must determine correct execution order',
  );

  // Contract 5: intercept observes hook lifecycle events including call, tap, and register
  const interceptedEvents = [];
  const interceptHook = new SyncHook(['val']);
  interceptHook.intercept({
    register: (tapInfo) => {
      interceptedEvents.push(`register:${tapInfo.name}`);
      return tapInfo;
    },
    call: (...args) => {
      interceptedEvents.push(`call:${args.join(',')}`);
    },
    tap: (tapInfo) => {
      interceptedEvents.push(`tap:${tapInfo.name}`);
    },
  });

  interceptHook.tap('MonitoredPlugin', (val) => {
    interceptedEvents.push(`run:${val}`);
  });
  interceptHook.call('ping');

  assert.deepEqual(
    interceptedEvents,
    ['register:MonitoredPlugin', 'call:ping', 'tap:MonitoredPlugin', 'run:ping'],
    'Interceptors must capture register, call, and tap events in sequence',
  );

  // Contract 6: tapAsync on SyncHook throws error indicating tapAsync is not supported
  const syncOnlyHook = new SyncHook(['task']);
  assert.throws(
    () => {
      syncOnlyHook.tapAsync('AsyncAttempt', (_task, callback) => callback());
    },
    {
      name: 'Error',
      message: /tapAsync is not supported on a SyncHook/i,
    },
    'Calling tapAsync on a SyncHook must throw unsupported error',
  );

  // Contract 7: tapPromise on SyncHook throws error indicating tapPromise is not supported
  assert.throws(
    () => {
      syncOnlyHook.tapPromise('PromiseAttempt', async (_task) => {});
    },
    {
      name: 'Error',
      message: /tapPromise is not supported on a SyncHook/i,
    },
    'Calling tapPromise on a SyncHook must throw unsupported error',
  );

  // Contract 8: listener error thrown during call halts subsequent tap execution and propagates synchronously
  const errorOrder = [];
  const failingHook = new SyncHook(['ctx']);
  failingHook.tap('FirstStep', () => {
    errorOrder.push('step1');
  });
  failingHook.tap('FailingStep', () => {
    errorOrder.push('step2');
    throw new Error('Sync hook aborted in step 2');
  });
  failingHook.tap('NeverRunStep', () => {
    errorOrder.push('step3');
  });

  assert.throws(
    () => {
      failingHook.call('ctx-data');
    },
    {
      name: 'Error',
      message: 'Sync hook aborted in step 2',
    },
    'Error in listener must synchronously propagate to hook.call caller',
  );
  assert.deepEqual(
    errorOrder,
    ['step1', 'step2'],
    'Subsequent listeners must not run after an unhandled listener error',
  );

  // Demonstrate CompilerLifecycle workflow integration
  const lifecycle = new CompilerLifecycle();
  const lifecycleEvents = [];
  lifecycle.hooks.initialize.tap('InitPlugin', (cfg) => lifecycleEvents.push(`init:${cfg.mode}`));
  lifecycle.hooks.beforeCompile.tap('BeforeCompilePlugin', (p) => lifecycleEvents.push(`before:${p.entry}`));
  lifecycle.hooks.compile.tap('CompilePlugin', (comp) => {
    comp.logs.push('compiled');
    lifecycleEvents.push('compile');
  });
  lifecycle.hooks.done.tap('DonePlugin', (stats) => lifecycleEvents.push(`done:${stats.compilation.id}`));

  lifecycle.initialize({ mode: 'production' });
  const stats = lifecycle.compile({ entry: './src/index.mjs' });
  assert.equal(stats.compilation.id, 'compilation-1');
  assert.deepEqual(stats.compilation.logs, ['compiled']);
  assert.deepEqual(
    lifecycleEvents,
    ['init:production', 'before:./src/index.mjs', 'compile', 'done:compilation-1'],
    'CompilerLifecycle must execute all hooks in expected sequence',
  );

  console.log('All tapable.SyncHook contract assertions passed successfully.');
} catch (err) {
  console.error('Contract verification failed:', err);
  process.exit(1);
}