calver-bump 0.1.8 → 1.0.0

package/README.md

@@ -20,8 +20,7 @@ Example:
 2. Updates `package-lock.json` or `npm-shrinkwrap.json` when present.
 3. Warns when `pnpm-lock.yaml` or `yarn.lock` is present, because those lockfiles do not store the root package version consistently.
 4. Creates or prepends a `CHANGELOG.md` entry from conventional commits since the nearest reachable tag.
-5. Creates a release commit.
-6. Creates an annotated git tag.
+5. Prints the git commands needed to commit, tag, and push the reviewed release.
 
 ## Usage
 
@@ -29,6 +28,8 @@ Example:
 npx calver-bump
 ```
 
+By default, `calver-bump` updates files only. Review `CHANGELOG.md`, then run the printed git commands when the release notes are correct.
+
 Preview the planned release without writing files:
 
 ```bash
@@ -107,7 +108,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,6 +165,10 @@ 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` does not commit or tag by default; it prints the follow-up `git add`, `git commit`, `git tag`, and `git push --follow-tags` commands.
+- Use `--commit` to create only the release commit.
+- Use `--tag` to create the release commit and annotated 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.
 - Existing release tags are rejected before files are written.

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,15 +73,24 @@ 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 tag = push || (flag(args, '--tag') ?? config.tag ?? false);
+  const commit = tag || (flag(args, '--commit') ?? config.commit ?? false);
   if (versionOnly && changelogOnly) {
     throw new Error('--version-only cannot be combined with --changelog-only.');
   }
+  if (skipCommit && (commit || 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,
@@ -134,7 +143,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 +160,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() {
@@ -167,8 +210,10 @@ Options:
   --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.0",
   "description": "Release CLI for internal applications using readable CalVer versions.",
   "repository": {
     "type": "git",

package/src/changelog.js

@@ -39,10 +39,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 +69,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 +89,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;
 }
 

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

@@ -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,
@@ -59,7 +60,7 @@ export async function runRelease(options = {}) {
   }
 
   await assertCleanWorktree(cwd);
-  if (!options.skipCommit && !options.versionOnly && !options.changelogOnly) {
+  if (createsTag(options)) {
     await assertTagAvailable(cwd, plan.tag);
   }
 
@@ -71,23 +72,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,13 +101,23 @@ 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);
 
@@ -119,7 +132,10 @@ async function prependChangelog(cwd, version, options = {}) {
     tag: options.tagPrefix ? `${options.tagPrefix}${version}` : 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 ? `${options.tagPrefix}${version}` : 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`)