@tallyrelease/core 0.1.1 → 0.2.0-beta.8

package/dist/facts.d.ts

@@ -0,0 +1,81 @@
+import type { Warning } from "./errors.js";
+import type { Change, GitReader, ReadonlyFs } from "./plugin.js";
+import type { UnitTag } from "./tags.js";
+import type { Workspace } from "./workspace.js";
+export interface FactsOptions {
+    head: string;
+    fs: ReadonlyFs;
+    debug?: (message: string) => void;
+}
+/** A Change with the ids of the units it is attributed to. */
+export interface AttributedChange {
+    readonly change: Change;
+    /** Sorted. */
+    readonly units: readonly string[];
+}
+/**
+ * Changes of `(from, head]`, in core commit order, attributed to all units. A
+ * unit's consumers read only its own range (`UnitFacts.from`), filtered to the
+ * unit and the units it absorbs.
+ */
+export interface RangeFacts {
+    readonly from: string | null;
+    readonly changes: readonly AttributedChange[];
+}
+export interface UnitFacts {
+    readonly id: string;
+    /** Fixed group name. */
+    readonly group: string | null;
+    /**
+     * Range key, null from the root: the base tag commit; for a group member
+     * its own base tag when that descends from the group base tag, else the
+     * group base tag.
+     */
+    readonly from: string | null;
+    /** Every matched tag, reachable or not, scheme-sorted. */
+    readonly tags: readonly UnitTag[];
+    /** Highest stable tag merged into head. */
+    readonly baseTag: UnitTag | null;
+    /** Source of the `from` version: the group base tag for members, else `baseTag`. */
+    readonly fromTag: UnitTag | null;
+    /** Highest stable tag on head's first-parent chain. */
+    readonly lineBaseTag: UnitTag | null;
+    readonly sinceLineBase: number;
+    readonly total: number;
+    /** Changes since the base tag attributed to this unit, core commit order. */
+    readonly changes: readonly AttributedChange[];
+    /** Qualified Release-As values naming this unit, core commit order. */
+    readonly releaseAs: readonly {
+        sha?: string;
+        version: string;
+    }[];
+}
+/**
+ * A fixed group. Base and line base are the highest member tags as for a
+ * unit; equal versions prefer the tag whose commit descends from the other's.
+ */
+export interface GroupFacts {
+    readonly name: string;
+    readonly members: readonly string[];
+    /** Highest stable member tag merged into head. */
+    readonly baseTag: UnitTag | null;
+    /** Highest stable member tag on head's first-parent chain. */
+    readonly lineBaseTag: UnitTag | null;
+    readonly sinceLineBase: number;
+}
+/** Git and intent data of every released unit, collected before release math. */
+export interface PlanFacts {
+    readonly head: string;
+    /** Released units, sorted by id. */
+    readonly units: readonly UnitFacts[];
+    /** One entry per distinct base tag commit. */
+    readonly ranges: readonly RangeFacts[];
+    /** Sorted by name. */
+    readonly groups: readonly GroupFacts[];
+    /** Every tag name, sorted. */
+    readonly tagNames: readonly string[];
+    /** Warnings logged by intent sources and for unknown explicit units. */
+    readonly warnings: readonly Warning[];
+}
+/** Runs every `GitReader` and intent source call a plan needs. */
+export declare const collectPlanFacts: (workspace: Workspace, git: GitReader, opts: FactsOptions) => Promise<PlanFacts>;

package/dist/facts.js

