@tallyrelease/core 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.2.0](https://github.com/abinnovision/tally-release/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))
+
 ## [0.1.1](https://github.com/abinnovision/tally-release/compare/core-v0.1.0...core-v0.1.1) (2026-10-15)
 
 

package/dist/affected.d.ts

@@ -2,14 +2,14 @@ import type { Warning } from "./errors.js";
 import type { GitReader } from "./plugin.js";
 import type { Workspace } from "./workspace.js";
 export type BaseSource = "cli" | "push-before" | "pr-merge-base" | "merge-group" | "forge-last-success" | "local-merge-base" | "none";
-export type AffectedReason = "direct" | "dependent" | "global" | "all";
+export type AffectedReason = "direct" | "dependent" | "global" | "all" | "group";
 export interface AffectedUnit {
     id: string;
     /** Unit root, `.` for the repo root. */
     path: string;
     plugin: string;
     reason: AffectedReason;
-    /** Affected direct dependencies that made a dependent affected. */
+    /** Affected direct dependencies of a dependent, or affected mates of a group member. */
     via: string[];
     /** True unless the unit's version is `none`. */
     released: boolean;

package/dist/affected.js

@@ -49,20 +49,31 @@ export const computeAffected = async (workspace, git, opts) => {
     if (hits.length > 0) {
         return doc(everything("global"), { all: true, globalInputs: hits }, uniqueSorted(unattributed));
     }
+    const mates = new Map(workspace.groups.flatMap((g) => g.members.map((id) => [id, g.members.filter((m) => m !== id)])));
     const affected = new Set(direct);
     const queue = [...direct];
     for (const id of queue) {
-        for (const dependent of graph.dependents.get(id) ?? []) {
-            if (!affected.has(dependent)) {
-                affected.add(dependent);
-                queue.push(dependent);
+        for (const next of [
+            ...(graph.dependents.get(id) ?? []),
+            ...(mates.get(id) ?? []),
+        ]) {
+            if (!affected.has(next)) {
+                affected.add(next);
+                queue.push(next);
             }
         }
     }
+    // Precedence: direct, then dependent, then group.
     const result = units
         .filter((u) => affected.has(u.id))
-        .map((u) => direct.has(u.id)
-        ? entry(u, "direct", [])
-        : entry(u, "dependent", (graph.dependencies.get(u.id) ?? []).filter((d) => affected.has(d))));
+        .map((u) => {
+        if (direct.has(u.id)) {
+            return entry(u, "direct", []);
+        }
+        const deps = (graph.dependencies.get(u.id) ?? []).filter((d) => affected.has(d));
+        return deps.length > 0
+            ? entry(u, "dependent", deps)
+            : entry(u, "group", (mates.get(u.id) ?? []).filter((m) => affected.has(m)));
+    });
     return doc(result, { all: false, globalInputs: [] }, uniqueSorted(unattributed));
 };

package/dist/branches.d.ts

@@ -0,0 +1,70 @@
+import type { BumpLevel } from "./plugin.js";
+import type { BranchRule } from "./release.js";
+/** The branch rule matching the planned branch. */
+export interface Line {
+    rule: string;
+    kind: "default" | "maintenance";
+    /** Rendered with the rule's captures. */
+    channel: string | null;
+    /** Maintenance rules: `minor` for `{major}`, `patch` with `{minor}`. */
+    maxBump: "minor" | "patch" | null;
+    absolute: {
+        unit: string | null;
+        group: string | null;
+        major: number;
+        minor?: number;
+    } | null;
+}
+/**
+ * Validates rule names, `unit`/`group` and channels: `E_BRANCH_RULE`, `E_CHANNEL_WILDCARD`,
+ * `E_CHANNEL_INVALID` and `E_CHANNEL_DUPLICATE`.
+ */
+export declare const validateBranches: (rules: readonly BranchRule[]) => void;
+/**
+ * The first rule matching `branch`, or null. Rules must be validated. A
+ * maintenance rule with `{major}` gets an absolute check for its `unit` or
+ * `group`, else for `single`, the repo's only release item.
+ */
+export declare const matchBranch: (rules: readonly BranchRule[], branch: string, single?: ReleaseItem | null) => Line | null;
+/** An ungrouped released unit or a fixed group. */
+export interface ReleaseItem {
+    unit: string | null;
+    group: string | null;
+}
+/** Major and minor of a version. */
+export interface Core {
+    major: number;
+    minor: number;
+}
+/** A formatted version with its core. */
+export interface CoreVersion extends Core {
+    version: string;
+}
+/** A commit that contributes to a release item's `next`. */
+export interface LimitCommit {
+    sha?: string;
+    subject: string;
+    /** Null for a Release-As only commit. */
+    level: BumpLevel | null;
+    /** Absorbed unit the change came through. */
+    via?: string;
+    /** The Release-As value it sets. */
+    releaseAs?: CoreVersion;
+}
+export interface LimitItem extends ReleaseItem {
+    /** Null on a first release. */
+    from: CoreVersion | null;
+    /** Null without a pending release. */
+    next: CoreVersion | null;
+    commits: readonly LimitCommit[];
+}
+/**
+ * Maintenance limits: `E_CAP_BASE` when the absolute item's `from` is off the
+ * rule's line, `E_CAP` when a release item's `next` leaves the line of its
+ * `from`. First releases are not checked. `implicit`: the absolute target is
+ * the only release item, not named by the rule.
+ */
+export declare const checkLimits: (line: Line | null, items: readonly LimitItem[], { branch, implicit }: {
+    branch: string;
+    implicit: boolean;
+}) => void;

package/dist/branches.js

@@ -0,0 +1,168 @@
+import { TallyError } from "./errors.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}`, {
+    rule: rule.name,
+});
+/** Anchored regex of a rule name; throws `E_BRANCH_RULE`. */
+const compileRule = (rule) => {
+    const { name } = rule;
+    if (name === "") {
+        throw ruleError(rule, "has an empty name");
+    }
+    const tokens = name.match(/\{[^{}]*\}/gu) ?? [];
+    const unknown = tokens.find((t) => t !== "{major}" && t !== "{minor}");
+    if (unknown !== undefined) {
+        throw ruleError(rule, `uses unknown token ${unknown}`);
+    }
+    if (new Set(tokens).size !== tokens.length) {
+        throw ruleError(rule, "repeats a token");
+    }
+    if (tokens.includes("{minor}") && !tokens.includes("{major}")) {
+        throw ruleError(rule, "uses {minor} without {major}");
+    }
+    if (/[{}]/u.test(name.replace(PART, ""))) {
+        throw ruleError(rule, "has an unbalanced brace");
+    }
+    let source = "";
+    let last = 0;
+    for (const match of name.matchAll(PART)) {
+        source += name.slice(last, match.index).replace(SPECIAL, "\\$&");
+        source += match[1] === undefined ? ".*" : `(?<${match[1]}>0|[1-9]\\d*)`;
+        last = match.index + match[0].length;
+    }
+    source += name.slice(last).replace(SPECIAL, "\\$&");
+    return new RegExp(`^${source}$`, "u");
+};
+const within = (limit, from, next) => next.major === from.major && (limit === "minor" || next.minor === from.minor);
+const itemLabel = ({ unit, group }) => unit === null ? `group "${group ?? ""}"` : `unit "${unit}"`;
+const itemDetails = ({ unit, group }) => unit === null ? { group } : { unit };
+/** `c3 web v2 (major)`, with `via` and Release-As when set. */
+const commitLabel = ({ sha, subject, level, via, releaseAs }) => {
+    const notes = [
+        level === null
+            ? undefined
+            : via === undefined
+                ? level
+                : `${level} via ${via}`,
+        releaseAs && `Release-As ${releaseAs.version}`,
+    ].filter((n) => n !== undefined);
+    return `${sha === undefined ? subject : `${sha} ${subject}`} (${notes.join(", ")})`;
+};
+/**
+ * Validates rule names, `unit`/`group` and channels: `E_BRANCH_RULE`, `E_CHANNEL_WILDCARD`,
+ * `E_CHANNEL_INVALID` and `E_CHANNEL_DUPLICATE`.
+ */
+export const validateBranches = (rules) => {
+    const channels = new Map();
+    for (const rule of rules) {
+        compileRule(rule);
+        if (rule.unit !== null && rule.group !== null) {
+            throw ruleError(rule, "sets both unit and group");
+        }
+        if ((rule.unit !== null || rule.group !== null) &&
+            (rule.line !== "maintenance" || !rule.name.includes("{major}"))) {
+            throw ruleError(rule, "sets unit or group without being a maintenance rule with {major}");
+        }
+        const { channel } = rule;
+        if (channel === null) {
+            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 });
+        }
+        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 });
+        }
+        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] });
+        }
+        channels.set(channel, rule.name);
+    }
+};
+/**
+ * The first rule matching `branch`, or null. Rules must be validated. A
+ * maintenance rule with `{major}` gets an absolute check for its `unit` or
+ * `group`, else for `single`, the repo's only release item.
+ */
+export const matchBranch = (rules, branch, single = null) => {
+    for (const rule of rules) {
+        const match = compileRule(rule).exec(branch);
+        if (!match) {
+            continue;
+        }
+        const captures = match.groups ?? {};
+        const { major, minor } = captures;
+        const capped = rule.line === "maintenance" && major !== undefined;
+        const target = rule.unit !== null || rule.group !== null
+            ? { unit: rule.unit, group: rule.group }
+            : single;
+        return {
+            rule: rule.name,
+            kind: rule.line,
+            channel: rule.channel?.replace(/\{(major|minor)\}/gu, (_, token) => captures[token] ?? "") ?? null,
+            maxBump: !capped ? null : minor === undefined ? "minor" : "patch",
+            absolute: !capped || target === null
+                ? null
+                : {
+                    ...target,
+                    major: Number(major),
+                    ...(minor === undefined ? {} : { minor: Number(minor) }),
+                },
+        };
+    }
+    return null;
+};
+/**
+ * Maintenance limits: `E_CAP_BASE` when the absolute item's `from` is off the
+ * rule's line, `E_CAP` when a release item's `next` leaves the line of its
+ * `from`. First releases are not checked. `implicit`: the absolute target is
+ * the only release item, not named by the rule.
+ */
+export const checkLimits = (line, items, { branch, implicit }) => {
+    const limit = line?.maxBump ?? null;
+    if (line === null || limit === null) {
+        return;
+    }
+    const { absolute } = line;
+    const target = items.find((i) => absolute !== null &&
+        i.unit === absolute.unit &&
+        i.group === absolute.group);
+    if (absolute !== null && target?.from) {
+        const { from } = target;
+        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)`, {
+                ...itemDetails(target),
+                branch,
+                rule: line.rule,
+                major: absolute.major,
+                ...(absolute.minor === undefined ? {} : { minor: absolute.minor }),
+                from: from.version,
+            });
+        }
+    }
+    for (const item of items) {
+        const { from, next } = item;
+        if (from === null || next === null || within(limit, from, next)) {
+            continue;
+        }
+        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}`}`, {
+            ...itemDetails(item),
+            rule: line.rule,
+            limit,
+            from: from.version,
+            next: next.version,
+            commits,
+        });
+    }
+};

package/dist/builtin.d.ts

@@ -0,0 +1,5 @@
+import type { Plugin } from "./plugin.js";
+/** Plugin name reserved for core built-ins. */
+export declare const CORE_PLUGIN = "core";
+/** Core built-ins, registered before every configured plugin. */
+export declare const corePlugin: Plugin;

package/dist/builtin.js

@@ -0,0 +1,12 @@
+import { conventionalCommits } from "./conventional.js";
+import { PLUGIN_API_VERSION } from "./plugin.js";
+import { semver } from "./semver.js";
+/** Plugin name reserved for core built-ins. */
+export const CORE_PLUGIN = "core";
+/** Core built-ins, registered before every configured plugin. */
+export const corePlugin = {
+    apiVersion: PLUGIN_API_VERSION,
+    name: CORE_PLUGIN,
+    schemes: { semver },
+    intent: [conventionalCommits],
+};

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import type { Propagate, VersionSource } from "./plugin.js";
+import type { BumpLevel, Propagate, VersionSource } from "./plugin.js";
 /** Config overlay for the unit at a root; creates a config-only unit if none is discovered. */
 export interface UnitOverlay {
     id?: string;
@@ -13,6 +13,38 @@ export interface UnitOverlay {
     propagate?: Propagate;
     /** Labels for filtering, each matching `/^[A-Za-z0-9._-]+$/`. */
     tags?: string[];
+    /** First release version, parsed by the unit's scheme. */
+    initialVersion?: string;
+}
+/** A branch rule; the first rule whose `name` matches the branch wins. */
+export interface BranchConfig {
+    /** Pattern with `*`, `{major}` and `{minor}`. */
+    name: string;
+    line: "default" | "maintenance";
+    /** Prerelease channel, may use the `{major}`/`{minor}` captures of `name`. */
+    channel?: string;
+    /** Maintenance rules: the unit of the absolute check; excludes `group`. */
+    unit?: string;
+    /** Maintenance rules: the group of the absolute check; excludes `unit`. */
+    group?: string;
+}
+export interface BumpsConfig {
+    /** Commit type to level, merged over the defaults. */
+    types?: Record<string, BumpLevel>;
+    /** Levels used while the major version is 0. */
+    preMajor?: {
+        breaking?: BumpLevel;
+        feat?: BumpLevel;
+    };
+    /** Level of changes absorbed from unreleased dependencies, default `patch`. */
+    absorbed?: "patch" | "minor";
+}
+/** A fixed group: members share one version. Selections are unioned. */
+export interface GroupConfig {
+    /** Member unit ids. */
+    units?: string[];
+    /** Selects released units with any of these tags. */
+    tags?: string[];
 }
 export interface DepConfig {
     from: string;
@@ -31,12 +63,17 @@ export interface TallyConfig {
         release?: boolean;
         tagFormat?: string;
         propagate?: Propagate;
+        initialVersion?: string;
     };
     /** Overlays keyed by unit root. */
     units?: Record<string, UnitOverlay>;
     deps?: DepConfig[];
     ignore?: string[];
     globalInputs?: string[];
+    branches?: BranchConfig[];
+    bumps?: BumpsConfig;
+    /** Fixed groups by name; names follow the unit id pattern. */
+    groups?: Record<string, GroupConfig>;
 }
 /** Global input owned by core. */
 export declare const CONFIG_FILE = "tallyrelease.yaml";

package/dist/conventional.d.ts

@@ -0,0 +1,20 @@
+import type { IntentSource } from "./plugin.js";
+export interface ParsedCommit {
+    /** Empty for a non-conventional header. */
+    type: string;
+    scope: string | undefined;
+    breaking: boolean;
+    subject: string;
+    body: string | undefined;
+    pr: number | undefined;
+    /** Lowercased footer key to values in message order. */
+    footers: Record<string, string[]>;
+}
+/**
+ * Parses a commit message per Conventional Commits. The footer block starts at
+ * the first paragraph whose first line is `token: value` or `token #value`; a
+ * footer value runs until the next such line.
+ */
+export declare const parseCommit: (message: string) => ParsedCommit;
+/** Maps each commit to exactly one commit-derived Change. */
+export declare const conventionalCommits: IntentSource;

