@tallyrelease/core 0.2.0 → 0.3.0

package/dist/marker.js

@@ -0,0 +1,48 @@
+import { decodeBase64, encodeBase64 } from "./base64.js";
+const MARKER = /<!-- tallyrelease-plan:v1 ([A-Za-z0-9+/=]*) -->/u;
+const isRelease = (value) => {
+    const r = value;
+    return (typeof r === "object" &&
+        r !== null &&
+        typeof r.id === "string" &&
+        typeof r.version === "string" &&
+        typeof r.tag === "string");
+};
+/** `<!-- tallyrelease-plan:v1 <base64 json> -->` holding only the marker fields. */
+export const encodeMarker = ({ head, releaseCommit, releases, }) => {
+    const json = JSON.stringify({
+        head,
+        releaseCommit,
+        releases: releases.map(({ id, version, tag }) => ({ id, version, tag })),
+    });
+    return `<!-- tallyrelease-plan:v1 ${encodeBase64(json)} -->`;
+};
+/** The marker in a PR body; undefined when missing or malformed. */
+export const decodeMarker = (body) => {
+    const data = MARKER.exec(body)?.[1];
+    const json = data === undefined ? undefined : decodeBase64(data);
+    if (json === undefined) {
+        return undefined;
+    }
+    let value;
+    try {
+        value = JSON.parse(json);
+    }
+    catch {
+        return undefined;
+    }
+    const m = value;
+    if (typeof m !== "object" ||
+        m === null ||
+        typeof m.head !== "string" ||
+        typeof m.releaseCommit !== "string" ||
+        !Array.isArray(m.releases) ||
+        !m.releases.every(isRelease)) {
+        return undefined;
+    }
+    return {
+        head: m.head,
+        releaseCommit: m.releaseCommit,
+        releases: m.releases.map(({ id, version, tag }) => ({ id, version, tag })),
+    };
+};

package/dist/plan.d.ts

