calver-bump 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# calver-bump
+
+Release CLI for applications and internal tools that use readable CalVer versions.
+
+Default version and tag format:
+
+```text
+YYYY.MM.DD.N
+```
+
+Example:
+
+```text
+2026.05.29.1
+```
+
+## What it does
+
+1. Bumps `package.json` to the next CalVer version.
+2. Updates `package-lock.json` or `npm-shrinkwrap.json` when present.
+3. Creates or prepends a `CHANGELOG.md` entry from git commits since the last CalVer tag.
+4. Creates a release commit.
+5. Creates a git tag.
+
+## Usage
+
+```bash
+npx calver-bump
+```
+
+Preview the planned release without writing files:
+
+```bash
+npx calver-bump --dry-run
+```
+
+Use compact CalVer instead:
+
+```bash
+npx calver-bump --format compact
+```
+
+## Notes
+
+- The default `dotted` format is `YYYY.MM.DD.N`.
+- The optional `compact` format is `YYYYMMDD.N`.
+- Existing `v`-prefixed tags are considered when calculating the next sequence number.
+- Changelog ranges ignore non-CalVer tags.
+- The working tree must be clean before creating a real release.
+- If tag creation fails after the release commit, the CLI rolls back its own release commit.

package/bin/calver-bump.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { runRelease } from '../src/index.js';
+import { assertFormat } from '../src/calver.js';
+
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const formatIndex = args.indexOf('--format');
+const format = formatIndex >= 0 ? args[formatIndex + 1] : 'dotted';
+
+try {
+  assertFormat(format);
+  const result = await runRelease({ dryRun, format });
+  console.log(`Release version: ${result.version}`);
+  for (const action of result.actions) {
+    console.log(`- ${action}`);
+  }
+  if (!dryRun) {
+    console.log('');
+    console.log('Next steps:');
+    console.log('1. Review the release commit:');
+    console.log('   git show --stat HEAD');
+    console.log('2. Push the release commit and tag:');
+    console.log(`   git push --follow-tags origin ${result.branch}`);
+    console.log('3. Trigger or verify your deployment pipeline.');
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "calver-bump",
+  "version": "0.1.0",
+  "description": "Release CLI for internal applications using readable CalVer versions.",
+  "main": "src/index.js",
+  "bin": {
+    "calver-bump": "bin/calver-bump.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "release",
+    "calver",
+    "changelog",
+    "git-tag"
+  ],
+  "author": "",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/calver.js

@@ -0,0 +1,41 @@
+export function nextCalVer({ date = new Date(), existingTags = [], format = 'dotted' } = {}) {
+  assertFormat(format);
+  const parts = dateParts(date);
+  const prefix = format === 'compact'
+    ? `${parts.year}${parts.month}${parts.day}`
+    : `${parts.year}.${parts.month}.${parts.day}`;
+  const matcher = new RegExp(`^v?${escapeRegExp(prefix)}\\.(\\d+)$`);
+  const highest = existingTags.reduce((max, tag) => {
+    const match = matcher.exec(tag.trim());
+    if (!match) return max;
+    return Math.max(max, Number(match[1]));
+  }, 0);
+
+  return `${prefix}.${highest + 1}`;
+}
+
+export function assertFormat(format) {
+  if (!['dotted', 'compact'].includes(format)) {
+    throw new Error(`Invalid format "${format}". Expected "dotted" or "compact".`);
+  }
+}
+
+export function isCalVerTag(tag) {
+  return /^v?\d{4}\.\d{2}\.\d{2}\.\d+$/.test(tag) || /^v?\d{8}\.\d+$/.test(tag);
+}
+
+export function isoDate(date = new Date()) {
+  const parts = dateParts(date);
+  return `${parts.year}-${parts.month}-${parts.day}`;
+}
+
+function dateParts(date) {
+  const year = String(date.getFullYear());
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return { year, month, day };
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/index.js

@@ -0,0 +1,169 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { access, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+import { isoDate, isCalVerTag, nextCalVer } from './calver.js';
+
+const execFile = promisify(execFileCallback);
+
+export async function planRelease(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const existingTags = options.existingTags ?? await gitLines(cwd, ['tag', '--list']);
+  const version = nextCalVer({
+    date: options.date,
+    existingTags,
+    format: options.format ?? 'dotted',
+  });
+
+  return {
+    version,
+    branch: await currentBranch(cwd),
+    actions: releaseActions(version),
+  };
+}
+
+export async function runRelease(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const plan = await planRelease(options);
+
+  if (options.dryRun) {
+    return plan;
+  }
+
+  await assertCleanWorktree(cwd);
+  await updatePackageVersion(cwd, plan.version);
+  await updatePackageLock(cwd, plan.version);
+  await prependChangelog(cwd, plan.version, options.date ?? new Date());
+  await git(cwd, ['add', ...await releaseFiles(cwd)]);
+  await git(cwd, ['commit', '-m', `chore(release): ${plan.version}`]);
+  try {
+    await git(cwd, ['tag', plan.version]);
+  } catch (error) {
+    await git(cwd, ['reset', '--hard', 'HEAD~1']);
+    throw new Error(`Failed to create git tag ${plan.version}; rolled back release commit. ${error.message}`);
+  }
+
+  return plan;
+}
+
+function releaseActions(version) {
+  return [
+    `update package.json version to ${version}`,
+    `prepend CHANGELOG.md entry for ${version}`,
+    `create git commit chore(release): ${version}`,
+    `create git tag ${version}`,
+  ];
+}
+
+async function updatePackageVersion(cwd, version) {
+  const packagePath = path.join(cwd, 'package.json');
+  const pkg = JSON.parse(await readFile(packagePath, 'utf8'));
+  pkg.version = version;
+  await writeFile(packagePath, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+async function updatePackageLock(cwd, version) {
+  for (const fileName of ['package-lock.json', 'npm-shrinkwrap.json']) {
+    const filePath = path.join(cwd, fileName);
+    let lock;
+    try {
+      lock = JSON.parse(await readFile(filePath, 'utf8'));
+    } catch (error) {
+      if (error.code === 'ENOENT') continue;
+      throw error;
+    }
+
+    if (typeof lock.version === 'string') {
+      lock.version = version;
+    }
+    if (lock.packages?.[''] && typeof lock.packages[''].version === 'string') {
+      lock.packages[''].version = version;
+    }
+
+    await writeFile(filePath, `${JSON.stringify(lock, null, 2)}\n`);
+  }
+}
+
+async function releaseFiles(cwd) {
+  const candidates = ['package.json', 'package-lock.json', 'npm-shrinkwrap.json', 'CHANGELOG.md'];
+  const files = [];
+  for (const candidate of candidates) {
+    if (await fileExists(path.join(cwd, candidate))) {
+      files.push(candidate);
+    }
+  }
+  return files;
+}
+
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function prependChangelog(cwd, version, date) {
+  const changelogPath = path.join(cwd, 'CHANGELOG.md');
+  const changes = await releaseNotes(cwd);
+  const entry = `## ${version} - ${isoDate(date)}\n\n${changes.map((change) => `- ${change}`).join('\n')}\n`;
+  let existing = '';
+
+  try {
+    existing = await readFile(changelogPath, 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+
+  const body = existing.trim().startsWith('# Changelog')
+    ? existing.replace(/^# Changelog\s*/, `# Changelog\n\n${entry}\n`)
+    : `# Changelog\n\n${entry}\n${existing}`;
+
+  await writeFile(changelogPath, body);
+}
+
+async function releaseNotes(cwd) {
+  const latestTag = await latestReachableTag(cwd);
+  const range = latestTag ? [`${latestTag}..HEAD`] : [];
+  const lines = await gitLines(cwd, ['log', '--pretty=%s', ...range]);
+  return lines.length > 0 ? lines : ['Initial internal release.'];
+}
+
+async function latestReachableTag(cwd) {
+  const tags = await gitLines(cwd, [
+    'for-each-ref',
+    '--merged',
+    'HEAD',
+    '--sort=-creatordate',
+    '--format=%(refname:short)',
+    'refs/tags',
+  ]);
+  return tags.find(isCalVerTag) ?? null;
+}
+
+async function currentBranch(cwd) {
+  try {
+    const { stdout } = await git(cwd, ['branch', '--show-current']);
+    return stdout.trim() || 'HEAD';
+  } catch {
+    return 'HEAD';
+  }
+}
+
+async function assertCleanWorktree(cwd) {
+  const status = await gitLines(cwd, ['status', '--porcelain']);
+  if (status.length > 0) {
+    throw new Error('Working tree is not clean. Commit or stash changes before releasing.');
+  }
+}
+
+async function gitLines(cwd, args) {
+  const { stdout } = await git(cwd, args);
+  return stdout.split('\n').map((line) => line.trim()).filter(Boolean);
+}
+
+async function git(cwd, args) {
+  return execFile('git', args, { cwd, encoding: 'utf8' });
+}

package/test/calver.test.js

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { nextCalVer } from '../src/calver.js';
+
+test('nextCalVer defaults to readable dotted format YYYY.MM.DD.N', () => {
+  const version = nextCalVer({
+    date: new Date('2026-05-29T12:00:00-07:00'),
+    existingTags: [],
+  });
+
+  assert.equal(version, '2026.05.29.1');
+});
+
+test('nextCalVer increments the sequence for existing tags on the same day', () => {
+  const version = nextCalVer({
+    date: new Date('2026-05-29T12:00:00-07:00'),
+    existingTags: ['2026.05.28.7', '2026.05.29.1', 'v2026.05.29.2'],
+  });
+
+  assert.equal(version, '2026.05.29.3');
+});
+
+test('nextCalVer can emit compact YYYYMMDD.N when requested', () => {
+  const version = nextCalVer({
+    date: new Date('2026-05-29T12:00:00-07:00'),
+    existingTags: ['20260529.1'],
+    format: 'compact',
+  });
+
+  assert.equal(version, '20260529.2');
+});

package/test/cli.test.js

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { test } from 'node:test';
+
+test('CLI rejects invalid release formats', () => {
+  const result = spawnSync(process.execPath, ['bin/calver-bump.js', '--format', 'nope'], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+  });
+
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /Invalid format/);
+});
+
+test('CLI explains how to push the release commit and tag after a real release', async () => {
+  const repo = await makeRepo();
+  const cliPath = path.resolve('bin/calver-bump.js');
+
+  const result = spawnSync(process.execPath, [cliPath], {
+    cwd: repo,
+    encoding: 'utf8',
+  });
+
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /Next steps:/);
+  assert.match(result.stdout, /git push --follow-tags origin main/);
+});
+
+async function makeRepo() {
+  const repo = await mkdtemp(path.join(tmpdir(), 'calver-bump-cli-'));
+  execFileSync('git', ['init'], { cwd: repo });
+  execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: repo });
+  execFileSync('git', ['config', 'user.name', 'Test User'], { cwd: repo });
+  await writeFile(
+    path.join(repo, 'package.json'),
+    `${JSON.stringify({ name: 'demo-app', version: '0.0.0' }, null, 2)}\n`,
+  );
+  execFileSync('git', ['add', 'package.json'], { cwd: repo });
+  execFileSync('git', ['commit', '-m', 'feat: initial app'], { cwd: repo });
+  return repo;
+}

package/test/release.test.js

@@ -0,0 +1,155 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { test } from 'node:test';
+import { execFileSync } from 'node:child_process';
+
+import { planRelease, runRelease } from '../src/index.js';
+
+test('planRelease reports version, changelog, commit, and tag actions without writing in dry-run mode', async () => {
+  const repo = await makeRepo();
+
+  const plan = await planRelease({
+    cwd: repo,
+    date: new Date('2026-05-29T12:00:00-07:00'),
+    dryRun: true,
+  });
+
+  assert.equal(plan.version, '2026.05.29.1');
+  assert.deepEqual(plan.actions, [
+    'update package.json version to 2026.05.29.1',
+    'prepend CHANGELOG.md entry for 2026.05.29.1',
+    'create git commit chore(release): 2026.05.29.1',
+    'create git tag 2026.05.29.1',
+  ]);
+
+  const pkg = JSON.parse(await readFile(path.join(repo, 'package.json'), 'utf8'));
+  assert.equal(pkg.version, '0.0.0');
+});
+
+test('runRelease updates package.json, prepends changelog, commits, and tags', async () => {
+  const repo = await makeRepo();
+
+  const result = await runRelease({
+    cwd: repo,
+    date: new Date('2026-05-29T12:00:00-07:00'),
+  });
+
+  assert.equal(result.version, '2026.05.29.1');
+
+  const pkg = JSON.parse(await readFile(path.join(repo, 'package.json'), 'utf8'));
+  assert.equal(pkg.version, '2026.05.29.1');
+
+  const changelog = await readFile(path.join(repo, 'CHANGELOG.md'), 'utf8');
+  assert.match(changelog, /^# Changelog\n\n## 2026\.05\.29\.1 - 2026-05-29\n\n- feat: initial app/);
+
+  const tag = execFileSync('git', ['tag', '--list', '2026.05.29.1'], {
+    cwd: repo,
+    encoding: 'utf8',
+  }).trim();
+  assert.equal(tag, '2026.05.29.1');
+
+  const subject = execFileSync('git', ['log', '-1', '--pretty=%s'], {
+    cwd: repo,
+    encoding: 'utf8',
+  }).trim();
+  assert.equal(subject, 'chore(release): 2026.05.29.1');
+});
+
+test('runRelease returns the current branch for push guidance', async () => {
+  const repo = await makeRepo();
+  execFileSync('git', ['checkout', '-b', 'release/train'], { cwd: repo });
+
+  const result = await runRelease({
+    cwd: repo,
+    date: new Date('2026-05-29T12:00:00-07:00'),
+  });
+
+  assert.equal(result.branch, 'release/train');
+});
+
+test('runRelease updates package-lock.json when it exists', async () => {
+  const repo = await makeRepo({ packageLock: true });
+
+  await runRelease({
+    cwd: repo,
+    date: new Date('2026-05-29T12:00:00-07:00'),
+  });
+
+  const lock = JSON.parse(await readFile(path.join(repo, 'package-lock.json'), 'utf8'));
+  assert.equal(lock.version, '2026.05.29.1');
+  assert.equal(lock.packages[''].version, '2026.05.29.1');
+});
+
+test('runRelease uses the latest CalVer tag as the changelog base and ignores other tags', async () => {
+  const repo = await makeRepo();
+  execFileSync('git', ['tag', '2026.05.28.1'], { cwd: repo });
+  await writeFile(path.join(repo, 'feature-a.txt'), 'a\n');
+  execFileSync('git', ['add', 'feature-a.txt'], { cwd: repo });
+  execFileSync('git', ['commit', '-m', 'feat: after calver tag'], { cwd: repo });
+  execFileSync('git', ['tag', 'deploy-preview'], { cwd: repo });
+  await writeFile(path.join(repo, 'feature-b.txt'), 'b\n');
+  execFileSync('git', ['add', 'feature-b.txt'], { cwd: repo });
+  execFileSync('git', ['commit', '-m', 'fix: after non-release tag'], { cwd: repo });
+
+  await runRelease({
+    cwd: repo,
+    date: new Date('2026-05-29T12:00:00-07:00'),
+  });
+
+  const changelog = await readFile(path.join(repo, 'CHANGELOG.md'), 'utf8');
+  assert.match(changelog, /- fix: after non-release tag/);
+  assert.match(changelog, /- feat: after calver tag/);
+  assert.doesNotMatch(changelog, /- feat: initial app/);
+});
+
+test('runRelease rolls back its release commit when tag creation fails', async () => {
+  const repo = await makeRepo();
+  execFileSync('git', ['tag', '2026.05.29.1'], { cwd: repo });
+  const before = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8' }).trim();
+
+  await assert.rejects(
+    () => runRelease({
+      cwd: repo,
+      date: new Date('2026-05-29T12:00:00-07:00'),
+      existingTags: [],
+    }),
+    /Failed to create git tag/,
+  );
+
+  const after = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8' }).trim();
+  assert.equal(after, before);
+});
+
+async function makeRepo({ packageLock = false } = {}) {
+  const repo = await mkdtemp(path.join(tmpdir(), 'calver-bump-'));
+  execFileSync('git', ['init'], { cwd: repo });
+  execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: repo });
+  execFileSync('git', ['config', 'user.name', 'Test User'], { cwd: repo });
+  execFileSync('git', ['checkout', '-b', 'main'], { cwd: repo });
+  await writeFile(
+    path.join(repo, 'package.json'),
+    `${JSON.stringify({ name: 'demo-app', version: '0.0.0' }, null, 2)}\n`,
+  );
+  if (packageLock) {
+    await writeFile(
+      path.join(repo, 'package-lock.json'),
+      `${JSON.stringify({
+        name: 'demo-app',
+        version: '0.0.0',
+        lockfileVersion: 3,
+        requires: true,
+        packages: {
+          '': {
+            name: 'demo-app',
+            version: '0.0.0',
+          },
+        },
+      }, null, 2)}\n`,
+    );
+  }
+  execFileSync('git', ['add', '.'], { cwd: repo });
+  execFileSync('git', ['commit', '-m', 'feat: initial app'], { cwd: repo });
+  return repo;
+}