@tallyrelease/cli 0.1.1 → 0.2.0-beta.9

package/README.md

@@ -39,9 +39,13 @@ units:
 
 Global flags: `--cwd <dir>` (repository root), `--config <file>` (default `tallyrelease.yaml`), `--token <token>` (forge token, default `GITHUB_TOKEN`), `--verbose`.
 
-- `tallyrelease check` validates config, plugins, units and graph.
+- `tallyrelease check` validates config, plugins, units, graph and release config; with released units it also checks the repository's tags.
 - `tallyrelease graph [--format text|json|mermaid] [--json]` prints units and edges.
 - `tallyrelease affected [--base <ref>] [--format text|json|tsv] [--json] [--out <file>] [--github-output] [--tag <tag>]` computes the build set. `--out` writes the affected document as JSON, `--github-output` appends outputs to `$GITHUB_OUTPUT`. `--tag` (repeatable) keeps units with any of the given tags.
+- `tallyrelease plan [--branch <name>] [--base <ref>] [--head <ref>] [--all] [--format text|json] [--json] [--out <file>] [--github-output] [--summary]` computes the release plan without changing anything: kind, base version, bump, next version and prerelease version per unit. `--head` plans another commit with the current config, `--all` also lists released units with a pending release outside the build set. `--github-output` writes `plan`, the path of the written plan (`--out`, else `$RUNNER_TEMP/tallyrelease-plan.json`). `--summary` appends a markdown summary to `$GITHUB_STEP_SUMMARY`, or prints it instead of the table when unset (exit 2 with `--json` then). The JSON schema is exported as `@tallyrelease/cli/plan.schema.json`.
+- `tallyrelease explain <unit> [--branch <name>] [--base <ref>]` explains a unit: why it is affected, which commits and files bump it (including changes absorbed from unreleased dependencies), propagation and Release-As footers.
+
+- `tallyrelease shadow [--manifest <path>] [--rp-config <path>] [--head <ref>] [--branch <name>] [--pin <spec>] [--out <file>] [--summary] [--strict]` compares tallyrelease with a release-please release: on a push that changes the release-please manifest, it plans the parent commit and compares each unit's next version with the new manifest value. See [Shadow mode](#shadow-mode).
 
 Exit codes: `0` ok, `1` error, `2` usage. For scripts use `--format tsv` or `--json`; the text layout may change between versions.
 