package/dist/conventional.js

@@ -0,0 +1,90 @@
+const HEADER = /^(?<type>[A-Za-z][\w-]*)(?:\((?<scope>[^()]*)\))?(?<bang>!)?: (?<subject>.+)$/u;
+const PR = /\s*\(#(?<pr>\d+)\)$/u;
+const FOOTER = /^(?<key>BREAKING[ -]CHANGE|[A-Za-z][A-Za-z0-9-]*)(?:: | #)(?<value>.*)$/u;
+const QUALIFIED = /^(?<unit>[A-Za-z0-9._-]+)@(?<version>.+)$/u;
+const BREAKING = new Set(["BREAKING CHANGE", "BREAKING-CHANGE"]);
+const releaseAs = (value) => {
+    const version = value.split("\n")[0]?.trim() ?? "";
+    const match = QUALIFIED.exec(version)?.groups;
+    return match?.["unit"] !== undefined && match["version"] !== undefined
+        ? { unit: match["unit"], version: match["version"] }
+        : { version };
+};
+const withPr = (text) => {
+    const pr = PR.exec(text)?.groups?.["pr"];
+    return pr === undefined
+        ? { subject: text, pr: undefined }
+        : { subject: text.replace(PR, ""), pr: Number(pr) };
+};
+/**
+ * Parses a commit message per Conventional Commits. The footer block starts at
+ * the first paragraph whose first line is `token: value` or `token #value`; a
+ * footer value runs until the next such line.
+ */
+export const parseCommit = (message) => {
+    const [first = "", ...rest] = message.replace(/\r\n?/gu, "\n").split("\n");
+    const header = first.trim();
+    let start = rest.findIndex((line, i) => FOOTER.test(line) && (i === 0 || rest[i - 1]?.trim() === ""));
+    start = start === -1 ? rest.length : start;
+    const footers = new Map();
+    let current;
+    let breaking = false;
+    for (const line of rest.slice(start)) {
+        const match = FOOTER.exec(line)?.groups;
+        if (match?.["key"] === undefined) {
+            current?.push(line);
+            continue;
+        }
+        breaking ||= BREAKING.has(match["key"]);
+        const key = match["key"].toLowerCase();
+        current = [(match["value"] ?? "").trim()];
+        footers.set(key, [...(footers.get(key) ?? []), current]);
+    }
+    const body = rest
+        .slice(0, start)
+        .join("\n")
+        .replace(/^(?:[ \t]*\n)+/u, "")
+        .trimEnd() || undefined;
+    const common = {
+        body,
+        footers: Object.fromEntries([...footers].map(([key, values]) => [
+            key,
+            values.map((lines) => lines.join("\n").trimEnd()),
+        ])),
+    };
+    const parts = HEADER.exec(header)?.groups;
+    if (parts?.["type"] === undefined) {
+        return {
+            type: "",
+            scope: undefined,
+            breaking,
+            ...withPr(header),
+            ...common,
+        };
+    }
+    return {
+        type: parts["type"],
+        scope: parts["scope"] === "" ? undefined : parts["scope"],
+        breaking: breaking || parts["bang"] !== undefined,
+        ...withPr(parts["subject"] ?? ""),
+        ...common,
+    };
+};
+/** Maps each commit to exactly one commit-derived Change. */
+export const conventionalCommits = {
+    name: "conventional-commits",
+    collect: (_ctx, { commits }) => commits.map((commit) => {
+        const parsed = parseCommit(commit.message);
+        const values = parsed.footers["release-as"] ?? [];
+        return {
+            sha: commit.sha,
+            type: parsed.type,
+            breaking: parsed.breaking,
+            ...(parsed.scope === undefined ? {} : { scope: parsed.scope }),
+            subject: parsed.subject,
+            ...(parsed.body === undefined ? {} : { body: parsed.body }),
+            ...(parsed.pr === undefined ? {} : { pr: parsed.pr }),
+            ...(values.length === 0 ? {} : { releaseAs: values.map(releaseAs) }),
+        };
+    }),
+};

package/dist/discover.js

@@ -41,7 +41,7 @@ export const discoverUnits = async (active, env) => {
             });
         }
     }
