@entro314labs/release-kit 2.3.3 → 2.5.0

package/README.md

@@ -342,6 +342,11 @@ the version. Only the version itself is rewritten, so comments and formatting su
 because the TOML match is anchored to the start of a line, a dependency's
 `serde = { version = "1.0" }` is left alone.
 
+**Lockfiles are scoped automatically.** A `Cargo.lock` records a version for every
+dependency — hundreds of them — so matching the first `version = "…"` would rewrite an
+unrelated crate. Listing one rewrites only the `[[package]]` block whose name matches the
+crate in the sibling `Cargo.toml`; with no sibling to read, it refuses rather than guesses.
+
 For anything else, give a pattern with one capture group around the version. `versionFiles`
 takes the same entries, so several files stay in sync across formats:
 
@@ -352,6 +357,29 @@ takes the same entries, so several files stay in sync across formats:
 }
 ```
 
+A desktop app usually carries the same version in a lot of places at once — a workspace
+manifest, per-platform bundle configs, a crate manifest and its lockfile. They stay in step
+in one release, across three formats, with no scripting:
+
+```json
+{
+  "versionFiles": [
+    "apps/desktop/package.json",
+    "apps/desktop/src-tauri/tauri.conf.json",
+    "apps/desktop/src-tauri/tauri.macos.conf.json",
+    "apps/desktop/src-tauri/tauri.windows.conf.json",
+    "apps/desktop/src-tauri/tauri.linux.conf.json",
+    "apps/desktop/src-tauri/Cargo.toml",
+    "apps/desktop/src-tauri/Cargo.lock"
+  ],
+  "publish": null,
+  "steps": ["version", "changelog", "tag", "push"]
+}
+```
+
+Stopping at `push` because the tag is what triggers the build pipeline — see
+[Libraries versus apps](#-libraries-versus-apps).
+
 The project name comes from the manifest when there is one (`name` in `package.json`,
 `Cargo.toml` or `pyproject.toml`), and falls back to the repository directory.
 
@@ -593,6 +621,18 @@ jobs:
       - run: goreleaser release --clean --release-notes dist-notes.md
 ```
 
+A Go project has no version file at all — the tag is the version — so it is
+`"versionFile": null` and the version is passed explicitly, or inferred with `auto`:
+
+```sh
+release-kit auto      # bump from the commits, tag, push; goreleaser takes it from there
+```
+
+**Only one of the two should write release notes.** goreleaser groups conventional commits
+itself; `--release-notes` makes it use yours instead and skip its own generation. Leaving
+both on means the notes in the GitHub release and the notes in your `CHANGELOG.md` are
+generated by different code from the same commits, and they drift.
+
 **Do not leave `release` in `steps` here.** goreleaser creates the GitHub release itself; if
 release-kit has already created one for that tag, goreleaser fails. Exactly one of them
 should own it, and it should be the one attaching the binaries.
@@ -642,6 +682,17 @@ with the reasoning — are in [ROADMAP.md](ROADMAP.md).
 
 ## 🤝 Contributing
 
+```sh
+pnpm install
+pnpm test     # 63 tests, node --test, no framework
+pnpm check    # format + lint + tests, the same gate CI runs
+```
+
+`test/` holds unit suites for the pure functions and an integration suite that builds real
+throwaway repositories with a real bare remote and stubbed `gh`/`npm`. The integration tests
+pin defects found in use, so a name like "refuses to reuse a tag while still producing a
+commit" is describing something that actually happened.
+
 The tool releases itself, so a change ships the same way it would in any consuming project:
 add a `## [Unreleased]` entry to `CHANGELOG.md`, then run `pnpm release <bump>` from a clone.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entro314labs/release-kit",
