@entro314labs/release-kit 2.4.0 → 2.6.0

package/README.md

@@ -430,6 +430,18 @@ re-deriving it: `version`, `tag`, `name`, `dist-tag`, `steps`, `published`, `rel
 Nothing is written on a dry run, and an unwritable `$GITHUB_OUTPUT` never fails a release
 that already completed.
 
+Two upstream habits make commit-derived notes trustworthy, and neither is release-kit's job:
+
+- **Gate the release on CI, and guard against forks.** Trigger on `workflow_run` after your
+  check workflow succeeds, with `if: github.repository_owner == 'your-org'` so a fork never
+  tries to release.
+- **Validate pull request titles.** A squash-merge takes its subject from the PR title, so
+  that title becomes the commit the notes are built from.
+  [`amannn/action-semantic-pull-request`](https://github.com/amannn/action-semantic-pull-request)
+  enforces it. Without something like it, work silently goes missing from release notes —
+  release-kit says how many commits are not Conventional Commits, but it cannot fix them
+  after the fact.
+
 Three things CI does that are worth knowing about:
 
 - **`fetch-depth: 0`.** The default checkout is a shallow clone, which hides the history
@@ -552,7 +564,10 @@ downgrade, so a configured pipeline fails loudly; `"auto"` degrades quietly by d
   than committed. Attribution lines (`Co-Authored-By`, `Generated with`) are stripped, so
   the tool never signs your commits.
 - **Release notes** are drafted from the commits since the last tag when `CHANGELOG.md` has
-  no section for the version. They are written into the changelog, used as the tag
+  no section for the version. Each bullet ends with a link to the commits it covers: the
+  assistant is given the short hashes and asked to cite them, and every citation is checked
+  against the commits that actually exist. Models invent plausible-looking hashes, so an
+  unrecognised one is removed rather than published as a link to nothing. They are written into the changelog, used as the tag
   annotation, and posted as the GitHub release body — the same "written once, lands in three
   places" path a hand-written section takes.
 
@@ -621,6 +636,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entro314labs/release-kit",
-  "version": "2.4.0",
+  "version": "2.6.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",

package/release.mjs

@@ -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
 }
 
@@ -630,8 +644,36 @@ function draftCommitMessage() {
  *
  * @returns {string | null} markdown body (no version heading), or null
  */
-function draftReleaseNotes(version, subjects, lastTag) {
-  if (!subjects.length) return null
+/**
+ * Attach commit links to a drafted bullet's citation.
+ *
+ * The model is asked to end each bullet with the short hashes it covers. Models invent
+ * plausible-looking hashes, so every citation is checked against the commits that actually
+ * exist: real ones become links, invented ones are removed rather than published.
+ *
+ * @returns {string} the notes with citations resolved
+ */
+function linkCitedCommits(notes, commits, links) {
+  const known = new Set(commits.map((c) => (c.hash ?? '').slice(0, 7)).filter(Boolean))
+  return notes.replace(/\s*\(([0-9a-f]{7,40}(?:\s*,\s*[0-9a-f]{7,40})*)\)\s*$/gim, (_, cited) => {
+    const real = [
+      ...new Set(cited.split(/\s*,\s*/).map((h) => h.toLowerCase().slice(0, 7))),
+    ].filter((h) => known.has(h))
+    if (!real.length) return ''
+    const rendered = links
+      ? real.map((h) => `[${h}](${links.commit}/${h})`)
+      : real.map((h) => `\`${h}\``)
+    return ` (${rendered.join(', ')})`
+  })
+}
+
+/**
+ * Draft release notes from the commit log.
+ *
+ * @returns {string | null} markdown body (no version heading), or null
+ */
+function draftReleaseNotes(version, commits, lastTag, links) {
+  if (!commits.length) return null
 
   const prompt = [
     `Write release notes for version ${version}.`,
@@ -640,18 +682,23 @@ function draftReleaseNotes(version, subjects, lastTag) {
     '- Group the changes under Keep a Changelog headings (`### Added`, `### Changed`,',
     '  `### Fixed`, `### Removed`), including only the headings that apply.',
     '- One bullet per user-visible change. Merge related commits into a single bullet.',
+    '- End every bullet with the short hashes it covers, in parentheses: `(abc1234)` or',
+    '  `(abc1234, def5678)` when merged. Copy them exactly from the list below and invent',
+    '  nothing — a hash that is not in the list will be removed.',
     '- Omit internal chores: CI, linting, formatting, dependency bumps, version bumps.',
     '- Write for someone upgrading: say what changed for them, not which files moved.',
     '- Plain, factual language. No hype, no emoji, no concluding summary.',
     '- Output only the markdown body: no version heading, no code fences, no attribution.',
     '- Do NOT explain your reasoning or add any commentary before or after the notes.',
     '',
-    `Commit subjects since ${lastTag ?? 'the start of the project'}:`,
-    ...subjects.map((s) => `- ${s}`),
+    `Commits since ${lastTag ?? 'the start of the project'}:`,
+    ...commits.map((c) => `- ${(c.hash ?? '').slice(0, 7)} ${c.subject}`),
   ].join('\n')
 
   const drafted = runAssistant(prompt)
-  return drafted ? cleanNotes(drafted) : null
+  if (!drafted) return null
+  const cleaned = cleanNotes(drafted)
+  return cleaned ? linkCitedCommits(cleaned, commits, links) : null
 }
 
 /** One-line rendering of an argv, so a multi-line arg (release notes) stays readable. */
@@ -841,8 +888,50 @@ function changelogSection(text, version) {
 }
 
 /**
- * Rewrite a `## [Unreleased]` heading as the released version, and open a fresh
- * `## [Unreleased]` above it for the next cycle.
+ * Version sections that sit above a newer one.
+ *
+ * Placement only keeps a changelog tidy going forward; a file already out of order stays
+ * that way, and its disorder is invisible until a release lands somewhere surprising.
+ *
+ * @returns {string[]} the versions found out of order, newest-first order being expected
+ */
+function changelogOutOfOrder(text) {
+  const versions = [...text.matchAll(/^## \[?v?(\d+\.\d+\.\d+(?:-[\w.]+)?)\]?/gm)].map((m) => m[1])
+  return versions.filter((v, i) => i > 0 && compareVersions(versions[i - 1], v) < 0)
+}
+
+/** The `## ` heading offsets in a changelog, in file order. */
+const sectionOffsets = (text) => [...text.matchAll(/^## .*$/gm)].map((m) => m.index)
+
+/**
+ * Place a version's section where it belongs: above the first section whose version is
+ * lower, rather than wherever the file happens to start.
+ *
+ * Blindly inserting at the top is correct only while the file is already newest-first. A
+ * changelog that drifts out of order once then stays that way, and every release makes it
+ * worse — which is how a released version ends up sitting between two older ones.
+ */
+function insertChangelogSection(text, version, date, body) {
+  const entry = `## [${version}] - ${date}\n\n${body}\n`
+  for (const offset of sectionOffsets(text)) {
+    const heading = /^## \[?v?([\d.]+(?:-[\w.]+)?)\]?/m.exec(
+      text.slice(offset, text.indexOf('\n', offset)),
+    )
+    // An [Unreleased] heading has no version and always stays above the releases.
+    if (!heading) continue
+    if (compareVersions(version, heading[1]) > 0) {
+      return `${text.slice(0, offset)}${entry}\n${text.slice(offset)}`
+    }
+  }
+  const trimmed = text.trimEnd()
+  return `${trimmed}\n\n${entry}`
+}
+
+/**
+ * Promote `## [Unreleased]` to a released version and reopen an empty one above it.
+ *
+ * The section is lifted out and re-placed in version order, so a misplaced `[Unreleased]`
+ * does not drag the new release into the middle of the file with it.
  *
  * @returns {string | null} the updated document, or null when there is nothing to roll
  */
@@ -856,23 +945,18 @@ function rollUnreleased(text, version, date) {
   if (!match) return null
 
   // An empty [Unreleased] has nothing to promote; rolling it produces an empty section.
-  const rest = text.slice(match.index + match[0].length)
-  const next = /^## /m.exec(rest)
-  const body = (next ? rest.slice(0, next.index) : rest).trim()
+  const after = text.slice(match.index + match[0].length)
+  const next = /^## /m.exec(after)
+  const body = (next ? after.slice(0, next.index) : after).trim()
   if (!body) return null
-  const released = `## [Unreleased]\n\n## [${version}] - ${date}`
-  return text.slice(0, match.index) + released + text.slice(match.index + match[0].length)
-}
 
-/**
- * Insert a section for a version above the newest existing one, so drafted notes are kept
- * in the changelog rather than only reaching the tag and the GitHub release.
- */
-function insertChangelogSection(text, version, date, body) {
-  const entry = `## [${version}] - ${date}\n\n${body}\n`
-  const firstSection = /^## /m.exec(text)
-  if (!firstSection) return `${text.trimEnd()}\n\n${entry}`
-  return `${text.slice(0, firstSection.index)}${entry}\n${text.slice(firstSection.index)}`
+  // Remove the section wherever it sits, then place the release by version.
+  const withoutUnreleased = text.slice(0, match.index) + (next ? after.slice(next.index) : '')
+  const placed = insertChangelogSection(withoutUnreleased.trimEnd() + '\n', version, date, body)
+
+  // A fresh [Unreleased] belongs above every release, whatever the file looked like before.
+  const first = sectionOffsets(placed)[0] ?? placed.length
+  return `${placed.slice(0, first)}## [Unreleased]\n\n${placed.slice(first)}`
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1188,7 +1272,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}`)
 }
@@ -1280,14 +1377,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) {
@@ -1310,7 +1410,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) {
@@ -1616,6 +1719,18 @@ if (!publishCommand) {
   }
 }
 
+/** Say so when the changelog is not newest-first, since placement cannot repair it. */
+function reportChangelogOrder(text) {
+  const misplaced = changelogOutOfOrder(text)
+  if (misplaced.length) {
+    warn(
+      `${config.changelog} is not in newest-first order (${misplaced.slice(0, 3).join(', ')}` +
+        `${misplaced.length > 3 ? ', …' : ''} sit above a newer version).\n` +
+        '       New sections are placed correctly, but the existing order is left alone.',
+    )
+  }
+}
+
 // Notes: the changelog section for this version, else a draft, else GitHub generates them.
 let notes = null
 let rolledChangelog = null
@@ -1635,6 +1750,17 @@ const notesDeferred = !!(dirty && runs('commit') && assistant)
 function draftNotesFor(v) {
   const { lastTag, subjects, commits } = commitsSinceLastTag()
   if (!commits.length) return null
+
+  // Notes are built from Conventional Commits, so anything not written that way is simply
+  // absent from them. A squash-merge takes its subject from the pull request title, which
+  // is where this usually goes wrong — and silently, since the release still succeeds.
+  const unconventional = commits.filter((c) => !parseCommit(c.subject, c.body, c.hash)).length
+  if (unconventional) {
+    warn(
+      `${unconventional} of ${commits.length} commit(s) are not Conventional Commits, so they ` +
+        'will not appear in the notes.',
+    )
+  }
   if (!assistant) return changelogFromCommits(commits, remoteLinks(config.remote))
   if (shallow) {
     warn(
@@ -1644,7 +1770,7 @@ function draftNotesFor(v) {
   }
   note(`drafting notes from ${subjects.length} commit(s) with ${assistantName}...`)
   return (
-    draftReleaseNotes(v, subjects, lastTag) ??
+    draftReleaseNotes(v, commits, lastTag, remoteLinks(config.remote)) ??
     changelogFromCommits(commits, remoteLinks(config.remote))
   )
 }
@@ -1653,11 +1779,13 @@ if (config.changelog && existsSync(config.changelog)) {
   notes = changelogSection(text, version)
   if (notes) {
     ok(`${config.changelog} has a ${version} section`)
+    reportChangelogOrder(text)
   } else {
     rolledChangelog = rollUnreleased(text, version, new Date().toISOString().slice(0, 10))
     if (rolledChangelog) {
       notes = changelogSection(rolledChangelog, version)
       ok(`${config.changelog}: [Unreleased] will become [${version}]`)
+      reportChangelogOrder(text)
     } else {
       draftedNotes = notesDeferred ? null : draftNotesFor(version)
       if (notesDeferred) {