@tallyrelease/cli 0.1.1-beta.1 → 0.2.0-beta.7

package/dist/session.d.ts

@@ -1,7 +1,7 @@
 import type { Env, GithubContext } from "./ci/github-env.js";
 import type { Forge } from "./forge/forge.js";
 import type { RepoGit } from "./git/reader.js";
-import type { ReadonlyFs, Warning, Workspace } from "@tallyrelease/core";
+import type { Plan, PlanOptions, ReadonlyFs, Warning, Workspace } from "@tallyrelease/core";
 export interface Writer {
     write: (chunk: string) => unknown;
 }
@@ -15,6 +15,8 @@ export interface Deps {
     git?: RepoGit;
     /** Defaults to `node:fs` at the repo root. */
     fs?: ReadonlyFs;
+    /** Files at a commit; defaults to the git object store at the repo root. */
+    fsAt?: (ref: string) => ReadonlyFs;
     /** Defaults to GitHub when a token is available; used only with a token. */
     forge?: Forge;
 }
@@ -36,6 +38,18 @@ export interface Session {
     /** Undefined without a token. */
     readonly forge: Forge | undefined;
     readonly workspace: () => Promise<Workspace>;
+    /** Content of `path` at commit `ref`, undefined when absent. */
+    readonly readAt: (ref: string, path: string) => string | undefined;
+    /**
+     * Runs `use` with the workspace and files at commit `ref`, or of the
+     * working tree when `ref` is null; the config is always read from the
+     * working tree.
+     */
+    readonly workspaceAt: <T>(ref: string | null, use: (workspace: Workspace, fs: ReadonlyFs) => Promise<T>) => Promise<T>;
+    /** `computePlan` with the workspace and files of `workspaceAt(ref)`. */
+    readonly planAt: (ref: string | null, opts: Omit<PlanOptions, "fs">) => Promise<Plan>;
     readonly warn: (warnings: readonly Warning[]) => void;
 }
 export declare const createSession: (deps: Deps, opts: GlobalOptions) => Session;
+/** PR head branch, else the GitHub ref name, else the checked-out branch, else `HEAD`. */
+export declare const branchName: (session: Pick<Session, "git" | "github">) => Promise<string>;

package/dist/session.js

@@ -1,10 +1,10 @@
-import { loadWorkspace, TallyError } from "@tallyrelease/core";
+import { computePlan, loadWorkspace, TallyError } from "@tallyrelease/core";
 import { existsSync } from "node:fs";
 import { basename, relative, resolve, sep } from "node:path";
 import { githubContext } from "./ci/github-env.js";
 import { loadConfig } from "./config/load.js";
 import { githubForge } from "./forge/github.js";
-import { nodeFs } from "./fs-ctx.js";
+import { gitBlob, gitTreeFs, nodeFs } from "./fs-ctx.js";
 import { git as runGit } from "./git/exec.js";
 import { gitReader } from "./git/reader.js";
 import { painter } from "./output/paint.js";
@@ -56,30 +56,42 @@ export const createSession = (deps, opts) => {
         }
         return basename(root);
     };