-  "version": "2.3.3",
+  "version": "2.5.0",
   "description": "Single-file, zero-dependency release mechanism for JS/TS/Node projects: version bump, changelog roll, commit, annotated tag, push, publish, GitHub release",
   "keywords": [
     "changelog",
@@ -41,12 +41,14 @@
     "format:check": "oxfmt --check .",
     "lint": "oxlint .",
     "lint:ci": "oxlint --deny-warnings .",
-    "check": "pnpm run format:check && pnpm run lint:ci",
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "check": "pnpm run format:check && pnpm run lint:ci && pnpm run test",
     "release": "node release.mjs"
   },
   "devDependencies": {
     "oxfmt": "^0.63.0",
-    "oxlint": "^1.78.0"
+    "oxlint": "^1.78.0",
+    "semver": "^7.8.5"
   },
   "engines": {
     "node": ">=22"

package/release.mjs

@@ -41,7 +41,7 @@ import {
   writeFileSync,
 } from 'node:fs'
 import { homedir, tmpdir } from 'node:os'
-import { basename, join, relative, resolve, sep } from 'node:path'
+import { basename, dirname, join, relative, resolve, sep } from 'node:path'
 import { createInterface } from 'node:readline/promises'
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -419,6 +419,7 @@ const CHANGELOG_SECTIONS = [
   { type: 'fix', section: 'Bug Fixes' },
   { type: 'perf', section: 'Performance Improvements' },
   { type: 'revert', section: 'Reverts' },
+  { type: 'deps', section: 'Dependencies' },
   { type: 'docs', section: 'Documentation', hidden: true },
   { type: 'style', section: 'Styles', hidden: true },
   { type: 'refactor', section: 'Code Refactoring', hidden: true },
@@ -435,7 +436,9 @@ const CHANGELOG_SECTIONS = [
  *   releaseAs: string|null} | null} null when the subject is not Conventional Commits
  */
 function parseCommit(subject, body = '', hash = '') {
-  const match = /^([a-z]+)(?:\(([^)]+)\))?(!)?: (.+)$/i.exec(subject)
+  // Conventional Commits does not restrict the type to letters — `i18n:` and `a11y:` are
+  // types people really use, and `[a-z]+` silently failed to parse them at all.
+  const match = /^([a-z][a-z0-9-]*)(?:\(([^)]+)\))?(!)?: (.+)$/i.exec(subject)
   if (!match) return null
   const [, type, scope, bang, text] = match
   const shortHash = hash.slice(0, 7)
@@ -519,6 +522,7 @@ function changelogFromCommits(commits, links = null) {
     lines.push('')
   }
 
