fix(#1006): rc CHANGELOG preview crash on malformed changeset fragment + validate fragment content at the gate (#1007)

* fix(#1006): harden render --preview against fragment parse failures

`render --preview` wrote `report.preview` unconditionally. When a `.changeset`
fragment fails to parse, `cmdRender` early-returns with `{exitCode:1, report:
{failures}}` and NO `preview` key, so `process.stdout.write(undefined)` threw
ERR_INVALID_ARG_TYPE and the rc release job's "Preview CHANGELOG" step died with
a cryptic TypeError that masked the real cause.

Guard the preview write on `typeof report.preview === 'string'` (ADR-227: shape,
not just type); when absent, fall through to the existing failure reporter that
names the offending fragment and exits non-zero — identical to a non-preview
render. Also backfills the stray placeholder `pr: 0` -> `pr: 939` in
.changeset/936-convergence-inline-plan-phase.md that triggered the live failure.

Regression test (red-then-green verified) added at the render --preview seam.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#1006): validate changeset fragment content at the Changeset Required gate

The `Changeset Required` gate (scripts/changeset/lint.cjs) only checked that a
`.changeset/*.md` fragment EXISTS in the PR diff; it never validated the
fragment's contents. So a malformed fragment (e.g. an un-backfilled `pr: 0`
placeholder) silently merged to `next` and only detonated later in the rc
release job. This is the upstream prevention for #1006 — the crash hardening
turns the failure into a clear message, this stops the bad fragment ever
reaching the release path.

evaluateLint now accepts `fragmentFailures` and fails with the typed reason
`fail_invalid_fragment` (naming each offending file) before the existence/
opt-out checks — a malformed fragment beats `no-changelog`, since it will break
the render regardless. main() reads + parseFragment()s every changed fragment:
a deleted fragment (not on disk) is skipped, a present-but-unreadable one fails
closed. Tests assert on the typed LINT_REASON enum (no raw-text matching), a
precedence case over the opt-out label, and an end-to-end suite that drives the
real main() against a temp git repo (malformed -> fail, valid -> pass, deleted
-> skipped) so the wiring is regression-proof.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* test(#1006): assert the typed --json report in the preview regression test

Code review flagged the preview parse-failure regression test for positive
raw-text matching on CLI output (`combined.includes('bad-fragment.md')` /
`'invalid_pr'`), which this repo's testing standards forbid. Keep the non-json
`runRenderRaw` call for the negative crash proof (the ERR_INVALID_ARG_TYPE
crash lives only on the non-json stdout.write path), and add a `--json`
invocation that asserts the offending fragment + typed `invalid_pr` reason via
the structured `report.failures[]` surface instead of rendered prose.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

scripts/changeset/cli.cjs

@@ -565,8 +565,15 @@ function main() {
   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) {
+  } else if (opts.cmd === 'render' && opts.preview && typeof report.preview === 'string') {
     // render --preview: emit the rendered section verbatim (no mutation occurred).
+    // The `typeof report.preview === 'string'` guard is load-bearing: cmdRender
+    // early-returns on a fragment parse failure (failures.length > 0) WITHOUT a
+    // `preview` key, so writing report.preview unguarded crashed the rc release
+    // job with ERR_INVALID_ARG_TYPE, masking the real cause (a malformed
+    // fragment). When preview is absent we fall through to the failure reporter
+    // below, which names the offending file and exits non-zero — identical to a
+    // non-preview render.
     process.stdout.write(report.preview);
   } else if (opts.cmd === 'github-release-notes' && report.body) {
     process.stdout.write(report.body);

scripts/changeset/lint.cjs

@@ -17,6 +17,7 @@ const LINT_REASON = Object.freeze({
   OK_OPT_OUT_LABEL: 'ok_opt_out_label',
   OK_NO_USER_FACING_CHANGES: 'ok_no_user_facing_changes',
   FAIL_MISSING_FRAGMENT: 'fail_missing_fragment',
+  FAIL_INVALID_FRAGMENT: 'fail_invalid_fragment',
 });
 
 const OPT_OUT_LABEL = 'no-changelog';
@@ -47,7 +48,10 @@ function isFragment(file) {
   return /^\.changeset\/[^/]+\.md$/.test(file) && !file.endsWith('/README.md');
 }
 
-function evaluateLint({ changedFiles, labels }) {
+function evaluateLint({ changedFiles, labels, fragmentFailures = [] }) {
+  if (fragmentFailures.length > 0) {
+    return { ok: false, reason: LINT_REASON.FAIL_INVALID_FRAGMENT, failures: fragmentFailures };
+  }
   if (changedFiles.some(isFragment)) {
     return { ok: true, reason: LINT_REASON.OK_FRAGMENT_PRESENT };
   }
@@ -61,6 +65,7 @@ function evaluateLint({ changedFiles, labels }) {
 }
 
 const { ExitError, runMain } = require('../lib/cli-exit.cjs');
+const { parseFragment } = require('./parse.cjs');
 
 function main() {
   const fs = require('node:fs');
@@ -92,11 +97,42 @@ function main() {
     throw new ExitError(2, `could not compute diff: ${e.message}`);
   }
 
-  const verdict = evaluateLint({ changedFiles, labels });
+  // Validate the content of every changed fragment file.
+  const fragmentFailures = [];
+  for (const file of changedFiles) {
+    if (!isFragment(file)) continue;
+    // A fragment path in the diff that no longer exists on disk was deleted in
+    // this PR — a deletion can't be malformed, so skip it.
+    if (!fs.existsSync(file)) continue;
+    let src;
+    try {
+      src = fs.readFileSync(file, 'utf8');
+    } catch (e) {
+      // Present in the diff but unreadable (broken symlink, permissions). A
+      // changed fragment we cannot read is suspect — fail closed rather than
+      // letting it slip through to the release-time CHANGELOG render.
+      fragmentFailures.push({ file, reason: 'unreadable', detail: e.code || 'read_error' });
+      continue;
+    }
+    const result = parseFragment(src);
+    if (!result.ok) {
+      fragmentFailures.push({ file, reason: result.reason, detail: result.detail });
+    }
+  }
+
+  const verdict = evaluateLint({ changedFiles, labels, fragmentFailures });
   if (process.argv.includes('--json')) {
     process.stdout.write(JSON.stringify({ ...verdict, changedFiles, labels }, null, 2) + '\n');
   } else if (verdict.ok) {
     process.stdout.write(`ok changeset-lint: ${verdict.reason}\n`);
+  } else if (verdict.reason === LINT_REASON.FAIL_INVALID_FRAGMENT) {
+    process.stderr.write(`\nERROR changeset-lint: ${verdict.reason}\n`);
+    process.stderr.write(`The following .changeset fragment(s) failed content validation:\n`);
+    for (const f of verdict.failures) {
+      const detail = f.detail !== undefined ? ` (${f.detail})` : '';
+      process.stderr.write(`  ${f.file}: ${f.reason}${detail}\n`);
+    }
+    process.stderr.write(`Fix the fragment(s) above before merging.\n`);
   } else {
     process.stderr.write(`\nERROR changeset-lint: ${verdict.reason}\n`);
     process.stderr.write(`PR touches user-facing files but does not include a .changeset/*.md fragment.\n`);