msd-core/scripts/changeset/cli.cjs

#!/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 { 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');
const {
  compareSemverCore,
  isStableTripletSemver,
} = require('../../gsd-core/bin/lib/semver-compare.cjs');
const { packageName, repoSlug: defaultRepoSlug } = require('../../gsd-core/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,
    allowEmpty: false,
    preview: 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 === '--allow-empty') { opts.allowEmpty = true; continue; }
    if (a === '--preview') { opts.preview = 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 };
}

// 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');
}

// Insert a "_No notable changes._" placeholder after the dated release heading
// of an otherwise-empty release block. serializeChangelog with no sections
// yields just "## [v] - d\n"; we expand the trailing newline into a blank line
// + placeholder + blank line so parseChangelog still sees the dated heading
// first and the output is human-readable. Shared by the --allow-empty and
// --preview zero-fragment paths so they can never drift.
function injectEmptyPlaceholder(headerOnlyBlock) {
  return headerOnlyBlock.replace(
    /^(##\s+\[[^\]]+\][^\n]*)\n+/,
    '$1\n\n_No notable changes._\n\n',
  );
}

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 });
  }

  // 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') : '';

  // Preview mode (#759): render the dated release section WITHOUT writing
  // CHANGELOG.md and WITHOUT consuming .changeset fragments. Used by the rc
  // release job to surface the curated notes for the version under test while
  // leaving the fragment set intact for the eventual finalize render.
  if (opts.preview) {
    // priorChangelog is intentionally null: a preview shows ONLY the new dated
    // section for the version under test, not the full file history.
    // serializeChangelog appends priorChangelog verbatim, so passing the prior
    // text here would dump every past release into the rc job summary.
    const ir = renderChangelog({
      fragments,
      version: opts.version,
      date: opts.date,
      priorChangelog: null,
    });
    let releaseBlock = serializeChangelog(ir);
    if (fragments.length === 0) {
      // Mirror --allow-empty: a no-fragment release still shows a dated heading
      // with a placeholder rather than an empty block.
      releaseBlock = injectEmptyPlaceholder(releaseBlock);
    }
    return {
      exitCode: 0,
      report: {
        consumed: 0,
        failures: [],
        preview: releaseBlock,
        fragmentCount: fragments.length,
      },
    };
  }

  // 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) {
    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);
    const releaseBlock = injectEmptyPlaceholder(headerOnlyBlock);
    // 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 },
      },
    };
  }

  // 5. Normal render path: fragments present — reuse priorText already read above.
  const { lead, prior } = splitChangelog(priorText);

  const ir = renderChangelog({
    fragments,
    version: opts.version,
    date: opts.date,
    priorChangelog: prior || null,
  });
  const releaseBlock = serializeChangelog(ir);
  // FIX 2: use shared assembleChangelog helper.
  const out = assembleChangelog(lead, releaseBlock);

  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 },
    },
  };
}

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
 * 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 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 = resolveChangelogPath(opts);

  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 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({
    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 [--allow-empty] [--preview] [--json]',
    '    --preview renders the dated section to stdout without writing CHANGELOG.md or consuming fragments.',
    '  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');
}

function main() {
  const parsed = parseArgs(process.argv.slice(2));
  if (!parsed.ok) {
    process.stderr.write(`${parsed.error}\n`);
    process.stderr.write(usage());
    throw new ExitError(2);
  }
  const { opts } = parsed;
  if (opts.cmd !== 'render' && opts.cmd !== 'github-release-notes' && opts.cmd !== 'extract' && opts.cmd !== 'verify') {
    process.stderr.write(usage());
    throw new ExitError(1);
  }
  if (opts.cmd === 'render' && (!opts.version || !opts.date)) {
    throw new ExitError(2, '--version and --date are required for render');
  }
  if (opts.cmd === 'github-release-notes' && (!opts.fromRef || !opts.toRef)) {
    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());
    throw new ExitError(1);
  }
  if (opts.cmd === 'verify' && !opts.version) {
    throw new ExitError(2, '--version is required for verify');
  }

  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`);
    }
    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);
  if (opts.json) {
    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
  } else if (opts.cmd === 'render' && opts.preview) {
    // render --preview: emit the rendered section verbatim (no mutation occurred).
    process.stdout.write(report.preview);
  } 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`);
      for (const f of report.failures) {
        process.stdout.write(`  ${f.file}: ${f.reason}${f.detail ? ` (${f.detail})` : ''}\n`);
      }
    }
  }
  return exitCode;
}

if (require.main === module) runMain(main);

module.exports = { cmdRender, cmdExtract, cmdVerify, cmdGithubReleaseNotes, parseArgs, splitChangelog, assembleChangelog, listFragmentFiles, usage };