@tallyrelease/cli 0.0.0-stage → 0.1.0-beta.1

package/dist/affected-schema.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+/** Schema of `tallyrelease affected --json`, published as `affected.schema.json`. */
+export declare const affectedDocSchema: z.ZodObject<{
+    schema: z.ZodLiteral<1>;
+    tool: z.ZodString;
+    repo: z.ZodString;
+    branch: z.ZodString;
+    head: z.ZodString;
+    build: z.ZodObject<{
+        base: z.ZodNullable<z.ZodString>;
+        baseSource: z.ZodEnum<{
+            cli: "cli";
+            "push-before": "push-before";
+            "pr-merge-base": "pr-merge-base";
+            "merge-group": "merge-group";
+            "forge-last-success": "forge-last-success";
+            none: "none";
+        }>;
+        all: z.ZodBoolean;
+        globalInputs: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    units: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodString;
+        plugin: z.ZodString;
+        reason: z.ZodEnum<{
+            direct: "direct";
+            dependent: "dependent";
+            global: "global";
+            all: "all";
+        }>;
+        via: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    unattributed: z.ZodArray<z.ZodString>;
+    warnings: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        plugin: z.ZodExactOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;

package/dist/affected-schema.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+const reason = z.enum(["direct", "dependent", "global", "all"]);
+/** Schema of `tallyrelease affected --json`, published as `affected.schema.json`. */
+export const affectedDocSchema = z.strictObject({
+    schema: z.literal(1),
+    tool: z.string(),
+    repo: z.string(),
+    branch: z.string(),
+    head: z.string(),
+    build: z.strictObject({
+        base: z.string().nullable(),
+        baseSource: z.enum([
+            "cli",
+            "push-before",
+            "pr-merge-base",
+            "merge-group",
+            "forge-last-success",
+            "none",
+        ]),
+        all: z.boolean(),
+        globalInputs: z.array(z.string()),
+    }),
+    units: z.array(z.strictObject({
+        id: z.string(),
+        path: z.string(),
+        plugin: z.string(),
+        reason,
+        via: z.array(z.string()),
+    })),
+    unattributed: z.array(z.string()),
+    warnings: z.array(z.strictObject({
+        code: z.string(),
+        message: z.string(),
+        plugin: z.string().exactOptional(),
+    })),
+});

package/dist/affected.schema.json

@@ -0,0 +1,140 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"properties": {
+		"schema": {
+			"type": "number",
+			"const": 1
+		},
+		"tool": {
+			"type": "string"
+		},
+		"repo": {
+			"type": "string"
+		},
+		"branch": {
+			"type": "string"
+		},
+		"head": {
+			"type": "string"
+		},
+		"build": {
+			"type": "object",
+			"properties": {
+				"base": {
+					"type": [
+						"string",
+						"null"
+					]
+				},
+				"baseSource": {
+					"type": "string",
+					"enum": [
+						"cli",
+						"push-before",
+						"pr-merge-base",
+						"merge-group",
+						"forge-last-success",
+						"none"
+					]
+				},
+				"all": {
+					"type": "boolean"
+				},
+				"globalInputs": {
+					"type": "array",
+					"items": {
+						"type": "string"
+					}
+				}
+			},
+			"required": [
+				"base",
+				"baseSource",
+				"all",
+				"globalInputs"
+			],
+			"additionalProperties": false
+		},
+		"units": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"properties": {
+					"id": {
+						"type": "string"
+					},
+					"path": {
+						"type": "string"
+					},
+					"plugin": {
+						"type": "string"
+					},
+					"reason": {
+						"type": "string",
+						"enum": [
+							"direct",
+							"dependent",
+							"global",
+							"all"
+						]
+					},
+					"via": {
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				},
+				"required": [
+					"id",
+					"path",
+					"plugin",
+					"reason",
+					"via"
+				],
+				"additionalProperties": false
+			}
+		},
+		"unattributed": {
+			"type": "array",
+			"items": {
+				"type": "string"
+			}
+		},
+		"warnings": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"properties": {
+					"code": {
+						"type": "string"
+					},
+					"message": {
+						"type": "string"
+					},
+					"plugin": {
+						"type": "string"
+					}
+				},
+				"required": [
+					"code",
+					"message"
+				],
+				"additionalProperties": false
+			}
+		}
+	},
+	"required": [
+		"schema",
+		"tool",
+		"repo",
+		"branch",
+		"head",
+		"build",
+		"units",
+		"unattributed",
+		"warnings"
+	],
+	"additionalProperties": false
+}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from "./main.js";
+process.exitCode = await main(process.argv.slice(2), {
+    env: process.env,
+    cwd: process.cwd(),
+    stdout: process.stdout,
+    stderr: process.stderr,
+});

