@opengsd/gsd-core 1.2.0-rc.1

package/scripts/changeset/README.md

@@ -0,0 +1,129 @@
+# changeset/ — release-notes tooling
+
+This directory holds the scripts that turn per-PR fragments in [`.changeset/`](../../.changeset/README.md)
+and git history into the project's `CHANGELOG.md` and GitHub release notes.
+
+The entry point is `cli.cjs`. It exposes three subcommands:
+
+| Subcommand | Purpose |
+|---|---|
+| `render` | Render a single version's changelog section from consolidated data. |
+| `github-release-notes` | Build GitHub release-notes body for a ref range. |
+| `extract` | Pull existing `CHANGELOG.md` entries that fall in a version range. |
+
+The rest of this document specifies the **`extract`** contract, because it is the
+surface most likely to be called by external tooling (CI workflows, npm scripts,
+release automation) that needs a stable exit-code and output guarantee to code
+against.
+
+---
+
+## `cli.cjs extract`
+
+Extract the changelog entries for every release in a version range, reading from
+an existing `CHANGELOG.md`. The range is **`--from` exclusive, `--to` inclusive**.
+
+```bash
+node scripts/changeset/cli.cjs extract --from VERSION --to VERSION \
+  [--changelog FILE] [--repo <dir>] [--json]
+```
+
+### Flags
+
+| Flag | Required | Description |
+|---|---|---|
+| `--from VERSION` | Yes | Lower bound, **exclusive** — entries equal to `--from` are not returned. |
+| `--to VERSION` | Yes | Upper bound, **inclusive** — entries equal to `--to` are returned. |
+| `--changelog FILE` | No | Path to the changelog to read. Defaults to `<repo>/CHANGELOG.md`. |
+| `--repo <dir>` | No | Repo root used to locate `CHANGELOG.md` when `--changelog` is omitted. Defaults to the current working directory. |
+| `--json` | No | Emit the structured report as JSON instead of rendered markdown. |
+
+### Version validation
+
+Both `--from` and `--to` must be **stable triplet semver** — `MAJOR.MINOR.PATCH`,
+digits only.
+
+- A leading `v` is accepted and stripped: `v1.42.0` is treated as `1.42.0`.
+- Pre-release and build suffixes are **rejected**: `1.42.0-rc.1`, `1.42.0+build`,
+  and partial versions like `1.42.x` all fail validation and exit `1`.
+
+Strict validation is deliberate. Coercing a malformed bound such as `1.42.x` to
+`1.42.0` would silently change which releases the range selects, so a malformed
+bound is rejected early with a structured error rather than guessed at.
+
+Changelog entries that are themselves pre-release or non-semver (and the
+`Unreleased` section) are skipped during matching; a notice for each skipped
+entry is written to stderr.
+
+### Exit codes
+
+`extract` resolves to one of three exit codes. The output shape depends on
+whether `--json` is passed.
+
+| Exit | Meaning | Default stdout | `--json` stdout |
+|---|---|---|---|
+| `0` | One or more releases fall in the range. | Rendered markdown for the matched releases. | `{ "releases": [ ... ], "from": "...", "to": "..." }` |
+| `1` | Bad input: `--from`/`--to` is not stable semver, a required flag is missing, or the changelog file was not found. | Nothing (a missing-flag error and usage go to stderr). | `{ "error": "<message>", "releases": [] }` |
+| `2` | Bounds are valid but no release falls in the range. | A `no releases found in range` notice on stderr. | `{ "releases": [], "from": "...", "to": "..." }` |
+
+Notes for callers:
+
+- **Treat exit `2` as "empty range", not "failure".** For a well-formed
+  invocation it means the request was understood and simply matched nothing — do
+  not surface it as an error. (At the argument-parsing layer, malformed argv such
+  as an unknown flag also exits `2`; pass well-formed arguments and this overlap
+  does not arise.)
+- **In default (text) mode, a failure is signalled by the exit code alone** —
+  exit `1` from invalid semver or a missing changelog writes nothing to stdout.
+  Machine consumers should pass `--json` to receive the `error` field.
+
+### Output shape
+
+With `--json`, the report is pretty-printed JSON. The `releases` array contains
+one object per matched release (version, date, and parsed sections); `from` and
+`to` echo the normalized bounds. On exit `1`, `releases` is empty and an `error`
+string describes the failure.
+
+Without `--json`, exit `0` prints the matched releases as markdown, ready to
+paste into release notes:
+
+```text
+## [1.42.0] - 2026-01-15
+
+### Added
+
+- New `--json` flag on the extract command (#3796)
+
+### Fixed
+
+- Trailing-slash handling in config paths (#3651)
+```
+
+### Examples
+
+Extract everything released after `1.41.0` up to and including `1.42.0`:
+
+```bash
+node scripts/changeset/cli.cjs extract --from 1.41.0 --to 1.42.0
+```
+
+The same range as structured JSON, reading an explicit changelog file:
+
+```bash
+node scripts/changeset/cli.cjs extract \
+  --from v1.41.0 --to v1.42.0 \
+  --changelog ./CHANGELOG.md --json
+```
+
+Handle the three outcomes in a shell consumer:
+
+```bash
+if out=$(node scripts/changeset/cli.cjs extract --from "$FROM" --to "$TO" --json); then
+  echo "$out"            # exit 0 — releases found
+else
+  case $? in
+    2) echo "no releases in range — nothing to publish" ;;  # not an error
+    *) echo "extract failed: $out" >&2; exit 1 ;;            # exit 1 — bad input
+  esac
+fi
+```

