@entro314labs/release-kit 2.5.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.
 

package/package.json

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

@@ -644,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}.`,
@@ -654,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. */
@@ -855,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
  */
@@ -870,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)}`
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1649,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
@@ -1668,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(
@@ -1677,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))
   )
 }
@@ -1686,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) {