@entro314labs/release-kit 2.5.0 → 2.7.0

package/release.mjs

@@ -69,6 +69,12 @@ import { createInterface } from 'node:readline/promises'
  *   assets          string[] files attached to the GitHub release
  *   notesFile       string   write the resolved release notes here, for a build tool that
  *                            takes them as a file (goreleaser --release-notes, and similar)
+ *   notes           string   where release notes come from: "auto" tries the changelog,
+ *                            then an assistant, then the commits; or force one of
+ *                            changelog / assistant / commits / github
+ *   hiddenTypes     string[] commit types to leave out of the notes; empty means report all
+ *   ignoreCommits   string[] regexes for commits that are bookkeeping rather than change:
+ *                            release commits, merges, work-in-progress, autosquash markers
  *   versioning      string   how `auto` derives a bump: "conventional", or
  *                            always-patch / always-minor / always-major to never infer
  *   assistant       string|object  drafting CLI for commit messages and notes. A key of
@@ -94,8 +100,12 @@ import { createInterface } from 'node:readline/promises'
  */
 const STEPS = ['commit', 'version', 'changelog', 'tag', 'push', 'publish', 'release']
 
-/** Everything but `commit`, which is opt-in because it commits work you did not stage. */
-const DEFAULT_STEPS = STEPS.filter((name) => name !== 'commit')
+/**
+ * All seven. `commit` is a conditional default: it no-ops on a clean tree, and on a dirty
+ * tree it proceeds only when a drafting assistant is configured — otherwise preflight
+ * still refuses the unclean tree. Opt out with `--skip commit` or a `steps` config.
+ */
+const DEFAULT_STEPS = [...STEPS]
 
 const DEFAULTS = {
   steps: DEFAULT_STEPS,
@@ -112,6 +122,14 @@ const DEFAULTS = {
   assistant: null,
   notesFile: null,
   versioning: 'conventional',
+  notes: 'auto',
+  hiddenTypes: [],
+  ignoreCommits: [
+    '^chore\\(release\\)',
+    '^Merge (branch|pull request|remote)',
+    '^wip\\b',
+    '^(fixup|squash)!',
+  ],
 }
 
 /**
@@ -146,13 +164,15 @@ Steps, in the fixed order they run. All but "commit" run by default:
 Flags:
   --only <steps>       run only these steps, comma-separated
   --skip <steps>       run every step except these
-  --commit             add the opt-in commit step: commit a dirty working tree with a
+  --commit             force the commit step on when a steps config removed it:
+                       commit a dirty working tree with a
                        drafted Conventional Commits message instead of refusing to release
   --preid <id>         prerelease identifier (alpha, beta, rc, next, nightly, canary)
   --dist-tag <name>    override the npm dist-tag (default: derived from the version)
   --dry-run            print every step and execute nothing
   --yes, -y            skip the confirmation prompt
   --notes-file <path>  write the resolved release notes to a file for the next tool
+  --notes <source>     where notes come from: auto, changelog, assistant, commits, github
   --assistant <name>   drafting CLI to use: auto, none, claude, codex
   --assistant-model <name>
                        model the assistant runs with (e.g. sonnet, opus)
@@ -382,6 +402,7 @@ function runAssistant(prompt) {
 
 /** Commit subjects since the last tag, with release and merge commits filtered out. */
 function commitsSinceLastTag() {
+  const ignored = (config.ignoreCommits ?? []).map((pattern) => new RegExp(pattern, 'i'))
   const lastTag = tryRead('git', ['describe', '--tags', '--abbrev=0'])
   const range = lastTag ? `${lastTag}..HEAD` : 'HEAD'
   // %B is the whole message: bodies carry BREAKING CHANGE and Release-As footers. A record
@@ -397,22 +418,20 @@ function commitsSinceLastTag() {
       const [subject, ...rest] = message.split('\n')
       return { hash: hash.trim(), subject: subject.trim(), body: rest.join('\n').trim() }
     })
-    .filter(
-      ({ subject }) =>
-        subject &&
-        !/^chore\(release\)/i.test(subject) &&
-        !/^Merge (branch|pull request|remote)/i.test(subject) &&
-        !/^wip\b/i.test(subject) &&
-        !/^(fixup|squash)!/.test(subject),
-    )
+    // Bookkeeping rather than change: the previous release's own commit, merges that
+    // duplicate the branch they bring in, and markers meant to be autosquashed away.
+    .filter(({ subject }) => subject && !ignored.some((re) => re.test(subject)))
   const kept = withoutRevertedCommits(commits)
   return { lastTag, commits: kept, subjects: kept.map((c) => c.subject) }
 }
 
 /**
- * Conventional Commit types and the changelog heading each lands under, following
- * release-please's defaults. Types marked hidden are real changes but not release notes:
- * a reader upgrading does not need to know the CI config moved.
+ * Conventional Commit types and the changelog heading each lands under.
+ *
+ * Every type is reported. release-please and goreleaser hide `chore`, `ci`, `docs` and the
+ * rest by default, on the view that a reader upgrading does not care — but a changelog is a
+ * record, and silently omitting work makes it a partial one. A project that wants the
+ * shorter version lists the types to drop in `hiddenTypes`.
  */
 const CHANGELOG_SECTIONS = [
   { type: 'feat', section: 'Features' },
@@ -420,13 +439,13 @@ const CHANGELOG_SECTIONS = [
   { 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 },
-  { type: 'test', section: 'Tests', hidden: true },
-  { type: 'build', section: 'Build System', hidden: true },
-  { type: 'ci', section: 'Continuous Integration', hidden: true },
-  { type: 'chore', section: 'Miscellaneous Chores', hidden: true },
+  { type: 'docs', section: 'Documentation' },
+  { type: 'refactor', section: 'Code Refactoring' },
+  { type: 'build', section: 'Build System' },
+  { type: 'ci', section: 'Continuous Integration' },
+  { type: 'test', section: 'Tests' },
+  { type: 'style', section: 'Styles' },
+  { type: 'chore', section: 'Miscellaneous Chores' },
 ]
 
 /**
@@ -498,7 +517,7 @@ function inferBump(commits, currentVersion, strategy = 'conventional') {
  *
  * @returns {string | null} markdown body, or null when nothing visible changed
  */
-function changelogFromCommits(commits, links = null) {
+function changelogFromCommits(commits, links = null, hidden = []) {
   const parsed = commits.map((c) => parseCommit(c.subject, c.body, c.hash)).filter(Boolean)
   const lines = []
 
@@ -523,8 +542,9 @@ function changelogFromCommits(commits, links = null) {
   }
 
   const known = new Set(CHANGELOG_SECTIONS.map((s) => s.type))
-  for (const { type, section, hidden } of CHANGELOG_SECTIONS) {
-    if (hidden) continue
+  const hiddenTypes = new Set(hidden)
+  for (const { type, section } of CHANGELOG_SECTIONS) {
+    if (hiddenTypes.has(type)) continue
     const inSection = parsed.filter(
       (c) => c.type === type || (type === 'feat' && c.type === 'feature'),
     )
@@ -537,7 +557,9 @@ function changelogFromCommits(commits, links = null) {
   // 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')
+  const other = parsed.filter(
+    (c) => !known.has(c.type) && c.type !== 'feature' && !hiddenTypes.has(c.type),
+  )
   if (other.length) {
     lines.push('### Other Changes', '')
     for (const c of other) lines.push(bullet(c, c.subject))
@@ -644,8 +666,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 +704,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 +910,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 +967,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)}`
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1028,6 +1120,7 @@ const explicitDistTag = option('--dist-tag')
 const requestedPreid = option('--preid')
 const autoCommit = flag('--commit')
 const requestedNotesFile = option('--notes-file')
+const requestedNotesSource = option('--notes')
 const requestedAssistant = option('--assistant')
 const requestedModel = option('--assistant-model')
 const requestedEffort = option('--assistant-effort')
@@ -1096,23 +1189,33 @@ const VALUE_OPTIONS = new Set([
   '--skip',
   '--preid',
   '--dist-tag',
+  '--notes',
   '--notes-file',
   '--assistant',
   '--assistant-model',
   '--assistant-effort',
 ])
 
-/** The version or bump target: the first argument that is neither a flag nor a flag's value. */
-const target = (() => {
-  for (let i = 0; i < argv.length; i += 1) {
-    if (VALUE_OPTIONS.has(argv[i])) {
-      i += 1
-      continue
-    }
-    if (!argv[i].startsWith('-')) return argv[i]
+/** The version or bump target: the only argument that is neither a flag nor a flag's value. */
+const positionals = []
+for (let i = 0; i < argv.length; i += 1) {
+  if (VALUE_OPTIONS.has(argv[i])) {
+    i += 1
+    continue
   }
-  return undefined
-})()
+  if (!argv[i].startsWith('-')) positionals.push(argv[i])
+}
+const target = positionals[0]
+// A second positional is always a mistake, and silently ignoring it changes the release
+// that runs — `release-kit auto assistant auto` must not quietly mean `release-kit auto`.
+if (positionals.length > 1) {
+  const extras = positionals.slice(1)
+  const flagLike = extras.find((arg) => VALUE_OPTIONS.has(`--${arg}`))
+  const hint = flagLike
+    ? `\n  Flags are spelled with dashes: --${flagLike} ${extras[extras.indexOf(flagLike) + 1] ?? '<value>'}`
+    : ''
+  abort(`unexpected argument${extras.length > 1 ? 's' : ''}: ${extras.join(' ')}${hint}`)
+}
 
 // ─────────────────────────────────────────────────────────────────────────────
 // SETUP
@@ -1144,7 +1247,8 @@ if (unknownKeys.length) abort(`release.config.json has unknown keys: ${unknownKe
 
 /**
  * Which steps run: config provides the baseline, --only replaces it, --skip subtracts, and
- * --commit adds the opt-in step. Unknown names are an error rather than a silent no-op.
+ * --commit forces the step on when a steps config removed it. Unknown names are an
+ * error rather than a silent no-op.
  */
 const parseStepList = (value) =>
   value
@@ -1469,7 +1573,7 @@ if (bumping && compareVersions(version, currentVersion) <= 0) {
 
 const dirty = tryRead('git', ['status', '--porcelain'])
 if (dirty === null) fail('could not read git status')
-else if (dirty && runs('commit')) {
+else if (dirty && runs('commit') && assistant) {
   const entries = dirty.split('\n')
   ok(`working tree has ${entries.length} change(s) — will be committed first`)
   console.log(dim(indent(formatStatus(dirty))))
@@ -1488,16 +1592,17 @@ else if (dirty && runs('commit')) {
         'releasing with --skip commit.',
     )
   }
+} else if (dirty && runs('commit')) {
+  fail(
+    `working tree is not clean:\n${indent(formatStatus(dirty))}\n` +
+      '       Configure a drafting assistant (`--assistant auto`, or "assistant" in ' +
+      'release.config.json) to have these committed automatically, or commit them yourself.',
+  )
 } else if (dirty) {
   fail(`working tree is not clean:\n${indent(formatStatus(dirty))}`)
 } else ok('working tree clean')
 
-if (runs('commit') && !assistant) {
-  fail(
-    'the commit step needs a drafting assistant to write the message. Configure one with ' +
-      '`--assistant auto`, or set "assistant" in release.config.json.',
-  )
-} else if (assistant) {
+if (assistant) {
   const detail = [
     assistantModel && `model ${assistantModel}`,
     assistantEffort && `effort ${assistantEffort}`,
@@ -1649,7 +1754,35 @@ if (!publishCommand) {
   }
 }
 
-// Notes: the changelog section for this version, else a draft, else GitHub generates them.
+/** 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.',
+    )
+  }
+}
+
+/**
+ * Where the notes come from. "auto" walks the list — a hand-written changelog section beats
+ * anything generated — while an explicit source forces one, because asking for a thing and
+ * being given something else is worse than being told the thing is unavailable.
+ */
+const NOTE_SOURCES = ['auto', 'changelog', 'assistant', 'commits', 'github']
+const notesSource = requestedNotesSource ?? config.notes ?? 'auto'
+if (!NOTE_SOURCES.includes(notesSource)) {
+  abort(`unknown notes source "${notesSource}". Known: ${NOTE_SOURCES.join(', ')}`)
+}
+if (notesSource === 'assistant' && !assistant) {
+  abort(
+    'notes are set to come from an assistant, but none is available.\n' +
+      '  Add --assistant auto, or set "assistant" in release.config.json.',
+  )
+}
+
 let notes = null
 let rolledChangelog = null
 let draftedNotes = null
@@ -1668,7 +1801,20 @@ const notesDeferred = !!(dirty && runs('commit') && assistant)
 function draftNotesFor(v) {
   const { lastTag, subjects, commits } = commitsSinceLastTag()
   if (!commits.length) return null
-  if (!assistant) return changelogFromCommits(commits, remoteLinks(config.remote))
+
+  // 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.',
+    )
+  }
+  // An explicitly named source wins over the assistant being merely available.
+  if (!assistant || notesSource === 'commits')
+    return changelogFromCommits(commits, remoteLinks(config.remote), config.hiddenTypes)
   if (shallow) {
     warn(
       `shallow clone: only ${subjects.length} commit(s) are visible, so the notes will ` +
@@ -1677,41 +1823,59 @@ function draftNotesFor(v) {
   }
   note(`drafting notes from ${subjects.length} commit(s) with ${assistantName}...`)
   return (
-    draftReleaseNotes(v, subjects, lastTag) ??
-    changelogFromCommits(commits, remoteLinks(config.remote))
+    draftReleaseNotes(v, commits, lastTag, remoteLinks(config.remote)) ??
+    changelogFromCommits(commits, remoteLinks(config.remote), config.hiddenTypes)
   )
 }
-if (config.changelog && existsSync(config.changelog)) {
-  const text = readFileSync(config.changelog, 'utf8')
-  notes = changelogSection(text, version)
-  if (notes) {
-    ok(`${config.changelog} has a ${version} section`)
-  } else {
-    rolledChangelog = rollUnreleased(text, version, new Date().toISOString().slice(0, 10))
+const changelogText =
+  config.changelog && existsSync(config.changelog) ? readFileSync(config.changelog, 'utf8') : null
+if (changelogText) reportChangelogOrder(changelogText)
+
+// `github` means write nothing and let GitHub generate from the commit log.
+if (notesSource === 'github') {
+  note('notes will be generated by GitHub')
+} else if (notesSource === 'changelog' && !changelogText) {
+  fail(`notes are set to come from ${config.changelog}, which does not exist`)
+} else {
+  const wantsChangelog = notesSource === 'auto' || notesSource === 'changelog'
+
+  // A section already written for this version is the most authoritative thing there is.
+  if (wantsChangelog && changelogText) {
+    notes = changelogSection(changelogText, version)
+    if (notes) ok(`${config.changelog} has a ${version} section`)
+  }
+
+  // Otherwise promote [Unreleased], which is equally hand-written.
+  if (!notes && wantsChangelog && changelogText) {
+    rolledChangelog = rollUnreleased(changelogText, version, new Date().toISOString().slice(0, 10))
     if (rolledChangelog) {
       notes = changelogSection(rolledChangelog, version)
       ok(`${config.changelog}: [Unreleased] will become [${version}]`)
+    }
+  }
+
+  // Generate, either because nothing was written or because a source was named.
+  if (!notes) {
+    if (notesDeferred) {
+      ok('release notes will be drafted after the commit')
     } else {
-      draftedNotes = notesDeferred ? null : draftNotesFor(version)
-      if (notesDeferred) {
-        ok(`${config.changelog}: a ${version} section will be drafted after the commit`)
-      } else if (draftedNotes) {
+      draftedNotes = draftNotesFor(version)
+      if (draftedNotes) {
         notes = draftedNotes
-        ok(`${config.changelog}: a ${version} section will be drafted by ${assistantName}`)
-      } else {
+        ok(
+          notesSource === 'commits' || !assistant
+            ? 'release notes built from the commit log'
+            : `release notes drafted by ${assistantName}`,
+        )
+      } else if (notesSource === 'auto') {
         warn(
-          `${config.changelog} has no ${version} or [Unreleased] section — GitHub will generate the notes`,
+          `no ${config.changelog ?? 'changelog'} section and nothing to draft from — GitHub will generate the notes`,
         )
+      } else {
+        fail(`notes are set to come from "${notesSource}", which produced nothing`)
       }
     }
   }
-} else {
-  // No changelog file at all: there is nothing to roll, but notes can still be drafted for
-  // the tag annotation and the GitHub release.
-  notes = notesDeferred ? null : draftNotesFor(version)
-  if (notesDeferred) ok('release notes will be drafted after the commit')
-  else if (notes) ok(`release notes drafted by ${assistantName}`)
-  else if (config.changelog) note(`no ${config.changelog} — GitHub will generate the notes`)
 }
 
 for (const asset of config.assets) {
@@ -1760,7 +1924,7 @@ if (dirty && runs('commit') && !dryRun) {
     mutate('git', ['reset', '--quiet'])
     abort(
       `${assistantName} could not draft a Conventional Commits message for these changes.\n\n` +
-        '  Commit them yourself and re-run, or run without --commit.',
+        '  Commit them yourself and re-run, or release with --skip commit.',
     )
   }
   console.log(indent(commitMessage))