@@ -0,0 +1,250 @@
+import { attribution, matcher } from "./attribution.js";
+import { TallyError } from "./errors.js";
+import { pluginCtx, runHook } from "./plugins.js";
+import { schemeRegistry } from "./schemes.js";
+import { matchUnitTags } from "./tags.js";
+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 });
+    }
+    return time;
+};
+/** Committer date descending, compared as instants, then sha. */
+const byCommitOrder = (a, b) => instant(b) - instant(a) || compare(a.sha, b.sha);
+const releaseAsKey = (r) => `${r.unit ?? ""}@${r.version}`;
+/** Keeps the first commit-derived Change per dedupe key, unioning `releaseAs`. */
+const dedupe = (changes) => {
+    const kept = [];
+    const index = new Map();
+    for (const change of changes) {
+        const key = change.sha === undefined
+            ? undefined
+            : [
+                change.sha,
+                change.type,
+                String(change.breaking),
+                uniqueSorted(change.units ?? []).join(","),
+            ].join("\0");
+        const at = key === undefined ? undefined : index.get(key);
+        const prior = at === undefined ? undefined : kept[at];
+        if (at === undefined || !prior) {
+            if (key !== undefined) {
+                index.set(key, kept.length);
+            }
+            kept.push(change);
+            continue;
+        }
+        if (change.releaseAs) {
+            const values = new Map([...(prior.releaseAs ?? []), ...change.releaseAs].map((r) => [
+                releaseAsKey(r),
+                r,
+            ]));
+            kept[at] = { ...prior, releaseAs: [...values.values()] };
+        }
+    }
+    return kept;
+};
+/** Runs every `GitReader` and intent source call a plan needs. */
+export const collectPlanFacts = async (workspace, git, opts) => {
+    const { head } = opts;
+    const warnings = [];
+    const ctx = pluginCtx({ ...opts, repo: { name: workspace.repo } }, warnings);
+    const intents = workspace.intents.map((entry) => ({
+        ...entry,
+        ctx: ctx(entry.plugin, entry.options),
+    }));
+    const schemes = schemeRegistry(workspace.schemes);
+    const allTags = await git.tags();
+    const tags = matchUnitTags(workspace.units, allTags, schemes);
+    const merged = new Set((await git.tagsMerged(head)).map((t) => t.name));
+    const total = await git.countFirstParent(null, head);
+    const ignored = matcher(workspace.ignore);
+    const isGlobal = matcher(workspace.globalInputs);
+    const owners = attribution(workspace.units);
+    const known = new Set(workspace.units.map((u) => u.id));
+    // File-less commits belong to every released unit (release-please parity).
+    const released = workspace.units
+        .filter((u) => u.version !== "none")
+        .map((u) => u.id);
+    const warned = new Set();
+    const warnUnknown = (plugin, changes) => {
+        for (const id of changes.flatMap((c) => c.units ?? [])) {
+            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,
+                });
+            }
+        }
+    };
+    const counts = new Map();
+    const countSince = async (sha) => {
+        const cached = counts.get(sha);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const count = await git.countFirstParent(sha, head);
+        counts.set(sha, count);
+        return count;
+    };
+    const ranges = new Map();
+    const range = async (from) => {
+        const cached = ranges.get(from);
+        if (cached) {
+            return cached;
+        }
+        const commits = Object.freeze([...(await git.log(from, head))].sort(byCommitOrder));
+        const position = new Map(commits.map((c, i) => [c.sha, i]));
+        const commitUnits = new Map(commits.map((c) => [
+            c.sha,
+            c.files.length === 0
+                ? released
+                : uniqueSorted(c.files
+                    .filter((f) => !ignored(f) && !isGlobal(f))
+                    .flatMap(owners)),
+        ]));
+        const changes = [];
+        for (const { plugin, source, ctx: sourceCtx } of intents) {
+            // eslint-disable-next-line no-await-in-loop -- hooks run sequentially in config order
+            const collected = await runHook(plugin, "intent", () => source.collect(sourceCtx, { from, to: head, commits }));
+            warnUnknown(plugin, collected);
+            changes.push(...collected);
+        }
+        const attributed = dedupe(changes)
+            .map((change) => ({
+            change,
+            units: change.units
+                ? uniqueSorted(change.units.filter((id) => known.has(id)))
+                : (commitUnits.get(change.sha ?? "") ?? []),
+        }))
+            .sort((a, b) => (position.get(a.change.sha ?? "") ?? commits.length) -
+            (position.get(b.change.sha ?? "") ?? commits.length));
+        const result = { from, changes: attributed };
+        ranges.set(from, result);
+        return result;
+    };
+    const ancestry = new Map();
+    const isAncestor = async (a, b) => {
+        const key = `${a}\0${b}`;
+        const cached = ancestry.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = await git.isAncestor(a, b);
+        ancestry.set(key, result);
+        return result;
+    };
+    /** The higher tag; equal versions prefer the tag descending from the other. */
+    const higher = async (scheme, a, b) => {
+        if (a === null || b === null) {
+            return a ?? b;
+        }
+        const x = scheme.parse(a.version);
+        const y = scheme.parse(b.version);
+        // Members with another scheme fail validateRelease (E_GROUP_SCHEME).
+        if (x === undefined || y === undefined) {
+            return a;
+        }
+        const order = scheme.compare(y, x);
+        if (order !== 0) {
+            return order > 0 ? b : a;
+        }
+        return a.sha !== b.sha && (await isAncestor(a.sha, b.sha)) ? b : a;
+    };
+    const bases = new Map();
+    for (const unit of workspace.units) {
+        const matched = tags.get(unit.id);
+        if (!matched) {
+            // Unreleased.
+            continue;
+        }
+        const { scheme } = matched;
+        const stable = matched.tags.filter((t) => merged.has(t.name) && !scheme.isPrerelease(scheme.parse(t.version)));
+        let lineBaseTag = null;
+        for (const tag of [...stable].reverse()) {
+            // eslint-disable-next-line no-await-in-loop -- stops at the first match
+            if (await git.isFirstParentAncestor(tag.sha, head)) {
+                lineBaseTag = tag;
+                break;
+            }
+        }
+        bases.set(unit.id, { scheme, baseTag: stable.at(-1) ?? null, lineBaseTag });
+    }
+    const sinceLine = async (tag) => tag ? await countSince(tag.sha) : total;
+    const groups = [];
+    for (const { name, members } of workspace.groups) {
+        let baseTag = null;
+        let lineBaseTag = null;
+        for (const id of members) {
+            const own = bases.get(id);
+            if (own) {
+                // eslint-disable-next-line no-await-in-loop -- memoized ancestry
+                baseTag = await higher(own.scheme, baseTag, own.baseTag);
+                // eslint-disable-next-line no-await-in-loop -- memoized ancestry
+                lineBaseTag = await higher(own.scheme, lineBaseTag, own.lineBaseTag);
+            }
+        }
+        groups.push({
+            name,
+            members,
+            baseTag,
+            lineBaseTag,
+            // eslint-disable-next-line no-await-in-loop -- memoized per line base
+            sinceLineBase: await sinceLine(lineBaseTag),
+        });
+    }
+    const groupOf = new Map(groups.flatMap((g) => g.members.map((id) => [id, g])));
+    const units = [];
+    for (const unit of workspace.units) {
+        const matched = tags.get(unit.id);
+        const own = bases.get(unit.id);
+        if (!matched || !own) {
+            continue;
+        }
+        const { baseTag, lineBaseTag } = own;
+        const group = groupOf.get(unit.id);
+        const fromTag = group ? group.baseTag : baseTag;
+        const rangeBase = group &&
+            baseTag &&
+            fromTag &&
+            baseTag.sha !== fromTag.sha &&
+            // eslint-disable-next-line no-await-in-loop -- memoized ancestry
+            (await isAncestor(fromTag.sha, baseTag.sha))
+            ? baseTag
+            : fromTag;
+        // eslint-disable-next-line no-await-in-loop -- intent sources run sequentially
+        const { from, changes } = await range(rangeBase?.sha ?? null);
+        units.push({
+            id: unit.id,
+            group: group?.name ?? null,
+            from,
+            tags: matched.tags,
+            baseTag,
+            fromTag,
+            lineBaseTag,
+            // eslint-disable-next-line no-await-in-loop -- memoized per line base
+            sinceLineBase: await sinceLine(lineBaseTag),
+            total,
+            changes: changes.filter((c) => c.units.includes(unit.id)),
+            releaseAs: changes.flatMap(({ change }) => (change.releaseAs ?? [])
+                .filter((r) => r.unit === unit.id)
+                .map((r) => ({
+                ...(change.sha === undefined ? {} : { sha: change.sha }),
+                version: r.version,
+            }))),
+        });
+    }
+    return {
+        head,
+        units,
+        ranges: [...ranges.values()],
+        groups,
+        tagNames: uniqueSorted(allTags.map((t) => t.name)),
+        warnings,
+    };
+};

