From 8650f522fc6f8a25a5c9311178c95bf522b5751a Mon Sep 17 00:00:00 2001 From: Bradley Hilton Date: Thu, 12 Nov 2026 16:23:59 -0600 Subject: [PATCH 1/2] fix: repair release preparation metadata workflow --- CHANGELOG.md | 1 + README.md | 14 ++++ scripts/release-prep.mjs | 46 +++++++------ scripts/releasePrep.test.mjs | 129 +++++++++++++++++++++++++++++++++++ 4 files changed, 169 insertions(+), 21 deletions(-) create mode 100644 scripts/releasePrep.test.mjs diff --git a/CHANGELOG.md b/CHANGELOG.md index b0404b8..47f18f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ - Upgrade vulnerable production dependencies (markdown-it, mermaid, sanitize-html, katex, Puppeteer, cspell, highlight.js, Shiki) and remove unused gRPC packages; `npm audit --omit=dev` is clean. - Load Puppeteer 25 as an ESM runtime and make webview/graph build steps cross-platform. - Add CI for typecheck, tests, build, universal VSIX packaging, and production audit; set the public `atomicdotdev` publisher metadata and 1.0.0 version. +- Fix release preparation on the `release` branch, synchronize and commit lockfile versions, and accept dated changelog headings without requiring a horizontal-rule separator. ## 0.2.12 - Package one universal, JavaScript-only VSIX; Atomic's platform library is supplied by the separate Atomic installation on the extension host. diff --git a/README.md b/README.md index 73345ef..8194ebd 100644 --- a/README.md +++ b/README.md @@ -120,6 +120,20 @@ For a browser-only demo after building, run `npm run preview` and open `http://1 With the preview running and Chrome/Edge installed, `npm run test:browser` runs the browser smoke check. `CHROME_PATH` can select an executable; `SCREENSHOT_PATH` optionally saves a screenshot. +### Prepare a future release + +Run the helper from a clean `release` branch. These commands bump the version; they are not needed merely to publish the already-prepared 1.0.0 package. + +```sh +npm run release:prep -- patch --dry-run +npm run release:prep -- patch +# Review package.json, package-lock.json, and CHANGELOG.md. +npm run release:finalize +``` + +Preparation synchronizes the manifest version and both lockfile version fields, then inserts release notes before the existing changelog sections. Finalization accepts either `## 1.2.3` or `## 1.2.3 - YYYY-MM-DD`, checks that all version fields match, and commits only those three release files before creating a local annotated tag. Unrelated working-tree changes are rejected. The helper prints the commands to push the `release` branch and tag; it does not push, package, or publish anything. + + ## Preservation and safety The presentation parser never serializes the whole Markdown or YAML document. Field edits preserve unrelated text, unknown attributes, evidence, quotation style, and comments. Conflicting external source changes keep the active draft and block Save rather than overwriting the changed file. Unsafe prose that would prematurely close a directive is rejected. diff --git a/scripts/release-prep.mjs b/scripts/release-prep.mjs index 0131e2b..6257ddb 100644 --- a/scripts/release-prep.mjs +++ b/scripts/release-prep.mjs @@ -56,10 +56,10 @@ function bumpVersion(currentVersion, mode) { return mode; } -function ensureMainBranch() { +function ensureReleaseBranch() { const branch = tryGit(["symbolic-ref", "--quiet", "--short", "HEAD"]); - if (!branch) fail("HEAD is detached. Switch to main before running release prep."); - if (branch !== "main") fail(`Current branch is '${branch}'. Switch to 'main' first.`); + if (!branch) fail("HEAD is detached. Switch to release before running release prep."); + if (branch !== "release") fail(`Current branch is '${branch}'. Switch to 'release' first.`); } function ensureCleanTree() { @@ -86,8 +86,13 @@ function readPackageJson() { return { raw, data: JSON.parse(raw) }; } -function writePackageJson(pkg) { +function writePackageVersions(pkg, version) { + const lock = JSON.parse(fs.readFileSync("package-lock.json", "utf8")); + pkg.version = version; + lock.version = version; + lock.packages[""].version = version; fs.writeFileSync("package.json", `${JSON.stringify(pkg, null, 2)}\n`); + fs.writeFileSync("package-lock.json", `${JSON.stringify(lock, null, 2)}\n`); } function latestTag() { @@ -210,16 +215,11 @@ function prependChangelog(version, items) { const changelogPath = "CHANGELOG.md"; const current = fs.readFileSync(changelogPath, "utf8"); - const marker = "---\n"; - const idx = current.indexOf(marker); - if (idx === -1) { - fail("CHANGELOG.md is missing the expected '---' separator."); - } - - const insertAt = idx + marker.length; + const idx = current.search(/^##[ \t]+/m); + const prefix = idx === -1 ? `${current.trimEnd()}\n\n` : current.slice(0, idx); + const suffix = idx === -1 ? "" : current.slice(idx); const section = formatChangelogSection(version, items); - const next = `${current.slice(0, insertAt)}${section}${current.slice(insertAt)}`; - fs.writeFileSync(changelogPath, next); + fs.writeFileSync(changelogPath, `${prefix}${section}${suffix}`); } function ensureTagDoesNotExist(tag) { @@ -229,7 +229,8 @@ function ensureTagDoesNotExist(tag) { function ensureChangelogHasVersion(version) { const changelog = fs.readFileSync("CHANGELOG.md", "utf8"); - if (!changelog.includes(`## ${version}\n`)) { + const heading = new RegExp(`^##[ \\t]+${version.replaceAll(".", "\\.")}(?:[ \\t]+-[ \\t]+\\d{4}-\\d{2}-\\d{2})?[ \\t]*\\r?$`, "m"); + if (!heading.test(changelog)) { fail(`CHANGELOG.md does not contain a '## ${version}' section.`); } } @@ -240,7 +241,7 @@ function ensureOnlyReleaseFilesChanged() { fail("No local changes found. Run prepare first."); } - const allowed = new Set(["package.json", "CHANGELOG.md"]); + const allowed = new Set(["package.json", "package-lock.json", "CHANGELOG.md"]); const disallowed = []; for (const line of statusLines) { @@ -251,14 +252,14 @@ function ensureOnlyReleaseFilesChanged() { } if (disallowed.length > 0) { - console.error("ERROR: Finalize only allows local changes in package.json and CHANGELOG.md."); + console.error("ERROR: Finalize only allows local changes in package.json, package-lock.json and CHANGELOG.md."); disallowed.forEach((line) => console.error(` ${line}`)); process.exit(1); } } function commitAndTag(version) { - runGit(["add", "package.json", "CHANGELOG.md"]); + runGit(["add", "package.json", "package-lock.json", "CHANGELOG.md"]); runGit(["commit", "-m", `chore: update version to ${version}`]); runGit(["tag", "-a", version, "-m", `v${version}`]); } @@ -290,8 +291,7 @@ function prepareRelease(versionOrBump, write) { process.exit(0); } - pkg.version = nextVersion; - writePackageJson(pkg); + writePackageVersions(pkg, nextVersion); prependChangelog(nextVersion, changelogItems); console.log(`Release draft prepared locally for ${nextVersion}`); @@ -304,6 +304,10 @@ function finalizeRelease() { const { data: pkg } = readPackageJson(); if (!pkg.version) fail("package.json is missing a version field."); + const lock = JSON.parse(fs.readFileSync("package-lock.json", "utf8")); + if (lock.version !== pkg.version || lock.packages[""].version !== pkg.version) { + fail("package-lock.json versions must match package.json before finalizing."); + } ensureTagDoesNotExist(pkg.version); ensureChangelogHasVersion(pkg.version); @@ -311,13 +315,13 @@ function finalizeRelease() { console.log(`Release finalized locally for ${pkg.version}`); console.log("Next steps:"); - console.log(" git push origin main"); + console.log(" git push origin release"); console.log(` git push origin ${pkg.version}`); } function main() { const args = parseArgs(process.argv.slice(2)); - ensureMainBranch(); + ensureReleaseBranch(); if (args.mode === "finalize") { finalizeRelease(); return; diff --git a/scripts/releasePrep.test.mjs b/scripts/releasePrep.test.mjs new file mode 100644 index 0000000..85ab5c0 --- /dev/null +++ b/scripts/releasePrep.test.mjs @@ -0,0 +1,129 @@ +import { expect, test } from 'bun:test'; +import { execFileSync, spawnSync } from 'node:child_process'; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { devNull, tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const helper = fileURLToPath(new URL('./release-prep.mjs', import.meta.url)); +const releaseFiles = ['package.json', 'package-lock.json', 'CHANGELOG.md']; + +function withRepository(run, branch = 'release') { + const root = mkdtempSync(join(tmpdir(), 'sherpa-release-prep-')); + const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))); + Object.assign(env, { + GIT_CONFIG_GLOBAL: devNull, + GIT_CONFIG_NOSYSTEM: '1', + GIT_AUTHOR_NAME: 'Release test', + GIT_AUTHOR_EMAIL: 'release-test@example.invalid', + GIT_COMMITTER_NAME: 'Release test', + GIT_COMMITTER_EMAIL: 'release-test@example.invalid', + }); + const git = (...args) => execFileSync('git', args, { cwd: root, env, encoding: 'utf8', stdio: 'pipe' }).trim(); + const read = (file) => readFileSync(join(root, file), 'utf8'); + const write = (file, text) => writeFileSync(join(root, file), text); + const json = (file) => JSON.parse(read(file)); + const writeJson = (file, value) => write(file, `${JSON.stringify(value, null, 2)}\n`); + const invoke = (...args) => spawnSync(process.execPath, [helper, ...args], { + cwd: root, env, encoding: 'utf8', timeout: 15_000, + }); + try { + git('init', '-b', branch); + git('config', 'core.autocrlf', 'false'); + writeJson('package.json', { name: 'release-fixture', version: '1.0.0' }); + writeJson('package-lock.json', { + name: 'release-fixture', version: '1.0.0', lockfileVersion: 3, + packages: { + '': { name: 'release-fixture', version: '1.0.0' }, + 'node_modules/example': { version: '2.3.4', optional: true }, + }, + }); + write('CHANGELOG.md', '# Release fixture\n\n## 1.0.0 - 2026-11-05\n- Existing release\n'); + git('add', ...releaseFiles); + git('commit', '-m', 'fix: preserve release metadata'); + return run({ git, read, write, json, writeJson, invoke }); + } finally { + rmSync(root, { recursive: true, force: true }); + } +} + +for (const dated of [false, true]) { + test(`prepare and finalize preserve synchronized committed metadata with ${dated ? 'dated' : 'undated'} headings`, () => { + withRepository((repo) => { + const before = releaseFiles.map(repo.read); + const dependencies = repo.json('package-lock.json').packages['node_modules/example']; + expect(repo.invoke('patch', '--dry-run').status).toBe(0); + expect(releaseFiles.map(repo.read)).toEqual(before); + expect(repo.git('tag', '--list')).toBe(''); + + expect(repo.invoke('patch').status).toBe(0); + expect(repo.json('package.json').version).toBe('1.0.1'); + const lock = repo.json('package-lock.json'); + expect(lock.version).toBe('1.0.1'); + expect(lock.packages[''].version).toBe('1.0.1'); + expect(lock.packages['node_modules/example']).toEqual(dependencies); + const changelog = repo.read('CHANGELOG.md'); + expect(changelog.indexOf('## 1.0.1\n')).toBeLessThan(changelog.indexOf('## 1.0.0 - 2026-11-05')); + if (dated) repo.write('CHANGELOG.md', changelog.replace('## 1.0.1\n', '## 1.0.1 - 2026-11-12\n')); + const reviewedChangelog = repo.read('CHANGELOG.md'); + + expect(repo.invoke('finalize').status).toBe(0); + expect(repo.git('rev-parse', '1.0.1^{commit}')).toBe(repo.git('rev-parse', 'HEAD')); + expect(JSON.parse(repo.git('show', '1.0.1:package.json')).version).toBe('1.0.1'); + const committedLock = JSON.parse(repo.git('show', '1.0.1:package-lock.json')); + expect(committedLock.version).toBe('1.0.1'); + expect(committedLock.packages[''].version).toBe('1.0.1'); + expect(repo.git('show', '1.0.1:CHANGELOG.md')).toBe(reviewedChangelog.trim()); + expect(repo.git('status', '--porcelain')).toBe(''); + }); + }); +} + +for (const mode of ['main', 'detached']) { + test(`release preparation rejects ${mode} without modifying release files`, () => { + withRepository((repo) => { + if (mode === 'detached') repo.git('checkout', '--detach'); + const before = releaseFiles.map(repo.read); + const head = repo.git('rev-parse', 'HEAD'); + expect(repo.invoke('patch').status).not.toBe(0); + expect(releaseFiles.map(repo.read)).toEqual(before); + expect(repo.git('rev-parse', 'HEAD')).toBe(head); + expect(repo.git('tag', '--list')).toBe(''); + }, mode === 'main' ? 'main' : 'release'); + }); +} + +for (const field of ['top-level', 'root-package']) { + test(`finalization rejects a mismatched ${field} lockfile version before committing or tagging`, () => { + withRepository((repo) => { + expect(repo.invoke('patch').status).toBe(0); + const lock = repo.json('package-lock.json'); + if (field === 'top-level') lock.version = '1.0.0'; + else lock.packages[''].version = '1.0.0'; + repo.writeJson('package-lock.json', lock); + const head = repo.git('rev-parse', 'HEAD'); + expect(repo.invoke('finalize').status).not.toBe(0); + expect(repo.git('rev-parse', 'HEAD')).toBe(head); + expect(repo.git('tag', '--list')).toBe(''); + }); + }); +} + +test('finalization rejects a different changelog version and unrelated work without creating a release', () => { + withRepository((repo) => { + expect(repo.invoke('patch').status).toBe(0); + const head = repo.git('rev-parse', 'HEAD'); + const changelog = repo.read('CHANGELOG.md'); + repo.write('CHANGELOG.md', changelog.replace('## 1.0.1\n', '## 1.0.10\n')); + expect(repo.invoke('finalize').status).not.toBe(0); + expect(repo.git('rev-parse', 'HEAD')).toBe(head); + expect(repo.git('tag', '--list')).toBe(''); + + repo.write('CHANGELOG.md', changelog); + repo.write('unrelated.txt', 'Do not include in the release commit.\n'); + expect(repo.invoke('finalize').status).not.toBe(0); + expect(repo.git('rev-parse', 'HEAD')).toBe(head); + expect(repo.git('tag', '--list')).toBe(''); + expect(repo.read('unrelated.txt')).toBe('Do not include in the release commit.\n'); + }); +}); From 599bb1b83aef81f767bc6734ddcbc45a76e862b5 Mon Sep 17 00:00:00 2001 From: Bradley Hilton Date: Thu, 12 Nov 2026 16:35:24 -0600 Subject: [PATCH 2/2] test: use a portable Git config for release fixtures --- CHANGELOG.md | 1 + scripts/releasePrep.test.mjs | 15 ++++++++++----- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 47f18f5..6c56540 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ - Load Puppeteer 25 as an ESM runtime and make webview/graph build steps cross-platform. - Add CI for typecheck, tests, build, universal VSIX packaging, and production audit; set the public `atomicdotdev` publisher metadata and 1.0.0 version. - Fix release preparation on the `release` branch, synchronize and commit lockfile versions, and accept dated changelog headings without requiring a horizontal-rule separator. +- Use an empty regular Git configuration file for release regression fixtures instead of an OS null-device path, which Git for Windows rejects. ## 0.2.12 - Package one universal, JavaScript-only VSIX; Atomic's platform library is supplied by the separate Atomic installation on the extension host. diff --git a/scripts/releasePrep.test.mjs b/scripts/releasePrep.test.mjs index 85ab5c0..6352093 100644 --- a/scripts/releasePrep.test.mjs +++ b/scripts/releasePrep.test.mjs @@ -1,7 +1,7 @@ import { expect, test } from 'bun:test'; import { execFileSync, spawnSync } from 'node:child_process'; -import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; -import { devNull, tmpdir } from 'node:os'; +import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { fileURLToPath } from 'node:url'; @@ -9,10 +9,13 @@ const helper = fileURLToPath(new URL('./release-prep.mjs', import.meta.url)); const releaseFiles = ['package.json', 'package-lock.json', 'CHANGELOG.md']; function withRepository(run, branch = 'release') { - const root = mkdtempSync(join(tmpdir(), 'sherpa-release-prep-')); + const directory = mkdtempSync(join(tmpdir(), 'sherpa-release-prep-')); + const root = join(directory, 'repository'); + // Git for Windows needs a regular config file, outside the worktree to keep it clean. + const globalConfig = join(directory, 'gitconfig'); const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))); Object.assign(env, { - GIT_CONFIG_GLOBAL: devNull, + GIT_CONFIG_GLOBAL: globalConfig, GIT_CONFIG_NOSYSTEM: '1', GIT_AUTHOR_NAME: 'Release test', GIT_AUTHOR_EMAIL: 'release-test@example.invalid', @@ -28,6 +31,8 @@ function withRepository(run, branch = 'release') { cwd: root, env, encoding: 'utf8', timeout: 15_000, }); try { + mkdirSync(root); + writeFileSync(globalConfig, ''); git('init', '-b', branch); git('config', 'core.autocrlf', 'false'); writeJson('package.json', { name: 'release-fixture', version: '1.0.0' }); @@ -43,7 +48,7 @@ function withRepository(run, branch = 'release') { git('commit', '-m', 'fix: preserve release metadata'); return run({ git, read, write, json, writeJson, invoke }); } finally { - rmSync(root, { recursive: true, force: true }); + rmSync(directory, { recursive: true, force: true }); } }