calver-bump 0.1.0 → 0.1.2

package/README.md

@@ -5,22 +5,22 @@ Release CLI for applications and internal tools that use readable CalVer version
 Default version and tag format:
 
 ```text
-YYYY.MM.DD.N
+YY.MMDD
 ```
 
 Example:
 
 ```text
-2026.05.29.1
+26.0529
 ```
 
 ## 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.
+3. Creates or prepends a `CHANGELOG.md` entry from conventional commits since the latest reachable tag.
 4. Creates a release commit.
-5. Creates a git tag.
+5. Creates an annotated git tag.
 
 ## Usage
 
@@ -40,11 +40,66 @@ Use compact CalVer instead:
 npx calver-bump --format compact
 ```
 
+Use long CalVer instead:
+
+```bash
+npx calver-bump --format long
+```
+
+Create a `v`-prefixed git tag while keeping `package.json` unprefixed:
+
+```bash
+npx calver-bump --tag-prefix v
+```
+
+Push the release commit and annotated tag:
+
+```bash
+npx calver-bump --push
+```
+
+Push to a different remote:
+
+```bash
+npx calver-bump --push --remote upstream
+```
+
+Only include selected conventional commit types:
+
+```bash
+npx calver-bump --types feat,fix,perf
+```
+
+Update files without creating a release commit or tag:
+
+```bash
+npx calver-bump --skip-commit
+```
+
+## Configuration
+
+Project defaults can be stored in `.calverbumprc.json`:
+
+```json
+{
+  "format": "short",
+  "tagPrefix": "v",
+  "remote": "origin",
+  "types": ["feat", "fix", "perf"]
+}
+```
+
 ## Notes
 
-- The default `dotted` format is `YYYY.MM.DD.N`.
-- The optional `compact` format is `YYYYMMDD.N`.
+- The default `short` format is `YY.MMDD` for the first release of the day, then `YY.MMDD.1`, `YY.MMDD.2`, etc.
+- The optional `compact` format is `YYMMDD` for the first release of the day, then `YYMMDD.1`, `YYMMDD.2`, etc.
+- The optional `long` format is `YYYY.MM.DD` for the first release of the day, then `YYYY.MM.DD.1`, `YYYY.MM.DD.2`, etc.
 - Existing `v`-prefixed tags are considered when calculating the next sequence number.
-- Changelog ranges ignore non-CalVer tags.
+- Changelog ranges start from the latest reachable tag, even when it is not a CalVer tag.
+- Changelog entries include conventional commit subjects only, such as `feat:`, `fix(scope):`, or `chore!:`.
+- Changelog entries are grouped into `Features`, `Fixes`, and `Other Changes`.
+- Changelog entries link to their commit hash for GitHub and GitLab-style `origin` remotes.
+- Later releases prepend only commits since the previous reachable tag.
+- Release tags are annotated so `git push --follow-tags <remote> <branch>` pushes them.
 - 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

@@ -1,29 +1,82 @@
 #!/usr/bin/env node
+import { execFile as execFileCallback } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+
 import { runRelease } from '../src/index.js';
 import { assertFormat } from '../src/calver.js';
 
+const execFile = promisify(execFileCallback);
 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 });
+  const options = await releaseOptions(args);
+  assertFormat(options.format);
+  const result = await runRelease(options);
   console.log(`Release version: ${result.version}`);
   for (const action of result.actions) {
     console.log(`- ${action}`);
   }
-  if (!dryRun) {
+  if (options.push && !options.dryRun) {
+    const pushArgs = ['push', '--follow-tags', result.remote, result.branch];
+    console.log('');
+    console.log(`Running: git ${pushArgs.join(' ')}`);
+    await execFile('git', pushArgs, { encoding: 'utf8' });
+  } else if (!options.dryRun && !options.skipCommit) {
     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(`   git push --follow-tags ${result.remote} ${result.branch}`);
     console.log('3. Trigger or verify your deployment pipeline.');
   }
 } catch (error) {
   console.error(error.message);
   process.exitCode = 1;
 }
+
+async function releaseOptions(args) {
+  const config = await readConfig();
+  return {
+    ...config,
+    dryRun: flag(args, '--dry-run') ?? config.dryRun ?? false,
+    push: flag(args, '--push') ?? config.push ?? false,
+    skipCommit: flag(args, '--skip-commit') ?? config.skipCommit ?? false,
+    format: value(args, '--format') ?? config.format ?? 'short',
+    remote: value(args, '--remote') ?? config.remote ?? 'origin',
+    tagPrefix: value(args, '--tag-prefix') ?? config.tagPrefix ?? '',
+    types: parseTypes(value(args, '--types')) ?? config.types,
+  };
+}
+
+async function readConfig() {
+  try {
+    return JSON.parse(await readFile('.calverbumprc.json', 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return {};
+    }
+    throw error;
+  }
+}
+
+function flag(args, name) {
+  return args.includes(name) ? true : undefined;
+}
+
+function value(args, name) {
+  const index = args.indexOf(name);
+  if (index < 0) {
+    return undefined;
+  }
+  const found = args[index + 1];
+  if (!found || found.startsWith('--')) {
+    throw new Error(`${name} requires a value.`);
+  }
+  return found;
+}
+
+function parseTypes(types) {
+  return types?.split(',').map((type) => type.trim()).filter(Boolean);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "calver-bump",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Release CLI for internal applications using readable CalVer versions.",
   "main": "src/index.js",
   "bin": {

package/src/calver.js

@@ -1,27 +1,34 @@
-export function nextCalVer({ date = new Date(), existingTags = [], format = 'dotted' } = {}) {
+export function nextCalVer({ date = new Date(), existingTags = [], format = 'short' } = {}) {
   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 prefix = calVerPrefix(parts, format);
+  const matcher = new RegExp(`^v?${escapeRegExp(prefix)}(?:\\.(\\d+))?$`);
+  const releaseState = existingTags.reduce((state, tag) => {
     const match = matcher.exec(tag.trim());
-    if (!match) return max;
-    return Math.max(max, Number(match[1]));
-  }, 0);
+    if (!match) return state;
+    return {
+      hasBase: state.hasBase || !match[1],
+      highestSequence: match[1] ? Math.max(state.highestSequence, Number(match[1])) : state.highestSequence,
+    };
+  }, { hasBase: false, highestSequence: 0 });
 
-  return `${prefix}.${highest + 1}`;
+  if (!releaseState.hasBase && releaseState.highestSequence === 0) {
+    return prefix;
+  }
+  return `${prefix}.${releaseState.highestSequence + 1}`;
 }
 
 export function assertFormat(format) {
-  if (!['dotted', 'compact'].includes(format)) {
-    throw new Error(`Invalid format "${format}". Expected "dotted" or "compact".`);
+  if (!['short', 'compact', 'long'].includes(format)) {
+    throw new Error(`Invalid format "${format}". Expected "short", "compact", or "long".`);
   }
 }
 
 export function isCalVerTag(tag) {
-  return /^v?\d{4}\.\d{2}\.\d{2}\.\d+$/.test(tag) || /^v?\d{8}\.\d+$/.test(tag);
+  return /^v?\d{2}\.\d{4}(?:\.\d+)?$/.test(tag)
+    || /^v?\d{6}(?:\.\d+)?$/.test(tag)
+    || /^v?\d{4}\.\d{2}\.\d{2}(?:\.\d+)?$/.test(tag)
+    || /^v?\d{8}(?:\.\d+)?$/.test(tag);
 }
 
 export function isoDate(date = new Date()) {
@@ -31,9 +38,20 @@ export function isoDate(date = new Date()) {
 
 function dateParts(date) {
   const year = String(date.getFullYear());
+  const shortYear = year.slice(-2);
   const month = String(date.getMonth() + 1).padStart(2, '0');
   const day = String(date.getDate()).padStart(2, '0');
-  return { year, month, day };
+  return { year, shortYear, month, day };
+}
+
+function calVerPrefix(parts, format) {
+  if (format === 'compact') {
+    return `${parts.shortYear}${parts.month}${parts.day}`;
+  }
+  if (format === 'long') {
+    return `${parts.year}.${parts.month}.${parts.day}`;
+  }
+  return `${parts.shortYear}.${parts.month}${parts.day}`;
 }
 
 function escapeRegExp(value) {

package/src/index.js

@@ -3,7 +3,7 @@ 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';
+import { isoDate, nextCalVer } from './calver.js';
 
 const execFile = promisify(execFileCallback);
 
@@ -13,13 +13,16 @@ export async function planRelease(options = {}) {
   const version = nextCalVer({
     date: options.date,
     existingTags,
-    format: options.format ?? 'dotted',
+    format: options.format ?? 'short',
   });
+  const tag = `${options.tagPrefix ?? ''}${version}`;
 
   return {
     version,
+    tag,
     branch: await currentBranch(cwd),
-    actions: releaseActions(version),
+    remote: options.remote ?? 'origin',
+    actions: releaseActions({ version, tag, skipCommit: options.skipCommit }),
   };
 }
 
@@ -34,26 +37,34 @@ export async function runRelease(options = {}) {
   await assertCleanWorktree(cwd);
   await updatePackageVersion(cwd, plan.version);
   await updatePackageLock(cwd, plan.version);
-  await prependChangelog(cwd, plan.version, options.date ?? new Date());
+  await prependChangelog(cwd, plan.version, options.date ?? new Date(), options);
+
+  if (options.skipCommit) {
+    return { ...plan, tag: null };
+  }
+
   await git(cwd, ['add', ...await releaseFiles(cwd)]);
   await git(cwd, ['commit', '-m', `chore(release): ${plan.version}`]);
   try {
-    await git(cwd, ['tag', plan.version]);
+    await git(cwd, ['tag', '-a', plan.tag, '-m', `Release ${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}`);
+    throw new Error(`Failed to create git tag ${plan.tag}; rolled back release commit. ${error.message}`);
   }
 
   return plan;
 }
 
-function releaseActions(version) {
-  return [
+function releaseActions({ version, tag, skipCommit = false }) {
+  const actions = [
     `update package.json version to ${version}`,
     `prepend CHANGELOG.md entry for ${version}`,
-    `create git commit chore(release): ${version}`,
-    `create git tag ${version}`,
   ];
+  if (!skipCommit) {
+    actions.push(`create git commit chore(release): ${version}`);
+    actions.push(`create git tag ${tag}`);
+  }
+  return actions;
 }
 
 async function updatePackageVersion(cwd, version) {
@@ -105,10 +116,10 @@ async function fileExists(filePath) {
   }
 }
 
-async function prependChangelog(cwd, version, date) {
+async function prependChangelog(cwd, version, date, options = {}) {
   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`;
