Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Render stable release notes from the stable tag's changesets (PRD-9389) (#6400)
Andrew Mikofalvy97a5a8879cac
diff --git a/.github/scripts/point-release-plan.mjs b/.github/scripts/point-release-plan.mjsindex a9f77c927..559bde7a3 100644--- a/.github/scripts/point-release-plan.mjs+++ b/.github/scripts/point-release-plan.mjs@@ -13,6 +13,14 @@ import {serializeBumpVerdicts,withBumpVerdicts,} from '../../scripts/compute-stable-version.mjs';+import {+ noteReaderAt,+ parseNoteLevels,+ recordNoteLevels,+ serializeNoteLevels,+ stableNotes,+ withNoteLevels,+} from '../../scripts/render-stable-notes.mjs';import {describeNoSelection,listPrebuildRuns,@@ -437,20 +445,31 @@ export const pushTagArgs = (tag) => [tag,];-export function readFixBumps({ mode, fixRefs }, git) {- const verdicts = new Map();- if (mode === 'revert') return verdicts;- const reading = recordBumpVerdicts(git, verdicts);+function forEachFixChangeset({ mode, fixRefs }, git, visit) {+ if (mode === 'revert') return;for (const ref of fixRefs) {const sha = git.revParse(ref);const before = git.changesetBlobs(`${sha}^`);for (const [id, blob] of git.changesetBlobs(sha)) {- if (before.get(id) !== blob) reading.bumpTypeOf(sha, id);+ if (before.get(id) !== blob) visit(sha, id);}}+}++export function readFixBumps(opts, git) {+ const verdicts = new Map();+ const reading = recordBumpVerdicts(git, verdicts);+ forEachFixChangeset(opts, git, (sha, id) => reading.bumpTypeOf(sha, id));return verdicts;}+export function readFixNoteLevels(opts, git) {+ const levels = new Map();+ const reading = recordNoteLevels(git, levels);+ forEachFixChangeset(opts, git, (sha, id) => reading.noteLevelOf(sha, id));+ return levels;+}+export class PointReleaseRefusal extends Error {constructor(code, message) {super(message);@@ -583,7 +602,8 @@ export function runPointRelease(opts, io) {guards,warnings,};- plan.releaseNotes = formatReleaseNotes(plan);+ plan.releaseNotes =+ mode === 'cherry-pick' ? renderedReleaseNotes(plan, io, warnings) : formatReleaseNotes(plan);if (dryRun) return plan;@@ -746,13 +766,38 @@ function decideMainReset({ anchorDeltaIds, addedIds, bridgeConfigured, guards, wreturn { dispatch: true, deltaIds, skipReason: null };}-export function formatReleaseNotes(plan) {- const lines = [+function provenanceLines(plan) {+ return [`Point release over ${plan.latestStableTag}: the current stable plus ${plan.fixRefs.length} applied ` +`commit(s), isolated from the changes still soaking on main.`,'',`Applied: ${plan.fixRefs.map((r) => (r.ref === r.sha ? r.sha : `${r.ref} (${r.sha})`)).join(', ')}`,];+}++function renderedReleaseNotes(plan, io, warnings) {+ let notes;+ try {+ notes = stableNotes(+ {+ commit: plan.syntheticSha,+ excludeTags: [plan.tag],+ publishedTags: io.containment.publishedStableTags(),+ },+ io.git,+ );+ } catch (err) {+ warnings.push(+ `The release notes could not be rendered from the changesets (${messageOf(err)}), so the body quotes ` ++ `them instead and carries no notes-source marker; the docs changelog keeps CHANGELOG.md for ${plan.tag}.`,+ );+ return formatReleaseNotes(plan);+ }+ return `${notes}\n${provenanceLines(plan).join('\n')}\n`;+}++export function formatReleaseNotes(plan) {+ const lines = provenanceLines(plan);const entries = plan.changesetEntries ?? [];const quoted = entries.filter((e) => e.body);const unquoted = entries.filter((e) => !e.body);@@ -777,7 +822,7 @@ export function realIo() {writeWorktreeFile: (path, content) => writeFileSync(path, content),},git: {- ...realGit,+ ...noteReaderAt(),isOnMain: (ref) => realGit.isAncestor(ref, 'origin/main'),tagExists: (tag) => {const res = spawnSync('git', ['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`], { encoding: 'utf8' });@@ -858,16 +903,33 @@ function log(...args) {}function readBumpsMain() {+ let opts;+ let reader;let verdicts;try {- verdicts = readFixBumps({ mode: process.env.MODE, fixRefs: parseFixRefs(process.env.FIX_REFS) }, realGit);+ opts = { mode: process.env.MODE, fixRefs: parseFixRefs(process.env.FIX_REFS) };+ reader = noteReaderAt();+ verdicts = readFixBumps(opts, reader);} catch (err) {console.error(`::error::point-release-plan --read-bumps: ${messageOf(err)}`);process.exit(1);}+ let levels;+ try {+ levels = readFixNoteLevels(opts, reader);+ } catch (err) {+ levels = new Map();+ console.log(+ `::warning::point-release-plan --read-bumps: the release-note level of a changeset could not be read ` ++ `(${messageOf(err)}), so the release body will quote the changesets without the notes-source marker.`,+ );+ }log(`Read the bump of ${verdicts.size} changeset(s) written by ${process.env.MODE} refs ${process.env.FIX_REFS}.`);if (process.env.GITHUB_OUTPUT) {- appendFileSync(process.env.GITHUB_OUTPUT, `bump_verdicts=${serializeBumpVerdicts(verdicts)}\n`);+ appendFileSync(+ process.env.GITHUB_OUTPUT,+ `bump_verdicts=${serializeBumpVerdicts(verdicts)}\nnote_levels=${serializeNoteLevels(levels)}\n`,+ );}}@@ -885,6 +947,9 @@ function main() {if (process.env.BUMP_VERDICTS !== undefined) {io.git = withBumpVerdicts(io.git, parseBumpVerdicts(process.env.BUMP_VERDICTS));}+ if (process.env.NOTE_LEVELS !== undefined) {+ io.git = withNoteLevels(io.git, parseNoteLevels(process.env.NOTE_LEVELS));+ }plan = runPointRelease({mode: process.env.MODE,diff --git a/.github/scripts/point-release-plan.test.mjs b/.github/scripts/point-release-plan.test.mjsindex 764aeedcd..6b1e916aa 100644--- a/.github/scripts/point-release-plan.test.mjs+++ b/.github/scripts/point-release-plan.test.mjs@@ -7,6 +7,7 @@ import { Project, ts } from 'ts-morph';import { afterEach, describe, expect, test } from 'vitest';import { gitAt, withBumpVerdicts } from '../../scripts/compute-stable-version.mjs';import { gitCleanEnv } from '../../scripts/git-clean-env.mjs';+import { NOTES_SOURCE_MARKER, withNoteLevels } from '../../scripts/render-stable-notes.mjs';import {APP_CREDENTIAL_HELPER,deriveEntryLevelResolution,@@ -26,6 +27,7 @@ import {pushTagArgs,RESOLVABLE_PATHS,readFixBumps,+ readFixNoteLevels,realIo,runPointRelease,verifyWorkspaceMatchesLockfile,@@ -610,6 +612,7 @@ function makeIo(overrides = {}) {existingTags = ['v0.32.0'],changesets = { 'stable-sha': ['keep-a'], 'synthetic-sha': ['keep-a'] },bumpTypes = {},+ noteLevels = {},changesetContents = {},nativeConfigSelection = { headSha: 'prebuild-sha', reason: '' },ancestries = [['prebuild-sha', 'synthetic-sha']],@@ -669,13 +672,21 @@ function makeIo(overrides = {}) {isOnMain: (ref) => onMain.includes(ref),tagExists: (t) => existingTags.includes(t),isAncestor: (a, b) => ancestries.some(([x, y]) => x === a && y === b),- changesetIds: (sha) => changesets[sha] ?? [],+ changesetIds: (sha) =>+ changesets[sha] ?? changesets[sha === stableTag ? 'stable-sha' : sha] ?? [],+ stableTags: () => existingTags.filter((t) => /^v\d+\.\d+\.\d+$/.test(t)),bumpTypeOf: (_sha, id) => bumpTypes[id] ?? 'patch',+ noteLevelOf: (_sha, id) => (id in noteLevels ? noteLevels[id] : 'patch'),changesetContent: (_sha, id) => {const content = changesetContents[id];if (content === undefined) throw new Error(`no changeset content for ${id}`);return content;},+ changesetText: (_sha, id) => {+ const content = changesetContents[id];+ if (content === undefined) throw new Error(`no changeset content for ${id}`);+ return content;+ },checkoutDetached: (sha) => checkedOut.push(sha),cherryPick: cherryPick ?? ((ref) => applied.push(['cherry-pick', ref])),revert: revert ?? ((ref) => applied.push(['revert', ref])),@@ -922,6 +933,92 @@ describe('runPointRelease cascade', () => {expect(io.calls).toEqual({ tag: 0, pushTag: 0, createRelease: 0, dispatch: 0 });});+ const shinyFix = (overrides = {}) =>+ makeIo({+ changesets: {+ 'stable-sha': ['keep-a'],+ 'synthetic-sha': ['keep-a', 'shiny-fix'],+ fix1: ['keep-a', 'shiny-fix'],+ 'fix1^': ['keep-a'],+ },+ changesetContents: {+ 'shiny-fix':+ '---\n"@inkeep/open-knowledge": patch\n---\n\nChips no longer balloon into ovals.\n',+ },+ ...overrides,+ });++ test('a cherry-pick body is the stable notes renderer output, marker and all, with the provenance after it', () => {+ const io = shinyFix();+ runPointRelease({ mode: 'cherry-pick', fixRefs: ['fix1'], dryRun: false }, io);+ const notes = io.releases[0].notes;+ const [rendered, provenance] = notes.split(`${NOTES_SOURCE_MARKER}\n`);+ expect(rendered).toBe('### Patch Changes\n\n- Chips no longer balloon into ovals.\n\n');+ expect(provenance).toMatch(+ /^\nPoint release over v0\.32\.0: the current stable plus 1 applied commit\(s\)/,+ );+ expect(provenance).toContain('\nApplied: fix1 (fix1-sha)\n');+ });++ test('a changeset some older published stable already shipped is not listed again', () => {+ const io = shinyFix({+ existingTags: ['v0.31.0', 'v0.32.0'],+ publishedTags: ['v0.31.0', 'v0.32.0'],+ changesets: {+ 'v0.31.0': ['keep-a', 'shiny-fix'],+ 'stable-sha': ['keep-a'],+ 'synthetic-sha': ['keep-a', 'shiny-fix'],+ fix1: ['keep-a', 'shiny-fix'],+ 'fix1^': ['keep-a'],+ },+ });+ const plan = runPointRelease({ mode: 'cherry-pick', fixRefs: ['fix1'], dryRun: true }, io);+ expect(plan.releaseNotes).toMatch(/^No changelog entries\.\n\nPoint release over v0\.32\.0/);+ expect(plan.releaseNotes).not.toContain(NOTES_SOURCE_MARKER);+ });++ test('a changeset only an unpublished stable tag carries is still listed', () => {+ const io = shinyFix({+ existingTags: ['v0.31.0', 'v0.32.0'],+ publishedTags: ['v0.32.0'],+ changesets: {+ 'v0.31.0': ['keep-a', 'shiny-fix'],+ 'stable-sha': ['keep-a'],+ 'synthetic-sha': ['keep-a', 'shiny-fix'],+ fix1: ['keep-a', 'shiny-fix'],+ 'fix1^': ['keep-a'],+ },+ });+ const plan = runPointRelease({ mode: 'cherry-pick', fixRefs: ['fix1'], dryRun: true }, io);+ expect(plan.releaseNotes).toMatch(/^### Patch Changes\n\n- Chips no longer balloon into ovals\./);+ expect(plan.releaseNotes).toContain(NOTES_SOURCE_MARKER);+ });++ test('a revert body carries no notes-source marker, so the docs keep CHANGELOG.md for it', () => {+ const io = makeIo();+ runPointRelease({ mode: 'revert', fixRefs: ['bad1'], dryRun: false }, io);+ expect(io.releases[0].notes).not.toContain('ok-notes-source');+ });++ test('notes that cannot render fall back to the unmarked quoted form with a warning, never a refusal', () => {+ const io = shinyFix();+ io.git = withNoteLevels(+ {+ ...io.git,+ changesetBlobs: (sha) =>+ new Map((io.git.changesetIds(sha) ?? []).map((id) => [id, `blob-${id}`])),+ },+ new Map(),+ );+ const plan = runPointRelease({ mode: 'cherry-pick', fixRefs: ['fix1'], dryRun: false }, io);+ expect(io.calls.createRelease).toBe(1);+ expect(io.releases[0].notes).not.toContain('ok-notes-source');+ expect(io.releases[0].notes).toContain('- Chips no longer balloon into ovals.');+ expect(plan.warnings.some((w) => /no note level for \.changeset\/shiny-fix\.md/.test(w))).toBe(+ true,+ );+ });+test('revert with no named delta skips main-reset and names both follow-ups', () => {const io = makeIo();const plan = runPointRelease({ mode: 'revert', fixRefs: ['bad1'], dryRun: false }, io);@@ -1737,6 +1834,32 @@ describe('readFixBumps, run by the job that holds no release credential', () =>});});+describe('readFixNoteLevels, run beside readFixBumps in the reader job', () => {+ test('records the note level of each changeset blob a fix ref writes, and nothing for a revert', () => {+ const reads = [];+ const git = {+ revParse: (ref) => `${ref}-sha`,+ changesetBlobs: (sha) =>+ new Map(+ Object.entries(+ { 'fix1-sha^': { 'keep-a': 'b0' }, 'fix1-sha': { 'keep-a': 'b0', 'shiny-fix': 'b1' } }[+ sha+ ] ?? {},+ ),+ ),+ noteLevelOf: (sha, id) => {+ reads.push(`${sha}:${id}`);+ return 'patch';+ },+ };+ expect(readFixNoteLevels({ mode: 'cherry-pick', fixRefs: ['fix1'] }, git)).toEqual(+ new Map([['b1', 'patch']]),+ );+ expect(reads).toEqual(['fix1-sha:shiny-fix']);+ expect(readFixNoteLevels({ mode: 'revert', fixRefs: ['fix1'] }, git).size).toBe(0);+ });+});+describe('runPointRelease in the release job, which has no Changesets reader', () => {const cherryPickChangesets = {'stable-sha': ['keep-a'],@@ -1903,7 +2026,7 @@ describe('the production entry points the release workflows run', () => {if (res.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${res.stderr}`);return res.stdout.trim();};- const fixRepo = (fixBump) => {+ const fixRepo = (fixBump, { config = true } = {}) => {const root = scratch('point-release-read-bumps-');const changeset = (id, type) => {mkdirSync(join(root, '.changeset'), { recursive: true });@@ -1911,6 +2034,12 @@ describe('the production entry points the release workflows run', () => {};git(root, 'init', '-q', '-b', 'main');changeset('keep-a', 'patch');+ if (config) {+ writeFileSync(+ join(root, '.changeset', 'config.json'),+ JSON.stringify({ fixed: [['@inkeep/open-knowledge']] }),+ );+ }git(root, 'add', '-A');git(root, 'commit', '-q', '-m', 'stable');changeset('shiny-fix', fixBump);@@ -1956,24 +2085,32 @@ describe('the production entry points the release workflows run', () => {]);});- test('--read-bumps writes the bump of each changeset a fix ref writes, keyed by blob id', () => {+ test('--read-bumps writes the bump and note level of each changeset a fix ref writes, keyed by blob id', () => {const { root, fix, blob } = fixRepo('minor');const res = runScript(root, ['--read-bumps'], { MODE: 'cherry-pick', FIX_REFS: fix });expect(res.status, res.stderr).toBe(0);- expect(res.output).toBe(`bump_verdicts={"${blob}":"minor"}\n`);+ expect(res.output).toBe(`bump_verdicts={"${blob}":"minor"}\nnote_levels={"${blob}":"minor"}\n`);});test('--read-bumps writes {} in revert mode without reading frontmatter it could not parse', () => {const { root, fix } = fixRepo('Major');const revert = runScript(root, ['--read-bumps'], { MODE: 'revert', FIX_REFS: fix });expect(revert.status, revert.stderr).toBe(0);- expect(revert.output).toBe('bump_verdicts={}\n');+ expect(revert.output).toBe('bump_verdicts={}\nnote_levels={}\n');const cherryPick = runScript(root, ['--read-bumps'], { MODE: 'cherry-pick', FIX_REFS: fix });expect(cherryPick.status).toBe(1);expect(cherryPick.output).toBe('');});+ test('--read-bumps still writes the bumps when a note level cannot be read, with no levels and a warning', () => {+ const { root, fix, blob } = fixRepo('minor', { config: false });+ const res = runScript(root, ['--read-bumps'], { MODE: 'cherry-pick', FIX_REFS: fix });+ expect(res.status, res.stderr).toBe(0);+ expect(res.output).toBe(`bump_verdicts={"${blob}":"minor"}\nnote_levels={}\n`);+ expect(res.stdout).toMatch(/::warning::.*without the notes-source marker/);+ });+test('an empty BUMP_VERDICTS stops the release run with an error naming the read-bumps output', () => {const res = runScript(scratch('point-release-empty-verdicts-'), [], { BUMP_VERDICTS: '' });expect(res.status).toBe(1);diff --git a/.github/scripts/release-cascade-shape.test.mjs b/.github/scripts/release-cascade-shape.test.mjsindex 28f8b617b..ec15f7010 100644--- a/.github/scripts/release-cascade-shape.test.mjs+++ b/.github/scripts/release-cascade-shape.test.mjs@@ -7,6 +7,7 @@ import { dirname, join, resolve } from 'node:path';import { fileURLToPath } from 'node:url';import { afterAll, describe, expect, test } from 'vitest';import { parse } from 'yaml';+import { NOTES_SOURCE_MARKER, renderStableNotes } from '../../scripts/render-stable-notes.mjs';import { buildSlackPayload } from './build-smoke-alert-payload.mjs';import { execFileSync } from './child-tripwire.test-helper.mjs';import { selectPromotion } from './select-beta-to-promote.mjs';@@ -561,10 +562,11 @@ describe('the moved dispatch keeps the contract release.yml consumes', () => {});test('the dispatch is gated so beta cuts and manual re-runs never publish npm', () => {- const dispatch = desktopRelease.slice(- desktopRelease.indexOf('- name: Trigger release.yml to publish stable to npm'),- desktopRelease.indexOf('# The on-site changelog'),- );+ const start = desktopRelease.indexOf('- name: Trigger release.yml to publish stable to npm');+ const end = desktopRelease.indexOf('- name: Announce stable release to Slack');+ expect(start).toBeGreaterThan(-1);+ expect(end).toBeGreaterThan(start);+ const dispatch = desktopRelease.slice(start, end);expect(dispatch).toContain("needs.prepare.outputs.channel == 'latest'");expect(dispatch).toContain("github.event_name != 'workflow_dispatch'");});@@ -1573,18 +1575,24 @@ describe('every job that reads changesets installs the Changesets reader first',importsReader(resolve(dirname(file), spec), seen),);};- const VERDICT_MODE_SCRIPTS = new Set([- join(OK_ROOT, 'scripts', 'compute-stable-version.mjs'),- join(OK_ROOT, '.github', 'scripts', 'point-release-plan.mjs'),- join(OK_ROOT, '.github', 'scripts', 'bug-lane.mjs'),- join(OK_ROOT, '.github', 'scripts', 'select-beta-to-promote.mjs'),+ const VERDICT_MODE_SCRIPTS = new Map([+ [join(OK_ROOT, 'scripts', 'compute-stable-version.mjs'), ['BUMP_VERDICTS']],+ [join(OK_ROOT, 'scripts', 'render-stable-notes.mjs'), ['NOTE_LEVELS']],+ [+ join(OK_ROOT, '.github', 'scripts', 'point-release-plan.mjs'),+ ['BUMP_VERDICTS', 'NOTE_LEVELS'],+ ],+ [join(OK_ROOT, '.github', 'scripts', 'bug-lane.mjs'), ['BUMP_VERDICTS']],+ [join(OK_ROOT, '.github', 'scripts', 'select-beta-to-promote.mjs'), ['BUMP_VERDICTS']],]);const readsChangesets = (step) => {const readers = [...(step.run ?? '').matchAll(/[\w./-]+\.mjs\b/g)].map(([path]) => resolve(OK_ROOT, path)).filter((file) => importsReader(file));if (readers.length === 0) return false;- return step.env?.BUMP_VERDICTS === undefined || readers.some((file) => !VERDICT_MODE_SCRIPTS.has(file));+ return readers.some(+ (file) => !VERDICT_MODE_SCRIPTS.has(file) || VERDICT_MODE_SCRIPTS.get(file).some((name) => step.env?.[name] === undefined),+ );};const readerJobs = readdirSync(WORKFLOWS).filter((file) => file.endsWith('.yml'))@@ -1614,15 +1622,19 @@ describe('every job that reads changesets installs the Changesets reader first',expect(uninstalled).toEqual([]);});- test('BUMP_VERDICTS exempts only a script that implements verdict mode', () => {+ test('BUMP_VERDICTS and NOTE_LEVELS exempt only a script that implements verdict mode for every read it makes', () => {const env = { BUMP_VERDICTS: '${{ needs.read-bumps.outputs.bump_verdicts }}' };expect(readsChangesets({ env, run: 'node scripts/compute-stable-version.mjs "$BETA_TAG"' })).toBe(false);- expect(readsChangesets({ env, run: 'node .github/scripts/point-release-plan.mjs' })).toBe(false);+ expect(readsChangesets({ env, run: 'node .github/scripts/point-release-plan.mjs' })).toBe(true);expect(readsChangesets({ env, run: 'node scripts/compute-next-beta.mjs' })).toBe(true);expect(readsChangesets({ env, run: 'node scripts/compute-stable-version.mjs v1\nnode scripts/compute-next-beta.mjs' }),).toBe(true);expect(readsChangesets({ run: 'node scripts/compute-stable-version.mjs "$BETA_TAG"' })).toBe(true);+ const levels = { NOTE_LEVELS: '${{ needs.read-bumps.outputs.note_levels }}' };+ expect(readsChangesets({ env: levels, run: 'node scripts/render-stable-notes.mjs --commit "$SHA"' })).toBe(false);+ expect(readsChangesets({ env, run: 'node scripts/render-stable-notes.mjs --commit "$SHA"' })).toBe(true);+ expect(readsChangesets({ env: { ...env, ...levels }, run: 'node .github/scripts/point-release-plan.mjs' })).toBe(false);});});@@ -1689,6 +1701,7 @@ describe('the release App credential never shares a job with installed packages'const isSanctionedRead = (job, { path, expr }) => {if (path[0] !== 'steps' || path[2] !== 'env') return false;if (path[3] === 'BUMP_VERDICTS') return expr === 'needs.read-bumps.outputs.bump_verdicts';+ if (path[3] === 'NOTE_LEVELS') return expr === 'needs.read-bumps.outputs.note_levels';return (path[3] === 'READ_BUMPS_BETA_TAG' &&job.steps[path[1]]?.name === REFUSAL &&@@ -1870,6 +1883,9 @@ describe('the release App credential never shares a job with installed packages''BUMP_VERDICTS reading another output': withStep({env: { BUMP_VERDICTS: '${{ needs.read-bumps.outputs.beta_tag }}' },}),+ 'NOTE_LEVELS reading another output': withStep({+ env: { NOTE_LEVELS: '${{ needs.read-bumps.outputs.beta_tag }}' },+ }),'an action input named BUMP_VERDICTS': withStep({uses: './.github/actions/consumer',with: { BUMP_VERDICTS: '${{ needs.read-bumps.outputs.bump_verdicts }}' },@@ -1884,7 +1900,7 @@ describe('the release App credential never shares a job with installed packages'}});- test('a job that mints an App token takes only bump_verdicts from the reader job', () => {+ test('a job that mints an App token takes only bump_verdicts and note_levels from the reader job', () => {for (const { name, job } of jobs.filter(({ job }) => mintsAppToken(job))) {const verdictSteps = steps(job).filter((step) => step.env?.BUMP_VERDICTS !== undefined);expect(verdictSteps.length, name).toBeGreaterThan(0);@@ -1893,6 +1909,13 @@ describe('the release App credential never shares a job with installed packages''${{ needs.read-bumps.outputs.bump_verdicts }}',);}+ const levelSteps = steps(job).filter((step) => step.env?.NOTE_LEVELS !== undefined);+ expect(levelSteps.length, name).toBeGreaterThan(0);+ for (const step of levelSteps) {+ expect(step.env.NOTE_LEVELS, `${name} ${step.name}`).toBe(+ '${{ needs.read-bumps.outputs.note_levels }}',+ );+ }expect(strayReaderReads(job), name).toEqual([]);for (const step of steps(job).filter((candidate) => candidate.name === REFUSAL)) {expect(step.id, name).toBeUndefined();@@ -3099,3 +3122,24 @@ describe('Linux packaging ships the native prebuilds and checks them before uplo}});});++describe('the Discord stable announcement and the notes renderer agree on the notes-source marker', () => {+ test('the announcement strips the marker line the renderer writes and keeps the notes', () => {+ const step = workflowStep(desktopRelease, 'desktop-release.yml', 'Announce stable release to Discord');+ const stripLine = step.split('\n').find((line) => line.includes('ok-notes-source'));+ expect(stripLine, 'the Discord step no longer strips the notes-source marker').toBeDefined();+ const programs = [...(stripLine ?? '').matchAll(/-e '([^']*)'/g)].map((match) => match[1]);+ const rendered = renderStableNotes([{ id: 'a-fix', level: 'patch', summary: 'A fix.' }], {+ marked: true,+ });+ expect(rendered).toContain(NOTES_SOURCE_MARKER);+ const body = `${rendered}\n<!-- ok-downloads:start -->\n| a | b |\n<!-- ok-downloads:end -->\n`;+ const stripped = execFileSync('sed', programs.flatMap((program) => ['-e', program]), {+ input: body,+ encoding: 'utf8',+ });+ expect(stripped).not.toContain('ok-notes-source');+ expect(stripped).not.toContain('ok-downloads');+ expect(stripped).toContain('- A fix.');+ });+});diff --git a/.github/scripts/step-slicer-shape.test.mjs b/.github/scripts/step-slicer-shape.test.mjsindex 9e0e08654..9d73453a5 100644--- a/.github/scripts/step-slicer-shape.test.mjs+++ b/.github/scripts/step-slicer-shape.test.mjs@@ -15,7 +15,7 @@ const NESTED_SLICE = /\.slice\(\s*[A-Za-z_$][\w$]*(?:\.[\w$]+)*\.(?:indexOf|lastconst BASELINE = {'build-smoke-alert-payload.test.mjs': 3,'point-release-plan.test.mjs': 1,- 'release-cascade-shape.test.mjs': 18,+ 'release-cascade-shape.test.mjs': 17,};const countIn = (src) => [...src.matchAll(NESTED_SLICE)].length;diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.ymlindex 5b06bf65f..1b61dd27d 100644--- a/.github/workflows/desktop-release.yml+++ b/.github/workflows/desktop-release.yml@@ -1893,14 +1893,6 @@ jobs:exit 1fi- # Marker-delimited (`<!-- ok-downloads:start/end -->`) so re-renders are- # idempotent and the rest of the body — the changelog and the beta- # cadence's hidden consumed-set marker, which compute-next-beta.mjs- # reads back from the previous beta's body — passes through- # byte-identical. The announcement steps below and- # aggregate-stable-changelog.mjs each strip the block on their side.- # Best-effort: a release with assets but no Downloads table is a- # cosmetic gap, not a reason to strand the release as a draft.- name: Render the Downloads table into the release bodyenv:GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}@@ -1980,6 +1972,45 @@ jobs:echo "published=true" >> "$GITHUB_OUTPUT"+ - name: Detect bridge App for the docs changelog refresh+ id: docs-bridge+ if: success() && needs.prepare.outputs.channel == 'latest'+ env:+ OK_RELEASE_BRIDGE_APP_ID: ${{ secrets.OK_RELEASE_BRIDGE_APP_ID }}+ run: |+ if [[ -n "${OK_RELEASE_BRIDGE_APP_ID:-}" ]]; then+ echo "configured=true" >> "$GITHUB_OUTPUT"+ else+ echo "configured=false" >> "$GITHUB_OUTPUT"+ echo "::notice::OK_RELEASE_BRIDGE_APP_ID not set; skipping the docs changelog refresh for ${RELEASE_TAG}. The changelog picks it up on the next docs deploy."+ fi++ - name: Mint docs refresh token (bridge App)+ id: docs-bridge-token+ if: success() && steps.docs-bridge.outputs.configured == 'true'+ continue-on-error: true+ uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1+ with:+ client-id: Iv23lii4qS2FAc6tkzfI+ private-key: ${{ secrets.OK_RELEASE_BRIDGE_APP_PRIVATE_KEY }}+ owner: inkeep+ repositories: agents-private++ - name: Refresh the docs changelog on agents-private+ if: success() && steps.docs-bridge-token.outputs.token != ''+ env:+ GH_TOKEN: ${{ steps.docs-bridge-token.outputs.token }}+ run: |+ set -uo pipefail+ SELF_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"+ payload=$(jq -nc --arg tag "$RELEASE_TAG" --arg by "$SELF_URL" \+ '{event_type: "ok-stable-published", client_payload: {release_tag: $tag, dispatched_by: $by}}')+ if gh api -X POST "repos/inkeep/agents-private/dispatches" --input - <<<"$payload" >/dev/null; then+ echo "Dispatched ok-stable-published to agents-private for ${RELEASE_TAG}; the docs changelog rebuilds there."+ else+ echo "::warning::Could not dispatch ok-stable-published for ${RELEASE_TAG}; the docs changelog refreshes on the next docs deploy, or run public-open-knowledge-docs-changelog-deploy.yml by hand."+ fi+# FR5b — the npm stable publish sits downstream of the DMG smoke gate# (build-macos fails on a bad verdict, which skips this whole job) AND# the full-inventory verification, so npm `latest` can only move for a@@ -2024,13 +2055,6 @@ jobs:if [[ -n "$CHILD" ]]; then echo "- Run: ${CHILD}"; else echo "- (run link unresolved; open release.yml)"; fi} >> "$GITHUB_STEP_SUMMARY"- # The on-site changelog (/docs/changelog) is rebuilt by- # public-open-knowledge-docs-changelog-deploy.yml (on agents-private), which- # fires the Vercel deploy hook when the `main-reset` commit rewrites- # packages/cli/CHANGELOG.md on main. Triggering here would be too early — the- # changelog reads that file, and it isn't updated until main-reset lands after- # this release completes.-# Announce STABLE releases to Slack. Gated on channel=latest so betas# stay silent — every *-beta.N cut also flows through this job (on# channel=beta) and must not post. Placed AFTER the promote step and@@ -2128,7 +2152,7 @@ jobs:# Discord renders no markdown tables; strip the marker-delimited# Downloads block (the release page keeps it — the embed links# there).- NOTES="$(printf '%s' "$NOTES" | sed '/<!-- ok-downloads:start -->/,/<!-- ok-downloads:end -->/d')"+ NOTES="$(printf '%s' "$NOTES" | sed -e '/<!-- ok-downloads:start -->/,/<!-- ok-downloads:end -->/d' -e '/^<!-- ok-notes-source: .* -->$/d')"NOTES_LIMIT=3500if [[ "${#NOTES}" -gt "$NOTES_LIMIT" ]]; thenNOTES="${NOTES:0:$NOTES_LIMIT}…"diff --git a/.github/workflows/point-release.yml b/.github/workflows/point-release.ymlindex c5d39e7b8..e8e902ef9 100644--- a/.github/workflows/point-release.yml+++ b/.github/workflows/point-release.yml@@ -118,6 +118,7 @@ jobs:contents: readoutputs:bump_verdicts: ${{ steps.bumps.outputs.bump_verdicts }}+ note_levels: ${{ steps.bumps.outputs.note_levels }}steps:- name: Checkoutuses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1@@ -136,7 +137,7 @@ jobs:corepack enablepnpm install --frozen-lockfile --filter=. --ignore-scripts- - name: Read the bump of every changeset the fix refs write+ - name: Read the bump and release-note level of every changeset the fix refs writeid: bumpsenv:MODE: ${{ inputs.mode }}@@ -247,6 +248,7 @@ jobs:BRIDGE_GH_TOKEN: ${{ steps.bridge-token.outputs.token }}BRIDGE_CONFIGURED: ${{ steps.bridge-check.outputs.configured }}BUMP_VERDICTS: ${{ needs.read-bumps.outputs.bump_verdicts }}+ NOTE_LEVELS: ${{ needs.read-bumps.outputs.note_levels }}MODE: ${{ inputs.mode }}FIX_REFS: ${{ inputs.fix_refs }}ANCHOR_DELTA_IDS: ${{ inputs.anchor_delta_ids }}diff --git a/.github/workflows/promote-stable.yml b/.github/workflows/promote-stable.ymlindex 1beac7690..21a8d4d13 100644--- a/.github/workflows/promote-stable.yml+++ b/.github/workflows/promote-stable.yml@@ -114,6 +114,7 @@ jobs:outputs:beta_tag: ${{ steps.resolve.outputs.beta_tag }}bump_verdicts: ${{ steps.bumps.outputs.bump_verdicts }}+ note_levels: ${{ steps.levels.outputs.note_levels }}steps:- name: Checkoutuses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1@@ -174,6 +175,15 @@ jobs:set -euo pipefailnode scripts/compute-stable-version.mjs "$BETA_TAG"+ - name: Read the release-note level of every changeset the stable ships+ id: levels+ if: steps.bumps.outputs.skip != 'true'+ env:+ BETA_SHA: ${{ steps.bumps.outputs.beta_sha }}+ run: |+ set -euo pipefail+ node scripts/render-stable-notes.mjs --read-levels --commit "$BETA_SHA"+promote:name: Promote ${{ inputs.beta_tag || 'newest beta' }} to stableneeds: read-bumps@@ -337,130 +347,33 @@ jobs:origin: https://openknowledge.aievidence-name: share-contract-promote-${{ github.run_id }}-${{ github.run_attempt }}- - name: Tag stable at beta SHA- if: steps.ver.outputs.skip != 'true'- env:- GH_TOKEN: ${{ steps.app-token.outputs.token }}- STABLE_TAG: ${{ steps.ver.outputs.stable_tag }}- BETA_SHA: ${{ steps.ver.outputs.beta_sha }}- run: |- set -euo pipefail- git config user.name "github-actions[bot]"- git config user.email "41898282+github-actions[bot]@users.noreply.github.com"-- # Idempotency: a re-run after a transient failure should not- # explode if the tag already exists.- if git rev-parse "refs/tags/${STABLE_TAG}" >/dev/null 2>&1; then- EXISTING=$(git rev-parse "refs/tags/${STABLE_TAG}")- if [[ "$EXISTING" != "$BETA_SHA" ]]; then- echo "::error::Stable tag ${STABLE_TAG} already exists at ${EXISTING} (expected ${BETA_SHA}). Refusing to retag."- exit 1- fi- echo "Tag ${STABLE_TAG} already at ${BETA_SHA}; skipping git tag step."- else- git tag "$STABLE_TAG" "$BETA_SHA"- # shellcheck disable=SC2016- git -c credential.helper= \- -c 'credential.helper=!f() { test "$1" = get || return 0; echo username=x-access-token; echo "password=$GH_TOKEN"; }; f' \- push origin "$STABLE_TAG"- fi-- - name: Aggregate beta release bodies since previous stable+ - name: Render release notes from the stable's changesetsid: changelogif: steps.ver.outputs.skip != 'true'env:GH_TOKEN: ${{ steps.app-token.outputs.token }}STABLE_TAG: ${{ steps.ver.outputs.stable_tag }}BETA_SHA: ${{ steps.ver.outputs.beta_sha }}- # Pass the resolved beta tag via env to keep ${{ }} expression- # interpolation out of the run: block — direct ${{ }} substitution- # in shell is a script-injection foothold (a malicious tag value- # like `v1; curl evil.example` would expand textually before bash- # parsed the printf invocation). Defense-in-depth even though- # dispatching this workflow requires repo write access.- BETA_TAG_INPUT: ${{ steps.resolve.outputs.beta_tag }}+ NOTE_LEVELS: ${{ needs.read-bumps.outputs.note_levels }}run: |set -euo pipefailBODY_FILE=$(mktemp)+ node scripts/render-stable-notes.mjs --commit "$BETA_SHA" --exclude-tag "$STABLE_TAG" > "$BODY_FILE"- # Resolve the previous stable tag (most recent tag matching v*.*.*- # without -beta suffix, ancestor of the beta SHA). May be empty for- # the first-ever stable.- PREV_STABLE=$(git tag --list 'v*' --sort=-version:refname \- --merged "$BETA_SHA" \- | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' \- | grep -v "^${STABLE_TAG}$" \- | head -n 1 || true)-- # Betas whose changes are in this stable = beta tags reachable from the- # promoted beta SHA but NOT from the previous stable. Under delta- # versioning the promoted beta's NAME (e.g. v0.30.1-beta.6) no longer- # matches the computed stable version (e.g. 0.30.2), so we range by- # commit ancestry (--merged/--no-merged), not a name glob.- if [[ -n "$PREV_STABLE" ]]; then- echo "Aggregating betas reachable from ${BETA_TAG_INPUT} but not ${PREV_STABLE}"- BETA_TAGS_IN_RANGE=$(git tag --list 'v*-beta.*' --merged "$BETA_SHA" --no-merged "$PREV_STABLE" --sort=version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+-beta\.[0-9]+$' || true)- else- echo "No previous stable tag; aggregating all betas reachable from ${BETA_TAG_INPUT}"- BETA_TAGS_IN_RANGE=$(git tag --list 'v*-beta.*' --merged "$BETA_SHA" --sort=version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+-beta\.[0-9]+$' || true)- fi-- # Under the zero-commit-bump cadence, beta release bodies are the- # source of truth — packages/*/CHANGELOG.md no longer accumulates- # per-beta entries (only per-stable, written by main-reset's- # `pnpm exec changeset version` at promotion time). Each beta body carries- # ONLY the delta introduced in that beta (compute-next-beta.mjs filters- # against the prior beta's embedded consumed-set marker), so the cycle's- # betas concatenated are a clean, duplication-free set of the changes- # this stable ships.- #- # aggregate-stable-changelog.mjs regroups that concatenation into one- # section per bump level (Major/Minor/Patch, empty levels omitted) and- # emits no preamble of its own: the GitHub Release title already carries- # the version, and under delta versioning the promoted beta's name no- # longer equals the stable version, so the old "## X.Y.Z / Stable- # promotion of beta … / Aggregated changes since previous stable" header- # was both redundant and inaccurate. The script also drops the internal- # `<!-- ok-consumed-set: … -->` markers and the per-beta "Delta since- # previous beta" / "First beta of the cycle" lead lines.- RAW_BODIES=$(mktemp)- UNAVAILABLE=""- for tag in $BETA_TAGS_IN_RANGE; do- if BODY=$(gh release view "$tag" --json body --jq .body 2>/dev/null) && [[ -n "$BODY" ]]; then- printf '%s\n\n' "$BODY" >> "$RAW_BODIES"- else- UNAVAILABLE="${UNAVAILABLE:+$UNAVAILABLE, }${tag}"- fi- done-- node scripts/aggregate-stable-changelog.mjs < "$RAW_BODIES" > "$BODY_FILE"-- # A stable with no resolvable beta changelog (no betas in range, or- # every body empty/unavailable) still needs a non-empty release body.if [[ ! -s "$BODY_FILE" ]]; thenprintf 'No changelog entries.\n' > "$BODY_FILE"fi- # Surface any beta whose body could not be fetched so its changes are- # not silently missing from the aggregated notes.- if [[ -n "$UNAVAILABLE" ]]; then- printf '\n_Release body unavailable for: %s — see the per-beta releases for those changes._\n' "$UNAVAILABLE" >> "$BODY_FILE"- fi-- # GitHub rejects release bodies over 125,000 chars with HTTP 422.- # A long beta cycle (dozens of betas, each contributing its delta)- # can blow past that. Cap with margin and point readers at the full- # per-beta history rather than failing the whole promotion.MAX_BODY=120000if [[ $(wc -c < "$BODY_FILE") -gt $MAX_BODY ]]; then- echo "Aggregated body $(wc -c < "$BODY_FILE") chars exceeds ${MAX_BODY}; truncating."+ echo "Release notes are $(wc -c < "$BODY_FILE") chars, over ${MAX_BODY}; truncating."TRUNC=$(mktemp)# Cut at MAX_BODY bytes, then drop the (now-partial) last line.head -c "$MAX_BODY" "$BODY_FILE" | sed '$d' > "$TRUNC"{printf '\n\n---\n\n'printf '_Changelog truncated to fit GitHub'\''s 125,000-character release-body limit. '- printf 'Full per-beta history: https://github.com/%s/releases_\n' "$GITHUB_REPOSITORY"+ printf 'The notes for every release are at https://github.com/%s/releases_\n' "$GITHUB_REPOSITORY"} >> "$TRUNC"mv "$TRUNC" "$BODY_FILE"fi@@ -470,6 +383,34 @@ jobs:cat "$BODY_FILE"echo "------------------------------"+ - name: Tag stable at beta SHA+ if: steps.ver.outputs.skip != 'true'+ env:+ GH_TOKEN: ${{ steps.app-token.outputs.token }}+ STABLE_TAG: ${{ steps.ver.outputs.stable_tag }}+ BETA_SHA: ${{ steps.ver.outputs.beta_sha }}+ run: |+ set -euo pipefail+ git config user.name "github-actions[bot]"+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"++ # Idempotency: a re-run after a transient failure should not+ # explode if the tag already exists.+ if git rev-parse "refs/tags/${STABLE_TAG}" >/dev/null 2>&1; then+ EXISTING=$(git rev-parse "refs/tags/${STABLE_TAG}")+ if [[ "$EXISTING" != "$BETA_SHA" ]]; then+ echo "::error::Stable tag ${STABLE_TAG} already exists at ${EXISTING} (expected ${BETA_SHA}). Refusing to retag."+ exit 1+ fi+ echo "Tag ${STABLE_TAG} already at ${BETA_SHA}; skipping git tag step."+ else+ git tag "$STABLE_TAG" "$BETA_SHA"+ # shellcheck disable=SC2016+ git -c credential.helper= \+ -c 'credential.helper=!f() { test "$1" = get || return 0; echo username=x-access-token; echo "password=$GH_TOKEN"; }; f' \+ push origin "$STABLE_TAG"+ fi+- name: Create stable GitHub Releaseif: steps.ver.outputs.skip != 'true'env:diff --git a/docs/src/lib/releases.test.ts b/docs/src/lib/releases.test.tsindex 7bf92cfa5..72e4af885 100644--- a/docs/src/lib/releases.test.ts+++ b/docs/src/lib/releases.test.ts@@ -1,5 +1,20 @@-import { describe, expect, test } from 'vitest';-import { collectDates, fetchReleaseDates, parseChangelog } from './releases.ts';+import { readFileSync } from 'node:fs';+import { join } from 'node:path';+import { describe, expect, test, vi } from 'vitest';+import {+ collectDates,+ collectMarkedNotes,+ cutoverOf,+ fetchReleaseFeed,+ loadStableReleases,+ markedNotes,+ mergeReleaseNotes,+ NOTES_SOURCE_MARKER,+ newMarkedNotesScan,+ parseChangelog,+ passedCutover,+ releaseNotesFrom,+} from './releases.ts';const SAMPLE = `# @inkeep/open-knowledge@@ -67,10 +82,24 @@ describe('parseChangelog', () => {function apiRelease(tag: string,- opts: { draft?: boolean; prerelease?: boolean; published_at?: string | null } = {},+ opts: {+ draft?: boolean;+ prerelease?: boolean;+ published_at?: string | null;+ created_at?: string;+ body?: string;+ } = {},) {- const { draft = false, prerelease = false, published_at = '2026-07-01T00:00:00Z' } = opts;- return { tag_name: tag, draft, prerelease, published_at };+ const { draft = false, prerelease = false, published_at = '2026-07-01T00:00:00Z', body } = opts;+ const created_at = opts.created_at ?? published_at ?? '2026-07-01T00:00:00Z';+ return {+ tag_name: tag,+ draft,+ prerelease,+ created_at,+ published_at,+ ...(body === undefined ? {} : { body }),+ };}describe('collectDates', () => {@@ -114,34 +143,453 @@ const json = (data: unknown) => new Response(JSON.stringify(data), { status: 200const fullPage = (page: number) =>Array.from({ length: 100 }, (_, i) => apiRelease(`v9.${page}.${i}`, { prerelease: i > 0 }));-describe('fetchReleaseDates (best-effort)', () => {- test('paginates until it has enough stable dates, then stops', async () => {- const dates = await fetchReleaseDates(- 2,- mockFetch((p) => json(fullPage(p))),- );- expect(dates.size).toBe(2);+describe('fetchReleaseFeed dates (best-effort)', () => {+ test('keeps only as many stable dates as asked for', async () => {+ const feed = await fetchReleaseFeed({+ dateLimit: 2,+ changelogTags: new Set(),+ fetchImpl: mockFetch((p) => json(fullPage(p))),+ });+ expect(feed.dates.size).toBe(2);});test('stops on a short (final) page', async () => {- const dates = await fetchReleaseDates(- 30,- mockFetch(() => json([apiRelease('v1.0.0')])),- );- expect(dates.size).toBe(1);+ const feed = await fetchReleaseFeed({+ changelogTags: new Set(),+ fetchImpl: mockFetch(() => json([apiRelease('v1.0.0')])),+ });+ expect(feed.dates.size).toBe(1);});test('degrades to empty on HTTP error — never throws', async () => {- const dates = await fetchReleaseDates(- 30,- mockFetch(() => new Response('nope', { status: 500 })),- );- expect(dates.size).toBe(0);+ const feed = await fetchReleaseFeed({+ changelogTags: new Set(),+ fetchImpl: mockFetch(() => new Response('nope', { status: 500 })),+ });+ expect(feed.dates.size).toBe(0);});test('degrades to empty on a network throw — never throws', async () => {- const dates = await fetchReleaseDates(30, (() =>- Promise.reject(new Error('offline'))) as never);- expect(dates.size).toBe(0);+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const feed = await fetchReleaseFeed({+ changelogTags: new Set(),+ fetchImpl: (() => Promise.reject(new Error('offline'))) as never,+ });+ expect(feed.dates.size).toBe(0);+ warn.mockRestore();+ });+});++const DOWNLOADS =+ '<!-- ok-downloads:start -->\n## Downloads\n\n| a | b |\n| --- | --- |\n<!-- ok-downloads:end -->';+const marked = (notes: string) => `${notes}\n\n${NOTES_SOURCE_MARKER}\n\n${DOWNLOADS}\n`;++describe('markedNotes', () => {+ test('is the body before the notes-source marker, without the Downloads block', () => {+ expect(markedNotes(marked('### Patch Changes\n\n- A fix.'))).toBe(+ '### Patch Changes\n\n- A fix.',+ );+ expect(+ markedNotes(+ `### Patch Changes\n\n- A fix.\n\n${NOTES_SOURCE_MARKER}\n\nPoint release over v1.0.0.`,+ ),+ ).toBe('### Patch Changes\n\n- A fix.');+ });++ test('is null for a body without the marker, so the version keeps its CHANGELOG.md notes', () => {+ expect(markedNotes(`### Patch Changes\n\n- A fix.\n\n${DOWNLOADS}\n`)).toBeNull();+ expect(markedNotes('')).toBeNull();+ });+});++const day = (n: number) => new Date(Date.UTC(2026, 9, 1) - n * 86_400_000).toISOString();++describe('collectMarkedNotes', () => {+ test('keeps every marked stable body and takes the highest unmarked CHANGELOG stable published before them as the cutover', () => {+ const scan = newMarkedNotesScan();+ collectMarkedNotes(+ [+ apiRelease('v0.88.0', { draft: true, body: marked('- Draft.') }),+ apiRelease('v0.88.0-beta.1', { prerelease: true, body: marked('- Beta.') }),+ apiRelease('v0.87.1', { body: marked('- Newest.'), published_at: day(0) }),+ apiRelease('v0.87.0', {+ body: 'A revert point release, unmarked and not in CHANGELOG.md.',+ published_at: day(1),+ }),+ apiRelease('v0.86.11', { body: '- Covered, below the cutover.', published_at: day(5) }),+ apiRelease('v0.86.13', { body: marked('- Older.'), published_at: day(2) }),+ apiRelease('v0.86.12', { body: '- From before the cutover.', published_at: day(3) }),+ ],+ scan,+ new Set(['v0.86.12', 'v0.86.11']),+ );+ expect([...scan.notes]).toEqual([+ ['v0.87.1', '- Newest.'],+ ['v0.86.13', '- Older.'],+ ]);+ expect(cutoverOf(scan)).toEqual({ tag: 'v0.86.12', publishedAt: Date.parse(day(3)) });+ });++ test('an unmarked CHANGELOG stable published after a marked body is never the cutover', () => {+ const scan = newMarkedNotesScan();+ collectMarkedNotes(+ [+ apiRelease('v0.90.1', { body: '- Revert, unmarked.', published_at: day(1) }),+ apiRelease('v0.90.0', { body: marked('- Ninety.'), published_at: day(3) }),+ ],+ scan,+ new Set(['v0.90.1']),+ );+ expect(cutoverOf(scan)).toBeNull();+ });++ test('tolerates malformed entries and payloads', () => {+ const scan = newMarkedNotesScan();+ collectMarkedNotes([null, 42, { tag_name: 5 }, apiRelease('v1.0.0')], scan, new Set());+ collectMarkedNotes('not-an-array', scan, new Set());+ expect(scan.notes.size).toBe(0);+ expect(cutoverOf(scan)).toBeNull();+ });+});++describe('passedCutover', () => {+ test('holds once the scan reaches releases created 14 days before the cutover was published', () => {+ const scan = newMarkedNotesScan();+ const covered = new Set(['v1.0.0']);+ collectMarkedNotes([apiRelease('v1.0.0', { published_at: day(0) })], scan, covered);+ collectMarkedNotes(+ [apiRelease('v0.9.0-beta.0', { prerelease: true, created_at: day(13) })],+ scan,+ covered,+ );+ expect(passedCutover(scan)).toBe(false);+ collectMarkedNotes(+ [apiRelease('v0.9.0-beta.1', { prerelease: true, created_at: day(15) })],+ scan,+ covered,+ );+ expect(passedCutover(scan)).toBe(true);+ });++ test('never holds without an unmarked stable the CHANGELOG covers', () => {+ const scan = newMarkedNotesScan();+ collectMarkedNotes(+ [apiRelease('v2.0.0', { body: marked('- x'), created_at: day(400) })],+ scan,+ new Set(['v1.0.0']),+ );+ expect(passedCutover(scan)).toBe(false);+ });+});++function pagedFetch(pages: unknown[][], status: (page: number) => number = () => 200) {+ const requested: number[] = [];+ const impl = ((url: string | URL) => {+ const page = Number(/[?&]page=(\d+)/.exec(String(url))?.[1] ?? '1');+ requested.push(page);+ const code = status(page);+ return Promise.resolve(+ code === 200+ ? new Response(JSON.stringify(pages[page - 1] ?? []), { status: 200 })+ : new Response('no', { status: code }),+ );+ }) as unknown as typeof fetch;+ return { impl, requested };+}++const betas = (page: number, count: number) =>+ Array.from({ length: count }, (_, i) =>+ apiRelease(`v9.${page}.${i}-beta.0`, { prerelease: true }),+ );++const betasCreated = (page: number, count: number, createdDay: number) =>+ Array.from({ length: count }, (_, i) =>+ apiRelease(`v9.${page}.${i}-beta.0`, { prerelease: true, created_at: day(createdDay) }),+ );++describe('fetchReleaseFeed', () => {+ test('pages past the date limit until it is 14 days below the newest unmarked CHANGELOG stable', async () => {+ const pages = [+ [+ apiRelease('v0.90.0', { body: marked('- Ninety.'), published_at: day(0) }),+ ...betasCreated(1, 99, 1),+ ],+ [+ apiRelease('v0.89.0', { body: marked('- Eighty-nine.'), published_at: day(2) }),+ ...betasCreated(2, 99, 3),+ ],+ [+ apiRelease('v0.88.0', { body: '- Before the marker.', published_at: day(9) }),+ ...betasCreated(3, 99, 10),+ ],+ [+ apiRelease('v0.87.0', { body: '- Old.', published_at: day(20) }),+ ...betasCreated(4, 99, 25),+ ],+ [apiRelease('v0.86.0', { body: marked('- Not read.') }), ...betasCreated(5, 99, 30)],+ ];+ const { impl, requested } = pagedFetch(pages);+ const feed = await fetchReleaseFeed({+ dateLimit: 1,+ changelogTags: new Set(['v0.88.0', 'v0.87.0']),+ fetchImpl: impl,+ });+ expect(requested).toEqual([1, 2, 3, 4]);+ expect([...feed.dates.keys()]).toEqual(['v0.90.0']);+ expect([...feed.notes.keys()]).toEqual(['v0.90.0', 'v0.89.0']);+ expect(feed.notesComplete).toBe(true);+ expect(feed.failure).toBeNull();+ });++ test('a revert or truncated stable published after marked bodies does not end the scan before them', async () => {+ const pages = [+ [+ apiRelease('v0.90.1', {+ body: '- Revert point release, unmarked.',+ created_at: day(1),+ published_at: day(1),+ }),+ ...betasCreated(1, 99, 2),+ ],+ [+ apiRelease('v0.90.0', {+ body: marked('- Ninety.'),+ created_at: day(4),+ published_at: day(3),+ }),+ ...betasCreated(2, 99, 16),+ ],+ [+ apiRelease('v0.89.0', {+ body: marked('- Eighty-nine.'),+ created_at: day(17),+ published_at: day(16),+ }),+ ...betasCreated(3, 99, 30),+ ],+ [+ apiRelease('v0.88.0', {+ body: '- Before the marker.',+ created_at: day(31),+ published_at: day(30),+ }),+ ...betasCreated(4, 99, 50),+ ],+ [apiRelease('v0.87.0', { body: marked('- Not read.') }), ...betasCreated(5, 99, 60)],+ ];+ const { impl, requested } = pagedFetch(pages);+ const feed = await fetchReleaseFeed({+ dateLimit: 1,+ changelogTags: new Set(['v0.90.1', 'v0.88.0']),+ fetchImpl: impl,+ });+ expect(requested).toEqual([1, 2, 3, 4]);+ expect([...feed.notes.keys()]).toEqual(['v0.90.0', 'v0.89.0']);+ expect(feed.notesComplete).toBe(true);+ });++ test('a newer marked stable listed after an unmarked point release is still read', async () => {+ const pages = [+ [+ apiRelease('v0.90.1', {+ body: '- Revert point release, unmarked.',+ created_at: day(1),+ published_at: day(1),+ }),+ ...betasCreated(1, 99, 1),+ ],+ [+ apiRelease('v0.91.0', {+ body: marked('- Promoted after the point release.'),+ created_at: day(2),+ published_at: day(0),+ }),+ apiRelease('v0.90.0', {+ body: marked('- Ninety.'),+ created_at: day(5),+ published_at: day(4),+ }),+ ...betasCreated(2, 98, 6),+ ],+ [+ apiRelease('v0.89.0', { body: '- Before the marker.', published_at: day(7) }),+ ...betasCreated(3, 99, 30),+ ],+ betasCreated(4, 100, 40),+ ];+ const { impl, requested } = pagedFetch(pages);+ const feed = await fetchReleaseFeed({+ dateLimit: 1,+ changelogTags: new Set(['v0.90.1', 'v0.89.0']),+ fetchImpl: impl,+ });+ expect(requested).toEqual([1, 2, 3]);+ expect([...feed.notes.keys()]).toEqual(['v0.91.0', 'v0.90.0']);+ expect(feed.notesComplete).toBe(true);+ });++ test('a short final page completes the notes even with no unmarked stable', async () => {+ const { impl } = pagedFetch([[apiRelease('v1.0.0', { body: marked('- One.') })]]);+ const feed = await fetchReleaseFeed({ changelogTags: new Set(), fetchImpl: impl });+ expect(feed.notesComplete).toBe(true);+ expect([...feed.notes.keys()]).toEqual(['v1.0.0']);+ });++ test('an HTTP error before the cutover leaves the notes incomplete and names the page and status', async () => {+ const { impl } = pagedFetch(+ [[apiRelease('v1.1.0', { body: marked('- New.') }), ...betas(1, 99)]],+ (page) => (page === 2 ? 502 : 200),+ );+ const feed = await fetchReleaseFeed({ changelogTags: new Set(['v1.0.0']), fetchImpl: impl });+ expect(feed.notesComplete).toBe(false);+ expect(feed.failure).toBe('page 2 returned HTTP 502');+ expect([...feed.dates.keys()]).toEqual(['v1.1.0']);+ });++ test('a 200 that is not a list of releases leaves the notes incomplete', async () => {+ const impl = (() =>+ Promise.resolve(json({ message: 'API rate limit exceeded' }))) as unknown as typeof fetch;+ const feed = await fetchReleaseFeed({ changelogTags: new Set(['v1.0.0']), fetchImpl: impl });+ expect(feed.notesComplete).toBe(false);+ expect(feed.failure).toBe('page 1 returned a body that is not a list of releases');+ });++ test('stops at the page cap without passing the cutover, and says the notes are incomplete', async () => {+ const { impl, requested } = pagedFetch(+ Array.from({ length: 30 }, (_, i) => [+ apiRelease(`v2.${i}.0`, { body: marked('- x') }),+ ...betas(i, 99),+ ]),+ );+ const feed = await fetchReleaseFeed({ changelogTags: new Set(['v1.0.0']), fetchImpl: impl });+ expect(requested).toHaveLength(20);+ expect(feed.notesComplete).toBe(false);+ expect(feed.failure).toBe('stopped at the 20-page cap');+ });++ test('a network throw leaves the notes incomplete and never throws', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const feed = await fetchReleaseFeed({+ changelogTags: new Set(['v1.0.0']),+ fetchImpl: (() => Promise.reject(new Error('offline'))) as never,+ });+ expect(feed).toEqual({+ dates: new Map(),+ notes: new Map(),+ notesComplete: false,+ failure: 'offline',+ });+ warn.mockRestore();+ });+});++describe('releaseNotesFrom', () => {+ test('passes complete notes through and drops incomplete ones with a warning', () => {+ const notes = new Map([['v1.0.0', '- One.']]);+ expect(releaseNotesFrom({ dates: new Map(), notes, notesComplete: true, failure: null })).toBe(+ notes,+ );+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ expect(+ releaseNotesFrom({+ dates: new Map(),+ notes,+ notesComplete: false,+ failure: 'page 2 returned HTTP 403',+ }).size,+ ).toBe(0);+ expect(warn).toHaveBeenCalledWith(+ expect.stringMatching(/\(page 2 returned HTTP 403\).*CHANGELOG\.md notes only/),+ );+ warn.mockRestore();+ });+});++describe('mergeReleaseNotes', () => {+ const changelog = parseChangelog(SAMPLE);++ test('with no marked notes it returns the CHANGELOG releases untouched', () => {+ expect(mergeReleaseNotes(changelog, new Map(), new Map())).toBe(changelog);+ });++ test('a marked body replaces that version and adds new ones, newest version first', () => {+ const dates = new Map([['v0.36.0', '2026-08-01T00:00:00Z']]);+ const out = mergeReleaseNotes(+ changelog,+ new Map([+ ['v0.36.0', '### Patch Changes\n\n- From the tag.'],+ ['v0.34.0', '### Patch Changes\n\n- Corrected in the Release body.'],+ ['v0.10.0', '### Patch Changes\n\n- Sorted by version, not text.'],+ ]),+ dates,+ );+ expect(out.map((r) => r.tag)).toEqual(['v0.36.0', 'v0.35.0', 'v0.34.0', 'v0.10.0', 'v0.9.1']);+ expect(out[0]).toEqual({+ tag: 'v0.36.0',+ title: 'v0.36.0',+ publishedAt: '2026-08-01T00:00:00Z',+ bodyHtml: expect.stringContaining('<li>From the tag.</li>'),+ htmlUrl: 'https://github.com/inkeep/open-knowledge/releases/tag/v0.36.0',+ });+ expect(out[2]?.bodyHtml).toContain('Corrected in the Release body.');+ expect(out[2]?.bodyHtml).not.toContain('95380ab');+ expect(out[1]).toBe(changelog[0]);+ });+});++describe('loadStableReleases', () => {+ const realChangelog = readFileSync(+ join(process.cwd(), '..', 'packages', 'cli', 'CHANGELOG.md'),+ 'utf8',+ );+ const changelogTags = realChangelog+ .split('\n')+ .flatMap((line) => /^## (\d+\.\d+\.\d+)\s*$/.exec(line)?.slice(1) ?? [])+ .map((version) => `v${version}`);+ const unmarkedPages = () => {+ const releases = changelogTags.flatMap((tag, i) => [+ apiRelease(`${tag}-beta.0`, { prerelease: true, body: 'Beta.' }),+ apiRelease(tag, {+ body: `### Patch Changes\n\n- Unmarked ${i}.\n\n${DOWNLOADS}\n`,+ published_at: `2026-01-01T00:00:${String(i % 60).padStart(2, '0')}Z`,+ }),+ ]);+ return Array.from({ length: Math.ceil(releases.length / 100) }, (_, i) =>+ releases.slice(i * 100, i * 100 + 100),+ );+ };++ test('with no marked Release body it renders exactly what CHANGELOG.md alone renders today', async () => {+ const pages = unmarkedPages();+ const out = await loadStableReleases(undefined, { fetchImpl: pagedFetch(pages).impl });+ const dates = new Map<string, string>();+ for (const page of pages.slice(0, 5)) collectDates(page, dates, 30);+ expect(out).toEqual(parseChangelog(realChangelog, dates));+ expect(dates.size).toBe(30);+ });++ test('a marked stable shows its Release body; every other version keeps its CHANGELOG.md notes', async () => {+ const pages = unmarkedPages();+ pages[0]?.unshift(+ apiRelease('v99.0.0', { body: marked('### Minor Changes\n\n- From the stable tag.') }),+ );+ const out = await loadStableReleases(undefined, { fetchImpl: pagedFetch(pages).impl });+ expect(out[0]?.tag).toBe('v99.0.0');+ expect(out[0]?.bodyHtml).toContain('<li>From the stable tag.</li>');+ expect(out[0]?.bodyHtml).not.toContain('Downloads');+ const changelogOnly = parseChangelog(realChangelog, new Map());+ expect(out.slice(1).map((r) => [r.tag, r.bodyHtml])).toEqual(+ changelogOnly.map((r) => [r.tag, r.bodyHtml]),+ );+ });++ test('when the Release bodies cannot be read it falls back to CHANGELOG.md alone', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const out = await loadStableReleases(undefined, {+ fetchImpl: pagedFetch([], () => 503).impl,+ });+ expect(out).toEqual(parseChangelog(realChangelog, new Map()));+ expect(warn).toHaveBeenCalledWith(expect.stringMatching(/CHANGELOG\.md notes only/));+ warn.mockRestore();});});diff --git a/docs/src/lib/releases.ts b/docs/src/lib/releases.tsindex a32e11a15..1e636c7a4 100644--- a/docs/src/lib/releases.ts+++ b/docs/src/lib/releases.ts@@ -10,8 +10,20 @@ const PER_PAGE = 100;const MAX_DATE_PAGES = 5;+const MAX_RELEASE_PAGES = 20;+const DATE_LIMIT = 30;+const RELEASE_NOTES_REQUIRED = false;++const NOTES_LAG_MS = 14 * 24 * 60 * 60 * 1000;++export const NOTES_SOURCE_MARKER = '<!-- ok-notes-source: stable-tag-tree -->';++const DOWNLOADS_BLOCK = /<!-- ok-downloads:start -->[\s\S]*?<!-- ok-downloads:end -->/g;++const STABLE_TAG = /^v(\d+)\.(\d+)\.(\d+)$/;+const CHANGELOG_PATH = join(process.cwd(), '..', 'packages', 'cli', 'CHANGELOG.md');export interface ReleaseNote {@@ -81,11 +93,110 @@ export function collectDates(payload: unknown, dates: Map<string, string>, limit}}-export async function fetchReleaseDates(- limit = DATE_LIMIT,- fetchImpl: typeof fetch = fetch,-): Promise<Map<string, string>> {+export function markedNotes(body: string): string | null {+ const marker = body.indexOf(NOTES_SOURCE_MARKER);+ if (marker === -1) return null;+ return body.slice(0, marker).replace(DOWNLOADS_BLOCK, '').trim();+}++interface PublishedStable {+ tag: string;+ publishedAt: number;+}++export interface MarkedNotesScan {+ notes: Map<string, string>;+ unmarkedCovered: PublishedStable[];+ earliestMarkedAt: number;+ oldestCreatedAt: number;+}++export function newMarkedNotesScan(): MarkedNotesScan {+ return {+ notes: new Map(),+ unmarkedCovered: [],+ earliestMarkedAt: Number.POSITIVE_INFINITY,+ oldestCreatedAt: Number.POSITIVE_INFINITY,+ };+}++function versionOf(tag: string): number[] {+ return STABLE_TAG.exec(tag)?.slice(1).map(Number) ?? [0, 0, 0];+}++function compareVersions(a: string, b: string): number {+ const pa = versionOf(a);+ const pb = versionOf(b);+ for (let i = 0; i < 3; i++) {+ const delta = (pa[i] ?? 0) - (pb[i] ?? 0);+ if (delta !== 0) return delta;+ }+ return 0;+}++export function collectMarkedNotes(+ payload: unknown,+ scan: MarkedNotesScan,+ changelogTags: ReadonlySet<string>,+): void {+ if (!Array.isArray(payload)) return;+ for (const entry of payload) {+ if (!entry || typeof entry !== 'object') continue;+ const rec = entry as Record<string, unknown>;+ const createdAt = typeof rec.created_at === 'string' ? Date.parse(rec.created_at) : Number.NaN;+ if (Number.isFinite(createdAt))+ scan.oldestCreatedAt = Math.min(scan.oldestCreatedAt, createdAt);+ if (rec.draft || rec.prerelease) continue;+ const tag = rec.tag_name;+ if (typeof tag !== 'string' || !STABLE_TAG.test(tag)) continue;+ const publishedAt =+ typeof rec.published_at === 'string' ? Date.parse(rec.published_at) : Number.NaN;+ const notes = typeof rec.body === 'string' ? markedNotes(rec.body) : null;+ if (notes !== null) {+ if (!scan.notes.has(tag)) scan.notes.set(tag, notes);+ if (Number.isFinite(publishedAt)) {+ scan.earliestMarkedAt = Math.min(scan.earliestMarkedAt, publishedAt);+ }+ } else if (changelogTags.has(tag) && Number.isFinite(publishedAt)) {+ scan.unmarkedCovered.push({ tag, publishedAt });+ }+ }+}++export function cutoverOf(scan: MarkedNotesScan): PublishedStable | null {+ let cutover: PublishedStable | null = null;+ for (const release of scan.unmarkedCovered) {+ if (release.publishedAt >= scan.earliestMarkedAt) continue;+ if (cutover === null || compareVersions(release.tag, cutover.tag) > 0) cutover = release;+ }+ return cutover;+}++export function passedCutover(scan: MarkedNotesScan): boolean {+ const cutover = cutoverOf(scan);+ return cutover !== null && scan.oldestCreatedAt < cutover.publishedAt - NOTES_LAG_MS;+}++export interface ReleaseFeed {+ dates: Map<string, string>;+ notes: Map<string, string>;+ notesComplete: boolean;+ failure: string | null;+}++export async function fetchReleaseFeed({+ dateLimit = DATE_LIMIT,+ changelogTags,+ fetchImpl = fetch,+}: {+ dateLimit?: number;+ changelogTags: ReadonlySet<string>;+ fetchImpl?: typeof fetch;+}): Promise<ReleaseFeed> {const dates = new Map<string, string>();+ const scan = newMarkedNotesScan();+ let exhausted = false;+ let failure: string | null = null;const token = process.env.GITHUB_TOKEN;const headers = {accept: 'application/vnd.github+json',@@ -93,21 +204,73 @@ export async function fetchReleaseDates(...(token ? { authorization: `Bearer ${token}` } : {}),};try {- for (let page = 1; page <= MAX_DATE_PAGES && dates.size < limit; page++) {+ for (let page = 1; ; page++) {+ const wantDates = page <= MAX_DATE_PAGES && dates.size < dateLimit;+ if (!wantDates && passedCutover(scan)) break;+ if (page > MAX_RELEASE_PAGES) {+ failure = `stopped at the ${MAX_RELEASE_PAGES}-page cap`;+ break;+ }const res = await fetchImpl(`${RELEASES_API}?per_page=${PER_PAGE}&page=${page}`, { headers });- if (!res.ok) break;+ if (!res.ok) {+ failure = `page ${page} returned HTTP ${res.status}`;+ break;+ }const payload = await res.json();- collectDates(payload, dates, limit);- if (!Array.isArray(payload) || payload.length < PER_PAGE) break;+ if (!Array.isArray(payload)) {+ failure = `page ${page} returned a body that is not a list of releases`;+ break;+ }+ if (wantDates) collectDates(payload, dates, dateLimit);+ collectMarkedNotes(payload, scan, changelogTags);+ if (payload.length < PER_PAGE) {+ exhausted = true;+ break;+ }}} catch (err) {- console.warn(- `[releases] date enrichment failed; building changelog without dates: ${- err instanceof Error ? err.message : String(err)- }`,- );+ failure = err instanceof Error ? err.message : String(err);+ console.warn(`[releases] date enrichment failed; building changelog without dates: ${failure}`);}- return dates;+ return {+ dates,+ notes: scan.notes,+ notesComplete: passedCutover(scan) || exhausted,+ failure,+ };+}++function compareTagsDescending(a: ReleaseNote, b: ReleaseNote): number {+ return compareVersions(b.tag, a.tag);+}++export function mergeReleaseNotes(+ changelogReleases: ReleaseNote[],+ notes: ReadonlyMap<string, string>,+ dates: ReadonlyMap<string, string>,+): ReleaseNote[] {+ if (notes.size === 0) return changelogReleases;+ const fromBodies = [...notes].map(([tag, markdown]) => ({+ tag,+ title: tag,+ publishedAt: dates.get(tag) ?? null,+ bodyHtml: renderNotes(markdown),+ htmlUrl: `${REPO_URL}/releases/tag/${tag}`,+ }));+ return [...fromBodies, ...changelogReleases.filter((release) => !notes.has(release.tag))].sort(+ compareTagsDescending,+ );+}++export function releaseNotesFrom(feed: ReleaseFeed): ReadonlyMap<string, string> {+ if (feed.notesComplete) return feed.notes;+ const reason =+ '[releases] could not read every stable Release body back to the newest one without notes' ++ `${feed.failure ? ` (${feed.failure})` : ''}; ` ++ 'the changelog cannot tell which versions have notes in their Release body.';+ if (RELEASE_NOTES_REQUIRED) throw new Error(reason);+ console.warn(`${reason} Showing packages/cli/CHANGELOG.md notes only.`);+ return new Map();}function readChangelog(): string | null {@@ -133,12 +296,23 @@ export async function loadStableReleases(): Promise<ReleaseNote[]> {const markdown = readChangelog();if (markdown === null) return [];- const dates = await fetchReleaseDates(DATE_LIMIT, deps.fetchImpl ?? fetch);- const releases = parseChangelog(markdown, dates);- if (releases.length === 0) {+ const changelogTags = new Set(+ markdown.split('\n').flatMap((line) => {+ const heading = VERSION_HEADING.exec(line);+ return heading ? [`v${heading[1]}`] : [];+ }),+ );+ const feed = await fetchReleaseFeed({+ dateLimit: DATE_LIMIT,+ changelogTags,+ fetchImpl: deps.fetchImpl ?? fetch,+ });+ const changelogReleases = parseChangelog(markdown, feed.dates);+ if (changelogReleases.length === 0) {throw new Error(`[changelog] CHANGELOG.md at ${CHANGELOG_PATH} has no \`## X.Y.Z\` sections — malformed or empty.`,);}+ const releases = mergeReleaseNotes(changelogReleases, releaseNotesFrom(feed), feed.dates);return Number.isFinite(limit) ? releases.slice(0, limit) : releases;}diff --git a/scripts/aggregate-stable-changelog.mjs b/scripts/aggregate-stable-changelog.mjsdeleted file mode 100644index 3654346b9..000000000--- a/scripts/aggregate-stable-changelog.mjs+++ /dev/null@@ -1,63 +0,0 @@-#!/usr/bin/env node-import { pathToFileURL } from 'node:url';--const LEVELS = ['Major', 'Minor', 'Patch'];--const LEVEL_HEADING = /^#{2,4} (Major|Minor|Patch) Changes\s*$/;--const STRIP_LINE =- /^(?:<!-- ok-consumed-set:.*-->|Delta since previous beta\b.*|First beta of the cycle\b.*)\s*$/;--const STRIP_DOWNLOADS_BLOCK = /<!-- ok-downloads:start -->[\s\S]*?<!-- ok-downloads:end -->/g;--export function aggregateStableChangelog(input) {- const withoutDownloads = input.replace(STRIP_DOWNLOADS_BLOCK, '');- const buckets = { Major: [], Minor: [], Patch: [] };- let level = null;- let block = null;-- const flush = () => {- if (level && block) {- while (block.length && block[block.length - 1].trim() === '') block.pop();- if (block.length) buckets[level].push(block.join('\n'));- }- block = null;- };-- for (const line of withoutDownloads.split('\n')) {- if (STRIP_LINE.test(line)) continue;- const heading = LEVEL_HEADING.exec(line);- if (heading) {- flush();- level = heading[1];- continue;- }- if (line.startsWith('- ')) {- flush();- block = [line];- continue;- }- if (block) block.push(line);- }- flush();-- const out = [];- for (const lvl of LEVELS) {- if (buckets[lvl].length === 0) continue;- out.push(`### ${lvl} Changes`, '', buckets[lvl].join('\n\n'), '');- }- const body = out.join('\n').replace(/\n+$/, '');- return body ? `${body}\n` : '';-}--function main() {- const chunks = [];- process.stdin.on('data', (c) => chunks.push(c));- process.stdin.on('end', () => {- process.stdout.write(aggregateStableChangelog(Buffer.concat(chunks).toString('utf8')));- });-}--if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {- main();-}diff --git a/scripts/aggregate-stable-changelog.test.mjs b/scripts/aggregate-stable-changelog.test.mjsdeleted file mode 100644index 826e8ca31..000000000--- a/scripts/aggregate-stable-changelog.test.mjs+++ /dev/null@@ -1,131 +0,0 @@-import { describe, expect, test } from 'vitest';-import { aggregateStableChangelog } from './aggregate-stable-changelog.mjs';--function betaBody({ lead, section }) {- return `${lead}\n\n${section}\n\n<!-- ok-consumed-set: ["x"] -->\n`;-}--describe('aggregateStableChangelog', () => {- test('merges bullets from many betas into one section per level (Major → Minor → Patch)', () => {- const input = [- betaBody({- lead: 'Delta since previous beta (v0.31.0-beta.0) — 1 new changeset.',- section: '### Minor Changes\n\n- Minor from beta.1',- }),- betaBody({- lead: 'Delta since previous beta (v0.31.0-beta.1) — 1 new changeset.',- section: '### Patch Changes\n\n- Patch from beta.2',- }),- betaBody({- lead: 'Delta since previous beta (v0.31.0-beta.2) — 1 new changeset.',- section: '### Patch Changes\n\n- Patch from beta.3',- }),- betaBody({- lead: 'First beta of the cycle.',- section: '### Major Changes\n\n- Major from beta.4',- }),- ].join('\n');-- expect(aggregateStableChangelog(input)).toBe(- [- '### Major Changes',- '',- '- Major from beta.4',- '',- '### Minor Changes',- '',- '- Minor from beta.1',- '',- '### Patch Changes',- '',- '- Patch from beta.2',- '',- '- Patch from beta.3',- '',- ].join('\n'),- );- });-- test('omits a level entirely when it has no changesets', () => {- const input = betaBody({- lead: 'First beta of the cycle.',- section: '### Patch Changes\n\n- Only a patch',- });- const out = aggregateStableChangelog(input);- expect(out).toBe('### Patch Changes\n\n- Only a patch\n');- expect(out).not.toContain('Major Changes');- expect(out).not.toContain('Minor Changes');- });-- test('drops no preamble of its own — no version header or promotion note', () => {- const out = aggregateStableChangelog(- betaBody({ lead: 'First beta of the cycle.', section: '### Minor Changes\n\n- A change' }),- );- expect(out.startsWith('### Minor Changes')).toBe(true);- expect(out).not.toContain('Stable promotion of beta');- expect(out).not.toContain('Aggregated changes since previous stable');- expect(out).not.toMatch(/^## \d/m);- });-- test('strips per-beta bookkeeping lines (consumed-set marker, delta/first-beta lead)', () => {- const out = aggregateStableChangelog(- betaBody({- lead: 'Delta since previous beta (v1.0.0-beta.0) — 2 new changesets.',- section: '### Patch Changes\n\n- A patch',- }),- );- expect(out).not.toContain('ok-consumed-set');- expect(out).not.toContain('Delta since previous beta');- expect(out).not.toContain('First beta of the cycle');- });-- test('strips the Downloads block even when a bullet block is still open above it', () => {- const downloads = [- '<!-- ok-downloads:start -->',- '## Downloads',- '',- '| Platform | Architecture | Download |',- '| --- | --- | --- |',- '| Windows | x64 | [OpenKnowledge-Setup-x64.exe](https://example.invalid/x) |',- '<!-- ok-downloads:end -->',- ].join('\n');- const out = aggregateStableChangelog(- `Delta since previous beta (v1.0.0-beta.0)\n\n### Patch Changes\n\n- A patch\n\n<!-- ok-consumed-set: ["x"] -->\n\n${downloads}\n`,- );- expect(out).toContain('- A patch');- expect(out).not.toContain('Downloads');- expect(out).not.toContain('|');- expect(out).not.toContain('ok-downloads');- });-- test('preserves a bullet body verbatim, including indented continuation paragraphs', () => {- const bullet = [- '- Report a bug from inside the app. Opens from Help → Report a Bug…',- '',- ' A second paragraph, indented two spaces, with `code` and a — dash.',- '',- ' A third paragraph.',- ].join('\n');- const out = aggregateStableChangelog(`### Minor Changes\n\n${bullet}\n`);- expect(out).toBe(`### Minor Changes\n\n${bullet}\n`);- });-- test('keeps multiple bullets within a single beta section', () => {- const input = '### Patch Changes\n\n- First patch\n\n- Second patch\n\n- Third patch\n';- expect(aggregateStableChangelog(input)).toBe(- '### Patch Changes\n\n- First patch\n\n- Second patch\n\n- Third patch\n',- );- });-- test('tolerates h2 and h4 level headings (upstream heading-level drift)', () => {- const input = '## Minor Changes\n\n- via h2\n\n#### Patch Changes\n\n- via h4\n';- expect(aggregateStableChangelog(input)).toBe(- '### Minor Changes\n\n- via h2\n\n### Patch Changes\n\n- via h4\n',- );- });-- test('empty input yields empty output (no headings emitted for absent levels)', () => {- expect(aggregateStableChangelog('')).toBe('');- expect(aggregateStableChangelog('\n\n')).toBe('');- });-});diff --git a/scripts/compute-stable-version.mjs b/scripts/compute-stable-version.mjsindex 50e39ad43..d3782a8b7 100644--- a/scripts/compute-stable-version.mjs+++ b/scripts/compute-stable-version.mjs@@ -202,61 +202,92 @@ export function gitAt(cwd) {`git merge-base --is-ancestor ${a} ${b} failed (exit ${res.status}): ${String(res.stderr || '').trim()}`,);},+ changesetText: (sha, id) => runGit(['show', `${sha}:./.changeset/${id}.md`], cwd),+ stableTags: () =>+ runGit(['tag', '--list', 'v*'], cwd)+ .split('\n')+ .map((line) => line.trim())+ .filter((tag) => STABLE_TAG_RE.test(tag)),bumpTypeOf: (sha, id) =>maxReleaseType(loadChangesets().parse(runGit(['show', `${sha}:./.changeset/${id}.md`], cwd)).releases),};}+export function releasedChangesetIds(git, { excludeTags = [], releasedTags = null } = {}) {+ const excluded = new Set(excludeTags);+ const released = new Set();+ for (const tag of releasedTags ?? git.stableTags()) {+ if (excluded.has(tag)) continue;+ for (const id of git.changesetIds(tag)) released.add(id);+ }+ return released;+}++export function unreleasedChangesetIds(git, sha, { excludeTags = [], releasedTags = null } = {}) {+ const released = releasedChangesetIds(git, { excludeTags, releasedTags });+ return git.changesetIds(sha).filter((id) => !released.has(id));+}+export const realGit = gitAt();-const BUMP_VERDICT_TYPES = new Set(['patch', 'minor', 'major', null]);+const VERDICT_TYPES = new Set(['patch', 'minor', 'major', null]);-export function parseBumpVerdicts(raw) {+const BUMP_VERDICTS = {+ env: 'BUMP_VERDICTS',+ output: 'bump_verdicts',+ job: 'read-bumps',+ noun: 'bump verdict',+ value: 'bump types',+};++export function parseVerdicts(raw, { env, output, job, noun, value }) {if (String(raw ?? '').trim() === '') {throw new Error(- 'BUMP_VERDICTS is empty: the read-bumps job wrote no bump_verdicts output, or this step does not ' +- 'receive needs.read-bumps.outputs.bump_verdicts.',+ `${env} is empty: the ${job} job wrote no ${output} output, or this step does not ` ++ `receive needs.${job}.outputs.${output}.`,);}let parsed;try {parsed = JSON.parse(String(raw));} catch (err) {- throw new Error(`bump verdicts are not JSON: ${err.message}`);+ throw new Error(`${noun}s are not JSON: ${err.message}`);}if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {- throw new Error('bump verdicts must be a JSON object mapping changeset blob ids to bump types.');+ throw new Error(`${noun}s must be a JSON object mapping changeset blob ids to ${value}.`);}for (const [blob, type] of Object.entries(parsed)) {- if (!BUMP_VERDICT_TYPES.has(type)) {- throw new Error(`bump verdict for blob ${blob} is ${JSON.stringify(type)}, not patch, minor, major or null.`);+ if (!VERDICT_TYPES.has(type)) {+ throw new Error(`${noun} for blob ${blob} is ${JSON.stringify(type)}, not patch, minor, major or null.`);}}return new Map(Object.entries(parsed));}+export const parseBumpVerdicts = (raw) => parseVerdicts(raw, BUMP_VERDICTS);+export const serializeBumpVerdicts = (verdicts) => JSON.stringify(Object.fromEntries(verdicts));-export function recordBumpVerdicts(git, verdicts) {+export function recordVerdicts(git, method, verdicts) {return {...git,- bumpTypeOf: (sha, id) => {- const type = git.bumpTypeOf(sha, id);+ [method]: (sha, id) => {+ const type = git[method](sha, id);verdicts.set(git.changesetBlobs(sha).get(id), type);return type;},};}-export function withBumpVerdicts(git, verdicts) {+export function withVerdicts(git, method, verdicts, { noun }) {return {...git,- bumpTypeOf: (sha, id) => {+ [method]: (sha, id) => {const blob = git.changesetBlobs(sha).get(id);if (blob === undefined || !verdicts.has(blob)) {throw new Error(- `no bump verdict for .changeset/${id}.md at ${sha} (blob ${blob ?? 'absent'}); the job that ran the ` +- 'Changesets reader did not read this changeset, so its bump is unknown here.',+ `no ${noun} for .changeset/${id}.md at ${sha} (blob ${blob ?? 'absent'}); the job that ran the ` ++ `Changesets reader did not read this changeset, so its ${noun} is unknown here.`,);}return verdicts.get(blob);@@ -264,6 +295,11 @@ export function withBumpVerdicts(git, verdicts) {};}+export const recordBumpVerdicts = (git, verdicts) => recordVerdicts(git, 'bumpTypeOf', verdicts);++export const withBumpVerdicts = (git, verdicts) =>+ withVerdicts(git, 'bumpTypeOf', verdicts, BUMP_VERDICTS);+export function readAnchorVersion() {const pre = JSON.parse(readFileSync('.changeset/pre.json', 'utf8'));if (pre.mode !== 'pre') {diff --git a/scripts/compute-stable-version.test.mjs b/scripts/compute-stable-version.test.mjsindex af3156f21..f998b3786 100644--- a/scripts/compute-stable-version.test.mjs+++ b/scripts/compute-stable-version.test.mjs@@ -14,6 +14,8 @@ import {gitAt,parseBumpVerdicts,recordBumpVerdicts,+ releasedChangesetIds,+ unreleasedChangesetIds,withBumpVerdicts,} from './compute-stable-version.mjs';import { gitCleanEnv } from './git-clean-env.mjs';@@ -125,6 +127,39 @@ describe('computeStablePromotion', () => {});});+describe('releasedChangesetIds', () => {+ const tags = {+ 'v1.0.0': ['a', 'x'],+ 'v1.0.1': ['a'],+ 'v1.1.0': ['a', 'y'],+ };+ const releaseGit = (extra = {}) => ({+ stableTags: () => Object.keys(tags),+ changesetIds: (ref) => tags[ref] ?? extra[ref] ?? [],+ });++ test('is the union of every stable tag tree, not only the newest', () => {+ expect([...releasedChangesetIds(releaseGit())].sort()).toEqual(['a', 'x', 'y']);+ });++ test('skips the tags it is told to exclude', () => {+ expect([...releasedChangesetIds(releaseGit(), { excludeTags: ['v1.1.0'] })].sort()).toEqual([+ 'a',+ 'x',+ ]);+ });++ test('a changeset a revert point release removed from its tag stays released for the next stable', () => {+ const git = releaseGit({ MAIN: ['a', 'x', 'y', 'z'] });+ expect(unreleasedChangesetIds(git, 'MAIN', { excludeTags: ['v1.2.0'] })).toEqual(['z']);+ });++ test('with no stable tag every changeset is unreleased', () => {+ const git = { stableTags: () => [], changesetIds: () => ['a', 'b'] };+ expect(unreleasedChangesetIds(git, 'MAIN')).toEqual(['a', 'b']);+ });+});+describe('evaluateAnchorGuard', () => {test('level anchor passes', () => {expect(evaluateAnchorGuard({ anchorVersion: '0.41.0', latestStableTag: 'v0.41.0' })).toMatchObject({@@ -433,6 +468,14 @@ describe('gitAt reads a commit\'s changesets the way Changesets reads the same texpect(reader.bumpTypeOf('HEAD', 'quoted')).toBe('minor');});+ test('stableTags lists only vX.Y.Z tags, whatever else the clone carries', () => {+ const root = committedChangesets({ 'plain.md': bump(`"${OK}": patch`) });+ for (const tag of ['v1.0.0', 'v1.0.1-beta.0', 'v1.1.0', 'docs-v2', 'v2'])+ git(root, ['tag', tag]);+ expect(gitAt(root).stableTags().sort()).toEqual(['v1.0.0', 'v1.1.0']);+ expect(gitAt(root).changesetIds('v1.1.0')).toEqual(['plain']);+ });+test('a changeset Changesets cannot parse fails the read instead of counting as no bump', () => {const root = committedChangesets({ 'broken.md': bump(`"${OK}": Major`) });expect(() => gitAt(root).bumpTypeOf('HEAD', 'broken')).toThrow();diff --git a/scripts/render-stable-notes.mjs b/scripts/render-stable-notes.mjsnew file mode 100644index 000000000..91c52664b--- /dev/null+++ b/scripts/render-stable-notes.mjs@@ -0,0 +1,210 @@+#!/usr/bin/env node+import { appendFileSync, readFileSync } from 'node:fs';+import { pathToFileURL } from 'node:url';+import {+ createShippedFixCheck,+ parseReleaseListing,+} from '../.github/scripts/shipped-fix-containment.mjs';+import { FIXED_GROUP_ANCHOR, loadChangesets, maxReleaseType } from './compute-next-beta.mjs';+import {+ gitAt,+ parseVerdicts,+ recordVerdicts,+ runGit,+ serializeBumpVerdicts,+ unreleasedChangesetIds,+ withVerdicts,+} from './compute-stable-version.mjs';++export const NOTES_SOURCE_MARKER = '<!-- ok-notes-source: stable-tag-tree -->';++export const EMPTY_NOTES = 'No changelog entries.';++const NOTE_LEVELS = {+ env: 'NOTE_LEVELS',+ output: 'note_levels',+ job: 'read-bumps',+ noun: 'note level',+ value: 'release-note levels',+};++const SECTIONS = [+ ['major', 'Major Changes'],+ ['minor', 'Minor Changes'],+ ['patch', 'Patch Changes'],+];++const CHANGESET_FILE = /\s*---([\s\S]*?)\n\s*---(\s*(?:\n|$)[\s\S]*)/;++export function changesetSummary(text) {+ const match = CHANGESET_FILE.exec(String(text ?? ''));+ if (!match)+ throw new Error(+ 'changeset has no frontmatter delimited by "---"; Changesets cannot read it either.',+ );+ return match[2].trim();+}++export function fixedGroupOf(config) {+ const group = (config?.fixed ?? []).find((members) => members.includes(FIXED_GROUP_ANCHOR));+ return group ?? [FIXED_GROUP_ANCHOR];+}++export function noteLevel(releases, fixedGroup) {+ const cli = releases.filter(({ name, type }) => name === FIXED_GROUP_ANCHOR && type !== 'none');+ return maxReleaseType(+ cli.length > 0 ? cli : releases.filter(({ name }) => fixedGroup.includes(name)),+ );+}++export function renderEntry(summary) {+ const [first, ...rest] = summary.split('\n').map((line) => line.trimEnd());+ return [`- ${first}`, ...rest.map((line) => (line === '' ? '' : ` ${line}`))].join('\n');+}++const isLoose = (summary) => /\n[ \t]*\n/.test(summary);++const fileOrder = (a, b) => {+ const left = `${a.id}.md`;+ const right = `${b.id}.md`;+ return left < right ? -1 : left > right ? 1 : 0;+};++export function renderStableNotes(entries, { marked = false } = {}) {+ const sections = [];+ for (const [level, heading] of SECTIONS) {+ const items = entries.filter((entry) => entry.level === level).sort(fileOrder);+ if (items.length === 0) continue;+ const lines = [];+ items.forEach((entry, index) => {+ lines.push(renderEntry(entry.summary));+ if (index < items.length - 1 && isLoose(entry.summary)) lines.push('');+ });+ sections.push(`### ${heading}\n\n${lines.join('\n')}`);+ }+ if (sections.length === 0) return `${EMPTY_NOTES}\n`;+ const notes = sections.join('\n\n');+ return marked ? `${notes}\n\n${NOTES_SOURCE_MARKER}\n` : `${notes}\n`;+}++export function collectStableNotes({ commit, excludeTags = [], releasedTags = null }, git) {+ return unreleasedChangesetIds(git, commit, { excludeTags, releasedTags })+ .map((id) => ({+ id,+ level: git.noteLevelOf(commit, id),+ summary: changesetSummary(git.changesetText(commit, id)),+ }))+ .filter((entry) => entry.level !== null);+}++export function stableNotes({ commit, excludeTags = [], publishedTags = null }, git) {+ const entries = collectStableNotes({ commit, excludeTags, releasedTags: publishedTags }, git);+ return renderStableNotes(entries, { marked: Array.isArray(publishedTags) });+}++export function readPublishedStableTags({ releasesFile = '' } = {}) {+ try {+ return createShippedFixCheck(+ releasesFile === ''+ ? {}+ : { listReleases: () => parseReleaseListing(readFileSync(releasesFile, 'utf8')) },+ ).publishedStableTags();+ } catch (err) {+ console.error(+ `::warning::render-stable-notes: could not read the published stable Releases (${err instanceof Error ? err.message : String(err)}). ` ++ 'The notes count every stable tag as released, so they may leave out changesets first tagged in a stable ' ++ 'whose Release never published, and they carry no notes-source marker; the docs keep CHANGELOG.md for this version.',+ );+ return null;+ }+}++export function noteReaderAt(cwd) {+ const git = gitAt(cwd);+ const fixedGroups = new Map();+ const fixedGroupAt = (sha) => {+ if (!fixedGroups.has(sha)) {+ fixedGroups.set(+ sha,+ fixedGroupOf(JSON.parse(runGit(['show', `${sha}:./.changeset/config.json`], cwd))),+ );+ }+ return fixedGroups.get(sha);+ };+ return {+ ...git,+ noteLevelOf: (sha, id) => {+ const text = git.changesetText(sha, id);+ const parsed = loadChangesets().parse(text);+ if (parsed.summary !== changesetSummary(text)) {+ throw new Error(+ `.changeset/${id}.md at ${sha}: the summary this renderer reads differs from the one Changesets reads, ` ++ 'so its release note would not match the changelog.',+ );+ }+ return noteLevel(parsed.releases, fixedGroupAt(sha));+ },+ };+}++export const parseNoteLevels = (raw) => parseVerdicts(raw, NOTE_LEVELS);++export const serializeNoteLevels = serializeBumpVerdicts;++export const recordNoteLevels = (git, levels) => recordVerdicts(git, 'noteLevelOf', levels);++export const withNoteLevels = (git, levels) =>+ withVerdicts(git, 'noteLevelOf', levels, NOTE_LEVELS);++export function parseArgs(argv) {+ const args = { readLevels: false, commit: '', excludeTags: [], releasesFile: '' };+ for (let i = 0; i < argv.length; i += 1) {+ const arg = argv[i];+ if (arg === '--read-levels') args.readLevels = true;+ else if (arg === '--commit') args.commit = argv[++i] ?? '';+ else if (arg === '--releases') args.releasesFile = argv[++i] ?? '';+ else if (arg === '--exclude-tag') {+ const tag = argv[++i] ?? '';+ if (tag !== '') args.excludeTags.push(tag);+ } else throw new Error(`unknown argument '${arg}'`);+ }+ if (args.commit === '') throw new Error('--commit <sha> is required');+ return args;+}++function main() {+ let args;+ try {+ args = parseArgs(process.argv.slice(2));+ const reader = noteReaderAt();+ const commit = reader.revParse(args.commit);+ if (args.readLevels) {+ const levels = new Map();+ const reading = recordNoteLevels(reader, levels);+ const ids = reader.changesetIds(commit);+ for (const id of ids) reading.noteLevelOf(commit, id);+ process.stderr.write(`Read the note level of ${ids.length} changeset(s) at ${commit}.\n`);+ if (process.env.GITHUB_OUTPUT) {+ appendFileSync(process.env.GITHUB_OUTPUT, `note_levels=${serializeNoteLevels(levels)}\n`);+ }+ return;+ }+ const git =+ process.env.NOTE_LEVELS === undefined+ ? reader+ : withNoteLevels(reader, parseNoteLevels(process.env.NOTE_LEVELS));+ const publishedTags = readPublishedStableTags({ releasesFile: args.releasesFile });+ process.stdout.write(+ stableNotes({ commit, excludeTags: args.excludeTags, publishedTags }, git),+ );+ } catch (err) {+ console.error(+ `::error::render-stable-notes: ${err instanceof Error ? err.message : String(err)}`,+ );+ process.exit(1);+ }+}++if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {+ main();+}diff --git a/scripts/render-stable-notes.test.mjs b/scripts/render-stable-notes.test.mjsnew file mode 100644index 000000000..2298d707e--- /dev/null+++ b/scripts/render-stable-notes.test.mjs@@ -0,0 +1,643 @@+import { spawnSync } from 'node:child_process';+import {+ copyFileSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ realpathSync,+ rmSync,+ writeFileSync,+} from 'node:fs';+import { createRequire } from 'node:module';+import { tmpdir } from 'node:os';+import { dirname, join } from 'node:path';+import { fileURLToPath } from 'node:url';+import { afterEach, describe, expect, test } from 'vitest';+import { configureTestGitRepository } from '../test-support/configure-git-fixture.test-helper.ts';+import {+ NOTES_SOURCE_MARKER as DOCS_NOTES_SOURCE_MARKER,+ markedNotes,+} from '../docs/src/lib/releases.ts';+import { gitCleanEnv } from './git-clean-env.mjs';+import {+ changesetSummary,+ collectStableNotes,+ EMPTY_NOTES,+ fixedGroupOf,+ NOTES_SOURCE_MARKER,+ noteLevel,+ noteReaderAt,+ parseArgs,+ parseNoteLevels,+ recordNoteLevels,+ renderStableNotes,+ stableNotes,+ withNoteLevels,+} from './render-stable-notes.mjs';++const SCRIPTS = dirname(fileURLToPath(import.meta.url));+const OK_ROOT = dirname(SCRIPTS);+const OK = '@inkeep/open-knowledge';+const CORE = '@inkeep/open-knowledge-core';+const FIXED = [+ OK,+ CORE,+ '@inkeep/open-knowledge-server',+ '@inkeep/open-knowledge-app',+ '@inkeep/open-knowledge-desktop',+];+const CONFIG = JSON.stringify({ changelog: '@changesets/cli/changelog', fixed: [FIXED] });++const changeset = (frontmatter, summary) => `---\n${frontmatter}\n---\n\n${summary}\n`;++const repos = [];++afterEach(() => {+ while (repos.length) rmSync(repos.pop(), { recursive: true, force: true });+});++function git(cwd, args) {+ const res = spawnSync('git', args, { cwd, env: gitCleanEnv(), encoding: 'utf8' });+ if (res.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${res.stderr}`);+ return res.stdout;+}++function tempDir(prefix) {+ const dir = realpathSync(mkdtempSync(join(tmpdir(), prefix)));+ repos.push(dir);+ return dir;+}++function releaseHistory({ subtree = '' } = {}) {+ const root = tempDir('stable-notes-history-');+ const base = join(root, subtree);+ const changesetDir = join(base, '.changeset');+ git(root, ['init', '-q', '-b', 'main']);+ configureTestGitRepository(root);+ mkdirSync(changesetDir, { recursive: true });+ writeFileSync(join(changesetDir, 'config.json'), CONFIG);+ writeFileSync(join(changesetDir, 'README.md'), '# Changesets\n');+ const commit = (message, files = {}, removed = []) => {+ for (const [name, body] of Object.entries(files)) writeFileSync(join(changesetDir, name), body);+ for (const name of removed) git(root, ['rm', '-q', join(changesetDir, name)]);+ git(root, ['add', '-A']);+ git(root, [+ '-c',+ 'user.name=t',+ '-c',+ '[email protected]',+ 'commit',+ '-q',+ '--allow-empty',+ '-m',+ message,+ ]);+ return git(root, ['rev-parse', 'HEAD']).trim();+ };+ return { root, base, commit, tag: (name, sha) => git(root, ['tag', name, sha]) };+}++describe('renderStableNotes', () => {+ test('groups entries by level, omits empty levels and ends with the source marker', () => {+ const out = renderStableNotes(+ [+ { id: 'b-fix', level: 'patch', summary: 'Fix b.' },+ { id: 'a-feature', level: 'minor', summary: 'Add a.' },+ { id: 'a-fix', level: 'patch', summary: 'Fix a.' },+ ],+ { marked: true },+ );+ expect(out).toBe(+ `### Minor Changes\n\n- Add a.\n\n### Patch Changes\n\n- Fix a.\n- Fix b.\n\n${NOTES_SOURCE_MARKER}\n`,+ );+ });++ test('orders entries by changeset file name, the order Changesets reads them in', () => {+ const out = renderStableNotes([+ { id: 'foo', level: 'patch', summary: 'Second, because foo.md sorts after foo-bar.md.' },+ { id: 'foo-bar', level: 'patch', summary: 'First.' },+ { id: 'Zed', level: 'patch', summary: 'Upper case sorts before lower case.' },+ ]);+ expect(out.split('\n').filter((line) => line.startsWith('- '))).toEqual([+ '- Upper case sorts before lower case.',+ '- First.',+ '- Second, because foo.md sorts after foo-bar.md.',+ ]);+ });++ test('indents continuation lines and separates a multi-paragraph entry from the next one', () => {+ const out = renderStableNotes(+ [+ { id: 'a', level: 'patch', summary: 'Lead.\n\nSecond paragraph.\n- nested item' },+ { id: 'b', level: 'patch', summary: 'Single line.' },+ { id: 'c', level: 'patch', summary: 'Last.' },+ ],+ { marked: true },+ );+ expect(out).toBe(+ '### Patch Changes\n\n- Lead.\n\n Second paragraph.\n - nested item\n\n- Single line.\n- Last.\n\n' ++ `${NOTES_SOURCE_MARKER}\n`,+ );+ });++ test('the docs changelog reads the marker this renderer writes', () => {+ expect(DOCS_NOTES_SOURCE_MARKER).toBe(NOTES_SOURCE_MARKER);+ const rendered = renderStableNotes([{ id: 'a-fix', level: 'patch', summary: 'A fix.' }], {+ marked: true,+ });+ const body = `${rendered}\n<!-- ok-downloads:start -->\n| a |\n<!-- ok-downloads:end -->\n`;+ expect(markedNotes(body)).toBe('### Patch Changes\n\n- A fix.');+ expect(markedNotes(renderStableNotes([], { marked: true }))).toBeNull();+ });++ test('a release with no entries says so and carries no marker, so the docs keep CHANGELOG.md', () => {+ expect(renderStableNotes([], { marked: true })).toBe(`${EMPTY_NOTES}\n`);+ });+});++describe('renderStableNotes matches what `changeset version` writes to the CLI changelog', () => {+ const entries = {+ 'b-multi': {+ level: 'patch',+ summary:+ 'A fix with detail.\n\nThe second paragraph explains it.\n\n- a nested point\n- another point\n\nA closing paragraph.',+ },+ 'a-feature': { level: 'minor', summary: 'Add a feature.' },+ 'c-plain': {+ level: 'patch',+ summary: 'A plain one-line fix with `code` and a [link](https://example.com).',+ },+ 'c-plain-tail': { level: 'patch', summary: 'Sorted before c-plain.md by file name.' },+ 'd-fence': {+ level: 'patch',+ summary: 'A fix with a fence.\n\n```sh\nok start\n\nok stop\n```',+ },+ };++ test('byte for byte, once the commit hash is stripped', () => {+ const root = tempDir('stable-notes-changesets-oracle-');+ writeFileSync(+ join(root, 'package.json'),+ JSON.stringify({ name: OK, version: '0.1.0' }, null, 2),+ );+ mkdirSync(join(root, '.changeset'));+ writeFileSync(+ join(root, '.changeset', 'config.json'),+ JSON.stringify({ changelog: '@changesets/cli/changelog', commit: false, fixed: [[OK]] }),+ );+ for (const [id, { level, summary }] of Object.entries(entries)) {+ writeFileSync(join(root, '.changeset', `${id}.md`), changeset(`"${OK}": ${level}`, summary));+ }+ git(root, ['init', '-q', '-b', 'main']);+ configureTestGitRepository(root);+ git(root, ['add', '-A']);+ git(root, [+ '-c',+ 'user.name=t',+ '-c',+ '[email protected]',+ 'commit',+ '-q',+ '-m',+ 'changesets',+ ]);++ const bin = createRequire(join(OK_ROOT, 'package.json')).resolve('@changesets/cli/bin.js');+ const res = spawnSync(process.execPath, [bin, 'version'], {+ cwd: root,+ env: gitCleanEnv(),+ encoding: 'utf8',+ });+ expect(res.status, res.stderr).toBe(0);++ const changelog = readFileSync(join(root, 'CHANGELOG.md'), 'utf8');+ const heading = changelog.indexOf('## 0.2.0');+ expect(heading).toBeGreaterThan(-1);+ const section = changelog+ .slice(heading + '## 0.2.0'.length)+ .replace(/^(\s*[-*] )[0-9a-f]{6,40}: /gm, '$1')+ .trim();+ const rendered = renderStableNotes(+ Object.entries(entries).map(([id, entry]) => ({ id, ...entry })),+ { marked: true },+ );+ expect(rendered).toBe(`${section}\n\n${NOTES_SOURCE_MARKER}\n`);+ });+});++describe('section levels match the CLI changelog `changeset version` writes for a fixed group', () => {+ test('a changeset naming the CLI is filed under its CLI bump, not the group maximum', () => {+ const root = tempDir('stable-notes-changesets-levels-');+ writeFileSync(+ join(root, 'package.json'),+ JSON.stringify({ name: 'root', private: true, workspaces: ['packages/*'] }, null, 2),+ );+ for (const [dir, name] of [+ ['cli', OK],+ ['core', CORE],+ ]) {+ mkdirSync(join(root, 'packages', dir), { recursive: true });+ writeFileSync(+ join(root, 'packages', dir, 'package.json'),+ JSON.stringify({ name, version: '0.1.0' }, null, 2),+ );+ }+ mkdirSync(join(root, '.changeset'));+ const config = { changelog: '@changesets/cli/changelog', commit: false, fixed: [[OK, CORE]] };+ writeFileSync(join(root, '.changeset', 'config.json'), JSON.stringify(config));+ const files = {+ 'a-mixed': changeset(`"${CORE}": minor\n"${OK}": patch`, 'Core minor, CLI patch.'),+ 'b-cli-minor': changeset(`"${OK}": minor`, 'A CLI feature.'),+ };+ for (const [id, text] of Object.entries(files)) {+ writeFileSync(join(root, '.changeset', `${id}.md`), text);+ }+ git(root, ['init', '-q', '-b', 'main']);+ configureTestGitRepository(root);+ git(root, ['add', '-A']);+ git(root, [+ '-c',+ 'user.name=t',+ '-c',+ '[email protected]',+ 'commit',+ '-q',+ '-m',+ 'changesets',+ ]);++ const bin = createRequire(join(OK_ROOT, 'package.json')).resolve('@changesets/cli/bin.js');+ const res = spawnSync(process.execPath, [bin, 'version'], {+ cwd: root,+ env: gitCleanEnv(),+ encoding: 'utf8',+ });+ expect(res.status, res.stderr).toBe(0);++ const changelog = readFileSync(join(root, 'packages', 'cli', 'CHANGELOG.md'), 'utf8');+ const heading = changelog.indexOf('## 0.2.0');+ expect(heading).toBeGreaterThan(-1);+ const section = changelog+ .slice(heading + '## 0.2.0'.length)+ .replace(/^(\s*[-*] )[0-9a-f]{6,40}: /gm, '$1')+ .trim();+ const reader = noteReaderAt(root);+ const head = reader.revParse('HEAD');+ const rendered = renderStableNotes(+ Object.keys(files).map((id) => ({+ id,+ level: reader.noteLevelOf(head, id),+ summary: changesetSummary(reader.changesetText(head, id)),+ })),+ { marked: true },+ );+ expect(rendered).toBe(`${section}\n\n${NOTES_SOURCE_MARKER}\n`);+ expect(section).toMatch(/### Patch Changes\n\n- Core minor, CLI patch\./);+ });+});++describe('changesetSummary', () => {+ test('reads the text after the frontmatter, trimmed, as @changesets/parse does', () => {+ expect(changesetSummary(`---\n"${OK}": patch\n---\n\n A fix.\n\nMore.\n\n`)).toBe(+ 'A fix.\n\nMore.',+ );+ });++ test('refuses a file with no frontmatter', () => {+ expect(() => changesetSummary('Just text.\n')).toThrow(/no frontmatter/);+ });+});++describe('noteLevel', () => {+ test('is the bump a changeset declares for the CLI package when it names the CLI', () => {+ const releases = [+ { name: OK, type: 'patch' },+ { name: CORE, type: 'minor' },+ { name: '@inkeep/open-knowledge-docs', type: 'major' },+ ];+ expect(noteLevel(releases, FIXED)).toBe('patch');+ });++ test('is the highest fixed-group bump when the changeset does not name the CLI', () => {+ const releases = [+ { name: '@inkeep/open-knowledge-desktop', type: 'patch' },+ { name: CORE, type: 'minor' },+ { name: '@inkeep/open-knowledge-docs', type: 'major' },+ ];+ expect(noteLevel(releases, FIXED)).toBe('minor');+ });++ test('falls back to the fixed group when the changeset declares `none` for the CLI', () => {+ const releases = [+ { name: OK, type: 'none' },+ { name: '@inkeep/open-knowledge-desktop', type: 'patch' },+ ];+ expect(noteLevel(releases, FIXED)).toBe('patch');+ });++ test('is null for a changeset that names no fixed-group package or only `none`', () => {+ expect(noteLevel([{ name: '@inkeep/open-knowledge-docs', type: 'patch' }], FIXED)).toBeNull();+ expect(noteLevel([{ name: OK, type: 'none' }], FIXED)).toBeNull();+ });++ test('reads the fixed group that contains the CLI package from the Changesets config', () => {+ expect(fixedGroupOf(JSON.parse(CONFIG))).toEqual(FIXED);+ expect(fixedGroupOf({ fixed: [['other-a', 'other-b']] })).toEqual([OK]);+ expect(fixedGroupOf({})).toEqual([OK]);+ });+});++describe('collectStableNotes over a release history', () => {+ test('lists only changesets no other stable tag carries, with their text at the commit', () => {+ const h = releaseHistory();+ const a = h.commit('A', { 'x-fix.md': changeset(`"${OK}": patch`, 'X shipped in A.') });+ h.tag('v1.0.0', a);+ h.commit('B', { 'y-fix.md': changeset(`"${OK}": patch`, 'Y as first written.') });+ const c = h.commit('C', {+ 'y-fix.md': changeset(`"${OK}": patch`, 'Y as it ships.'),+ 'z-feature.md': changeset(`"${CORE}": minor`, 'Z.'),+ 'docs-only.md': changeset('"@inkeep/open-knowledge-docs": patch', 'Docs only.'),+ });++ const notes = collectStableNotes({ commit: c, excludeTags: ['v1.1.0'] }, noteReaderAt(h.base));+ expect(notes).toEqual([+ { id: 'y-fix', level: 'patch', summary: 'Y as it ships.' },+ { id: 'z-feature', level: 'minor', summary: 'Z.' },+ ]);+ });++ test('a changeset a revert point release removed stays released for every later stable', () => {+ const h = releaseHistory();+ const a = h.commit('A', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') });+ h.tag('v1.0.0', a);+ const main = h.commit('main after A', { 'y-fix.md': changeset(`"${OK}": patch`, 'Y.') });+ git(h.root, ['checkout', '-q', '--detach', a]);+ const revert = h.commit('revert X', {}, ['x-fix.md']);+ h.tag('v1.0.1', revert);+ git(h.root, ['checkout', '-q', 'main']);+ expect(git(h.root, ['ls-tree', '--name-only', main, '--', '.changeset/'])).toContain(+ 'x-fix.md',+ );++ const reader = noteReaderAt(h.base);+ const notes = collectStableNotes({ commit: main, excludeTags: ['v1.1.0'] }, reader);+ expect(notes.map((entry) => entry.id)).toEqual(['y-fix']);+ });++ test('the tag being rendered is excluded, so a re-run renders the same notes', () => {+ const h = releaseHistory();+ h.tag('v1.0.0', h.commit('A', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') }));+ const b = h.commit('B', { 'y-fix.md': changeset(`"${OK}": patch`, 'Y.') });+ h.tag('v1.0.1', b);+ const reader = noteReaderAt(h.base);+ expect(+ collectStableNotes({ commit: b, excludeTags: ['v1.0.1'] }, reader).map((e) => e.id),+ ).toEqual(['y-fix']);+ expect(collectStableNotes({ commit: b }, reader)).toEqual([]);+ });++ test('with no stable tag at all every changeset in the tree is rendered', () => {+ const h = releaseHistory();+ const a = h.commit('A', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') });+ expect(collectStableNotes({ commit: a }, noteReaderAt(h.base)).map((e) => e.id)).toEqual([+ 'x-fix',+ ]);+ });++ test('from a monorepo subtree it reads the subtree .changeset', () => {+ const h = releaseHistory({ subtree: 'public/open-knowledge' });+ const a = h.commit('A', { 'x-fix.md': changeset(`"${OK}": minor`, 'X.') });+ expect(collectStableNotes({ commit: a }, noteReaderAt(h.base))).toEqual([+ { id: 'x-fix', level: 'minor', summary: 'X.' },+ ]);+ });+});++describe('only stable tags whose Release published count as released', () => {+ test('a stable whose Release never published releases nothing, so the next one lists its changesets', () => {+ const h = releaseHistory();+ h.tag('v0.9.0', h.commit('A', { 'w-fix.md': changeset(`"${OK}": patch`, 'W.') }));+ h.tag('v1.0.0', h.commit('B', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') }));+ const c = h.commit('C', { 'y-fix.md': changeset(`"${OK}": patch`, 'Y.') });+ const reader = noteReaderAt(h.base);++ const published = collectStableNotes(+ { commit: c, excludeTags: ['v1.0.1'], releasedTags: ['v0.9.0'] },+ reader,+ );+ expect(published.map((entry) => entry.id)).toEqual(['x-fix', 'y-fix']);+ expect(+ collectStableNotes({ commit: c, excludeTags: ['v1.0.1'] }, reader).map((entry) => entry.id),+ ).toEqual(['y-fix']);+ });++ test('the marker follows the released set: only a published list marks the body', () => {+ const h = releaseHistory();+ h.tag('v0.9.0', h.commit('A', { 'w-fix.md': changeset(`"${OK}": patch`, 'W.') }));+ h.tag('v1.0.0', h.commit('B', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') }));+ const c = h.commit('C', { 'y-fix.md': changeset(`"${OK}": patch`, 'Y.') });+ const reader = noteReaderAt(h.base);++ expect(+ stableNotes({ commit: c, excludeTags: ['v1.0.1'], publishedTags: ['v0.9.0'] }, reader),+ ).toBe(`### Patch Changes\n\n- X.\n- Y.\n\n${NOTES_SOURCE_MARKER}\n`);+ expect(stableNotes({ commit: c, excludeTags: ['v1.0.1'] }, reader)).toBe(+ '### Patch Changes\n\n- Y.\n',+ );+ });++ test('a render that is not asked to mark keeps the notes and drops only the marker', () => {+ const entries = [{ id: 'a-fix', level: 'patch', summary: 'A fix.' }];+ expect(renderStableNotes(entries)).toBe('### Patch Changes\n\n- A fix.\n');+ });+});++describe('note levels carry the Changesets read from the reader job to the release job', () => {+ test('levels recorded where the reader ran answer the same blobs where it cannot run', () => {+ const h = releaseHistory();+ const a = h.commit('A', {+ 'x-fix.md': changeset(`"${OK}": patch`, 'X.'),+ 'y-feature.md': changeset(`"${CORE}": minor`, 'Y.'),+ });+ const levels = new Map();+ const read = collectStableNotes({ commit: a }, recordNoteLevels(noteReaderAt(h.base), levels));+ expect([...levels.values()].sort()).toEqual(['minor', 'patch']);++ const noReader = withNoteLevels(+ {+ ...noteReaderAt(h.base),+ noteLevelOf: () => {+ throw new Error('the Changesets reader is not installed in this job');+ },+ },+ levels,+ );+ expect(collectStableNotes({ commit: a }, noReader)).toEqual(read);++ const later = h.commit('B', { 'z-fix.md': changeset(`"${OK}": patch`, 'Z.') });+ expect(() => collectStableNotes({ commit: later }, noReader)).toThrow(+ /no note level for \.changeset\/z-fix\.md/,+ );+ });++ test('parseNoteLevels names the note_levels output when it is missing', () => {+ expect(() => parseNoteLevels('')).toThrow(+ /^NOTE_LEVELS is empty: the read-bumps job wrote no note_levels output/,+ );+ expect(parseNoteLevels('{"abc":null}')).toEqual(new Map([['abc', null]]));+ expect(() => parseNoteLevels('[]')).toThrow(+ 'note levels must be a JSON object mapping changeset blob ids to release-note levels.',+ );+ });+});++describe('parseArgs', () => {+ test('reads the commit, repeated exclusions and the read-levels mode, ignoring an empty exclusion', () => {+ expect(+ parseArgs([+ '--commit',+ 'abc',+ '--exclude-tag',+ 'v1.0.0',+ '--exclude-tag',+ '',+ '--read-levels',+ ]),+ ).toEqual({+ readLevels: true,+ commit: 'abc',+ excludeTags: ['v1.0.0'],+ releasesFile: '',+ });+ expect(parseArgs(['--commit', 'abc', '--releases', '/tmp/r']).releasesFile).toBe('/tmp/r');+ });++ test('refuses a missing commit and unknown arguments', () => {+ expect(() => parseArgs([])).toThrow(/--commit <sha> is required/);+ expect(() => parseArgs(['--commit', 'abc', '--bogus'])).toThrow(/unknown argument '--bogus'/);+ });+});++describe('the release job renders the notes with no node_modules at all', () => {+ const SCRIPT_FILES = [+ 'render-stable-notes.mjs',+ 'compute-stable-version.mjs',+ 'compute-next-beta.mjs',+ 'git-clean-env.mjs',+ ];++ function isolatedScript() {+ const dir = tempDir('stable-notes-no-node-modules-');+ mkdirSync(join(dir, 'scripts'));+ for (const file of SCRIPT_FILES) copyFileSync(join(SCRIPTS, file), join(dir, 'scripts', file));+ mkdirSync(join(dir, '.github', 'scripts'), { recursive: true });+ copyFileSync(+ join(OK_ROOT, '.github', 'scripts', 'shipped-fix-containment.mjs'),+ join(dir, '.github', 'scripts', 'shipped-fix-containment.mjs'),+ );+ return join(dir, 'scripts', 'render-stable-notes.mjs');+ }++ function releaseListing(releases) {+ const file = join(tempDir('stable-notes-releases-'), 'releases.jsonl');+ const lines = releases.map(([tag, draft]) =>+ JSON.stringify({ tag_name: tag, draft, body: '' }),+ );+ writeFileSync(file, lines.join('\n'));+ return file;+ }++ function run(script, cwd, args, env = {}) {+ const outDir = tempDir('stable-notes-output-');+ const output = join(outDir, 'github-output');+ writeFileSync(output, '');+ const { NOTE_LEVELS: _inherited, ...base } = gitCleanEnv();+ const res = spawnSync(process.execPath, [script, ...args], {+ cwd,+ encoding: 'utf8',+ env: { ...base, GITHUB_OUTPUT: output, ...env },+ });+ return { ...res, output: readFileSync(output, 'utf8') };+ }++ test('the reader job records note_levels and the release job renders byte-identical notes from them', () => {+ const h = releaseHistory();+ h.tag('v1.0.0', h.commit('A', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') }));+ const b = h.commit('B', {+ 'y-fix.md': changeset(`"${OK}": patch`, 'Y.'),+ 'z-feature.md': changeset(`"${CORE}": minor`, 'Z.'),+ });+ const releases = releaseListing([+ ['v1.0.0', false],+ ['v1.1.0-beta.1', false],+ ]);+ const args = ['--commit', b, '--exclude-tag', 'v1.1.0', '--releases', releases];++ const withReader = run(join(SCRIPTS, 'render-stable-notes.mjs'), h.root, args);+ expect(withReader.status, withReader.stderr).toBe(0);+ expect(withReader.stdout).toBe(+ `### Minor Changes\n\n- Z.\n\n### Patch Changes\n\n- Y.\n\n${NOTES_SOURCE_MARKER}\n`,+ );++ const reading = run(join(SCRIPTS, 'render-stable-notes.mjs'), h.root, [+ '--commit',+ b,+ '--read-levels',+ ]);+ expect(reading.status, reading.stderr).toBe(0);+ const levels = /^note_levels=(.*)$/m.exec(reading.output)?.[1];+ expect(Object.values(JSON.parse(levels ?? '{}')).sort()).toEqual(['minor', 'patch', 'patch']);++ const isolated = run(isolatedScript(), h.root, args, { NOTE_LEVELS: levels });+ expect(isolated.status, isolated.stderr).toBe(0);+ expect(isolated.stdout).toBe(withReader.stdout);+ });++ test('a stable tag whose Release is still a draft releases nothing, so its changesets are listed again', () => {+ const h = releaseHistory();+ h.tag('v0.9.0', h.commit('A', { 'w-fix.md': changeset(`"${OK}": patch`, 'W.') }));+ h.tag('v1.0.0', h.commit('B', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') }));+ const c = h.commit('C', { 'y-fix.md': changeset(`"${OK}": patch`, 'Y.') });+ const releases = releaseListing([+ ['v0.9.0', false],+ ['v1.0.0', true],+ ]);+ const res = run(join(SCRIPTS, 'render-stable-notes.mjs'), h.root, [+ '--commit',+ c,+ '--releases',+ releases,+ ]);+ expect(res.status, res.stderr).toBe(0);+ expect(res.stdout).toBe(`### Patch Changes\n\n- X.\n- Y.\n\n${NOTES_SOURCE_MARKER}\n`);+ });++ test('when the published Releases cannot be read the notes carry no marker and warn they may omit changesets', () => {+ const h = releaseHistory();+ h.tag('v1.0.0', h.commit('A', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') }));+ const b = h.commit('B', { 'y-fix.md': changeset(`"${OK}": patch`, 'Y.') });+ const res = run(join(SCRIPTS, 'render-stable-notes.mjs'), h.root, [+ '--commit',+ b,+ '--releases',+ releaseListing([]),+ ]);+ expect(res.status, res.stderr).toBe(0);+ expect(res.stdout).toBe('### Patch Changes\n\n- Y.\n');+ expect(res.stderr).toMatch(+ /::warning::render-stable-notes: could not read the published stable Releases \(.*holds no stable Release/,+ );+ expect(res.stderr).toMatch(+ /may leave out changesets first tagged in a stable whose Release never published/,+ );+ });++ test('without note levels the isolated copy cannot load the reader, so the run above never tried', () => {+ const h = releaseHistory();+ const a = h.commit('A', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') });+ const res = run(isolatedScript(), h.root, ['--commit', a, '--releases', releaseListing([])]);+ expect(res.status).toBe(1);+ expect(res.stderr).toMatch(/@changesets\/cli/);+ expect(res.stdout).toBe('');+ });+});