@@ -11,6 +11,8 @@ export interface PlanChange {
     breaking: boolean;
     scope?: string;
     subject: string;
+    /** `BREAKING CHANGE` footer text. */
+    notes?: string;
     pr?: number;
     /** Absorbed unit the change came through. */
     via?: string;

package/dist/plan.js

@@ -34,6 +34,7 @@ const planChanges = (intent) => (intent?.changes ?? []).map(({ change, via }) =>
         breaking: change.breaking,
         ...(change.scope === undefined ? {} : { scope: change.scope }),
         subject: change.subject,
+        ...(change.notes === undefined ? {} : { notes: change.notes }),
         ...(change.pr === undefined ? {} : { pr: change.pr }),
         ...(via === undefined ? {} : { via }),
         ...(releaseAs === undefined ? {} : { releaseAs }),

package/dist/plugin.d.ts

@@ -125,6 +125,8 @@ export interface VersionFile {
 }
 export interface WriteCtx {
     unit: Unit;
+    /** All units of the workspace. */
+    units: readonly Unit[];
     /** Unit id to version in the current plan. */
     versions: ReadonlyMap<string, string>;
 }
@@ -183,6 +185,8 @@ export interface Change {
     scope?: string;
     subject: string;
     body?: string;
+    /** `BREAKING CHANGE` footer text. */
+    notes?: string;
     releaseAs?: ReleaseAsValue[];
     pr?: number;
     date?: string;

package/dist/propagate.d.ts

@@ -1,5 +1,11 @@
 import type { Graph } from "./graph.js";
-import type { BumpLevel, Unit } from "./plugin.js";
+import type { BumpLevel, Edge, Unit } from "./plugin.js";
+/**
+ * Edges between released units, `to` to `from` to `pinned`. A path through
+ * unreleased units counts as an edge with the first hop's `pinned`; several
+ * paths are OR-combined.
+ */
+export declare const releasedEdges: (edges: readonly Edge[], released: ReadonlySet<string>) => Map<string, Map<string, boolean>>;
 /** Bump state of a released unit. */
 export interface Pending {
     readonly bump: BumpLevel | null;

package/dist/propagate.js

@@ -4,7 +4,7 @@ import { maxLevel, uniqueSorted } from "./util.js";
  * unreleased units counts as an edge with the first hop's `pinned`; several
  * paths are OR-combined.
  */
-const releasedEdges = (edges, released) => {
+export const releasedEdges = (edges, released) => {
     const out = new Map();
     for (const e of edges) {
         const list = out.get(e.from) ?? [];

package/dist/release-items.d.ts

@@ -0,0 +1,35 @@
+import type { ReleasePrMode } from "./config.js";
+import type { MarkerRelease } from "./marker.js";
+import type { Plan } from "./plan.js";
+import type { Workspace } from "./workspace.js";
+/** A group or an ungrouped released unit; releases as one. */
+export interface ReleaseItem {
+    name: string;
+    kind: "unit" | "group";
+    mode: ReleasePrMode;
+    /** Sorted member ids; the unit itself for kind `unit`. */
+    units: string[];
+    /** Stable `next`. */
+    version: string;
+    /** Version tag of each member, in `units` order. */
+    tags: {
+        id: string;
+        tag: string;
+    }[];
+}
+/** Pending release items (stable `next`) in plan unit order. */
+export declare const releaseItems: (workspace: Workspace, plan: Plan) => ReleaseItem[];
+/** One release per item member. */
+export declare const releaseEntries: (items: readonly ReleaseItem[]) => MarkerRelease[];
+/**
+ * True when every marker release equals the plan's release of that unit and
+ * every item the marker touches is complete. Pending items outside the marker
+ * are ignored; an empty marker never equals.
+ */
+export declare const planEquals: (marker: readonly MarkerRelease[], plan: Plan, workspace: Workspace) => boolean;
+/**
+ * Release PR checks: `releasePr` only on ungrouped units (`E_CONFIG`), item
+ * names (`E_RELEASE_ITEM_NAME`) and patch-propagating edges between items in
+ * different release PRs (`E_RELEASE_PR_SPLIT_EDGE`).
+ */
+export declare const validateReleaseItems: (workspace: Workspace) => void;

package/dist/release-items.js

@@ -0,0 +1,120 @@
+import { TallyError } from "./errors.js";
+import { releasedEdges } from "./propagate.js";
+import { renderTag } from "./tags.js";
+/** Item of each released unit, by unit id. */
+const itemsByUnit = (workspace) => {
+    const { releasePr } = workspace.release;
+    const byUnit = new Map();
+    for (const { name, members } of workspace.groups) {
+        const item = {
+            name,
+            kind: "group",
+            mode: releasePr.groups.get(name) ?? releasePr.default,
+            units: [...members],
+        };
+        for (const id of members) {
+            byUnit.set(id, item);
+        }
+    }
+    for (const { id, version } of workspace.units) {
+        if (version !== "none" && !byUnit.has(id)) {
+            byUnit.set(id, {
+                name: id,
+                kind: "unit",
+                mode: releasePr.units.get(id) ?? releasePr.default,
+                units: [id],
+            });
+        }
+    }
+    return byUnit;
+};
+/** Why `name` cannot name a release item, else undefined. */
+const itemNameProblem = (name) => {
+    if (name === "shared") {
+        return "is reserved for the shared release PR";
+    }
+    return name.startsWith(".") ||
+        name.endsWith(".") ||
+        name.endsWith(".lock") ||
+        name.includes("..")
+        ? "does not form a valid branch name"
+        : undefined;
+};
+/** Pending release items (stable `next`) in plan unit order. */
+export const releaseItems = (workspace, plan) => {
+    const units = new Map(workspace.units.map((u) => [u.id, u]));
+    const byUnit = itemsByUnit(workspace);
+    const items = new Map();
+    for (const { id, next } of plan.units) {
+        const item = byUnit.get(id);
+        if (next === null || !item || items.has(item.name)) {
+            continue;
+        }
+        items.set(item.name, {
+            ...item,
+            version: next,
+            tags: item.units.flatMap((u) => {
+                const unit = units.get(u);
+                return unit ? [{ id: u, tag: renderTag(unit, next) }] : [];
+            }),
+        });
+    }
+    return [...items.values()];
+};
+/** One release per item member. */
+export const releaseEntries = (items) => items.flatMap((item) => item.tags.map(({ id, tag }) => ({ id, version: item.version, tag })));
+/**
+ * True when every marker release equals the plan's release of that unit and
+ * every item the marker touches is complete. Pending items outside the marker
+ * are ignored; an empty marker never equals.
+ */
+export const planEquals = (marker, plan, workspace) => {
+    const items = releaseItems(workspace, plan);
+    const entries = new Map(releaseEntries(items).map((e) => [e.id, e]));
+    const ids = new Set(marker.map((r) => r.id));
+    return (marker.length > 0 &&
+        marker.every((r) => {
+            const entry = entries.get(r.id);
+            return entry?.version === r.version && entry.tag === r.tag;
+        }) &&
+        items.every((item) => item.units.every((id) => ids.has(id)) ||
+            !item.units.some((id) => ids.has(id))));
+};
+/**
+ * Release PR checks: `releasePr` only on ungrouped units (`E_CONFIG`), item
+ * names (`E_RELEASE_ITEM_NAME`) and patch-propagating edges between items in
+ * different release PRs (`E_RELEASE_PR_SPLIT_EDGE`).
+ */
+export const validateReleaseItems = (workspace) => {
+    const byUnit = itemsByUnit(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 });
+        }
+    }
+    const groups = new Set(workspace.groups.map((g) => g.name));
+    for (const item of new Set(byUnit.values())) {
+        const problem = item.kind === "unit" && groups.has(item.name)
+            ? "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 });
+        }
+    }
+    const policies = new Map(workspace.units.map((u) => [u.id, u.propagate]));
+    const pr = (item) => item.mode === "shared" ? "shared" : item.name;
+    const edges = releasedEdges(workspace.graph.edges, new Set(byUnit.keys()));
+    for (const [to, incoming] of edges) {
+        const policy = policies.get(to) ?? "auto";
+        for (const [from, pinned] of incoming) {
+            const a = byUnit.get(from);
+            const b = byUnit.get(to);
+            const patch = policy === "auto" ? pinned : policy === "patch";
+            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] });
+        }
+    }
+};