+  const changes = await releaseNotes(cwd, options);
+  const entry = `## ${version} - ${isoDate(date)}\n\n${formatReleaseNotes(changes)}\n`;
   let existing = '';
 
   try {
@@ -124,11 +135,105 @@ async function prependChangelog(cwd, version, date) {
   await writeFile(changelogPath, body);
 }
 
-async function releaseNotes(cwd) {
+async function releaseNotes(cwd, options = {}) {
   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.'];
+  const commits = await gitCommits(cwd, range);
+  const commitUrlBuilder = await commitUrlBuilderForOrigin(cwd);
+  const allowedTypes = options.types ?? ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert'];
+  const conventionalCommits = commits
+    .filter((commit) => isConventionalCommit(commit.subject))
+    .filter((commit) => allowedTypes.includes(conventionalType(commit.subject)))
+    .map((commit) => ({
+      ...commit,
+      url: commitUrlBuilder ? commitUrlBuilder(commit.hash) : null,
+    }));
+  return conventionalCommits.length > 0 ? conventionalCommits : ['No conventional commits in this release.'];
+}
+
+function isConventionalCommit(subject) {
+  return /^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([^)]+\))?!?: .+/.test(subject);
+}
+
+function formatReleaseNotes(changes) {
+  if (changes.length === 1 && changes[0] === 'No conventional commits in this release.') {
+    return `- ${changes[0]}`;
+  }
+
+  const features = changes.filter((change) => conventionalType(change.subject) === 'feat');
+  const fixes = changes.filter((change) => conventionalType(change.subject) === 'fix');
+  const other = changes.filter((change) => !['feat', 'fix'].includes(conventionalType(change.subject)));
+  const sections = [
+    ['Features', features],
+    ['Fixes', fixes],
+    ['Other Changes', other],
+  ];
+
+  return sections
+    .filter(([, entries]) => entries.length > 0)
+    .map(([heading, entries]) => `### ${heading}\n\n${entries.map((entry) => `- ${formatCommitEntry(entry)}`).join('\n')}`)
+    .join('\n\n');
+}
+
+function conventionalType(subject) {
+  return /^(?<type>[a-z]+)(\([^)]+\))?!?: .+/.exec(subject)?.groups.type;
+}
+
+function formatCommitEntry(commit) {
+  const shortHash = commit.hash.slice(0, 7);
+  const suffix = commit.url ? ` ([${shortHash}](${commit.url}))` : ` (${shortHash})`;
+  return `${commit.subject}${suffix}`;
+}
+
+async function gitCommits(cwd, range) {
+  const { stdout } = await git(cwd, ['log', '--pretty=format:%H%x00%s', ...range]);
+  return stdout
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      const [hash, subject] = line.split('\0');
+      return { hash, subject };
+    });
+}
+
+async function commitUrlBuilderForOrigin(cwd) {
+  try {
+    const { stdout } = await git(cwd, ['remote', 'get-url', 'origin']);
+    return commitUrlBuilder(stdout.trim());
+  } catch {
+    return null;
+  }
+}
+
+function commitUrlBuilder(remote) {
+  const parsed = parseGitRemote(remote);
+  if (!parsed) {
+    return null;
+  }
+
+  const baseUrl = `https://${parsed.host}/${parsed.repo}`;
+  if (parsed.host === 'github.com') {
+    return (hash) => `${baseUrl}/commit/${hash}`;
+  }
+  if (parsed.host.includes('gitlab')) {
+    return (hash) => `${baseUrl}/-/commit/${hash}`;
+  }
+
+  return null;
+}
+
+function parseGitRemote(remote) {
+  const sshMatch = /^git@(?<host>[^:]+):(?<repo>.+?)(?:\.git)?$/.exec(remote);
+  if (sshMatch) {
+    return sshMatch.groups;
+  }
+
+  const httpsMatch = /^https:\/\/(?<host>[^/]+)\/(?<repo>.+?)(?:\.git)?$/.exec(remote);
+  if (httpsMatch) {
+    return httpsMatch.groups;
+  }
+
+  return null;
 }
 
 async function latestReachableTag(cwd) {
@@ -140,7 +245,7 @@ async function latestReachableTag(cwd) {
     '--format=%(refname:short)',
     'refs/tags',
   ]);
