@williamthorsen/release-kit 18.2.0 → 18.3.0

package/.meta/changelog.json

@@ -1,4 +1,94 @@
 [
+  {
+    "version": "18.3.0",
+    "date": "2026-11-14",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Adds the `versionPatterns.none` setting to `release-kit`, whose default list (`ai`, `ci`, `docs`, `tests`, `tooling`) names the types that do not bump a version unless an item is breaking, so that `prepare` skips a window containing only those items; `none: []` restores a patch bump for them. (#1340)",
+            "hash": "d060436067879c9934d3dccbbde10c0b34392989",
+            "entry": 1
+          },
+          {
+            "description": "Makes `release-kit` list a dependent's own unreleased items, such as `tests` or `ci` items, together with its dependencies in the changelog entry for a release triggered by propagation alone, rather than the dependencies only. (#1340)",
+            "hash": "d060436067879c9934d3dccbbde10c0b34392989",
+            "entry": 2
+          },
+          {
+            "description": "Changes `create-github-release` to print a stderr warning that names the tag and the file when a tag's `changelog.json` is missing or cannot be parsed, instead of listing that tag in its `Skipped N tag(s) without releasable content` summary. (#1343)",
+            "hash": "64a18b97c8100012dbde3284f4c0c65a2a8ebe4e",
+            "entry": 1
+          },
+          {
+            "description": "Adds the tag and its workspace to the warning that `publish` prints when it skips injecting release notes into a README, alongside the reason: a missing or unparseable `changelog.json`, a version without an entry, or an entry without user-facing release notes. (#1343)",
+            "hash": "64a18b97c8100012dbde3284f4c0c65a2a8ebe4e",
+            "entry": 2
+          },
+          {
+            "description": "Adds the labels `effort:1`, `effort:2`, `effort:3`, `effort:5`, `effort:8`, and `effort:13` to the `common` label preset, which state an item's size in points apart from its urgency and value. (#1355)",
+            "hash": "998ba6fbaa286eef4960adc5e25523f6b50338d5",
+            "entry": 1
+          }
+        ]
+      },
+      {
+        "title": "🐛 Bug fixes",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Fixes the issue that `release-kit prepare` treated an unreadable, unparseable, or non-array `changelog.json` as empty and silently dropped elements that are not changelog entries, which overwrote the history in the file; `prepare` now stops with an error that names the file and tells the user to repair or delete it. (#1346)",
+            "hash": "4a0c6ee88949cd9a8ff0b91ec6a603caa5a6b692",
+            "entry": 1
+          },
+          {
+            "description": "Fixes the issue that `release-kit tag` reported a failed git command during its clean-tree check as a dirty working tree rather than as git's own error. (#1348)",
+            "hash": "17acd51ac7f25580a6277b88b1c01bc8fc76ee1d",
+            "entry": 1
+          },
+          {
+            "description": "Fixes the issue that `release-kit` reported a JSON file that it could not read as one that it could not parse, or the reverse, by giving each failure the message `Failed to read <path>` or `Failed to parse JSON in <path>`. (#1350)",
+            "hash": "bbe64c890eb8adff00e9f76aff25fab092fe638c",
+            "entry": 1
+          },
+          {
+            "description": "Fixes the issue that the `release-kit prepare` report printed a single-package release's and a project's warnings, bump override, and parsed count in a different order from a workspace's, and printed \"Parsed 0 typed commits\" for a single-package release or a count for one that skipped. (#1354)",
+            "hash": "a7548a236902ff6d2e7968271459e02114de640f",
+            "entry": 1
+          }
+        ]
+      },
+      {
+        "title": "♻️ Refactoring",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Routes release-kit's git calls, apart from those in `packFromCleanCheckout.ts`, through a `Git` adapter in `git.ts` that each module receives as a parameter, so that unit tests pass a fake git instead of mocking `node:child_process`. (#1348)",
+            "hash": "17acd51ac7f25580a6277b88b1c01bc8fc76ee1d",
+            "entry": 2
+          },
+          {
+            "description": "Moves the dry-run notice, eligibility checks, and repo-type detection that `release-kit`'s `init` and `update-templates` commands each repeated into `resolveEligibleRepoType` in `src/init/eligibility.ts`, so that `updateTemplatesCommand.ts` no longer imports from `initCommand.ts`. (#1353)",
+            "hash": "d663fdfe45d03fb9dcadef09f80a32191a531f10",
+            "entry": 1
+          }
+        ]
+      },
+      {
+        "title": "🧪 Tests",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Replaces the file-wide `silenceConsole` calls in the release-kit and v11y-check tests with a `using` silencer in each test that logs, restricted to the channels that the test fires, and reads asserted output through `listConsoleLines` rather than through the `console` mocks. (#1349)",
+            "hash": "38e028a3010ee083c1d48f0b22f72a45fc4852a3",
+            "entry": 3
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "18.2.0",
     "date": "2026-11-13",

package/.readyup/kits/default.js

@@ -805,12 +805,12 @@ ${result.diff ?? ""}` };
 }
 
 // .readyup/lib/workflow-hashes.ts
-var COMMON_PRESET_HASH = "945ee6d9f69365b0c8c5e20e9fed5b7ef7eee418fa28bf3602a21a48d293ed03";
+var COMMON_PRESET_HASH = "c39637a3c99735331c46ef0ca29eb5031c02185c53e1cb007ccc50ecefad3fcd";
 var SYNC_LABELS_WORKFLOW_HASH = "0a88829d154c0de7cdd4246fede99e9311a89ab4199034dbe601663d641ab1e4";
 
 // .readyup/kits/default.ts
 function getMinVersion() {
-  const picked = { "version": "18.2.0" };
+  const picked = { "version": "18.3.0" };
   if (typeof picked["version"] !== "string") {
     throw new TypeError("release-kit/package.json: 'version' must be a string");
   }

package/.readyup/manifest.json

@@ -3,12 +3,12 @@
   "kits": [
     {
       "bundledDependencies": {
-        "@williamthorsen/toolbelt.datetime": "4.1.4",
+        "@williamthorsen/toolbelt.datetime": "4.1.5",
         "@williamthorsen/toolbelt.errors": "0.10.1",
-        "@williamthorsen/toolbelt.filesystem": "0.10.3",
-        "@williamthorsen/toolbelt.numbers": "8.0.1",
+        "@williamthorsen/toolbelt.filesystem": "0.11.0",
+        "@williamthorsen/toolbelt.numbers": "8.0.2",
         "@williamthorsen/toolbelt.objects": "4.4.3",
-        "@williamthorsen/toolbelt.packaging": "0.7.3",
+        "@williamthorsen/toolbelt.packaging": "0.8.0",
         "@williamthorsen/toolbelt.terminal": "0.3.1",
         "ansi-regex": "6.6.0",
         "ansi-styles": "6.2.3, 7.0.0",
@@ -25,7 +25,7 @@
           "checklist": "release-kit",
           "checks": [
             "@williamthorsen/release-kit in devDependencies",
-            "@williamthorsen/release-kit >= 18.2.0",
+            "@williamthorsen/release-kit >= 18.3.0",
             "release.yaml workflow exists",
             "release.yaml matches template",
             "release.yaml does not reference deprecated tag ref",
@@ -160,12 +160,12 @@
           "path": "lib/template-checks.ts"
         },
         {
-          "hash": "ec55cfef",
+          "hash": "3c6fd66a",
           "kind": "module",
           "path": "lib/workflow-hashes.ts"
         },
         {
-          "hash": "ec16f961",
+          "hash": "af60087a",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -203,7 +203,7 @@
           "path": "../src/init/scaffold.ts"
         },
         {
-          "hash": "e10ddb57",
+          "hash": "4d4b66bc",
           "kind": "module",
           "path": "../src/init/templates.ts"
         },
@@ -218,16 +218,16 @@
       "readyupVersion": "0.46.2",
       "source": "kits/default.ts",
       "sourceHash": "ee8d2dc8",
-      "targetHash": "dfbfab4f"
+      "targetHash": "5985226a"
     },
     {
       "bundledDependencies": {
-        "@williamthorsen/toolbelt.datetime": "4.1.4",
+        "@williamthorsen/toolbelt.datetime": "4.1.5",
         "@williamthorsen/toolbelt.errors": "0.10.1",
-        "@williamthorsen/toolbelt.filesystem": "0.10.3",
-        "@williamthorsen/toolbelt.numbers": "8.0.1",
+        "@williamthorsen/toolbelt.filesystem": "0.11.0",
+        "@williamthorsen/toolbelt.numbers": "8.0.2",
         "@williamthorsen/toolbelt.objects": "4.4.3",
-        "@williamthorsen/toolbelt.packaging": "0.7.3",
+        "@williamthorsen/toolbelt.packaging": "0.8.0",
         "@williamthorsen/toolbelt.terminal": "0.3.1",
         "ansi-regex": "6.6.0",
         "ansi-styles": "6.2.3, 7.0.0",

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## 18.3.0 — 2026-11-14
+
+### 🎉 Features
+
+- Adds the `versionPatterns.none` setting to `release-kit`, whose default list (`ai`, `ci`, `docs`, `tests`, `tooling`) names the types that do not bump a version unless an item is breaking, so that `prepare` skips a window containing only those items; `none: []` restores a patch bump for them. (#1340)
+- Makes `release-kit` list a dependent's own unreleased items, such as `tests` or `ci` items, together with its dependencies in the changelog entry for a release triggered by propagation alone, rather than the dependencies only. (#1340)
+- Changes `create-github-release` to print a stderr warning that names the tag and the file when a tag's `changelog.json` is missing or cannot be parsed, instead of listing that tag in its `Skipped N tag(s) without releasable content` summary. (#1343)
+- Adds the tag and its workspace to the warning that `publish` prints when it skips injecting release notes into a README, alongside the reason: a missing or unparseable `changelog.json`, a version without an entry, or an entry without user-facing release notes. (#1343)
+- Adds the labels `effort:1`, `effort:2`, `effort:3`, `effort:5`, `effort:8`, and `effort:13` to the `common` label preset, which state an item's size in points apart from its urgency and value. (#1355)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that `release-kit prepare` treated an unreadable, unparseable, or non-array `changelog.json` as empty and silently dropped elements that are not changelog entries, which overwrote the history in the file; `prepare` now stops with an error that names the file and tells the user to repair or delete it. (#1346)
+- Fixes the issue that `release-kit tag` reported a failed git command during its clean-tree check as a dirty working tree rather than as git's own error. (#1348)
+- Fixes the issue that `release-kit` reported a JSON file that it could not read as one that it could not parse, or the reverse, by giving each failure the message `Failed to read <path>` or `Failed to parse JSON in <path>`. (#1350)
+- Fixes the issue that the `release-kit prepare` report printed a single-package release's and a project's warnings, bump override, and parsed count in a different order from a workspace's, and printed "Parsed 0 typed commits" for a single-package release or a count for one that skipped. (#1354)
+
+### ♻️ Refactoring
+
+- Routes release-kit's git calls, apart from those in `packFromCleanCheckout.ts`, through a `Git` adapter in `git.ts` that each module receives as a parameter, so that unit tests pass a fake git instead of mocking `node:child_process`. (#1348)
+- Moves the dry-run notice, eligibility checks, and repo-type detection that `release-kit`'s `init` and `update-templates` commands each repeated into `resolveEligibleRepoType` in `src/init/eligibility.ts`, so that `updateTemplatesCommand.ts` no longer imports from `initCommand.ts`. (#1353)
+
+### 🧪 Tests
+
+- Replaces the file-wide `silenceConsole` calls in the release-kit and v11y-check tests with a `using` silencer in each test that logs, restricted to the channels that the test fires, and reads asserted output through `listConsoleLines` rather than through the `console` mocks. (#1349)
+
 ## 18.2.0 — 2026-11-13
 
 ### 🎉 Features

package/README.md

@@ -7,23 +7,22 @@ Version-bumping and changelog-generation toolkit for release workflows.
 Provides a self-contained CLI that auto-discovers workspaces from `pnpm-workspace.yaml`, parses conventional commits, determines version bumps, updates `package.json` files, and generates changelogs from the same commit history that decides each bump (with optional [editorial overrides](docs/editorial-overrides.md)).
 
 <!-- section:release-notes -->
-## Release notes — v18.2.0 (2026-11-13)
+## Release notes — v18.3.0 (2026-11-14)
 
 ### 🎉 Features
 
-- Changes `release-kit show-tag-prefixes` to print one block per target that lists the derived prefix and each declared legacy identity with their tag counts in aligned columns, and to print the "Undeclared tag prefixes" section on every run, showing `(none)` when the scan does not find any candidates. (#1332)
-- Adds a "Retired packages" section to `release-kit show-tag-prefixes`, which lists each entry declared in `retiredPackages` with its tag prefix, tag count, name, and successor. (#1332)
-- Adds a closing note to `release-kit show-tag-prefixes` when a derived prefix does not have any tags yet, which explains that `release-kit tag` creates the first tag from the tags file that `release-kit prepare` writes. (#1332)
-- Makes the template checks for `release.yaml`, `publish.yaml`, and `create-github-release.yaml` report the differing hunks, and distinguish a missing file from an unreadable one, rather than report only that a hash differs. (#1336)
-
-### 🪦 Removed
-
-- Removes the check for the retired `.config/sync-labels.config.ts`, which made `sync-labels init`, `generate`, and `sync` exit with an error and made the release-kit readyup kit fail while the file existed. (#1333)
+- Adds the `versionPatterns.none` setting to `release-kit`, whose default list (`ai`, `ci`, `docs`, `tests`, `tooling`) names the types that do not bump a version unless an item is breaking, so that `prepare` skips a window containing only those items; `none: []` restores a patch bump for them. (#1340)
+- Makes `release-kit` list a dependent's own unreleased items, such as `tests` or `ci` items, together with its dependencies in the changelog entry for a release triggered by propagation alone, rather than the dependencies only. (#1340)
+- Changes `create-github-release` to print a stderr warning that names the tag and the file when a tag's `changelog.json` is missing or cannot be parsed, instead of listing that tag in its `Skipped N tag(s) without releasable content` summary. (#1343)
+- Adds the tag and its workspace to the warning that `publish` prints when it skips injecting release notes into a README, alongside the reason: a missing or unparseable `changelog.json`, a version without an entry, or an entry without user-facing release notes. (#1343)
+- Adds the labels `effort:1`, `effort:2`, `effort:3`, `effort:5`, `effort:8`, and `effort:13` to the `common` label preset, which state an item's size in points apart from its urgency and value. (#1355)
 
 ### 🐛 Bug fixes
 
-- Fixes the issue that `release-kit`'s ReadyUp kit reported the warning `releaseNotes.shouldInjectIntoReadme is true`, which the consumer could not clear, in a repo without any publishable package, by making the check skip with the reason `no publishable packages`. (#1334)
-- Fixes the issue that the `publish.yaml matches template` check in `rdy run --from npm:@williamthorsen/release-kit` failed a `publish.yaml` that omits provenance, a setting that `release-kit update-templates` preserves. (#1336)
+- Fixes the issue that `release-kit prepare` treated an unreadable, unparseable, or non-array `changelog.json` as empty and silently dropped elements that are not changelog entries, which overwrote the history in the file; `prepare` now stops with an error that names the file and tells the user to repair or delete it. (#1346)
+- Fixes the issue that `release-kit tag` reported a failed git command during its clean-tree check as a dirty working tree rather than as git's own error. (#1348)
+- Fixes the issue that `release-kit` reported a JSON file that it could not read as one that it could not parse, or the reverse, by giving each failure the message `Failed to read <path>` or `Failed to parse JSON in <path>`. (#1350)
+- Fixes the issue that the `release-kit prepare` report printed a single-package release's and a project's warnings, bump override, and parsed count in a different order from a workspace's, and printed "Parsed 0 typed commits" for a single-package release or a count for one that skipped. (#1354)
 <!-- /section:release-notes -->
 
 ## Installation
@@ -123,7 +122,7 @@ export default defineConfig({
   formatCommand: 'npx prettier --write',
 
   // Override the default version patterns
-  versionPatterns: { major: ['!'], minor: ['feat', 'feature'] },
+  versionPatterns: { major: ['!'], minor: ['feat', 'feature'], none: ['ai', 'ci', 'docs', 'tests', 'tooling'] },
 
   // Add or override work types (merged with defaults by key)
   workTypes: { perf: { header: 'Performance' } },

package/dist/esm/assertCleanWorkingTree.d.ts

@@ -1,2 +1,3 @@
+import { type Git } from './git.js';
 /** Throws if `git status --porcelain` reports any uncommitted change in the working tree. */
-export declare function assertCleanWorkingTree(): void;
+export declare function assertCleanWorkingTree(git?: Git): void;

package/dist/esm/assertCleanWorkingTree.js

@@ -1,14 +1,10 @@
-import { execFileSync } from 'node:child_process';
-import { GIT_OUTPUT_LIMIT_BYTES, UserError } from '@williamthorsen/nmr-core';
+import { UserError } from '@williamthorsen/nmr-core';
+import { realGit } from "./git.js";
 import { asUserError } from "./user-error-chaining.js";
-export function assertCleanWorkingTree() {
+export function assertCleanWorkingTree(git = realGit) {
     let status;
     try {
-        status = execFileSync('git', ['status', '--porcelain'], {
-            encoding: 'utf8',
-            maxBuffer: GIT_OUTPUT_LIMIT_BYTES,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        }).trim();
+        status = git.readStatus();
     }
     catch (error) {
         throw asUserError(error);

package/dist/esm/assertReleasesOnNpm.js

@@ -1,9 +1,8 @@
-import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { isRecord, UserError } from '@williamthorsen/nmr-core';
 import { isPublishableManifest } from "./isPublishableManifest.js";
 import { lookUpNpmPackage } from "./npmRegistry.js";
-import { chainUserError } from "./user-error-chaining.js";
+import { readJsonFile } from "./readJsonFile.js";
 export function assertReleasesOnNpm(workspacePaths) {
     const unpublishedCandidates = [];
     const unverifiableCandidates = [];
@@ -27,13 +26,7 @@ export function assertReleasesOnNpm(workspacePaths) {
 }
 function buildNpmCandidate(workspacePath) {
     const manifestPath = join(workspacePath, 'package.json');
-    let manifest;
-    try {
-        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-    }
-    catch (error) {
-        throw chainUserError(`Failed to parse ${manifestPath}`, error);
-    }
+    const manifest = readJsonFile(manifestPath);
     if (!isRecord(manifest) || !isPublishableManifest(manifest) || typeof manifest['name'] !== 'string') {
         return undefined;
     }

package/dist/esm/assertTarballsComplete.js

@@ -1,4 +1,3 @@
-import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { isAnticipatedFailure, isRecord, UserError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
@@ -6,7 +5,7 @@ import { detectPackageManager } from "./detectPackageManager.js";
 import { findMissingManifestPaths } from "./findMissingManifestPaths.js";
 import { isPublishableManifest } from "./isPublishableManifest.js";
 import { packFromCleanCheckout } from "./packFromCleanCheckout.js";
-import { chainUserError } from "./user-error-chaining.js";
+import { readJsonFile } from "./readJsonFile.js";
 export function assertTarballsComplete(workspacePaths, devExportConditions, pack = packFromCleanCheckout) {
     const candidates = workspacePaths
         .map((workspacePath) => ({ workspacePath, manifest: readManifest(workspacePath) }))
@@ -52,12 +51,6 @@ function describeRefusal(incompletePackages) {
 }
 function readManifest(workspacePath) {
     const manifestPath = join(workspacePath, 'package.json');
-    let manifest;
-    try {
-        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-    }
-    catch (error) {
-        throw chainUserError(`Failed to parse ${manifestPath}`, error);
-    }
+    const manifest = readJsonFile(manifestPath);
     return isRecord(manifest) ? manifest : {};
 }

package/dist/esm/buildChangelogEntries.d.ts

@@ -1,13 +1,13 @@
 import { type ChangelogDiagnostics } from './buildChangelogItem.js';
-import { type RawCommit } from './enumerateReleaseWindows.js';
 import type { GenerateChangelogOptions } from './generateChangelogs.js';
+import { type Git, type RawCommit } from './git.js';
 import type { ChangelogEntry, ChangelogSection, ReleaseSettings, ReleaseType } from './types.js';
 /**
  * Builds structured changelog entries from the release windows of git history, naming the unreleased window `tag`.
  *
  * Composes `readReleaseHistory` and `convertToChangelogEntries` for a caller that knows the tag before it reads.
  */
-export declare function buildChangelogEntries(config: ReleaseHistoryConfig, tag: string, options: GenerateChangelogOptions): {
+export declare function buildChangelogEntries(config: ReleaseHistoryConfig, tag: string, options: GenerateChangelogOptions, git?: Git): {
     entries: ChangelogEntry[];
     diagnostics: ChangelogDiagnostics;
 };
@@ -38,7 +38,9 @@ export declare function convertToReleaseEntries(history: ReleaseHistory, tag: st
  * `classifyChangelogCommit`. A `release:` or merge subject yields nothing either way. The read records diagnostics
  * only for the unreleased window, since the released windows were reported when they were prepared.
  */
-export declare function readReleaseHistory(config: ReleaseHistoryConfig, options: GenerateChangelogOptions): ReleaseHistory;
+export declare function readReleaseHistory(config: ReleaseHistoryConfig, options: GenerateChangelogOptions, git: Git): ReleaseHistory;
+/** Returns `sections` in canonical order; a stable sort keeps unknown sections, which sort last, in encounter order. */
+export declare function sortSectionsCanonically(sections: readonly ChangelogSection[]): ChangelogSection[];
 /**
  * Strips a section title down to its bare name.
  *

package/dist/esm/buildChangelogEntries.js

@@ -5,13 +5,14 @@ import { classifyChangelogCommit, isNonChangeSubject, isReleaseSubject } from ".
 import { DEFAULT_BREAKING_POLICIES, DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
 import { determineBumpType } from "./determineBumpType.js";
 import { enumerateReleaseWindows } from "./enumerateReleaseWindows.js";
+import { realGit } from "./git.js";
 import { parseChangeRecordBlock } from "./parseChangeRecordBlock.js";
 import { stripEmojiPrefix } from "./stripEmojiPrefix.js";
 import { prefixUserError } from "./user-error-chaining.js";
 const UNRELEASED_TAG = 'unreleased';
 const CANONICAL_SECTION_ORDER = new Map(Object.values(DEFAULT_WORK_TYPES).map((config, index) => [stripGroupDecorations(config.header), index]));
-export function buildChangelogEntries(config, tag, options) {
-    const history = readReleaseHistory(config, options);
+export function buildChangelogEntries(config, tag, options, git = realGit) {
+    const history = readReleaseHistory(config, options, git);
     return { entries: convertToChangelogEntries(history, tag), diagnostics: history.unreleasedReading.diagnostics };
 }
 export function convertToChangelogEntries(history, tag) {
@@ -30,9 +31,10 @@ export function convertToReleaseEntries(history, tag, today) {
     }
     return convertToChangelogEntries(history, tag);
 }
-export function readReleaseHistory(config, options) {
+export function readReleaseHistory(config, options, git) {
     try {
         const windows = enumerateReleaseWindows({
+            git,
             ...(options.paths !== undefined && { paths: options.paths }),
             tagPrefixes: options.tagPrefixes,
             unreleasedTag: UNRELEASED_TAG,
@@ -52,6 +54,9 @@ export function readReleaseHistory(config, options) {
         throw prefixUserError(`Failed to read the release history for ${options.tagPrefixes.join(', ')}`, error);
     }
 }
+export function sortSectionsCanonically(sections) {
+    return sections.toSorted((a, b) => getCanonicalSectionPriority(a.title) - getCanonicalSectionPriority(b.title));
+}
 export function stripGroupDecorations(group) {
     return stripEmojiPrefix(group);
 }
@@ -72,7 +77,7 @@ function buildSections(sectionMap, devOnlySections) {
             items,
         });
     }
-    return sections.toSorted((a, b) => getCanonicalSectionPriority(a.title) - getCanonicalSectionPriority(b.title));
+    return sortSectionsCanonically(sections);
 }
 function formatDate(timestampSec) {
     return new Date(timestampSec * 1000).toISOString().slice(0, 10);

package/dist/esm/buildChangelogItem.d.ts

@@ -1,5 +1,5 @@
 import type { BumpSignal } from './determineBumpType.js';
-import type { RawCommit } from './enumerateReleaseWindows.js';
+import type { RawCommit } from './git.js';
 import { type ChangeRecordEntry } from './parseChangeRecordBlock.js';
 import type { ChangelogItem, MalformedChangeRecordBlock, PolicyViolation, ReleaseSettings, UndeclaredEntryType, UnroutedEntryScope, VersionPatterns, WorkTypeConfig } from './types.js';
 /**

package/dist/esm/buildDependencyGraph.js

@@ -1,6 +1,5 @@
-import { readFileSync } from 'node:fs';
 import { UserError } from '@williamthorsen/nmr-core';
-import { chainUserError } from "./user-error-chaining.js";
+import { readJsonFile } from "./readJsonFile.js";
 function isPackageJsonSubset(value) {
     return typeof value === 'object' && value !== null;
 }
@@ -52,20 +51,7 @@ export function buildDependencyGraph(targets) {
     return { packageNameToDir, dirToPackageName, dirToVersion, dependentsOf, dependenciesOf };
 }
 function readPackageJsonSubset(filePath) {
-    let content;
-    try {
-        content = readFileSync(filePath, 'utf8');
-    }
-    catch (error) {
-        throw chainUserError(`Failed to read ${filePath}`, error);
-    }
-    let parsedJson;
-    try {
-        parsedJson = JSON.parse(content);
-    }
-    catch (error) {
-        throw chainUserError(`Failed to parse JSON in ${filePath}`, error);
-    }
+    const parsedJson = readJsonFile(filePath);
     if (!isPackageJsonSubset(parsedJson)) {
         throw new UserError(`Invalid package.json at ${filePath}`);
     }

package/dist/esm/buildReleasedResult.d.ts

@@ -1,4 +1,4 @@
-import type { ReleaseHistory } from './buildChangelogEntries.js';
+import { type ReleaseHistory } from './buildChangelogEntries.js';
 import type { ChangelogEntry, PropagationSource, ReleasedCompositeResult, ReleasedTargetResult, ReleaseTarget, ReleaseType } from './types.js';
 /** The release level that a target takes, whether its own commits or a dependency's bump decided it. */
 export interface TargetRelease {
@@ -13,8 +13,20 @@ interface ReleaseDecisionFields {
 }
 /** The fields that a released result of either kind takes from the plan. */
 type ReleaseResultFields = Omit<ReleasedCompositeResult, 'commits' | 'kind' | 'parsedCommitCount' | 'releaseType' | 'status'>;
-/** Builds the one synthetic entry of a release that propagation alone set, under the dependencies header. */
-export declare function buildPropagationEntries(target: ReleaseTarget, release: TargetRelease, newVersion: string, today: string, dependenciesHeader: string): ChangelogEntry[];
+/** The inputs from which `buildPropagationEntries` builds a propagated release's entries. */
+export interface PropagationEntryArgs {
+    history: ReleaseHistory;
+    tag: string;
+    newVersion: string;
+    today: string;
+    dependenciesHeader: string;
+}
+/**
+ * Builds the entries of a release that propagation alone set: the window's own entries with the dependencies added to
+ * the new version's section under the dependencies header, or, when the window doesn't yield any item, the one
+ * synthetic entry under that header.
+ */
+export declare function buildPropagationEntries(target: ReleaseTarget, release: TargetRelease, args: PropagationEntryArgs): ChangelogEntry[];
 /** Builds the released result of a target from the plan's fields, by the target's kind. */
 export declare function buildReleasedResult(target: ReleaseTarget, fields: ReleaseResultFields, release: TargetRelease, decision: ReleaseDecisionFields | undefined, history: ReleaseHistory): ReleasedTargetResult;
 export {};

package/dist/esm/buildReleasedResult.js

@@ -1,10 +1,17 @@
 import { attachChangelogDiagnostics } from "./attachChangelogDiagnostics.js";
+import { convertToChangelogEntries, sortSectionsCanonically, stripGroupDecorations, } from "./buildChangelogEntries.js";
 import { buildSyntheticChangelogEntry } from "./buildSyntheticChangelogEntry.js";
-export function buildPropagationEntries(target, release, newVersion, today, dependenciesHeader) {
+export function buildPropagationEntries(target, release, args) {
     if (release.propagatedFrom === undefined) {
         throw new Error(`Workspace '${target.id}' has neither a direct release nor a propagation source`);
     }
-    return [buildSyntheticChangelogEntry(release.propagatedFrom, newVersion, today, dependenciesHeader)];
+    const { history, tag, newVersion, today, dependenciesHeader } = args;
+    const synthetic = buildSyntheticChangelogEntry(release.propagatedFrom, newVersion, today, dependenciesHeader);
+    const [newEntry, ...releasedEntries] = convertToChangelogEntries(history, tag);
+    if (history.unreleasedReading.sections.length === 0 || newEntry === undefined) {
+        return [synthetic];
+    }
+    return [{ ...newEntry, sections: mergeSections(newEntry.sections, synthetic.sections) }, ...releasedEntries];
 }
 export function buildReleasedResult(target, fields, release, decision, history) {
     switch (target.kind) {
@@ -78,3 +85,17 @@ function buildReleasedPackage(target, fields, release, decision, history) {
     attachChangelogDiagnostics(result, unreleasedReading.diagnostics);
     return result;
 }
+function mergeSections(sections, added) {
+    const merged = [...sections];
+    for (const section of added) {
+        const index = merged.findIndex((existing) => stripGroupDecorations(existing.title) === stripGroupDecorations(section.title));
+        const existing = merged[index];
+        if (existing === undefined) {
+            merged.push(section);
+        }
+        else {
+            merged[index] = { ...existing, items: [...existing.items, ...section.items] };
+        }
+    }
+    return sortSectionsCanonically(merged);
+}

package/dist/esm/changelogJsonFile.d.ts

@@ -7,7 +7,8 @@ export declare function renderChangelogJson(entries: ChangelogEntry[]): string;
  * Merges `entries` with the on-disk entries at `filePath` and returns the merged set in newest-first order, without
  * writing.
  *
- * Keeps an on-disk entry that `entries` lacks, which preserves synthetic entries across propagation runs. A missing or
- * malformed file counts as empty, so that a malformed file does not abort the release.
+ * Keeps an on-disk entry that `entries` lacks, which preserves synthetic entries across propagation runs. A missing file
+ * counts as empty. Throws a `UserError` when the file cannot be read as entries or contains an element that is not an
+ * entry, because the merged set would replace the history that the file holds.
  */
 export declare function mergeChangelogEntriesWithDisk(filePath: string, entries: ChangelogEntry[]): ChangelogEntry[];

package/dist/esm/changelogJsonFile.js

@@ -1,10 +1,8 @@
-import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { describeError } from '@williamthorsen/toolbelt.errors';
+import { UserError } from '@williamthorsen/nmr-core';
 import stringify from 'json-stringify-pretty-compact';
-import { isChangelogEntry } from "./changelogJsonUtils.js";
+import { loadChangelogEntries } from "./changelogJsonUtils.js";
 import { compareVersionsDescending } from "./compareVersions.js";
-import { isUnknownArray } from "./typeGuards.js";
 export function resolveChangelogJsonPath(config, changelogPath) {
     return join(changelogPath, config.changelogJson.outputPath);
 }
@@ -12,28 +10,24 @@ export function renderChangelogJson(entries) {
     return stringify(sortNewestFirst(entries), { maxLength: 100 }) + '\n';
 }
 export function mergeChangelogEntriesWithDisk(filePath, entries) {
-    const existingEntries = readExistingEntries(filePath);
-    return mergeEntries(entries, existingEntries);
+    return mergeEntries(entries, readExistingEntries(filePath));
 }
 function sortNewestFirst(entries) {
     return [...entries].toSorted((a, b) => compareVersionsDescending(a.version, b.version));
 }
 function readExistingEntries(filePath) {
-    if (!existsSync(filePath)) {
+    const loaded = loadChangelogEntries(filePath);
+    if (loaded.status === 'missing') {
         return [];
     }
-    try {
-        const content = readFileSync(filePath, 'utf8');
-        const parsedJson = JSON.parse(content);
-        if (!isUnknownArray(parsedJson)) {
-            return [];
-        }
-        return parsedJson.filter(isChangelogEntry);
+    if (loaded.status === 'unreadable') {
+        throw buildRefusal(filePath, loaded.reason);
     }
-    catch (error) {
-        console.warn(`Warning: could not parse existing ${filePath}: ${describeError(error)}; treating as empty`);
-        return [];
+    if (loaded.rejectedCount > 0) {
+        const elements = loaded.rejectedCount === 1 ? 'element is not a changelog entry' : 'elements are not changelog entries';
+        throw buildRefusal(filePath, `${loaded.rejectedCount} ${elements}`);
     }
+    return loaded.entries;
 }
 function mergeEntries(newEntries, existingEntries) {
     const versionMap = new Map();
@@ -45,3 +39,6 @@ function mergeEntries(newEntries, existingEntries) {
     }
     return sortNewestFirst(versionMap.values());
 }
+function buildRefusal(filePath, problem) {
+    return new UserError(`Cannot prepare the changelog from ${filePath}: ${problem}. Repair or delete the file, then rerun 'release-kit prepare'.`);
+}