package/dist/ci/base.d.ts

@@ -0,0 +1,21 @@
+import type { GithubContext } from "./github-env.js";
+import type { Forge } from "../forge/forge.js";
+import type { RepoGit } from "../git/reader.js";
+import type { BaseSource, Warning } from "@tallyrelease/core";
+export interface BuildBase {
+    base: string | null;
+    source: BaseSource;
+    warnings: Warning[];
+}
+export interface BuildBaseInput {
+    git: RepoGit;
+    /** Resolved HEAD sha. */
+    head: string;
+    /** `--base`. */
+    cliBase?: string | undefined;
+    github?: GithubContext | undefined;
+    /** Present only when a token is available. */
+    forge?: Forge | undefined;
+}
+/** Resolves the build base from `--base`, the CI event, then the forge. */
+export declare const resolveBuildBase: (input: BuildBaseInput) => Promise<BuildBase>;

package/dist/ci/base.js

@@ -0,0 +1,130 @@
+import { TallyError } from "@tallyrelease/core";
+const ZERO_SHA = /^0+$/;
+const str = (value) => typeof value === "string" && value !== "" ? value : undefined;
+const field = (value, key) => typeof value === "object" && value !== null
+    ? value[key]
+    : undefined;
+const noForge = {
+    code: "W_NO_FORGE",
+    message: "no token for the forge; the last successful run is unknown",
+};
+const noWorkflowContext = {
+    code: "W_NO_WORKFLOW_CONTEXT",
+    message: "GITHUB_REPOSITORY, GITHUB_WORKFLOW_REF or GITHUB_REF_NAME is missing; the last successful run is unknown",
+};
+const forgeError = (error) => {
+    const status = error?.status;
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+        code: "W_FORGE_ERROR",
+        message: `forge request failed${typeof status === "number" ? ` (${String(status)})` : ""}: ${reason}; the last successful run is unknown`,
+    };
+};
+const noLastSuccess = {
+    code: "W_NO_LAST_SUCCESS",
+    message: "no successful push run of this workflow on this branch",
+};
+/** Resolves the build base from `--base`, the CI event, then the forge. */
+export const resolveBuildBase = async (input) => {
+    const { git, head, github, forge } = input;
+    // A named sha missing from a shallow clone must not silently become "everything".
+    const local = async (ref, what) => {
+        const sha = await git.resolve(ref);
+        if (sha === undefined && (await git.isShallow())) {
+            throw new TallyError("E_SHALLOW_BASE", `${what} "${ref}" is missing in this shallow clone; fetch with fetch-depth: 0`, { ref });
+        }
+        return sha;
+    };
+    const required = async (ref, what) => {
+        const sha = ref === undefined ? undefined : await local(ref, what);
+        if (sha === undefined) {
+            throw new TallyError("E_BASE_UNRESOLVED", `${what} "${ref ?? ""}" does not resolve to a commit`, { ref });
+        }
+        return sha;
+    };
+    // A named sha that is not an ancestor may only be cut off by a shallow clone.
+    const shallowBase = async (ref, what) => {
+        if (await git.isShallow()) {
+            throw new TallyError("E_SHALLOW_BASE", `${what} "${ref}" has no history in common with HEAD in this shallow clone; fetch with fetch-depth: 0`, { ref });
+        }
+    };
+    /** The newest usable successful run, or the warning why there is none. */
+    const lastSuccess = async (from) => {
+        if (!github?.repository || !github.workflow || !github.refName) {
+            return noWorkflowContext;
+        }
+        let shas;
+        try {
+            shas = await from.lastSuccessfulPushRuns({
+                ...github.repository,
+                workflow: github.workflow,
+                branch: github.refName,
+            });
+        }
+        catch (error) {
+            return forgeError(error);
+        }
+        for (const candidate of shas) {
+            // eslint-disable-next-line no-await-in-loop -- newest usable run wins
+            const sha = await local(candidate, "last successful run");
+            // eslint-disable-next-line no-await-in-loop -- newest usable run wins
+            if (sha !== undefined && (await git.isAncestor(sha, head))) {
+                return sha;
+            }
+        }
+        return noLastSuccess;
+    };
+    const result = (base, source, ...warnings) => ({ base, source, warnings });
+    const fromLastSuccess = async () => {
+        if (!forge) {
+            return result(null, "none", noForge);
+        }
+        const last = await lastSuccess(forge);
+        return typeof last === "string"
+            ? result(last, "forge-last-success")
+            : result(null, "none", last);
+    };
+    if (input.cliBase !== undefined) {
+        return result(await required(input.cliBase, "--base"), "cli");
+    }
+    switch (github?.eventName) {
+        case "pull_request": {
+            const target = await required(str(field(field(github.payload()["pull_request"], "base"), "sha")), "pull_request.base.sha");
+            const base = await git.mergeBase(head, target);
+            if (base === undefined) {
+                await shallowBase(target, "pull_request.base.sha");
+                throw new TallyError("E_BASE_UNRESOLVED", `no merge base of HEAD and "${target}"`, { ref: target });
+            }
+            return result(base, "pr-merge-base");
+        }
+        case "merge_group":
+            return result(await required(str(field(github.payload()["merge_group"], "base_sha")), "merge_group.base_sha"), "merge-group");
+        case "push": {
+            const ref = str(github.payload()["before"]);
+            const before = ref === undefined || ZERO_SHA.test(ref)
+                ? undefined
+                : await local(ref, "push before");
+            if (before !== undefined && (await git.isAncestor(before, head))) {
+                if (!forge) {
+                    return result(before, "push-before", noForge);
+                }
+                const last = await lastSuccess(forge);
+                if (typeof last !== "string") {
+                    return result(before, "push-before", last);
+                }
+                return (await git.isAncestor(last, before))
+                    ? result(last, "forge-last-success")
+                    : result(before, "push-before");
+            }
+            if (before !== undefined) {
+                await shallowBase(before, "push before");
+            }
+            return await fromLastSuccess();
+        }
+        case "workflow_dispatch":
+        case "schedule":
+            return await fromLastSuccess();
+        default:
+            return result(null, "none");
+    }
+};

