@williamthorsen/release-kit 10.6.0 → 10.8.0

package/docs/work-types.md

@@ -0,0 +1,116 @@
+# Work types and tiers
+
+The taxonomy against which release-kit parses commits: its tiers, the breaking-change policy, section markers, customization, and the commands that compare it with its upstream.
+
+release-kit bundles a copy of the codeassembly canonical taxonomy in `packages/release-kit/src/work-types.json`, kept level by `release-kit work-types sync`. The taxonomy is split into three tiers that drive section rendering and audience classification.
+
+| Tier     | Key         | Header                    | Aliases       | `!` policy   |
+| -------- | ----------- | ------------------------- | ------------- | ------------ |
+| public   | `feat`      | 🎉 Features               | `feature`     | optional     |
+| public   | `drop`      | 🪦 Removed                |               | **required** |
+| public   | `deprecate` | 🗑️ Deprecated             |               | forbidden    |
+| public   | `fix`       | 🐛 Bug fixes              | `bugfix`      | optional     |
+| public   | `sec`       | 🔒 Security               | `security`    | optional     |
+| public   | `perf`      | ⚡ Performance            | `performance` | optional     |
+| internal | `internal`  | 🏗️ Internal features      | `utility`     | forbidden    |
+| internal | `refactor`  | ♻️ Refactoring            |               | forbidden    |
+| internal | `tests`     | 🧪 Tests                  | `test`        | forbidden    |
+| process  | `tooling`   | ⚙️ Tooling                |               | forbidden    |
+| process  | `ci`        | 👷 CI                     |               | forbidden    |
+| process  | `deps`      | 📦 Dependencies           | `dep`         | forbidden    |
+| process  | `ai`        | 🤖 Agentic support        |               | forbidden    |
+| process  | `docs`      | 📚 Documentation          | `doc`         | forbidden    |
+| process  | `fmt`       | (excluded from changelog) |               | forbidden    |
+
+## Tier semantics
+
+- **`public`** — visible to all audiences. `public`-tier sections appear in both public release notes and dev changelogs.
+- **`internal`** — dev-only. `internal`-tier sections appear in dev changelogs but not in public-facing release notes.
+- **`process`** — dev-only. Same audience treatment as `internal`.
+
+Section render order is **tier order (`public` → `internal` → `process`), then row order within tier**. The bundled `cliff.toml.template` encodes this order via hidden `<!-- NN -->` HTML-comment prefixes on each parser's `group` value; tera's `group_by` filter sorts groups lexicographically (now monotonic by row number), and the body template's `striptags` filter erases the prefix from rendered headings.
+
+## `utility` alias
+
+`utility:` is a backward-compat alias for `internal:`. Both forms parse to the same canonical type, route to the same `🏗️ Internal features` section, and are subject to the same `!` policy.
+
+## `!` (breaking change) policy
+
+Each work-type carries a `breakingPolicy` value:
+
+- `optional` (`feat`, `fix`, `sec`, `perf`): `!` is allowed; both `type:` and `type!:` parse cleanly. Any of these can break consumers, and the marker records when one does: A fix can break consumers who relied on the defective behavior, and a performance change can break a contract to achieve its gain.
+- `forbidden` (`deprecate` and every `internal`- and `process`-tier type): `!` is a policy violation. Deprecating a surface keeps it working, and removing it is a `drop`. Internal- and process-tier work does not face consumers; a change that breaks consumers faces them and therefore takes a public-tier type.
+- `required` (`drop`): Bare `drop:` is a policy violation; only `drop!:` is accepted. Removing a public surface always breaks consumers, and the `!` form makes that explicit.
+
+### Policy enforcement
+
+`parseCommitMessage` enforces the `!` policy at release time and treats a violation as a warning. Commits already in the log cannot be rewritten, so a policy-violating commit is parsed using its canonical type with `breaking: false` (the `!` is dropped from the parse) and an `onPolicyViolation` callback fires. Callers (`decideRelease` etc.) can collect these warnings and surface them in the release report. A single legacy `internal!` in a year-old log does not block releases.
+
+A `BREAKING CHANGE:` body footer on a `forbidden`-policy type triggers the same warning path as the prefix `!` does: A type that cannot be breaking is parsed as non-breaking whichever surface carries the signal.
+
+The release-prepare orchestrators (`releasePrepare`, `releasePrepareMono`, `releasePrepareProject`) apply `DEFAULT_BREAKING_POLICIES` automatically. Violations encountered while parsing each workspace's or project's commit window are collected onto the corresponding result's `policyViolations` field and rendered under the section in the prepare report:
+
+```
+arrays
+  Found 1 commits since arrays-v1.0.0
+  ⚠️  1 policy violation:
+      · def5678 'internal!: refactor cache' — type 'internal' at prefix surface
+  Bumping versions (patch)...
+  📦 1.0.0 → 1.0.1 (patch)
+```
+
+To customize, set `breakingPolicies` in `release-kit.config.ts`. The map replaces the default policies rather than merging with them, and the parser treats any type that the map omits as `'optional'`: A config that changes one type lists every policy that it keeps, and `{}` disables enforcement entirely. Violations remain warnings, never failures.
+
+## `🚨 **Breaking:**` bullet marker
+
+Items whose commit subject carries the `!` prefix (e.g. `feat!`, `drop!`, `feat(api)!`) on a type whose policy permits it are rendered with a `🚨 **Breaking:** ` prefix on the bullet:
+
+```markdown
+- 🚨 **Breaking:** Drop legacy /v1 endpoint
+```
+
+The marker agrees with the version bump:
+
+- A `forbidden`-policy type carrying `!`, such as `refactor!`, gets no marker, just as its `!` raises no bump; the prepare report lists it as a policy violation. An [editorial override](editorial-overrides.md) that sets `breaking: true` restores the marker for one entry.
+- The configured `breakingPolicies` map, `{}` included, decides which types permit the marker.
+- A commit whose type the parser cannot resolve has no policy, so its `!` prefix alone decides.
+
+A `BREAKING CHANGE:` body footer on its own does **not** retroactively mark a changelog item as breaking, even on a type whose policy permits `!`; the changelog signal is tied to the commit prefix. This avoids surprise breaking-marker appearances for older commits written under earlier conventions.
+
+The emoji and label of this marker are sourced from the `markers.breaking` entry in `work-types.json` (see [Section markers](#section-markers)) so consumers that render their own breaking-changes section draw from the same SSOT.
+
+## Section markers
+
+Alongside `tiers` and `types`, `work-types.json` exposes a top-level `markers` object for cross-cutting section markers — visual indicators that aren't tied to a specific work type. Today the canonical entry is `breaking`; additional keys (e.g., security advisories, migration notices) can be added without a schema change.
+
+```jsonc
+{
+  "markers": {
+    "breaking": { "emoji": "🚨", "label": "Breaking" },
+  },
+}
+```
+
+Entries store plain text only — the SSOT is format-agnostic, so consumers apply their own emphasis (Markdown bold, ANSI escape, HTML `<strong>`) when constructing the rendered form. release-kit's own renderer constructs the per-bullet prefix as `${emoji} **${label}:** ` from this entry.
+
+## `fmt`
+
+`fmt:` commits are recognized by `parseCommitMessage` (they contribute to a patch bump) but `fmt` carries `excludedFromChangelog: true`. The bundled `cliff.toml.template` skips `fmt:` commits at the parser level, so they never appear in `CHANGELOG.md`, `changelog.json`, or release notes. The label and emoji are present in `work-types.json` for schema parity with the codeassembly upstream but never render.
+
+## Custom work types
+
+Work types from your config are merged with these defaults by key — your entries override or extend, they don't replace the full set. Release-notes sections are rendered in the declaration order of the merged work-types record, with any unknown titles trailing the known ones.
+
+The default `devOnlySections` (excluded from public release notes but still written to `CHANGELOG.md`) are derived from the `internal` and `process` tiers (excluding `fmt`). Override via `changelogJson.devOnlySections` in your config; matching is decorator-tolerant, so a bare-name override like `['Internal features']` keeps working against the emoji-prefixed and prefix-decorated default titles.
+
+## `release-kit work-types`
+
+Manage the canonical work-types taxonomy used by changelog and release-notes generation.
+
+`check` exits 0 on a match, 1 on drift, 2 when the upstream fetch fails, and 3 when either file is not valid JSON or the upstream fails the shape check. When the upstream URL returns 404, `check` exits 0 with a warning.
+
+These commands are also exposed as `nmr work-types:check` / `nmr work-types:sync` from any package directory.
+
+### Authenticated fetches
+
+The upstream codeassembly repo is public, so `check` and `sync` need no token. When `GITHUB_TOKEN` is set in the environment, both commands send it as `Authorization: Bearer <token>`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/release-kit",
-  "version": "10.6.0",
+  "version": "10.8.0",
   "description": "Version-bumping and changelog-generation toolkit for release workflows",
   "keywords": [
     "changelog",
@@ -45,11 +45,13 @@
     "bin",
     "cliff.toml.template",
     "dist/*",
+    "docs",
+    "!docs/*.v*.md",
     "presets/**",
     "schemas/**"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.11.0",
+    "@williamthorsen/nmr-core": "0.11.1",
     "@williamthorsen/toolbelt.errors": "0.7.0",
     "glob": "13.0.6",
     "json-stringify-pretty-compact": "4.0.0",
@@ -62,8 +64,9 @@
     "@williamthorsen/toolbelt.filesystem": "0.8.3",
     "@williamthorsen/toolbelt.testing": "0.5.1",
     "@williamthorsen/toolbelt.vitest": "0.9.0",
-    "readyup": "0.35.0",
-    "smol-toml": "1.8.0"
+    "readyup": "0.36.0",
+    "smol-toml": "1.8.0",
+    "vitest": "4.1.11"
   },
   "engines": {
     "node": ">=24"

package/dist/esm/readCurrentVersion.d.ts

@@ -1,2 +0,0 @@
-/** Read the `version` field from a package.json file. Returns undefined if the file can't be read or parsed. */
-export declare function readCurrentVersion(filePath: string): string | undefined;

package/dist/esm/readCurrentVersion.js

@@ -1,18 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { describeError } from '@williamthorsen/toolbelt.errors';
-function hasVersionField(value) {
-    return typeof value === 'object' && value !== null && 'version' in value && typeof value.version === 'string';
-}
-export function readCurrentVersion(filePath) {
-    try {
-        const content = readFileSync(filePath, 'utf8');
-        const parsed = JSON.parse(content);
-        if (hasVersionField(parsed)) {
-            return parsed.version;
-        }
-    }
-    catch (error) {
-        console.warn(`Failed to read current version from ${filePath}: ${describeError(error)}`);
-    }
-    return undefined;
-}