package/dist/groups.d.ts

@@ -0,0 +1,15 @@
+import type { GroupConfig } from "./config.js";
+import type { Warning } from "./errors.js";
+import type { Unit } from "./plugin.js";
+/** A fixed group: its members release together with one version. */
+export interface Group {
+    readonly name: string;
+    /** Sorted unit ids. */
+    readonly members: readonly string[];
+}
+/**
+ * Resolves group members: `units` by id, `tags` to released units with any of
+ * the tags. Throws `E_GROUP_UNKNOWN_UNIT` and `E_GROUP_OVERLAP`; a group
+ * selecting nothing warns `W_GROUP_EMPTY` and is dropped.
+ */
+export declare const resolveGroups: (units: readonly Unit[], config: Readonly<Record<string, GroupConfig>> | undefined, warnings: Warning[]) => Group[];

package/dist/groups.js

@@ -0,0 +1,41 @@
+import { TallyError } from "./errors.js";
+import { compare, uniqueSorted } from "./util.js";
+/**
+ * Resolves group members: `units` by id, `tags` to released units with any of
+ * the tags. Throws `E_GROUP_UNKNOWN_UNIT` and `E_GROUP_OVERLAP`; a group
+ * selecting nothing warns `W_GROUP_EMPTY` and is dropped.
+ */
+export const resolveGroups = (units, config, warnings) => {
+    const known = new Set(units.map((u) => u.id));
+    const owner = new Map();
+    const groups = [];
+    for (const name of Object.keys(config ?? {}).sort(compare)) {
+        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 });
+        }
+        const members = uniqueSorted([
+            ...ids,
+            ...units
+                .filter((u) => u.version !== "none" && u.tags.some((t) => tags.includes(t)))
+                .map((u) => u.id),
+        ]);
+        if (members.length === 0) {
+            warnings.push({
+                code: "W_GROUP_EMPTY",
+                message: `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] });
+            }
+            owner.set(id, name);
+        }
+        groups.push({ name, members });
+    }
+    return groups;
+};

package/dist/index.d.ts

@@ -1,16 +1,28 @@
 export declare const version = "0.0.0";
 export type { AffectedDoc, AffectedOptions, AffectedReason, AffectedUnit, BaseSource, } from "./affected.js";
-export type { DepConfig, TallyConfig, UnitOverlay } from "./config.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";
+export type { DepConfig, GroupConfig, TallyConfig, UnitOverlay, } from "./config.js";
 export type { Warning } from "./errors.js";
 export type { Graph, SourcedEdge } from "./graph.js";
-export type { BumpLevel, Change, Ctx, Edge, EdgeDraft, GitReader, IntentSource, MaybePromise, Plugin, PreCtx, Propagate, RawCommit, ReadonlyFs, TagRef, Unit, UnitDraft, VersionFile, VersionMode, VersionScheme, VersionSource, WriteCtx, } from "./plugin.js";
+export type { Group } from "./groups.js";
+export type { BumpLevel, Change, Ctx, Edge, EdgeDraft, GitReader, IntentSource, MaybePromise, Plugin, PreCtx, Propagate, RawCommit, ReadonlyFs, ReleaseAsValue, TagRef, Unit, UnitDraft, VersionFile, VersionMode, VersionScheme, VersionSource, WriteCtx, } from "./plugin.js";
 export type { ActivePlugin, PluginEnv } from "./plugins.js";
-export type { Workspace, WorkspaceInput } from "./workspace.js";
+export type { BranchRule, ReleaseSettings } from "./release.js";
+export type { SchemeEntry } from "./schemes.js";
+export type { SemVer } from "./semver.js";
+export type { IntentEntry, Workspace, WorkspaceInput } from "./workspace.js";
 export { computeAffected } from "./affected.js";
 export { CONFIG_FILE } from "./config.js";
+export { conventionalCommits, parseCommit } from "./conventional.js";
 export { discoverUnits } from "./discover.js";
 export { TallyError } from "./errors.js";
+export { explainUnit } from "./explain.js";
 export { buildGraph } from "./graph.js";
 export { definePlugin, defaultUnitId, PLUGIN_API_VERSION } from "./plugin.js";
+export { computePlan } from "./plan.js";
 export { activatePlugins } from "./plugins.js";
+export { semver } from "./semver.js";
+export { validateRelease, validateTags } from "./validate.js";
 export { loadWorkspace } from "./workspace.js";

package/dist/index.js

@@ -1,9 +1,14 @@
 export const version = "0.0.0";
 export { computeAffected } from "./affected.js";
 export { CONFIG_FILE } from "./config.js";
+export { conventionalCommits, parseCommit } from "./conventional.js";
 export { discoverUnits } from "./discover.js";
 export { TallyError } from "./errors.js";
+export { explainUnit } from "./explain.js";
 export { buildGraph } from "./graph.js";
 export { definePlugin, defaultUnitId, PLUGIN_API_VERSION } from "./plugin.js";
+export { computePlan } from "./plan.js";
 export { activatePlugins } from "./plugins.js";
+export { semver } from "./semver.js";
+export { validateRelease, validateTags } from "./validate.js";
 export { loadWorkspace } from "./workspace.js";

package/dist/plan.d.ts

@@ -0,0 +1,108 @@
+import type { AffectedDoc, AffectedOptions, AffectedReason } from "./affected.js";
+import type { Line } from "./branches.js";
+import type { PlanFacts } from "./facts.js";
+import type { BumpLevel, GitReader, ReadonlyFs, VersionScheme } from "./plugin.js";
+import type { UnitRelease } from "./release.js";
+import type { Workspace } from "./workspace.js";
+export interface PlanChange {
+    /** Absent for file-based changes. */
+    sha?: string;
+    type: string;
+    breaking: boolean;
+    scope?: string;
+    subject: string;
+    pr?: number;
+    /** Absorbed unit the change came through. */
+    via?: string;
+    /** Release-As value of this commit for the unit. */
+    releaseAs?: string;
+}
+export interface UnitPlan {
+    id: string;
+    /** Unit root, `.` for the repo root. */
+    path: string;
+    plugin: string;
+    scheme: string;
+    tags: string[];
+    group: string | null;
+    affected: {
+        reason: AffectedReason;
+        via: string[];
+    } | null;
+    kind: "prerelease" | "rebuild" | "none";
+    baseTag: string | null;
+    lineBaseTag: string | null;
+    /** Null on a first release. */
+    from: string | null;
+    bump: BumpLevel | null;
+    releaseAs: string | null;
+    propagatedFrom: string[];
+    absorbedFrom: string[];
+    next: string | null;
+    version: string | null;
+    /** The planned commit. */
+    sha: string;
+    /** Core commit order. */
+    changes: PlanChange[];
+}
+export interface GroupPlan {
+    name: string;
+    members: string[];
+    baseTag: string | null;
+    from: string | null;
+    bump: BumpLevel | null;
+    next: string | null;
+    version: string | null;
+}
+export interface ReleasedUnit {
+    id: string;
+    path: string;
+    version: string;
+    tag: string;
+    floatingTags: string[];
+    releaseSha: string;
+    catchUp: boolean;
+    pr: number | null;
+    line: "default" | "maintenance";
+}
+/** `tallyrelease plan --json`, schema 1. */
+export interface Plan extends Omit<AffectedDoc, "units"> {
+    line: Line | null;
+    /** Topological order, cycles by id. */
+    units: UnitPlan[];
+    /** Sorted by name. */
+    groups: GroupPlan[];
+    /** Stable releases in `(build.base, head]`; empty until filled. */
+    released: ReleasedUnit[];
+}
+export interface PlanOptions extends AffectedOptions {
+    /** Files at `head`, for intent source contexts. */
+    fs: ReadonlyFs;
+    /** Also list released units outside the build set with a pending release. */
+    all?: boolean;
+    debug?: (message: string) => void;
+}
+/** Inputs of `resolvePlan`, all collected before release math. */
+export interface ResolveInput {
+    affected: AffectedDoc;
+    facts: PlanFacts;
+    schemes: ReadonlyMap<string, VersionScheme<any>>;
+    all: boolean;
+}
+/** Release math over collected facts; no I/O. */
+export declare const resolvePlan: (workspace: Workspace, input: ResolveInput) => Plan;
+/** A plan with the facts it was resolved from. */
+export interface PlanResult {
+    plan: Plan;
+    facts: PlanFacts;
+    /** Releases of the released units with a scheme. */
+    releases: ReadonlyMap<string, UnitRelease>;
+}
+/** `computePlan` keeping the collected facts, for `explainUnit`. */
+export declare const planWithFacts: (workspace: Workspace, git: GitReader, opts: PlanOptions) => Promise<PlanResult>;
+/**
+ * Plans `head`: validates release config, computes the build set, collects
+ * git and intent facts and resolves versions and kinds.
+ */
+export declare const computePlan: (workspace: Workspace, git: GitReader, opts: PlanOptions) => Promise<Plan>;
+export type { Line as PlanLine } from "./branches.js";