-    for (const [key, { release, tags, ...overlay }] of Object.entries(env.config.units ?? {})) {
+    for (const [key, { release, tags, initialVersion, ...overlay },] of Object.entries(env.config.units ?? {})) {
         const root = normalizeRoot(key);
         const invalid = tags?.find((t) => !UNIT_TAG.test(t));
         if (invalid !== undefined) {
@@ -52,6 +52,7 @@ export const discoverUnits = async (active, env) => {
             entry.draft = { ...entry.draft, ...overlay };
             entry.release = release;
             entry.tags = tags;
+            entry.initialVersion = initialVersion;
         }
         else {
             byRoot.set(root, {
@@ -64,6 +65,7 @@ export const discoverUnits = async (active, env) => {
                 meta: {},
                 release,
                 tags,
+                initialVersion,
             });
         }
     }
@@ -91,7 +93,7 @@ export const discoverUnits = async (active, env) => {
     const roots = [...byRoot.keys()].sort(compare);
     const { defaults } = env.config;
     return [...byId.values()]
-        .map(({ plugin, draft, meta, release, tags }) => {
+        .map(({ plugin, draft, meta, release, tags, initialVersion }) => {
         const { root } = draft;
         const nested = roots
             .filter((r) => isInside(r, root))
@@ -115,6 +117,7 @@ export const discoverUnits = async (active, env) => {
                 (root === "." ? "v{version}" : "{id}-v{version}"),
             propagate: draft.propagate ?? defaults?.propagate ?? "auto",
             tags: Object.freeze(uniqueSorted(tags ?? [])),
+            initialVersion: initialVersion ?? defaults?.initialVersion ?? null,
             meta: Object.freeze(meta),
         });
     })

package/dist/errors.d.ts

@@ -10,4 +10,6 @@ export interface Warning {
     code: string;
     message: string;
     plugin?: string;
+    /** The unit the warning concerns. */
+    unit?: string;
 }

package/dist/explain.d.ts

@@ -0,0 +1,49 @@
+import type { Warning } from "./errors.js";
+import type { Plan, PlanChange, PlanOptions, UnitPlan } from "./plan.js";
+import type { GitReader } from "./plugin.js";
+import type { Workspace } from "./workspace.js";
+export interface ExplainedChange extends PlanChange {
+    /** Commit files attributed to the unit, or to `via`. */
+    files: string[];
+}
+export interface ReleaseAsFooter {
+    sha?: string;
+    /** Raw value; qualified values without the unit prefix. */
+    version: string;
+    qualified: boolean;
+    /** The value that set `releaseAs`. */
+    applied: boolean;
+}
+/** Why a unit is affected and how its version is computed. */
+export interface UnitExplanation {
+    /** The plan with `all` set. */
+    plan: Plan;
+    /** Plan entry; null when the unit is neither affected nor pending. */
+    unit: UnitPlan | null;
+    /** The unit's fixed group. */
+    group: {
+        name: string;
+        members: string[];
+    } | null;
+    /** What set `unit.next`: the bump, the initial version or a Release-As value. */
+    nextSource: "bump" | "initial" | "release-as" | null;
+    /** Changed unit files (reason `direct`) or changed global inputs (`global`). */
+    files: string[];
+    /** Plan changes with their files, core commit order. */
+    changes: ExplainedChange[];
+    /** `pinned` is null when the dependency is reached through unreleased units. */
+    propagatedFrom: {
+        id: string;
+        pinned: boolean | null;
+    }[];
+    /** Release-As footers for the unit since its base tag, core commit order. */
+    releaseAs: ReleaseAsFooter[];
+    /** Plan warnings of the unit and those of no unit. */
+    warnings: Warning[];
+}
+export interface ExplainOptions extends PlanOptions {
+    /** Unit id. */
+    unit: string;
+}
+/** Explains one unit of the plan of `opts.head`; throws `E_UNIT_UNKNOWN`. */
+export declare const explainUnit: (workspace: Workspace, git: GitReader, { unit: id, ...opts }: ExplainOptions) => Promise<UnitExplanation>;