@opengsd/gsd-core 1.3.1 → 1.4.0-rc.2

package/scripts/ci-test-scope.cjs

@@ -3,18 +3,87 @@
 
 const { execFileSync } = require('child_process');
 const { existsSync, readdirSync, appendFileSync } = require('fs');
-const { join } = require('path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+// Workflow files that are purely administrative / policy bots. Changes to these
+// files do NOT require the cross-platform test matrix — only a lightweight
+// ubuntu lane running workflow-lint tests is needed.
+// FAIL-SAFE: any .github/workflows/*.yml NOT listed here is treated as a
+// pipeline workflow and gets the full matrix. New workflow files default to full.
+const INERT_WORKFLOWS = new Set([
+  'stale.yml',
+  'branch-cleanup.yml',
+  'branch-naming.yml',
+  'auto-label-issues.yml',
+  'auto-branch.yml',
+  'auto-backmerge.yml',
+  'close-draft-prs.yml',
+  'dismiss-unauthorized-pr-approvals.yml',
+  'pr-gate.yml',
+  'pr-target-validator.yml',
+  'pr-template-format.yml',
+  'require-issue-link.yml',
+  'changeset-required.yml',
+  'docs-required.yml',
+  'discord-changelog.yml',
+]);
+
+// Workflows that gate merges, ship the product, or run security/cross-platform
+// suites — these must ALWAYS get the full pipeline treatment and can never be
+// added to INERT_WORKFLOWS. A module-load assertion enforces this so a mistaken
+// or malicious addition fails CI loudly in the `changes` job on every PR.
+const PROTECTED_WORKFLOWS = new Set([
+  'test.yml',
+  'install-smoke.yml',
+  'mutation.yml',
+  'security-scan.yml',
+  'release.yml',
+]);
+for (const wf of PROTECTED_WORKFLOWS) {
+  if (INERT_WORKFLOWS.has(wf)) {
+    throw new Error(`ci-test-scope: protected workflow "${wf}" must not be in INERT_WORKFLOWS (it requires the full test matrix).`);
+  }
+}
+
+/**
+ * Returns true if the path is an inert (non-pipeline) workflow file.
+ * Only `.github/workflows/<name>` where <name> is in INERT_WORKFLOWS qualifies.
+ */
+function isInertCi(filePath) {
+  if (!filePath.startsWith('.github/workflows/')) return false;
+  const name = filePath.slice('.github/workflows/'.length);
+  // Must be a direct child (no further slashes) and in the allowlist.
+  return !name.includes('/') && INERT_WORKFLOWS.has(name);
+}
+
+// Tests shared by both the 'workflow automation' and 'inert CI' rules.
+const WORKFLOW_LINT_TESTS = [
+  'tests/workflow-shell-pinning.test.cjs',
+  'tests/pr-template-policy.test.cjs',
+  'tests/lint-pr-check-project-dir.test.cjs',
+];
 
 const RULES = [
   {
     name: 'workflow automation',
-    match: path => path.startsWith('.github/workflows/') || path.startsWith('.github/rulesets/'),
+    // Only NON-inert .github/workflows/* and all .github/rulesets/* trigger full matrix.
+    // FAIL-SAFE: any .github/workflows/*.yml not in INERT_WORKFLOWS is treated as pipeline.
+    match: filePath => (filePath.startsWith('.github/workflows/') && !isInertCi(filePath)) ||
+      filePath.startsWith('.github/rulesets/'),
     fullMatrix: true,
     tests: [
-      'tests/workflow-shell-pinning.test.cjs',
+      ...WORKFLOW_LINT_TESTS,
       'tests/release-tarball-smoke-workflow.test.cjs',
-      'tests/lint-pr-check-project-dir.test.cjs',
-      'tests/pr-template-policy.test.cjs',
+    ],
+  },
+  {
+    name: 'inert CI',
+    match: filePath => isInertCi(filePath),
+    fullMatrix: false,
+    tests: [
+      ...WORKFLOW_LINT_TESTS,
+      'tests/policy-lint-shallow-checkout.test.cjs',
     ],
   },
   {
@@ -143,14 +212,6 @@ const RULES = [
       'tests/docs-parity-live-registry.test.cjs',
     ],
   },
-  {
-    name: 'docs content',
-    match: path => path.startsWith('docs/'),
-    fullMatrix: false,
-    tests: [
-      'tests/docs-parity-live-registry.test.cjs',
-    ],
-  },
   {
     name: 'configuration',
     match: path => ['config', 'configuration', 'model-catalog', 'model-profile'].some(k => path.includes(k)),
@@ -198,7 +259,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}`);
     }
@@ -228,7 +289,12 @@ function changedFiles(args) {
   if (!args.base || !args.head) {
     throw new Error('--base/--head or --files is required');
   }
-  const stdout = execFileSync('git', ['diff', '--name-only', args.base, args.head], {
+  // Three-dot diff (merge-base...head) matches GitHub's PR "Files changed" semantics.
+  // A two-dot `git diff base head` would surface every file `next` gained after this
+  // branch's merge-base, mis-flagging product_changed/full_matrix on docs-only PRs cut
+  // from a slightly stale base (#837). The `changes` job checks out with fetch-depth: 0,
+  // so the merge-base is always available.
+  const stdout = execFileSync('git', ['diff', '--name-only', `${args.base}...${args.head}`], {
     encoding: 'utf8',
   });
   return splitFiles(stdout);
@@ -250,16 +316,30 @@ function classify(files) {
   const targeted = new Set();
   const windows = new Set();
   const reasons = [];
-  let codeChanged = false;
+  let productOrPipelineChanged = false; // product/pipeline code (excludes docs)
+  let inertCiChanged = false;           // inert workflow files
   let fullMatrix = false;
 
   for (const file of files) {
-    if (['bin/', 'gsd-core/', 'agents/', 'commands/', 'docs/', 'hooks/', 'tests/', 'scripts/'].some(p => file.startsWith(p)) ||
+    // Determine if this file is product/pipeline code.
+    // docs/ and root-level .md files are intentionally excluded.
+    if (
+      ['bin/', 'src/', 'gsd-core/', 'agents/', 'commands/', 'hooks/', 'tests/', 'scripts/'].some(p => file.startsWith(p)) ||
       file === 'package.json' || file === 'package-lock.json' ||
       (file.startsWith('tsconfig') && file.endsWith('.json')) ||
-      file.startsWith('.github/workflows/') ||
-      file.startsWith('.github/rulesets/')) {
-      codeChanged = true;
+      file.startsWith('.github/rulesets/')
+    ) {
+      productOrPipelineChanged = true;
+    }
+
+    // Non-inert .github/workflows/* are pipeline code → full matrix.
+    if (file.startsWith('.github/workflows/') && !isInertCi(file)) {
+      productOrPipelineChanged = true;
+    }
+
+    // Inert workflow files set a lightweight signal.
+    if (isInertCi(file)) {
+      inertCiChanged = true;
     }
 
     if (file.startsWith('tests/') && file.endsWith('.test.cjs')) {
@@ -279,6 +359,10 @@ function classify(files) {
     }
   }
 
+  // code_changed: true when product/pipeline OR inert CI changed.
+  // Docs-only PRs (neither flag set) get code_changed=false → full matrix skip.
+  const codeChanged = productOrPipelineChanged || inertCiChanged;
+
   const targetedTests = existingTests([...targeted].sort());
 
   // When code changed but no rule matched any changed file, fall back to the
@@ -289,8 +373,25 @@ function classify(files) {
 
   const windowsTests = existingTests([...new Set([...windows, ...targetedTests.filter(isWindowsHint)])].sort());
 
+  // Inert-CI-only: full_matrix must be false (override any RULES that fired).
+  if (inertCiChanged && !productOrPipelineChanged) {
+    fullMatrix = false;
+  }
+
+  // Normalize: when code_changed is false, the output must be self-consistent.
+  // A docs file can coincidentally match a coarse content RULE (e.g. docs/installer-migrations.md
+  // matches the installer rule via path.includes('install')), leaving full_matrix=true and
+  // non-empty targeted_tests/windows_tests. The workflow skips correctly (gated on code_changed)
+  // but the output object would be self-contradictory. Force a clean "nothing to run" result.
+  if (!codeChanged) {
+    fullMatrix = false;
+    targetedTests.length = 0;
+    windowsTests.length = 0;
+  }
+
   return {
     code_changed: codeChanged,
+    product_changed: productOrPipelineChanged,
     full_matrix: fullMatrix,
     targeted_tests: targetedTests,
     windows_tests: windowsTests,
@@ -302,6 +403,7 @@ function writeOutputs(result) {
   if (!process.env.GITHUB_OUTPUT) return;
   const lines = [
     `code_changed=${result.code_changed}`,
+    `product_changed=${result.product_changed}`,
     `full_matrix=${result.full_matrix}`,
     `targeted_tests=${result.targeted_tests.join(' ')}`,
     `windows_tests=${result.windows_tests.join(' ')}`,
@@ -312,16 +414,18 @@ function writeOutputs(result) {
 function main() {
   try {
     const args = parseArgs(process.argv.slice(2));
+
     const files = changedFiles(args);
     const result = classify(files);
     result.changed_files = files;
     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 };

package/scripts/gen-inventory-manifest.cjs

@@ -16,6 +16,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
 const ROOT = path.resolve(__dirname, '..');
 const MANIFEST_PATH = path.join(ROOT, 'docs', 'INVENTORY-MANIFEST.json');
 
@@ -70,40 +72,44 @@ function buildManifest() {
   return manifest;
 }
 
-const [, , flag] = process.argv;
+function main() {
+  const [, , flag] = process.argv;
 
-if (flag === '--check') {
-  const committed = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
-  const live = buildManifest();
-  // Strip the generated date for comparison
-  delete committed.generated;
-  delete live.generated;
-  const committedStr = JSON.stringify(committed, null, 2);
-  const liveStr = JSON.stringify(live, null, 2);
-  if (committedStr !== liveStr) {
-    process.stderr.write(
-      'docs/INVENTORY-MANIFEST.json is stale. Run:\n' +
-      '  node scripts/gen-inventory-manifest.cjs --write\n' +
-      'then add a matching row in docs/INVENTORY.md for each new entry.\n\n',
-    );
-    // Show diff-friendly output
-    for (const family of Object.keys(live.families)) {
-      const liveSet = new Set(live.families[family]);
-      const committedSet = new Set((committed.families || {})[family] || []);
-      for (const name of liveSet) {
-        if (!committedSet.has(name)) process.stderr.write('  + ' + family + '/' + name + '\n');
-      }
-      for (const name of committedSet) {
-        if (!liveSet.has(name)) process.stderr.write('  - ' + family + '/' + name + '\n');
+  if (flag === '--check') {
+    const committed = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
+    const live = buildManifest();
+    // Strip the generated date for comparison
+    delete committed.generated;
+    delete live.generated;
+    const committedStr = JSON.stringify(committed, null, 2);
+    const liveStr = JSON.stringify(live, null, 2);
+    if (committedStr !== liveStr) {
+      process.stderr.write(
+        'docs/INVENTORY-MANIFEST.json is stale. Run:\n' +
+        '  node scripts/gen-inventory-manifest.cjs --write\n' +
+        'then add a matching row in docs/INVENTORY.md for each new entry.\n\n',
+      );
+      // Show diff-friendly output
+      for (const family of Object.keys(live.families)) {
+        const liveSet = new Set(live.families[family]);
+        const committedSet = new Set((committed.families || {})[family] || []);
+        for (const name of liveSet) {
+          if (!committedSet.has(name)) process.stderr.write('  + ' + family + '/' + name + '\n');
+        }
+        for (const name of committedSet) {
+          if (!liveSet.has(name)) process.stderr.write('  - ' + family + '/' + name + '\n');
+        }
       }
+      throw new ExitError(1);
     }
-    process.exit(1);
+    process.stdout.write('docs/INVENTORY-MANIFEST.json is up to date.\n');
+  } else if (flag === '--write') {
+    const manifest = buildManifest();
+    fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n');
+    process.stdout.write('Wrote ' + MANIFEST_PATH + '\n');
+  } else {
+    process.stdout.write(JSON.stringify(buildManifest(), null, 2) + '\n');
   }
-  process.stdout.write('docs/INVENTORY-MANIFEST.json is up to date.\n');
-} else if (flag === '--write') {
-  const manifest = buildManifest();
-  fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n');
-  process.stdout.write('Wrote ' + MANIFEST_PATH + '\n');
-} else {
-  process.stdout.write(JSON.stringify(buildManifest(), null, 2) + '\n');
 }
+
+runMain(main);