@opengsd/gsd-core 1.3.0 → 1.4.0-rc.1

package/scripts/check-npm-integrity.cjs

@@ -16,62 +16,7 @@
 const fs = require('fs');
 const path = require('path');
 
-// ---- Argument parsing -------------------------------------------------------
-
-let ignoreExtraneous = false;
-
-for (const arg of process.argv.slice(2)) {
-  if (arg === '--ignore-extraneous') {
-    ignoreExtraneous = true;
-  } else if (arg === '--help' || arg === '-h') {
-    process.stdout.write(
-      'Usage: node scripts/check-npm-integrity.cjs [--ignore-extraneous]\n'
-    );
-    process.exit(0);
-  } else {
-    process.stderr.write(`ERROR: Unknown argument: ${arg}\n`);
-    process.exit(2);
-  }
-}
-
-// ---- Locate lockfile --------------------------------------------------------
-
-const lockfilePath = path.join(process.cwd(), 'package-lock.json');
-
-if (!fs.existsSync(lockfilePath)) {
-  process.stderr.write(`ERROR: package-lock.json not found in ${process.cwd()}\n`);
-  process.exit(2);
-}
-
-// ---- Parse lockfile ---------------------------------------------------------
-
-let lock;
-try {
-  lock = JSON.parse(fs.readFileSync(lockfilePath, 'utf-8'));
-} catch (e) {
-  process.stderr.write(`ERROR: Failed to parse package-lock.json: ${e.message}\n`);
-  process.exit(2);
-}
-
-const lockVersion = lock.lockfileVersion || 1;
-if (lockVersion < 2) {
-  process.stderr.write(
-    `ERROR: package-lock.json lockfileVersion ${lockVersion} is not supported. ` +
-    'Run `npm install` to upgrade to v3.\n'
-  );
-  process.exit(2);
-}
-
-const packages = lock.packages || {};
-const rootEntry = packages[''] || {};
-
-// Collect declared dependency ranges from root entry.
-const declaredRanges = {};
-for (const field of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']) {
-  for (const [name, range] of Object.entries(rootEntry[field] || {})) {
-    if (!declaredRanges[name]) declaredRanges[name] = range;
-  }
-}
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
 // ---- Minimal semver satisfies -----------------------------------------------
 
@@ -132,78 +77,139 @@ function satisfies(installed, range) {
   return installed === range;
 }
 
