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

package/scripts/changeset/cli.cjs

@@ -17,7 +17,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const { parseFragment, FRAGMENT_ERROR } = require('./parse.cjs');
+const { ExitError, runMain } = require('../lib/cli-exit.cjs');
+const { parseFragment } = require('./parse.cjs');
 const { renderChangelog } = require('./render.cjs');
 const { serializeChangelog, parseChangelog } = require('./serialize.cjs');
 const { renderGithubReleaseNotes } = require('./github-release-notes.cjs');
@@ -40,6 +41,7 @@ function parseArgs(argv) {
     repoSlug: defaultRepoSlug,
     installCommand: `npx ${packageName}@latest`,
     json: false,
+    allowEmpty: false,
   };
   if (argv.length === 0) return { ok: true, opts };
   opts.cmd = argv[0];
@@ -59,6 +61,7 @@ function parseArgs(argv) {
   for (let i = 1; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--json') { opts.json = true; continue; }
+    if (a === '--allow-empty') { opts.allowEmpty = true; continue; }
     if (
       a === '--repo' ||
       a === '--version' ||
@@ -118,6 +121,18 @@ function splitChangelog(text) {
   return { lead, prior };
 }
 
+// FIX 2: tiny local helper so both render paths share identical assembly logic.
+function assembleChangelog(lead, releaseBlock) {
+  return [
+    lead || '# Changelog',
+    '',
+    '## [Unreleased]',
+    '',
+    releaseBlock.replace(/\s+$/, ''),
+    '',
+  ].join('\n');
+}
+
 function cmdRender(opts) {
   const repo = path.resolve(opts.repo);
   const changesetDir = path.join(repo, '.changeset');
@@ -133,14 +148,83 @@ function cmdRender(opts) {
     else failures.push({ file: path.relative(repo, file), reason: r.reason, detail: r.detail || null });
   }
 
+  // 1. parse-failure → exitCode 1 (unchanged).
   if (failures.length > 0) {
     return { exitCode: 1, report: { consumed: 0, failures } };
   }
+
+  // 2. Read priorText once; reuse in all subsequent branches.
+  const priorText = fs.existsSync(changelogPath) ? fs.readFileSync(changelogPath, 'utf8') : '';
+
+  // 3. FIX 1: idempotency guard — if the version is already promoted (a dated
+  //    release heading for this version already exists in CHANGELOG), split on
+  //    whether fragments are still present:
+  //    • alreadyPromoted + zero fragments → legitimate CI-retry no-op (the prior
+  //      render commit already deleted fragments and wrote the heading).
+  //    • alreadyPromoted + fragments present → inconsistent state: the heading
+  //      was written out-of-band but fragments were never consumed.  Fail loudly
+  //      so the operator resolves it manually rather than silently leaving stale
+  //      fragments to be re-consumed in a later release.
+  const version = stripV(opts.version);
+  const { releases: existingReleases } = parseChangelog(priorText);
+  const alreadyPromoted = existingReleases.some(
+    (rel) => rel.version === version && rel.date,
+  );
+  if (alreadyPromoted) {
+    if (fragments.length === 0) {
+      return { exitCode: 0, report: { consumed: 0, failures: [], alreadyPromoted: true } };
+    }
+    const errMsg =
+      `CHANGELOG.md already has a dated heading for ${version} but ` +
+      `${fragments.length} unconsumed fragment(s) remain in .changeset/ — ` +
+      `resolve manually (the version was likely promoted out-of-band).`;
+    return {
+      exitCode: 1,
+      report: { consumed: 0, failures: [], alreadyPromoted: true, error: errMsg },
+    };
+  }
+
+  // 4. Zero-fragment + !allowEmpty early-exit: write nothing.
   if (fragments.length === 0) {
-    return { exitCode: 0, report: { consumed: 0, failures: [] } };
+    if (!opts.allowEmpty) {
+      return { exitCode: 0, report: { consumed: 0, failures: [] } };
+    }
+    // --allow-empty: emit a dated heading with a placeholder even though there
+    // are no fragments. This lets the render→verify CI chain succeed when a
+    // release contains no user-visible changes.
+    const { lead, prior } = splitChangelog(priorText);
+    // Build a header-only release block and inject the placeholder line.
+    const ir = renderChangelog({
+      fragments: [],
+      version: opts.version,
+      date: opts.date,
+      priorChangelog: prior || null,
+    });
+    const headerOnlyBlock = serializeChangelog(ir);
+    // Insert placeholder after the release header line.
+    // serializeChangelog with no sections yields just "## [v] - d\n" (single
+    // trailing newline, no blank line).  We replace that trailing newline with
+    // a blank line + placeholder + blank line so parseChangelog still sees the
+    // dated heading first and the file is human-readable.
+    const releaseBlock = headerOnlyBlock.replace(
+      /^(##\s+\[[^\]]+\][^\n]*)\n+/,
+      '$1\n\n_No notable changes._\n\n',
+    );
+    // FIX 2: use shared assembleChangelog helper.
+    const out = assembleChangelog(lead, releaseBlock);
+    fs.writeFileSync(changelogPath, out);
+    return {
+      exitCode: 0,
+      report: {
+        consumed: 0,
+        failures: [],
+        written: true,
+        release: { version: opts.version, date: opts.date },
+      },
+    };
   }
 
-  const priorText = fs.existsSync(changelogPath) ? fs.readFileSync(changelogPath, 'utf8') : '';
+  // 5. Normal render path: fragments present — reuse priorText already read above.
   const { lead, prior } = splitChangelog(priorText);
 
   const ir = renderChangelog({
@@ -150,14 +234,8 @@ function cmdRender(opts) {
     priorChangelog: prior || null,
   });
   const releaseBlock = serializeChangelog(ir);
-  const out = [
-    lead || '# Changelog',
-    '',
-    '## [Unreleased]',
-    '',
-    releaseBlock.replace(/\s+$/, ''),
-    '',
-  ].join('\n');
+  // FIX 2: use shared assembleChangelog helper.
+  const out = assembleChangelog(lead, releaseBlock);
 
   fs.writeFileSync(changelogPath, out);
 
@@ -188,6 +266,14 @@ function cmdRender(opts) {
   };
 }
 
+function stripV(v) { return typeof v === 'string' ? v.replace(/^v/, '') : v; }
+
+function resolveChangelogPath(opts) {
+  return opts.changelog
+    ? path.resolve(opts.changelog)
+    : path.join(path.resolve(opts.repo), 'CHANGELOG.md');
+}
+
 /**
  * extract subcommand: extracts all changelog release blocks strictly after
  * `--from` (exclusive) up to and including `--to` (inclusive).  Both
@@ -203,7 +289,6 @@ function cmdRender(opts) {
  * vague/manual extraction that can silently skip intermediate versions.
  */
 function cmdExtract(opts) {
-  const stripV = (v) => (typeof v === 'string' ? v.replace(/^v/, '') : v);
   const from = stripV(opts.fromRef);
   const to = stripV(opts.toRef);
 
@@ -225,9 +310,7 @@ function cmdExtract(opts) {
     };
   }
 
-  const changelogPath = opts.changelog
-    ? path.resolve(opts.changelog)
-    : path.join(path.resolve(opts.repo), 'CHANGELOG.md');
+  const changelogPath = resolveChangelogPath(opts);
 
   if (!fs.existsSync(changelogPath)) {
     return {
@@ -282,6 +365,61 @@ function cmdExtract(opts) {
   };
 }
 
+function cmdVerify(opts) {
+  const version = stripV(opts.version);
+
+  if (!isStableTripletSemver(version)) {
+    return {
+      exitCode: 1,
+      report: { error: `invalid semver for --version: "${version}" (expected N.N.N)`, ok: false },
+      textOutput: null,
+    };
+  }
+
+  const changelogPath = resolveChangelogPath(opts);
+
+  if (!fs.existsSync(changelogPath)) {
+    return {
+      exitCode: 1,
+      report: { error: `CHANGELOG not found: ${changelogPath}`, ok: false },
+      textOutput: null,
+    };
+  }
+
+  const text = fs.readFileSync(changelogPath, 'utf8');
+  const { releases } = parseChangelog(text);
+
+  const match = releases.find((r) => r.version === version);
+
+  if (!match) {
+    return {
+      exitCode: 1,
+      report: {
+        error: `CHANGELOG.md has no \`## [${version}]\` release heading — promote [Unreleased] into a dated section before releasing (see #690)`,
+        ok: false,
+      },
+      textOutput: null,
+    };
+  }
+
+  if (!match.date) {
+    return {
+      exitCode: 1,
+      report: {
+        error: `CHANGELOG.md heading \`## [${version}]\` has no date — expected \`## [${version}] - YYYY-MM-DD\``,
+        ok: false,
+      },
+      textOutput: null,
+    };
+  }
+
+  return {
+    exitCode: 0,
+    report: { ok: true, version, date: match.date },
+    textOutput: `CHANGELOG.md has a dated heading for ${version} (${match.date})`,
+  };
+}
+
 function cmdGithubReleaseNotes(opts) {
   const repo = path.resolve(opts.repo);
   const report = renderGithubReleaseNotes({
@@ -322,12 +460,13 @@ function cmdGithubReleaseNotes(opts) {
 function usage() {
   return [
     'usage:',
-    '  changeset/cli.cjs render --repo <dir> --version V --date D [--json]',
+    '  changeset/cli.cjs render --repo <dir> --version V --date D [--allow-empty] [--json]',
     '  changeset/cli.cjs github-release-notes --repo <dir> --from REF --to REF [--output FILE] [--repo-slug OWNER/REPO] [--install-command CMD] [--json]',
     '  changeset/cli.cjs extract --from VERSION --to VERSION [--changelog FILE] [--repo <dir>] [--json]',
     '    Extracts changelog entries strictly after --from (exclusive) and up to',
     '    and including --to (inclusive).  Accepts v-prefixed versions.',
     '    Exit 2 when no releases fall in range.',
+    '  changeset/cli.cjs verify --version <X.Y.Z> [--changelog <path>]   Exit non-zero if CHANGELOG.md has no dated `## [X.Y.Z]` heading (release gate, #690)',
     '',
   ].join('\n');
 }
@@ -337,25 +476,26 @@ function main() {
   if (!parsed.ok) {
     process.stderr.write(`${parsed.error}\n`);
     process.stderr.write(usage());
-    process.exit(2);
+    throw new ExitError(2);
   }
   const { opts } = parsed;
-  if (opts.cmd !== 'render' && opts.cmd !== 'github-release-notes' && opts.cmd !== 'extract') {
+  if (opts.cmd !== 'render' && opts.cmd !== 'github-release-notes' && opts.cmd !== 'extract' && opts.cmd !== 'verify') {
     process.stderr.write(usage());
-    process.exit(1);
+    throw new ExitError(1);
   }
   if (opts.cmd === 'render' && (!opts.version || !opts.date)) {
-    process.stderr.write('--version and --date are required for render\n');
-    process.exit(2);
+    throw new ExitError(2, '--version and --date are required for render');
   }
   if (opts.cmd === 'github-release-notes' && (!opts.fromRef || !opts.toRef)) {
-    process.stderr.write('--from and --to are required for github-release-notes\n');
-    process.exit(2);
+    throw new ExitError(2, '--from and --to are required for github-release-notes');
   }
   if (opts.cmd === 'extract' && (!opts.fromRef || !opts.toRef)) {
     process.stderr.write('--from and --to are required for extract\n');
     process.stderr.write(usage());
-    process.exit(1);
+    throw new ExitError(1);
+  }
+  if (opts.cmd === 'verify' && !opts.version) {
+    throw new ExitError(2, '--version is required for verify');
   }
 
   if (opts.cmd === 'extract') {
@@ -367,7 +507,19 @@ function main() {
     } else if (exitCode === 2) {
       process.stderr.write(`no releases found in range (from=${report.from}, to=${report.to})\n`);
     }
-    process.exit(exitCode);
+    return exitCode;
+  }
+
+  if (opts.cmd === 'verify') {
+    const { exitCode, report, textOutput } = cmdVerify(opts);
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    } else if (textOutput) {
+      process.stdout.write(textOutput + '\n');
+    } else {
+      process.stderr.write(report.error + '\n');
+    }
+    return exitCode;
   }
 
   const { exitCode, report } = opts.cmd === 'render' ? cmdRender(opts) : cmdGithubReleaseNotes(opts);
@@ -376,6 +528,9 @@ function main() {
   } else if (opts.cmd === 'github-release-notes' && report.body) {
     process.stdout.write(report.body);
   } else {
+    if (report.error) {
+      process.stderr.write(`${report.error}\n`);
+    }
     process.stdout.write(`Consumed: ${report.consumed} fragment(s)\n`);
     if (report.failures.length > 0) {
       process.stdout.write(`Failures: ${report.failures.length}\n`);
@@ -384,9 +539,9 @@ function main() {
       }
     }
   }
-  process.exit(exitCode);
+  return exitCode;
 }
 
-if (require.main === module) main();
+if (require.main === module) runMain(main);
 
-module.exports = { cmdRender, cmdExtract, cmdGithubReleaseNotes, parseArgs, splitChangelog, listFragmentFiles, usage };
+module.exports = { cmdRender, cmdExtract, cmdVerify, cmdGithubReleaseNotes, parseArgs, splitChangelog, assembleChangelog, listFragmentFiles, usage };

package/scripts/changeset/lint.cjs

@@ -60,6 +60,8 @@ function evaluateLint({ changedFiles, labels }) {
   return { ok: false, reason: LINT_REASON.FAIL_MISSING_FRAGMENT };
 }
 
+const { ExitError, runMain } = require('../lib/cli-exit.cjs');
+
 function main() {
   const fs = require('node:fs');
   const cp = require('node:child_process');
@@ -87,8 +89,7 @@ function main() {
     );
     changedFiles = out.split('\n').filter(Boolean);
   } catch (e) {
-    process.stderr.write(`could not compute diff: ${e.message}\n`);
-    process.exit(2);
+    throw new ExitError(2, `could not compute diff: ${e.message}`);
   }
 
   const verdict = evaluateLint({ changedFiles, labels });
@@ -102,9 +103,9 @@ function main() {
     process.stderr.write(`Run \`npm run changeset\` to create one, or add the \`${OPT_OUT_LABEL}\` label\n`);
     process.stderr.write(`if this PR genuinely has no user-facing impact (test refactor, CI tweak, etc.).\n`);
   }
-  process.exit(verdict.ok ? 0 : 1);
+  return verdict.ok ? 0 : 1;
 }
 
-if (require.main === module) main();
+if (require.main === module) runMain(main);
 
 module.exports = { evaluateLint, LINT_REASON, OPT_OUT_LABEL, isUserFacing, isFragment };

package/scripts/changeset/new.cjs

@@ -13,6 +13,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { ExitError, runMain } = require('../lib/cli-exit.cjs');
 
 // Small word lists — keep the function simple and dependency-free.
 // Together this gives ~40 * 40 * 40 = 64,000 distinct names. The lint
@@ -121,17 +122,16 @@ function main() {
   if (!parsed.ok) {
     process.stderr.write(`${parsed.error}\n`);
     process.stderr.write('usage: changeset/new.cjs --type <Fixed|Added|...> --pr NNNN --body "..."\n');
-    process.exit(2);
+    throw new ExitError(2);
   }
   const { opts } = parsed;
   if (!opts.type || !opts.pr || !opts.body) {
-    process.stderr.write('usage: changeset/new.cjs --type <Fixed|Added|...> --pr NNNN --body "..."\n');
-    process.exit(2);
+    throw new ExitError(2, 'usage: changeset/new.cjs --type <Fixed|Added|...> --pr NNNN --body "..."');
   }
   const file = scaffoldFragment(opts);
   process.stdout.write(`${path.relative(process.cwd(), file)}\n`);
 }
 
-if (require.main === module) main();
+if (require.main === module) runMain(main);
 
 module.exports = { generateFragmentName, scaffoldFragment, parseArgs, ALLOWED_TYPES };

package/scripts/check-alias-drift.cjs

@@ -3,12 +3,14 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
 const ROOT = path.resolve(__dirname, '..');
 const aliasesPath = path.join(ROOT, 'gsd-core', 'bin', 'lib', 'command-aliases.cjs');
 
 function fail(message) {
   process.stderr.write(`${message}\n`);
-  process.exit(1);
+  throw new ExitError(1);
 }
 
 function ensureArray(value, name) {
@@ -27,82 +29,86 @@ function assertNoDuplicates(values, label) {
   }
 }
 
-if (!fs.existsSync(aliasesPath)) {
-  fail(`check:alias-drift: missing ${path.relative(ROOT, aliasesPath)}`);
-}
-
-const aliases = require(aliasesPath);
-
-const families = [
-  {
-    commandAliases: 'STATE_COMMAND_ALIASES',
-    subcommands: 'STATE_SUBCOMMANDS',
-    routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'state-command-router.cjs'),
-  },
-  {
-    commandAliases: 'VERIFY_COMMAND_ALIASES',
-    subcommands: 'VERIFY_SUBCOMMANDS',
-    routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'verify-command-router.cjs'),
-  },
-  {
-    commandAliases: 'INIT_COMMAND_ALIASES',
-    subcommands: 'INIT_SUBCOMMANDS',
-    routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'init-command-router.cjs'),
-  },
-  {
-    commandAliases: 'PHASE_COMMAND_ALIASES',
-    subcommands: 'PHASE_SUBCOMMANDS',
-    routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'phase-command-router.cjs'),
-  },
-  {
-    commandAliases: 'PHASES_COMMAND_ALIASES',
-    subcommands: 'PHASES_SUBCOMMANDS',
-    routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'phases-command-router.cjs'),
-  },
-  {
-    commandAliases: 'VALIDATE_COMMAND_ALIASES',
-    subcommands: 'VALIDATE_SUBCOMMANDS',
-    routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'validate-command-router.cjs'),
-  },
-  {
-    commandAliases: 'ROADMAP_COMMAND_ALIASES',
-    subcommands: 'ROADMAP_SUBCOMMANDS',
-    routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'roadmap-command-router.cjs'),
-  },
-];
-
-for (const family of families) {
-  const commandAliases = aliases[family.commandAliases];
-  const subcommands = aliases[family.subcommands];
-
-  ensureArray(commandAliases, family.commandAliases);
-  ensureArray(subcommands, family.subcommands);
-
-  const derivedSubcommands = commandAliases.map((entry) => entry && entry.subcommand);
-  assertNoDuplicates(derivedSubcommands, `${family.commandAliases}.subcommand`);
-
-  if (derivedSubcommands.length !== subcommands.length) {
-    fail(
-      `check:alias-drift: ${family.subcommands} length ${subcommands.length} does not match ` +
-      `${family.commandAliases} length ${derivedSubcommands.length}`,
-    );
+function main() {
+  if (!fs.existsSync(aliasesPath)) {
+    fail(`check:alias-drift: missing ${path.relative(ROOT, aliasesPath)}`);
   }
 
-  for (let i = 0; i < derivedSubcommands.length; i++) {
-    if (derivedSubcommands[i] !== subcommands[i]) {
+  const aliases = require(aliasesPath);
+
+  const families = [
+    {
+      commandAliases: 'STATE_COMMAND_ALIASES',
+      subcommands: 'STATE_SUBCOMMANDS',
+      routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'state-command-router.cjs'),
+    },
+    {
+      commandAliases: 'VERIFY_COMMAND_ALIASES',
+      subcommands: 'VERIFY_SUBCOMMANDS',
+      routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'verify-command-router.cjs'),
+    },
+    {
+      commandAliases: 'INIT_COMMAND_ALIASES',
+      subcommands: 'INIT_SUBCOMMANDS',
+      routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'init-command-router.cjs'),
+    },
+    {
+      commandAliases: 'PHASE_COMMAND_ALIASES',
+      subcommands: 'PHASE_SUBCOMMANDS',
+      routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'phase-command-router.cjs'),
+    },
+    {
+      commandAliases: 'PHASES_COMMAND_ALIASES',
+      subcommands: 'PHASES_SUBCOMMANDS',
+      routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'phases-command-router.cjs'),
+    },
+    {
+      commandAliases: 'VALIDATE_COMMAND_ALIASES',
+      subcommands: 'VALIDATE_SUBCOMMANDS',
+      routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'validate-command-router.cjs'),
+    },
+    {
+      commandAliases: 'ROADMAP_COMMAND_ALIASES',
+      subcommands: 'ROADMAP_SUBCOMMANDS',
+      routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'roadmap-command-router.cjs'),
+    },
+  ];
+
+  for (const family of families) {
+    const commandAliases = aliases[family.commandAliases];
+    const subcommands = aliases[family.subcommands];
+
+    ensureArray(commandAliases, family.commandAliases);
+    ensureArray(subcommands, family.subcommands);
+
+    const derivedSubcommands = commandAliases.map((entry) => entry && entry.subcommand);
+    assertNoDuplicates(derivedSubcommands, `${family.commandAliases}.subcommand`);
+
+    if (derivedSubcommands.length !== subcommands.length) {
       fail(
-        `check:alias-drift: ${family.subcommands}[${i}] = "${subcommands[i]}" ` +
-        `does not match ${family.commandAliases}[${i}].subcommand = "${derivedSubcommands[i]}"`,
+        `check:alias-drift: ${family.subcommands} length ${subcommands.length} does not match ` +
+        `${family.commandAliases} length ${derivedSubcommands.length}`,
       );
     }
-  }
 
-  const routerSource = fs.readFileSync(family.routerPath, 'utf8');
-  if (!routerSource.includes(family.subcommands)) {
-    fail(
-      `check:alias-drift: ${path.relative(ROOT, family.routerPath)} does not reference ${family.subcommands}`,
-    );
+    for (let i = 0; i < derivedSubcommands.length; i++) {
+      if (derivedSubcommands[i] !== subcommands[i]) {
+        fail(
+          `check:alias-drift: ${family.subcommands}[${i}] = "${subcommands[i]}" ` +
+          `does not match ${family.commandAliases}[${i}].subcommand = "${derivedSubcommands[i]}"`,
+        );
+      }
+    }
+
+    const routerSource = fs.readFileSync(family.routerPath, 'utf8');
+    if (!routerSource.includes(family.subcommands)) {
+      fail(
+        `check:alias-drift: ${path.relative(ROOT, family.routerPath)} does not reference ${family.subcommands}`,
+      );
+    }
   }
+
+  process.stdout.write('check:alias-drift ok\n');
 }
 
-process.stdout.write('check:alias-drift ok\n');
+runMain(main);