+    const repoGit = deps.git ?? gitReader(root, debug);
+    const workspaceAt = async (ref, use) => {
+        if (onDisk) {
+            await assertRepoRoot();
+        }
+        const config = loadConfig(fs, configPath);
+        const files = ref === null ? fs : (deps.fsAt?.(ref) ?? gitTreeFs(root, ref));
+        const workspace = await loadWorkspace({
+            config,
+            configFile: configPath,
+            plugins: Object.values(builtinPlugins),
+            fs: files,
+            repo: { name: await repoName() },
+            ...(debug && { debug }),
+        });
+        return await use(workspace, files);
+    };
     return {
         cwd: deps.cwd,
         root,
         env: deps.env,
         stdout: deps.stdout,
         fs,
-        git: deps.git ?? gitReader(root, debug),
+        git: repoGit,
         github,
         forge: token
             ? (deps.forge ?? githubForge({ token, baseUrl: github?.apiUrl }))
             : undefined,
-        workspace: async () => {
-            if (onDisk) {
-                await assertRepoRoot();
-            }
-            return await loadWorkspace({
-                config: loadConfig(fs, configPath),
-                configFile: configPath,
-                plugins: Object.values(builtinPlugins),
-                fs,
-                repo: { name: await repoName() },
-                ...(debug && { debug }),
-            });
-        },
+        workspace: async () => await workspaceAt(null, (workspace) => Promise.resolve(workspace)),
+        readAt: (ref, path) => deps.fsAt ? deps.fsAt(ref).read(path) : gitBlob(root, ref, path),
+        workspaceAt,
+        planAt: async (ref, opts) => await workspaceAt(ref, async (workspace, files) => await computePlan(workspace, repoGit, {
+            ...opts,
+            fs: files,
+            ...(debug && { debug }),
+        })),
         warn: (warnings) => {
             const paint = painter(deps.stderr);
             for (const w of warnings) {
@@ -88,3 +100,8 @@ export const createSession = (deps, opts) => {
         },
     };
 };
+/** PR head branch, else the GitHub ref name, else the checked-out branch, else `HEAD`. */
+export const branchName = async (session) => session.github?.headRef ??
+    session.github?.refName ??
+    (await session.git.branch()) ??
+    "HEAD";

package/dist/shadow/compare.d.ts

@@ -0,0 +1,50 @@
+import type { Plan } from "@tallyrelease/core";
+export type ShadowStatus = "match" | "mismatch" | "tallyrelease-only" | "rp-only";
+/** Known divergence classes between tallyrelease and release-please. */
+export type ShadowLabel = "absorbed-internal" | "dependent-patch" | "group-vs-rp" | "release-config" | "separate-pr" | "squash-split";
+export interface ShadowRow {
+    /** Manifest path, else the unit root. */
+    path: string;
+    unit: string | null;
+    status: ShadowStatus;
+    /** Manifest value at `HEAD^1`. */
+    before: string | null;
+    /** Manifest value at `HEAD`. */
+    after: string | null;
+    /** tallyrelease `from`. */
+    from: string | null;
+    /** tallyrelease `next`. */
+    next: string | null;
+    /** Sorted. */
+    labels: ShadowLabel[];
+}
+export interface ShadowUnit {
+    id: string;
+    path: string;
+    released: boolean;
+    dependsOn: readonly string[];
+}
+export interface CompareInput {
+    /** Manifest at `HEAD^1`. */
+    before: Readonly<Record<string, string>>;
+    /** Manifest at `HEAD`. */
+    after: Readonly<Record<string, string>>;
+    /** Plan of `HEAD^1`. */
+    plan: Pick<Plan, "units">;
+    units: readonly ShadowUnit[];
+    /** Parsed `release-please-config.json`. */
+    rpConfig: Readonly<Record<string, unknown>>;
+    /** Full commit messages by sha, for `squash-split`. */
+    messages: ReadonlyMap<string, string>;
+    /** Commit types with a bump level. */
+    bumpTypes: ReadonlySet<string>;
+}
+/** True when release-please would split `message` into more commits. */
+export declare const isSquashBody: (message: string) => boolean;
+/**
+ * Compares the plan of `HEAD^1` with the manifest change of a release-please
+ * merge. Rows are sorted by path; a label names a known divergence class only
+ * when it explains the direction of the difference, and never changes the
+ * status.
+ */
+export declare const compareShadow: (input: CompareInput) => ShadowRow[];

package/dist/shadow/compare.js

@@ -0,0 +1,112 @@
+import { semver } from "@tallyrelease/core";
+/*
+ * release-please (`splitMessages` in src/commit.ts) splits a message into
+ * extra commits at a blank line followed by one of these types, and at
+ * `BEGIN_NESTED_COMMIT` blocks.
+ */
+const SPLIT = /\n\n(?:feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.*?\))?: |BEGIN_NESTED_COMMIT/;
+/** `a > b` as semver; false when either does not parse. */
+const higher = (a, b) => {
+    const [x, y] = [a, b].map((v) => (v === null ? undefined : semver.parse(v)));
+    return x !== undefined && y !== undefined && semver.compare(x, y) > 0;
+};
+/** True when `v` is exactly the patch bump of `base`. */
+const isPatchOf = (v, base) => {
+    const [x, y] = [v, base].map((s) => s === null ? undefined : semver.parse(s));
+    return (x !== undefined &&
+        y !== undefined &&
+        semver.compare(x, semver.bump(y, "patch")) === 0);
+};
+/** Effective `separate-pull-requests` for a manifest path. */
+const separatePr = (rpConfig, path) => {
+    const packages = rpConfig["packages"];
+    const own = packages?.[path]?.["separate-pull-requests"];
+    return (own ?? rpConfig["separate-pull-requests"]) === true;
+};
+/** True when release-please would split `message` into more commits. */
+export const isSquashBody = (message) => SPLIT.test(message);
+/**
+ * Compares the plan of `HEAD^1` with the manifest change of a release-please
+ * merge. Rows are sorted by path; a label names a known divergence class only
+ * when it explains the direction of the difference, and never changes the
+ * status.
+ */
+export const compareShadow = (input) => {
+    const { before, after, plan, units, rpConfig, messages, bumpTypes } = input;
+    const changed = new Set(Object.keys(after).filter((path) => before[path] !== after[path]));
+    const unitByPath = new Map(units.map((u) => [u.path, u]));
+    const pathById = new Map(units.map((u) => [u.id, u.path]));
+    const planByPath = new Map(plan.units.map((u) => [u.path, u]));
+    // release-please node-workspace patches dependents of changed paths.
+    const dependentPatch = (row, planned) => {
+        if (row.status === "rp-only") {
+            const deps = unitByPath.get(row.path)?.dependsOn ?? [];
+            return (isPatchOf(row.after, row.before) &&
+                deps.some((id) => changed.has(pathById.get(id) ?? "")));
+        }
+        return (row.status === "tallyrelease-only" &&
+            (planned?.propagatedFrom.length ?? 0) > 0 &&
+            isPatchOf(row.next, row.from));
+    };
+    // tallyrelease is higher because of a bumping change from an absorbed unit.
+    const absorbedInternal = (row, planned) => (row.status === "tallyrelease-only" ||
+        (row.status === "mismatch" && higher(row.next, row.after))) &&
+        (planned?.changes ?? []).some((c) => c.via !== undefined && (c.breaking || bumpTypes.has(c.type)));
+    // release-please is higher and split a squash body into more commits.
+    const squashSplit = (row, planned) => (row.status === "rp-only" ||
+        (row.status === "mismatch" && higher(row.after, row.next))) &&
+        (planned?.changes ?? []).some((c) => c.sha !== undefined && isSquashBody(messages.get(c.sha) ?? ""));
+    const labels = (row, planned) => {
+        if (row.status === "match") {
+            return [];
+        }
+        const unit = unitByPath.get(row.path);
+        const checks = [
+            ["absorbed-internal", absorbedInternal(row, planned)],
+            ["dependent-patch", dependentPatch(row, planned)],
+            ["group-vs-rp", Boolean(planned?.group)],
+            ["release-config", !unit?.released || !(row.path in after)],
+            [
+                "separate-pr",
+                row.status === "tallyrelease-only" && separatePr(rpConfig, row.path),
+            ],
+            ["squash-split", squashSplit(row, planned)],
+        ];
+        return checks.filter(([, hit]) => hit).map(([label]) => label);
+    };
+    const rows = [];
+    for (const path of changed) {
+        const unit = unitByPath.get(path);
+        const planned = planByPath.get(path);
+        const next = planned?.next ?? null;
+        const value = after[path] ?? null;
+        const row = {
+            path,
+            unit: unit?.id ?? null,
+            status: next === null ? "rp-only" : next === value ? "match" : "mismatch",
+            before: before[path] ?? null,
+            after: value,
+            from: planned?.from ?? null,
+            next,
+            labels: [],
+        };
+        rows.push({ ...row, labels: labels(row, planned) });
+    }
+    for (const planned of plan.units) {
+        if (planned.next === null || changed.has(planned.path)) {
+            continue;
+        }
+        const row = {
+            path: planned.path,
+            unit: planned.id,
+            status: "tallyrelease-only",
+            before: before[planned.path] ?? null,
+            after: after[planned.path] ?? null,
+            from: planned.from,
+            next: planned.next,
+            labels: [],
+        };
+        rows.push({ ...row, labels: labels(row, planned) });
+    }
+    return rows.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+};