+  const known = new Set(CHANGELOG_SECTIONS.map((s) => s.type))
   for (const { type, section, hidden } of CHANGELOG_SECTIONS) {
     if (hidden) continue
     const inSection = parsed.filter(
@@ -530,6 +534,16 @@ function changelogFromCommits(commits, links = null) {
     lines.push('')
   }
 
+  // A conventional type nobody anticipated — `security:`, `i18n:` — is still a change
+  // someone made deliberately. Dropping it silently is how a security fix goes unmentioned.
+  // The hidden types are excluded because hiding them is the point.
+  const other = parsed.filter((c) => !known.has(c.type) && c.type !== 'feature')
+  if (other.length) {
+    lines.push('### Other Changes', '')
+    for (const c of other) lines.push(bullet(c, c.subject))
+    lines.push('')
+  }
+
   return lines.length ? lines.join('\n').trim() : null
 }
 
@@ -919,9 +933,29 @@ function readNameFrom(entry) {
 /** Normalise a versionFile / versionFiles entry to { path, pattern }. */
 const versionSource = (entry) => (typeof entry === 'string' ? { path: entry } : entry)
 
+/**
+ * A lockfile records a version for every dependency — hundreds of them — so the first
+ * `version = "…"` in the file belongs to whichever crate sorts first, not to this project.
+ * Rewriting it corrupts an unrelated dependency, silently. Scope to the named package block.
+ */
+function cargoLockPattern(lockPath) {
+  const sibling = join(dirname(lockPath), 'Cargo.toml')
+  const crate = existsSync(sibling) ? readNameFrom({ path: sibling }) : null
+  if (!crate) {
+    throw new Error(
+      `${lockPath} lists every dependency's version, so it needs to know which package is ` +
+        `yours.\n  No Cargo.toml beside it to read the name from — give an explicit ` +
+        `pattern:\n  { "path": "${lockPath}", "pattern": "name = \\"<crate>\\"\\nversion = ` +
+        `\\"(.+)\\"" }`,
+    )
+  }
+  return new RegExp(`\\[\\[package\\]\\]\\nname = "${escapeRe(crate)}"\\nversion = "([^"]*)"`)
+}
+
 /** The regex for a source, or null when the whole file is the version. */
 function patternFor({ path, pattern }) {
   if (pattern) return new RegExp(pattern, 'm')
+  if (basename(path) === 'Cargo.lock') return cargoLockPattern(path)
   if (path.endsWith('.json')) return VERSION_PATTERNS.json
   if (path.endsWith('.toml')) return VERSION_PATTERNS.toml
   return null
@@ -941,9 +975,10 @@ function readVersionFrom(entry) {
  * Replace the version in a source file, touching nothing else: only the captured range is
  * rewritten, so formatting, key order and comments all survive.
  *
+ * @param {{dryRun?: boolean}} [options] report the change without making it
  * @returns {boolean} whether the file needed changing
  */
-function writeVersionInto(entry, version) {
+function writeVersionInto(entry, version, { dryRun = false } = {}) {
   const source = versionSource(entry)
   const text = readFileSync(source.path, 'utf8')
   const pattern = patternFor(source)
@@ -1167,7 +1202,20 @@ if (versionFile && !existsSync(versionFile.path)) {
   abort(`versionFile ${versionFile.path} does not exist`)
 }
 
-const currentVersion = versionFile ? readVersionFrom(versionFile) : null
+/**
+ * Where a repository versions by tag alone — a Go module, a docs site — the latest tag is
+ * the current version. Without this, `auto` and every bump have nothing to work from and
+ * the version has to be typed out in full every time.
+ */
+function versionFromLastTag() {
+  const tag = tryRead('git', ['describe', '--tags', '--abbrev=0'])
+  if (!tag) return null
+  const bare =
+    config.tagPrefix && tag.startsWith(config.tagPrefix) ? tag.slice(config.tagPrefix.length) : tag
+  return parseVersion(bare) ? bare : null
+}
+
+const currentVersion = versionFile ? readVersionFrom(versionFile) : versionFromLastTag()
 if (versionFile && !currentVersion) {
   abort(`could not read a version from ${versionFile.path}`)
 }
@@ -1259,14 +1307,17 @@ let version
 if (!target) {
   if (!currentVersion) {
     abort(
-      'this repository has no versionFile, so there is no version to default to.\n' +
-        '  Pass one explicitly: release-kit 1.2.3',
+      'nothing to default to: this repository has no versionFile and no tag to read a ' +
+        'version from.\n  Pass one explicitly: release-kit 1.2.3',
     )
   }
   version = currentVersion
 } else if (target === 'auto') {
   if (!currentVersion) {
-    abort('auto needs a versionFile to bump from. Pass a version explicitly instead.')
+    abort(
+      'auto has nothing to bump from: there is no versionFile and no tag to read a version ' +
+        'from.\n  Pass the first version explicitly: release-kit 0.1.0',
+    )
   }
   const { commits, lastTag } = commitsSinceLastTag()
   if (!commits.length) {
@@ -1289,7 +1340,10 @@ if (!target) {
   }
 } else if (BUMPS.has(target)) {
   if (!currentVersion) {
-    abort(`a ${target} bump needs a versionFile to bump from. Pass a version explicitly instead.`)
+    abort(
+      `a ${target} bump has nothing to bump from: no versionFile, and no tag to read a ` +
+        'version from.\n  Pass the version explicitly instead.',
+    )
   }
   const preid = requestedPreid ?? preidOf(currentVersion)
   if (target.startsWith('pre') && !preid) {
@@ -1754,7 +1808,7 @@ if (bumping) {
   for (const entry of [versionFile, ...config.versionFiles]) {
     const source = versionSource(entry)
     if (!existsSync(source.path)) abort(`versionFiles entry ${source.path} does not exist`)
-    if (writeVersionInto(source, version)) {
+    if (writeVersionInto(source, version, { dryRun })) {
       staged.push(source.path)
       console.log(`  ${dryRun ? yellow('would write') : dim('wrote')} ${source.path}`)
     }