package/dist/ci/github-env.d.ts

@@ -0,0 +1,19 @@
+export type Env = Readonly<Record<string, string | undefined>>;
+/** GitHub Actions run context from `GITHUB_*` variables. */
+export interface GithubContext {
+    eventName: string;
+    /** Parsed `GITHUB_EVENT_PATH` (read on first call), empty when unset. */
+    payload: () => Record<string, unknown>;
+    refName: string | undefined;
+    /** Head branch of a pull request run. */
+    headRef: string | undefined;
+    /** Workflow file name from `GITHUB_WORKFLOW_REF`. */
+    workflow: string | undefined;
+    repository: {
+        owner: string;
+        repo: string;
+    } | undefined;
+    apiUrl: string | undefined;
+}
+/** Undefined outside GitHub Actions (no `GITHUB_EVENT_NAME`). */
+export declare const githubContext: (env: Env) => GithubContext | undefined;

package/dist/ci/github-env.js

@@ -0,0 +1,32 @@
+import { TallyError } from "@tallyrelease/core";
+import { readFileSync } from "node:fs";
+const nonEmpty = (value) => value === "" ? undefined : value;
+const parseEvent = (path) => {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new TallyError("E_GITHUB_EVENT", `cannot read GITHUB_EVENT_PATH "${path}": ${error instanceof Error ? error.message : String(error)}`, { path });
+    }
+};
+/** Undefined outside GitHub Actions (no `GITHUB_EVENT_NAME`). */
+export const githubContext = (env) => {
+    const eventName = env["GITHUB_EVENT_NAME"];
+    if (!eventName) {
+        return undefined;
+    }
+    const eventPath = env["GITHUB_EVENT_PATH"];
+    let payload;
+    // owner/repo/.github/workflows/ci.yaml@refs/heads/main
+    const workflowPath = env["GITHUB_WORKFLOW_REF"]?.split("@")[0];
+    const [owner, repo] = env["GITHUB_REPOSITORY"]?.split("/") ?? [];
+    return {
+        eventName,
+        payload: () => (payload ??= eventPath ? parseEvent(eventPath) : {}),
+        refName: nonEmpty(env["GITHUB_REF_NAME"]),
+        headRef: nonEmpty(env["GITHUB_HEAD_REF"]),
+        workflow: nonEmpty(workflowPath?.split("/").at(-1)),
+        repository: owner && repo ? { owner, repo } : undefined,
+        apiUrl: nonEmpty(env["GITHUB_API_URL"]),
+    };
+};

package/dist/ci/outputs.d.ts

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

package/dist/ci/outputs.js

