@tallyrelease/core 0.4.2-beta.6 → 0.5.0-beta.14

package/CHANGELOG.md

@@ -33,48 +33,48 @@
 
 * **core:** count prereleases from a unit's introduction without a line base ([#48](https://github.com/abinnovision/tallyrelease/issues/48)) ([06a591b](https://github.com/abinnovision/tallyrelease/commit/06a591b3522cf60ce5bde56e393f464617ffa101))
 
-## [0.3.0](https://github.com/abinnovision/tally-release/compare/core-v0.2.0...core-v0.3.0) (2026-10-16)
+## [0.3.0](https://github.com/abinnovision/tallyrelease/compare/core-v0.2.0...core-v0.3.0) (2026-10-16)
 
 
 ### Features
 
-* **cli:** add tallyrelease pr for shared and separate release PRs ([#34](https://github.com/abinnovision/tally-release/issues/34)) ([5dbb294](https://github.com/abinnovision/tally-release/commit/5dbb2944a6f9535511710cbcfa5c6ddfccb14fe8))
-* **cli:** add tallyrelease run and fill released in plans ([#36](https://github.com/abinnovision/tally-release/issues/36)) ([8d90546](https://github.com/abinnovision/tally-release/commit/8d905469ed398a6daaa0e09f4fd9eb9c4c79c818))
-* **core:** add changelog writer, release items and PR marker ([#30](https://github.com/abinnovision/tally-release/issues/30)) ([e74244e](https://github.com/abinnovision/tally-release/commit/e74244ebc4752e3de39614159ef0761f1cd2a33c))
-* tag merged release PRs with tallyrelease release ([#35](https://github.com/abinnovision/tally-release/issues/35)) ([0058045](https://github.com/abinnovision/tally-release/commit/005804542b3f0b18a1a5afdb1a559231f8d10b4d))
-* write version files and changelogs with tallyrelease version ([#33](https://github.com/abinnovision/tally-release/issues/33)) ([5961ce0](https://github.com/abinnovision/tally-release/commit/5961ce0c56b7ddbb4bff2cf154d5b5556212e8cb))
+* **cli:** add tallyrelease pr for shared and separate release PRs ([#34](https://github.com/abinnovision/tallyrelease/issues/34)) ([5dbb294](https://github.com/abinnovision/tallyrelease/commit/5dbb2944a6f9535511710cbcfa5c6ddfccb14fe8))
+* **cli:** add tallyrelease run and fill released in plans ([#36](https://github.com/abinnovision/tallyrelease/issues/36)) ([8d90546](https://github.com/abinnovision/tallyrelease/commit/8d905469ed398a6daaa0e09f4fd9eb9c4c79c818))
+* **core:** add changelog writer, release items and PR marker ([#30](https://github.com/abinnovision/tallyrelease/issues/30)) ([e74244e](https://github.com/abinnovision/tallyrelease/commit/e74244ebc4752e3de39614159ef0761f1cd2a33c))
+* tag merged release PRs with tallyrelease release ([#35](https://github.com/abinnovision/tallyrelease/issues/35)) ([0058045](https://github.com/abinnovision/tallyrelease/commit/005804542b3f0b18a1a5afdb1a559231f8d10b4d))
+* write version files and changelogs with tallyrelease version ([#33](https://github.com/abinnovision/tallyrelease/issues/33)) ([5961ce0](https://github.com/abinnovision/tallyrelease/commit/5961ce0c56b7ddbb4bff2cf154d5b5556212e8cb))
 
-## [0.2.0](https://github.com/abinnovision/tally-release/compare/core-v0.1.1...core-v0.2.0) (2026-10-15)
+## [0.2.0](https://github.com/abinnovision/tallyrelease/compare/core-v0.1.1...core-v0.2.0) (2026-10-15)
 
 
 ### Features
 
-* add fixed groups ([#23](https://github.com/abinnovision/tally-release/issues/23)) ([9822ded](https://github.com/abinnovision/tally-release/commit/9822dedcb572b852348e7df3577d101bf4d70e62))
-* **cli:** add plan and explain commands ([#20](https://github.com/abinnovision/tally-release/issues/20)) ([4a68ff1](https://github.com/abinnovision/tally-release/commit/4a68ff10092b44fb994fd62f86a51b7af4bdbd5f))
-* **core:** absorb internal changes as patch by default ([#22](https://github.com/abinnovision/tally-release/issues/22)) ([947b85f](https://github.com/abinnovision/tally-release/commit/947b85fd442ca650f0a47ee2349ffe41b9ea5b69))
-* **core:** absorb unreleased dependencies and propagate releases ([#19](https://github.com/abinnovision/tally-release/issues/19)) ([bb987ba](https://github.com/abinnovision/tally-release/commit/bb987ba04fec52cea611cd0b8c9ed2e851fb0c9c))
-* **core:** add semver scheme and conventional commit parser ([#16](https://github.com/abinnovision/tally-release/issues/16)) ([2012c0b](https://github.com/abinnovision/tally-release/commit/2012c0ba035d551335f14ba709ec6db5d5ea1582))
-* **core:** compute release versions with computePlan ([#18](https://github.com/abinnovision/tally-release/issues/18)) ([0341c3e](https://github.com/abinnovision/tally-release/commit/0341c3eea127abf32c1eda59344481a3ee506e84))
-* **core:** match unit tags and collect plan facts ([#17](https://github.com/abinnovision/tally-release/issues/17)) ([828f9bd](https://github.com/abinnovision/tally-release/commit/828f9bd427b6e69419bdbb00d6570edee0cd9e0e))
-* enforce maintenance branch limits ([#24](https://github.com/abinnovision/tally-release/issues/24)) ([c5e382b](https://github.com/abinnovision/tally-release/commit/c5e382bb1d58430555b85d8076659272353c1e30))
+* add fixed groups ([#23](https://github.com/abinnovision/tallyrelease/issues/23)) ([9822ded](https://github.com/abinnovision/tallyrelease/commit/9822dedcb572b852348e7df3577d101bf4d70e62))
+* **cli:** add plan and explain commands ([#20](https://github.com/abinnovision/tallyrelease/issues/20)) ([4a68ff1](https://github.com/abinnovision/tallyrelease/commit/4a68ff10092b44fb994fd62f86a51b7af4bdbd5f))
+* **core:** absorb internal changes as patch by default ([#22](https://github.com/abinnovision/tallyrelease/issues/22)) ([947b85f](https://github.com/abinnovision/tallyrelease/commit/947b85fd442ca650f0a47ee2349ffe41b9ea5b69))
+* **core:** absorb unreleased dependencies and propagate releases ([#19](https://github.com/abinnovision/tallyrelease/issues/19)) ([bb987ba](https://github.com/abinnovision/tallyrelease/commit/bb987ba04fec52cea611cd0b8c9ed2e851fb0c9c))
+* **core:** add semver scheme and conventional commit parser ([#16](https://github.com/abinnovision/tallyrelease/issues/16)) ([2012c0b](https://github.com/abinnovision/tallyrelease/commit/2012c0ba035d551335f14ba709ec6db5d5ea1582))
+* **core:** compute release versions with computePlan ([#18](https://github.com/abinnovision/tallyrelease/issues/18)) ([0341c3e](https://github.com/abinnovision/tallyrelease/commit/0341c3eea127abf32c1eda59344481a3ee506e84))
+* **core:** match unit tags and collect plan facts ([#17](https://github.com/abinnovision/tallyrelease/issues/17)) ([828f9bd](https://github.com/abinnovision/tallyrelease/commit/828f9bd427b6e69419bdbb00d6570edee0cd9e0e))
+* enforce maintenance branch limits ([#24](https://github.com/abinnovision/tallyrelease/issues/24)) ([c5e382b](https://github.com/abinnovision/tallyrelease/commit/c5e382bb1d58430555b85d8076659272353c1e30))
 
-## [0.1.1](https://github.com/abinnovision/tally-release/compare/core-v0.1.0...core-v0.1.1) (2026-10-15)
+## [0.1.1](https://github.com/abinnovision/tallyrelease/compare/core-v0.1.0...core-v0.1.1) (2026-10-15)
 
 
 ### Bug Fixes
 
-* add unit tags and an affected --tag filter ([#14](https://github.com/abinnovision/tally-release/issues/14)) ([733e556](https://github.com/abinnovision/tally-release/commit/733e55642dc582e24e06d2e2b118110547ace742))
+* add unit tags and an affected --tag filter ([#14](https://github.com/abinnovision/tallyrelease/issues/14)) ([733e556](https://github.com/abinnovision/tallyrelease/commit/733e55642dc582e24e06d2e2b118110547ace742))
 
 ## 0.1.0 (2026-10-15)
 
 
 ### Features
 
-* bootstrap tallyrelease with build selection (v0.1) ([#1](https://github.com/abinnovision/tally-release/issues/1)) ([4efde72](https://github.com/abinnovision/tally-release/commit/4efde72e32091df3c84a2b497272a3a0efdac659))
-* **cli:** align human-readable output and add a local build base ([#8](https://github.com/abinnovision/tally-release/issues/8)) ([96cb5f0](https://github.com/abinnovision/tally-release/commit/96cb5f010f3090806da4317a50c23ba17884c5c5))
-* make units build-only unless opted into release ([#6](https://github.com/abinnovision/tally-release/issues/6)) ([4b01768](https://github.com/abinnovision/tally-release/commit/4b0176809d38504eec22e35168f57ca17840ef13))
+* bootstrap tallyrelease with build selection (v0.1) ([#1](https://github.com/abinnovision/tallyrelease/issues/1)) ([4efde72](https://github.com/abinnovision/tallyrelease/commit/4efde72e32091df3c84a2b497272a3a0efdac659))
+* **cli:** align human-readable output and add a local build base ([#8](https://github.com/abinnovision/tallyrelease/issues/8)) ([96cb5f0](https://github.com/abinnovision/tallyrelease/commit/96cb5f010f3090806da4317a50c23ba17884c5c5))
+* make units build-only unless opted into release ([#6](https://github.com/abinnovision/tallyrelease/issues/6)) ([4b01768](https://github.com/abinnovision/tallyrelease/commit/4b0176809d38504eec22e35168f57ca17840ef13))
 
 
 ### Bug Fixes
 
-* **cli:** clearer errors and package docs for the 0.1.0 release ([#11](https://github.com/abinnovision/tally-release/issues/11)) ([85fc7ed](https://github.com/abinnovision/tally-release/commit/85fc7ed70693bae01c9b90319d808f72f5eef6f6))
+* **cli:** clearer errors and package docs for the 0.1.0 release ([#11](https://github.com/abinnovision/tallyrelease/issues/11)) ([85fc7ed](https://github.com/abinnovision/tallyrelease/commit/85fc7ed70693bae01c9b90319d808f72f5eef6f6))

package/dist/branches.js

@@ -1,10 +1,10 @@
-import { TallyError } from "./errors.js";
+import { coreCodes } from "./codes.js";
 import { schemeRegistry } from "./schemes.js";
 import { maxLevel } from "./util.js";
 const SPECIAL = /[\\^$.*+?()[\]{}|/]/gu;
 const PART = /\{(major|minor)\}|\*/gu;
 const CHANNEL = /^[0-9A-Za-z-]+$/u;
-const ruleError = (rule, problem) => new TallyError("E_BRANCH_RULE", `branch rule "${rule.name}" ${problem}`, {
+const ruleError = (rule, problem) => coreCodes.error("E_BRANCH_RULE", `branch rule "${rule.name}" ${problem}`, {
     rule: rule.name,
 });
 /** Anchored regex of a rule name; throws `E_BRANCH_RULE`. */
@@ -72,16 +72,16 @@ export const validateBranches = (rules) => {
             continue;
         }
         if (rule.name.includes("*")) {
-            throw new TallyError("E_CHANNEL_WILDCARD", `branch rule "${rule.name}" contains * and cannot set a channel`, { rule: rule.name, channel });
+            throw coreCodes.error("E_CHANNEL_WILDCARD", `branch rule "${rule.name}" contains * and cannot set a channel`, { rule: rule.name, channel });
         }
         const literal = channel.replace(/\{(major|minor)\}/gu, (token) => rule.name.includes(token) ? "0" : token);
         if (!CHANNEL.test(literal) ||
             !/[A-Za-z-]/u.test(channel.replace(/\{(major|minor)\}/gu, ""))) {
-            throw new TallyError("E_CHANNEL_INVALID", `channel "${channel}" of branch rule "${rule.name}" must match ${CHANNEL.source}, contain a letter or dash and use only tokens captured by the rule`, { rule: rule.name, channel });
+            throw coreCodes.error("E_CHANNEL_INVALID", `channel "${channel}" of branch rule "${rule.name}" must match ${CHANNEL.source}, contain a letter or dash and use only tokens captured by the rule`, { rule: rule.name, channel });
         }
         const other = channels.get(channel);
         if (other !== undefined) {
-            throw new TallyError("E_CHANNEL_DUPLICATE", `channel "${channel}" is set by branch rules "${other}" and "${rule.name}"`, { channel, rules: [other, rule.name] });
+            throw coreCodes.error("E_CHANNEL_DUPLICATE", `channel "${channel}" is set by branch rules "${other}" and "${rule.name}"`, { channel, rules: [other, rule.name] });
         }
         channels.set(channel, rule.name);
     }
@@ -139,7 +139,7 @@ export const checkLimits = (line, items, { branch, implicit }) => {
         if (from.major !== absolute.major ||
             (absolute.minor !== undefined && from.minor !== absolute.minor)) {
             const expected = [absolute.major, absolute.minor ?? "x"].join(".");
-            throw new TallyError("E_CAP_BASE", `branch "${branch}": ${itemLabel(target)}${implicit ? " (the only release item)" : ""} is at ${from.version}, off the ${expected} line of branch rule "${line.rule}"; the branch was cut from or merged with a commit carrying a newer tag, or names a next major, which maintenance rules do not support (use a default-line rule with a channel)`, {
+            throw coreCodes.error("E_CAP_BASE", `branch "${branch}": ${itemLabel(target)}${implicit ? " (the only release item)" : ""} is at ${from.version}, off the ${expected} line of branch rule "${line.rule}"; the branch was cut from or merged with a commit carrying a newer tag, or names a next major, which maintenance rules do not support (use a default-line rule with a channel)`, {
                 ...itemDetails(target),
                 branch,
                 rule: line.rule,
@@ -157,7 +157,7 @@ export const checkLimits = (line, items, { branch, implicit }) => {
         const commits = item.commits.filter((c) => (c.level !== null && maxLevel(c.level, limit) !== limit) ||
             (c.releaseAs !== undefined && !within(limit, from, c.releaseAs)));
         const listed = commits.map(commitLabel).join("; ");
-        throw new TallyError("E_CAP", `${itemLabel(item)}: ${from.version} to ${next.version} exceeds the ${limit} limit of branch rule "${line.rule}"${listed === "" ? "" : `; commits: ${listed}`}`, {
+        throw coreCodes.error("E_CAP", `${itemLabel(item)}: ${from.version} to ${next.version} exceeds the ${limit} limit of branch rule "${line.rule}"${listed === "" ? "" : `; commits: ${listed}`}`, {
             ...itemDetails(item),
             rule: line.rule,
             limit,

package/dist/codes.d.ts

@@ -0,0 +1,26 @@
+import { TallyError } from "./errors.js";
+import type { Warning } from "./errors.js";
+type Checked<R> = {
+    [K in keyof R]: K extends `${"E" | "W"}_${string}` ? CodeDoc : never;
+};
+/** Documentation of one error or warning code. */
+export interface CodeDoc {
+    cause: string;
+    fix: string;
+}
+export type ErrorCode<C extends string> = Extract<C, `E_${string}`>;
+export type WarningCode<C extends string> = Extract<C, `W_${string}`>;
+/** Documented codes and constructors typed to them. */
+export interface CodeRegistry<C extends string> {
+    readonly docs: Readonly<Record<C, CodeDoc>>;
+    error: (code: ErrorCode<C>, message: string, details?: Record<string, unknown>) => TallyError;
+    warning: (code: WarningCode<C>, message: string, extra?: Pick<Warning, "plugin" | "unit">) => Warning;
+}
+export type CodeOf<R> = R extends CodeRegistry<infer C> ? C : never;
+/** Builds a registry from `E_*` and `W_*` codes and their documentation. */
+export declare const defineCodes: <R extends Record<string, CodeDoc>>(docs: R & Checked<R>) => CodeRegistry<keyof R & string>;
+/**
+ * Codes raised by core. Codes are only added, never removed or renamed.
+ */
+export declare const coreCodes: CodeRegistry<"E_BRANCH_RULE" | "E_CAP" | "E_CAP_BASE" | "E_CHANNEL_DUPLICATE" | "E_CHANNEL_INVALID" | "E_CHANNEL_WILDCARD" | "E_CONFIG" | "E_DUPLICATE_ROOT" | "E_DUPLICATE_UNIT" | "E_EDGE_SELF" | "E_EDGE_UNKNOWN_UNIT" | "E_GIT_DATE" | "E_GROUP_NOT_RELEASED" | "E_GROUP_OVERLAP" | "E_GROUP_SCHEME" | "E_GROUP_UNKNOWN_UNIT" | "E_INITIAL_VERSION" | "E_PLUGIN_API" | "E_PLUGIN_HOOK" | "E_PLUGIN_NAME" | "E_PLUGIN_OPTIONS" | "E_PLUGIN_UNKNOWN" | "E_RELEASE_ITEM_NAME" | "E_RELEASE_PR_SPLIT_EDGE" | "E_ROOT_INVALID" | "E_ROOT_MISSING" | "E_SCHEME_CLASH" | "E_SCHEME_UNKNOWN" | "E_TAG_FORMAT" | "E_TAG_FORMAT_OVERLAP" | "E_UNIT_GLOB" | "E_UNIT_ID" | "E_UNIT_TAG" | "E_UNIT_UNKNOWN" | "E_VERSION_FILE_CLAIM" | "E_VERSION_FILE_MISSING" | "E_VERSION_INVALID" | "W_CYCLE" | "W_GROUP_EMPTY" | "W_INITIAL_BELOW_PRERELEASE" | "W_NO_BRANCH_RULE" | "W_NO_MATCHING_TAG" | "W_NO_RELEASED_UNITS" | "W_PLUGIN" | "W_RELEASED_NO_BASE" | "W_RELEASE_AS_CONFLICT" | "W_RELEASE_AS_IGNORED" | "W_RELEASE_AS_INVALID" | "W_RELEASE_AS_UNKNOWN" | "W_RELEASE_NOT_BUILT" | "W_UNIT_GLOB_UNMATCHED" | "W_UNIT_UNKNOWN" | "W_VERSION_FILE_NO_MATCH">;
+export {};

package/dist/codes.js

@@ -0,0 +1,224 @@
+import { TallyError } from "./errors.js";
+/** Builds a registry from `E_*` and `W_*` codes and their documentation. */
+export const defineCodes = (docs) => ({
+    docs,
+    error: (code, message, details) => new TallyError(code, message, details),
+    warning: (code, message, extra) => ({ code, message, ...extra }),
+});
+/**
+ * Codes raised by core. Codes are only added, never removed or renamed.
+ */
+export const coreCodes = defineCodes({
+    E_BRANCH_RULE: {
+        cause: "An entry of `branches` is invalid. The `name` is empty, uses a token other than `{major}` or `{minor}`, repeats a token, uses `{minor}` without `{major}` or has an unbalanced brace. Or `unit` and `group` are both set, `unit` or `group` is set on a rule that is not a `maintenance` rule with `{major}`, or `unit` names a unit that is not released, is in a group or does not exist, or `group` names an unknown group.",
+        fix: "Correct the rule named in the message. Use either `unit` (ungrouped released unit) or `group`, only on `line: maintenance` rules whose `name` contains `{major}`, and name a unit or group that exists in the config.",
+    },
+    E_CAP: {
+        cause: "On a maintenance branch, a release item would leave the line of its current version, for example a breaking change or `Release-As` on a `release/1.x` branch. The message lists the offending commits.",
+        fix: "Remove or reword the commits that exceed the limit, for example by moving them to the default branch, or use a `Release-As` value inside the line. If the branch should release a new major, use a `default` line rule with a `channel` instead of a `maintenance` rule.",
+    },
+    E_CAP_BASE: {
+        cause: "On a maintenance branch, the unit or group named by the rule (or the only release item) is at a version outside the line captured by the branch name. Typically the branch was cut from or merged with a commit that carries a newer tag.",
+        fix: "Cut the branch from the last release of that line, or remove the newer commits from it. Set `unit` or `group` on the rule to name the item the line applies to.",
+    },
+    E_CHANNEL_DUPLICATE: {
+        cause: "Two `branches` rules set the same `channel`.",
+        fix: "Give each rule a distinct `channel`, or remove the `channel` from one of them.",
+    },
+    E_CHANNEL_INVALID: {
+        cause: "A rule's `channel` is not a valid prerelease identifier: it must match `[0-9A-Za-z-]+`, contain a letter or dash, and use only `{major}` and `{minor}` tokens that the rule's `name` captures. The same code is raised when the channel does not form a valid prerelease for a version.",
+        fix: "Use letters, digits and dashes only (for example `beta` or `rc-{major}`) and capture any token you use in the rule `name`.",
+    },
+    E_CHANNEL_WILDCARD: {
+        cause: "A `branches` rule sets a `channel` while its `name` contains `*`, so the channel would be ambiguous.",
+        fix: "Remove the `*` from the rule `name`, or remove the `channel` from that rule.",
+    },
+    E_CONFIG: {
+        cause: "The config file is not valid YAML, does not match the schema (unknown key, wrong type), or fails a semantic check: a unit sets `releasePr` while being in a group, a `tags.floating` format uses a token other than `{id}`, `{major}` or `{minor}`, or a `versionFiles` entry has a bad `file` or `pattern`.",
+        fix: "Fix the key named in the message. A `versionFiles` `pattern` needs literal text and either `{version}` or the `{major}`, `{minor}`, `{patch}` tokens (not mixed), and `file` must be a repo-relative path without `..`. Set `releasePr` on the group instead of on its members.",
+    },
+    E_DUPLICATE_ROOT: {
+        cause: "Two plugins discover a unit at the same root.",
+        fix: "Disable one of the plugins under `plugins`, or move one of the packages so each root is discovered once.",
+    },
+    E_DUPLICATE_UNIT: {
+        cause: "Two units resolve to the same id.",
+        fix: "Give one of them a distinct `id` in `units.<root>`.",
+    },
+    E_EDGE_SELF: {
+        cause: "A dependency edge points from a unit to itself. The message names the source, either a plugin or `config` (a `deps` entry).",
+        fix: "Remove the edge, or correct `from` or `to` in the `deps` entry.",
+    },
+    E_EDGE_UNKNOWN_UNIT: {
+        cause: "A dependency edge names a unit id that does not exist. The message names the source, either a plugin or `config` (a `deps` entry).",
+        fix: "Correct `from` or `to` in the `deps` entry so both are existing unit ids.",
+    },
+    E_GIT_DATE: {
+        cause: "A commit has a committer date that cannot be parsed.",
+        fix: "Check the commit named in the message with `git log --format=%cI <sha>`. Rewrite the history if the date is corrupt, or plan with a `--base` after that commit.",
+    },
+    E_GROUP_NOT_RELEASED: {
+        cause: "A group member is a unit that is not released.",
+        fix: "Set `release: true` on the unit (or `defaults.release: true`), or remove it from the group's `units` or `tags` selection.",
+    },
+    E_GROUP_OVERLAP: {
+        cause: "A unit is a member of two groups.",
+        fix: "Adjust `groups.<name>.units` and `groups.<name>.tags` so every unit belongs to at most one group.",
+    },
+    E_GROUP_SCHEME: {
+        cause: "Members of a group use different version schemes.",
+        fix: "Set the same `scheme` on all members of the group, or split the group.",
+    },
+    E_GROUP_UNKNOWN_UNIT: {
+        cause: "A group's `units` list names a unit id that does not exist.",
+        fix: "Correct the id in `groups.<name>.units`.",
+    },
+    E_INITIAL_VERSION: {
+        cause: "A unit's `initialVersion` is not a valid version for its scheme.",
+        fix: "Set `initialVersion` (on the unit or in `defaults`) to a version its scheme accepts, for example `1.0.0` for `semver`.",
+    },
+    E_PLUGIN_API: {
+        cause: "A plugin uses an API version that this tallyrelease does not support.",
+        fix: "Use a plugin built for this version of tallyrelease, or upgrade or downgrade the CLI to match the plugin.",
+    },
+    E_PLUGIN_HOOK: {
+        cause: "A plugin hook (such as `discover`, `edges`, `intent` or `write`) threw an error. The message names the plugin, the hook and the reason.",
+        fix: "Fix the cause given in the message, usually a malformed manifest or version file in the repository, or the plugin options in `plugins.<name>`.",
+    },
+    E_PLUGIN_NAME: {
+        cause: "A plugin name does not match `^[a-z][a-z0-9-]*$`, or uses the name `core`, which is reserved.",
+        fix: "Rename the plugin to lowercase letters, digits and dashes starting with a letter, and not `core`.",
+    },
+    E_PLUGIN_OPTIONS: {
+        cause: "The options under `plugins.<name>` fail the plugin's option validation.",
+        fix: "Fix the options named in the message, or remove them.",
+    },
+    E_PLUGIN_UNKNOWN: {
+        cause: "`plugins` lists a name that matches no built-in plugin (`node`, `php`, `kustomize`).",
+        fix: "Correct the plugin name in `plugins`, or remove the entry.",
+    },
+    E_RELEASE_ITEM_NAME: {
+        cause: "A release item (a group or an ungrouped released unit) has a name that cannot be used in a release PR branch: it is `shared`, starts or ends with `.`, ends with `.lock`, contains `..`, or a unit id equals a group name.",
+        fix: "Rename the unit (`units.<root>.id`) or the group so the name is valid and unique.",
+    },
+    E_RELEASE_PR_SPLIT_EDGE: {
+        cause: "A dependency edge that propagates a patch release connects two release items that are in different release PRs.",
+        fix: "Put both items in the same release PR with `releasePr` (or `defaults.releasePr`), group them under `groups`, or set `propagate: rebuild` on the dependent unit.",
+    },
+    E_ROOT_INVALID: {
+        cause: "A unit root, such as a key under `units` or a root discovered by a plugin, is absolute or contains `..` segments.",
+        fix: "Use repo-relative paths without `..`.",
+    },
+    E_ROOT_MISSING: {
+        cause: "The root of a unit does not exist in the working tree, for example a key under `units` that points to a missing directory.",
+        fix: "Create the directory, or correct or remove the `units` key.",
+    },
+    E_SCHEME_CLASH: {
+        cause: "Two plugins register a version scheme under the same name.",
+        fix: "Disable one of the plugins under `plugins`.",
+    },
+    E_SCHEME_UNKNOWN: {
+        cause: "A released unit's `scheme` is not registered by any enabled plugin.",
+        fix: "Correct `scheme` on the unit, or enable the plugin that provides it under `plugins`. The default scheme is `semver`.",
+    },
+    E_TAG_FORMAT: {
+        cause: "A unit's `tagFormat` does not contain `{version}` exactly once.",
+        fix: "Set `tagFormat` (on the unit or in `defaults`) to a template with a single `{version}`, for example `{id}-v{version}`.",
+    },
+    E_TAG_FORMAT_OVERLAP: {
+        cause: "Two released units render the same tag format, or one existing tag matches the format of more than one released unit.",
+        fix: "Give the units distinct `tagFormat` values, usually by including `{id}`.",
+    },
+    E_UNIT_GLOB: {
+        cause: "A glob key under `units` uses `*` inside a path segment instead of as a whole segment, or sets `id`, `include`, `exclude` or `versionFiles`, which globs cannot set.",
+        fix: "Use `*` only as a whole path segment (`packages/*`), and move those fields to an exact key.",
+    },
+    E_UNIT_ID: {
+        cause: "A unit id contains characters other than letters, digits, `.`, `_` and `-`, or is `.` or `..`.",
+        fix: "Set a valid `id` in `units.<root>`.",
+    },
+    E_UNIT_TAG: {
+        cause: "An entry in a unit's `tags` contains characters other than letters, digits, `.`, `_` and `-`.",
+        fix: "Rename the label in `units.<root>.tags`.",
+    },
+    E_UNIT_UNKNOWN: {
+        cause: "`explain` was given a unit id that does not exist.",
+        fix: "Pass an existing unit id. List ids with `tallyrelease graph`.",
+    },
+    E_VERSION_FILE_CLAIM: {
+        cause: "A file is the version file of two units, or is both a plugin version file and a `versionFiles` template target.",
+        fix: "Remove the duplicate `versionFiles` entry, or set one file per unit.",
+    },
+    E_VERSION_FILE_MISSING: {
+        cause: "A version file of a unit (from a plugin or a `versionFiles` entry) does not exist in the commit the release is based on.",
+        fix: "Create the file, or correct or remove the `versionFiles` entry.",
+    },
+    E_VERSION_INVALID: {
+        cause: "Bumping a version produced a string that is not a valid version. This does not happen for a valid current version.",
+        fix: "Report it as a bug with the version named in the message and the `--verbose` output.",
+    },
+    W_CYCLE: {
+        cause: "The dependency graph has a cycle. The message shows the path.",
+        fix: "Remove one of the edges, for example a `deps` entry. The plan still runs, but the order of units in a cycle is not meaningful.",
+    },
+    W_GROUP_EMPTY: {
+        cause: "A group in `groups` selects no released unit through `units` or `tags`, so it is dropped.",
+        fix: "Add member ids to `groups.<name>.units`, tag units with a label listed in `groups.<name>.tags`, or remove the group.",
+    },
+    W_INITIAL_BELOW_PRERELEASE: {
+        cause: "A unit's initial version does not exceed an existing prerelease tag of that unit.",
+        fix: "Raise `initialVersion` above the prerelease tag named in the message, or remove the stale tag.",
+    },
+    W_NO_BRANCH_RULE: {
+        cause: "No `branches` rule matches the branch, so versions in the plan are null.",
+        fix: "Add a rule for the branch under `branches`, for example `{ name: main, line: default }`, or pass `--branch`.",
+    },
+    W_NO_MATCHING_TAG: {
+        cause: "A released unit has no tag matching its `tagFormat`, but an existing tag contains its id.",
+        fix: "Rename the tag or set `tagFormat` on the unit so it matches existing tags.",
+    },
+    W_NO_RELEASED_UNITS: {
+        cause: "A branch rule matches, but no unit is released.",
+        fix: "Set `release: true` on units, or `defaults.release: true`.",
+    },
+    W_PLUGIN: {
+        cause: "A plugin logged a warning. The text is prefixed with the plugin name.",
+        fix: "Follow the message. It usually points at a manifest or option the plugin could not use.",
+    },
+    W_RELEASED_NO_BASE: {
+        cause: "The build base is unknown, so `released` in the plan only lists releases at HEAD and leaves out earlier releases on the first-parent chain.",
+        fix: "Pass `--base <ref>` or make the base resolvable (see `W_NO_FORGE` and `W_NO_LAST_SUCCESS`).",
+    },
+    W_RELEASE_AS_CONFLICT: {
+        cause: "Several different `Release-As` values apply to a unit. The newest valid one wins and the message names it.",
+        fix: "Remove the extra `Release-As` footers if the winner is not the intended one.",
+    },
+    W_RELEASE_AS_IGNORED: {
+        cause: "A `Release-As` footer is ignored because its commit is not attributed to a released unit, or it names a unit that is not released.",
+        fix: "Name a released unit (`Release-As: <unit>@<version>`), or remove the footer.",
+    },
+    W_RELEASE_AS_INVALID: {
+        cause: "A `Release-As` value is not a version of the unit's scheme, or is a prerelease, or does not exceed the unit's current version. It is ignored.",
+        fix: "Correct the footer value in the commit message, or drop it.",
+    },
+    W_RELEASE_AS_UNKNOWN: {
+        cause: "A `Release-As: <unit>@<version>` footer names a unit that does not exist.",
+        fix: "Correct the unit id in the footer.",
+    },
+    W_RELEASE_NOT_BUILT: {
+        cause: "A release of a unit is at HEAD, but the unit is not in the build set. It is listed as a catch-up.",
+        fix: "Build and publish the unit for that release, or ignore the warning if it was already built.",
+    },
+    W_UNIT_GLOB_UNMATCHED: {
+        cause: "A glob key under `units` matches no discovered unit. Globs never create units.",
+        fix: "Correct the glob, or remove it.",
+    },
+    W_UNIT_UNKNOWN: {
+        cause: "An intent source of a plugin names a unit id that does not exist.",
+        fix: "Correct the unit id in the intent source, or add the unit to the config.",
+    },
+    W_VERSION_FILE_NO_MATCH: {
+        cause: "A `versionFiles` `pattern` of a unit matches nothing in its file, so the file is not updated for the release.",
+        fix: "Make `pattern` match the text that holds the previous version, or remove the entry.",
+    },
+});

package/dist/discover.js

@@ -1,4 +1,4 @@
-import { TallyError } from "./errors.js";
+import { coreCodes } from "./codes.js";
 import { defaultUnitId } from "./plugin.js";
 import { runHook } from "./plugins.js";
 import { compare, uniqueSorted } from "./util.js";
@@ -16,11 +16,11 @@ const GLOB_REJECTED = ["id", "include", "exclude", "versionFiles"];
 const globSegments = (key, root, overlay) => {
     const segments = root.split("/");
     if (segments.some((s) => s !== "*" && s.includes("*"))) {
-        throw new TallyError("E_UNIT_GLOB", `unit overlay "${key}" may use "*" only as a whole path segment`, { key });
+        throw coreCodes.error("E_UNIT_GLOB", `unit overlay "${key}" may use "*" only as a whole path segment`, { key });
     }
     const field = GLOB_REJECTED.find((f) => overlay[f] !== undefined);
     if (field !== undefined) {
-        throw new TallyError("E_UNIT_GLOB", `unit overlay "${key}" cannot set "${field}" on a glob key`, { key, field });
+        throw coreCodes.error("E_UNIT_GLOB", `unit overlay "${key}" cannot set "${field}" on a glob key`, { key, field });
     }
     return segments;
 };
@@ -46,7 +46,7 @@ const applyOverlay = (entry, { release, tags, initialVersion, ...overlay }) => {
 export const normalizeRoot = (root) => {
     const segments = root.split("/");
     if (root.startsWith("/") || segments.includes("..")) {
-        throw new TallyError("E_ROOT_INVALID", `root "${root}" must be repo-relative without ".." segments`, { root });
+        throw coreCodes.error("E_ROOT_INVALID", `root "${root}" must be repo-relative without ".." segments`, { root });
     }
     return segments.filter((s) => s !== "" && s !== ".").join("/") || ".";
 };
@@ -67,7 +67,7 @@ export const discoverUnits = async (active, env, warnings = []) => {
             const root = normalizeRoot(draft.root);
             const prior = byRoot.get(root);
             if (prior) {
-                throw new TallyError("E_DUPLICATE_ROOT", `root "${root}" is discovered by "${prior.plugin}" and "${plugin.name}"`, { root, plugins: [prior.plugin, plugin.name] });
+                throw coreCodes.error("E_DUPLICATE_ROOT", `root "${root}" is discovered by "${prior.plugin}" and "${plugin.name}"`, { root, plugins: [prior.plugin, plugin.name] });
             }
             byRoot.set(root, {
                 plugin: plugin.name,
@@ -82,7 +82,7 @@ export const discoverUnits = async (active, env, warnings = []) => {
         const root = normalizeRoot(key);
         const invalid = overlay.tags?.find((t) => !UNIT_TAG.test(t));
         if (invalid !== undefined) {
-            throw new TallyError("E_UNIT_TAG", `tag "${invalid}" of unit at "${root}" must match ${UNIT_TAG.source}`, { tag: invalid, root });
+            throw coreCodes.error("E_UNIT_TAG", `tag "${invalid}" of unit at "${root}" must match ${UNIT_TAG.source}`, { tag: invalid, root });
         }
         if (root.includes("*")) {
             globs.push([key, globSegments(key, root, overlay), overlay]);
@@ -102,10 +102,7 @@ export const discoverUnits = async (active, env, warnings = []) => {
     for (const [key, segments, overlay] of globs) {
         const matched = [...byRoot.entries()].filter(([root]) => globMatches(segments, root));
         if (matched.length === 0) {
-            warnings.push({
-                code: "W_UNIT_GLOB_UNMATCHED",
-                message: `unit overlay "${key}" matches no unit`,
-            });
+            warnings.push(coreCodes.warning("W_UNIT_GLOB_UNMATCHED", `unit overlay "${key}" matches no unit`));
         }
         for (const [, entry] of matched) {
             applyOverlay(entry, overlay);
@@ -118,11 +115,11 @@ export const discoverUnits = async (active, env, warnings = []) => {
     for (const entry of byRoot.values()) {
         const { id, root } = entry.draft;
         if (!UNIT_ID.test(id)) {
-            throw new TallyError("E_UNIT_ID", `unit id "${id}" at "${root}" must match ${UNIT_ID.source}`, { id, root, plugin: entry.plugin });
+            throw coreCodes.error("E_UNIT_ID", `unit id "${id}" at "${root}" must match ${UNIT_ID.source}`, { id, root, plugin: entry.plugin });
         }
         const prior = byId.get(id);
         if (prior) {
-            throw new TallyError("E_DUPLICATE_UNIT", `unit id "${id}" is used by "${prior.plugin}" at "${prior.draft.root}" and "${entry.plugin}" at "${root}"`, {
+            throw coreCodes.error("E_DUPLICATE_UNIT", `unit id "${id}" is used by "${prior.plugin}" at "${prior.draft.root}" and "${entry.plugin}" at "${root}"`, {
                 id,
                 owners: [
                     { plugin: prior.plugin, root: prior.draft.root },
@@ -132,7 +129,7 @@ export const discoverUnits = async (active, env, warnings = []) => {
         }
         byId.set(id, entry);
         if (root !== "." && !env.fs.exists(root)) {
-            throw new TallyError("E_ROOT_MISSING", `root "${root}" of unit "${id}" does not exist`, { id, root });
+            throw coreCodes.error("E_ROOT_MISSING", `root "${root}" of unit "${id}" does not exist`, { id, root });
         }
     }
     const roots = [...byRoot.keys()].sort(compare);

package/dist/explain.js

@@ -1,11 +1,11 @@
 import { attribution, matcher } from "./attribution.js";
 import { changelogPath } from "./changelog.js";
-import { TallyError } from "./errors.js";
+import { coreCodes } from "./codes.js";
 import { planWithFacts } from "./plan.js";
 /** Explains one unit of the plan of `opts.head`; throws `E_UNIT_UNKNOWN`. */
 export const explainUnit = async (workspace, git, { unit: id, ...opts }) => {
     if (!workspace.units.some((u) => u.id === id)) {
-        throw new TallyError("E_UNIT_UNKNOWN", `unknown unit "${id}"`, {
+        throw coreCodes.error("E_UNIT_UNKNOWN", `unknown unit "${id}"`, {
             unit: id,
         });
     }

package/dist/facts.js

@@ -1,5 +1,5 @@
 import { attribution, matcher } from "./attribution.js";
-import { TallyError } from "./errors.js";
+import { coreCodes } from "./codes.js";
 import { pluginCtx, runHook } from "./plugins.js";
 import { schemeRegistry } from "./schemes.js";
 import { matchUnitTags } from "./tags.js";
@@ -7,7 +7,7 @@ import { compare, uniqueSorted } from "./util.js";
 const instant = (commit) => {
     const time = Date.parse(commit.date);
     if (Number.isNaN(time)) {
-        throw new TallyError("E_GIT_DATE", `commit ${commit.sha} has an invalid committer date "${commit.date}"`, { sha: commit.sha, date: commit.date });
+        throw coreCodes.error("E_GIT_DATE", `commit ${commit.sha} has an invalid committer date "${commit.date}"`, { sha: commit.sha, date: commit.date });
     }
     return time;
 };
@@ -74,11 +74,7 @@ export const collectPlanFacts = async (workspace, git, opts) => {
             const key = `${plugin}\0${id}`;
             if (!known.has(id) && !warned.has(key)) {
                 warned.add(key);
-                warnings.push({
-                    code: "W_UNIT_UNKNOWN",
-                    message: `intent names unknown unit "${id}"`,
-                    plugin,
-                });
+                warnings.push(coreCodes.warning("W_UNIT_UNKNOWN", `intent names unknown unit "${id}"`, { plugin }));
             }
         }
     };

package/dist/floating.js

@@ -1,4 +1,4 @@
-import { TallyError } from "./errors.js";
+import { coreCodes } from "./codes.js";
 import { compileTagFormat } from "./tags.js";
 const TOKEN = /\{([^{}]*)\}/gu;
 const TOKENS = new Set(["id", "major", "minor"]);
@@ -7,7 +7,7 @@ export const validateFloating = (formats) => {
     for (const format of formats) {
         const unknown = [...format.matchAll(TOKEN)].find(([, token]) => !TOKENS.has(token ?? ""));
         if (unknown) {
-            throw new TallyError("E_CONFIG", `floating tag format "${format}" uses unknown token "${unknown[0]}"; use {id}, {major} or {minor}`, { format });
+            throw coreCodes.error("E_CONFIG", `floating tag format "${format}" uses unknown token "${unknown[0]}"; use {id}, {major} or {minor}`, { format });
         }
     }
 };

package/dist/graph.js

@@ -1,4 +1,4 @@
-import { TallyError } from "./errors.js";
+import { coreCodes } from "./codes.js";
 import { compare, uniqueSorted } from "./util.js";
 /** Tarjan's algorithm; components are emitted after everything they reach. */
 const stronglyConnected = (ids, next) => {
@@ -73,11 +73,11 @@ export const buildGraph = (units, drafts) => {
     for (const { from, to, reason, pinned, source } of drafts) {
         for (const id of [from, to]) {
             if (!known.has(id)) {
-                throw new TallyError("E_EDGE_UNKNOWN_UNIT", `edge ${from} -> ${to} from "${source}" names unknown unit "${id}"`, { from, to, source, unit: id });
+                throw coreCodes.error("E_EDGE_UNKNOWN_UNIT", `edge ${from} -> ${to} from "${source}" names unknown unit "${id}"`, { from, to, source, unit: id });
             }
         }
         if (from === to) {
-            throw new TallyError("E_EDGE_SELF", `edge ${from} -> ${to} from "${source}" points to itself`, { from, to, source });
+            throw coreCodes.error("E_EDGE_SELF", `edge ${from} -> ${to} from "${source}" points to itself`, { from, to, source });
         }
         const key = `${from}\n${to}`;
         const edge = merged.get(key);
@@ -115,10 +115,7 @@ export const buildGraph = (units, drafts) => {
     const components = stronglyConnected(ids, dependencies);
     const warnings = components
         .filter((c) => c.length > 1)
-        .map((c) => ({
-        code: "W_CYCLE",
-        message: `dependency cycle: ${cyclePath(c, dependents).join(" -> ")}`,
-    }));
+        .map((c) => coreCodes.warning("W_CYCLE", `dependency cycle: ${cyclePath(c, dependents).join(" -> ")}`));
     return {
         edges,
         dependents,

package/dist/groups.js

@@ -1,4 +1,4 @@
-import { TallyError } from "./errors.js";
+import { coreCodes } from "./codes.js";
 import { compare, uniqueSorted } from "./util.js";
 /**
  * Resolves group members: `units` by id, `tags` to released units with any of
@@ -13,7 +13,7 @@ export const resolveGroups = (units, config, warnings) => {
         const { units: ids = [], tags = [] } = config?.[name] ?? {};
         const unknown = ids.find((id) => !known.has(id));
         if (unknown !== undefined) {
-            throw new TallyError("E_GROUP_UNKNOWN_UNIT", `group "${name}" names unknown unit "${unknown}"`, { group: name, unit: unknown });
+            throw coreCodes.error("E_GROUP_UNKNOWN_UNIT", `group "${name}" names unknown unit "${unknown}"`, { group: name, unit: unknown });
         }
         const members = uniqueSorted([
             ...ids,
@@ -22,16 +22,13 @@ export const resolveGroups = (units, config, warnings) => {
                 .map((u) => u.id),
         ]);
         if (members.length === 0) {
-            warnings.push({
-                code: "W_GROUP_EMPTY",
-                message: `group "${name}" selects no unit`,
-            });
+            warnings.push(coreCodes.warning("W_GROUP_EMPTY", `group "${name}" selects no unit`));
             continue;
         }
         for (const id of members) {
             const other = owner.get(id);
             if (other !== undefined) {
-                throw new TallyError("E_GROUP_OVERLAP", `unit "${id}" is in groups "${other}" and "${name}"`, { unit: id, groups: [other, name] });
+                throw coreCodes.error("E_GROUP_OVERLAP", `unit "${id}" is in groups "${other}" and "${name}"`, { unit: id, groups: [other, name] });
             }
             owner.set(id, name);
         }

package/dist/index.d.ts

@@ -2,6 +2,7 @@
 export declare const version = "0.0.0";
 export type { AffectedDoc, AffectedOptions, AffectedReason, AffectedUnit, BaseSource, } from "./affected.js";
 export type { ChangelogDependency, ChangelogInput } from "./changelog.js";
+export type { CodeDoc, CodeOf, CodeRegistry, ErrorCode, WarningCode, } from "./codes.js";
 export type { ParsedCommit } from "./conventional.js";
 export type { ExplainedChange, ExplainOptions, ReleaseAsFooter, UnitExplanation, } from "./explain.js";
 export type { GroupPlan, Plan, PlanChange, PlanLine, PlanOptions, ReleasedUnit, UnitPlan, } from "./plan.js";
@@ -20,6 +21,7 @@ export type { IntentEntry, Workspace, WorkspaceInput } from "./workspace.js";
 export { computeAffected } from "./affected.js";
 export { maintenanceCut } from "./branches.js";
 export { changelogSection, releaseNotes, renderChangelogSection, updateChangelog, } from "./changelog.js";
+export { coreCodes, defineCodes } from "./codes.js";
 export { CONFIG_FILE } from "./config.js";
 export { conventionalCommits, parseCommit } from "./conventional.js";
 export { discoverUnits } from "./discover.js";

package/dist/index.js

@@ -3,6 +3,7 @@ export const version = "0.0.0";
 export { computeAffected } from "./affected.js";
 export { maintenanceCut } from "./branches.js";
 export { changelogSection, releaseNotes, renderChangelogSection, updateChangelog, } from "./changelog.js";
+export { coreCodes, defineCodes } from "./codes.js";
 export { CONFIG_FILE } from "./config.js";
 export { conventionalCommits, parseCommit } from "./conventional.js";
 export { discoverUnits } from "./discover.js";

package/dist/plan.js

@@ -1,5 +1,6 @@
 import { computeAffected } from "./affected.js";
 import { checkLimits, matchBranch } from "./branches.js";
+import { coreCodes } from "./codes.js";
 import { collectPlanFacts } from "./facts.js";
 import { propagate } from "./propagate.js";
 import { changeLevel, footerOf, reach, releaseAsWarnings, releaseGroup, releaseUnit, unitIntent, } from "./release.js";
@@ -9,18 +10,12 @@ import { validateRelease } from "./validate.js";
 const lineWarnings = (workspace, branch, line) => {
     if (!line) {
         return [
-            {
-                code: "W_NO_BRANCH_RULE",
-                message: `no branch rule matches "${branch}"; versions are null`,
-            },
+            coreCodes.warning("W_NO_BRANCH_RULE", `no branch rule matches "${branch}"; versions are null`),
         ];
     }
     return workspace.units.every((u) => u.version === "none")
         ? [
-            {
-                code: "W_NO_RELEASED_UNITS",
-                message: `branch rule "${line.rule}" matches, but no unit is released`,
-            },
+            coreCodes.warning("W_NO_RELEASED_UNITS", `branch rule "${line.rule}" matches, but no unit is released`),
         ]
         : [];
 };

package/dist/plugin.js

@@ -1,14 +1,14 @@
-import { TallyError } from "./errors.js";
+import { coreCodes } from "./codes.js";
 const PLUGIN_NAME = /^[a-z][a-z0-9-]*$/;
 export const PLUGIN_API_VERSION = 1;
 /** Throws `E_PLUGIN_API` or `E_PLUGIN_NAME` for an unsupported plugin. */
 export const assertPlugin = (plugin) => {
     const name = String(plugin.name);
     if (plugin.apiVersion !== PLUGIN_API_VERSION) {
-        throw new TallyError("E_PLUGIN_API", `plugin "${name}" uses API version ${String(plugin.apiVersion)}, supported is ${String(PLUGIN_API_VERSION)}`, { plugin: name, apiVersion: plugin.apiVersion });
+        throw coreCodes.error("E_PLUGIN_API", `plugin "${name}" uses API version ${String(plugin.apiVersion)}, supported is ${String(PLUGIN_API_VERSION)}`, { plugin: name, apiVersion: plugin.apiVersion });
     }
     if (typeof plugin.name !== "string" || !PLUGIN_NAME.test(plugin.name)) {
-        throw new TallyError("E_PLUGIN_NAME", `plugin name "${name}" must match ${PLUGIN_NAME.source}`, { plugin: name });
+        throw coreCodes.error("E_PLUGIN_NAME", `plugin name "${name}" must match ${PLUGIN_NAME.source}`, { plugin: name });
     }
 };
 /** Validates name and API version, returns the plugin unchanged. */

package/dist/plugins.js

@@ -1,5 +1,5 @@
 import { CORE_PLUGIN } from "./builtin.js";
-import { TallyError } from "./errors.js";
+import { coreCodes } from "./codes.js";
 import { assertPlugin } from "./plugin.js";
 /** Frozen `Ctx` factory; warnings are tagged with the plugin name. */
 export const pluginCtx = (env, warnings) => (name, options) => Object.freeze({
@@ -8,7 +8,7 @@ export const pluginCtx = (env, warnings) => (name, options) => Object.freeze({
     fs: env.fs,
     log: Object.freeze({
         warn: (message) => {
-            warnings.push({ code: "W_PLUGIN", message, plugin: name });
+            warnings.push(coreCodes.warning("W_PLUGIN", message, { plugin: name }));
         },
         debug: (message) => env.debug?.(`${name}: ${message}`),
     }),
@@ -19,13 +19,13 @@ export const activatePlugins = async (env, warnings) => {
     for (const [name, raw] of Object.entries(env.config.plugins)) {
         const plugin = env.plugins.find((p) => p.name === name);
         if (!plugin) {
-            throw new TallyError("E_PLUGIN_UNKNOWN", `unknown plugin "${name}"`, {
+            throw coreCodes.error("E_PLUGIN_UNKNOWN", `unknown plugin "${name}"`, {
                 plugin: name,
             });
         }
         assertPlugin(plugin);
         if (plugin.name === CORE_PLUGIN) {
-            throw new TallyError("E_PLUGIN_NAME", `plugin name "${CORE_PLUGIN}" is reserved for core built-ins`, { plugin: name });
+            throw coreCodes.error("E_PLUGIN_NAME", `plugin name "${CORE_PLUGIN}" is reserved for core built-ins`, { plugin: name });
         }
         const { globalInputs, ...rest } = raw ?? {};
         let options = rest;
@@ -33,7 +33,7 @@ export const activatePlugins = async (env, warnings) => {
             // eslint-disable-next-line no-await-in-loop -- plugins load sequentially in config order
             const result = await plugin.options["~standard"].validate(rest);
             if (result.issues) {
-                throw new TallyError("E_PLUGIN_OPTIONS", `invalid options for plugin "${name}": ${result.issues.map((i) => i.message).join("; ")}`, { plugin: name, issues: result.issues });
+                throw coreCodes.error("E_PLUGIN_OPTIONS", `invalid options for plugin "${name}": ${result.issues.map((i) => i.message).join("; ")}`, { plugin: name, issues: result.issues });
             }
             options = result.value;
         }
@@ -49,6 +49,6 @@ export const runHook = async (plugin, hook, call) => {
     }
     catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
-        throw new TallyError("E_PLUGIN_HOOK", `plugin "${plugin}" failed in ${hook}: ${reason}`, { plugin, hook, error });
+        throw coreCodes.error("E_PLUGIN_HOOK", `plugin "${plugin}" failed in ${hook}: ${reason}`, { plugin, hook, error });
     }
 };

package/dist/release-items.js

@@ -1,4 +1,4 @@
-import { TallyError } from "./errors.js";
+import { coreCodes } from "./codes.js";
 import { releasedEdges } from "./propagate.js";
 import { renderTag } from "./tags.js";
 /** Item of each released unit, by unit id. */
@@ -90,7 +90,7 @@ export const validateReleaseItems = (workspace) => {
     for (const id of workspace.release.releasePr.units.keys()) {
         const item = byUnit.get(id);
         if (item?.kind === "group") {
-            throw new TallyError("E_CONFIG", `unit "${id}" sets releasePr but is in group "${item.name}"; set it on the group`, { unit: id, group: item.name });
+            throw coreCodes.error("E_CONFIG", `unit "${id}" sets releasePr but is in group "${item.name}"; set it on the group`, { unit: id, group: item.name });
         }
     }
     const groups = new Set(workspace.groups.map((g) => g.name));
@@ -99,7 +99,7 @@ export const validateReleaseItems = (workspace) => {
             ? "is also a group name"
             : itemNameProblem(item.name);
         if (problem !== undefined) {
-            throw new TallyError("E_RELEASE_ITEM_NAME", `release item "${item.name}" ${problem}`, { item: item.name });
+            throw coreCodes.error("E_RELEASE_ITEM_NAME", `release item "${item.name}" ${problem}`, { item: item.name });
         }
     }
     const policies = new Map(workspace.units.map((u) => [u.id, u.propagate]));
@@ -114,7 +114,7 @@ export const validateReleaseItems = (workspace) => {
             if (!a || !b || !patch || pr(a) === pr(b)) {
                 continue;
             }
-            throw new TallyError("E_RELEASE_PR_SPLIT_EDGE", `edge "${from}" -> "${to}" propagates a patch between release items "${a.name}" and "${b.name}" in different release PRs`, { from, to, items: [a.name, b.name] });
+            throw coreCodes.error("E_RELEASE_PR_SPLIT_EDGE", `edge "${from}" -> "${to}" propagates a patch between release items "${a.name}" and "${b.name}" in different release PRs`, { from, to, items: [a.name, b.name] });
         }
     }
 };

package/dist/release.js

@@ -1,3 +1,4 @@
+import { coreCodes } from "./codes.js";
 import { normalizeRoot } from "./discover.js";
 import { compare, maxLevel, uniqueSorted } from "./util.js";
 const DEFAULT_TYPES = {
@@ -54,21 +55,13 @@ const pickReleaseAs = (input, warnings) => {
                 ? `is not a ${unit.scheme} version`
                 : releaseAsProblem(scheme, version, from);
             if (problem !== undefined || version === undefined) {
-                warnings.push({
-                    code: "W_RELEASE_AS_INVALID",
-                    message: `unit "${unit.id}": Release-As "${raw}"${at(sha)} ${problem ?? ""}; ignored`,
-                    unit: unit.id,
-                });
+                warnings.push(coreCodes.warning("W_RELEASE_AS_INVALID", `unit "${unit.id}": Release-As "${raw}"${at(sha)} ${problem ?? ""}; ignored`, { unit: unit.id }));
             }
             else if (!winner) {
                 winner = { ...(sha === undefined ? {} : { sha }), raw, version };
             }
             else if (scheme.compare(version, winner.version) !== 0) {
-                warnings.push({
-                    code: "W_RELEASE_AS_CONFLICT",
-                    message: `unit "${unit.id}": Release-As "${winner.raw}"${at(winner.sha)} wins over "${raw}"${at(sha)}`,
-                    unit: unit.id,
-                });
+                warnings.push(coreCodes.warning("W_RELEASE_AS_CONFLICT", `unit "${unit.id}": Release-As "${winner.raw}"${at(winner.sha)} wins over "${raw}"${at(sha)}`, { unit: unit.id }));
             }
         }
     }
@@ -119,11 +112,7 @@ const initialBelowPrerelease = (scheme, initial, facts) => {
     return scheme.compare(initial, version) > 0
         ? []
         : [
-            {
-                code: "W_INITIAL_BELOW_PRERELEASE",
-                message: `unit "${facts.id}": initial version ${scheme.format(initial)} does not exceed prerelease tag "${highest.name}"`,
-                unit: facts.id,
-            },
+            coreCodes.warning("W_INITIAL_BELOW_PRERELEASE", `unit "${facts.id}": initial version ${scheme.format(initial)} does not exceed prerelease tag "${highest.name}"`, { unit: facts.id }),
         ];
 };
 /** Normalized value of the first valid Release-As of a commit. */
@@ -231,11 +220,7 @@ export const releaseAsWarnings = (units, ranges) => {
     const released = new Set(units.filter((u) => u.version !== "none").map((u) => u.id));
     const warnings = new Map();
     const warn = (code, message, unit) => {
-        warnings.set(`${code}\0${message}`, {
-            code,
-            message,
-            ...(unit === undefined ? {} : { unit }),
-        });
+        warnings.set(`${code}\0${message}`, coreCodes.warning(code, message, unit === undefined ? {} : { unit }));
     };
     for (const { changes } of ranges) {
         for (const { change, units: owners } of changes) {

package/dist/released.js

@@ -1,3 +1,4 @@
+import { coreCodes } from "./codes.js";
 import { renderFloatingTags } from "./floating.js";
 import { schemeRegistry } from "./schemes.js";
 import { matchUnitTags } from "./tags.js";
@@ -83,18 +84,11 @@ export const withReleased = async (workspace, plan, { git }) => {
         ...(omitted === 0
             ? []
             : [
-                {
-                    code: "W_RELEASED_NO_BASE",
-                    message: "the build base is unknown; released leaves out earlier releases on the first-parent chain",
-                },
+                coreCodes.warning("W_RELEASED_NO_BASE", "the build base is unknown; released leaves out earlier releases on the first-parent chain"),
             ]),
         ...released
             .filter((r) => r.releaseSha === head && r.catchUp)
-            .map((r) => ({
-            code: "W_RELEASE_NOT_BUILT",
-            message: `release ${r.tag} is at HEAD but unit ${r.id} is not in the build set; it is listed as a catch-up`,
-            unit: r.id,
-        })),
+            .map((r) => coreCodes.warning("W_RELEASE_NOT_BUILT", `release ${r.tag} is at HEAD but unit ${r.id} is not in the build set; it is listed as a catch-up`, { unit: r.id })),
     ];
     return { ...plan, released, warnings: [...plan.warnings, ...warnings] };
 };

package/dist/schemes.js

@@ -1,5 +1,5 @@
 import { corePlugin } from "./builtin.js";
-import { TallyError } from "./errors.js";
+import { coreCodes } from "./codes.js";
 /** Schemes of core and the given plugins, in that order. */
 export const collectSchemes = (active) => [corePlugin, ...active.map((a) => a.plugin)].flatMap((plugin) => Object.entries(plugin.schemes ?? {}).map(([name, scheme]) => ({
     plugin: plugin.name,
@@ -13,7 +13,7 @@ export const schemeRegistry = (list) => {
     for (const { plugin, name, scheme } of list) {
         const owner = owners.get(name);
         if (owner !== undefined) {
-            throw new TallyError("E_SCHEME_CLASH", `scheme "${name}" is registered by "${owner}" and "${plugin}"`, { scheme: name, plugins: [owner, plugin] });
+            throw coreCodes.error("E_SCHEME_CLASH", `scheme "${name}" is registered by "${owner}" and "${plugin}"`, { scheme: name, plugins: [owner, plugin] });
         }
         owners.set(name, plugin);
         registry.set(name, scheme);

package/dist/semver.js

@@ -1,5 +1,5 @@
 import lib from "semver";
-import { TallyError } from "./errors.js";
+import { coreCodes } from "./codes.js";
 const format = (v) => {
     const pre = v.prerelease.length > 0 ? `-${v.prerelease.join(".")}` : "";
     const build = v.build.length > 0 ? `+${v.build.join(".")}` : "";
@@ -23,7 +23,7 @@ const parse = (raw) => {
 const mustParse = (raw) => {
     const v = parse(raw);
     if (!v) {
-        throw new TallyError("E_VERSION_INVALID", `invalid version "${raw}"`, {
+        throw coreCodes.error("E_VERSION_INVALID", `invalid version "${raw}"`, {
             version: raw,
         });
     }
@@ -46,7 +46,7 @@ export const semver = {
         const raw = `${[major, minor, patch].join(".")}-${ctx.channel}.${n}`;
         const v = parse(raw);
         if (!v) {
-            throw new TallyError("E_CHANNEL_INVALID", `channel "${ctx.channel}" does not form a valid prerelease`, { channel: ctx.channel });
+            throw coreCodes.error("E_CHANNEL_INVALID", `channel "${ctx.channel}" does not form a valid prerelease`, { channel: ctx.channel });
         }
         return v;
     },

package/dist/tags.js

@@ -1,12 +1,12 @@
-import { TallyError } from "./errors.js";
+import { coreCodes } from "./codes.js";
 import { compare } from "./util.js";
 const SPECIAL = /[\\^$.*+?()[\]{}|/]/gu;
-const overlap = (units, detail) => new TallyError("E_TAG_FORMAT_OVERLAP", `released units "${units.join('", "')}" share tags (${Object.values(detail).join(", ")})`, { units, ...detail });
+const overlap = (units, detail) => coreCodes.error("E_TAG_FORMAT_OVERLAP", `released units "${units.join('", "')}" share tags (${Object.values(detail).join(", ")})`, { units, ...detail });
 /** Compiles `format`; literal parts and `{id}` are escaped, `{version}` must occur once. */
 export const compileTagFormat = (format, unitId) => {
     const parts = format.split("{version}");
     if (parts.length !== 2) {
-        throw new TallyError("E_TAG_FORMAT", `tag format "${format}" of unit "${unitId}" must contain {version} exactly once`, { unit: unitId, format });
+        throw coreCodes.error("E_TAG_FORMAT", `tag format "${format}" of unit "${unitId}" must contain {version} exactly once`, { unit: unitId, format });
     }
     const literal = (part) => part.replaceAll("{id}", unitId).replace(SPECIAL, "\\$&");
     const re = new RegExp(`^${literal(parts[0] ?? "")}(.+)${literal(parts[1] ?? "")}$`, "u");
@@ -30,7 +30,7 @@ export const matchUnitTags = (units, tags, schemes) => {
         .map((unit) => {
         const scheme = schemes.get(unit.scheme);
         if (!scheme) {
-            throw new TallyError("E_SCHEME_UNKNOWN", `unit "${unit.id}" uses unknown scheme "${unit.scheme}"`, { unit: unit.id, scheme: unit.scheme });
+            throw coreCodes.error("E_SCHEME_UNKNOWN", `unit "${unit.id}" uses unknown scheme "${unit.scheme}"`, { unit: unit.id, scheme: unit.scheme });
         }
         return {
             unit,
@@ -86,11 +86,7 @@ export const noMatchingTag = (units, matched, tagNames) => {
             return [];
         }
         return [
-            {
-                code: "W_NO_MATCHING_TAG",
-                message: `released unit "${m.id}" has no tag matching "${unit.tagFormat.replaceAll("{id}", m.id)}", but "${similar}" contains its id`,
-                unit: m.id,
-            },
+            coreCodes.warning("W_NO_MATCHING_TAG", `released unit "${m.id}" has no tag matching "${unit.tagFormat.replaceAll("{id}", m.id)}", but "${similar}" contains its id`, { unit: m.id }),
         ];
     });
 };

package/dist/validate.js

@@ -1,5 +1,5 @@
 import { validateBranches } from "./branches.js";
-import { TallyError } from "./errors.js";
+import { coreCodes } from "./codes.js";
 import { validateFloating } from "./floating.js";
 import { validateReleaseItems } from "./release-items.js";
 import { schemeRegistry } from "./schemes.js";
@@ -20,23 +20,23 @@ export const validateRelease = (workspace) => {
         }
         const scheme = schemes.get(unit.scheme);
         if (!scheme) {
-            throw new TallyError("E_SCHEME_UNKNOWN", `unit "${unit.id}" uses unknown scheme "${unit.scheme}"`, { unit: unit.id, scheme: unit.scheme });
+            throw coreCodes.error("E_SCHEME_UNKNOWN", `unit "${unit.id}" uses unknown scheme "${unit.scheme}"`, { unit: unit.id, scheme: unit.scheme });
         }
         compileTagFormat(unit.tagFormat, unit.id);
         if (unit.initialVersion !== null &&
             scheme.parse(unit.initialVersion) === undefined) {
-            throw new TallyError("E_INITIAL_VERSION", `initial version "${unit.initialVersion}" of unit "${unit.id}" is not a ${unit.scheme} version`, { unit: unit.id, version: unit.initialVersion });
+            throw coreCodes.error("E_INITIAL_VERSION", `initial version "${unit.initialVersion}" of unit "${unit.id}" is not a ${unit.scheme} version`, { unit: unit.id, version: unit.initialVersion });
         }
     }
     const units = new Map(workspace.units.map((u) => [u.id, u]));
     for (const { name, members } of workspace.groups) {
         const unreleased = members.find((id) => units.get(id)?.version === "none");
         if (unreleased !== undefined) {
-            throw new TallyError("E_GROUP_NOT_RELEASED", `group "${name}" names unit "${unreleased}", which is not released`, { group: name, unit: unreleased });
+            throw coreCodes.error("E_GROUP_NOT_RELEASED", `group "${name}" names unit "${unreleased}", which is not released`, { group: name, unit: unreleased });
         }
         const schemeNames = uniqueSorted(members.map((id) => units.get(id)?.scheme ?? ""));
         if (schemeNames.length > 1) {
-            throw new TallyError("E_GROUP_SCHEME", `members of group "${name}" use different schemes: ${schemeNames.join(", ")}`, { group: name, schemes: schemeNames });
+            throw coreCodes.error("E_GROUP_SCHEME", `members of group "${name}" use different schemes: ${schemeNames.join(", ")}`, { group: name, schemes: schemeNames });
         }
     }
     validateBranches(workspace.release.branches);
@@ -53,7 +53,7 @@ export const validateRelease = (workspace) => {
                 ? `names unknown group "${group}"`
                 : undefined;
         if (problem !== undefined) {
-            throw new TallyError("E_BRANCH_RULE", `branch rule "${rule.name}" ${problem}`, {
+            throw coreCodes.error("E_BRANCH_RULE", `branch rule "${rule.name}" ${problem}`, {
                 rule: rule.name,
                 ...(unit === null ? { group } : { unit }),
             });

package/dist/version-files.js

@@ -1,6 +1,6 @@
 import { changelogPath, changelogSection, updateChangelog, } from "./changelog.js";
+import { coreCodes } from "./codes.js";
 import { normalizeRoot } from "./discover.js";
-import { TallyError } from "./errors.js";
 import { runHook } from "./plugins.js";
 import { schemeRegistry } from "./schemes.js";
 const TOKEN = /\{([^{}]*)\}/gu;
@@ -9,7 +9,7 @@ const CORE_TOKENS = ["major", "minor", "patch"];
 const VERSION = "\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?";
 const ALNUM = /[0-9A-Za-z]/u;
 const escape = (text) => text.replace(SPECIAL, "\\$&");
-const configError = (pattern, unit, problem) => new TallyError("E_CONFIG", `version file pattern "${pattern}" of unit "${unit}" ${problem}`, { unit, pattern });
+const configError = (pattern, unit, problem) => coreCodes.error("E_CONFIG", `version file pattern "${pattern}" of unit "${unit}" ${problem}`, { unit, pattern });
 /**
  * Compiles a template pattern: literal parts escaped, `{id}` literal, version
  * tokens captured. An edge that is a token or an alphanumeric literal must not
@@ -110,7 +110,7 @@ const applyTemplate = (content, { pattern, unit, from, next, scheme, }) => {
 };
 /** Repo-relative template file; `E_CONFIG` for `.`, absolute or `..` paths. */
 const templateFile = (file, unit) => {
-    const invalid = () => new TallyError("E_CONFIG", `version file "${file}" of unit "${unit}" must be a repo-relative file without ".." segments`, { unit, file });
+    const invalid = () => coreCodes.error("E_CONFIG", `version file "${file}" of unit "${unit}" must be a repo-relative file without ".." segments`, { unit, file });
     let path;
     try {
         path = normalizeRoot(file);
@@ -144,7 +144,7 @@ export const versionFileClaims = async (workspace) => {
         for (const { path } of list) {
             const prior = claims.get(path);
             if (prior !== undefined) {
-                throw new TallyError("E_VERSION_FILE_CLAIM", `version file "${path}" is claimed by units "${prior}" and "${id}"`, { path, units: [prior, id] });
+                throw coreCodes.error("E_VERSION_FILE_CLAIM", `version file "${path}" is claimed by units "${prior}" and "${id}"`, { path, units: [prior, id] });
             }
             claims.set(path, id);
         }
@@ -154,7 +154,7 @@ export const versionFileClaims = async (workspace) => {
             const path = templateFile(file, id);
             const owner = claims.get(path);
             if (owner !== undefined) {
-                throw new TallyError("E_VERSION_FILE_CLAIM", `version file template of unit "${id}" targets "${path}", a version file of unit "${owner}"`, { path, units: [owner, id] });
+                throw coreCodes.error("E_VERSION_FILE_CLAIM", `version file template of unit "${id}" targets "${path}", a version file of unit "${owner}"`, { path, units: [owner, id] });
             }
         }
     }
@@ -183,7 +183,7 @@ export const releaseFiles = async (workspace, plan, opts) => {
     const required = (path, unit) => {
         const content = read(path);
         if (content === undefined) {
-            throw new TallyError("E_VERSION_FILE_MISSING", `version file "${path}" of unit "${unit}" does not exist`, { path, unit });
+            throw coreCodes.error("E_VERSION_FILE_MISSING", `version file "${path}" of unit "${unit}" does not exist`, { path, unit });
         }
         return content;
     };
@@ -219,11 +219,7 @@ export const releaseFiles = async (workspace, plan, opts) => {
                 });
                 files.set(file, result.content);
                 if (!result.hit) {
-                    warnings.push({
-                        code: "W_VERSION_FILE_NO_MATCH",
-                        message: `version file pattern "${pattern}" of unit "${id}" matches nothing in "${file}"`,
-                        unit: id,
-                    });
+                    warnings.push(coreCodes.warning("W_VERSION_FILE_NO_MATCH", `version file pattern "${pattern}" of unit "${id}" matches nothing in "${file}"`, { unit: id }));
                 }
             }
             const section = changelogSection(workspace, plan, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyrelease/core",
-  "version": "0.4.2-beta.6",
+  "version": "0.5.0-beta.14",
   "description": "Pure planning core of tallyrelease",
   "repository": {
     "type": "git",