@entro314labs/release-kit 2.7.0 → 2.8.0

package/README.md

@@ -189,26 +189,58 @@ Prerelease bumps need `--preid` unless the current version already carries one t
 | `--sync <dir>...`            | Copy this script into other projects and exit. Touches no git state.       |
 | `--help`, `-h`               | Full flag list.                                                            |
 
+### Linting commits
+
+A subject that is not Conventional Commits is invisible: it contributes nothing to the
+inferred bump and never reaches the changelog. `lint-commits` checks subjects against the
+same parser the release uses, so the gate and the release can never disagree about what
+counts.
+
+```bash
+release-kit lint-commits                      # since the last tag
+release-kit lint-commits main..HEAD           # an explicit range
+release-kit lint-commits --subject "feat: x"  # one subject — a pull request title
+```
+
+It exits non-zero on a subject the release cannot read. A type outside the changelog table
+— `security:`, `i18n:` — is a warning, not a failure: those still get printed, under _Other
+Changes_. Release commits, merges and `fixup!`/`squash!` markers are skipped, per the same
+`ignoreCommits` config the release notes use.
+
+Local commit-msg hooks cannot cover the case that matters most. If you squash-merge, the
+commit released is the **pull request title**, which no hook ever sees — check it in CI:
+
+```yaml
+- name: Lint the pull request title
+  env:
+    TITLE: ${{ github.event.pull_request.title }}
+  run: npx @entro314labs/release-kit@2.8.0 lint-commits --subject "$TITLE"
+```
+
+Pass the title through `env`, never through `${{ }}` inside `run:` — a pull request title is
+attacker-controlled text and interpolating it into a shell command is a script injection.
+
 ## 🧩 Steps
 
 A release is seven named steps. They always run in this order — `steps` selects which of
 them execute, it never reorders them.
 