-  return tags.find(isCalVerTag) ?? null;
+  return tags[0] ?? null;
 }
 
 async function currentBranch(cwd) {

package/test/calver.test.js

@@ -3,30 +3,67 @@ import { test } from 'node:test';
 
 import { nextCalVer } from '../src/calver.js';
 
-test('nextCalVer defaults to readable dotted format YYYY.MM.DD.N', () => {
+test('nextCalVer defaults to readable YY.MMDD format for the first release of the day', () => {
   const version = nextCalVer({
     date: new Date('2026-05-29T12:00:00-07:00'),
     existingTags: [],
   });
 
-  assert.equal(version, '2026.05.29.1');
+  assert.equal(version, '26.0529');
 });
 
 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'],
+    existingTags: ['26.0528.7', '26.0529', 'v26.0529.2'],
+  });
+
+  assert.equal(version, '26.0529.3');
+});
+
+test('nextCalVer emits .1 for the second release of the day', () => {
+  const version = nextCalVer({
+    date: new Date('2026-05-29T12:00:00-07:00'),
+    existingTags: ['26.0529'],
+  });
+
+  assert.equal(version, '26.0529.1');
+});
+
+test('nextCalVer can emit compact YYMMDD without sequence for the first release of the day', () => {
+  const version = nextCalVer({
+    date: new Date('2026-05-29T12:00:00-07:00'),
+    format: 'compact',
   });
 
-  assert.equal(version, '2026.05.29.3');
+  assert.equal(version, '260529');
 });
 
