calver-bump 0.1.8 → 1.0.1

package/README.md

@@ -2,16 +2,23 @@
 
 Release CLI for applications and internal tools that use readable CalVer versions.
 
-Default version and tag format:
+Default version format:
 
 ```text
 YY.MMDD
 ```
 
-Example:
+Default git tag format:
+
+```text
+vYY.MMDD
+```
+
+Example package version and git tag:
 
 ```text
 26.0529
+v26.0529
 ```
 
 ## What it does
@@ -29,6 +36,8 @@ Example:
 npx calver-bump
 ```
 
+By default, `calver-bump` updates release files, creates a release commit, and creates an annotated `v`-prefixed git tag.
+
 Preview the planned release without writing files:
 
 ```bash
@@ -59,10 +68,10 @@ Use long CalVer instead:
 npx calver-bump --format long
 ```
 
-Create a `v`-prefixed git tag while keeping `package.json` unprefixed:
+Create an unprefixed git tag while keeping the default package version unchanged:
 
 ```bash
-npx calver-bump --tag-prefix v
+npx calver-bump --tag-prefix ""
 ```
 
 Push the release commit and annotated tag:
@@ -107,7 +116,19 @@ Update only `CHANGELOG.md`:
 npx calver-bump --changelog-only
 ```
 
-Update files without creating a release commit or tag:
+Create a release commit after updating files:
+
+```bash
+npx calver-bump --commit
+```
+
+Create a release commit and annotated tag after updating files:
+
+```bash
+npx calver-bump --tag
+```
+
+Explicitly update files without creating a release commit or tag:
 
 ```bash
 npx calver-bump --skip-commit
@@ -152,7 +173,12 @@ The package includes a manual GitHub Actions publish workflow. Run the `Publish`
 - Changelog entries fall back to commit hash links for GitHub and GitLab-style remotes when no pull/merge request reference is found.
 - Release entries include a `Full Changelog` section with a deduped list of pull/merge requests found in the release range, including the local commit title when available.
 - Later releases prepend only commits since the previous nearest reachable tag.
+- Plain `calver-bump` creates the release commit and annotated tag by default.
+- Use `--commit` to create only the release commit.
+- Use `--tag` to create the release commit and annotated tag.
+- Use `--skip-commit` to update files only without creating a release commit or tag.
+- Use `--push` to create the release commit, create the annotated tag, and push both.
 - Release tags are annotated so `git push --follow-tags <remote> <branch>` pushes them.
-- The working tree must be clean before creating a real release.
+- Unrelated dirty working-tree files do not block a release; only release files are staged.
 - Existing release tags are rejected before files are written.
 - If tag creation fails after the release commit, the CLI undoes its own commit and leaves the file changes in the working tree for inspection or recovery.

package/bin/calver-bump.js

@@ -10,6 +10,7 @@ const execFile = promisify(execFileCallback);
 const args = process.argv.slice(2);
 const KNOWN_OPTIONS = new Set([
   '--changelog-only',
+  '--commit',
   '--dry-run',
   '--format',
   '--from',
@@ -18,6 +19,7 @@ const KNOWN_OPTIONS = new Set([
   '--push',
   '--remote',
   '--skip-commit',
+  '--tag',
   '--tag-prefix',
   '--types',
   '--version',
@@ -49,19 +51,17 @@ try {
   for (const action of result.actions) {
     console.log(`- ${action}`);
   }
-  if (options.push && !options.dryRun && createsGitObjects(options)) {
+  if (options.push && !options.dryRun && createsTag(options)) {
     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 && createsGitObjects(options)) {
+  } else if (!options.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 ${result.remote} ${result.branch}`);
-    console.log('3. Trigger or verify your deployment pipeline.');
+    for (const instruction of nextStepInstructions(result, options)) {
+      console.log(instruction);
+    }
   }
 } catch (error) {
   console.error(error.message);
@@ -73,21 +73,33 @@ async function releaseOptions(args) {
   const config = await readConfig();
   const versionOnly = flag(args, '--version-only') ?? config.versionOnly ?? false;
   const changelogOnly = flag(args, '--changelog-only') ?? config.changelogOnly ?? false;
+  const skipCommit = flag(args, '--skip-commit') ?? config.skipCommit ?? false;
+  const push = flag(args, '--push') ?? config.push ?? false;
+  const commitFlag = flag(args, '--commit');
+  const tagFlag = flag(args, '--tag');
+  const writesOnly = skipCommit || versionOnly || changelogOnly;
+  const tag = !writesOnly && (push || (tagFlag ?? config.tag ?? (commitFlag || config.commit ? false : true)));
+  const commit = tag || (!writesOnly && (commitFlag ?? config.commit ?? false));
   if (versionOnly && changelogOnly) {
     throw new Error('--version-only cannot be combined with --changelog-only.');
   }
+  if (skipCommit && (commitFlag || tagFlag || config.commit || config.tag || push)) {
+    throw new Error('--skip-commit cannot be combined with --commit, --tag, or --push.');
+  }
   return {
     ...config,
     dryRun: flag(args, '--dry-run') ?? config.dryRun ?? false,
     noFetch: flag(args, '--no-fetch') ?? config.noFetch ?? false,
-    push: flag(args, '--push') ?? config.push ?? false,
-    skipCommit: flag(args, '--skip-commit') ?? config.skipCommit ?? false,
+    commit,
+    tag,
+    push,
+    skipCommit,
     versionOnly,
     changelogOnly,
     from: value(args, '--from') ?? config.from,
     format: value(args, '--format') ?? config.format ?? 'short',
     remote: value(args, '--remote') ?? config.remote ?? 'origin',
-    tagPrefix: value(args, '--tag-prefix') ?? config.tagPrefix ?? '',
+    tagPrefix: value(args, '--tag-prefix') ?? config.tagPrefix ?? 'v',
     types: parseTypes(value(args, '--types')) ?? config.types,
     changelogSections: config.changelogSections,
   };
@@ -134,7 +146,7 @@ function rejectUnknownOptions(args) {
 
 function printResult(result, options) {
   console.log(`Release version: ${result.version}`);
-  console.log(`Git tag: ${createsGitObjects(options) ? result.tag : '(not created)'}`);
+  console.log(`Git tag: ${result.createdTag ?? '(not created)'}`);
   console.log(`Branch: ${result.branch}`);
   console.log(`Remote: ${result.remote}`);
   if (!options.versionOnly) {
@@ -151,8 +163,42 @@ function printResult(result, options) {
   console.log(options.dryRun ? 'Planned actions:' : 'Completed actions:');
 }
 
-function createsGitObjects(options) {
-  return !options.skipCommit && !options.versionOnly && !options.changelogOnly;
+function createsCommit(options) {
+  return Boolean(options.commit || options.tag || options.push) && !options.skipCommit && !options.versionOnly && !options.changelogOnly;
+}
+
+function createsTag(options) {
+  return Boolean(options.tag || options.push) && createsCommit(options);
+}
+
+function nextStepInstructions(result, options) {
+  if (options.versionOnly || options.changelogOnly) {
+    return ['Review the generated file changes.'];
+  }
+  if (!createsCommit(options)) {
+    return [
+      'Review CHANGELOG.md, then run:',
+      `git add ${result.files.join(' ')}`,
+      `git commit -m "chore(release): ${result.version}"`,
+      `git tag -a ${result.tag} -m "Release ${result.version}"`,
+      `git push --follow-tags ${result.remote} ${result.branch}`,
+    ];
+  }
+  if (!createsTag(options)) {
+    return [
+      'Review the release commit, then run:',
+      'git show --stat HEAD',
+      `git tag -a ${result.tag} -m "Release ${result.version}"`,
+      `git push --follow-tags ${result.remote} ${result.branch}`,
+    ];
+  }
+  return [
+    'Review the release commit:',
+    'git show --stat HEAD',
+    'Push the release commit and tag:',
+    `git push --follow-tags ${result.remote} ${result.branch}`,
+    'Trigger or verify your deployment pipeline.',
+  ];
 }
 
 function helpText() {
@@ -161,14 +207,16 @@ function helpText() {
 Options:
   --dry-run              Preview the release without writing files.
   --format <name>        Version format: short, compact, or long.
-  --tag-prefix <prefix>  Prefix the git tag without changing package.json.
+  --tag-prefix <prefix>  Prefix the git tag without changing package.json (default: v).
   --types <list>         Comma-separated conventional commit types to include.
   --from <tag>           Use an explicit changelog base tag.
   --no-fetch             Use local tags only; do not fetch remote tags.
   --version-only         Update package.json and supported npm lockfiles only.
   --changelog-only       Update CHANGELOG.md only.
-  --skip-commit          Update files without creating a release commit or tag.
-  --push                 Push the release commit and annotated tag.
+  --commit               Create the release commit after updating files.
+  --tag                  Create the release commit and annotated tag.
+  --skip-commit          Explicitly update files without creating a release commit or tag.
+  --push                 Create, tag, and push the release.
   --remote <name>        Remote used for fetch, links, and push.
   --version              Print the calver-bump package version.
   --help                 Show this help.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "calver-bump",
-  "version": "0.1.8",
+  "version": "1.0.1",
   "description": "Release CLI for internal applications using readable CalVer versions.",
   "repository": {
     "type": "git",

package/src/changelog.js

@@ -21,6 +21,7 @@ export async function releaseNotes(cwd, options = {}) {
   const conventionalCommits = dedupeConventionalChanges(commits
     .map((commit) => ({ ...commit, subject: conventionalSubjectForCommit(commit) ?? commit.subject }))
     .filter((commit) => isConventionalCommit(commit.subject))
+    .filter((commit) => !isReleaseCommit(commit.subject))
     .filter((commit) => allowedTypes.includes(conventionalType(commit.subject)))
     .filter((commit) => !isCommitInChangelog(commit, options.existingChangelog ?? ''))
     .map((commit) => ({
@@ -28,7 +29,10 @@ export async function releaseNotes(cwd, options = {}) {
       request: requestForCommit(commit, requestUrlBuilder),
       url: commitUrlBuilder ? commitUrlBuilder(commit.hash) : null,
     })));
-  const requests = uniqueRequests(commits.map((commit) => requestForCommit(commit, requestUrlBuilder)).filter(Boolean));
+  const requests = uniqueRequests(commits
+    .filter((commit) => !isReleaseCommit(conventionalSubjectForCommit(commit) ?? commit.subject))
+    .map((commit) => requestForCommit(commit, requestUrlBuilder))
+    .filter(Boolean));
   return {
     previousTag: latestTag,
     range: latestTag ? `${latestTag}..HEAD` : 'HEAD',
@@ -39,10 +43,7 @@ export async function releaseNotes(cwd, options = {}) {
 }
 
 export function formatReleaseHeading({ version, previousTag, tag, compareUrlBuilder }) {
-  const label = previousTag && compareUrlBuilder
-    ? `[${version}](${compareUrlBuilder(previousTag, tag)})`
-    : version;
-  return `## ${label}`;
+  return `## ${version}`;
 }
 
 export function formatReleaseNotes(changes, sectionConfig = {}) {
@@ -72,11 +73,15 @@ export function formatReleaseNotes(changes, sectionConfig = {}) {
     .join('\n\n');
 }
 
-export function formatFullChangelog(requests) {
-  if (requests.length === 0) {
+export function formatFullChangelog(requests, compareUrl = null) {
+  const entries = [
+    ...requests.map((request) => formatRequestEntry(request)),
+    ...(compareUrl ? [`[Compare changes](${compareUrl})`] : []),
+  ];
+  if (entries.length === 0) {
     return '';
   }
-  return `\n\n### Full Changelog\n\n${requests.map((request) => `- ${formatRequestEntry(request)}`).join('\n')}`;
+  return `\n\n### Full Changelog\n\n${entries.map((entry) => `- ${entry}`).join('\n')}`;
 }
 
 async function latestReleaseTag(cwd, changelog) {
@@ -88,7 +93,7 @@ async function latestReleaseTag(cwd, changelog) {
 }
 
 function latestChangelogCompareTarget(changelog) {
-  const match = /^## \[[^\]]+\]\([^)]*\/(?:-\/)?compare\/[^)]*?\.{3}(?<tag>[^)\s]+)\)/m.exec(changelog);
+  const match = /\[[^\]]+\]\([^)]*\/(?:-\/)?compare\/[^)]*?\.{3}(?<tag>[^)\s]+)\)/m.exec(changelog);
   return match?.groups.tag ?? null;
 }
 
@@ -101,6 +106,10 @@ function isConventionalCommit(subject) {
   return /^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([^)]+\))?!?: .+/.test(subject);
 }
 
+function isReleaseCommit(subject) {
+  return /^chore\(release\):\s.+/.test(subject);
+}
+
 function conventionalSubjectForCommit(commit) {
   return commitLines(commit).find((line) => isConventionalCommit(line)) ?? null;
 }
@@ -132,14 +141,16 @@ function conventionalType(subject) {
 
 function formatCommitEntry(commit) {
   const shortHash = commit.hash.slice(0, 7);
-  const suffix = commit.request
-    ? ` (${formatRequestLink(commit.request)})`
-    : commit.url ? ` ([${shortHash}](${commit.url}))` : ` (${shortHash})`;
+  const links = [
+    shortHash,
+    commit.request ? formatRequestLink(commit.request) : null,
+  ].filter(Boolean);
+  const suffix = ` (${links.join(', ')})`;
   return `${commit.subject}${suffix}`;
 }
 
 function formatRequestLink(request) {
-  return request.url ? `[${request.label}](${request.url})` : request.label;
+  return request.label;
 }
 
 function formatRequestEntry(request) {
@@ -220,7 +231,7 @@ function requestTitleForCommit(commit) {
 }
 
 function parseRequestReference(message) {
-  const gitlabMerge = /(?:^|\s)(?:See merge request\s+\S+!|!)(?<number>\d+)(?=\D|$)/i.exec(message);
+  const gitlabMerge = /(?:^|[\s(])(?:See merge request\s+\S+!|!)(?<number>\d+)(?=\D|$)/i.exec(message);
   if (gitlabMerge) {
     return { provider: 'gitlab', number: gitlabMerge.groups.number, label: `!${gitlabMerge.groups.number}` };
   }
@@ -257,7 +268,7 @@ function parseGitRemote(remote) {
     return sshMatch.groups;
   }
 
-  const httpsMatch = /^https:\/\/(?<host>[^/]+)\/(?<repo>.+?)(?:\.git)?$/.exec(remote);
+  const httpsMatch = /^https?:\/\/(?<host>[^/]+)\/(?<repo>.+?)(?:\.git)?$/.exec(remote);
   if (httpsMatch) {
     return httpsMatch.groups;
   }

package/src/files.js

@@ -32,18 +32,18 @@ export async function updatePackageLock(cwd, version) {
 
 export async function releaseFiles(cwd, options = {}) {
   const candidates = [];
+  const files = [];
   if (options.version !== false) {
     candidates.push('package.json', 'package-lock.json', 'npm-shrinkwrap.json');
   }
-  if (options.changelog !== false) {
-    candidates.push('CHANGELOG.md');
-  }
-  const files = [];
   for (const candidate of candidates) {
     if (await fileExists(path.join(cwd, candidate))) {
       files.push(candidate);
     }
   }
+  if (options.changelog !== false) {
+    files.push('CHANGELOG.md');
+  }
   return files;
 }
 

package/src/index.js

@@ -8,7 +8,7 @@ import {
   updatePackageVersion,
   writeChangelog,
 } from './files.js';
-import { assertCleanWorktree, assertTagAvailable, currentBranch, git, gitLines } from './git.js';
+import { assertTagAvailable, currentBranch, git, gitLines } from './git.js';
 
 export async function planRelease(options = {}) {
   const cwd = options.cwd ?? process.cwd();
@@ -18,7 +18,7 @@ export async function planRelease(options = {}) {
     existingTags,
     format: options.format ?? 'short',
   });
-  const tag = `${options.tagPrefix ?? ''}${version}`;
+  const tag = `${options.tagPrefix ?? 'v'}${version}`;
   const notes = options.versionOnly
     ? null
     : await releaseNotes(cwd, { ...options, tag, existingChangelog: await readChangelog(cwd) });
@@ -42,7 +42,8 @@ export async function planRelease(options = {}) {
     actions: releaseActions({
       version,
       tag,
-      skipCommit: options.skipCommit || options.versionOnly || options.changelogOnly,
+      commit: createsCommit(options),
+      tagRelease: createsTag(options),
       versionOnly: options.versionOnly,
       changelogOnly: options.changelogOnly,
       files,
@@ -58,8 +59,7 @@ export async function runRelease(options = {}) {
     return plan;
   }
 
-  await assertCleanWorktree(cwd);
-  if (!options.skipCommit && !options.versionOnly && !options.changelogOnly) {
+  if (createsTag(options)) {
     await assertTagAvailable(cwd, plan.tag);
   }
 
@@ -71,23 +71,25 @@ export async function runRelease(options = {}) {
     await prependChangelog(cwd, plan.version, options);
   }
 
-  if (options.skipCommit || options.versionOnly || options.changelogOnly) {
-    return { ...plan, tag: null };
+  if (!createsCommit(options)) {
+    return { ...plan, createdTag: null };
   }
 
   await git(cwd, ['add', ...await releaseFiles(cwd)]);
   await git(cwd, ['commit', '-m', `chore(release): ${plan.version}`]);
-  try {
-    await git(cwd, ['tag', '-a', plan.tag, '-m', `Release ${plan.version}`]);
-  } catch (error) {
-    await git(cwd, ['reset', '--soft', 'HEAD~1']);
-    throw new Error(`Failed to create git tag ${plan.tag}; release commit was undone and file changes were left in the working tree. ${error.message}`);
+  if (createsTag(options)) {
+    try {
+      await git(cwd, ['tag', '-a', plan.tag, '-m', `Release ${plan.version}`]);
+    } catch (error) {
+      await git(cwd, ['reset', '--soft', 'HEAD~1']);
+      throw new Error(`Failed to create git tag ${plan.tag}; release commit was undone and file changes were left in the working tree. ${error.message}`);
+    }
   }
 
-  return plan;
+  return createsTag(options) ? { ...plan, createdTag: plan.tag } : { ...plan, createdTag: null };
 }
 
-function releaseActions({ version, tag, skipCommit = false, versionOnly = false, changelogOnly = false, files = [] }) {
+function releaseActions({ version, tag, commit = false, tagRelease = false, versionOnly = false, changelogOnly = false, files = [] }) {
   const actions = [];
   if (!changelogOnly) {
     actions.push(`update package.json version to ${version}`);
@@ -98,28 +100,41 @@ function releaseActions({ version, tag, skipCommit = false, versionOnly = false,
   if (!versionOnly) {
     actions.push(`prepend CHANGELOG.md entry for ${version}`);
   }
-  if (!skipCommit) {
+  if (commit) {
     actions.push(`create git commit chore(release): ${version}`);
+  }
+  if (tagRelease) {
     actions.push(`create git tag ${tag}`);
   }
   return actions;
 }
 
+function createsCommit(options) {
+  return Boolean(options.commit || options.tag || options.push) && !options.skipCommit && !options.versionOnly && !options.changelogOnly;
+}
+
+function createsTag(options) {
+  return Boolean(options.tag || options.push) && createsCommit(options);
+}
+
 async function prependChangelog(cwd, version, options = {}) {
   const existing = await readChangelog(cwd);
 
   const notes = await releaseNotes(cwd, {
     ...options,
     existingChangelog: existing,
-    tag: `${options.tagPrefix ?? ''}${version}`,
+    tag: `${options.tagPrefix ?? 'v'}${version}`,
   });
   const heading = formatReleaseHeading({
     version,
     previousTag: notes.previousTag,
-    tag: options.tagPrefix ? `${options.tagPrefix}${version}` : version,
+    tag: `${options.tagPrefix ?? 'v'}${version}`,
     compareUrlBuilder: notes.compareUrlBuilder,
   });
-  const entry = `${heading}\n\n${formatReleaseNotes(notes.changes, options.changelogSections)}${formatFullChangelog(notes.requests)}\n`;
+  const compareUrl = notes.previousTag && notes.compareUrlBuilder
+    ? notes.compareUrlBuilder(notes.previousTag, `${options.tagPrefix ?? 'v'}${version}`)
+    : null;
+  const entry = `${heading}\n\n${formatReleaseNotes(notes.changes, options.changelogSections)}${formatFullChangelog(notes.requests, compareUrl)}\n`;
 
   const body = existing.trim().startsWith('# Changelog')
     ? existing.replace(/^# Changelog\s*/, `# Changelog\n\n${entry}\n`)