@@ -92,6 +96,26 @@ jobs:
       - run: echo "build ${{ matrix.unit.id }} from ${{ matrix.unit.path }}"
 ```
 
+## Shadow mode
+
+While release-please owns versions, `shadow` checks that tallyrelease would have released the same versions. Run it on pushes to the default branch:
+
+```yaml
+shadow:
+  if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+  runs-on: ubuntu-latest
+  permissions:
+    contents: read
+  steps:
+    - uses: actions/checkout@v6
+      with:
+        fetch-depth: 0
+        persist-credentials: false
+    - run: npx @tallyrelease/cli@<version> shadow --pin <version> --out shadow-report.json --summary
+```
+
+Pushes that do not change `.release-please-manifest.json` are skipped (`W_SHADOW_SKIPPED`). Each row is `match`, `mismatch`, `tallyrelease-only` or `rp-only`; known differences are labelled (`release-config`, `dependent-patch`, `absorbed-internal`, `group-vs-rp`, `separate-pr`, `squash-split`). `--strict` exits 1 on unlabelled rows. Replay an earlier release merge locally with `shadow --head <sha> --branch main`.
+
 ## Editor support
 
 `tallyrelease.yaml` has a JSON schema for completion and validation in editors using the YAML language server. Add one of these modelines as the first line.

package/dist/affected-schema.d.ts

@@ -29,6 +29,7 @@ export declare const affectedDocSchema: z.ZodObject<{
             dependent: "dependent";
             global: "global";
             all: "all";
+            group: "group";
         }>;
         via: z.ZodArray<z.ZodString>;
         released: z.ZodBoolean;
@@ -39,5 +40,6 @@ export declare const affectedDocSchema: z.ZodObject<{
         code: z.ZodString;
         message: z.ZodString;
         plugin: z.ZodExactOptional<z.ZodString>;
+        unit: z.ZodExactOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strict>;

package/dist/affected-schema.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-const reason = z.enum(["direct", "dependent", "global", "all"]);
+const reason = z.enum(["direct", "dependent", "global", "all", "group"]);
 /** Schema of `tallyrelease affected --json`, published as `affected.schema.json`. */
 export const affectedDocSchema = z.strictObject({
     schema: z.literal(1),
@@ -35,5 +35,6 @@ export const affectedDocSchema = z.strictObject({
         code: z.string(),
         message: z.string(),
         plugin: z.string().exactOptional(),
+        unit: z.string().exactOptional(),
     })),
 });

package/dist/affected.schema.json

@@ -77,7 +77,8 @@
 							"direct",
 							"dependent",
 							"global",
-							"all"
+							"all",
+							"group"
 						]
 					},
 					"via": {
@@ -127,6 +128,9 @@
 					},
 					"plugin": {
 						"type": "string"
+					},
+					"unit": {
+						"type": "string"
 					}
 				},
 				"required": [

package/dist/ci/base.d.ts

@@ -1,6 +1,7 @@
 import type { Env, GithubContext } from "./github-env.js";
 import type { Forge } from "../forge/forge.js";
 import type { RepoGit } from "../git/reader.js";
+import type { Paint } from "../output/paint.js";
 import type { BaseSource, Warning } from "@tallyrelease/core";
 export interface BuildBase {
     base: string | null;
@@ -22,3 +23,7 @@ export interface BuildBaseInput {
 }
 /** Resolves the build base from `--base`, the CI event, the forge, then the local default branch. */
 export declare const resolveBuildBase: (input: BuildBaseInput) => Promise<BuildBase>;
+/** Short description of where the build base came from. */
+export declare const baseLabel: (base: BuildBase) => string;
+/** `base` line of the `plan` and `explain` text. */
+export declare const baseLine: (paint: Paint, base: BuildBase) => string;

package/dist/ci/base.js

@@ -167,3 +167,24 @@ export const resolveBuildBase = async (input) => {
             return result(null, "none");
     }
 };
+/** Short description of where the build base came from. */
+export const baseLabel = (base) => {
+    switch (base.source) {
+        case "cli":
+            return `--base ${base.ref ?? ""}`;
+        case "push-before":
+            return "push before";
+        case "pr-merge-base":
+            return "merge base with the PR target";
+        case "merge-group":
+            return "merge group base";
+        case "forge-last-success":
+            return "last successful run";
+        case "local-merge-base":
+            return `merge base with ${base.ref ?? ""}`;
+        case "none":
+            return "everything is affected";
+    }
+};
+/** `base` line of the `plan` and `explain` text. */
+export const baseLine = (paint, base) => `${paint("bold", "base")}    ${paint("yellow", base.base?.slice(0, 7) ?? "none")} ${paint("dim", `(${baseLabel(base)})`)}`;

package/dist/ci/outputs.d.ts

@@ -1,3 +1,5 @@
 import type { AffectedDoc } from "@tallyrelease/core";
 /** `$GITHUB_OUTPUT` entries of `affected`; units are ordered by id. */
 export declare const affectedGithubOutput: (doc: AffectedDoc) => string;
+/** `$GITHUB_OUTPUT` entry of `plan`: the path of the written plan document. */
+export declare const planGithubOutput: (path: string) => string;

package/dist/ci/outputs.js

@@ -11,3 +11,5 @@ export const affectedGithubOutput = (doc) => [
     `base=${doc.build.base ?? ""}\n`,
     `base-source=${doc.build.baseSource}\n`,
 ].join("");
+/** `$GITHUB_OUTPUT` entry of `plan`: the path of the written plan document. */
+export const planGithubOutput = (path) => `plan=${path}\n`;

package/dist/ci/summary.d.ts

@@ -0,0 +1,2 @@
+/** Appends markdown to `$GITHUB_STEP_SUMMARY`; false when it is not set. */
+export declare const appendStepSummary: (env: Readonly<Record<string, string | undefined>>, markdown: string) => boolean;

package/dist/ci/summary.js

@@ -0,0 +1,10 @@
+import { appendFileSync } from "node:fs";
+/** Appends markdown to `$GITHUB_STEP_SUMMARY`; false when it is not set. */
+export const appendStepSummary = (env, markdown) => {
+    const path = env["GITHUB_STEP_SUMMARY"];
+    if (!path) {
+        return false;
+    }
+    appendFileSync(path, markdown);
+    return true;
+};

package/dist/commands/affected.js

@@ -1,36 +1,20 @@
 import { computeAffected, TallyError } from "@tallyrelease/core";
 import { appendFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { resolveBuildBase } from "../ci/base.js";
+import { baseLabel, resolveBuildBase } from "../ci/base.js";
 import { affectedGithubOutput } from "../ci/outputs.js";
 import { alignColumns } from "../output/columns.js";
 import { count } from "../output/count.js";
 import { painter } from "../output/paint.js";
+import { branchName } from "../session.js";
 import { version } from "../version.js";
 const GROUPS = [
     "all",
     "global",
     "direct",
     "dependent",
+    "group",
 ];
-const baseLabel = (base) => {
-    switch (base.source) {
-        case "cli":
-            return `--base ${base.ref ?? ""}`;
-        case "push-before":
-            return "push before";
-        case "pr-merge-base":
-            return "merge base with the PR target";
-        case "merge-group":
-            return "merge group base";
-        case "forge-last-success":
-            return "last successful run";
-        case "local-merge-base":
-            return `merge base with ${base.ref ?? ""}`;
-        case "none":
-            return "everything is affected";
-    }
-};
 const tsv = (doc) => [
     "id\tpath\treason\tvia\treleased\ttags",
     ...doc.units.map((u) => [
@@ -62,7 +46,7 @@ export const affected = async (session, flags) => {
     });
     const computed = await computeAffected(workspace, git, {
         tool: `tallyrelease@${version}`,
-        branch: github?.headRef ?? github?.refName ?? (await git.branch()) ?? "HEAD",
+        branch: await branchName(session),
         head,
         base: base.base,
         baseSource: base.source,

package/dist/commands/check.d.ts

@@ -1,3 +1,6 @@
 import type { Session } from "../session.js";
-/** Validates config, plugins, units and graph. */
+/**
+ * Validates config, plugins, units, graph and release config; with released
+ * units also the repository's tags.
+ */
 export declare const check: (session: Session) => Promise<void>;

package/dist/commands/check.js

@@ -1,11 +1,19 @@
+import { validateRelease, validateTags } from "@tallyrelease/core";
 import { count } from "../output/count.js";
-/** Validates config, plugins, units and graph. */
+/**
+ * Validates config, plugins, units, graph and release config; with released
+ * units also the repository's tags.
+ */
 export const check = async (session) => {
     const workspace = await session.workspace();
     session.warn(workspace.warnings);
+    validateRelease(workspace);
     const released = workspace.units
         .filter((u) => u.version !== "none")
         .map((u) => u.id);
+    if (released.length > 0) {
+        session.warn(validateTags(workspace, await session.git.tags()));
+    }
     const list = released.length > 0 ? `: ${released.join(", ")}` : "";
     session.stdout.write(`ok: ${count(workspace.units.length, "unit")} (${String(released.length)} released${list}), ${count(workspace.graph.edges.length, "edge")}\n`);
 };

package/dist/commands/explain.d.ts

@@ -0,0 +1,5 @@
+import type { PlanFlags } from "./plan.js";
+import type { Session } from "../session.js";
+export type ExplainFlags = Pick<PlanFlags, "branch" | "base">;
+/** Explains why a unit is affected and how its version is computed. */
+export declare const explain: (session: Session, id: string, flags: ExplainFlags) => Promise<void>;

package/dist/commands/explain.js

@@ -0,0 +1,79 @@
+import { explainUnit } from "@tallyrelease/core";
+import { planOptions } from "./plan.js";
+import { baseLine } from "../ci/base.js";
+import { alignColumns } from "../output/columns.js";
+import { painter } from "../output/paint.js";
+const short = (sha) => sha?.slice(0, 7) ?? "-";
+const releaseLine = (u, released, { group, nextSource }) => {
+    if (!released) {
+        return "not released";
+    }
+    if (u === null || u.next === null) {
+        return "nothing pending";
+    }
+    const why = group !== null && nextSource !== "bump"
+        ? `group ${group.name}, ${nextSource ?? ""}`
+        : group === null && u.releaseAs !== null
+            ? "release-as"
+            : (u.bump ?? "");
+    return `${u.from ?? "first release"} -> ${u.next} (${why})${u.version === null ? "" : `, version ${u.version}`}`;
+};
+/** Explains why a unit is affected and how its version is computed. */
+export const explain = async (session, id, flags) => {
+    const { opts, ref, base, warnings } = await planOptions(session, flags);
+    const { explanation, unit } = await session.workspaceAt(ref, async (workspace, fs) => ({
+        explanation: await explainUnit(workspace, session.git, {
+            ...opts,
+            fs,
+            unit: id,
+        }),
+        unit: workspace.units.find((u) => u.id === id),
+    }));
+    session.warn([...explanation.warnings, ...warnings]);
+    const paint = painter(session.stdout);
+    const plan = explanation.unit;
+    const affected = plan?.affected;
+    const { group } = explanation;
+    const lines = [
+        `${paint("bold", id)}  ${paint("dim", `${unit?.root ?? ""}  ${unit?.plugin ?? ""}  ${unit?.scheme ?? ""}`)}`,
+        baseLine(paint, base),
+        "",
+        `${paint("bold", "affected")}  ${affected
+            ? `${affected.reason === "group" ? `pulled by group ${group?.name ?? ""}` : affected.reason}${affected.via.length > 0 ? ` via ${affected.via.join(", ")}` : ""}`
+            : "no"}`,
+        ...explanation.files.map((f) => `  ${f}`),
+        ...(group
+            ? [
+                `${paint("bold", "group")}     ${group.name} ${paint("dim", `(${group.members.join(", ")})`)}`,
+            ]
+            : []),
+        `${paint("bold", "release")}   ${releaseLine(explanation.unit, unit?.version !== "none", explanation)}`,
+    ];
+    if (plan?.baseTag) {
+        lines.push(`  base tag ${plan.baseTag}${plan.lineBaseTag !== null && plan.lineBaseTag !== plan.baseTag ? `, line base tag ${plan.lineBaseTag}` : ""}`);
+    }
+    if (explanation.changes.length > 0) {
+        lines.push("", paint("bold", `changes (${String(explanation.changes.length)})`));
+        const rows = alignColumns(explanation.changes.map((c) => [
+            short(c.sha),
+            `${c.type || "-"}${c.breaking ? "!" : ""}`,
+            c.subject,
+            c.via === undefined ? "" : `via ${c.via}`,
+            c.releaseAs === undefined ? "" : `release-as ${c.releaseAs}`,
+        ]), { indent: 2, styles: ["yellow", undefined, undefined, "dim", "cyan"] }, paint);
+        explanation.changes.forEach((c, i) => {
+            lines.push(rows[i] ?? "", ...c.files.map((f) => `      ${paint("dim", f)}`));
+        });
+    }
+    if (explanation.propagatedFrom.length > 0) {
+        lines.push("", paint("bold", "propagated from"), ...explanation.propagatedFrom.map((p) => `  ${p.id} ${paint("dim", p.pinned === null ? "(through unreleased units)" : p.pinned ? "(pinned)" : "(unpinned)")}`));
+    }
+    if (explanation.releaseAs.length > 0) {
+        lines.push("", paint("bold", "release-as footers"), ...alignColumns(explanation.releaseAs.map((r) => [
+            short(r.sha),
+            r.qualified ? `${id}@${r.version}` : r.version,
+            r.applied ? "applied" : "ignored",
+        ]), { indent: 2, styles: ["yellow", undefined, "dim"] }, paint));
+    }
+    session.stdout.write(`${lines.join("\n")}\n`);
+};

package/dist/commands/plan.d.ts

@@ -0,0 +1,29 @@
+import type { BuildBase } from "../ci/base.js";
+import type { Session } from "../session.js";
+import type { PlanOptions, Warning } from "@tallyrelease/core";
+export interface PlanFlags {
+    branch?: string;
+    base?: string;
+    head?: string;
+    all?: boolean;
+    format?: "text" | "json";
+    json?: boolean;
+    out?: string;
+    githubOutput?: boolean;
+    summary?: boolean;
+}
+export interface PlanSetup {
+    opts: Omit<PlanOptions, "fs">;
+    /** `--head` sha, null to plan the working tree at HEAD. */
+    ref: string | null;
+    base: BuildBase;
+    /** Base warnings and `W_HEAD_BRANCH`. */
+    warnings: Warning[];
+}
+/**
+ * Plan options for `--branch`, `--base` and `--head`. With `--head` only
+ * `--base` and the local merge base apply, and files come from the commit.
+ */
+export declare const planOptions: (session: Session, flags: Pick<PlanFlags, "branch" | "base" | "head">) => Promise<PlanSetup>;
+/** Computes the release plan and writes the requested outputs. */
+export declare const plan: (session: Session, flags: PlanFlags) => Promise<void>;

package/dist/commands/plan.js

@@ -0,0 +1,161 @@
+import { TallyError } from "@tallyrelease/core";
+import { appendFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { baseLabel, baseLine, resolveBuildBase } from "../ci/base.js";
+import { planGithubOutput } from "../ci/outputs.js";
+import { appendStepSummary } from "../ci/summary.js";
+import { alignColumns } from "../output/columns.js";
+import { count } from "../output/count.js";
+import { painter } from "../output/paint.js";
+import { branchName } from "../session.js";
+import { version } from "../version.js";
+const lineLabel = (line, branch) => line === null
+    ? `${branch} (no branch rule)`
+    : `${branch} (rule ${line.rule}, ${line.kind} line${line.channel === null ? "" : `, channel ${line.channel}`}${line.maxBump === null ? "" : `, max bump ${line.maxBump}`}${line.absolute === null ? "" : `, base ${String(line.absolute.major)}.${line.absolute.minor === undefined ? "x" : String(line.absolute.minor)} of ${line.absolute.unit ?? line.absolute.group ?? ""}`})`;
+const text = (session, doc, base) => {
+    const paint = painter(session.stdout);
+    const lines = [
+        `${paint("bold", "branch")}  ${lineLabel(doc.line, doc.branch)}`,
+        baseLine(paint, base),
+        "",
+    ];
+    if (doc.units.length === 0) {
+        lines.push("no units planned");
+        return `${lines.join("\n")}\n`;
+    }
+    const grouped = doc.units.some((u) => u.group !== null);
+    const table = [
+        [
+            "UNIT",
+            ...(grouped ? ["GROUP"] : []),
+            "KIND",
+            "FROM",
+            "BUMP",
+            "NEXT",
+            "VERSION",
+        ],
+        ...doc.units.map((u) => [
+            u.id,
+            ...(grouped ? [u.group ?? "-"] : []),
+            u.kind,
+            u.from ?? "-",
+            u.bump ?? "-",
+            u.next ?? "-",
+            u.version ?? "-",
+        ]),
+    ];
+    // Header is aligned unstyled so column styles do not apply to it.
+    const [header = ""] = alignColumns(table);
+    const [, ...rows] = alignColumns(table, { styles: grouped ? [undefined, "dim", "cyan"] : [undefined, "cyan"] }, paint);
+    const kinds = ["prerelease", "rebuild", "none"]
+        .map((kind) => [kind, doc.units.filter((u) => u.kind === kind).length])
+        .filter(([, n]) => n !== 0)
+        .map(([kind, n]) => `${String(n)} ${String(kind)}`);
+    lines.push(paint("bold", header), ...rows, "", `${count(doc.units.length, "unit")} planned: ${kinds.join(", ")}`);
+    return `${lines.join("\n")}\n`;
+};
+const markdown = (doc, base) => {
+    const lines = [
+        "### tallyrelease plan",
+        "",
+        `Branch ${lineLabel(doc.line, doc.branch)}.`,
+        "",
+        `Base ${base.base?.slice(0, 7) ?? "none"} (${baseLabel(base)}).`,
+        "",
+    ];
+    if (doc.units.length === 0) {
+        lines.push("No units planned.");
+    }
+    else {
+        const grouped = doc.units.some((u) => u.group !== null);
+        lines.push(`| Unit |${grouped ? " Group |" : ""} Kind | From | Bump | Next | Version |`, `| :-- |${grouped ? " :-- |" : ""} :-- | :-- | :-- | :-- | :-- |`, ...doc.units.map((u) => `| ${u.id} |${grouped ? ` ${u.group ?? "-"} |` : ""} ${u.kind} | ${u.from ?? "-"} | ${u.bump ?? "-"} | ${u.next ?? "-"} | ${u.version ?? "-"} |`));
+    }
+    if (doc.warnings.length > 0) {
+        lines.push("", "Warnings:", "", ...doc.warnings.map((w) => `- ${w.code}: ${w.message}`));
+    }
+    return `${lines.join("\n")}\n`;
+};
+/**
+ * Plan options for `--branch`, `--base` and `--head`. With `--head` only
+ * `--base` and the local merge base apply, and files come from the commit.
+ */
+export const planOptions = async (session, flags) => {
+    const { git } = session;
+    const current = await git.resolve("HEAD");
+    if (current === undefined) {
+        // Surfaces E_NOT_A_REPO and E_NOT_REPO_ROOT first.
+        await session.workspace();
+        throw new TallyError("E_NO_HEAD", "HEAD does not resolve to a commit; the repository has no commits");
+    }
+    const head = flags.head === undefined ? current : await git.resolve(flags.head);
+    if (head === undefined) {
+        throw new TallyError("E_HEAD_UNRESOLVED", `--head "${flags.head ?? ""}" does not resolve to a commit`, { ref: flags.head });
+    }
+    const replay = flags.head !== undefined;
+    const base = await resolveBuildBase({
+        git,
+        head,
+        env: replay ? {} : session.env,
+        cliBase: flags.base,
+        github: replay ? undefined : session.github,
+        forge: replay ? undefined : session.forge,
+    });
+    const branch = flags.branch ?? (await branchName(session));
+    const headBranch = replay && flags.branch === undefined
+        ? [
+            {
+                code: "W_HEAD_BRANCH",
+                message: `planning --head under the branch rule for "${branch}"; pass --branch to choose`,
+            },
+        ]
+        : [];
+    return {
+        opts: {
+            tool: `tallyrelease@${version}`,
+            branch,
+            head,
+            base: base.base,
+            baseSource: base.source,
+        },
+        ref: replay ? head : null,
+        base,
+        warnings: [...base.warnings, ...headBranch],
+    };
+};
+/** Computes the release plan and writes the requested outputs. */
+export const plan = async (session, flags) => {
+    const { opts, ref, base, warnings } = await planOptions(session, flags);
+    const planned = await session.planAt(ref, {
+        ...opts,
+        all: flags.all ?? false,
+    });
+    const doc = { ...planned, warnings: [...planned.warnings, ...warnings] };
+    session.warn(doc.warnings);
+    const json = `${JSON.stringify(doc, null, 2)}\n`;
+    const out = flags.out === undefined ? undefined : resolve(session.cwd, flags.out);
+    if (out !== undefined) {
+        writeFileSync(out, json);
+    }
+    if (flags.githubOutput) {
+        const outputPath = session.env["GITHUB_OUTPUT"];
+        if (!outputPath) {
+            throw new TallyError("E_GITHUB_OUTPUT", "--github-output requires GITHUB_OUTPUT to be set");
+        }
+        const temp = session.env["RUNNER_TEMP"];
+        if (out === undefined && !temp) {
+            throw new TallyError("E_GITHUB_OUTPUT", "--github-output requires --out or RUNNER_TEMP to be set");
+        }
+        const path = out ?? join(temp ?? "", "tallyrelease-plan.json");
+        if (out === undefined) {
+            writeFileSync(path, json);
+        }
+        appendFileSync(outputPath, planGithubOutput(path));
+    }
+    const appended = flags.summary && appendStepSummary(session.env, markdown(doc, base));
+    const format = flags.format ?? (flags.json ? "json" : "text");
+    session.stdout.write(format === "json"
+        ? json
+        : flags.summary && !appended
+            ? markdown(doc, base)
+            : text(session, doc, base));
+};

package/dist/commands/shadow.d.ts

@@ -0,0 +1,37 @@
+import type { Session } from "../session.js";
+import type { ShadowRow } from "../shadow/compare.js";
+import type { Warning } from "@tallyrelease/core";
+export interface ShadowFlags {
+    manifest?: string;
+    rpConfig?: string;
+    head?: string;
+    branch?: string;
+    pin?: string;
+    out?: string;
+    summary?: boolean;
+    strict?: boolean;
+}
+/** `tallyrelease shadow --out`, schema 1. */
+export interface ShadowReport {
+    schema: 1;
+    tool: string;
+    /** `--pin`. */
+    pin: string | null;
+    /** `GITHUB_SHA`. */
+    sha: string | null;
+    /** True with `--head`, or when `head` is not `GITHUB_SHA`. */
+    replay: boolean;
+    branch: string;
+    head: string;
+    /** `HEAD^1`, the planned commit; null for a root commit. */
+    planned: string | null;
+    manifest: string;
+    skipped: {
+        reason: "manifest" | "cap";
+        message: string;
+    } | null;
+    rows: ShadowRow[];
+    warnings: Warning[];
+}
+/** Compares the plan before a release-please merge with its manifest change. */
+export declare const shadow: (session: Session, flags: ShadowFlags) => Promise<void>;