-test('nextCalVer can emit compact YYYYMMDD.N when requested', () => {
+test('nextCalVer can emit compact YYMMDD.N after the first release of the day', () => {
   const version = nextCalVer({
     date: new Date('2026-05-29T12:00:00-07:00'),
-    existingTags: ['20260529.1'],
+    existingTags: ['260529'],
     format: 'compact',
   });
 
-  assert.equal(version, '20260529.2');
+  assert.equal(version, '260529.1');
+});
+
+test('nextCalVer can emit long YYYY.MM.DD without sequence for the first release of the day', () => {
+  const version = nextCalVer({
+    date: new Date('2026-05-29T12:00:00-07:00'),
+    format: 'long',
+  });
+
+  assert.equal(version, '2026.05.29');
+});
+
+test('nextCalVer can emit long YYYY.MM.DD.N after the first release of the day', () => {
+  const version = nextCalVer({
+    date: new Date('2026-05-29T12:00:00-07:00'),
+    existingTags: ['2026.05.29'],
+    format: 'long',
+  });
+
+  assert.equal(version, '2026.05.29.1');
 });

package/test/cli.test.js

@@ -29,6 +29,65 @@ test('CLI explains how to push the release commit and tag after a real release',
   assert.match(result.stdout, /git push --follow-tags origin main/);
 });
 
+test('CLI reads .calverbumprc.json defaults', async () => {
+  const repo = await makeRepo();
+  await writeFile(
+    path.join(repo, '.calverbumprc.json'),
+    `${JSON.stringify({ tagPrefix: 'v', types: ['feat'] }, null, 2)}\n`,
+  );
+  execFileSync('git', ['add', '.calverbumprc.json'], { cwd: repo });
+  execFileSync('git', ['commit', '-m', 'chore: add calver bump config'], { cwd: repo });
+  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, /create git tag v26\.\d{4}/);
+  const tag = execFileSync('git', ['tag', '--list', 'v26*'], {
+    cwd: repo,
+    encoding: 'utf8',
+  }).trim();
+  assert.match(tag, /^v26\.\d{4}$/);
+});
+
+test('CLI prints and runs push command when --push is enabled', async () => {
+  const remote = await makeBareRepo();
+  const repo = await makeRepo();
+  execFileSync('git', ['remote', 'add', 'origin', remote], { cwd: repo });
+  const cliPath = path.resolve('bin/calver-bump.js');
+
+  const result = spawnSync(process.execPath, [cliPath, '--push'], {
+    cwd: repo,
+    encoding: 'utf8',
+  });
+
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /Running: git push --follow-tags origin main/);
+  const remoteTags = execFileSync('git', ['tag', '--list', '26*'], {
+    cwd: remote,
+    encoding: 'utf8',
+  }).trim();
+  assert.match(remoteTags, /^26\.\d{4}$/);
+});
+
+test('CLI supports --remote with --push', async () => {
+  const remote = await makeBareRepo();
+  const repo = await makeRepo();
+  execFileSync('git', ['remote', 'add', 'upstream', remote], { cwd: repo });
+  const cliPath = path.resolve('bin/calver-bump.js');
+
+  const result = spawnSync(process.execPath, [cliPath, '--push', '--remote', 'upstream'], {
+    cwd: repo,
+    encoding: 'utf8',
+  });
+
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /Running: git push --follow-tags upstream main/);
+});
+
 async function makeRepo() {
   const repo = await mkdtemp(path.join(tmpdir(), 'calver-bump-cli-'));
   execFileSync('git', ['init'], { cwd: repo });
@@ -42,3 +101,9 @@ async function makeRepo() {
   execFileSync('git', ['commit', '-m', 'feat: initial app'], { cwd: repo });
   return repo;
 }
+
+async function makeBareRepo() {
+  const repo = await mkdtemp(path.join(tmpdir(), 'calver-bump-remote-'));
+  execFileSync('git', ['init', '--bare'], { cwd: repo });
+  return repo;
+}

package/test/release.test.js

@@ -16,18 +16,40 @@ test('planRelease reports version, changelog, commit, and tag actions without wr
     dryRun: true,
   });
 
