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>

tests/changeset-cli.test.cjs

@@ -1073,4 +1073,42 @@ describe('changeset cli render --preview (#759)', () => {
       'CHANGELOG.md must be byte-identical after --preview',
     );
   });
+
+  // Regression (#939 / rc-job crash): a fragment that fails to parse (e.g. an
+  // un-backfilled `pr: 0` placeholder) makes cmdRender early-return WITHOUT a
+  // `preview` key. Before the fix, main() wrote report.preview unguarded, so
+  // `process.stdout.write(undefined)` threw ERR_INVALID_ARG_TYPE and the rc
+  // "Preview CHANGELOG" step died with a cryptic TypeError that masked the real
+  // cause. The preview failure path must now exit non-zero and NAME the bad
+  // fragment, identical to a non-preview render.
+  test('render --preview with an unparseable fragment fails cleanly (names the file, no TypeError crash)', () => {
+    // pr: 0 is the never-backfilled placeholder → parseFragment returns invalid_pr.
+    writeFragment('bad-fragment', 'Fixed', 0, '**Bad** — placeholder never backfilled. (#123)');
+
+    // The crash lived on the NON-json path: process.stdout.write(report.preview)
+    // with report.preview === undefined. Exercise it directly and assert it no
+    // longer crashes — non-zero exit and NO TypeError stack in the output (QA
+    // matrix: "No stack trace in non-debug failure output").
+    const raw = runRenderRaw(['--version', '9.9.0', '--date', '2026-01-02', '--preview']);
+    assert.notStrictEqual(raw.status, 0, `parse-failure preview must exit non-zero; stdout=${raw.stdout} stderr=${raw.stderr}`);
+    const combined = `${raw.stdout}\n${raw.stderr}`;
+    assert.ok(
+      !combined.includes('ERR_INVALID_ARG_TYPE'),
+      `preview must NOT crash with ERR_INVALID_ARG_TYPE; got: ${combined}`,
+    );
+
+    // Structured surface (--json) proves the failure NAMES the offending fragment
+    // and reports the typed parse reason — asserted on the typed report shape,
+    // not on rendered prose.
+    const json = runRender(['--version', '9.9.0', '--date', '2026-01-02', '--preview']);
+    assert.notStrictEqual(json.status, 0, 'json preview must also exit non-zero on parse failure');
+    assert.ok(Array.isArray(json.report.failures), `report.failures must be an array; got: ${JSON.stringify(json.report)}`);
+    const bad = json.report.failures.find((f) => f.file.endsWith('bad-fragment.md'));
+    assert.ok(bad, `failures must name the offending fragment; got: ${JSON.stringify(json.report.failures)}`);
+    assert.equal(bad.reason, 'invalid_pr', `failure reason must be the typed invalid_pr; got: ${bad && bad.reason}`);
+
+    // Still non-destructive: no CHANGELOG.md written, fragment left in place.
+    assert.ok(!fs.existsSync(path.join(tmp, 'CHANGELOG.md')), 'CHANGELOG.md must NOT be created by a failed preview');
+    assert.ok(fs.existsSync(path.join(tmp, '.changeset', 'bad-fragment.md')), 'fragment must still exist after failed preview');
+  });
 });