calver-bump 0.1.7 → 1.0.0

package/README.md

@@ -18,9 +18,9 @@ Example:
 
 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 conventional commits since the nearest reachable tag.
-4. Creates a release commit.
-5. Creates an annotated git tag.
+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. Prints the git commands needed to commit, tag, and push the reviewed release.
 
 ## Usage
 
@@ -28,12 +28,26 @@ 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
 npx calver-bump --dry-run
 ```
 
+Print help:
+
+```bash
+npx calver-bump --help
+```
+
+Print the installed `calver-bump` package version:
+
+```bash
+npx calver-bump --version
+```
+
 Use compact CalVer instead:
 
 ```bash
@@ -70,7 +84,43 @@ Only include selected conventional commit types:
 npx calver-bump --types feat,fix,perf
 ```
 
-Update files without creating a release commit or tag:
+Use an explicit changelog base tag:
+
+```bash
+npx calver-bump --from v1.35.0
+```
+
+Use local tags only without fetching from the configured remote:
+
+```bash
+npx calver-bump --no-fetch
+```
+
+Update only `package.json` and supported npm lockfiles:
+
+```bash
+npx calver-bump --version-only
+```
+
+Update only `CHANGELOG.md`:
+
+```bash
+npx calver-bump --changelog-only
+```
+
+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
@@ -85,10 +135,22 @@ Project defaults can be stored in `.calverbumprc.json`:
   "format": "short",
   "tagPrefix": "v",
   "remote": "origin",
-  "types": ["feat", "fix", "perf"]
+  "types": ["feat", "fix", "perf"],
+  "changelogSections": {
+    "perf": "Performance",
+    "security": "Security"
+  }
 }
 ```
 
+## Runtime support
+
+`calver-bump` supports Node.js LTS lines only. The current supported runtime range is Node.js 22 and Node.js 24.
+
+## Publishing
+
+The package includes a manual GitHub Actions publish workflow. Run the `Publish` workflow from GitHub after the package version has been bumped, tests pass, and the npm automation token is available as `NPM_TOKEN`.
+
 ## Notes
 
 - The default `short` format is `YY.MMDD` for the first release of the day, then `YY.MMDD.1`, `YY.MMDD.2`, etc.
@@ -98,11 +160,16 @@ Project defaults can be stored in `.calverbumprc.json`:
 - Existing `v`-prefixed tags are considered when calculating the next sequence number.
 - Changelog ranges start from the nearest 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 are grouped into `Features`, `Fixes`, and `Other Changes` by default. Use `changelogSections` to assign additional conventional commit types to named sections.
 - Changelog entries link to GitHub pull requests or GitLab merge requests when the local git message includes references such as `#123`, `Merge pull request #123`, `!123`, or `See merge request group/project!123`.
 - 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.
-- If tag creation fails after the release commit, the CLI rolls back its own release commit.
+- 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

@@ -8,28 +8,60 @@ import { assertFormat } from '../src/calver.js';
 
 const execFile = promisify(execFileCallback);
 const args = process.argv.slice(2);