-| Step        | Default | What it does                                                                                    |
-| ----------- | ------- | ----------------------------------------------------------------------------------------------- |
-| `commit`    | on\*    | Commit a dirty working tree with a drafted message ([assistant](#-assistant-optional) required) |
-| `version`   | on      | Write the version into `package.json` and `versionFiles`                                        |
-| `changelog` | on      | Roll `[Unreleased]` into the version, or add drafted notes                                      |
-| `tag`       | on      | Annotated git tag carrying the release notes                                                    |
-| `push`      | on      | Push the branch and tag together (`--follow-tags`)                                              |
-| `publish`   | on      | Run the configured `publish` command                                                            |
-| `release`   | on      | Create the GitHub release                                                                       |
-
-\* `commit` is a conditional default: it no-ops on a clean tree, and on a dirty tree it
-proceeds only when a drafting [assistant](#-assistant-optional) is configured — without
-one, preflight still refuses the unclean tree (with a hint), exactly as before. So
-`release-kit auto --assistant auto` releases a dirty tree end to end: stage, drafted
-commit, then the rest of the pipeline. Opt out with `--skip commit` or a `steps` config.
+| Step        | Default | What it does                                                                                       |
+| ----------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `commit`    | on\*    | Commit a dirty working tree — drafted with an [assistant](#-assistant-optional), generated without |
+| `version`   | on      | Write the version into `package.json` and `versionFiles`                                           |
+| `changelog` | on      | Roll `[Unreleased]` into the version, or add drafted notes                                         |
+| `tag`       | on      | Annotated git tag carrying the release notes                                                       |
+| `push`      | on      | Push the branch and tag together (`--follow-tags`)                                                 |
+| `publish`   | on      | Run the configured `publish` command                                                               |
+| `release`   | on      | Create the GitHub release                                                                          |
+
+\* `commit` no-ops on a clean tree. On a dirty tree it stages everything and commits:
+with an [assistant](#-assistant-optional) configured the message is drafted from the
+diff; without one it degrades gracefully to a generated `chore:` message naming the
+changed files — a release is never blocked because a text generator was unavailable.
+Opt out with `--skip commit` or a `steps` config, which restores the refusal on a dirty
+tree.
 
 `version` and `changelog` write files; those writes are persisted by a release commit made
 automatically when either step runs.
@@ -289,7 +321,14 @@ rather than stopping at the first problem.
 - Commit and tag signing can actually sign, and the key is one GitHub will accept
 - The publishing CLI is authenticated, and the version is not already published
 - Configured release assets exist
-- A shallow clone is reported, since it truncates the history notes come from _(warning)_
+- The configured `verify` command passes — the project's own gate (tests, build) runs
+  before anything mutates, instead of a `prepublishOnly` hook failing after the commit,
+  tag and push
+- `package.json`'s `repository` matches the git remote, so the registry's "Repository"
+  link is not broken _(warning)_
+- A shallow clone only matters when it truncates the history the release reads: with the
+  previous tag reachable it passes, without one it fails `auto` (the bump would be inferred
+  from partial history) and warns otherwise
 - A changelog section for the version exists _(warning — it falls back to generated notes)_
 
 Under `--dry-run` the failures are reported and then the remaining steps are shown anyway,
@@ -420,21 +459,22 @@ execution is not wired up yet.
 `release.config.json`, beside `package.json`. Every key is optional; unknown keys abort
 rather than being silently ignored.
 
-| Key             | Default                  | Meaning                                                      |
-| --------------- | ------------------------ | ------------------------------------------------------------ |
-| `steps`         | all but `commit`         | Which steps run; the order is fixed                          |
-| `tagPrefix`     | `"v"`                    | Prepended to the version to form the tag                     |
-| `branch`        | `"main"`                 | The only branch a release may run from; `null` allows any    |
-| `remote`        | `"origin"`               | Git remote to push to                                        |
-| `changelog`     | `"CHANGELOG.md"`         | Changelog path; `null` for a project without one             |
-| `versionFile`   | detected                 | Where the version lives; `null` versions by tag alone        |
-| `versionFiles`  | `[]`                     | Further files kept in sync; a path or `{ path, pattern }`    |
-| `publish`       | `"npm publish --tag %d"` | Publish command; `null` means none is configured             |
-| `versioning`    | `"conventional"`         | How `auto` infers; or `always-patch` / `-minor` / `-major`   |
-| `assistant`     | `null`                   | Drafting CLI: a name, `"auto"`, or `{ tool, model, effort }` |
-| `commitMessage` | `"chore(release): %t"`   | Release commit subject                                       |
-| `releaseTitle`  | `"%t"`                   | GitHub release title                                         |
-| `assets`        | `[]`                     | Files attached to the GitHub release                         |
+| Key             | Default                  | Meaning                                                               |
+| --------------- | ------------------------ | --------------------------------------------------------------------- |
+| `steps`         | all but `commit`         | Which steps run; the order is fixed                                   |
+| `tagPrefix`     | `"v"`                    | Prepended to the version to form the tag                              |
+| `branch`        | `"main"`                 | The only branch a release may run from; `null` allows any             |
+| `remote`        | `"origin"`               | Git remote to push to                                                 |
+| `changelog`     | `"CHANGELOG.md"`         | Changelog path; `null` for a project without one                      |
+| `versionFile`   | detected                 | Where the version lives; `null` versions by tag alone                 |
+| `versionFiles`  | `[]`                     | Further files kept in sync; a path or `{ path, pattern }`             |
+| `publish`       | `"npm publish --tag %d"` | Publish command; `null` means none is configured                      |
+| `versioning`    | `"conventional"`         | How `auto` infers; or `always-patch` / `-minor` / `-major`            |
+| `verify`        | `null`                   | Command run during preflight; non-zero aborts before anything mutates |
+| `assistant`     | `null`                   | Drafting CLI: a name, `"auto"`, or `{ tool, model, effort }`          |
+| `commitMessage` | `"chore(release): %t"`   | Release commit subject                                                |
+| `releaseTitle`  | `"%t"`                   | GitHub release title                                                  |
+| `assets`        | `[]`                     | Files attached to the GitHub release                                  |
 
 Command and message strings expand four tokens: `%v` version, `%t` tag, `%n` package
 name, `%d` npm dist-tag. In the `publish` command line the substituted values are
@@ -468,11 +508,11 @@ Two upstream habits make commit-derived notes trustworthy, and neither is releas
   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.
+  that title becomes the commit the notes are built from. Check it with
+  [`lint-commits`](#linting-commits), which uses this tool's own parser rather than a second
+  opinion about the grammar. 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:
 
@@ -590,12 +630,13 @@ downgrade, so a configured pipeline fails loudly; `"auto"` degrades quietly by d
 
 ### What it does
 
-- **A dirty working tree is committed instead of refusing to release.** The tree is
-  staged, a Conventional Commits message is drafted for the staged diff, and the commit is
-  made — by default, whenever an assistant is configured (`--skip commit` opts out). The subject is validated
-  against the Conventional Commits grammar; an answer that does not parse is rejected rather
-  than committed. Attribution lines (`Co-Authored-By`, `Generated with`) are stripped, so
-  the tool never signs your commits.
+- **Commit messages for a dirty working tree are drafted from the staged diff**, instead
+  of the generated `chore:` message used when no assistant is available. The draft is
+  validated, not trusted: a subject that is not Conventional Commits, or a message naming
+  a version the staged changes never touch (a model narrating an unchanged `"version"`
+  context line), falls back to the generated message rather than being 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. 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

package/package.json

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

@@ -77,6 +77,9 @@ import { createInterface } from 'node:readline/promises'
  *                            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
@@ -130,6 +133,7 @@ const DEFAULTS = {
     '^wip\\b',
     '^(fixup|squash)!',
   ],
+  verify: null,
 }
 
 /**
@@ -161,6 +165,13 @@ 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
@@ -223,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)
 }
 
@@ -624,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.
@@ -642,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,
@@ -658,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
 }
 
 /**
@@ -987,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:
@@ -1180,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.
@@ -1240,7 +1430,7 @@ 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(', ')}`)
@@ -1573,10 +1763,16 @@ 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') && assistant) {
+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(
@@ -1592,12 +1788,6 @@ else if (dirty && runs('commit') && assistant) {
         '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')
@@ -1627,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])) {
@@ -1652,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.
@@ -1791,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:
@@ -1815,7 +2049,7 @@ function draftNotesFor(v) {
   // 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) {
+  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).',
@@ -1857,7 +2091,7 @@ if (notesSource === 'github') {
   // 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')
+      ok(`release notes will be ${assistant ? 'drafted' : 'generated'} after the commit`)
     } else {
       draftedNotes = draftNotesFor(version)
       if (draftedNotes) {
@@ -1895,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)
@@ -1919,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 release with --skip 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))
 }