package/dist/release.d.ts

@@ -1,4 +1,4 @@
-import type { TallyConfig } from "./config.js";
+import type { ReleasePrMode, TallyConfig, VersionTemplate } from "./config.js";
 import type { Warning } from "./errors.js";
 import type { GroupFacts, RangeFacts, UnitFacts } from "./facts.js";
 import type { BumpLevel, Change, Unit, VersionScheme } from "./plugin.js";
@@ -38,6 +38,17 @@ export interface ReleaseSettings {
     readonly absorbed: "patch" | "minor";
     /** In config order. */
     readonly branches: readonly BranchRule[];
+    readonly releasePr: {
+        readonly default: ReleasePrMode;
+        /** Set by unit overlays, by unit id. */
+        readonly units: ReadonlyMap<string, ReleasePrMode>;
+        /** Set by groups, by group name. */
+        readonly groups: ReadonlyMap<string, ReleasePrMode>;
+    };
+    /** Floating tag formats. */
+    readonly floating: readonly string[];
+    /** Version file templates by unit id. */
+    readonly templates: ReadonlyMap<string, readonly VersionTemplate[]>;
 }
 /**
  * A Change of a released unit; `via` names the first absorbed unit (by id) a
@@ -93,7 +104,7 @@ export interface ReleaseInput<V> {
  */
 export declare const reach: (id: string, dependencies: ReadonlyMap<string, readonly string[]>, released: ReadonlySet<string>) => Set<string>;
 /** Applies the defaults to `bumps` and `branches`. */
