@evomap/evolver 1.89.3 → 1.89.4

package/scripts/build_binaries.js

@@ -1,479 +0,0 @@
-#!/usr/bin/env node
-/* eslint-disable no-console */
-//
-// build_binaries.js — produce standalone CLI binaries of evolver via the
-// hardened "obfuscator -> bun bundle -> bun compile" pipeline.
-//
-// Pipeline (decided after empirical testing — see notes at end of this file):
-//
-//   1. bun build ./index.js --target=node --outfile=stage/bundled.js
-//        -> resolves all require() into one self-contained file.
-//
-//   2. javascript-obfuscator stage/bundled.js -> stage/bundled.obf.js
-//        -> high-strength config: stringArray (rc4) + controlFlowFlattening +
-//           deadCodeInjection + identifier hex + splitStrings + numbers-to-expr.
-//        -> selfDefending MUST be off: it triggers infinite-loop self-defense
-//           when bun later wraps the bundle inside its standalone container.
-//        -> renameGlobals MUST be off (otherwise bun's bundle step fails to
-//           resolve dynamic require strings — but we already pass a single-file
-//           bundle here, so this no longer applies; kept off for safety).
-//        -> transformObjectKeys MUST be off (similar reason as above).
-//
-//   3. bun build stage/bundled.obf.js --compile --minify --target=<TARGET>
-//        -> embeds bun runtime + bundled+obfuscated JS into a single executable.
-//        -> --minify gives a second-pass identifier/whitespace squash on top
-//           of the obfuscator output.
-//
-// Targets shipped (decision per AGENTS sync 2026-05-05):
-//   bun-darwin-arm64  -> evolver-darwin-arm64
-//   bun-darwin-x64    -> evolver-darwin-x64
-//   bun-linux-x64     -> evolver-linux-x64
-//   bun-linux-arm64   -> evolver-linux-arm64
-//   bun-windows-x64   -> evolver-windows-x64.exe
-//
-// Usage:
-//   node scripts/build_binaries.js              # builds all 4 targets
-//   node scripts/build_binaries.js --target=darwin-arm64
-//   node scripts/build_binaries.js --skip-obfuscate    # bun-only fast path (DEV)
-//   node scripts/build_binaries.js --out-dir=dist-binaries
-//   node scripts/build_binaries.js --dry-run
-//
-// Outputs:
-//   <outDir>/evolver-<platform>           binary
-//   <outDir>/evolver-<platform>.sha256    hash file (one line)
-//   <outDir>/SHA256SUMS.txt               combined sha256 manifest
-//
-// Exit codes:
-//   0  success
-//   1  precondition failed (missing tool, version mismatch)
-//   2  build step failed
-//   3  smoke test of produced binary failed
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-const { execFileSync, spawnSync } = require('child_process');
-
-// ---------- argv ----------
-
-const argv = process.argv.slice(2);
-const OPTS = {
-  target: null,
-  skipObfuscate: false,
-  outDir: 'dist-binaries',
-  dryRun: false,
-  keepStage: false,
-};
-
-for (const a of argv) {
-  if (a === '--skip-obfuscate') OPTS.skipObfuscate = true;
-  else if (a === '--dry-run') OPTS.dryRun = true;
-  else if (a === '--keep-stage') OPTS.keepStage = true;
-  else if (a.startsWith('--target=')) OPTS.target = a.slice('--target='.length);
-  else if (a.startsWith('--out-dir=')) OPTS.outDir = a.slice('--out-dir='.length);
-  else if (a === '--help' || a === '-h') {
-    console.log(fs.readFileSync(__filename, 'utf8').split('\n').filter(l => l.startsWith('//')).map(l => l.replace(/^\/\/ ?/, '')).slice(0, 50).join('\n'));
-    process.exit(0);
-  } else {
-    console.error(`build_binaries: unknown argument: ${a}`);
-    process.exit(1);
-  }
-}
-
-// ---------- constants ----------
-
-const REPO_ROOT = path.resolve(__dirname, '..');
-const ENTRY = path.join(REPO_ROOT, 'index.js');
-const STAGE_DIR = path.join(REPO_ROOT, '.binary-stage');
-const OUT_DIR = path.resolve(REPO_ROOT, OPTS.outDir);
-
-const ALL_TARGETS = [
-  { triple: 'bun-darwin-arm64',  name: 'evolver-darwin-arm64'  },
-  { triple: 'bun-darwin-x64',    name: 'evolver-darwin-x64'    },
-  { triple: 'bun-linux-x64',     name: 'evolver-linux-x64'     },
-  { triple: 'bun-linux-arm64',   name: 'evolver-linux-arm64'   },
-  { triple: 'bun-windows-x64',   name: 'evolver-windows-x64.exe' },
-];
-
-const TARGETS = OPTS.target
-  ? ALL_TARGETS.filter(t => t.name.endsWith(OPTS.target) || t.triple.endsWith(OPTS.target))
-  : ALL_TARGETS;
-
-if (TARGETS.length === 0) {
-  console.error(`build_binaries: target "${OPTS.target}" matched no known triple. Known: ${ALL_TARGETS.map(t => t.triple).join(', ')}`);
-  process.exit(1);
-}
-
-// ---------- helpers ----------
-
-function step(label) {
-  console.log(`\n>> ${label}`);
-}
-
-function run(cmd, args, opts = {}) {
-  if (OPTS.dryRun) {
-    console.log(`  [dry-run] ${cmd} ${args.join(' ')}`);
-    return { status: 0, stdout: '', stderr: '' };
-  }
-  const r = spawnSync(cmd, args, { stdio: 'inherit', ...opts });
-  if (r.status !== 0) {
-    console.error(`  command failed (exit ${r.status}): ${cmd} ${args.join(' ')}`);
-    process.exit(2);
-  }
-  return r;
-}
-
-function runCapture(cmd, args, opts = {}) {
-  // Preflight version checks must always run (even in dry-run mode); use this
-  // helper only for read-only commands.
-  return execFileSync(cmd, args, { encoding: 'utf8', ...opts });
-}
-
-function ensureDir(d) {
-  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
-}
-
-function rmDir(d) {
-  if (fs.existsSync(d)) fs.rmSync(d, { recursive: true, force: true });
-}
-
-function sha256(filePath) {
-  const buf = fs.readFileSync(filePath);
-  return crypto.createHash('sha256').update(buf).digest('hex');
-}
-
-// ---------- preflight ----------
-
-step('Preflight');
-
-if (!fs.existsSync(ENTRY)) {
-  console.error(`  ERROR: entry not found: ${ENTRY}`);
-  process.exit(1);
-}
-
-try {
-  const v = runCapture('bun', ['--version']).trim();
-  console.log(`  bun: ${v}`);
-  // Pin a sane minimum. As of writing pipeline tested on 1.3.13.
-  const [maj, min] = v.split('.').map(Number);
-  if (maj < 1 || (maj === 1 && min < 3)) {
-    console.error(`  ERROR: bun >= 1.3 required; found ${v}`);
-    process.exit(1);
-  }
-} catch (e) {
-  console.error('  ERROR: `bun` not found in PATH. Install from https://bun.com');
-  process.exit(1);
-}
-
-if (!OPTS.skipObfuscate) {
-  try {
-    require.resolve('javascript-obfuscator', { paths: [REPO_ROOT] });
-    console.log('  javascript-obfuscator: present');
-  } catch {
-    console.error('  ERROR: javascript-obfuscator not installed. Run `npm install` in repo root first.');
-    process.exit(1);
-  }
-}
-
-const releaseVersion = process.env.RELEASE_VERSION
-  || JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8')).version;
-console.log(`  release version: ${releaseVersion}`);
-console.log(`  targets: ${TARGETS.map(t => t.name).join(', ')}`);
-console.log(`  out dir: ${OUT_DIR}`);
-if (OPTS.skipObfuscate) console.log('  WARN: --skip-obfuscate => DEV-grade binary, do NOT distribute');
-if (OPTS.dryRun) console.log('  mode: DRY RUN (no files will change)');
-
-// ---------- stage 1: bun bundle ----------
-
-step('Stage 1 — bun bundle (resolve require tree to one file)');
-
-ensureDir(STAGE_DIR);
-const BUNDLED_JS = path.join(STAGE_DIR, 'bundled.js');
-
-// `--external '@napi-rs/keyring'`: keyring is an optional dep loaded via
-// dynamic require() in workspace-id; bun otherwise tries to bundle the
-// platform-specific `.node` file as a second output asset, which makes
-// `bun build … --outfile=…` fail with "cannot write multiple output files
-// without an output directory". Treating it as external preserves the
-// existing optional-fallback behaviour (require throws → FS path used) in
-// the standalone binaries.
-run('bun', ['build', ENTRY, '--target=node', `--outfile=${BUNDLED_JS}`, '--external', '@napi-rs/keyring']);
-
-const bundleSize = OPTS.dryRun ? 0 : fs.statSync(BUNDLED_JS).size;
-console.log(`  bundled.js: ${(bundleSize / 1024 / 1024).toFixed(2)} MB`);
-
-// ---------- stage 2: obfuscate ----------
-
-let payloadJs = BUNDLED_JS;
-
-if (!OPTS.skipObfuscate) {
-  step('Stage 2 — javascript-obfuscator (high strength, bundler-safe)');
-  const OBF_JS = path.join(STAGE_DIR, 'bundled.obf.js');
-
-  if (!OPTS.dryRun) {
-    const O = require(require.resolve('javascript-obfuscator', { paths: [REPO_ROOT] }));
-    const src = fs.readFileSync(BUNDLED_JS, 'utf8');
-    // Seed obfuscation from release version: gives same-version reruns a
-    // narrow PRNG path, but the obfuscator has internal non-determinism
-    // beyond the seed (Set iteration / stringArray rotation timing) so two
-    // runs with the same seed can still differ slightly. Empirically ~5%
-    // of those runs emit invalid syntax (e.g. mangling `new.target` to
-    // `#target`, which then crashes `bun compile`). Validate after each
-    // attempt and retry — see RETRY note in pipeline rationale below.
-    const baseSeed = parseInt(crypto.createHash('sha256').update(`evolver:${releaseVersion}`).digest('hex').slice(0, 8), 16);
-    const obfOpts = {
-      compact: true,
-      controlFlowFlattening: true,
-      controlFlowFlatteningThreshold: 0.75,
-      deadCodeInjection: true,
-      deadCodeInjectionThreshold: 0.4,
-      stringArray: true,
-      stringArrayEncoding: ['rc4'],
-      stringArrayThreshold: 0.85,
-      identifierNamesGenerator: 'hexadecimal',
-      // The next three MUST stay disabled — they are incompatible with bun's
-      // standalone wrapping (selfDefending + transformObjectKeys + renameGlobals
-      // each break either compile-time bundling or run-time module resolution).
-      // See pipeline notes at top of file.
-      renameGlobals: false,
-      selfDefending: false,
-      transformObjectKeys: false,
-      debugProtection: false,
-      splitStrings: true,
-      splitStringsChunkLength: 8,
-      numbersToExpressions: true,
-      unicodeEscapeSequence: true,
-      target: 'node',
-    };
-
-    const MAX_OBF_ATTEMPTS_RAW = process.env.OBF_MAX_ATTEMPTS;
-    // Default 12 (was 4). The obfuscator's new.target -> #target mangling is
-    // non-deterministic ACROSS PROCESSES, not just across seeds: the same seed
-    // + same input can pass in one node process and fail in another (Set
-    // iteration / internal-state timing). So perturbing the seed per attempt is
-    // not the real lever — re-running the obfuscate call is. The v1.87.4 deploy
-    // hit 4/4 consecutive failures with the default of 4 and aborted the npm
-    // publish + binary upload. At an observed per-attempt failure rate that can
-    // run well above the historical ~5% for some bundles, 4 retries is too few;
-    // 12 drives the all-fail probability to negligible while costing only extra
-    // attempts on the rare unlucky run. Override with OBF_MAX_ATTEMPTS.
-    const MAX_OBF_ATTEMPTS = MAX_OBF_ATTEMPTS_RAW === undefined
-      ? 12
-      : parseInt(MAX_OBF_ATTEMPTS_RAW, 10);
-    if (!Number.isInteger(MAX_OBF_ATTEMPTS) || MAX_OBF_ATTEMPTS < 1) {
-      console.error(`  ERROR: OBF_MAX_ATTEMPTS must be a positive integer; got ${JSON.stringify(MAX_OBF_ATTEMPTS_RAW)}.`);
-      process.exit(1);
-    }
-    let attempt = 0;
-    let usedSeed = baseSeed;
-    let lastValidationErr = null;
-    let succeeded = false;
-    while (attempt < MAX_OBF_ATTEMPTS) {
-      attempt++;
-      // Perturb seed on retries to dodge a stuck PRNG path. Attempt 1 keeps
-      // the canonical seed for best-effort reproducibility; later attempts
-      // shift by attempt index so the next deploy gets a fresh trajectory.
-      usedSeed = baseSeed + (attempt - 1);
-      const t0 = Date.now();
-      const result = O.obfuscate(src, { ...obfOpts, seed: usedSeed });
-      fs.writeFileSync(OBF_JS, result.getObfuscatedCode());
-      const obfSize = fs.statSync(OBF_JS).size;
-      const obfSecs = ((Date.now() - t0) / 1000).toFixed(1);
-
-      const check = spawnSync('node', ['--check', OBF_JS], { encoding: 'utf8' });
-      if (check.status !== 0) {
-        lastValidationErr = (check.stderr || check.stdout || '').split('\n').slice(0, 3).join(' | ');
-        console.warn(`  attempt ${attempt}/${MAX_OBF_ATTEMPTS}: obfuscator output failed node --check (${lastValidationErr.slice(0, 200)}); retrying with perturbed seed...`);
-        continue;
-      }
-      // Second gate: bun's compile-time parser is stricter than node's.
-      // 1.87.x (post `@napi-rs/keyring` dep) revealed that ~5% of obfuscator
-      // outputs that pass `node --check` still trip bun with errors like
-      // `Expected "in" but found ","`. Probe with a cheap bundle-only call
-      // (no --compile, native target) to fail fast and feed back into the
-      // seed-perturbation loop instead of dying in stage 3.
-      const bunProbe = spawnSync('bun', [
-        'build', OBF_JS,
-        '--target=bun',
-        `--outfile=${path.join(STAGE_DIR, 'bundled.obf.bunprobe.js')}`,
-      ], { encoding: 'utf8' });
-      if (bunProbe.status !== 0) {
-        lastValidationErr = (bunProbe.stderr || bunProbe.stdout || '').split('\n').slice(0, 3).join(' | ');
-        console.warn(`  attempt ${attempt}/${MAX_OBF_ATTEMPTS}: obfuscator output rejected by bun parser (${lastValidationErr.slice(0, 200)}); retrying with perturbed seed...`);
-        continue;
-      }
-      console.log(`  obfuscation: ${obfSecs}s, output ${(obfSize / 1024 / 1024).toFixed(2)} MB (attempt ${attempt}/${MAX_OBF_ATTEMPTS}, seed=0x${usedSeed.toString(16)})`);
-      succeeded = true;
-      break;
-    }
-    if (!succeeded) {
-      console.error(`  ERROR: javascript-obfuscator produced syntactically invalid output in ${MAX_OBF_ATTEMPTS} attempts.`);
-      console.error(`         last error: ${lastValidationErr || '(none — loop did not run)'}`);
-      console.error(`         raise OBF_MAX_ATTEMPTS env var to retry more times, or temporarily run with --skip-obfuscate.`);
-      process.exit(2);
-    }
-  } else {
-    console.log('  [dry-run] would obfuscate stage/bundled.js -> stage/bundled.obf.js (with retry-on-syntax-error)');
-  }
-
-  payloadJs = OBF_JS;
-} else {
-  console.log('\n>> Stage 2 — SKIPPED (--skip-obfuscate)');
-}
-
-// ---------- stage 3: per-target compile ----------
-
-step(`Stage 3 — bun compile (${TARGETS.length} target${TARGETS.length === 1 ? '' : 's'})`);
-
-// Idempotency: scrub OUT_DIR up front so stale binaries from a prior partial
-// run can't leak into a subsequent `gh release upload dist-binaries/*`.
-if (!OPTS.dryRun) {
-  rmDir(OUT_DIR);
-}
-ensureDir(OUT_DIR);
-const sums = [];
-
-for (const t of TARGETS) {
-  const outPath = path.join(OUT_DIR, t.name);
-  console.log(`\n  --- ${t.triple} -> ${path.relative(REPO_ROOT, outPath)} ---`);
-
-  run('bun', [
-    'build',
-    payloadJs,
-    '--compile',
-    '--minify',
-    `--target=${t.triple}`,
-    `--outfile=${outPath}`,
-  ]);
-
-  if (!OPTS.dryRun) {
-    const stat = fs.statSync(outPath);
-    fs.chmodSync(outPath, 0o755);
-    const hash = sha256(outPath);
-    fs.writeFileSync(`${outPath}.sha256`, `${hash}  ${t.name}\n`);
-    sums.push(`${hash}  ${t.name}`);
-    console.log(`    size: ${(stat.size / 1024 / 1024).toFixed(1)} MB   sha256: ${hash.slice(0, 16)}…`);
-  }
-}
-
-// Smoke test only the host platform binary (cross-platform binaries cannot
-// be executed on the build host without an emulator; skip them by design).
-const hostTriple = (() => {
-  const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
-  const plat = process.platform === 'darwin' ? 'darwin'
-             : process.platform === 'linux'  ? 'linux'
-             : process.platform === 'win32'  ? 'windows'
-             : null;
-  return plat ? `${plat}-${arch}` : null;
-})();
-
-if (!OPTS.dryRun && hostTriple) {
-  // Match against the triple suffix (e.g. "darwin-arm64"), since the binary
-  // name on Windows includes a ".exe" extension.
-  const hostBin = TARGETS.find(t => t.triple.endsWith(hostTriple));
-  if (hostBin) {
-    step(`Stage 4 — smoke test ${hostBin.name}`);
-    const r = spawnSync(path.join(OUT_DIR, hostBin.name), ['--help'], {
-      timeout: 15000,
-      encoding: 'utf8',
-    });
-    if (r.status !== 0 || !r.stdout || !r.stdout.includes('Usage:')) {
-      console.error('  ERROR: smoke test failed.');
-      console.error(`    exit: ${r.status}`);
-      console.error(`    stdout: ${(r.stdout || '').slice(0, 200)}`);
-      console.error(`    stderr: ${(r.stderr || '').slice(0, 200)}`);
-      process.exit(3);
-    }
-    console.log('  smoke test: OK');
-  }
-}
-
-// ---------- write combined SHA256SUMS ----------
-
-if (!OPTS.dryRun) {
-  step('Writing combined SHA256SUMS.txt');
-  const sumsFile = path.join(OUT_DIR, 'SHA256SUMS.txt');
-  fs.writeFileSync(sumsFile, sums.join('\n') + '\n');
-  console.log(`  wrote ${path.relative(REPO_ROOT, sumsFile)}`);
-}
-
-// ---------- cleanup ----------
-
-if (!OPTS.keepStage && !OPTS.dryRun) {
-  rmDir(STAGE_DIR);
-} else if (OPTS.keepStage) {
-  console.log(`\n  (kept stage at ${path.relative(REPO_ROOT, STAGE_DIR)} for inspection)`);
-}
-
-step(`Done. ${TARGETS.length} binar${TARGETS.length === 1 ? 'y' : 'ies'} in ${path.relative(REPO_ROOT, OUT_DIR)}/`);
-console.log('  next: gh release upload v<ver> dist-binaries/* --repo EvoMap/evolver');
-
-//
-// =====================================================================
-//  PIPELINE RATIONALE — 2026-05-05
-// =====================================================================
-//
-// Why "bun-bundle then obfuscate" rather than the more obvious
-// "obfuscate src/ then bun-bundle":
-//
-//   javascript-obfuscator at high strength (stringArray + RC4 +
-//   transformObjectKeys + ...) rewrites string literals through a runtime
-//   lookup function: require('./gep/paths') becomes
-//   require(_0xLOOKUP(0x82b)). Bun's bundler does static analysis on
-//   require() arguments at compile time, so it cannot resolve those
-//   dynamic require calls and the resulting binary throws "Cannot find
-//   module './gep/paths'" on first invocation.
-//
-//   By bundling FIRST, every require() is inlined and resolved before the
-//   obfuscator ever sees the code. The obfuscator then operates on a
-//   single self-contained file with no remaining dynamic requires, so
-//   stringArray and friends are safe.
-//
-// Why selfDefending must stay OFF:
-//
-//   selfDefending: true injects a guard that hangs (infinite while loop)
-//   when it detects formatting changes. bun --compile wraps the JS payload
-//   in a standalone executable container that re-emits the source with
-//   different whitespace + line endings, which trips the guard immediately.
-//   Symptom: binary launches, opens stdio, then never exits.
-//
-// Why transformObjectKeys must stay OFF:
-//
-//   Same family of issue — it rewrites top-level module.exports / exports
-//   patterns in ways that bun's standalone runtime cannot rebuild.
-//
-// Why renameGlobals must stay OFF:
-//
-//   Not strictly required after the bundle step (no external require'd
-//   modules remain), but kept off as a safety belt; the cost is small
-//   because identifier hashing already covers >99% of names through
-//   identifierNamesGenerator='hexadecimal'.
-//
-// Smoke test policy:
-//
-//   We only smoke test the binary that matches the BUILD HOST triple.
-//   Cross-compiled binaries can't be executed without an emulator
-//   (qemu-user-static on linux, Rosetta on darwin-x64-on-arm64). CI/CD
-//   in GitHub Actions on `runs-on: macos-latest, ubuntu-latest` should
-//   set up the matrix so each runner smoke-tests its own native target.
-//
-// Stage 2 retry-on-syntax-error (added 2026-05-22, v1.85.0 deploy
-// post-mortem):
-//
-//   The v1.85.0 release deploy hit `bun compile` failing with
-//   `Expected "in" but found ","` at offset ~1.5MB into bundled.obf.js.
-//   The failing region contained `(#target,this)` — javascript-obfuscator
-//   had mangled `new.target` into `#target` (a private class field syntax
-//   that's only legal inside a class body). A from-scratch rebuild on the
-//   same source + seed produced a different output (15.18 MB vs 15.14 MB)
-//   that compiled cleanly, confirming the obfuscator has internal
-//   non-determinism beyond the user-supplied seed.
-//
-//   Mitigation: after each obfuscation attempt, run `node --check` on the
-//   output; if syntax is invalid, perturb the seed by +attempt and retry
-//   up to OBF_MAX_ATTEMPTS times (default 4). Cost of validation is
-//   ~1 second on 15 MB; cost of catching the failure here vs after a
-//   doomed bun compile pass is roughly 50s saved per failure.
-//