+const KNOWN_OPTIONS = new Set([
+  '--changelog-only',
+  '--commit',
+  '--dry-run',
+  '--format',
+  '--from',
+  '--help',
+  '--no-fetch',
+  '--push',
+  '--remote',
+  '--skip-commit',
+  '--tag',
+  '--tag-prefix',
+  '--types',
+  '--version',
+  '--version-only',
+]);
 
 try {
+  if (flag(args, '--help')) {
+    console.log(helpText());
+    process.exit(0);
+  }
+  if (flag(args, '--version')) {
+    const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    console.log(pkg.version);
+    process.exit(0);
+  }
+
   const options = await releaseOptions(args);
   assertFormat(options.format);
   const result = await runRelease(options);
-  console.log(`Release version: ${result.version}`);
+  printResult(result, options);
+  if (result.warnings.length > 0) {
+    console.log('');
+    console.log('Warnings:');
+    for (const warning of result.warnings) {
+      console.log(`- ${warning}`);
+    }
+  }
   for (const action of result.actions) {
     console.log(`- ${action}`);
   }
-  if (options.push && !options.dryRun) {
+  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 && !options.skipCommit) {
+  } 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);
@@ -37,16 +69,36 @@ try {
 }
 
 async function releaseOptions(args) {
+  rejectUnknownOptions(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,
-    push: flag(args, '--push') ?? config.push ?? false,
-    skipCommit: flag(args, '--skip-commit') ?? config.skipCommit ?? false,
+    noFetch: flag(args, '--no-fetch') ?? config.noFetch ?? 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 ?? '',
     types: parseTypes(value(args, '--types')) ?? config.types,
+    changelogSections: config.changelogSections,
   };
 }
 
