pirates 4.0.7: intercept require calls using addHook and revert

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: intercept require calls using addHook and revert
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/pirates@4.0.7
Demonstrate these symbols/APIs:
  - addHook
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:630455916ba3ed2c7ba4e7d8c9ea7f29313f5613a77ff8cffccde25bee402020","constraints":{"executionContext":"node"},"contract":["assert addHook transforms required JavaScript modules matching extension criteria","assert addHook matcher predicate filters which module filenames are transformed","assert addHook supports custom file extensions using exts option","assert revert function returned by addHook restores original require behavior"],"goal":"intercept require calls using addHook and revert","kind":"HOW","packages":["pkg:npm/pirates@4.0.7"],"schemaVersion":1,"symbols":["addHook"]},"contractCommand":["node","test/contract.cjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/pirates@4.0.7"],"schemaVersion":1,"subject":"pkg:npm/pirates@4.0.7","symbols":["addHook"],"verifierAdapter":"node-typescript@1"}

KEY=VALUE_ORIGINAL

module.exports = {
  message: "HELLO_ORIGINAL",
};

module.exports = {
  status: "UNTOUCHED",
};

const { addHook } = require("pirates");

/**
 * Registers a require hook to intercept and transform required files.
 * @param {Function} hook - Function (code, filename) => string
 * @param {Object} [options] - Configuration options for addHook
 * @returns {Function} Revert function to unregister the hook
 */
function registerTransformHook(hook, options) {
  return addHook(hook, options);
}

module.exports = {
  registerTransformHook,
  addHook,
};

{
  "name": "pirates-hook-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "pirates-hook-sample",
      "version": "1.0.0",
      "dependencies": {
        "pirates": "4.0.7"
      }
    },
    "node_modules/pirates": {
      "version": "4.0.7",
      "resolved": "https://registry.npmjs.org/pirates/-/pirates-4.0.7.tgz",
      "integrity": "sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==",
      "license": "MIT",
      "engines": {
        "node": ">= 6"
      }
    }
  }
}

{
  "name": "pirates-hook-sample",
  "version": "1.0.0",
  "private": true,
  "description": "Intercept require calls using addHook and revert",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "pirates": "4.0.7"
  }
}

{
  "schemaVersion": 1,
  "goal": "intercept require calls using addHook and revert",
  "kind": "HOW",
  "packages": [
    "pkg:npm/pirates@4.0.7"
  ],
  "symbols": [
    "addHook"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const assert = require("node:assert/strict");
const path = require("node:path");
const { addHook, registerTransformHook } = require("../index.js");

const greetingPath = path.resolve(__dirname, "../fixtures/greeting.js");
const unmatchedPath = path.resolve(__dirname, "../fixtures/unmatched.js");
const customPath = path.resolve(__dirname, "../fixtures/custom.data");

function clearCache(filePath) {
  delete require.cache[filePath];
}

// Contract 1: addHook intercepts required JS files and transforms source code
{
  clearCache(greetingPath);
  const revert = addHook(
    (code, filename) => {
      return code.replace("HELLO_ORIGINAL", "HELLO_TRANSFORMED");
    },
    { exts: [".js"] }
  );

  const mod = require(greetingPath);
  assert.equal(mod.message, "HELLO_TRANSFORMED");

  revert();
  clearCache(greetingPath);
  const modReverted = require(greetingPath);
  assert.equal(modReverted.message, "HELLO_ORIGINAL");
}

// Contract 2: addHook respects matcher predicate option
{
  clearCache(greetingPath);
  clearCache(unmatchedPath);

  const revert = addHook(
    (code, filename) => {
      return code.replace("UNTOUCHED", "TOUCHED_MATCHED");
    },
    {
      matcher: (filename) => filename.includes("unmatched.js"),
      exts: [".js"],
    }
  );

  const modUnmatched = require(unmatchedPath);
  assert.equal(modUnmatched.status, "TOUCHED_MATCHED");

  const modGreeting = require(greetingPath);
  assert.equal(modGreeting.message, "HELLO_ORIGINAL");

  revert();
}

// Contract 3: addHook supports custom file extensions via exts option
{
  clearCache(customPath);
  const revert = addHook(
    (code, filename) => {
      const [key, val] = code.trim().split("=");
      return `module.exports = { ${key}: "PARSED_${val}" };`;
    },
    { exts: [".data"] }
  );

  const customMod = require(customPath);
  assert.equal(customMod.KEY, "PARSED_VALUE_ORIGINAL");

  revert();
}

// Contract 4: registerTransformHook wrapper returns revert function
{
  clearCache(greetingPath);
  const revert = registerTransformHook((code) => {
    return code.replace("HELLO_ORIGINAL", "HELLO_WRAPPER");
  });

  const mod = require(greetingPath);
  assert.equal(mod.message, "HELLO_WRAPPER");

  assert.equal(typeof revert, "function");
  revert();
  clearCache(greetingPath);
  const restored = require(greetingPath);
  assert.equal(restored.message, "HELLO_ORIGINAL");
}

console.log("All contract tests passed successfully.");