-  assert.equal(plan.version, '2026.05.29.1');
+  assert.equal(plan.version, '26.0529');
   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',
+    'update package.json version to 26.0529',
+    'prepend CHANGELOG.md entry for 26.0529',
+    'create git commit chore(release): 26.0529',
+    'create git tag 26.0529',
   ]);
 
   const pkg = JSON.parse(await readFile(path.join(repo, 'package.json'), 'utf8'));
   assert.equal(pkg.version, '0.0.0');
 });
 
+test('runRelease supports tag prefixes without changing package.json version', async () => {
+  const repo = await makeRepo();
+
+  const result = await runRelease({
+    cwd: repo,
+    date: new Date('2026-05-29T12:00:00-07:00'),
+    tagPrefix: 'v',
+  });
+
+  assert.equal(result.version, '26.0529');
+  assert.equal(result.tag, 'v26.0529');
+
+  const pkg = JSON.parse(await readFile(path.join(repo, 'package.json'), 'utf8'));
+  assert.equal(pkg.version, '26.0529');
+
+  const tag = execFileSync('git', ['tag', '--list', 'v26.0529'], {
+    cwd: repo,
+    encoding: 'utf8',
+  }).trim();
+  assert.equal(tag, 'v26.0529');
+});
+
 test('runRelease updates package.json, prepends changelog, commits, and tags', async () => {
   const repo = await makeRepo();
 
@@ -36,25 +58,25 @@ test('runRelease updates package.json, prepends changelog, commits, and tags', a
     date: new Date('2026-05-29T12:00:00-07:00'),
   });
 
-  assert.equal(result.version, '2026.05.29.1');
+  assert.equal(result.version, '26.0529');
 
   const pkg = JSON.parse(await readFile(path.join(repo, 'package.json'), 'utf8'));
-  assert.equal(pkg.version, '2026.05.29.1');
+  assert.equal(pkg.version, '26.0529');
 
   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/);
