@oorabona/release-it-preset 0.13.1 → 0.15.0

package/README.md

@@ -556,6 +556,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 +701,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}`)

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,489 @@
+#!/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
+// ---------------------------------------------------------------------------
+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',
+            });
+        }
+    }
+    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());
@@ -112,19 +89,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) {
+            // F-003: 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.
+            //
+            // F-004: Use matchAll() 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).
+                // F-004: 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 +154,16 @@ export function parseCommitsWithMultiplePrefixes(gitOutput, repoUrl) {
     const groupedParts = {};
     const breakingChanges = [];
     for (const part of allParts) {
-        // Collect breaking changes separately
+        // F-002: 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 +172,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 +200,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 +297,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.13.1",
+  "version": "0.15.0",
   "description": "Shared release-it preset with OIDC trusted publishing, smart npm dist-tag selection, and monorepo per-package changelog support",
   "type": "module",
   "keywords": [
@@ -96,6 +96,7 @@
     "rimraf": "^6.1.3",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
+    "vite": "^7.3.2",
     "vitest": "^4.1.5"
   },
   "engines": {