Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@
- 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.
- 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.
Expand Down
14 changes: 14 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
46 changes: 25 additions & 21 deletions scripts/release-prep.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand All @@ -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() {
Expand Down Expand Up @@ -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) {
Expand All @@ -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.`);
}
}
Expand All @@ -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) {
Expand All @@ -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}`]);
}
Expand Down Expand Up @@ -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}`);
Expand All @@ -304,20 +304,24 @@ 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);
commitAndTag(pkg.version);

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;
Expand Down
134 changes: 134 additions & 0 deletions scripts/releasePrep.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
import { expect, test } from 'bun:test';
import { execFileSync, spawnSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { 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 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: globalConfig,
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 {
mkdirSync(root);
writeFileSync(globalConfig, '');
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(directory, { 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');
});
});
Loading