-export declare const releaseSettings: (config: TallyConfig) => ReleaseSettings;
+export declare const releaseSettings: (config: TallyConfig, units: readonly Unit[]) => ReleaseSettings;
 /**
  * Warns for qualified Release-As values naming unknown or unreleased units and
  * for plain values on commits attributed to no released unit.

package/dist/release.js

@@ -1,3 +1,4 @@
+import { normalizeRoot } from "./discover.js";
 import { compare, maxLevel, uniqueSorted } from "./util.js";
 const DEFAULT_TYPES = {
     feat: "minor",
@@ -189,7 +190,7 @@ export const reach = (id, dependencies, released) => {
     return found;
 };
 /** Applies the defaults to `bumps` and `branches`. */
-export const releaseSettings = (config) => ({
+export const releaseSettings = (config, units) => ({
     bumps: new Map(Object.entries({ ...DEFAULT_TYPES, ...config.bumps?.types })),
     absorbed: config.bumps?.absorbed ?? "patch",
     preMajor: {
@@ -203,6 +204,23 @@ export const releaseSettings = (config) => ({
         unit: b.unit ?? null,
         group: b.group ?? null,
     })),
+    releasePr: {
+        default: config.defaults?.releasePr ?? "shared",
+        units: new Map(Object.entries(config.units ?? {}).flatMap(([root, overlay]) => {
+            const unit = units.find((u) => u.root === normalizeRoot(root));
+            return unit && overlay.releasePr
+                ? [[unit.id, overlay.releasePr]]
+                : [];
+        })),
+        groups: new Map(Object.entries(config.groups ?? {}).flatMap(([name, group]) => group.releasePr ? [[name, group.releasePr]] : [])),
+    },
+    floating: config.tags?.floating ?? [],
+    templates: new Map(Object.entries(config.units ?? {}).flatMap(([root, overlay]) => {
+        const unit = units.find((u) => u.root === normalizeRoot(root));
+        return unit && overlay.versionFiles
+            ? [[unit.id, overlay.versionFiles]]
+            : [];
+    })),
 });
 /**
  * Warns for qualified Release-As values naming unknown or unreleased units and

package/dist/released.d.ts

@@ -0,0 +1,25 @@
+import type { Plan, ReleasedUnit } from "./plan.js";
+import type { GitReader } from "./plugin.js";
+import type { Workspace } from "./workspace.js";
+/**
+ * `plan` with `released`: stable unit tags whose commit is on HEAD's
+ * first-parent chain and not an ancestor of `build.base`. With a null base
+ * only tags at HEAD, warning `W_RELEASED_NO_BASE` when earlier releases on the
+ * chain are left out.
+ */
+export declare const withReleased: (workspace: Workspace, plan: Plan, { git }: {
+    git: GitReader;
+}) => Promise<Plan>;
+/**
+ * Released entries of the named tags, in `plan.released` order; names that
+ * are not stable tags of a released unit are skipped. Callers add the tags a
+ * reconcile created by passing the union of those and `plan.released` tags.
+ */
+export declare const releasedFromTags: (workspace: Workspace, plan: Plan, { git, tags }: {
+    git: GitReader;
+    tags: readonly string[];
+}) => Promise<ReleasedUnit[]>;
+/** Tag of the highest stable version of each released unit with one. */
+export declare const highestReleases: (workspace: Workspace, { git }: {
+    git: GitReader;
+}) => Promise<Set<string>>;

package/dist/released.js

@@ -0,0 +1,104 @@
+import { renderFloatingTags } from "./floating.js";
+import { schemeRegistry } from "./schemes.js";
+import { matchUnitTags } from "./tags.js";
+import { compare } from "./util.js";
+const stable = (scheme, version) => {
+    const v = scheme.parse(version);
+    return v !== undefined && !scheme.isPrerelease(v);
+};
+/**
+ * Released entries of the stable tags `keep` accepts: oldest release commit
+ * on the first-parent chain first, then plan unit order (topological), then
+ * tag name.
+ */
+const releasedEntries = async (workspace, plan, { git, keep, }) => {
+    const matched = matchUnitTags(workspace.units, await git.tags(), schemeRegistry(workspace.schemes));
+    const line = plan.line?.kind ?? "default";
+    const candidates = workspace.units.flatMap((unit) => {
+        const m = matched.get(unit.id);
+        if (!m) {
+            return [];
+        }
+        const names = m.tags.map((t) => t.name);
+        return m.tags
+            .filter((tag) => stable(m.scheme, tag.version))
+            .map((tag) => ({
+            id: unit.id,
+            path: unit.root,
+            version: tag.version,
+            tag: tag.name,
+            floatingTags: renderFloatingTags(unit, tag.version, {
+                tags: names,
+                scheme: m.scheme,
+                formats: workspace.release.floating,
+            }),
+            releaseSha: tag.sha,
+            catchUp: tag.sha !== plan.head,
+            pr: null,
+            line,
+        }));
+    });
+    const kept = await Promise.all(candidates.map(async (r) => await keep({ name: r.tag, sha: r.releaseSha, version: r.version })));
+    const released = candidates.filter((_, i) => kept[i]);
+    const shas = [...new Set(released.map((r) => r.releaseSha))];
+    const depths = await Promise.all(shas.map(async (sha) => await git.countFirstParent(null, sha)));
+    const depth = new Map(shas.map((sha, i) => [sha, depths[i] ?? 0]));
+    const rank = new Map(workspace.graph.order.map((id, i) => [id, i]));
+    return released.sort((a, b) => (depth.get(a.releaseSha) ?? 0) - (depth.get(b.releaseSha) ?? 0) ||
+        (rank.get(a.id) ?? 0) - (rank.get(b.id) ?? 0) ||
+        compare(a.tag, b.tag));
+};
+/**
+ * `plan` with `released`: stable unit tags whose commit is on HEAD's
+ * first-parent chain and not an ancestor of `build.base`. With a null base
+ * only tags at HEAD, warning `W_RELEASED_NO_BASE` when earlier releases on the
+ * chain are left out.
+ */
+export const withReleased = async (workspace, plan, { git }) => {
+    const { head } = plan;
+    const { base } = plan.build;
+    const atBase = base === null
+        ? new Set()
+        : new Set((await git.tagsMerged(base)).map((t) => t.name));
+    let omitted = 0;
+    const released = await releasedEntries(workspace, plan, {
+        git,
+        keep: async (tag) => {
+            if (atBase.has(tag.name) ||
+                !(await git.isFirstParentAncestor(tag.sha, head))) {
+                return false;
+            }
+            if (base === null && tag.sha !== head) {
+                omitted += 1;
+                return false;
+            }
+            return true;
+        },
+    });
+    const warnings = omitted === 0
+        ? []
+        : [
+            {
+                code: "W_RELEASED_NO_BASE",
+                message: "the build base is unknown; released leaves out earlier releases on the first-parent chain",
+            },
+        ];
+    return { ...plan, released, warnings: [...plan.warnings, ...warnings] };
+};
+/**
+ * Released entries of the named tags, in `plan.released` order; names that
+ * are not stable tags of a released unit are skipped. Callers add the tags a
+ * reconcile created by passing the union of those and `plan.released` tags.
+ */
+export const releasedFromTags = async (workspace, plan, { git, tags }) => {
+    const names = new Set(tags);
+    return await releasedEntries(workspace, plan, {
+        git,
+        keep: (tag) => names.has(tag.name),
+    });
+};
+/** Tag of the highest stable version of each released unit with one. */
+export const highestReleases = async (workspace, { git }) => {
+    const matched = matchUnitTags(workspace.units, await git.tags(), schemeRegistry(workspace.schemes));
+    return new Set([...matched.values()].flatMap(({ scheme, tags }) => tags.findLast((t) => stable(scheme, t.version))?.name ?? []));
+};

package/dist/tags.d.ts

@@ -15,6 +15,8 @@ export interface UnitTag {
 }
 /** Compiles `format`; literal parts and `{id}` are escaped, `{version}` must occur once. */
 export declare const compileTagFormat: (format: string, unitId: string) => TagFormat;
+/** The unit's tag for `version`. */
+export declare const renderTag: (unit: Pick<Unit, "id" | "tagFormat">, version: string) => string;
 /** Tags of a released unit and its scheme. */
 export interface UnitTags {
     readonly scheme: VersionScheme<any>;

package/dist/tags.js

@@ -15,6 +15,10 @@ export const compileTagFormat = (format, unitId) => {
         match: (tag) => re.exec(tag)?.[1],
     };
 };
+/** The unit's tag for `version`. */
+export const renderTag = (unit, version) => unit.tagFormat
+    .replaceAll("{id}", unit.id)
+    .replace("{version}", () => version);
 /**
  * Tags of each released unit, sorted by scheme order, then name. Unreleased
  * units never match. Throws `E_TAG_FORMAT_OVERLAP` if two released units render

package/dist/validate.d.ts

@@ -4,7 +4,8 @@ import type { Workspace } from "./workspace.js";
 /**
  * Release-only checks, never run by `affected`: scheme registry, schemes, tag
  * formats and initial versions of released units, group members, branch rules,
- * their absolute check targets and channels. Returns the scheme registry.
+ * their absolute check targets and channels, release items, floating tag
+ * formats and version file templates. Returns the scheme registry.
  */
 export declare const validateRelease: (workspace: Workspace) => ReadonlyMap<string, VersionScheme<any>>;
 /**

package/dist/validate.js

@@ -1,12 +1,16 @@
 import { validateBranches } from "./branches.js";
 import { TallyError } from "./errors.js";
+import { validateFloating } from "./floating.js";
+import { validateReleaseItems } from "./release-items.js";
 import { schemeRegistry } from "./schemes.js";
 import { compileTagFormat, matchUnitTags, noMatchingTag } from "./tags.js";
 import { uniqueSorted } from "./util.js";
+import { validateTemplates } from "./version-files.js";
 /**
  * Release-only checks, never run by `affected`: scheme registry, schemes, tag
  * formats and initial versions of released units, group members, branch rules,
- * their absolute check targets and channels. Returns the scheme registry.
+ * their absolute check targets and channels, release items, floating tag
+ * formats and version file templates. Returns the scheme registry.
  */
 export const validateRelease = (workspace) => {
     const schemes = schemeRegistry(workspace.schemes);
@@ -55,6 +59,9 @@ export const validateRelease = (workspace) => {
             });
         }
     }