@@ -80,3 +132,92 @@ function value(args, name) {
 function parseTypes(types) {
   return types?.split(',').map((type) => type.trim()).filter(Boolean);
 }
+
+function rejectUnknownOptions(args) {
+  for (const arg of args) {
+    if (arg.startsWith('--') && !KNOWN_OPTIONS.has(arg)) {
+      throw new Error(`Unknown option ${arg}. Run calver-bump --help for usage.`);
+    }
+  }
+}
+
+function printResult(result, options) {
+  console.log(`Release version: ${result.version}`);
+  console.log(`Git tag: ${result.createdTag ?? '(not created)'}`);
+  console.log(`Branch: ${result.branch}`);
+  console.log(`Remote: ${result.remote}`);
+  if (!options.versionOnly) {
+    console.log(`Changelog range: ${result.range}`);
+    console.log(`Previous tag: ${result.previousTag ?? '(none)'}`);
+  }
+  if (result.files.length > 0) {
+    console.log(`Files: ${result.files.join(', ')}`);
+  }
+  if (options.noFetch) {
+    console.log('Tag fetch: skipped (--no-fetch)');
+  }
+  console.log('');
+  console.log(options.dryRun ? 'Planned actions:' : 'Completed 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);
+}
+
+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() {
+  return `Usage: calver-bump [options]
+
+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.
+  --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.
+  --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.
+
+Configuration:
+  Project defaults can be stored in .calverbumprc.json.`;
+}

package/package.json

@@ -1,11 +1,24 @@
 {
   "name": "calver-bump",
-  "version": "0.1.7",
+  "version": "1.0.0",
   "description": "Release CLI for internal applications using readable CalVer versions.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/msako/calver-bump.git"
+  },
+  "homepage": "https://github.com/msako/calver-bump#readme",
+  "bugs": {
+    "url": "https://github.com/msako/calver-bump/issues"
+  },
   "main": "src/index.js",
   "bin": {
     "calver-bump": "bin/calver-bump.js"
   },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
   "scripts": {
     "test": "node --test"
   },
@@ -19,6 +32,6 @@
   "license": "MIT",
   "type": "module",
   "engines": {
-    "node": ">=20"
+    "node": "^22.0.0 || ^24.0.0"
   }
 }

package/src/changelog.js

@@ -0,0 +1,267 @@
+import { fetchTags, getRemoteUrl, gitCommits, latestReachableTag, tagExists } from './git.js';
+
+const DEFAULT_TYPES = ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert'];
+const DEFAULT_CHANGELOG_SECTIONS = {
+  feat: 'Features',
+  fix: 'Fixes',
+};
+
+export async function releaseNotes(cwd, options = {}) {
+  if (!options.noFetch) {
+    await fetchTags(cwd, options.remote ?? 'origin');
+  }
+  const latestTag = options.from ?? await latestReleaseTag(cwd, options.existingChangelog ?? '');
+  const range = latestTag ? [`${latestTag}..HEAD`] : [];
+  const commits = await gitCommits(cwd, range);
+  const remoteUrl = await getRemoteUrl(cwd, options.remote ?? 'origin');
+  const commitUrlBuilder = remoteUrl ? buildCommitUrlBuilder(remoteUrl) : null;
+  const compareUrlBuilder = remoteUrl ? buildCompareUrlBuilder(remoteUrl) : null;
+  const requestUrlBuilder = remoteUrl ? buildRequestUrlBuilder(remoteUrl) : null;
+  const allowedTypes = options.types ?? DEFAULT_TYPES;
+  const conventionalCommits = dedupeConventionalChanges(commits
+    .map((commit) => ({ ...commit, subject: conventionalSubjectForCommit(commit) ?? commit.subject }))
+    .filter((commit) => isConventionalCommit(commit.subject))
+    .filter((commit) => allowedTypes.includes(conventionalType(commit.subject)))
+    .filter((commit) => !isCommitInChangelog(commit, options.existingChangelog ?? ''))
+    .map((commit) => ({
+      ...commit,
+      request: requestForCommit(commit, requestUrlBuilder),
+      url: commitUrlBuilder ? commitUrlBuilder(commit.hash) : null,
+    })));
+  const requests = uniqueRequests(commits.map((commit) => requestForCommit(commit, requestUrlBuilder)).filter(Boolean));
+  return {
+    previousTag: latestTag,
+    range: latestTag ? `${latestTag}..HEAD` : 'HEAD',
+    compareUrlBuilder,
+    changes: conventionalCommits.length > 0 ? conventionalCommits : ['No conventional commits in this release.'],
+    requests,
+  };
+}
+
+export function formatReleaseHeading({ version, previousTag, tag, compareUrlBuilder }) {
+  return `## ${version}`;
+}
+
+export function formatReleaseNotes(changes, sectionConfig = {}) {
+  if (changes.length === 1 && changes[0] === 'No conventional commits in this release.') {
+    return `- ${changes[0]}`;
+  }
+
+  const sectionMap = { ...DEFAULT_CHANGELOG_SECTIONS, ...sectionConfig };
+  const grouped = new Map();
+  const other = [];
+  for (const change of changes) {
+    const heading = sectionMap[conventionalType(change.subject)];
+    if (!heading) {
+      other.push(change);
+      continue;
+    }
+    grouped.set(heading, [...(grouped.get(heading) ?? []), change]);
+  }
+  const sections = [...grouped.entries()];
+  if (other.length > 0) {
+    sections.push(['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');
+}
+
+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${entries.map((entry) => `- ${entry}`).join('\n')}`;
+}
+
+async function latestReleaseTag(cwd, changelog) {
+  const changelogTag = latestChangelogCompareTarget(changelog);
+  if (changelogTag && await tagExists(cwd, changelogTag)) {
+    return changelogTag;
+  }
+  return latestReachableTag(cwd);
+}
+
+function latestChangelogCompareTarget(changelog) {
+  const match = /\[[^\]]+\]\([^)]*\/(?:-\/)?compare\/[^)]*?\.{3}(?<tag>[^)\s]+)\)/m.exec(changelog);
+  return match?.groups.tag ?? null;
+}
+
+function isCommitInChangelog(commit, changelog) {
+  if (!changelog) return false;
+  return changelog.includes(commit.hash) || changelog.includes(commit.hash.slice(0, 7));
+}
+
+function isConventionalCommit(subject) {
+  return /^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([^)]+\))?!?: .+/.test(subject);
+}
+
+function conventionalSubjectForCommit(commit) {
+  return commitLines(commit).find((line) => isConventionalCommit(line)) ?? null;
+}
+
+function commitLines(commit) {
+  return [commit.subject, ...(commit.body ?? '').split('\n')]
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function dedupeConventionalChanges(changes) {
+  const deduped = [];
+  for (const change of changes) {
+    const existingIndex = deduped.findIndex((candidate) => candidate.subject === change.subject);
+    if (existingIndex < 0) {
+      deduped.push(change);
+      continue;
+    }
+    if (!deduped[existingIndex].request && change.request) {
+      deduped[existingIndex] = change;
+    }
+  }
+  return deduped;
+}
+
+function conventionalType(subject) {
+  return /^(?<type>[a-z]+)(\([^)]+\))?!?: .+/.exec(subject)?.groups.type;
+}
+
+function formatCommitEntry(commit) {
+  const shortHash = commit.hash.slice(0, 7);
+  const suffix = commit.request
+    ? ` (${formatRequestLink(commit.request)})`
+    : commit.url ? ` ([${shortHash}](${commit.url}))` : ` (${shortHash})`;
+  return `${commit.subject}${suffix}`;
+}
+
+function formatRequestLink(request) {
+  return request.url ? `[${request.label}](${request.url})` : request.label;
+}
+
+function formatRequestEntry(request) {
+  return request.title ? `${formatRequestLink(request)} ${request.title}` : formatRequestLink(request);
+}
+
+function buildCommitUrlBuilder(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 buildCompareUrlBuilder(remote) {
+  const parsed = parseGitRemote(remote);
+  if (!parsed) {
+    return null;
+  }
+
+  const baseUrl = `https://${parsed.host}/${parsed.repo}`;
+  if (parsed.host === 'github.com') {
+    return (from, to) => `${baseUrl}/compare/${from}...${to}`;
+  }
+  if (parsed.host.includes('gitlab')) {
+    return (from, to) => `${baseUrl}/-/compare/${from}...${to}`;
+  }
+
+  return null;
+}
+
+function buildRequestUrlBuilder(remote) {
+  const parsed = parseGitRemote(remote);
+  if (!parsed) {
+    return null;
+  }
+
+  const baseUrl = `https://${parsed.host}/${parsed.repo}`;
+  if (parsed.host === 'github.com') {
+    return (request) => request.provider === 'github' ? `${baseUrl}/pull/${request.number}` : null;
+  }
+  if (parsed.host.includes('gitlab')) {
+    return (request) => request.provider === 'gitlab' ? `${baseUrl}/-/merge_requests/${request.number}` : null;
+  }
+
+  return null;
+}
+
+function requestForCommit(commit, requestUrlBuilder) {
+  const request = parseRequestReference(`${commit.subject}\n${commit.body ?? ''}`);
+  if (!request) {
+    return null;
+  }
+  return {
+    ...request,
+    title: requestTitleForCommit(commit),
+    url: requestUrlBuilder ? requestUrlBuilder(request) : null,
+  };
+}
+
+function requestTitleForCommit(commit) {
+  const conventionalSubject = conventionalSubjectForCommit(commit);
+  if (conventionalSubject) {
+    return conventionalSubject;
+  }
+
+  return commitLines(commit)
+    .find((line) => line && !parseRequestReference(line) && !/^Merge\b/i.test(line)) ?? null;
+}
+
+function parseRequestReference(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}` };
+  }
+
+  const githubPull = /(?:Merge pull request\s+#|#)(?<number>\d+)(?=\D|$)/i.exec(message);
+  if (githubPull) {
+    return { provider: 'github', number: githubPull.groups.number, label: `#${githubPull.groups.number}` };
+  }
+
+  return null;
+}
+
+function uniqueRequests(requests) {
+  const seen = new Set();
+  const unique = [];
+  for (const request of requests) {
+    const key = `${request.provider}:${request.number}`;
+    if (seen.has(key)) {
+      const existing = unique.find((candidate) => `${candidate.provider}:${candidate.number}` === key);
+      if (existing && !existing.title && request.title) {
+        existing.title = request.title;
+      }
+      continue;
+    }
+    seen.add(key);
+    unique.push(request);
+  }
+  return unique;
+}
+
+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;
+}