package/scripts/check-changelog.js

@@ -1,166 +0,0 @@
-'use strict';
-
-/**
- * CHANGELOG release-section integrity guard.
- *
- * Catches the misattribution pattern that bit us with #540 / PR #107:
- * an entry filed under `## [X.Y.Z]` AFTER v1.85.0 was already published
- * to npm, so the changelog claimed a fix the binary didn't contain.
- *
- * Algorithm: for every `## [X.Y.Z]` heading in CHANGELOG.md that has a
- * matching git tag (`vX.Y.Z`), compare the section content at HEAD
- * against the section content at that tag. If they differ, somebody
- * edited a frozen-and-released section — fail loud.
- *
- * Notes:
- *   - `## [Unreleased]` is exempt (it's the staging area, no tag).
- *   - Version headings without a corresponding tag are exempt — that's
- *     usually the "preparing X.Y.Z" state right before the tag exists.
- *   - Tag lookup is local-only (`git rev-parse`); CI must `git fetch
- *     --tags` first if it runs on a shallow clone.
- *   - `repoRoot` is injectable so tests don't need to monkey-patch the
- *     module by re-evaluating source (see PR #115 review).
- *
- * Usage:
- *   node scripts/check-changelog.js              # CLI mode, exits 0/1
- *   const { checkChangelogIntegrity } = require('./check-changelog');
- *   const result = checkChangelogIntegrity({ repoRoot });
- */
-
-const { execFileSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-
-const DEFAULT_REPO_ROOT = path.resolve(__dirname, '..');
-
-function readChangelogAtHead(repoRoot) {
-  return fs.readFileSync(path.join(repoRoot, 'CHANGELOG.md'), 'utf8');
-}
-
-function readChangelogAtRef(repoRoot, ref) {
-  try {
-    return execFileSync('git', ['show', `${ref}:CHANGELOG.md`], {
-      cwd: repoRoot,
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    });
-  } catch {
-    return null;
-  }
-}
-
-function tagExists(repoRoot, tag) {
-  try {
-    execFileSync('git', ['rev-parse', '--verify', `refs/tags/${tag}`], {
-      cwd: repoRoot,
-      stdio: ['ignore', 'ignore', 'ignore'],
-    });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// Pull every `## [X.Y.Z]` heading from the file, skipping `[Unreleased]`.
-function listReleasedVersionHeadings(text) {
-  const versions = [];
-  const re = /^## \[(\d+\.\d+\.\d+(?:[-+][\w.]+)?)\]/gm;
-  let m;
-  while ((m = re.exec(text)) !== null) {
-    versions.push(m[1]);
-  }
-  return versions;
-}
-
-// Extract the body between `## [X.Y.Z]` and the next `## [` (or EOF).
-// Normalises trailing whitespace and trailing blank lines so a stray
-// newline doesn't fail the equality check.
-//
-// Heading match is line-anchored (`/^## \[X\.Y\.Z\]/m`) so a fenced
-// code block or quoted text containing `## [X.Y.Z]` mid-line cannot be
-// mistaken for the section start (Bugbot PR #115 review).
-function extractSection(text, version) {
-  const escaped = version.replace(/[.+]/g, (c) => '\\' + c);
-  const re = new RegExp(`^## \\[${escaped}\\]`, 'm');
-  const match = re.exec(text);
-  if (!match) return null;
-  const after = match.index + match[0].length;
-  const rest = text.slice(after);
-  const nextRel = rest.search(/\n## \[/);
-  const raw = nextRel === -1 ? rest : rest.slice(0, nextRel);
-  return raw
-    .split('\n')
-    .map((line) => line.replace(/\s+$/, ''))
-    .join('\n')
-    .replace(/\n+$/, '');
-}
-
-function checkChangelogIntegrity(opts) {
-  const repoRoot = (opts && opts.repoRoot) || DEFAULT_REPO_ROOT;
-  const head = readChangelogAtHead(repoRoot);
-  const versions = listReleasedVersionHeadings(head);
-
-  const drift = [];
-  const skipped = [];
-
-  for (const version of versions) {
-    const tag = `v${version}`;
-    if (!tagExists(repoRoot, tag)) {
-      skipped.push({ version, reason: 'no matching git tag (probably preparing this release)' });
-      continue;
-    }
-    const tagText = readChangelogAtRef(repoRoot, tag);
-    if (tagText == null) {
-      skipped.push({ version, reason: `tag ${tag} exists but its CHANGELOG.md is unreadable` });
-      continue;
-    }
-    const headSection = extractSection(head, version);
-    const tagSection = extractSection(tagText, version);
-    if (headSection == null || tagSection == null) {
-      skipped.push({ version, reason: 'section parse failed' });
-      continue;
-    }
-    if (headSection !== tagSection) {
-      drift.push({ version, tag });
-    }
-  }
-
-  return { drift, skipped, checked: versions.length - skipped.length };
-}
-
-function main() {
-  const result = checkChangelogIntegrity();
-
-  process.stdout.write(`\n=== CHANGELOG release-section guard ===\n`);
-  process.stdout.write(`Checked ${result.checked} released version section(s); skipped ${result.skipped.length}.\n`);
-
-  for (const s of result.skipped) {
-    process.stdout.write(`  [skip] ${s.version}: ${s.reason}\n`);
-  }
-
-  if (result.drift.length === 0) {
-    process.stdout.write(`\n[OK] No released CHANGELOG section was edited after its release tag.\n`);
-    return 0;
-  }
-
-  process.stderr.write(`\n[FAIL] ${result.drift.length} CHANGELOG section(s) diverged from their release tag:\n`);
-  for (const d of result.drift) {
-    process.stderr.write(`  - ## [${d.version}] differs from ${d.tag}:CHANGELOG.md\n`);
-  }
-  process.stderr.write(
-    `\nReleased sections must stay frozen. Move any new entries under ## [Unreleased],\n` +
-    `or, if the entry was genuinely missing from the release, amend it on a hotfix\n` +
-    `branch and tag a patch release.\n`
-  );
-  return 1;
-}
-
-if (require.main === module) {
-  process.exit(main());
-}
-
-module.exports = {
-  checkChangelogIntegrity,
-  extractSection,         // for tests
-  listReleasedVersionHeadings, // for tests
-};