@entro314labs/release-kit 2.6.0 → 2.8.0

package/release.mjs

@@ -69,8 +69,17 @@ 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
+ *   verify          string   command run during preflight — a project's own gate (tests,
+ *                            build). Non-zero aborts before anything mutates, instead of a
+ *                            prepublishOnly hook failing after the commit, tag and push
  *   assistant       string|object  drafting CLI for commit messages and notes. A key of
  *                            ASSISTANTS, "auto" for the first available, or null. The
  *                            object form { tool, model, effort } also pins which model and
@@ -94,8 +103,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 +125,15 @@ const DEFAULTS = {
   assistant: null,
   notesFile: null,
   versioning: 'conventional',
+  notes: 'auto',
+  hiddenTypes: [],
+  ignoreCommits: [
+    '^chore\\(release\\)',
+    '^Merge (branch|pull request|remote)',
+    '^wip\\b',
+    '^(fixup|squash)!',
+  ],
+  verify: null,
 }
 
 /**
@@ -143,16 +165,25 @@ Target (optional; defaults to the version already in package.json):
 Steps, in the fixed order they run. All but "commit" run by default:
   ${STEPS.join('  ')}
 
+Subcommands (they check or copy, and never start a release):
+  lint-commits [<range>]
+                       check commit subjects against Conventional Commits
+                       (default range: since the last tag)
+  lint-commits --subject <text>
+                       check one subject — a pull request title before it is squashed
+
 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)
@@ -203,8 +234,8 @@ const formatStatus = (porcelain) =>
     })
     .join('\n')
 
-function abort(message) {
-  console.log(`\n${red(bold('RELEASE ABORTED'))} — ${message}\n`)
+function abort(message, title = 'RELEASE ABORTED') {
+  console.log(`\n${red(bold(title))} — ${message}\n`)
   process.exit(1)
 }
 
@@ -382,6 +413,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 +429,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 +450,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 +528,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 +553,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 +568,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))
@@ -602,8 +635,104 @@ function withoutRevertedCommits(commits) {
   )
 }
 
-const CONVENTIONAL_TYPES = 'build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test'
-const CONVENTIONAL_RE = new RegExp(`^(${CONVENTIONAL_TYPES})(\\([^)]+\\))?!?: .+`)
+/**
+ * Semver strings a drafted message names that the staged changes never touch. The prompt
+ * forbids narrating versions, but a model can still read an unchanged `"version"` context
+ * line and describe it as work — a draft once claimed "release v1.4.5" for a commit that
+ * changed no version at all. Only added and removed lines are the change.
+ */
+function inventedVersions(message, changedLines) {
+  const versions = message.match(/\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/g) ?? []
+  return [...new Set(versions)].filter((version) => !changedLines.includes(version))
+}
+
+/**
+ * A repository URL reduced to what identifies the repository: `git+` and protocol
+ * prefixes, the `git@host:` shorthand, a trailing `.git` and letter case all vary between
+ * package.json and a git remote without meaning a different repo.
+ */
+function normalizeRepoUrl(url) {
+  if (!url) return null
+  return url
+    .trim()
+    .replace(/^git\+/, '')
+    .replace(/^git@([^:]+):/, 'https://$1/')
+    .replace(/^ssh:\/\/git@/, 'https://')
+    .replace(/^git:\/\//, 'https://')
+    .replace(/\.git$/, '')
+    .replace(/\/+$/, '')
+    .toLowerCase()
+}
+
+/**
+ * A deterministic Conventional Commits message built from the staged file list — the
+ * floor under the drafting assistant. A release is never blocked because a text
+ * generator was unavailable or produced an unusable answer: the honest fallback is a
+ * chore commit that names what it touches, with the full paths in the body.
+ */
+function fallbackCommitMessage(files) {
+  const named = `chore: update ${files.map((file) => basename(file)).join(' and ')}`
+  const subject =
+    files.length > 0 && files.length <= 2 && named.length <= 72
+      ? named
+      : `chore: update ${files.length} files`
+  const body = files.length > 2 ? files.map((file) => `- ${file}`).join('\n') : ''
+  return body ? `${subject}\n\n${body}` : subject
+}
+
+/**
+ * The types worth writing: every one has a changelog section of its own.
+ *
+ * Derived from CHANGELOG_SECTIONS rather than written out again, because the hand-kept
+ * copy had already drifted — it omitted `deps`, so the drafter could never produce a
+ * subject for the Dependencies section the changelog has always had.
+ */
+const CHANGELOG_TYPES = CHANGELOG_SECTIONS.map((s) => s.type)
+
+/** The drafter's types plus `feature`, the alias `changelogFromCommits` folds into feat. */
+const KNOWN_TYPES = new Set([...CHANGELOG_TYPES, 'feature'])
+const CONVENTIONAL_RE = new RegExp(`^(${[...KNOWN_TYPES].join('|')})(\\([^)]+\\))?!?: .+`)
+
+/**
+ * Check commit subjects against the grammar the rest of this file reads.
+ *
+ * Two severities, because the two failures do not cost the same:
+ *
+ *  - A subject `parseCommit` cannot read is invisible. It contributes nothing to the
+ *    inferred bump and never reaches the changelog, so the work simply disappears.
+ *  - A type outside CHANGELOG_SECTIONS is merely unfiled: `changelogFromCommits` still
+ *    prints it under "Other Changes". `security:` and `i18n:` warn rather than fail —
+ *    refusing them would make this stricter than the tool it is meant to protect.
+ *
+ * Case is not one of the failures: `parseCommit` folds the type, so `Feat:` bumps and files
+ * exactly as `feat:` does. The drafter is stricter about its own output than this is about
+ * anybody's commits, and deliberately so.
+ *
+ * @param {{subject: string, hash?: string}[]} commits
+ * @returns {{subject: string, hash: string, level: 'error'|'warn', reason: string}[]}
+ */
+function lintSubjects(commits) {
+  const findings = []
+  for (const { subject, hash = '' } of commits) {
+    const parsed = parseCommit(subject)
+    if (!parsed) {
+      findings.push({
+        subject,
+        hash,
+        level: 'error',
+        reason: `not Conventional Commits — expected "<type>(<scope>): <description>" with type one of ${CHANGELOG_TYPES.join(', ')}`,
+      })
+    } else if (!KNOWN_TYPES.has(parsed.type)) {
+      findings.push({
+        subject,
+        hash,
+        level: 'warn',
+        reason: `type "${parsed.type}" has no changelog section — it lands under "Other Changes"`,
+      })
+    }
+  }
+  return findings
+}
 
 /**
  * Draft a Conventional Commits message for the staged changes.
@@ -620,11 +749,15 @@ function draftCommitMessage() {
     'Write a Conventional Commits message for these staged changes.',
     '',
     'Rules:',
-    `- Subject: "<type>(<optional scope>): <description>" where type is one of ${CONVENTIONAL_TYPES.split('|').join(', ')}.`,
+    `- Subject: "<type>(<optional scope>): <description>" where type is one of ${CHANGELOG_TYPES.join(', ')}.`,
     '- Subject in the imperative mood, no trailing period, under 72 characters.',
     '- Add a body only if the change needs explanation; separate it with a blank line.',
     '- Output the raw commit message and nothing else: no markdown fences, no preamble.',
     '- Do NOT add Co-Authored-By, Signed-off-by, or any attribution or tool credit.',
+    '- Describe only lines that are added or removed in the diff. Unchanged context lines',
+    '  (including any version fields they show) are not part of this change.',
+    '- Never mention version numbers, releases, or version bumps: the release tooling',
+    '  handles versioning separately, and this commit is not the release.',
     '',
     'Files changed:',
     stat,
@@ -636,7 +769,19 @@ function draftCommitMessage() {
   const message = runAssistant(prompt)
   if (!message) return null
   const [subject] = message.split('\n')
-  return CONVENTIONAL_RE.test(subject) ? message : null
+  if (!CONVENTIONAL_RE.test(subject)) return null
+  // The prompt forbids narrating versions; this is the deterministic backstop — the same
+  // pattern as the citation check on drafted notes: validated, not trusted.
+  const changedLines = (tryRead('git', ['diff', '--cached', '--unified=0']) ?? '')
+    .split('\n')
+    .filter((line) => /^[+-](?![+-])/.test(line))
+    .join('\n')
+  const invented = inventedVersions(message, changedLines)
+  if (invented.length) {
+    note(`draft rejected: it names ${invented.join(', ')}, which the staged changes never touch`)
+    return null
+  }
+  return message
 }
 
 /**
@@ -952,7 +1097,7 @@ function rollUnreleased(text, version, date) {
 
   // 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)
+  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
@@ -965,6 +1110,10 @@ function rollUnreleased(text, version, date) {
 
 const readJson = (path) => JSON.parse(readFileSync(path, 'utf8'))
 
+/** The project's release.config.json, or {} when it has none. */
+const readUserConfig = () =>
+  existsSync('release.config.json') ? readJson('release.config.json') : {}
+
 /**
  * Where a project keeps its version. The format is inferred from the file name, so the
  * common cases need nothing but a path:
@@ -1098,6 +1247,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')
@@ -1157,6 +1307,69 @@ if (flag('--sync')) {
   process.exit(0)
 }
 
+// lint-commits checks subjects and exits; like --sync it starts no release. It is handled
+// before the positional parsing below because it takes a range, and a second positional is
+// otherwise a mistake.
+if (argv[0] === 'lint-commits') {
+  const rest = argv.slice(1)
+  const subjectAt = rest.indexOf('--subject')
+  const ignored = { ...DEFAULTS, ...readUserConfig() }.ignoreCommits.map(
+    (pattern) => new RegExp(pattern, 'i'),
+  )
+
+  let subjects
+  let scope
+  if (subjectAt !== -1) {
+    // A squash merge takes its subject from the pull request title, which is therefore the
+    // commit this repository will parse — and the one no commit-msg hook ever sees.
+    const text = rest[subjectAt + 1]
+    if (text === undefined) abort('--subject needs the text to check', 'COMMIT LINT FAILED')
+    subjects = [{ hash: '', subject: text.trim() }]
+    scope = null
+  } else {
+    if (!tryRead('git', ['rev-parse', '--show-toplevel'])) abort('not inside a git repository')
+    const lastTag = tryRead('git', ['describe', '--tags', '--abbrev=0'])
+    const range =
+      rest.find((arg) => !arg.startsWith('-')) ?? (lastTag ? `${lastTag}..HEAD` : 'HEAD')
+    // Merges carry no prose of their own, and %s is enough: nothing here reads the body.
+    const raw = tryRead('git', ['log', '--no-merges', '--format=%h%x1f%s', range])
+    if (raw === null) {
+      abort(
+        `\`git log ${range}\` failed — is that a range in this repository?`,
+        'COMMIT LINT FAILED',
+      )
+    }
+    subjects = raw
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => {
+        const [hash, subject = ''] = line.split('\u001F')
+        return { hash: hash.trim(), subject: subject.trim() }
+      })
+      // The bookkeeping `commitsSinceLastTag` drops for the same reason: a release commit,
+      // a merge or an autosquash marker is nobody's prose to fix.
+      .filter(({ subject }) => subject && !ignored.some((re) => re.test(subject)))
+    scope = range
+  }
+
+  const findings = lintSubjects(subjects)
+  for (const { hash, subject, level, reason } of findings) {
+    const label = level === 'error' ? red('error') : yellow('warn')
+    console.log(`  ${label} ${hash ? `${dim(hash)} ` : ''}${subject}\n        ${dim(reason)}`)
+  }
+  const errors = findings.filter((f) => f.level === 'error').length
+  if (errors) {
+    abort(
+      `${errors} subject${errors === 1 ? '' : 's'} the changelog and the version bump cannot read`,
+      'COMMIT LINT FAILED',
+    )
+  }
+  const counted = `${subjects.length} subject${subjects.length === 1 ? '' : 's'}`
+  const unfiled = findings.length ? `, ${findings.length} unfiled` : ''
+  ok(`${scope ? `${scope}: ` : ''}${counted} valid${unfiled}`)
+  process.exit(0)
+}
+
 /**
  * Options that consume the argument after them. Without this list a positional target is
  * found by guessing, and `--only tag,push` gets read as the version to release.
@@ -1166,23 +1379,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
@@ -1207,14 +1430,15 @@ if (existsSync(localManifest) && localManifest !== rootManifest) {
 }
 process.chdir(root)
 
-const userConfig = existsSync('release.config.json') ? readJson('release.config.json') : {}
+const userConfig = readUserConfig()
 const config = { ...DEFAULTS, ...userConfig }
 const unknownKeys = Object.keys(config).filter((key) => !(key in DEFAULTS))
 if (unknownKeys.length) abort(`release.config.json has unknown keys: ${unknownKeys.join(', ')}`)
 
 /**
  * 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
@@ -1543,6 +1767,12 @@ else if (dirty && runs('commit')) {
   const entries = dirty.split('\n')
   ok(`working tree has ${entries.length} change(s) — will be committed first`)
   console.log(dim(indent(formatStatus(dirty))))
+  if (!assistant) {
+    note(
+      'no assistant configured: the commit message will name the files — ' +
+        '`--assistant auto` drafts a real one',
+    )
+  }
   // One commit gets one subject. A change set spanning several top-level directories is
   // usually several pieces of work, and no honest Conventional Commits subject covers it.
   const areas = new Set(
@@ -1562,12 +1792,7 @@ else if (dirty && runs('commit')) {
   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}`,
@@ -1592,9 +1817,9 @@ else if (detached) {
   fail(`on '${branch}', expected '${config.branch}'`)
 } else ok(`on ${branch}`)
 
-// A shallow clone (CI checkouts default to depth 1) hides the history that release notes
-// and the last-tag lookup are derived from. It still releases correctly; the notes just
-// silently describe a fraction of the work, so say so before that happens.
+// A shallow clone (CI checkouts default to depth 1) is only a problem when it truncates
+// the history the release actually reads. Whether it does is checked after the fetch
+// below, where the answer is most accurate.
 const shallow = tryRead('git', ['rev-parse', '--is-shallow-repository']) === 'true'
 
 if (!succeeds('git', ['remote', 'get-url', config.remote])) {
@@ -1617,6 +1842,50 @@ if (!succeeds('git', ['remote', 'get-url', config.remote])) {
   }
 }
 
+// If the previous release tag is reachable from HEAD, a shallow clone hides nothing the
+// release reads — notes and `auto` see the whole span. No reachable tag means the history
+// is provably truncated: `auto` would infer the bump from a fraction of the commits, so
+// that is a failure; commit-derived notes merely come out partial, so that is a warning.
+let shallowHidesHistory = false
+if (shallow) {
+  const reachableTag = tryRead('git', ['describe', '--tags', '--abbrev=0'])
+  shallowHidesHistory = !reachableTag
+  if (reachableTag) {
+    ok(
+      `shallow clone, but history back to ${reachableTag} is visible — notes and auto are complete`,
+    )
+  } else if (autoBump) {
+    fail(
+      'shallow clone hides the history `auto` infers the bump from — no previous tag is ' +
+        'reachable.\n       Fetch full history: fetch-depth: 0 in CI, or git fetch --unshallow.',
+    )
+  } else {
+    warn(
+      'shallow clone: no previous tag is reachable, so notes drafted from commits will ' +
+        'describe only the visible history. Fetch full history (fetch-depth: 0, or ' +
+        'git fetch --unshallow).',
+    )
+  }
+}
+
+// The registry's "Repository" link comes from the manifest, not from git — a mismatch
+// ships a broken link with every publish, and npm only warns after the fact.
+if (existsSync('package.json')) {
+  const repoField = readJson('package.json').repository
+  const declared = typeof repoField === 'string' ? repoField : repoField?.url
+  const remoteUrl = tryRead('git', ['remote', 'get-url', config.remote])
+  if (declared && remoteUrl && /:\/\/|@/.test(declared)) {
+    if (normalizeRepoUrl(declared) !== normalizeRepoUrl(remoteUrl)) {
+      warn(
+        `package.json repository is ${declared}, but ${config.remote} is ${remoteUrl} — ` +
+          'the registry will link the wrong repository',
+      )
+    } else if (!/^git\+.*\.git$/.test(declared)) {
+      note(`npm normalizes repository.url on publish — \`npm pkg fix\` writes that form`)
+    }
+  }
+}
+
 // Signing is configured per repository and inherited, never managed here — git already
 // owns that. But a signing setup that cannot produce a signature fails at the commit step,
 // after the version has been written, so it is worth catching before anything mutates.
@@ -1731,7 +2000,23 @@ function reportChangelogOrder(text) {
   }
 }
 
-// Notes: the changelog section for this version, else a draft, else GitHub generates them.
+/**
+ * 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
@@ -1740,7 +2025,7 @@ let draftedNotes = null
  * True when --commit still has to create a commit. Notes drafted before that commit would
  * describe an incomplete release, so drafting waits until the working tree is committed.
  */
-const notesDeferred = !!(dirty && runs('commit') && assistant)
+const notesDeferred = !!(dirty && runs('commit'))
 
 /**
  * Notes for a version, in descending order of how much they can be trusted:
@@ -1761,8 +2046,10 @@ function draftNotesFor(v) {
         'will not appear in the notes.',
     )
   }
-  if (!assistant) return changelogFromCommits(commits, remoteLinks(config.remote))
-  if (shallow) {
+  // An explicitly named source wins over the assistant being merely available.
+  if (!assistant || notesSource === 'commits')
+    return changelogFromCommits(commits, remoteLinks(config.remote), config.hiddenTypes)
+  if (shallowHidesHistory) {
     warn(
       `shallow clone: only ${subjects.length} commit(s) are visible, so the notes will ` +
         'describe part of the release. Check out with full history (fetch-depth: 0).',
@@ -1771,42 +2058,58 @@ function draftNotesFor(v) {
   note(`drafting notes from ${subjects.length} commit(s) with ${assistantName}...`)
   return (
     draftReleaseNotes(v, commits, lastTag, remoteLinks(config.remote)) ??
-    changelogFromCommits(commits, 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`)
-    reportChangelogOrder(text)
-  } 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}]`)
-      reportChangelogOrder(text)
+    }
+  }
+
+  // Generate, either because nothing was written or because a source was named.
+  if (!notes) {
+    if (notesDeferred) {
+      ok(`release notes will be ${assistant ? 'drafted' : 'generated'} 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) {
@@ -1826,6 +2129,19 @@ if (taggedCommit && runs('tag') && (bumping || rolledChangelog)) {
   )
 }
 
+// The project's own gate, run while nothing has mutated. Without this, a prepublishOnly
+// hook is the gate — and it fails at the publish step, after the commit, tag and push.
+if (config.verify) {
+  note(`running verify: ${config.verify}`)
+  try {
+    execSync(config.verify, { stdio: 'pipe', encoding: 'utf8' })
+    ok(`verify passed: ${config.verify}`)
+  } catch (err) {
+    const tail = `${err.stdout ?? ''}${err.stderr ?? ''}`.trim().split('\n').slice(-12).join('\n')
+    fail(`verify failed: ${config.verify}\n${indent(tail)}`)
+  }
+}
+
 if (problems.length) {
   const summary = `${problems.length} preflight check(s) failed:\n  - ${problems.join('\n  - ')}`
   if (!dryRun) abort(summary)
@@ -1850,13 +2166,16 @@ if (dirty && runs('commit') && !dryRun) {
   step('Stage the working tree')
   mutate('git', ['add', '--all'])
   didStage = true
-  commitMessage = draftCommitMessage()
+  commitMessage = assistant ? draftCommitMessage() : null
   if (!commitMessage) {
-    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.',
-    )
+    // No assistant, or its draft was unusable: never block on a text generator. The
+    // deterministic floor is a chore commit that names what it touches.
+    if (assistant) {
+      note(`${assistantName} produced no usable message — falling back to a generated one`)
+    }
+    const files =
+      tryRead('git', ['diff', '--cached', '--name-only'])?.split('\n').filter(Boolean) ?? []
+    commitMessage = fallbackCommitMessage(files)
   }
   console.log(indent(commitMessage))
 }