@oorabona/release-it-preset 0.14.0 → 1.0.0-rc.0

package/README.md

@@ -2,18 +2,49 @@
 
 Shared [release-it](https://github.com/release-it/release-it) configuration and scripts for automated versioning, changelog generation, and package publishing.
 
-[![codecov](https://codecov.io/github/oorabona/release-it-preset/graph/badge.svg?token=6RMN34Z7TX)](https://codecov.io/github/oorabona/release-it-preset)
+[![NPM Version](https://img.shields.io/npm/v/@oorabona/release-it-preset.svg)](https://npmjs.org/package/@oorabona/release-it-preset)
+[![NPM Downloads](https://img.shields.io/npm/dm/@oorabona/release-it-preset.svg)](https://npmjs.org/package/@oorabona/release-it-preset)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node](https://img.shields.io/node/v/@oorabona/release-it-preset.svg)](https://nodejs.org/)
+[![OIDC trusted publishing](https://img.shields.io/badge/npm-OIDC%20trusted%20publishing-green.svg)](https://docs.npmjs.com/trusted-publishers)
 [![CI](https://github.com/oorabona/release-it-preset/actions/workflows/ci.yml/badge.svg)](https://github.com/oorabona/release-it-preset/actions/workflows/ci.yml)
 [![Audit](https://github.com/oorabona/release-it-preset/actions/workflows/audit.yml/badge.svg)](https://github.com/oorabona/release-it-preset/actions/workflows/audit.yml)
-[![NPM Version](https://img.shields.io/npm/v/release-it-preset.svg)](https://npmjs.org/package/@oorabona/release-it-preset)
-[![NPM Downloads](https://img.shields.io/npm/dm/release-it-preset.svg)](https://npmjs.org/package/@oorabona/release-it-preset)
+[![codecov](https://codecov.io/github/oorabona/release-it-preset/graph/badge.svg?token=6RMN34Z7TX)](https://codecov.io/github/oorabona/release-it-preset)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why this preset?
+
+Most release workflows fall into one of three traps: too much manual work (plain release-it, you assemble everything), too much ceremony (changesets, great for 5+ maintainers, heavy for one), or too much automation with too little control (semantic-release, hands-off by design and format).
+
+`@oorabona/release-it-preset` occupies the productive middle ground for solo and small-team JavaScript package maintainers who want:
+
+- **Human-readable changelogs.** Keep a Changelog format (Added/Fixed/Changed/Removed/Security) generated automatically from conventional commits — no manual entry writing, no machine-format diffs.
+- **OIDC publishing without CI plumbing.** Import the reusable `publish.yml` workflow in three lines. OIDC trusted publishing with npm provenance ships on day one, no `NPM_TOKEN` secret required.
+- **Diagnostic confidence before release.** Run `release-it-preset doctor` to surface every misconfiguration — git auth, npm auth, changelog hygiene, branch requirements — before anything breaks in CI.
+- **Recovery presets for the real world.** Dedicated `republish` and `retry-publish` configs handle the scenarios other tools pretend don't happen.
+
+**Pick this preset** if you maintain one or a few npm packages, write Keep a Changelog, deploy from GitHub Actions, and want pre-built OIDC publishing without adopting changesets or semantic-release's philosophy.
+
+**Do not pick this preset** if you have a large monorepo with cross-package dependency management needs (use [changesets](https://github.com/changesets/changesets)) or if you want zero human involvement in versioning decisions (use [semantic-release](https://github.com/semantic-release/semantic-release)).
+
+## Ecosystem positioning
+
+| Tool | Strength | When to prefer it |
+|---|---|---|
+| **`@oorabona/release-it-preset`** (this) | Keep a Changelog discipline + OIDC workflows + `doctor` CLI + recovery presets | Solo / small-team JS maintainer, human-curated changelogs, GitHub Actions CI |
+| [release-it](https://github.com/release-it/release-it) (plain) | Maximum flexibility, smallest opinion footprint | You want to assemble each piece yourself |
+| [changesets](https://github.com/changesets/changesets) | PR-driven versioning, fixed/linked package versions | 5+ maintainer monorepo, every change deserves explicit intent |
+| [semantic-release](https://github.com/semantic-release/semantic-release) | Fully-automated, zero human intervention | Branch-driven release pipelines, no human review of changelogs |
+| [release-please](https://github.com/googleapis/release-please) | GitHub Release PR pattern, 20+ language strategies | Polyglot repos, GitHub-native PR-driven workflow |
+| [`@release-it-plugins/workspaces`](https://github.com/release-it-plugins/workspaces) | Multi-package iteration + cross-pkg dep sync | Monorepo with bulk publish — composes with this preset (see [Composing with `@release-it-plugins/workspaces`](#composing-with-release-it-pluginsworkspaces)) |
 
 ## Table of Contents
 
+- [Why this preset?](#why-this-preset)
+- [Ecosystem positioning](#ecosystem-positioning)
 - [Features](#features)
 - [Installation](#installation)
+  - [Install patterns](#install-patterns)
 - [Quick Start](#quick-start)
 - [Available Configurations](#available-configurations)
 - [CLI Usage](#cli-usage)
@@ -21,6 +52,7 @@ Shared [release-it](https://github.com/release-it/release-it) configuration and
   - [Preset Selection Mode](#preset-selection-mode)
   - [Passthrough Mode (Custom Config Override)](#passthrough-mode-custom-config-override)
   - [Monorepo Support](#monorepo-support)
+  - [Composing with `@release-it-plugins/workspaces`](#composing-with-release-it-pluginsworkspaces)
   - [Utility Commands](#utility-commands)
 - [Scripts](#scripts)
 - [Environment Variables](#environment-variables)
@@ -30,8 +62,11 @@ Shared [release-it](https://github.com/release-it/release-it) configuration and
 - [GitHub Actions Workflows](#github-actions-workflows)
   - [Reusable Workflows](#reusable-workflows)
   - [Workflow Reference](#workflow-reference)
+- [Exit codes](#exit-codes)
 - [Best Practices](#best-practices)
 - [Troubleshooting](#troubleshooting)
+- [Public API](#public-api)
+- [Contributing](#contributing)
 
 ## Features
 
@@ -53,6 +88,20 @@ Shared [release-it](https://github.com/release-it/release-it) configuration and
 pnpm add -D @oorabona/release-it-preset release-it
 ```
 
+### Install patterns
+
+| Use case | Command | Notes |
+|---|---|---|
+| **Try without installing** | `pnpm dlx @oorabona/release-it-preset doctor` | Fetch + run, no install. Use for evaluating the preset on an existing repo. |
+| **One-shot npx** | `npx -y @oorabona/release-it-preset doctor` | Same idea, npm-flavored |
+| **Adopt as devDep** (recommended) | `pnpm add -D @oorabona/release-it-preset release-it` | Pins via lockfile, idiomatic for projects |
+| **CI usage** | `pnpm install --frozen-lockfile && pnpm exec release-it-preset retry-publish --ci` | Lockfile-deterministic, no prompts |
+| **Diagnostic on any repo** | `pnpm dlx @oorabona/release-it-preset doctor` | Works against the cwd's git/package.json/CHANGELOG; great for quick health checks |
+
+**Global install is not recommended** — pin per-project for reproducibility. The preset is small (<20KB unpacked); CI overhead is negligible.
+
+The peer requirement is `release-it ^19.0.0 || ^20.0.0`. CI runs against the upper bound (v20.x) on every commit; v19 was smoke-tested manually before the constraint was widened. v20 is recommended for the OIDC trusted publishing handshake (npm ≥ 11.5.1, Node ≥ 24); v19 is supported for composing with [`@release-it-plugins/workspaces`](#composing-with-release-it-pluginsworkspaces) (its peer maxes at v19 today).
+
 ## Quick Start
 
 ### Option 1: Using the CLI (Recommended)
@@ -476,7 +525,37 @@ pnpm release-it-preset --config .release-it-manual.json
 - Multiple validation layers prevent abuse
 - No privilege escalation in CLI tool context
 
-See [examples/monorepo-workflow.md](examples/monorepo-workflow.md) for complete monorepo guide.
+See [examples/monorepo-workflow.md](examples/monorepo-workflow.md) for complete monorepo guide and [examples/monorepo/](examples/monorepo/) for a runnable workspace demo.
+
+### Composing with `@release-it-plugins/workspaces`
+
+This preset focuses on a single package per release-it run. If your monorepo needs **bulk publish** (iterate over every workspace package + sync cross-package dependency versions), compose this preset with [`@release-it-plugins/workspaces`](https://github.com/release-it-plugins/workspaces) — the canonical release-it plugin for that workflow.
+
+```bash
+# Install both
+pnpm add -D @oorabona/release-it-preset @release-it-plugins/workspaces release-it@^19
+```
+
+```jsonc
+// .release-it.json — extends our preset AND loads the workspaces plugin
+{
+  "extends": "@oorabona/release-it-preset/config/default",
+  "plugins": {
+    "@release-it-plugins/workspaces": true
+  }
+}
+```
+
+**Peer compatibility note:** `@release-it-plugins/workspaces` v5.0.3 declares peer `release-it ^17 || ^18 || ^19`. Our preset declares peer `^19 || ^20`. The intersection is `^19`, so when composing with the workspaces plugin you must pin release-it to v19. v20 standalone (without the workspaces plugin) is fully supported and recommended for new projects.
+
+`release-it-preset doctor` does **not** check whether the workspaces plugin is loaded — it's an opt-in composition. Run it manually after install if you want to verify the plugin's own preflight checks.
+
+When this composition is right for you:
+- You release multiple packages from one repo with **synchronized versions** (all bumped together).
+- You want **cross-package dependency sync** (when `pkg-a` bumps to 2.0, `pkg-b`'s reference auto-updates).
+
+When our preset alone is enough:
+- **Independent versioning** per package (each package releases when ready). Use `GIT_CHANGELOG_PATH=packages/<pkg>` to scope the CHANGELOG. See [examples/monorepo/](examples/monorepo/) for the runnable demo.
 
 ### Utility Commands
 
@@ -556,6 +635,45 @@ pnpm release-it-preset check
 
 Useful for debugging release issues.
 
+#### `doctor` - Release Readiness Diagnostic
+
+Runs a structured checklist across four categories and outputs a readiness score:
+
+```bash
+pnpm release-it-preset doctor
+pnpm release-it-preset doctor --json
+```
+
+**What it checks:**
+
+| Category | Checks |
+|----------|--------|
+| Environment | Known env vars, source (env / default / unset), publish-mode consistency |
+| Repository | Git repo presence, branch vs `GIT_REQUIRE_BRANCH`, latest tag, commit count, dirty WD, upstream tracking, remote URL |
+| Configuration | `CHANGELOG.md` exists + Keep a Changelog format + `[Unreleased]` content, `.release-it.json` parseable + `extends` field, `package.json` valid semver version |
+| Readiness Summary | `PASS`/`WARN`/`FAIL` counts, score `N/M checks passing`, status (`READY`/`WARNINGS`/`BLOCKED`), actionable recommendations |
+
+**Exit codes:**
+- `0` — status is `READY` or `WARNINGS`
+- `1` — status is `BLOCKED` (at least one `FAIL`)
+
+**`--json` output shape:**
+```json
+{
+  "environment": { "checks": [...], "vars": [...], "status": "PASS" },
+  "repository":  { "checks": [...], "status": "WARN" },
+  "configuration": { "checks": [...], "status": "PASS" },
+  "summary": {
+    "pass": 10, "warn": 2, "fail": 0, "total": 12,
+    "score": "10/12 checks passing",
+    "status": "WARNINGS",
+    "recommendations": ["Review 2 warning(s) before releasing"]
+  }
+}
+```
+
+Use `doctor` as a pre-release sanity check, and `check` for the full verbose configuration dump.
+
 #### `check-pr` - Pull Request Hygiene
 
 Evaluates PR readiness by analysing commits and changelog changes. Designed for CI usage but safe locally when the required environment variables are set (`PR_BASE_REF`, `PR_HEAD_REF`).
@@ -662,6 +780,30 @@ Customize behavior with environment variables:
 - `CHANGELOG_FILE` - Changelog file path (default: `CHANGELOG.md`)
 - `GIT_CHANGELOG_PATH` - Optional. When set to a repository-relative path (e.g. `packages/tar-xz`), restrict changelog generation to commits touching that path. Useful for monorepo per-package CHANGELOG files. Empty / unset = repository-wide (default).
 - `GIT_CHANGELOG_SINCE` - Optional. Override the `since` baseline for changelog generation (any git ref: SHA, tag, branch). When set, bypasses both the per-package release-commit detection and the `git describe --tags` fallback. Useful for monorepo workspaces with non-standard release commit patterns. Empty / unset = use auto-detection.
+- `CHANGELOG_TYPE_MAP` - Optional. JSON string mapping commit types to CHANGELOG section headings. Merged on top of `.changelog-types.json` (if present) and the built-in defaults. Use `false` as a value to suppress a type entirely. Example: `CHANGELOG_TYPE_MAP='{"ops":"### Operations","deps":"### Dependencies"}'`.
+
+### Custom type map (`.changelog-types.json`)
+
+Create a `.changelog-types.json` file in your project root to override or extend the built-in commit-type → section mapping at the project level. The file is merged on top of the built-in defaults; individual keys can be overridden without touching the rest.
+
+**Resolution order** (highest priority wins):
+1. `CHANGELOG_TYPE_MAP` env var (runtime override, e.g. in CI)
+2. `.changelog-types.json` project file
+3. Built-in defaults
+
+**Example `.changelog-types.json`:**
+```json
+{
+  "deps": "### Dependencies",
+  "ops": "### Operations",
+  "ci": false
+}
+```
+- String values must be a valid `### Section Heading`.
+- `false` suppresses the type (no CHANGELOG entry emitted).
+- Malformed JSON or invalid values → warning logged, layer ignored, lower-priority map used.
+
+**BREAKING CHANGE: footer parsing** (Conventional Commits 1.0.0 §6): `BREAKING CHANGE:` is recognised as a footer only when it appears after a blank-line separator from the preceding paragraph. Mid-body occurrences without the blank line do not promote the commit to breaking. Multiple `BREAKING CHANGE:` lines in the same footer paragraph each emit a separate entry under `### ⚠️ BREAKING CHANGES`.
 
 ### Git
 - `GIT_COMMIT_MESSAGE` - Commit message template (default: `release: bump v${version}`)
@@ -1470,11 +1612,30 @@ Common issues:
 
 This can appear if you interrupt a release, tweak `CHANGELOG.md`, then retry with the same version. The preset automatically passes `--allow-same-version` to `npm version`, so simply re-run `pnpm release` (or `pnpm release-it-preset default --retry`) and select the same version—`npm` will no longer abort.
 
+## Exit codes
+
+The CLI follows this convention (stable from v1.0.0 onward):
+
+| Code | Meaning | Examples |
+|---|---|---|
+| `0` | Success | Command completed; for `doctor`, `READY` or `WARNINGS` status |
+| `1` | General failure | Unhandled error, validation failure, `doctor` `BLOCKED` status |
+| `2` | Precondition failure (CI-friendly) | `validate` reports CHANGELOG missing or `[Unreleased]` empty |
+| `3..9` | **Reserved** | Not currently emitted; reserved for future contract additions |
+
+In CI scripts, distinguish `exit 1` (try-again-friendly) from `exit 2` (precondition not met — require operator action) when chaining commands.
+
+## Public API
+
+The full **stable surface** (CLI commands, environment variables, config exports, GHA workflow inputs, exit codes) is documented in [`docs/PUBLIC_API.md`](docs/PUBLIC_API.md). Items not listed there are internal and may change in any version.
+
 ## License
 
-MIT
+MIT — see [`LICENSE`](LICENSE).
 
 ## Contributing
 
-Contributions are welcome! Please open an issue or pull request.
+PRs and issues welcome. Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) before opening a pull request — it covers the Conventional Commits requirement, branch prefixes, the pre-PR checklist, and the testing conventions. By participating you agree to abide by the [Code of Conduct](CODE_OF_CONDUCT.md) (Contributor Covenant 2.1).
+
+For security concerns, please email `olivier.orabona@gmail.com` directly rather than opening a public issue. See [`SECURITY.md`](SECURITY.md) for the disclosure policy.
 

package/bin/cli.js

@@ -48,6 +48,7 @@ const UTILITY_COMMANDS = {
   update: 'populate-unreleased-changelog',
   validate: 'validate-release',
   check: 'check-config',
+  doctor: 'doctor',
   'check-pr': 'check-pr-status',
   'retry-publish-preflight': 'retry-publish',
 };
@@ -77,6 +78,7 @@ Utility Commands:
   update                 Update [Unreleased] section from commits
   validate [--allow-dirty]  Validate project is ready for release
   check                  Display configuration and project status
+  doctor                 Run diagnostic checklist and show readiness score
   check-pr               Evaluate PR hygiene (branch diff, changelog status, conventions)
   retry-publish-preflight  Run retry publish safety checks without executing release
 
@@ -222,7 +224,7 @@ function handleUtilityCommand(commandName, args) {
   const compiledPath = join(__dirname, '..', 'dist', 'scripts', `${base}.js`);
   const sourcePath = join(__dirname, '..', 'scripts', `${base}.ts`);
 
-  console.log(`🔧 Running utility command: ${commandName}\n`);
+  console.error(`🔧 Running utility command: ${commandName}\n`);
 
   // Prefer compiled script; fallback to tsx source if not built yet (developer convenience)
   import('node:fs').then(fs => {
@@ -230,7 +232,7 @@ function handleUtilityCommand(commandName, args) {
     const runner = useCompiled ? 'node' : 'tsx';
     const target = useCompiled ? compiledPath : sourcePath;
     if (!useCompiled) {
-      console.log('ℹ️  Compiled script not found, falling back to tsx source execution (dev mode).');
+      console.error('ℹ️  Compiled script not found, falling back to tsx source execution (dev mode).');
     }
 
     const child = spawn(runner, [target, ...args], {

package/dist/scripts/doctor.js

@@ -0,0 +1,530 @@
+#!/usr/bin/env tsx
+/**
+ * Doctor — diagnostic checklist + readiness score for release-it-preset
+ *
+ * Inspects four categories:
+ *   1. Environment  — all known env vars, source (env vs default)
+ *   2. Repository   — git state (branch, tag, dirty WD, upstream)
+ *   3. Configuration — CHANGELOG.md, .release-it.json, package.json
+ *   4. Summary      — READY / WARNINGS / BLOCKED + score
+ *
+ * Usage:
+ *   node dist/scripts/doctor.js
+ *   node dist/scripts/doctor.js --json
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { isValidSemver } from './lib/semver-utils.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+export function safeExec(command, deps) {
+    try {
+        return deps.execSync(command, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function worstStatus(statuses) {
+    if (statuses.includes('FAIL'))
+        return 'FAIL';
+    if (statuses.includes('WARN'))
+        return 'WARN';
+    return 'PASS';
+}
+// ---------------------------------------------------------------------------
+// ENV VAR CATALOG
+// ---------------------------------------------------------------------------
+const ENV_VAR_CATALOG = [
+    { name: 'CHANGELOG_FILE', defaultValue: 'CHANGELOG.md' },
+    { name: 'GIT_CHANGELOG_PATH' },
+    { name: 'GIT_CHANGELOG_SINCE' },
+    { name: 'GIT_COMMIT_MESSAGE', defaultValue: 'release: bump v${version}' },
+    { name: 'GIT_TAG_NAME', defaultValue: 'v${version}' },
+    { name: 'GIT_REQUIRE_BRANCH', defaultValue: 'main' },
+    { name: 'GIT_REQUIRE_UPSTREAM', defaultValue: 'false' },
+    { name: 'GIT_REQUIRE_CLEAN', defaultValue: 'false' },
+    { name: 'GIT_REMOTE', defaultValue: 'origin' },
+    { name: 'GIT_CHANGELOG_COMMAND' },
+    { name: 'GIT_CHANGELOG_DESCRIBE_COMMAND' },
+    { name: 'GITHUB_RELEASE', defaultValue: 'false' },
+    { name: 'GITHUB_REPOSITORY' },
+    { name: 'NPM_PUBLISH', defaultValue: 'false' },
+    { name: 'NPM_SKIP_CHECKS', defaultValue: 'false' },
+    { name: 'NPM_ACCESS', defaultValue: 'public' },
+    { name: 'NPM_TAG' },
+];
+// ---------------------------------------------------------------------------
+// 1. Environment
+// ---------------------------------------------------------------------------
+export function collectEnvironment(deps) {
+    const vars = ENV_VAR_CATALOG.map(({ name, defaultValue }) => {
+        const value = deps.getEnv(name);
+        if (value !== undefined) {
+            return { name, value, source: 'env' };
+        }
+        if (defaultValue !== undefined) {
+            return { name, value: defaultValue, source: 'default', defaultValue };
+        }
+        return { name, value: undefined, source: 'unset', defaultValue };
+    });
+    const checks = [];
+    const githubRelease = deps.getEnv('GITHUB_RELEASE');
+    const githubRepo = deps.getEnv('GITHUB_REPOSITORY');
+    const npmPublish = deps.getEnv('NPM_PUBLISH');
+    if (githubRelease === 'true' && !githubRepo) {
+        checks.push({
+            name: 'GITHUB_REPOSITORY set when GITHUB_RELEASE=true',
+            status: 'WARN',
+            value: '<unset>',
+            detail: 'Set GITHUB_REPOSITORY=owner/repo to enable GitHub releases',
+        });
+    }
+    else {
+        checks.push({
+            name: 'GitHub release configuration',
+            status: 'PASS',
+            value: githubRelease === 'true' ? 'enabled' : 'disabled (default)',
+        });
+    }
+    if (npmPublish === 'true') {
+        checks.push({
+            name: 'npm publish configuration',
+            status: 'PASS',
+            value: 'enabled (NPM_PUBLISH=true)',
+        });
+    }
+    else {
+        checks.push({
+            name: 'npm publish configuration',
+            status: 'PASS',
+            value: 'disabled (default — safe for local runs)',
+        });
+    }
+    return {
+        vars,
+        checks,
+        status: worstStatus(checks.map((c) => c.status)),
+    };
+}
+// ---------------------------------------------------------------------------
+// 2. Repository
+// ---------------------------------------------------------------------------
+export function inspectRepository(deps) {
+    const checks = [];
+    const isGitRepo = safeExec('git rev-parse --git-dir', deps) !== null;
+    if (!isGitRepo) {
+        checks.push({
+            name: 'Git repository',
+            status: 'FAIL',
+            value: 'not a git repository',
+            detail: 'Run doctor from inside a git repository',
+        });
+        return { checks, status: 'FAIL' };
+    }
+    checks.push({ name: 'Git repository', status: 'PASS', value: 'yes' });
+    const branch = safeExec('git rev-parse --abbrev-ref HEAD', deps);
+    const requiredBranch = deps.getEnv('GIT_REQUIRE_BRANCH') ?? 'main';
+    if (!branch) {
+        checks.push({
+            name: 'Current branch',
+            status: 'WARN',
+            value: 'unknown',
+            detail: 'Could not determine current branch',
+        });
+    }
+    else if (requiredBranch && branch !== requiredBranch) {
+        checks.push({
+            name: 'Current branch',
+            status: 'WARN',
+            value: branch,
+            detail: `GIT_REQUIRE_BRANCH is "${requiredBranch}" — release will fail on this branch`,
+        });
+    }
+    else {
+        checks.push({ name: 'Current branch', status: 'PASS', value: branch });
+    }
+    const latestTag = safeExec('git describe --tags --abbrev=0', deps);
+    if (!latestTag) {
+        checks.push({
+            name: 'Latest tag',
+            status: 'WARN',
+            value: 'none',
+            detail: 'No tags found — first release scenario',
+        });
+    }
+    else {
+        checks.push({ name: 'Latest tag', status: 'PASS', value: latestTag });
+    }
+    let commitCount = 0;
+    if (latestTag) {
+        const countStr = safeExec(`git rev-list "${latestTag}"..HEAD --count`, deps);
+        commitCount = countStr ? parseInt(countStr, 10) : 0;
+    }
+    else {
+        const countStr = safeExec('git rev-list HEAD --count', deps);
+        commitCount = countStr ? parseInt(countStr, 10) : 0;
+    }
+    checks.push({
+        name: 'Commits since last tag',
+        status: 'PASS',
+        value: String(commitCount),
+    });
+    const dirtyOutput = safeExec('git status --porcelain', deps);
+    const isDirty = dirtyOutput !== null && dirtyOutput.length > 0;
+    if (isDirty) {
+        checks.push({
+            name: 'Working directory clean',
+            status: 'WARN',
+            value: 'dirty',
+            detail: 'Uncommitted changes present — release may fail if GIT_REQUIRE_CLEAN=true',
+        });
+    }
+    else {
+        checks.push({ name: 'Working directory clean', status: 'PASS', value: 'yes' });
+    }
+    const upstream = safeExec('git rev-parse --abbrev-ref @{u}', deps);
+    if (!upstream) {
+        checks.push({
+            name: 'Upstream tracking branch',
+            status: 'WARN',
+            value: 'none',
+            detail: 'No upstream set — git push will fail. Run: git push -u origin <branch>',
+        });
+    }
+    else {
+        checks.push({ name: 'Upstream tracking branch', status: 'PASS', value: upstream });
+    }
+    const remote = deps.getEnv('GIT_REMOTE') ?? 'origin';
+    const remoteUrl = safeExec(`git config --get remote.${remote}.url`, deps);
+    if (!remoteUrl) {
+        checks.push({
+            name: `Git remote (${remote})`,
+            status: 'WARN',
+            value: 'not configured',
+            detail: `Remote "${remote}" not found. Set GIT_REMOTE or run: git remote add origin <url>`,
+        });
+    }
+    else {
+        checks.push({ name: `Git remote (${remote})`, status: 'PASS', value: remoteUrl });
+    }
+    return { checks, status: worstStatus(checks.map((c) => c.status)) };
+}
+// ---------------------------------------------------------------------------
+// 3. Configuration
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Workspace integration helper (used by validateConfiguration)
+// ---------------------------------------------------------------------------
+function detectWorkspaceIntegration(deps) {
+    const hasPnpmWorkspace = deps.existsSync('pnpm-workspace.yaml');
+    let hasWorkspacesField = false;
+    if (!hasPnpmWorkspace && deps.existsSync('package.json')) {
+        try {
+            const raw = deps.readFileSync('package.json', 'utf8');
+            const pkg = JSON.parse(raw);
+            const ws = pkg.workspaces;
+            hasWorkspacesField =
+                Array.isArray(ws) ||
+                    (typeof ws === 'object' && ws !== null && Array.isArray(ws.packages));
+        }
+        catch {
+            // package.json parse errors are reported by the version check — skip here
+        }
+    }
+    const workspaceSetup = hasPnpmWorkspace || hasWorkspacesField;
+    if (!workspaceSetup) {
+        return { name: 'Workspace integration', status: 'PASS', value: 'not a monorepo' };
+    }
+    const pluginInstalled = deps.existsSync('node_modules/@release-it-plugins/workspaces/package.json');
+    if (pluginInstalled) {
+        return { name: 'Workspace integration', status: 'PASS', value: 'plugin installed' };
+    }
+    const source = hasPnpmWorkspace ? 'pnpm-workspace.yaml present' : 'package.json workspaces field';
+    return {
+        name: 'Workspace integration',
+        status: 'WARN',
+        value: `Workspace setup detected (no plugin loaded): ${source}`,
+        detail: [
+            'For multi-package publish + cross-pkg dep sync, run:',
+            '  pnpm add -D @release-it-plugins/workspaces',
+            'Then add `"plugins": {"@release-it-plugins/workspaces": true}` to .release-it.json.',
+            'Skip if you only need per-package CHANGELOG (use GIT_CHANGELOG_PATH).',
+        ].join('\n'),
+    };
+}
+export function validateConfiguration(deps) {
+    const checks = [];
+    const changelogPath = deps.getEnv('CHANGELOG_FILE') ?? 'CHANGELOG.md';
+    if (!deps.existsSync(changelogPath)) {
+        checks.push({
+            name: `${changelogPath} exists`,
+            status: 'FAIL',
+            value: 'missing',
+            detail: `Run: release-it-preset init  OR create ${changelogPath} manually`,
+        });
+    }
+    else {
+        checks.push({ name: `${changelogPath} exists`, status: 'PASS', value: 'yes' });
+        const content = deps.readFileSync(changelogPath, 'utf8');
+        const hasKacHeader = /^# Changelog/m.test(content);
+        if (!hasKacHeader) {
+            checks.push({
+                name: 'Keep a Changelog format',
+                status: 'FAIL',
+                value: 'invalid',
+                detail: 'CHANGELOG.md must start with "# Changelog" (Keep a Changelog format)',
+            });
+        }
+        else {
+            checks.push({ name: 'Keep a Changelog format', status: 'PASS', value: 'valid' });
+        }
+        const unreleasedMatch = content.match(/## \[Unreleased\]([\s\S]*?)(?=## \[|$)/);
+        if (!unreleasedMatch) {
+            checks.push({
+                name: '[Unreleased] section',
+                status: 'FAIL',
+                value: 'missing',
+                detail: 'Add "## [Unreleased]" section — run: release-it-preset update',
+            });
+        }
+        else {
+            const unreleasedContent = unreleasedMatch[1].trim();
+            const hasChanges = /^-/m.test(unreleasedContent);
+            if (!unreleasedContent || !hasChanges) {
+                checks.push({
+                    name: '[Unreleased] section',
+                    status: 'WARN',
+                    value: 'empty',
+                    detail: 'No entries yet — run: release-it-preset update',
+                });
+            }
+            else {
+                checks.push({ name: '[Unreleased] section', status: 'PASS', value: 'has content' });
+            }
+        }
+    }
+    const hasReleaseItJson = deps.existsSync('.release-it.json');
+    if (!hasReleaseItJson) {
+        checks.push({
+            name: '.release-it.json exists',
+            status: 'WARN',
+            value: 'missing',
+            detail: 'Optional but recommended. Run: release-it-preset init',
+        });
+    }
+    else {
+        checks.push({ name: '.release-it.json exists', status: 'PASS', value: 'yes' });
+        try {
+            const raw = deps.readFileSync('.release-it.json', 'utf8');
+            const config = JSON.parse(raw);
+            const extendsField = config.extends;
+            if (!extendsField) {
+                checks.push({
+                    name: '.release-it.json extends preset',
+                    status: 'WARN',
+                    value: 'no extends field',
+                    detail: 'Add "extends": "@oorabona/release-it-preset/config/<name>" for CLI auto-detection',
+                });
+            }
+            else if (!/@oorabona\/release-it-preset\/config\/[\w-]+/.test(extendsField)) {
+                checks.push({
+                    name: '.release-it.json extends preset',
+                    status: 'WARN',
+                    value: extendsField,
+                    detail: 'extends does not point to @oorabona/release-it-preset/config/<name>',
+                });
+            }
+            else {
+                checks.push({
+                    name: '.release-it.json extends preset',
+                    status: 'PASS',
+                    value: extendsField,
+                });
+            }
+        }
+        catch {
+            checks.push({
+                name: '.release-it.json parseable',
+                status: 'FAIL',
+                value: 'parse error',
+                detail: '.release-it.json contains invalid JSON',
+            });
+        }
+    }
+    if (!deps.existsSync('package.json')) {
+        checks.push({
+            name: 'package.json exists',
+            status: 'FAIL',
+            value: 'missing',
+            detail: 'package.json is required for release-it',
+        });
+    }
+    else {
+        try {
+            const raw = deps.readFileSync('package.json', 'utf8');
+            const pkg = JSON.parse(raw);
+            const version = pkg.version;
+            if (!version) {
+                checks.push({
+                    name: 'package.json version',
+                    status: 'FAIL',
+                    value: 'missing',
+                    detail: 'Add "version" field to package.json',
+                });
+            }
+            else if (!isValidSemver(version)) {
+                checks.push({
+                    name: 'package.json version',
+                    status: 'FAIL',
+                    value: version,
+                    detail: `"${version}" is not a valid semver string`,
+                });
+            }
+            else {
+                checks.push({ name: 'package.json version', status: 'PASS', value: version });
+            }
+        }
+        catch {
+            checks.push({
+                name: 'package.json parseable',
+                status: 'FAIL',
+                value: 'parse error',
+                detail: 'package.json contains invalid JSON',
+            });
+        }
+    }
+    checks.push(detectWorkspaceIntegration(deps));
+    return { checks, status: worstStatus(checks.map((c) => c.status)) };
+}
+// ---------------------------------------------------------------------------
+// 4. Summary
+// ---------------------------------------------------------------------------
+export function summarize(report) {
+    const allChecks = [
+        ...report.environment.checks,
+        ...report.repository.checks,
+        ...report.configuration.checks,
+    ];
+    const pass = allChecks.filter((c) => c.status === 'PASS').length;
+    const warn = allChecks.filter((c) => c.status === 'WARN').length;
+    const fail = allChecks.filter((c) => c.status === 'FAIL').length;
+    const total = allChecks.length;
+    const score = `${pass}/${total} checks passing`;
+    let status;
+    if (fail > 0) {
+        status = 'BLOCKED';
+    }
+    else if (warn > 0) {
+        status = 'WARNINGS';
+    }
+    else {
+        status = 'READY';
+    }
+    const recommendations = [];
+    if (fail > 0) {
+        const failedNames = allChecks.filter((c) => c.status === 'FAIL').map((c) => c.name);
+        const preview = failedNames.slice(0, 2).join(', ') + (failedNames.length > 2 ? '...' : '');
+        recommendations.push(`Fix ${fail} blocking issue(s): ${preview}`);
+    }
+    if (warn > 0) {
+        recommendations.push(`Review ${warn} warning(s) before releasing`);
+    }
+    if (status === 'READY') {
+        recommendations.push('All checks pass — run: release-it-preset validate && release-it-preset default');
+    }
+    return { pass, warn, fail, total, score, status, recommendations };
+}
+// ---------------------------------------------------------------------------
+// Main exported function (DI)
+// ---------------------------------------------------------------------------
+export function runDoctor(deps) {
+    const environment = collectEnvironment(deps);
+    const repository = inspectRepository(deps);
+    const configuration = validateConfiguration(deps);
+    const summary = summarize({ environment, repository, configuration });
+    return { environment, repository, configuration, summary };
+}
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+const ICONS = {
+    PASS: '[PASS]',
+    WARN: '[WARN]',
+    FAIL: '[FAIL]',
+};
+const STATUS_LABELS = {
+    READY: 'READY',
+    WARNINGS: 'WARNINGS',
+    BLOCKED: 'BLOCKED',
+};
+export function formatHuman(report) {
+    const lines = [];
+    function sectionHeader(title) {
+        lines.push('');
+        lines.push(title);
+        lines.push('-'.repeat(60));
+    }
+    function renderChecks(checks) {
+        for (const check of checks) {
+            const icon = ICONS[check.status];
+            lines.push(`  ${icon} ${check.name}: ${check.value}`);
+            if (check.detail) {
+                lines.push(`       ${check.detail}`);
+            }
+        }
+    }
+    lines.push('');
+    lines.push('release-it-preset doctor');
+    lines.push('='.repeat(60));
+    sectionHeader('1. Environment');
+    renderChecks(report.environment.checks);
+    lines.push('');
+    lines.push(`  Environment variables (${report.environment.vars.length} total):`);
+    for (const v of report.environment.vars) {
+        const srcLabel = v.source === 'env' ? '(env)' : v.source === 'default' ? '(default)' : '(unset)';
+        const displayVal = v.source === 'unset' ? '<not set>' : (v.value ?? '<not set>');
+        lines.push(`    ${v.name.padEnd(35)} ${displayVal.padEnd(30)} ${srcLabel}`);
+    }
+    sectionHeader('2. Repository');
+    renderChecks(report.repository.checks);
+    sectionHeader('3. Configuration');
+    renderChecks(report.configuration.checks);
+    sectionHeader('4. Readiness Summary');
+    const { summary } = report;
+    lines.push(`  Status : ${STATUS_LABELS[summary.status]}`);
+    lines.push(`  Score  : ${summary.score}  (PASS: ${summary.pass}, WARN: ${summary.warn}, FAIL: ${summary.fail})`);
+    if (summary.recommendations.length > 0) {
+        lines.push('');
+        lines.push('  Recommendations:');
+        for (const rec of summary.recommendations) {
+            lines.push(`    * ${rec}`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+export function formatJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+// ---------------------------------------------------------------------------
+// CLI entry (guarded)
+// ---------------------------------------------------------------------------
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const isJson = process.argv.includes('--json');
+    const deps = {
+        execSync,
+        existsSync,
+        readFileSync,
+        getEnv: (key) => process.env[key],
+    };
+    const report = runDoctor(deps);
+    if (isJson) {
+        process.stdout.write(formatJson(report) + '\n');
+    }
+    else {
+        process.stdout.write(formatHuman(report));
+    }
+    process.exit(report.summary.status === 'BLOCKED' ? 1 : 0);
+}

package/dist/scripts/lib/changelog-types.js

@@ -0,0 +1,107 @@
+/**
+ * Configurable commit-type → CHANGELOG section mapping.
+ *
+ * Resolution order (highest priority wins):
+ *   1. CHANGELOG_TYPE_MAP env var  (JSON string)
+ *   2. .changelog-types.json file  (project root)
+ *   3. Built-in defaults below
+ *
+ * A value of `false` means "skip this type entirely" (no changelog entry).
+ */
+/**
+ * Built-in commit-type → CHANGELOG section map.
+ * Values are `### SectionName` strings or `false` to suppress.
+ */
+export const BUILTIN_TYPE_MAP = {
+    feat: '### Added',
+    feature: '### Added',
+    add: '### Added',
+    fix: '### Fixed',
+    bugfix: '### Fixed',
+    security: '### Security',
+    perf: '### Changed',
+    refactor: '### Changed',
+    style: '### Changed',
+    docs: '### Changed',
+    test: '### Changed',
+    chore: '### Changed',
+    build: '### Changed',
+    deps: '### Changed',
+    dependency: '### Changed',
+    dependencies: '### Changed',
+    revert: '### Changed',
+    remove: '### Removed',
+    removed: '### Removed',
+    delete: '### Removed',
+    deleted: '### Removed',
+    ci: false,
+    release: false,
+    hotfix: false,
+    misc: '### Changed',
+};
+const CHANGELOG_TYPES_FILE = '.changelog-types.json';
+/**
+ * Validate that every value in the map is either a string or false.
+ * Throws on the first invalid entry.
+ */
+function validateMapStructure(map) {
+    if (typeof map !== 'object' || map === null || Array.isArray(map)) {
+        throw new TypeError('Type map must be a plain object');
+    }
+    for (const [key, value] of Object.entries(map)) {
+        if (typeof value !== 'string' && value !== false) {
+            throw new TypeError(`Invalid value for key "${key}": expected string or false, got ${typeof value}`);
+        }
+    }
+}
+/**
+ * Load the commit-type → CHANGELOG section mapping.
+ *
+ * Priority:
+ *  1. CHANGELOG_TYPE_MAP env var (JSON, merged on top of file + built-in)
+ *  2. .changelog-types.json project file (merged on top of built-in)
+ *  3. BUILTIN_TYPE_MAP (base)
+ *
+ * Malformed JSON or invalid structure → WARN + ignore that layer (fall back to lower priority).
+ */
+export function loadChangelogTypeMap(deps) {
+    let resolved = { ...BUILTIN_TYPE_MAP };
+    // Layer 1: project-level file override
+    let fileContent;
+    try {
+        fileContent = deps.readFileSync(CHANGELOG_TYPES_FILE, 'utf8');
+    }
+    catch (err) {
+        // ENOENT (file does not exist) is the expected case — silently skip.
+        // Other I/O errors (EACCES permission denied, EISDIR is a directory, etc.)
+        // are real problems and surfaced as a WARN so the user can investigate.
+        const e = err;
+        if (e?.code !== 'ENOENT') {
+            deps.warn(`Cannot read ${CHANGELOG_TYPES_FILE}: ${e?.message ?? String(err)}. Skipping file override.`);
+        }
+        fileContent = undefined;
+    }
+    if (fileContent !== undefined) {
+        try {
+            const parsed = JSON.parse(fileContent);
+            validateMapStructure(parsed);
+            resolved = { ...resolved, ...parsed };
+        }
+        catch (err) {
+            deps.warn(`Invalid ${CHANGELOG_TYPES_FILE}: ${err.message}. Using built-in type map.`);
+        }
+    }
+    // Layer 2: env var override (highest priority)
+    const envValue = deps.getEnv('CHANGELOG_TYPE_MAP');
+    if (envValue) {
+        try {
+            const parsed = JSON.parse(envValue);
+            validateMapStructure(parsed);
+            resolved = { ...resolved, ...parsed };
+        }
+        catch (err) {
+            deps.warn(`Invalid CHANGELOG_TYPE_MAP env var: ${err.message}. Using file/built-in type map.`);
+        }
+    }
+    return resolved;
+}

package/dist/scripts/populate-unreleased-changelog.js

@@ -23,6 +23,7 @@ import { getGitHubRepoUrl } from './lib/git-utils.js';
 import { CONVENTIONAL_COMMIT_REGEX } from './lib/commit-parser.js';
 import { runScript } from './lib/run-script.js';
 import { ValidationError } from './lib/errors.js';
+import { BUILTIN_TYPE_MAP, loadChangelogTypeMap } from './lib/changelog-types.js';
 /**
  * Extract all conventional commit patterns from a commit body
  */
@@ -46,43 +47,19 @@ export function extractConventionalCommitParts(commitBody, sha) {
     return parts;
 }
 /**
- * Normalize commit types to standard changelog categories
+ * Normalize a commit type to a CHANGELOG section heading.
+ * Uses `typeMap` (defaults to BUILTIN_TYPE_MAP) so callers can inject
+ * a custom or project-level override without touching this function.
+ * Returns false when the type should be suppressed entirely.
  */
-export function normalizeCommitType(type) {
-    const typeMap = {
-        feat: '### Added',
-        feature: '### Added',
-        add: '### Added',
-        fix: '### Fixed',
-        bugfix: '### Fixed',
-        security: '### Security',
-        perf: '### Changed',
-        refactor: '### Changed',
-        style: '### Changed',
-        docs: '### Changed',
-        test: '### Changed',
-        chore: '### Changed',
-        build: '### Changed',
-        deps: '### Changed',
-        dependency: '### Changed',
-        dependencies: '### Changed',
-        revert: '### Changed',
-        remove: '### Removed',
-        removed: '### Removed',
-        delete: '### Removed',
-        deleted: '### Removed',
-        ci: false,
-        release: false,
-        hotfix: false,
-        misc: '### Changed',
-    };
+export function normalizeCommitType(type, typeMap = BUILTIN_TYPE_MAP) {
     const result = typeMap[type.toLowerCase()];
     return result !== undefined ? result : '### Changed';
 }
 /**
  * Parse git log output and extract all conventional commit parts
  */
-export function parseCommitsWithMultiplePrefixes(gitOutput, repoUrl) {
+export function parseCommitsWithMultiplePrefixes(gitOutput, repoUrl, typeMap = BUILTIN_TYPE_MAP) {
     if (!gitOutput)
         return '';
     const commitEntries = gitOutput.split('|||END|||').filter((entry) => entry.trim());
@@ -98,8 +75,9 @@ export function parseCommitsWithMultiplePrefixes(gitOutput, repoUrl) {
             // Compute the header block: first contiguous run of non-empty lines.
             // This prevents paragraph-separated footer tokens like "Refs: #42" or
             // "Co-authored-by: ..." from matching the conventional-commit regex
-            // via the 'gm' flag in extractConventionalCommitParts. AC#5 (consecutive
-            // multi-prefix lines) is preserved because those lines share no blank line.
+            // via the 'gm' flag in extractConventionalCommitParts. Consecutive
+            // multi-prefix lines (e.g. "feat: x\nfix: y") are preserved because
+            // they share no blank line — see #23 for the original use case.
             const headerBlock = body.split('\n').reduce((acc, line) => {
                 if (!acc.done) {
                     if (line.trim() === '') {
@@ -112,19 +90,35 @@ export function parseCommitsWithMultiplePrefixes(gitOutput, repoUrl) {
                 return acc;
             }, { lines: [], done: false }).lines.join('\n');
             const parts = extractConventionalCommitParts(headerBlock, shortSha);
-            // Detect "BREAKING CHANGE:" trailer in the full body (not just header).
-            // This handles the footer-style breaking annotation per Conventional Commits spec.
-            const breakingFooterMatch = /^BREAKING[- ]CHANGE:\s*(.+)/m.exec(body);
-            if (breakingFooterMatch) {
+            // Detect "BREAKING CHANGE:" trailers only in the LAST paragraph of the body,
+            // AND only when the body has more than one paragraph (i.e., there is at least one
+            // blank-line separator). Per Conventional Commits 1.0.0 §6, a footer requires a
+            // blank line separating it from the preceding content. A "BREAKING CHANGE:" that
+            // appears on a line immediately after the subject line (no blank line) is mid-body
+            // prose, NOT a footer, and must NOT promote the commit to breaking.
+            //
+            // matchAll() is used so multiple BREAKING CHANGE: lines in the same last
+            // paragraph each emit a separate breaking entry.
+            // CRLF safety: accept both LF and CRLF line endings so commits authored on
+            // Windows produce the same output (a paragraph separator can be \n\n or \r\n\r\n).
+            const paragraphs = body.split(/\r?\n[ \t]*\r?\n/);
+            const hasFooterSection = paragraphs.length > 1;
+            const breakingFooterMatches = hasFooterSection
+                ? [...(paragraphs[paragraphs.length - 1] ?? '').matchAll(/^BREAKING[- ]CHANGE:\s*(.+)$/gm)]
+                : [];
+            if (breakingFooterMatches.length > 0) {
                 if (parts.length > 0) {
-                    // Promote the first emitted part to breaking.
+                    // Promote the first conventional-commit part to breaking so it appears in
+                    // the BREAKING CHANGES section with the commit's own description.
                     parts[0] = { ...parts[0], breaking: true };
                 }
-                else {
-                    // No leading conventional prefix found; emit a standalone breaking entry.
+                // Each BREAKING CHANGE: footer line emits its own breaking entry with the
+                // footer's description (distinct from the commit subject).
+                // Multiple footer lines → multiple entries.
+                for (const m of breakingFooterMatches) {
                     parts.push({
                         type: 'misc',
-                        description: breakingFooterMatch[1].trim(),
+                        description: m[1].trim(),
                         sha: shortSha,
                         breaking: true,
                     });
@@ -161,11 +155,16 @@ export function parseCommitsWithMultiplePrefixes(gitOutput, repoUrl) {
     const groupedParts = {};
     const breakingChanges = [];
     for (const part of allParts) {
-        // Collect breaking changes separately
+        // Breaking parts go ONLY into the BREAKING CHANGES section.
+        // They are NOT also added to their native section (e.g. ### Added), which
+        // would produce duplicate entries. The breaking indicator in the native
+        // section was confusing — the dedicated ### ⚠️ BREAKING CHANGES section
+        // already provides full visibility.
         if (part.breaking) {
             breakingChanges.push(part);
+            continue;
         }
-        const sectionName = normalizeCommitType(part.type);
+        const sectionName = normalizeCommitType(part.type, typeMap);
         if (sectionName === false) {
             continue;
         }
@@ -174,8 +173,19 @@ export function parseCommitsWithMultiplePrefixes(gitOutput, repoUrl) {
         }
         groupedParts[sectionName].push(part);
     }
+    // Build the final ordered section list.
+    // Custom sections (from typeMap overrides) are appended after the standard order.
     const sections = [];
-    const sectionOrder = ['### Added', '### Fixed', '### Changed', '### Removed', '### Security'];
+    const standardSectionOrder = [
+        '### Added',
+        '### Fixed',
+        '### Changed',
+        '### Removed',
+        '### Security',
+    ];
+    // Collect any custom section names not in the standard order
+    const customSections = Object.keys(groupedParts).filter((s) => !standardSectionOrder.includes(s));
+    const sectionOrder = [...standardSectionOrder, ...customSections];
     // Add BREAKING CHANGES section first if there are any
     if (breakingChanges.length > 0) {
         sections.push('### ⚠️ BREAKING CHANGES');
@@ -191,9 +201,8 @@ export function parseCommitsWithMultiplePrefixes(gitOutput, repoUrl) {
             sections.push(sectionTitle);
             sections.push(...groupedParts[sectionTitle].map((part) => {
                 const scopePart = part.scope ? ` (${part.scope})` : '';
-                const breakingIndicator = part.breaking ? ' ⚠️ BREAKING' : '';
                 const linkPart = repoUrl ? ` ([${part.sha}](${repoUrl}/commit/${part.sha}))` : ` (${part.sha})`;
-                return `- ${part.description}${scopePart}${breakingIndicator}${linkPart}`;
+                return `- ${part.description}${scopePart}${linkPart}`;
             }));
             sections.push('');
         }
@@ -289,7 +298,12 @@ export function populateChangelog(deps) {
         getEnv: deps.getEnv,
         warn: deps.warn,
     });
-    const commits = parseCommitsWithMultiplePrefixes(gitOutput, repoUrl);
+    const typeMap = loadChangelogTypeMap({
+        readFileSync: deps.readFileSync,
+        getEnv: deps.getEnv,
+        warn: deps.warn,
+    });
+    const commits = parseCommitsWithMultiplePrefixes(gitOutput, repoUrl, typeMap);
     const changelog = deps.readFileSync(changelogPath, 'utf8');
     const unreleasedContent = commits && commits.trim() ? commits : 'No changes yet.';
     const unreleasedRegex = /## \[Unreleased\][\s\S]*?(?=## \[|$)/;

package/dist/types/doctor.d.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env tsx
+/**
+ * Doctor — diagnostic checklist + readiness score for release-it-preset
+ *
+ * Inspects four categories:
+ *   1. Environment  — all known env vars, source (env vs default)
+ *   2. Repository   — git state (branch, tag, dirty WD, upstream)
+ *   3. Configuration — CHANGELOG.md, .release-it.json, package.json
+ *   4. Summary      — READY / WARNINGS / BLOCKED + score
+ *
+ * Usage:
+ *   node dist/scripts/doctor.js
+ *   node dist/scripts/doctor.js --json
+ */
+import type { ExecSyncOptions } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+export type CheckStatus = 'PASS' | 'WARN' | 'FAIL';
+export interface CheckResult {
+    name: string;
+    status: CheckStatus;
+    value: string;
+    detail?: string;
+}
+export interface EnvVarInfo {
+    name: string;
+    value: string | undefined;
+    source: 'env' | 'default' | 'unset';
+    defaultValue?: string;
+}
+export interface EnvironmentSection {
+    checks: CheckResult[];
+    vars: EnvVarInfo[];
+    status: CheckStatus;
+}
+export interface RepositorySection {
+    checks: CheckResult[];
+    status: CheckStatus;
+}
+export interface ConfigurationSection {
+    checks: CheckResult[];
+    status: CheckStatus;
+}
+export interface DoctorSummary {
+    pass: number;
+    warn: number;
+    fail: number;
+    total: number;
+    score: string;
+    status: 'READY' | 'WARNINGS' | 'BLOCKED';
+    recommendations: string[];
+}
+export interface DoctorReport {
+    environment: EnvironmentSection;
+    repository: RepositorySection;
+    configuration: ConfigurationSection;
+    summary: DoctorSummary;
+}
+export interface DoctorDeps {
+    execSync: (command: string, options?: ExecSyncOptions) => Buffer | string;
+    existsSync: typeof existsSync;
+    readFileSync: typeof readFileSync;
+    getEnv: (key: string) => string | undefined;
+}
+export declare function safeExec(command: string, deps: DoctorDeps): string | null;
+export declare function collectEnvironment(deps: DoctorDeps): EnvironmentSection;
+export declare function inspectRepository(deps: DoctorDeps): RepositorySection;
+export declare function validateConfiguration(deps: DoctorDeps): ConfigurationSection;
+export declare function summarize(report: Omit<DoctorReport, 'summary'>): DoctorSummary;
+export declare function runDoctor(deps: DoctorDeps): DoctorReport;
+export declare function formatHuman(report: DoctorReport): string;
+export declare function formatJson(report: DoctorReport): string;

package/dist/types/lib/changelog-types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Configurable commit-type → CHANGELOG section mapping.
+ *
+ * Resolution order (highest priority wins):
+ *   1. CHANGELOG_TYPE_MAP env var  (JSON string)
+ *   2. .changelog-types.json file  (project root)
+ *   3. Built-in defaults below
+ *
+ * A value of `false` means "skip this type entirely" (no changelog entry).
+ */
+import type { readFileSync as ReadFileSyncFn } from 'node:fs';
+/**
+ * Dependencies for loadChangelogTypeMap — follows the project DI pattern.
+ */
+export interface ChangelogTypeDeps {
+    readFileSync: typeof ReadFileSyncFn;
+    getEnv: (key: string) => string | undefined;
+    warn: (message: string) => void;
+}
+/**
+ * Built-in commit-type → CHANGELOG section map.
+ * Values are `### SectionName` strings or `false` to suppress.
+ */
+export declare const BUILTIN_TYPE_MAP: Record<string, string | false>;
+/**
+ * Load the commit-type → CHANGELOG section mapping.
+ *
+ * Priority:
+ *  1. CHANGELOG_TYPE_MAP env var (JSON, merged on top of file + built-in)
+ *  2. .changelog-types.json project file (merged on top of built-in)
+ *  3. BUILTIN_TYPE_MAP (base)
+ *
+ * Malformed JSON or invalid structure → WARN + ignore that layer (fall back to lower priority).
+ */
+export declare function loadChangelogTypeMap(deps: ChangelogTypeDeps): Record<string, string | false>;

package/dist/types/populate-unreleased-changelog.d.ts

@@ -43,13 +43,16 @@ export interface CommitPart {
  */
 export declare function extractConventionalCommitParts(commitBody: string, sha: string): CommitPart[];
 /**
- * Normalize commit types to standard changelog categories
+ * Normalize a commit type to a CHANGELOG section heading.
+ * Uses `typeMap` (defaults to BUILTIN_TYPE_MAP) so callers can inject
+ * a custom or project-level override without touching this function.
+ * Returns false when the type should be suppressed entirely.
  */
-export declare function normalizeCommitType(type: string): string | false;
+export declare function normalizeCommitType(type: string, typeMap?: Record<string, string | false>): string | false;
 /**
  * Parse git log output and extract all conventional commit parts
  */
-export declare function parseCommitsWithMultiplePrefixes(gitOutput: string, repoUrl: string): string;
+export declare function parseCommitsWithMultiplePrefixes(gitOutput: string, repoUrl: string, typeMap?: Record<string, string | false>): string;
 /**
  * Resolve the `since` baseline for changelog generation.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oorabona/release-it-preset",
-  "version": "0.14.0",
+  "version": "1.0.0-rc.0",
   "description": "Shared release-it preset with OIDC trusted publishing, smart npm dist-tag selection, and monorepo per-package changelog support",
   "type": "module",
   "keywords": [
@@ -85,7 +85,7 @@
     "prepublishOnly": "pnpm build && echo 'Running prepublish checks...' && test -f README.md && test -f LICENSE"
   },
   "peerDependencies": {
-    "release-it": "^20.0.0"
+    "release-it": "^19.0.0 || ^20.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",
@@ -96,10 +96,11 @@
     "rimraf": "^6.1.3",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
+    "vite": "^7.3.2",
     "vitest": "^4.1.5"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.19.0"
   },
   "packageManager": "pnpm@10.17.1"
 }