+    validateReleaseItems(workspace);
+    validateFloating(workspace.release.floating);
+    validateTemplates(workspace);
     return schemes;
 };
 /**

package/dist/version-files.d.ts

@@ -0,0 +1,34 @@
+import type { Warning } from "./errors.js";
+import type { Plan } from "./plan.js";
+import type { ReadonlyFs, VersionFile } from "./plugin.js";
+import type { ReleaseItem } from "./release-items.js";
+import type { Workspace } from "./workspace.js";
+/** Checks template files and patterns (`E_CONFIG`); runs no plugin hook. */
+export declare const validateTemplates: (workspace: Workspace) => void;
+/**
+ * Plugin version files by unit id. Throws `E_VERSION_FILE_CLAIM` when a path
+ * is a plugin version file of two units or also a template. Templates may
+ * share a file.
+ */
+export declare const versionFileClaims: (workspace: Workspace) => Promise<ReadonlyMap<string, readonly VersionFile[]>>;
+/**
+ * Files of a release of `items` (stable `next`): plugin version files,
+ * templates and `<root>/CHANGELOG.md` per unit, read through `fs`. Returns
+ * only files whose content changes, and each unit's changelog section;
+ * checks claims first. Templates skip first releases and warn
+ * `W_VERSION_FILE_NO_MATCH` without any match; a missing version file is
+ * `E_VERSION_FILE_MISSING`.
+ */
+export declare const releaseFiles: (workspace: Workspace, plan: Plan, opts: {
+    /** Files the release is based on. */
+    fs: ReadonlyFs;
+    items: readonly ReleaseItem[];
+    repoUrl: string | null;
+    /** `YYYY-MM-DD` changelog heading date. */
+    date: string;
+}) => Promise<{
+    files: Map<string, string>;
+    /** Changelog section of each unit, by unit id. */
+    sections: Map<string, string>;
+    warnings: Warning[];
+}>;