package/scripts/changeset/cli.cjs

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * CLI wrapper for the changeset-fragment workflow (#2975).
+ *
+ * Subcommands:
+ *   render --repo <dir> --version V --date D [--json]   Fold .changeset/*.md
+ *                                                       into CHANGELOG.md;
+ *                                                       delete consumed fragments.
+ *
+ * `--json` emits a structured report on stdout — the only contract tests
+ * assert against. Per CONTRIBUTING.md "Prohibited: Raw Text Matching on
+ * Test Outputs", the human formatter is operator-only.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { parseFragment, FRAGMENT_ERROR } = require('./parse.cjs');
+const { renderChangelog } = require('./render.cjs');
+const { serializeChangelog, parseChangelog } = require('./serialize.cjs');
+const { renderGithubReleaseNotes } = require('./github-release-notes.cjs');
+const {
+  compareSemverCore,
+  isStableTripletSemver,
+} = require('../../get-shit-done/bin/lib/semver-compare.cjs');
+const { packageName, repoSlug: defaultRepoSlug } = require('../../get-shit-done/bin/lib/package-identity.cjs');
+
+function parseArgs(argv) {
+  const opts = {
+    cmd: null,
+    repo: process.cwd(),
+    version: null,
+    date: null,
+    fromRef: null,
+    toRef: null,
+    changelog: null,
+    output: null,
+    repoSlug: defaultRepoSlug,
+    installCommand: `npx ${packageName}@latest`,
+    json: false,
+  };
+  if (argv.length === 0) return { ok: true, opts };
+  opts.cmd = argv[0];
+
+  // Pull a value for a value-taking flag, validating that the next token
+  // exists and is not itself another flag (which is the silently-misparsed
+  // case CR called out: e.g. `--repo --json` would consume `--json` as the
+  // repo path).
+  const requireValue = (flag, i) => {
+    const v = argv[i + 1];
+    if (v === undefined || v.startsWith('--')) {
+      return { ok: false, error: `missing value for ${flag}` };
+    }
+    return { ok: true, value: v };
+  };
+
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') { opts.json = true; continue; }
+    if (
+      a === '--repo' ||
+      a === '--version' ||
+      a === '--date' ||
+      a === '--from' ||
+      a === '--to' ||
+      a === '--changelog' ||
+      a === '--output' ||
+      a === '--repo-slug' ||
+      a === '--install-command'
+    ) {
+      const r = requireValue(a, i);
+      if (!r.ok) return { ok: false, error: r.error };
+      if (a === '--repo') opts.repo = r.value;
+      else if (a === '--version') opts.version = r.value;
+      else if (a === '--date') opts.date = r.value;
+      else if (a === '--from') opts.fromRef = r.value;
+      else if (a === '--to') opts.toRef = r.value;
+      else if (a === '--changelog') opts.changelog = r.value;
+      else if (a === '--output') opts.output = r.value;
+      else if (a === '--repo-slug') opts.repoSlug = r.value;
+      else if (a === '--install-command') opts.installCommand = r.value;
+      i++;
+      continue;
+    }
+    return { ok: false, error: `unknown argument: ${a}` };
+  }
+  return { ok: true, opts };
+}
+
+function listFragmentFiles(changesetDir) {
+  if (!fs.existsSync(changesetDir)) return [];
+  return fs.readdirSync(changesetDir)
+    .filter((f) => f.endsWith('.md') && f !== 'README.md')
+    .map((f) => path.join(changesetDir, f));
+}
+
+function splitChangelog(text) {
+  // Split off the top-level "# Changelog" heading + lead matter (everything
+  // before the first "## [version]" block) from the rest. The rest is the
+  // priorChangelog passed into renderChangelog. The "## [Unreleased]" block,
+  // if present, is dropped (the new release replaces it).
+  const lines = text.split(/\r?\n/);
+  const firstReleaseIdx = lines.findIndex((l) => /^##\s+\[/.test(l));
+  if (firstReleaseIdx === -1) {
+    return { lead: text.replace(/\s+$/, ''), prior: '' };
+  }
+  const lead = lines.slice(0, firstReleaseIdx).join('\n').replace(/\s+$/, '');
+  let priorStart = firstReleaseIdx;
+  // Skip the [Unreleased] block if present — it's a placeholder, not a release.
+  if (/^##\s+\[Unreleased\]/i.test(lines[firstReleaseIdx])) {
+    let j = firstReleaseIdx + 1;
+    while (j < lines.length && !/^##\s+\[/.test(lines[j])) j++;
+    priorStart = j;
+  }
+  const prior = lines.slice(priorStart).join('\n').trimStart();
+  return { lead, prior };
+}
+
+function cmdRender(opts) {
+  const repo = path.resolve(opts.repo);
+  const changesetDir = path.join(repo, '.changeset');
+  const changelogPath = path.join(repo, 'CHANGELOG.md');
+  const fragmentFiles = listFragmentFiles(changesetDir);
+
+  const fragments = [];
+  const failures = [];
+  for (const file of fragmentFiles) {
+    const src = fs.readFileSync(file, 'utf8');
+    const r = parseFragment(src);
+    if (r.ok) fragments.push({ ...r.fragment, file });
+    else failures.push({ file: path.relative(repo, file), reason: r.reason, detail: r.detail || null });
+  }
+
+  if (failures.length > 0) {
+    return { exitCode: 1, report: { consumed: 0, failures } };
+  }
+  if (fragments.length === 0) {
+    return { exitCode: 0, report: { consumed: 0, failures: [] } };
+  }
+
+  const priorText = fs.existsSync(changelogPath) ? fs.readFileSync(changelogPath, 'utf8') : '';
+  const { lead, prior } = splitChangelog(priorText);
+
+  const ir = renderChangelog({
+    fragments,
+    version: opts.version,
+    date: opts.date,
+    priorChangelog: prior || null,
+  });
+  const releaseBlock = serializeChangelog(ir);
+  const out = [
+    lead || '# Changelog',
+    '',
+    '## [Unreleased]',
+    '',
+    releaseBlock.replace(/\s+$/, ''),
+    '',
+  ].join('\n');
+
+  fs.writeFileSync(changelogPath, out);
+
+  // Delete consumed fragments. If any unlink fails the changelog is written
+  // but the fragment is still on disk, so a re-run would double-consume it.
+  // Surface the partial-failure as exitCode=1 with structured detail so the
+  // operator can manually clean up before retrying.
+  const deleteFailures = [];
+  for (const f of fragments) {
+    try {
+      fs.unlinkSync(f.file);
+    } catch (e) {
+      deleteFailures.push({
+        file: path.relative(repo, f.file),
+        reason: 'fail_fragment_delete',
+        detail: e.code || e.message,
+      });
+    }
+  }
+
+  return {
+    exitCode: deleteFailures.length > 0 ? 1 : 0,
+    report: {
+      consumed: fragments.length - deleteFailures.length,
+      failures: deleteFailures,
+      release: { version: opts.version, date: opts.date },
+    },
+  };
+}
+
+/**
+ * extract subcommand: extracts all changelog release blocks strictly after
+ * `--from` (exclusive) up to and including `--to` (inclusive).  Both
+ * arguments accept `v`-prefixed semver (e.g. `v1.5.13`).
+ *
+ * Exit codes:
+ *   0  — one or more releases matched, output written.
+ *   2  — no releases fall in the specified range (matches nothing).
+ *   1  — I/O error or missing required flags.
+ *
+ * Fix for #3496: provides a deterministic range-aware helper so the
+ * `/gsd:update` show_changes_and_confirm step no longer relies on
+ * 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);
+
+  // Validate that both bounds are strict semver (N.N.N, digits only).
+  // Coercing a malformed bound like "1.41.x" to "1.41.0" makes range
+  // selection silently wrong; reject early with a structured error.
+  if (!isStableTripletSemver(from)) {
+    return {
+      exitCode: 1,
+      report: { error: `invalid semver for --from: "${from}" (expected N.N.N)`, releases: [] },
+      textOutput: null,
+    };
+  }
+  if (!isStableTripletSemver(to)) {
+    return {
+      exitCode: 1,
+      report: { error: `invalid semver for --to: "${to}" (expected N.N.N)`, releases: [] },
+      textOutput: null,
+    };
+  }
+
+  const changelogPath = opts.changelog
+    ? path.resolve(opts.changelog)
+    : path.join(path.resolve(opts.repo), 'CHANGELOG.md');
+
+  if (!fs.existsSync(changelogPath)) {
+    return {
+      exitCode: 1,
+      report: { error: `CHANGELOG not found: ${changelogPath}`, releases: [] },
+      textOutput: null,
+    };
+  }
+
+  const text = fs.readFileSync(changelogPath, 'utf8');
+  const { releases } = parseChangelog(text);
+
+  const matched = releases.filter((rel) => {
+    if (rel.version === 'Unreleased') return false;
+    // Extract mode intentionally operates on stable releases only.
+    if (!isStableTripletSemver(rel.version)) {
+      process.stderr.write(`[extract] skipping pre-release/non-semver entry: ${rel.version}\n`);
+      return false;
+    }
+    // from is exclusive: cmp > 0 means rel.version > from
+    const afterFrom = compareSemverCore(rel.version, from) > 0;
+    // to is inclusive: cmp <= 0 means rel.version <= to
+    const upToTo = compareSemverCore(rel.version, to) <= 0;
+    return afterFrom && upToTo;
+  });
+
+  if (matched.length === 0) {
+    return {
+      exitCode: 2,
+      report: { releases: [], from, to },
+      textOutput: null,
+    };
+  }
+
+  return {
+    exitCode: 0,
+    report: { releases: matched, from, to },
+    textOutput: matched
+      .map((rel) => {
+        const header = `## [${rel.version}]${rel.date ? ` - ${rel.date}` : ''}`;
+        const sections = (rel.sections || [])
+          .map((s) => {
+            const bullets = s.bullets
+              .map((b) => (b.pr !== null ? `- ${b.body} (#${b.pr})` : `- ${b.body}`))
+              .join('\n');
+            return `### ${s.type}\n\n${bullets}`;
+          })
+          .join('\n\n');
+        return sections ? `${header}\n\n${sections}` : header;
+      })
+      .join('\n\n'),
+  };
+}
+
+function cmdGithubReleaseNotes(opts) {
+  const repo = path.resolve(opts.repo);
+  const report = renderGithubReleaseNotes({
+    repo,
+    fromRef: opts.fromRef,
+    toRef: opts.toRef,
+    repoSlug: opts.repoSlug,
+    installCommand: opts.installCommand,
+  });
+
+  if (!report.ok) {
+    return {
+      exitCode: 1,
+      report: {
+        consumed: 0,
+        failures: report.failures,
+        release: { from: opts.fromRef, to: opts.toRef },
+      },
+    };
+  }
+
+  if (opts.output) {
+    fs.writeFileSync(path.resolve(opts.output), report.body);
+  }
+
+  return {
+    exitCode: 0,
+    report: {
+      consumed: report.fragments.length,
+      failures: [],
+      release: { from: opts.fromRef, to: opts.toRef },
+      output: opts.output || null,
+      body: opts.output ? null : report.body,
+    },
+  };
+}
+
+function usage() {
+  return [
+    'usage:',
+    '  changeset/cli.cjs render --repo <dir> --version V --date D [--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.',
+    '',
+  ].join('\n');
+}
+
+function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (!parsed.ok) {
+    process.stderr.write(`${parsed.error}\n`);
+    process.stderr.write(usage());
+    process.exit(2);
+  }
+  const { opts } = parsed;
+  if (opts.cmd !== 'render' && opts.cmd !== 'github-release-notes' && opts.cmd !== 'extract') {
+    process.stderr.write(usage());
+    process.exit(1);
+  }
+  if (opts.cmd === 'render' && (!opts.version || !opts.date)) {
+    process.stderr.write('--version and --date are required for render\n');
+    process.exit(2);
+  }
+  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);
+  }
+  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);
+  }
+
+  if (opts.cmd === 'extract') {
+    const { exitCode, report, textOutput } = cmdExtract(opts);
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    } else if (textOutput) {
+      process.stdout.write(textOutput + '\n');
+    } else if (exitCode === 2) {
+      process.stderr.write(`no releases found in range (from=${report.from}, to=${report.to})\n`);
+    }
+    process.exit(exitCode);
+  }
+
+  const { exitCode, report } = opts.cmd === 'render' ? cmdRender(opts) : cmdGithubReleaseNotes(opts);
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+  } else if (opts.cmd === 'github-release-notes' && report.body) {
+    process.stdout.write(report.body);
+  } else {
+    process.stdout.write(`Consumed: ${report.consumed} fragment(s)\n`);
+    if (report.failures.length > 0) {
+      process.stdout.write(`Failures: ${report.failures.length}\n`);
+      for (const f of report.failures) {
+        process.stdout.write(`  ${f.file}: ${f.reason}${f.detail ? ` (${f.detail})` : ''}\n`);
+      }
+    }
+  }
+  process.exit(exitCode);
+}
+
+if (require.main === module) main();
+
+module.exports = { cmdRender, cmdExtract, cmdGithubReleaseNotes, parseArgs, splitChangelog, listFragmentFiles, usage };