package/dist/tallyrelease.schema.json

@@ -47,6 +47,10 @@
 						"rebuild"
 					],
 					"description": "Policy for this unit when a dependency is released: patch (at least a patch bump), rebuild (rebuild only) or auto (patch if the edge is pinned, else rebuild)."
+				},
+				"initialVersion": {
+					"type": "string",
+					"description": "Version of the first release, parsed by the unit's scheme. Defaults to the scheme's initial version (semver: 1.0.0)."
 				}
 			},
 			"additionalProperties": false,
@@ -114,6 +118,10 @@
 							"pattern": "^[A-Za-z0-9._-]+$"
 						},
 						"description": "Labels for filtering with affected --tag (letters, digits, dot, underscore, dash), for example docker or npm."
+					},
+					"initialVersion": {
+						"type": "string",
+						"description": "Version of the first release, parsed by the unit's scheme. Defaults to the scheme's initial version (semver: 1.0.0)."
 					}
 				},
 				"additionalProperties": false
@@ -163,6 +171,158 @@
 			"items": {
 				"type": "string"
 			}
+		},
+		"branches": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"properties": {
+					"name": {
+						"type": "string",
+						"description": "Branch name pattern; supports * and the captures {major} and {minor}."
+					},
+					"line": {
+						"type": "string",
+						"enum": [
+							"default",
+							"maintenance"
+						],
+						"description": "Release line of matching branches."
+					},
+					"channel": {
+						"type": "string",
+						"description": "Prerelease channel (letters, digits, dash); may use {major} and {minor} captured by name."
+					},
+					"unit": {
+						"type": "string",
+						"description": "Maintenance rules: ungrouped released unit whose version must be on the line captured by name. Excludes group."
+					},
+					"group": {
+						"type": "string",
+						"description": "Maintenance rules: fixed group whose version must be on the line captured by name. Excludes unit."
+					}
+				},
+				"required": [
+					"name",
+					"line"
+				],
+				"additionalProperties": false
+			},
+			"description": "Branch rules; the first rule matching the branch wins."
+		},
+		"bumps": {
+			"type": "object",
+			"properties": {
+				"types": {
+					"type": "object",
+					"propertyNames": {
+						"type": "string"
+					},
+					"additionalProperties": {
+						"type": "string",
+						"enum": [
+							"major",
+							"minor",
+							"patch"
+						]
+					},
+					"description": "Commit type to bump level, merged over feat: minor, fix: patch, perf: patch, revert: patch. Breaking changes bump major."
+				},
+				"preMajor": {
+					"type": "object",
+					"properties": {
+						"breaking": {
+							"type": "string",
+							"enum": [
+								"major",
+								"minor",
+								"patch"
+							]
+						},
+						"feat": {
+							"type": "string",
+							"enum": [
+								"major",
+								"minor",
+								"patch"
+							]
+						}
+					},
+					"additionalProperties": false,
+					"description": "Bump levels for breaking changes and feat while the major version is 0. Default minor for both."
+				},
+				"absorbed": {
+					"type": "string",
+					"enum": [
+						"patch",
+						"minor"
+					],
+					"description": "Level a released unit gets from bump-producing changes absorbed from unreleased dependencies: patch (default) or minor (feat and breaking give minor, fix gives patch)."
+				}
+			},
+			"additionalProperties": false,
+			"description": "How commits map to bump levels."
+		},
+		"groups": {
+			"type": "object",
+			"propertyNames": {
+				"type": "string",
+				"pattern": "^(?!\\.\\.?$)[A-Za-z0-9._-]+$"
+			},
+			"additionalProperties": {
+				"anyOf": [
+					{
+						"type": "object",
+						"properties": {
+							"units": {
+								"type": "array",
+								"items": {
+									"type": "string",
+									"pattern": "^(?!\\.\\.?$)[A-Za-z0-9._-]+$"
+								},
+								"description": "Member unit ids."
+							},
+							"tags": {
+								"type": "array",
+								"items": {
+									"type": "string"
+								},
+								"description": "Selects released units with any of these tags."
+							}
+						},
+						"required": [
+							"units"
+						],
+						"additionalProperties": false
+					},
+					{
+						"type": "object",
+						"properties": {
+							"units": {
+								"type": "array",
+								"items": {
+									"type": "string",
+									"pattern": "^(?!\\.\\.?$)[A-Za-z0-9._-]+$"
+								},
+								"description": "Member unit ids."
+							},
+							"tags": {
+								"type": "array",
+								"items": {
+									"type": "string"
+								},
+								"description": "Selects released units with any of these tags."
+							}
+						},
+						"required": [
+							"tags"
+						],
+						"additionalProperties": false
+					}
+				]
+			},
+			"description": "Fixed groups by name (unit id characters): members release together with one version. Each group needs units, tags or both.",
+			"minProperties": 1
 		}
 	},
 	"additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyrelease/cli",