@@ -0,0 +1,13 @@
+import { randomUUID } from "node:crypto";
+const multiline = (key, value) => {
+    const delimiter = `ghadelimiter_${randomUUID()}`;
+    return `${key}<<${delimiter}\n${value}\n${delimiter}\n`;
+};
+/** `$GITHUB_OUTPUT` entries of `affected`; units are ordered by id. */
+export const affectedGithubOutput = (doc) => [
+    `affected=${JSON.stringify(doc.units.map(({ id, path, reason }) => ({ id, path, reason })))}\n`,
+    multiline("affected-paths", doc.units.map((u) => u.path).join("\n")),
+    `all=${String(doc.build.all)}\n`,
+    `base=${doc.build.base ?? ""}\n`,
+    `base-source=${doc.build.baseSource}\n`,
+].join("");

package/dist/commands/affected.d.ts

@@ -0,0 +1,9 @@
+import type { Session } from "../session.js";
+export interface AffectedFlags {
+    base?: string;
+    json?: boolean;
+    out?: string;
+    githubOutput?: boolean;
+}
+/** Computes the build set and writes the requested outputs. */
+export declare const affected: (session: Session, flags: AffectedFlags) => Promise<void>;

package/dist/commands/affected.js

@@ -0,0 +1,54 @@
+import { computeAffected, TallyError } from "@tallyrelease/core";
+import { appendFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { resolveBuildBase } from "../ci/base.js";
+import { affectedGithubOutput } from "../ci/outputs.js";
+import { version } from "../version.js";
+/** Computes the build set and writes the requested outputs. */
+export const affected = async (session, flags) => {
+    const { git, github } = session;
+    const workspace = await session.workspace();
+    const head = await git.resolve("HEAD");
+    if (head === undefined) {
+        throw new TallyError("E_NO_HEAD", "HEAD does not resolve to a commit; the repository has no commits");
+    }
+    const base = await resolveBuildBase({
+        git,
+        head,
+        cliBase: flags.base,
+        github,
+        forge: session.forge,
+    });
+    const computed = await computeAffected(workspace, git, {
+        tool: `tallyrelease@${version}`,
+        branch: github?.headRef ?? github?.refName ?? (await git.branch()) ?? "HEAD",
+        head,
+        base: base.base,
+        baseSource: base.source,
+    });
+    const doc = {
+        ...computed,
+        warnings: [...computed.warnings, ...base.warnings],
+    };
+    session.warn(doc.warnings);
+    const json = `${JSON.stringify(doc, null, 2)}\n`;
+    if (flags.out !== undefined) {
+        writeFileSync(resolve(session.cwd, flags.out), json);
+    }
+    if (flags.githubOutput) {
+        const path = session.env["GITHUB_OUTPUT"];
+        if (!path) {
+            throw new TallyError("E_GITHUB_OUTPUT", "--github-output requires GITHUB_OUTPUT to be set");
+        }
+        appendFileSync(path, affectedGithubOutput(doc));
+    }
+    if (flags.json) {
+        session.stdout.write(json);
+        return;
+    }
+    session.stdout.write(`base: ${doc.build.base ?? "none"} (${doc.build.baseSource})\n`);
+    for (const u of doc.units) {
+        const via = u.via.length > 0 ? ` via ${u.via.join(", ")}` : "";
+        session.stdout.write(`${u.id}\t${u.path}\t${u.reason}${via}\n`);
+    }
+};

package/dist/commands/check.d.ts

@@ -0,0 +1,3 @@
+import type { Session } from "../session.js";
+/** Validates config, plugins, units and graph. */
+export declare const check: (session: Session) => Promise<void>;

package/dist/commands/check.js

@@ -0,0 +1,6 @@
+/** Validates config, plugins, units and graph. */
+export const check = async (session) => {
+    const workspace = await session.workspace();
+    session.warn(workspace.warnings);
+    session.stdout.write(`ok: ${String(workspace.units.length)} units, ${String(workspace.graph.edges.length)} edges\n`);
+};

package/dist/commands/graph.d.ts

@@ -0,0 +1,5 @@
+import type { Session } from "../session.js";
+/** Prints units and edges. */
+export declare const graph: (session: Session, flags: {
+    json?: boolean;
+}) => Promise<void>;

package/dist/commands/graph.js

@@ -0,0 +1,27 @@
+/** Prints units and edges. */
+export const graph = async (session, flags) => {
+    const workspace = await session.workspace();
+    session.warn(workspace.warnings);
+    const units = workspace.units.map((u) => ({
+        id: u.id,
+        path: u.root,
+        plugin: u.plugin,
+        version: u.version,
+    }));
+    const edges = workspace.graph.edges.map((e) => ({
+        from: e.from,
+        to: e.to,
+        pinned: e.pinned,
+        reasons: e.reasons,
+    }));
+    if (flags.json) {
+        session.stdout.write(`${JSON.stringify({ repo: workspace.repo, units, edges }, null, 2)}\n`);
+        return;
+    }
+    for (const u of units) {
+        session.stdout.write(`${u.id}\t${u.path}\t${u.plugin}\n`);
+    }
+    for (const e of edges) {
+        session.stdout.write(`${e.from} -> ${e.to}${e.pinned ? " (pinned)" : ""}\n`);
+    }
+};

package/dist/config/load.d.ts

@@ -0,0 +1,3 @@
+import type { ReadonlyFs, TallyConfig } from "@tallyrelease/core";
+/** Reads and validates the config file at the repo-relative `path`. */
+export declare const loadConfig: (fs: ReadonlyFs, path: string) => TallyConfig;

package/dist/config/load.js

@@ -0,0 +1,28 @@
+import { TallyError } from "@tallyrelease/core";
+import { parse } from "yaml";
+import { configSchema } from "./schema.js";
+/** Reads and validates the config file at the repo-relative `path`. */
+export const loadConfig = (fs, path) => {
+    const text = fs.read(path);
+    if (text === undefined) {
+        throw new TallyError("E_CONFIG_MISSING", `config file "${path}" not found`, {
+            path,
+        });
+    }
+    let raw;
+    try {
+        raw = parse(text) ?? {};
+    }
+    catch (error) {
+        throw new TallyError("E_CONFIG", `${path}: ${error instanceof Error ? error.message : String(error)}`, { path });
+    }
+    const result = configSchema.safeParse(raw);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`);
+        throw new TallyError("E_CONFIG", `${path}: ${issues.join("; ")}`, {
+            path,
+            issues: result.error.issues,
+        });
+    }
+    return result.data;
+};

package/dist/config/schema.d.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+/** Schema of `tallyrelease.yaml`. */
+export declare const configSchema: z.ZodObject<{
+    plugins: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+    defaults: z.ZodExactOptional<z.ZodObject<{
+        tagFormat: z.ZodExactOptional<z.ZodString>;
+        propagate: z.ZodExactOptional<z.ZodEnum<{
+            auto: "auto";
+            patch: "patch";
+            rebuild: "rebuild";
+        }>>;
+    }, z.core.$strict>>;
+    units: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodExactOptional<z.ZodString>;
+        include: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+        version: z.ZodExactOptional<z.ZodEnum<{
+            file: "file";
+            none: "none";
+            tag: "tag";
+        }>>;
+        scheme: z.ZodExactOptional<z.ZodString>;
+        tagFormat: z.ZodExactOptional<z.ZodString>;
+        propagate: z.ZodExactOptional<z.ZodEnum<{
+            auto: "auto";
+            patch: "patch";
+            rebuild: "rebuild";
+        }>>;
+    }, z.core.$strict>>>;
+    deps: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        pinned: z.ZodExactOptional<z.ZodBoolean>;
+        reason: z.ZodExactOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    ignore: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+    globalInputs: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;

package/dist/config/schema.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+const globs = z.array(z.string()).exactOptional();
+const propagate = z.enum(["auto", "patch", "rebuild"]);
+const unitOverlay = z.strictObject({
+    id: z.string().exactOptional(),
+    include: globs,
+    exclude: globs,
+    version: z.enum(["file", "tag", "none"]).exactOptional(),
+    scheme: z.string().exactOptional(),
+    tagFormat: z.string().exactOptional(),
+    propagate: propagate.exactOptional(),
+});
+/** Schema of `tallyrelease.yaml`. */
+export const configSchema = z.strictObject({
+    plugins: z
+        .record(z.string(), z.record(z.string(), z.unknown()).nullable())
+        .default({}),
+    defaults: z
+        .strictObject({
+        tagFormat: z.string().exactOptional(),
+        propagate: propagate.exactOptional(),
+    })
+        .exactOptional(),
+    units: z.record(z.string(), unitOverlay).exactOptional(),
+    deps: z
+        .array(z.strictObject({
+        from: z.string(),
+        to: z.string(),
+        pinned: z.boolean().exactOptional(),
+        reason: z.string().exactOptional(),
+    }))
+        .exactOptional(),
+    ignore: globs,
+    globalInputs: globs,
+});