@opengsd/gsd-core 1.20.0 → 1.21.0

package/scripts/merge-commit-pr.cjs

@@ -0,0 +1,186 @@
+'use strict';
+
+/**
+ * Land one of the release pipeline's history-carrying PRs as a merge commit (#5894).
+ *
+ * Two PRs must keep a parent edge, or main and next stop sharing history and
+ * the next release -> main merge conflicts in every version field:
+ *
+ *   release-merge           release/X.Y.0 | hotfix/X.Y.Z -> main        keeps the v<version> tag in main
+ *   main-to-next-backmerge  chore/backmerge-main-to-next-<sha> -> next  keeps main an ancestor of next
+ *
+ * v1.19.0 broke both (#5729 and #5730 were squash-merged). This script is the
+ * one sanctioned way to merge them, from auto-backmerge.yml, release.yml and a
+ * maintainer's shell alike:
+ *
+ *   1. it merges through `PUT /repos/{repo}/pulls/{n}/merge` with
+ *      merge_method=merge: never the merge queue, which squashes, and not
+ *      `gh pr merge --admin`, which does not honor a ruleset bypass;
+ *   2. the merge is pinned to the head sha it read (`sha=`), so a push after
+ *      the read is refused rather than merged unseen;
+ *   3. afterwards it proves the result: the merge commit has two parents, one
+ *      of them the PR head, and the base branch now contains the PR head.
+ *
+ * Usage: node scripts/merge-commit-pr.cjs <pr-number> [--repo owner/name]
+ * Prints one JSON result line; exits 0 when merged and verified, else 1.
+ */
+
+const { execFileSync } = require('node:child_process');
+const { RELEASE_PIPELINE_PR_KIND, releasePipelinePrKind } = require('./release-pipeline-pr.cjs');
+const { runMain } = require('./lib/cli-exit.cjs');
+
+const MERGE_COMMIT_PR_REASON = Object.freeze({
+  MERGED: 'merged',
+  USAGE: 'usage',
+  PR_UNREADABLE: 'pr-unreadable',
+  NOT_OPEN: 'not-open',
+  NOT_A_HISTORY_PR: 'not-a-history-pr',
+  MERGE_REFUSED: 'merge-refused',
+  NOT_A_MERGE_COMMIT: 'not-a-merge-commit',
+  ANCESTRY_BROKEN: 'ancestry-broken',
+  TAG_NOT_IN_BASE: 'tag-not-in-base',
+  VERIFY_UNREADABLE: 'verify-unreadable',
+});
+
+const HISTORY_KINDS = Object.freeze([
+  RELEASE_PIPELINE_PR_KIND.RELEASE_MERGE,
+  RELEASE_PIPELINE_PR_KIND.MAIN_TO_NEXT_BACKMERGE,
+]);
+
+const PR_NUMBER_RE = /^[1-9][0-9]*$/;
+const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const GH_TIMEOUT_MS = 30000;
+const GH_MERGE_TIMEOUT_MS = 60000;
+
+/** The release tag a release/hotfix head branch publishes: release/1.20.0 -> v1.20.0. */
+function releaseTagFor(headRef) {
+  const match = /^(?:release|hotfix)\/((?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*))$/.exec(String(headRef || ''));
+  return match ? `v${match[1]}` : null;
+}
+
+/** Parse argv. Returns { prNumber, repo } or { error }. */
+function parseArgs(argv, env = process.env) {
+  let prNumber = null;
+  let repo = env.GITHUB_REPOSITORY || 'open-gsd/gsd-core';
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--repo') {
+      const value = argv[i + 1];
+      if (typeof value !== 'string' || !REPO_RE.test(value)) return { error: '--repo needs owner/name' };
+      repo = value;
+      i += 1;
+    } else if (prNumber === null && PR_NUMBER_RE.test(arg)) {
+      prNumber = Number(arg);
+    } else {
+      return { error: `unexpected argument: ${arg}` };
+    }
+  }
+  if (prNumber === null) return { error: 'usage: merge-commit-pr.cjs <pr-number> [--repo owner/name]' };
+  if (!REPO_RE.test(repo)) return { error: `invalid repository: ${repo}` };
+  return { prNumber, repo };
+}
+
+/** Default gh runner: returns stdout; throws on non-zero exit (err.stderr carries gh's text). */
+function defaultGh(args, { timeout = GH_TIMEOUT_MS } = {}) {
+  return execFileSync('gh', args, { encoding: 'utf8', timeout, stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+function errorText(err) {
+  return String((err && (err.stderr || err.message)) || err).trim();
+}
+
+/**
+ * Merge PR `prNumber` of `repo` with a merge commit and verify the history.
+ * `gh(args, opts)` returns gh's stdout (JSON for `gh api`) and throws on failure.
+ *
+ * @returns {{ ok: boolean, reason: string, kind?: string, mergeSha?: string, detail?: string }}
+ */
+function mergeWithMergeCommit({ prNumber, repo, gh = defaultGh }) {
+  let pr;
+  try {
+    pr = JSON.parse(gh(['api', `repos/${repo}/pulls/${prNumber}`]));
+  } catch (err) {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.PR_UNREADABLE, detail: errorText(err) };
+  }
+  if (!pr || pr.state !== 'open' || pr.merged === true) {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.NOT_OPEN };
+  }
+  const head = pr.head || {};
+  const base = pr.base || {};
+  const headRepo = head.repo && typeof head.repo.full_name === 'string' ? head.repo.full_name : null;
+  const kind = releasePipelinePrKind({
+    headRef: head.ref,
+    baseRef: base.ref,
+    sameRepo: headRepo !== null && headRepo.toLowerCase() === repo.toLowerCase(),
+  });
+  if (!HISTORY_KINDS.includes(kind)) {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.NOT_A_HISTORY_PR, kind: kind || undefined };
+  }
+  const headSha = head.sha;
+
+  let merge;
+  try {
+    merge = JSON.parse(gh(
+      ['api', '-X', 'PUT', `repos/${repo}/pulls/${prNumber}/merge`, '-f', 'merge_method=merge', '-f', `sha=${headSha}`],
+      { timeout: GH_MERGE_TIMEOUT_MS },
+    ));
+  } catch (err) {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.MERGE_REFUSED, kind, detail: errorText(err) };
+  }
+  if (!merge || merge.merged !== true || typeof merge.sha !== 'string') {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.MERGE_REFUSED, kind, detail: JSON.stringify(merge) };
+  }
+  const mergeSha = merge.sha;
+
+  let commit;
+  let compare;
+  try {
+    commit = JSON.parse(gh(['api', `repos/${repo}/commits/${mergeSha}`]));
+    compare = JSON.parse(gh(['api', `repos/${repo}/compare/${headSha}...${base.ref}`]));
+  } catch (err) {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.VERIFY_UNREADABLE, kind, mergeSha, detail: errorText(err) };
+  }
+  const parents = commit && Array.isArray(commit.parents) ? commit.parents.map((p) => p && p.sha) : [];
+  if (parents.length !== 2 || !parents.includes(headSha)) {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.NOT_A_MERGE_COMMIT, kind, mergeSha, detail: `parents=${parents.join(',')}` };
+  }
+  if (!compare || compare.behind_by !== 0) {
+    return { ok: false, reason: MERGE_COMMIT_PR_REASON.ANCESTRY_BROKEN, kind, mergeSha, detail: `behind_by=${compare && compare.behind_by}` };
+  }
+  if (kind === RELEASE_PIPELINE_PR_KIND.RELEASE_MERGE) {
+    const tag = releaseTagFor(head.ref);
+    if (tag === null) {
+      return { ok: false, reason: MERGE_COMMIT_PR_REASON.VERIFY_UNREADABLE, kind, mergeSha, detail: 'no release tag for ' + head.ref };
+    }
+    let tagCompare;
+    try {
+      tagCompare = JSON.parse(gh(['api', `repos/${repo}/compare/${tag}...${base.ref}`]));
+    } catch (err) {
+      return { ok: false, reason: MERGE_COMMIT_PR_REASON.VERIFY_UNREADABLE, kind, mergeSha, detail: errorText(err) };
+    }
+    if (!tagCompare || tagCompare.behind_by !== 0) {
+      return { ok: false, reason: MERGE_COMMIT_PR_REASON.TAG_NOT_IN_BASE, kind, mergeSha, detail: `${tag} behind_by=${tagCompare && tagCompare.behind_by}` };
+    }
+  }
+  return { ok: true, reason: MERGE_COMMIT_PR_REASON.MERGED, kind, mergeSha };
+}
+
+function main(argv = process.argv.slice(2), { gh = defaultGh, env = process.env, stdout = process.stdout, stderr = process.stderr } = {}) {
+  const args = parseArgs(argv, env);
+  if (args.error) {
+    stderr.write(`::error::${args.error}\n`);
+    stdout.write(`${JSON.stringify({ ok: false, reason: MERGE_COMMIT_PR_REASON.USAGE })}\n`);
+    return 1;
+  }
+  const result = mergeWithMergeCommit({ prNumber: args.prNumber, repo: args.repo, gh });
+  stdout.write(`${JSON.stringify(result)}\n`);
+  if (!result.ok) {
+    stderr.write(`::error::PR #${args.prNumber} was not landed as a verified merge commit (${result.reason})${result.detail ? `: ${result.detail}` : ''}. `
+      + 'Never put a release or back-merge PR in the merge queue or squash it: main and next must keep sharing history (#5894).\n');
+  }
+  return result.ok ? 0 : 1;
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = { MERGE_COMMIT_PR_REASON, HISTORY_KINDS, GH_TIMEOUT_MS, GH_MERGE_TIMEOUT_MS, releaseTagFor, parseArgs, mergeWithMergeCommit, main };

package/scripts/release-ancestry.cjs

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * Release ancestry check (#5894): `main` must be an ancestor of `next`.
+ *
+ * auto-backmerge.yml keeps that true by landing a merge commit of main into
+ * next after every release. When the back-merge is squashed (#5730), main and
+ * next stop sharing history and the next release -> main merge conflicts in
+ * every version field. release.yml runs this before cutting or finalizing a
+ * release so the break surfaces there, with the fix, instead of as a 91-file
+ * conflict on the merge-back PR.
+ *
+ * Usage: node scripts/release-ancestry.cjs [--ancestor origin/main] [--descendant origin/next]
+ * Exits 0 when the ancestor is reachable from the descendant, else 1.
+ */
+
+const { execFileSync } = require('node:child_process');
+const { runMain } = require('./lib/cli-exit.cjs');
+
+const ANCESTRY_VERDICT = Object.freeze({
+  ANCESTOR: 'ancestor',
+  DIVERGED: 'diverged',
+  UNKNOWN: 'unknown',
+});
+
+const GIT_TIMEOUT_MS = 15000;
+const REF_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
+
+/** Default git runner: returns { status } for `git <args>`. */
+function defaultGit(args) {
+  try {
+    execFileSync('git', args, { stdio: 'ignore', timeout: GIT_TIMEOUT_MS });
+    return { status: 0 };
+  } catch (err) {
+    return { status: typeof err.status === 'number' ? err.status : null };
+  }
+}
+
+/**
+ * `git merge-base --is-ancestor` exits 0 (ancestor), 1 (not), or another code
+ * (an error, e.g. an unknown ref). Only 0 and 1 are verdicts; anything else is
+ * UNKNOWN, and the CLI treats UNKNOWN as a failure.
+ */
+function checkAncestry({ ancestor, descendant, git = defaultGit }) {
+  const { status } = git(['merge-base', '--is-ancestor', ancestor, descendant]);
+  if (status === 0) return ANCESTRY_VERDICT.ANCESTOR;
+  if (status === 1) return ANCESTRY_VERDICT.DIVERGED;
+  return ANCESTRY_VERDICT.UNKNOWN;
+}
+
+function parseArgs(argv) {
+  const out = { ancestor: 'origin/main', descendant: 'origin/next' };
+  for (let i = 0; i < argv.length; i += 1) {
+    const flag = argv[i];
+    const value = argv[i + 1];
+    if ((flag === '--ancestor' || flag === '--descendant') && typeof value === 'string' && REF_RE.test(value)) {
+      out[flag.slice(2)] = value;
+      i += 1;
+    } else {
+      return { error: `unexpected argument: ${flag}` };
+    }
+  }
+  return out;
+}
+
+function main(argv = process.argv.slice(2), { git = defaultGit, stdout = process.stdout, stderr = process.stderr } = {}) {
+  const args = parseArgs(argv);
+  if (args.error) {
+    stderr.write(`::error::${args.error}\n`);
+    return 1;
+  }
+  const verdict = checkAncestry({ ancestor: args.ancestor, descendant: args.descendant, git });
+  stdout.write(`${JSON.stringify({ verdict, ancestor: args.ancestor, descendant: args.descendant })}\n`);
+  if (verdict === ANCESTRY_VERDICT.ANCESTOR) return 0;
+  stderr.write(verdict === ANCESTRY_VERDICT.DIVERGED
+    ? `::error::${args.ancestor} is not an ancestor of ${args.descendant}, so the next release -> main merge will conflict (#5894). `
+      + 'Land a back-merge of main into next as a merge commit first: push chore/backmerge-main-to-next-<short sha of main> '
+      + '(next plus `git merge -s ours --no-ff origin/main`), open it against next, and merge it with '
+      + '`node scripts/merge-commit-pr.cjs <PR>` as a repo admin. Never send it through the merge queue.\n'
+    : `::error::could not read the ancestry of ${args.ancestor} and ${args.descendant} (git failed). Fetch both refs and retry.\n`);
+  return 1;
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = { ANCESTRY_VERDICT, GIT_TIMEOUT_MS, checkAncestry, parseArgs, main };

package/scripts/release-notes/changelog-release-notes.cjs

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Build a stable GitHub Release body from the release's CHANGELOG.md section
+ * (#5922).
+ *
+ * GitHub's generated notes list PRs whose merge commits lie in the tag range.
+ * A hotfix's fixes are cherry-picks with new shas, so that list is empty for
+ * them. The curated record is the `## [X.Y.Z] - DATE` section that the
+ * finalize job's "Promote CHANGELOG" step writes, so the body is built from it.
+ *
+ * Usage:
+ *   node scripts/release-notes/changelog-release-notes.cjs --version <X.Y.Z> \
+ *     --output <file> [--changelog <path>] [--package <name>] [--repo <owner/repo>] \
+ *     [--previous <X.Y.Z>]
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('../lib/cli-exit.cjs');
+const { parseChangelog, RELEASE_HEADING_RE, EMPTY_RELEASE_PLACEHOLDER } = require('../changeset/serialize.cjs');
+const { isStableTripletSemver } = require('../../gsd-core/bin/lib/semver-compare.cjs');
+const { packageName: defaultPackageName, repoSlug: defaultRepoSlug } = require('../../gsd-core/bin/lib/package-identity.cjs');
+
+/** Typed failure reasons; every one maps to a non-zero CLI exit. */
+const CHANGELOG_NOTES_ERROR = Object.freeze({
+  INVALID_VERSION: 'invalid-version',
+  INVALID_PREVIOUS: 'invalid-previous',
+  NO_SECTION: 'no-section',
+  UNDATED_SECTION: 'undated-section',
+  EMPTY_SECTION: 'empty-section',
+  NO_PREVIOUS: 'no-previous',
+  OUTPUT_NOT_ALLOWED: 'output-not-allowed',
+  BUDGET_TOO_SMALL: 'budget-too-small',
+});
+
+class ChangelogNotesError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'ChangelogNotesError';
+    this.code = code;
+  }
+}
+
+// GitHub rejects release bodies over 125,000 characters; stay well inside.
+const RELEASE_BODY_MAX_CHARS = 120000;
+
+// Stricter than isStableTripletSemver (src/semver-compare.cts:49-51), which
+// strips a leading `v` before testing: --previous must be a bare X.Y.Z, so a
+// `v1.2.0` is rejected here rather than silently accepted.
+const STRICT_TRIPLET_RE = /^\d+\.\d+\.\d+$/;
+const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+function sliceBody(lines, startIdx, endIdx) {
+  const body = lines.slice(startIdx, endIdx);
+  while (body.length > 0 && body[0].trim() === '') body.shift();
+  while (body.length > 0 && body[body.length - 1].trim() === '') body.pop();
+  return body.join('\n');
+}
+
+/**
+ * Split a section body into ordered units: `###` headings, top-level bullets
+ * (with their continuation lines) and any leading text. Raw lines are kept so
+ * concatenating all units reproduces the body exactly.
+ */
+function splitUnits(body) {
+  const units = [];
+  for (const line of body.split('\n')) {
+    if (/^#{3,6}\s/.test(line)) units.push({ kind: 'heading', lines: [line] });
+    else if (/^[-*]\s/.test(line)) units.push({ kind: 'bullet', lines: [line] });
+    else if (units.length === 0) units.push({ kind: 'text', lines: [line] });
+    else units[units.length - 1].lines.push(line);
+  }
+  return units;
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.changelog   Full CHANGELOG.md text.
+ * @param {string} opts.version     Version, with or without a leading "v".
+ * @param {string} [opts.packageName]
+ * @param {string} [opts.repoSlug]
+ * @param {string} [opts.previous]  Explicit previous release (strict X.Y.Z).
+ * @param {number} [opts.maxChars]  Body budget (default RELEASE_BODY_MAX_CHARS).
+ * @returns {string} Release body, trailing newline included.
+ * @throws {ChangelogNotesError}
+ */
+function buildChangelogReleaseNotes({
+  changelog,
+  version,
+  packageName = defaultPackageName,
+  repoSlug = defaultRepoSlug,
+  previous = null,
+  maxChars = RELEASE_BODY_MAX_CHARS,
+}) {
+  const ver = String(version || '').replace(/^v/, '');
+  if (!VERSION_RE.test(ver)) {
+    throw new ChangelogNotesError(
+      CHANGELOG_NOTES_ERROR.INVALID_VERSION,
+      `invalid version "${version}" (expected X.Y.Z or X.Y.Z-prerelease)`,
+    );
+  }
+  if (previous !== null && previous !== undefined && !STRICT_TRIPLET_RE.test(String(previous))) {
+    throw new ChangelogNotesError(
+      CHANGELOG_NOTES_ERROR.INVALID_PREVIOUS,
+      `invalid --previous "${previous}" (expected a strict X.Y.Z triplet)`,
+    );
+  }
+
+  const text = String(changelog || '');
+  const { releases } = parseChangelog(text);
+  const lines = text.split(/\r?\n/);
+  // parseChangelog pushes exactly one release per heading line matched by
+  // RELEASE_HEADING_RE, so heading line i belongs to releases[i].
+  const headingLines = [];
+  lines.forEach((line, idx) => {
+    if (RELEASE_HEADING_RE.test(line)) headingLines.push(idx);
+  });
+
+  const relIdx = releases.findIndex((r) => r.version === ver);
+  if (relIdx === -1) {
+    throw new ChangelogNotesError(
+      CHANGELOG_NOTES_ERROR.NO_SECTION,
+      `CHANGELOG.md has no \`## [${ver}]\` section`,
+    );
+  }
+  const release = releases[relIdx];
+  if (!release.date) {
+    throw new ChangelogNotesError(
+      CHANGELOG_NOTES_ERROR.UNDATED_SECTION,
+      `CHANGELOG.md heading \`## [${ver}]\` has no date (expected \`## [${ver}] - YYYY-MM-DD\`)`,
+    );
+  }
+  const bulletCount = release.sections.reduce((n, s) => n + s.bullets.length, 0);
+  const endIdx = relIdx + 1 < headingLines.length ? headingLines[relIdx + 1] : lines.length;
+  const body = sliceBody(lines, headingLines[relIdx] + 1, endIdx);
+  // `render --allow-empty` writes a dated heading plus a placeholder for a
+  // zero-fragment release; that is a valid (if sparse) section.
+  if (bulletCount === 0 && body !== EMPTY_RELEASE_PLACEHOLDER) {
+    throw new ChangelogNotesError(
+      CHANGELOG_NOTES_ERROR.EMPTY_SECTION,
+      `CHANGELOG.md section \`## [${ver}]\` has no bullets`,
+    );
+  }
+
+  let prev = previous === null || previous === undefined ? null : String(previous);
+  if (prev === null) {
+    const earlier = releases
+      .slice(relIdx + 1)
+      .find((r) => r.date && isStableTripletSemver(r.version));
+    if (!earlier) {
+      throw new ChangelogNotesError(
+        CHANGELOG_NOTES_ERROR.NO_PREVIOUS,
+        `CHANGELOG.md has no dated X.Y.Z section below \`## [${ver}]\`; pass --previous <X.Y.Z>`,
+      );
+    }
+    prev = earlier.version;
+  }
+
+  const install = [
+    '## Install',
+    '',
+    '```bash',
+    `npm i ${packageName}@${ver}`,
+    '# or',
+    `npm i ${packageName}@latest`,
+    '```',
+  ].join('\n');
+  const footer = `**Full Changelog**: https://github.com/${repoSlug}/compare/v${prev}...v${ver}`;
+  const changelogUrl = `https://github.com/${repoSlug}/blob/v${ver}/CHANGELOG.md`;
+  const assemble = (bodyText, dropped) => {
+    // An empty body (nothing fit) leaves just the heading, never a blank run.
+    const parts = [install, bodyText ? `## What's Changed\n\n${bodyText}` : "## What's Changed"];
+    if (dropped > 0) {
+      const noun = dropped === 1 ? 'entry' : 'entries';
+      parts.push(`_\u2026and ${dropped} more ${noun}. See the full [CHANGELOG](${changelogUrl})._`);
+    }
+    parts.push(footer);
+    return parts.join('\n\n') + '\n';
+  };
+
+  const full = assemble(body, 0);
+  if (full.length <= maxChars) return full;
+
+  // Over budget: keep whole units (headings, bullets with continuations) in
+  // order until the next one would not fit alongside the notice and footer.
+  const units = splitUnits(body);
+  let remaining = units.filter((u) => u.kind === 'bullet').length;
+  // The smallest possible body carries no entries at all; if even that is over
+  // budget no truncation can help, so fail instead of returning an oversized body.
+  const floor = assemble('', remaining).length;
+  if (floor > maxChars) {
+    throw new ChangelogNotesError(
+      CHANGELOG_NOTES_ERROR.BUDGET_TOO_SMALL,
+      `release body budget ${maxChars} is below the ${floor}-character floor (install block, notice and footer)`,
+    );
+  }
+  const kept = [];
+  for (const unit of units) {
+    const after = remaining - (unit.kind === 'bullet' ? 1 : 0);
+    const candidate = [...kept, unit].map((u) => u.lines.join('\n')).join('\n').replace(/\s+$/, '');
+    if (assemble(candidate, after).length > maxChars) break;
+    kept.push(unit);
+    remaining = after;
+  }
+  // Never leave a heading with no entries under it.
+  while (kept.length > 0 && kept[kept.length - 1].kind === 'heading') kept.pop();
+  const keptBullets = kept.filter((u) => u.kind === 'bullet').length;
+  const dropped = units.filter((u) => u.kind === 'bullet').length - keptBullets;
+  const keptBody = kept.map((u) => u.lines.join('\n')).join('\n').replace(/\s+$/, '');
+  return assemble(keptBody, dropped);
+}
+
+/**
+ * Resolve `--output` and require it to sit under the working directory, the OS
+ * temp directory or RUNNER_TEMP (symlinks resolved on the parent directory).
+ * An existing symlink as the final component is refused outright.
+ * @returns {string} Absolute path to write.
+ * @throws {ChangelogNotesError}
+ */
+function resolveOutputPath(output, { cwd = process.cwd(), tmpdir = os.tmpdir(), runnerTemp = process.env.RUNNER_TEMP } = {}) {
+  const abs = path.resolve(cwd, output);
+  let realParent;
+  try {
+    realParent = fs.realpathSync(path.dirname(abs));
+  } catch (_e) {
+    throw new ChangelogNotesError(CHANGELOG_NOTES_ERROR.OUTPUT_NOT_ALLOWED, `--output directory does not exist: ${path.dirname(abs)}`);
+  }
+  const target = path.join(realParent, path.basename(abs));
+  for (const root of [cwd, tmpdir, runnerTemp]) {
+    if (!root) continue;
+    let realRoot;
+    try {
+      realRoot = fs.realpathSync(root);
+    } catch (_e) {
+      continue;
+    }
+    if (target.startsWith(realRoot.endsWith(path.sep) ? realRoot : realRoot + path.sep)) {
+      let st = null;
+      try {
+        st = fs.lstatSync(target);
+      } catch (_e) {
+        st = null; // does not exist yet
+      }
+      if (st && st.isSymbolicLink()) {
+        throw new ChangelogNotesError(CHANGELOG_NOTES_ERROR.OUTPUT_NOT_ALLOWED, `--output ${output} is a symbolic link`);
+      }
+      return target;
+    }
+  }
+  throw new ChangelogNotesError(
+    CHANGELOG_NOTES_ERROR.OUTPUT_NOT_ALLOWED,
+    `--output ${output} is outside the working directory, the temp directory and RUNNER_TEMP`,
+  );
+}
+
+/**
+ * Write the body without following a symlink at the final path component.
+ * O_NOFOLLOW (where defined) closes the window between resolveOutputPath's
+ * lstat and the open; ELOOP is mapped to a typed error.
+ * @throws {ChangelogNotesError}
+ */
+function writeOutput(target, body) {
+  const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC | (fs.constants.O_NOFOLLOW || 0);
+  let fd;
+  try {
+    fd = fs.openSync(target, flags, 0o644);
+  } catch (err) {
+    if (err && err.code === 'ELOOP') {
+      throw new ChangelogNotesError(CHANGELOG_NOTES_ERROR.OUTPUT_NOT_ALLOWED, `--output ${target} is a symbolic link`);
+    }
+    throw err;
+  }
+  try {
+    fs.writeFileSync(fd, body, 'utf8');
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+const FLAGS_WITH_VALUE = new Set([
+  '--version', '--tag', '--changelog', '--output', '--package', '--repo', '--previous',
+]);
+
+function parseArgs(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!FLAGS_WITH_VALUE.has(arg)) throw new ExitError(2, `error: unknown argument ${arg}`);
+    const value = argv[++i];
+    if (value === undefined || value === '' || value.startsWith('--')) {
+      throw new ExitError(2, `error: ${arg} requires a value`);
+    }
+    opts[arg.slice(2)] = value;
+  }
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const version = opts.version || opts.tag;
+  if (!version) throw new ExitError(2, 'error: --version <X.Y.Z> is required');
+  if (!opts.output) throw new ExitError(2, 'error: --output <file> is required');
+
+  const changelogPath = path.resolve(opts.changelog || path.join(__dirname, '..', '..', 'CHANGELOG.md'));
+  if (!fs.existsSync(changelogPath)) {
+    throw new ExitError(1, `error: CHANGELOG not found: ${changelogPath}`);
+  }
+
+  let body;
+  let outputPath;
+  try {
+    outputPath = resolveOutputPath(opts.output);
+    body = buildChangelogReleaseNotes({
+      changelog: fs.readFileSync(changelogPath, 'utf8'),
+      version,
+      packageName: opts.package || defaultPackageName,
+      repoSlug: opts.repo || defaultRepoSlug,
+      previous: opts.previous === undefined ? null : opts.previous,
+    });
+    writeOutput(outputPath, body);
+  } catch (err) {
+    if (err instanceof ChangelogNotesError) {
+      throw new ExitError(1, `error[${err.code}]: ${err.message}`);
+    }
+    throw err;
+  }
+}
+
+if (require.main === module) {
+  runMain(main);
+}
+
+module.exports = {
+  buildChangelogReleaseNotes,
+  ChangelogNotesError,
+  CHANGELOG_NOTES_ERROR,
+  RELEASE_BODY_MAX_CHARS,
+  resolveOutputPath,
+  writeOutput,
+  parseArgs,
+};