-  "version": "0.1.1-beta.1",
+  "version": "0.2.0-beta.7",
   "description": "Command line interface of tallyrelease",
   "repository": {
     "type": "git",
@@ -21,6 +21,7 @@
       "default": "./dist/index.js"
     },
     "./affected.schema.json": "./dist/affected.schema.json",
+    "./plan.schema.json": "./dist/plan.schema.json",
     "./tallyrelease.schema.json": "./dist/tallyrelease.schema.json"
   },
   "bin": {
@@ -48,8 +49,9 @@
   "prettier": "@abinnovision/prettier-config",
   "dependencies": {
     "@octokit/rest": "^22.0.1",
-    "@tallyrelease/core": "^0.1.1-beta.1",
+    "@tallyrelease/core": "^0.2.0-beta.8",
     "commander": "^15.0.0",
+    "picomatch": "^4.0.7",
     "tinyglobby": "^0.2.17",
     "yaml": "^2.9.1",
     "zod": "^4.6.6"
@@ -59,6 +61,7 @@
     "@abinnovision/prettier-config": "^2.2.0",
     "@internal/tsconfig": "0.0.0",
     "@types/node": "^24.19.2",
+    "@types/picomatch": "^4.0.3",
     "@vitest/coverage-v8": "^5.0.4",
     "ajv": "^8.20.0",
     "eslint": "^10.12.0",
@@ -79,6 +82,7 @@
         "default": "./dist/index.js"
       },
       "./affected.schema.json": "./dist/affected.schema.json",
+      "./plan.schema.json": "./dist/plan.schema.json",
       "./tallyrelease.schema.json": "./dist/tallyrelease.schema.json"
     },
     "npm": true