+  assert.match(changelog, /^# Changelog\n\n## 26\.0529 - 2026-05-29\n\n### Features\n\n- feat: initial app/);
 
-  const tag = execFileSync('git', ['tag', '--list', '2026.05.29.1'], {
+  const tag = execFileSync('git', ['tag', '--list', '26.0529'], {
     cwd: repo,
     encoding: 'utf8',
   }).trim();
-  assert.equal(tag, '2026.05.29.1');
+  assert.equal(tag, '26.0529');
 
   const subject = execFileSync('git', ['log', '-1', '--pretty=%s'], {
     cwd: repo,
     encoding: 'utf8',
   }).trim();
-  assert.equal(subject, 'chore(release): 2026.05.29.1');
+  assert.equal(subject, 'chore(release): 26.0529');
 });
 
 test('runRelease returns the current branch for push guidance', async () => {
@@ -78,13 +100,13 @@ test('runRelease updates package-lock.json when it exists', async () => {
   });
 
   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');
+  assert.equal(lock.version, '26.0529');
+  assert.equal(lock.packages[''].version, '26.0529');
 });
 
-test('runRelease uses the latest CalVer tag as the changelog base and ignores other tags', async () => {
+test('runRelease uses the latest reachable tag as the changelog base', async () => {
   const repo = await makeRepo();
-  execFileSync('git', ['tag', '2026.05.28.1'], { cwd: repo });
+  execFileSync('git', ['tag', '26.0528.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 });
@@ -104,9 +126,148 @@ test('runRelease uses the latest CalVer tag as the changelog base and ignores ot
   assert.doesNotMatch(changelog, /- feat: initial app/);
 });
 
+test('runRelease includes only conventional commits in the changelog', async () => {
+  const repo = await makeRepo();
+  await writeFile(path.join(repo, 'note.txt'), 'note\n');
+  execFileSync('git', ['add', 'note.txt'], { cwd: repo });
+  execFileSync('git', ['commit', '-m', 'update docs manually'], { cwd: repo });
+  await writeFile(path.join(repo, 'fix.txt'), 'fix\n');
+  execFileSync('git', ['add', 'fix.txt'], { cwd: repo });
+  execFileSync('git', ['commit', '-m', 'fix(release): keep only conventional commits'], { 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\(release\): keep only conventional commits/);
+  assert.match(changelog, /- feat: initial app/);
+  assert.doesNotMatch(changelog, /update docs manually/);
+});
+
+test('runRelease filters changelog entries by configured conventional commit types', async () => {
+  const repo = await makeRepo();
+  await writeFile(path.join(repo, 'fix.txt'), 'fix\n');
+  execFileSync('git', ['add', 'fix.txt'], { cwd: repo });
+  execFileSync('git', ['commit', '-m', 'fix: excluded by type filter'], { cwd: repo });
+
+  await runRelease({
+    cwd: repo,
+    date: new Date('2026-05-29T12:00:00-07:00'),
+    types: ['feat'],
+  });
+
+  const changelog = await readFile(path.join(repo, 'CHANGELOG.md'), 'utf8');
+  assert.match(changelog, /- feat: initial app/);
+  assert.doesNotMatch(changelog, /fix: excluded by type filter/);
+});
+
+test('runRelease groups changelog entries by conventional commit type', async () => {
+  const repo = await makeRepo();
+  await writeFile(path.join(repo, 'fix.txt'), 'fix\n');
+  execFileSync('git', ['add', 'fix.txt'], { cwd: repo });
+  execFileSync('git', ['commit', '-m', 'fix(auth): repair token refresh'], { cwd: repo });
+  await writeFile(path.join(repo, 'feature.txt'), 'feature\n');
+  execFileSync('git', ['add', 'feature.txt'], { cwd: repo });
+  execFileSync('git', ['commit', '-m', 'feat: add release grouping'], { 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,
+    /## 26\.0529 - 2026-05-29\n\n### Features\n\n- feat: add release grouping \([a-f0-9]{7}\)\n- feat: initial app \([a-f0-9]{7}\)\n\n### Fixes\n\n- fix\(auth\): repair token refresh \([a-f0-9]{7}\)/,
+  );
+});
+
+test('runRelease links each changelog entry to its commit on GitHub', async () => {
+  const repo = await makeRepo();
+  execFileSync('git', ['remote', 'add', 'origin', 'git@github.com:msako/demo-app.git'], { cwd: repo });
+  await writeFile(path.join(repo, 'feature.txt'), 'feature\n');
+  execFileSync('git', ['add', 'feature.txt'], { cwd: repo });
+  execFileSync('git', ['commit', '-m', 'feat: add linked changelog entry'], { cwd: repo });
+  const hash = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8' }).trim();
+  const shortHash = hash.slice(0, 7);
+
+  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,
+    new RegExp(`- feat: add linked changelog entry \\(\\[${shortHash}\\]\\(https://github\\.com/msako/demo-app/commit/${hash}\\)\\)`),
+  );
+});
+
+test('runRelease links changelog entries for private GitLab-style remotes', async () => {
+  const repo = await makeRepo();
+  execFileSync('git', ['remote', 'add', 'origin', 'git@gitlab.internal.example.com:platform/demo-app.git'], { cwd: repo });
+  await writeFile(path.join(repo, 'feature.txt'), 'feature\n');
+  execFileSync('git', ['add', 'feature.txt'], { cwd: repo });
+  execFileSync('git', ['commit', '-m', 'fix: link private gitlab commit'], { cwd: repo });
+  const hash = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8' }).trim();
+  const shortHash = hash.slice(0, 7);
+
+  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,
+    new RegExp(`- fix: link private gitlab commit \\(\\[${shortHash}\\]\\(https://gitlab\\.internal\\.example\\.com/platform/demo-app/-/commit/${hash}\\)\\)`),
+  );
+});
+
+test('runRelease prepends only commits since the previous CalVer tag on later releases', async () => {
+  const repo = await makeRepo();
+  await runRelease({
+    cwd: repo,
+    date: new Date('2026-05-29T12:00:00-07:00'),
+  });
+  await writeFile(path.join(repo, 'second.txt'), 'second\n');
+  execFileSync('git', ['add', 'second.txt'], { cwd: repo });
+  execFileSync('git', ['commit', '-m', 'fix: second release only'], { cwd: repo });
+
+  await runRelease({
+    cwd: repo,
+    date: new Date('2026-05-29T13:00:00-07:00'),
+  });
+
+  const changelog = await readFile(path.join(repo, 'CHANGELOG.md'), 'utf8');
+  const latestEntry = changelog.split('## 26.0529 - 2026-05-29')[0];
+  assert.match(latestEntry, /## 26\.0529\.1 - 2026-05-29/);
+  assert.match(latestEntry, /- fix: second release only/);
+  assert.doesNotMatch(latestEntry, /feat: initial app/);
+});
+
+test('runRelease uses the latest reachable tag as the changelog base even when it is not CalVer', async () => {
+  const repo = await makeRepo();
+  execFileSync('git', ['tag', 'v2.20'], { cwd: repo });
+  await writeFile(path.join(repo, 'later.txt'), 'later\n');
+  execFileSync('git', ['add', 'later.txt'], { cwd: repo });
+  execFileSync('git', ['commit', '-m', 'fix: after legacy version 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 legacy version 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 });
+  execFileSync('git', ['tag', '26.0529'], { cwd: repo });
   const before = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8' }).trim();
 
   await assert.rejects(
@@ -122,6 +283,30 @@ test('runRelease rolls back its release commit when tag creation fails', async (
   assert.equal(after, before);
 });
 
+test('runRelease can skip commit and tag creation', async () => {
+  const repo = await makeRepo();
+
+  const result = await runRelease({
+    cwd: repo,
+    date: new Date('2026-05-29T12:00:00-07:00'),
+    skipCommit: true,
+  });
+
+  assert.equal(result.tag, null);
+  const subject = execFileSync('git', ['log', '-1', '--pretty=%s'], {
+    cwd: repo,
+    encoding: 'utf8',
+  }).trim();
+  assert.equal(subject, 'feat: initial app');
+
+  const status = execFileSync('git', ['status', '--porcelain'], {
+    cwd: repo,
+    encoding: 'utf8',
+  }).trim();
+  assert.match(status, /M package\.json/);
+  assert.match(status, /\?\? CHANGELOG\.md/);
+});
+
 async function makeRepo({ packageLock = false } = {}) {
   const repo = await mkdtemp(path.join(tmpdir(), 'calver-bump-'));
   execFileSync('git', ['init'], { cwd: repo });