-// ---- Walk packages map ------------------------------------------------------
+function main() {
+  // ---- Argument parsing -------------------------------------------------------
+
+  let ignoreExtraneous = false;
+
+  for (const arg of process.argv.slice(2)) {
+    if (arg === '--ignore-extraneous') {
+      ignoreExtraneous = true;
+    } else if (arg === '--help' || arg === '-h') {
+      process.stdout.write(
+        'Usage: node scripts/check-npm-integrity.cjs [--ignore-extraneous]\n'
+      );
+      return 0;
+    } else {
+      process.stderr.write(`ERROR: Unknown argument: ${arg}\n`);
+      throw new ExitError(2);
+    }
+  }
 
-const invalids = [];
-const missings = [];
-const extraneousFound = [];
+  // ---- Locate lockfile --------------------------------------------------------
 
-for (const [key, entry] of Object.entries(packages)) {
-  if (!key.startsWith('node_modules/')) continue;
-  const rest = key.slice('node_modules/'.length);
-  const isScoped = rest[0] === '@';
-  const slashCount = (rest.match(/\//g) || []).length;
-  if (isScoped && slashCount > 1) continue;
-  if (!isScoped && slashCount > 0) continue;
+  const lockfilePath = path.join(process.cwd(), 'package-lock.json');
 
-  const pkgName = rest;
-  const installedVersion = entry.version || '';
+  if (!fs.existsSync(lockfilePath)) {
+    process.stderr.write(`ERROR: package-lock.json not found in ${process.cwd()}\n`);
+    throw new ExitError(2);
+  }
 
-  if (entry.extraneous) {
-    extraneousFound.push({ name: pkgName, version: installedVersion });
-    continue;
+  // ---- Parse lockfile ---------------------------------------------------------
+
+  let lock;
+  try {
+    lock = JSON.parse(fs.readFileSync(lockfilePath, 'utf-8'));
+  } catch (e) {
+    process.stderr.write(`ERROR: Failed to parse package-lock.json: ${e.message}\n`);
+    throw new ExitError(2);
   }
 
-  if (!declaredRanges[pkgName]) continue;
+  const lockVersion = lock.lockfileVersion || 1;
+  if (lockVersion < 2) {
+    process.stderr.write(
+      `ERROR: package-lock.json lockfileVersion ${lockVersion} is not supported. ` +
+      'Run `npm install` to upgrade to v3.\n'
+    );
+    throw new ExitError(2);
+  }
 
-  if (!satisfies(installedVersion, declaredRanges[pkgName])) {
-    invalids.push({ name: pkgName, version: installedVersion, declared: declaredRanges[pkgName] });
+  const packages = lock.packages || {};
+  const rootEntry = packages[''] || {};
+
+  // Collect declared dependency ranges from root entry.
+  const declaredRanges = {};
+  for (const field of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']) {
+    for (const [name, range] of Object.entries(rootEntry[field] || {})) {
+      if (!declaredRanges[name]) declaredRanges[name] = range;
+    }
   }
-}
 
-for (const name of Object.keys(declaredRanges)) {
-  if (!packages[`node_modules/${name}`]) {
-    missings.push({ name, required: declaredRanges[name] });
+  // ---- Walk packages map ------------------------------------------------------
+
+  const invalids = [];
+  const missings = [];
+  const extraneousFound = [];
+
+  for (const [key, entry] of Object.entries(packages)) {
+    if (!key.startsWith('node_modules/')) continue;
+    const rest = key.slice('node_modules/'.length);
+    const isScoped = rest[0] === '@';
+    const slashCount = (rest.match(/\//g) || []).length;
+    if (isScoped && slashCount > 1) continue;
+    if (!isScoped && slashCount > 0) continue;
+
+    const pkgName = rest;
+    const installedVersion = entry.version || '';
+
+    if (entry.extraneous) {
+      extraneousFound.push({ name: pkgName, version: installedVersion });
+      continue;
+    }
+
+    if (!declaredRanges[pkgName]) continue;
+
+    if (!satisfies(installedVersion, declaredRanges[pkgName])) {
+      invalids.push({ name: pkgName, version: installedVersion, declared: declaredRanges[pkgName] });
+    }
   }
-}
 
-// ---- Verdict ----------------------------------------------------------------
+  for (const name of Object.keys(declaredRanges)) {
+    if (!packages[`node_modules/${name}`]) {
+      missings.push({ name, required: declaredRanges[name] });
+    }
+  }
 
-const failInvalid = invalids.length > 0;
-const failMissing = missings.length > 0;
-const failExtra   = !ignoreExtraneous && extraneousFound.length > 0;
+  // ---- Verdict ----------------------------------------------------------------
 
-if (!failInvalid && !failMissing && !failExtra) {
-  process.stderr.write('check-npm-integrity.cjs: clean\n');
-  process.exit(0);
-}
+  const failInvalid = invalids.length > 0;
+  const failMissing = missings.length > 0;
+  const failExtra   = !ignoreExtraneous && extraneousFound.length > 0;
 
-const lines = ['FAIL: dependency integrity drift detected', ''];
+  if (!failInvalid && !failMissing && !failExtra) {
+    process.stderr.write('check-npm-integrity.cjs: clean\n');
+    return 0;
+  }
 
-if (failInvalid) {
-  lines.push('  INVALID (installed version does not satisfy declared range):');
-  for (const { name, declared, version } of invalids) {
-    lines.push(`    ${name}: declared=${declared}  installed=${version}`);
+  const lines = ['FAIL: dependency integrity drift detected', ''];
+
+  if (failInvalid) {
+    lines.push('  INVALID (installed version does not satisfy declared range):');
+    for (const { name, declared, version } of invalids) {
+      lines.push(`    ${name}: declared=${declared}  installed=${version}`);
+    }
+    lines.push('');
   }
-  lines.push('');
-}
 
-if (failMissing) {
-  lines.push('  MISSING (declared but absent from lockfile packages map):');
-  for (const { name, required } of missings) {
-    lines.push(`    ${name}@${required}`);
+  if (failMissing) {
+    lines.push('  MISSING (declared but absent from lockfile packages map):');
+    for (const { name, required } of missings) {
+      lines.push(`    ${name}@${required}`);
+    }
+    lines.push('');
   }
-  lines.push('');
-}
 
-if (failExtra) {
-  lines.push('  EXTRANEOUS (in lockfile but not declared as a dependency):');
-  for (const { name, version } of extraneousFound) {
-    lines.push(`    ${name}@${version}`);
+  if (failExtra) {
+    lines.push('  EXTRANEOUS (in lockfile but not declared as a dependency):');
+    for (const { name, version } of extraneousFound) {
+      lines.push(`    ${name}@${version}`);
+    }
+    lines.push('');
   }
-  lines.push('');
+
+  lines.push('Remediation: rm -rf node_modules && npm ci');
+  process.stderr.write(lines.join('\n') + '\n');
+  throw new ExitError(1);
 }
 
-lines.push('Remediation: rm -rf node_modules && npm ci');
-process.stderr.write(lines.join('\n') + '\n');
-process.exit(1);
+runMain(main);

package/scripts/ci-guard-runner.cjs

@@ -6,11 +6,17 @@
 // Exit 0 = github-hosted runner confirmed.
 // Exit 1 = not a github-hosted runner (emits GitHub Actions error annotation).
 
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
 const env = process.env.RUNNER_ENVIRONMENT || '';
 
-if (env !== 'github-hosted') {
-  process.stderr.write(
-    `::error::Expected github-hosted runner. RUNNER_ENVIRONMENT=${env || 'unset'}\n`
-  );
-  process.exit(1);
+function main() {
+  if (env !== 'github-hosted') {
+    throw new ExitError(
+      1,
+      `::error::Expected github-hosted runner. RUNNER_ENVIRONMENT=${env || 'unset'}`
+    );
+  }
 }
+
+runMain(main);

package/scripts/ci-prepare-test-scope.cjs

@@ -14,33 +14,38 @@
 const fs = require('fs');
 const path = require('path');
 
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
 const scope = process.env.TEST_SCOPE || '';
 const targeted = process.env.TARGETED_TESTS || '';
 const windows = process.env.WINDOWS_TESTS || '';
 
 const FALLBACK = 'tests/command-contract.test.cjs tests/commands.test.cjs tests/core.test.cjs tests/package-manifest.test.cjs';
 
-let selected;
-if (scope === 'windows') {
-  selected = windows;
-} else if (scope === 'targeted') {
-  selected = targeted;
-} else {
-  process.stderr.write(`::error::Unknown test scope: ${scope}\n`);
-  process.exit(1);
-}
-
-// Trim and fall back to default set if empty.
-if (!selected.trim()) {
-  selected = FALLBACK;
+function main() {
+  let selected;
+  if (scope === 'windows') {
+    selected = windows;
+  } else if (scope === 'targeted') {
+    selected = targeted;
+  } else {
+    throw new ExitError(1, `::error::Unknown test scope: ${scope}`);
+  }
+
+  // Trim and fall back to default set if empty.
+  if (!selected.trim()) {
+    selected = FALLBACK;
+  }
+
+  // Split on whitespace, filter blanks, join with newlines.
+  const lines = selected.split(/\s+/).filter(Boolean);
+  const content = lines.join('\n') + '\n';
+
+  const outPath = path.join(process.cwd(), '.ci-selected-tests.txt');
+  fs.writeFileSync(outPath, content, 'utf-8');
+
+  process.stdout.write('Scoped tests:\n');
+  process.stdout.write(content);
 }
 
-// Split on whitespace, filter blanks, join with newlines.
-const lines = selected.split(/\s+/).filter(Boolean);
-const content = lines.join('\n') + '\n';
-
-const outPath = path.join(process.cwd(), '.ci-selected-tests.txt');
-fs.writeFileSync(outPath, content, 'utf-8');
-
-process.stdout.write('Scoped tests:\n');
-process.stdout.write(content);
+runMain(main);

package/scripts/ci-rebase-check.cjs

@@ -11,8 +11,9 @@
 // Exit 0 = merged cleanly (or merge was a no-op).
 // Exit 1 = merge conflict or fetch failure.
 
-const { execFileSync, execSync } = require('child_process');
-const path = require('path');
+const { execFileSync } = require('child_process');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
 function run(cmd, args, opts) {
   try {
@@ -27,8 +28,7 @@ function runOrThrow(cmd, args, label) {
   try {
     execFileSync(cmd, args, { stdio: 'inherit' });
   } catch (e) {
-    process.stderr.write(`::error::${label} failed\n`);
-    process.exit(1);
+    throw new ExitError(1, `::error::${label} failed`);
   }
 }
 
@@ -36,50 +36,51 @@ const token = process.env.GITHUB_TOKEN || '';
 const baseBranch = process.env.GITHUB_BASE_REF || 'main';
 const repo = process.env.GITHUB_REPOSITORY || '';
 
-// Configure git identity (needed for merge commit).
-runOrThrow('git', ['config', 'user.email', 'ci@gsd-redux'], 'git config user.email');
-runOrThrow('git', ['config', 'user.name', 'CI Rebase Check'], 'git config user.name');
-
-// Set authenticated remote URL.
-if (token && repo) {
-  runOrThrow(
-    'git',
-    ['remote', 'set-url', 'origin', `https://x-access-token:${token}@github.com/${repo}.git`],
-    'git remote set-url'
-  );
-}
+function main() {
+  // Configure git identity (needed for merge commit).
+  runOrThrow('git', ['config', 'user.email', 'ci@gsd-redux'], 'git config user.email');
+  runOrThrow('git', ['config', 'user.name', 'CI Rebase Check'], 'git config user.name');
 
-// Fetch base branch with retry.
-let fetched = false;
-for (let attempt = 1; attempt <= 3; attempt++) {
-  const result = run('git', ['fetch', 'origin', baseBranch]);
-  if (result) {
-    fetched = true;
-    break;
+  // Set authenticated remote URL.
+  if (token && repo) {
+    runOrThrow(
+      'git',
+      ['remote', 'set-url', 'origin', `https://x-access-token:${token}@github.com/${repo}.git`],
+      'git remote set-url'
+    );
   }
-  if (attempt === 3) {
-    process.stderr.write(`::error::git fetch origin ${baseBranch} failed after 3 attempts.\n`);
-    process.exit(1);
+
+  // Fetch base branch with retry.
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    const result = run('git', ['fetch', 'origin', baseBranch]);
+    if (result) {
+      break;
+    }
+    if (attempt === 3) {
+      throw new ExitError(1, `::error::git fetch origin ${baseBranch} failed after 3 attempts.`);
+    }
+    // Wait before retry: attempt * 4 seconds.
+    const waitMs = attempt * 4000;
+    const deadline = Date.now() + waitMs;
+    while (Date.now() < deadline) { /* busy wait, acceptable in CI */ }
   }
-  // Wait before retry: attempt * 4 seconds.
-  const waitMs = attempt * 4000;
-  const deadline = Date.now() + waitMs;
-  while (Date.now() < deadline) { /* busy wait, acceptable in CI */ }
-}
 
-// Attempt merge.
-try {
-  execFileSync('git', ['merge', '--no-edit', '--no-ff', `origin/${baseBranch}`], { stdio: 'inherit' });
-} catch (e) {
-  process.stderr.write(
-    `::error::This PR cannot cleanly merge origin/${baseBranch}. Rebase your branch onto current ${baseBranch} and push again.\n`
-  );
-  process.stderr.write('::error::Conflicting files:\n');
+  // Attempt merge.
   try {
-    execFileSync('git', ['diff', '--name-only', '--diff-filter=U'], { stdio: 'inherit' });
-  } catch (_) { /* ignore */ }
-  try {
-    execFileSync('git', ['merge', '--abort'], { stdio: 'inherit' });
-  } catch (_) { /* ignore */ }
-  process.exit(1);
+    execFileSync('git', ['merge', '--no-edit', '--no-ff', `origin/${baseBranch}`], { stdio: 'inherit' });
+  } catch (e) {
+    process.stderr.write(
+      `::error::This PR cannot cleanly merge origin/${baseBranch}. Rebase your branch onto current ${baseBranch} and push again.\n`
+    );
+    process.stderr.write('::error::Conflicting files:\n');
+    try {
+      execFileSync('git', ['diff', '--name-only', '--diff-filter=U'], { stdio: 'inherit' });
+    } catch (_) { /* ignore */ }
+    try {
+      execFileSync('git', ['merge', '--abort'], { stdio: 'inherit' });
+    } catch (_) { /* ignore */ }
+    throw new ExitError(1);
+  }
 }
+
+runMain(main);

package/scripts/ci-test-scope.cjs

@@ -3,7 +3,8 @@
 
 const { execFileSync } = require('child_process');
 const { existsSync, readdirSync, appendFileSync } = require('fs');
-const { join } = require('path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
 const RULES = [
   {
@@ -198,7 +199,7 @@ function parseArgs(argv) {
       if (!out.files) throw new Error('--files requires a value');
     } else if (arg === '--help' || arg === '-h') {
       console.log(usage());
-      process.exit(0);
+      throw new ExitError(0);
     } else {
       throw new Error(`unknown argument: ${arg}`);
     }
@@ -318,10 +319,11 @@ function main() {
     writeOutputs(result);
     console.log(JSON.stringify(result, null, 2));
   } catch (error) {
+    if (error instanceof ExitError) throw error;
     console.error(`ci-test-scope: ${error.message}`);
     console.error(usage());
-    process.exit(2);
+    throw new ExitError(2);
   }
 }
 
-main();
+runMain(main);

package/scripts/diff-touches-shipped-paths.cjs

@@ -43,6 +43,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
 const EXIT_SHIPPED = 0;
 const EXIT_NOT_SHIPPED = 1;
@@ -88,60 +89,67 @@ function isPushBlocking(diffPath) {
   return diffPath.replace(/\\/g, '/').startsWith('.github/workflows/');
 }
 
-function fail(message, err) {
-  process.stderr.write(`diff-touches-shipped-paths: ${message}\n`);
-  if (err && err.stack) process.stderr.write(`${err.stack}\n`);
-  process.exit(EXIT_ERROR);
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
 }
 
-function main() {
-  // Surface ANY uncaught failure as exit 2 (classifier error) rather
-  // than letting Node's default-1 shadow the legitimate
-  // "no shipped paths" result. Bug #2983.
-  process.on('uncaughtException', (err) => fail('uncaught exception', err));
-  process.on('unhandledRejection', (err) => fail('unhandled rejection', err));
-
-  let shipPrefixes;
+async function main() {
   try {
-    const pkgPath = path.resolve(process.cwd(), 'package.json');
-    shipPrefixes = loadShipPrefixes(pkgPath);
-  } catch (err) {
-    return fail(`failed to read package.json from ${process.cwd()}`, err);
-  }
+    let shipPrefixes;
+    try {
+      const pkgPath = path.resolve(process.cwd(), 'package.json');
+      shipPrefixes = loadShipPrefixes(pkgPath);
+    } catch (err) {
+      process.stderr.write(`diff-touches-shipped-paths: failed to read package.json from ${process.cwd()}\n`);
+      if (err && err.stack) process.stderr.write(`${err.stack}\n`);
+      throw new ExitError(EXIT_ERROR);
+    }
 
-  let buf = '';
-  process.stdin.setEncoding('utf8');
-  process.stdin.on('error', (err) => fail('stdin read error', err));
-  process.stdin.on('data', (chunk) => {
-    buf += chunk;
-  });
-  process.stdin.on('end', () => {
+    let buf;
     try {
-      const paths = buf.split('\n').map((s) => s.trim()).filter(Boolean);
-      // #2980 still wins over #3621: any commit touching .github/workflows/*
-      // is unpickable regardless of other content because the push step
-      // fails on workflow scope rejection. Check this first.
-      if (paths.some(isPushBlocking)) {
-        process.exit(EXIT_NOT_SHIPPED);
-      }
-      if (paths.some((p) => isShipped(p, shipPrefixes))) {
-        process.exit(EXIT_SHIPPED);
-      }
-      // #3621: a commit whose only relevant paths are CI-gating tests is
-      // still pickable — it can change whether the hotfix CI passes even
-      // though it doesn't change what the npm tarball ships.
-      if (paths.some(isCiGating)) {
-        process.exit(EXIT_SHIPPED);
-      }
-      process.exit(EXIT_NOT_SHIPPED);
+      buf = await readStdin();
     } catch (err) {
-      fail('classification failed', err);
+      process.stderr.write(`diff-touches-shipped-paths: stdin read error\n`);
+      if (err && err.stack) process.stderr.write(`${err.stack}\n`);
+      throw new ExitError(EXIT_ERROR);
     }
-  });
+
+    const paths = buf.split('\n').map((s) => s.trim()).filter(Boolean);
+    // #2980 still wins over #3621: any commit touching .github/workflows/*
+    // is unpickable regardless of other content because the push step
+    // fails on workflow scope rejection. Check this first.
+    if (paths.some(isPushBlocking)) {
+      return EXIT_NOT_SHIPPED;
+    }
+    if (paths.some((p) => isShipped(p, shipPrefixes))) {
+      return EXIT_SHIPPED;
+    }
+    // #3621: a commit whose only relevant paths are CI-gating tests is
+    // still pickable — it can change whether the hotfix CI passes even
+    // though it doesn't change what the npm tarball ships.
+    if (paths.some(isCiGating)) {
+      return EXIT_SHIPPED;
+    }
+    return EXIT_NOT_SHIPPED;
+  } catch (e) {
+    // Re-throw ExitError unchanged; map any unexpected error to EXIT_ERROR=2
+    // (Node's default uncaught-exception code is 1, which is indistinguishable
+    // from the legitimate EXIT_NOT_SHIPPED result — bug #2983).
+    if (e instanceof ExitError) throw e;
+    process.stderr.write(`diff-touches-shipped-paths: classification failed\n`);
+    if (e && e.stack) process.stderr.write(`${e.stack}\n`);
+    throw new ExitError(EXIT_ERROR);
+  }
 }
 
 if (require.main === module) {
-  main();
+  runMain(main);
 }
 
 module.exports = { loadShipPrefixes, isShipped, isCiGating, isPushBlocking, EXIT_SHIPPED, EXIT_NOT_SHIPPED, EXIT_ERROR };