@intentius/chant 0.124.27 → 0.124.29

package/dist/lifecycle/delivery-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-metrics.d.ts","sourceRoot":"","sources":["../../src/lifecycle/delivery-metrics.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/delivery-metrics.js

@@ -0,0 +1,145 @@
+/**
+ * The four DORA metrics of one environment's deploy records (#4039): how
+ * often it deploys, the lead time from commit to running release, the change
+ * failure rate and the time to restore.
+ *
+ * Everything here is pure. The caller reads the ledgers, the release files
+ * and the ci tags, and hands this module one environment's records with
+ * lookups for the rest; `workspace/delivery-metrics.ts` does that for
+ * `chant workspace metrics`.
+ *
+ * A deploy is one record in `<env>/releases.jsonl`: one component deployed
+ * once. A redeploy, which puts the running release back, is counted apart and
+ * is not a deploy for the metrics. A deploy fails when, within the failure window after it, the commit
+ * it deployed is revoked (a counted `ci/revoked/<sha>` tag, #4033) or the
+ * environment is rolled back from it. Which records are rollbacks, and which
+ * put the current release back, is decided in {@link rollbackOf} and
+ * {@link isRedeploy} and nowhere else, so a new kind of rollback record
+ * (#4035) changes those two functions only.
+ */
+/** The failure window when the declaration's `metrics.failureWindowDays` is not set. */
+export const DEFAULT_FAILURE_WINDOW_DAYS = 7;
+const DAY_MS = 86400000;
+/**
+ * The earlier deploy a rollback record restores, or null when the record is
+ * not a rollback. Today a rollback is a record `chant components rollback`
+ * wrote, which names what it restores in `restores` (#2531). Every rule below
+ * that asks whether a record rolled an environment back asks this function.
+ */
+export function rollbackOf(record) {
+    return record.restores ?? null;
+}
+/**
+ * Whether the record put the current release back (`chant components
+ * redeploy`, #2604). A redeploy deploys the same release again, so it neither
+ * restores a failed deploy nor stands between a deploy and its rollback.
+ */
+export function isRedeploy(record) {
+    return record.redeploys !== undefined;
+}
+function median(values) {
+    if (values.length === 0)
+        return null;
+    const s = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(s.length / 2);
+    return Math.round(s.length % 2 === 1 ? s[mid] : (s[mid - 1] + s[mid]) / 2);
+}
+const at = (iso) => Date.parse(iso);
+const ref = (r) => ({ runId: r.runId, timestamp: r.timestamp });
+/**
+ * The metrics of one environment's records. `records` is the whole ledger of
+ * the environment, every component, in ledger order: deploys before the
+ * window still decide lead times, and deploys after a failure decide its
+ * restore. Only deploys whose `timestamp` falls in `window` are counted.
+ */
+export function environmentMetrics(env, records, lookups, window, failureWindowDays = DEFAULT_FAILURE_WINDOW_DAYS) {
+    // Ledger order breaks timestamp ties, as `latestPerComponent` does.
+    const sorted = records.map((r, i) => ({ r, i })).sort((a, b) => at(a.r.timestamp) - at(b.r.timestamp) || a.i - b.i).map((x) => x.r);
+    const since = at(window.since);
+    const until = at(window.until);
+    const failureMs = failureWindowDays * DAY_MS;
+    const inWindow = (r) => at(r.timestamp) >= since && at(r.timestamp) <= until;
+    const facts = sorted.map((r) => {
+        const releaseDigest = lookups.releaseOf(r) ?? null;
+        const commit = (releaseDigest !== null ? lookups.commitOfRelease(releaseDigest) : null) ?? r.gitSha;
+        return { r, releaseDigest, commit, revocation: lookups.revocationOf(commit) };
+    });
+    // A redeploy puts the running release back: it is counted apart, and
+    // neither fails nor restores on its own.
+    const deployments = facts.filter((f) => inWindow(f.r) && !isRedeploy(f.r));
+    const failures = [];
+    for (const [i, f] of facts.entries()) {
+        if (!inWindow(f.r) || isRedeploy(f.r))
+            continue;
+        const t = at(f.r.timestamp);
+        const later = facts.slice(i + 1).filter((g) => g.r.component === f.r.component);
+        // Revoked within the window after the deploy. A tag with no time, or one
+        // made before the deploy, revokes what was deployed all the same.
+        const revoked = f.revocation !== null && (f.revocation.tagged === null || at(f.revocation.tagged) - t <= failureMs) ? f.revocation : null;
+        // Rolled back from it: the next deploy of the component that is not a
+        // redeploy is a rollback, within the window.
+        const next = later.find((g) => !isRedeploy(g.r));
+        const rolledBack = next !== undefined && rollbackOf(next.r) !== null && at(next.r.timestamp) - t <= failureMs ? next.r : null;
+        if (!revoked && !rolledBack)
+            continue;
+        const restore = later.find((g) => !isRedeploy(g.r) && g.revocation === null);
+        failures.push({
+            component: f.r.component,
+            timestamp: f.r.timestamp,
+            runId: f.r.runId,
+            releaseDigest: f.releaseDigest,
+            label: f.releaseDigest !== null ? lookups.labelOf(f.releaseDigest) : null,
+            commit: f.commit,
+            causes: [...(revoked ? ["revoked"] : []), ...(rolledBack ? ["rolled-back"] : [])],
+            revoked,
+            rolledBackBy: rolledBack ? ref(rolledBack) : null,
+            restoredBy: restore ? ref(restore.r) : null,
+            restoreSeconds: restore ? Math.round((at(restore.r.timestamp) - t) / 1000) : null,
+        });
+    }
+    // Lead time: one change per release, or per commit deployed from no
+    // release, timed at its first deploy in this environment.
+    const firstDeploy = new Map();
+    for (const f of facts) {
+        const key = f.releaseDigest !== null ? `release:${f.releaseDigest}` : `commit:${f.r.gitSha}`;
+        if (!firstDeploy.has(key))
+            firstDeploy.set(key, f);
+    }
+    const leads = [];
+    let fromRelease = 0;
+    let unknown = 0;
+    for (const f of firstDeploy.values()) {
+        if (!inWindow(f.r))
+            continue;
+        const committed = lookups.commitTime(f.commit);
+        if (committed === null) {
+            unknown++;
+            continue;
+        }
+        leads.push(Math.max(0, (at(f.r.timestamp) - committed) / 1000));
+        if (f.releaseDigest !== null)
+            fromRelease++;
+    }
+    const weeks = Math.max(until - since, DAY_MS) / (7 * DAY_MS);
+    const restored = failures.filter((x) => x.restoreSeconds !== null);
+    return {
+        env,
+        deployments: {
+            count: deployments.length,
+            redeploys: facts.filter((f) => inWindow(f.r) && isRedeploy(f.r)).length,
+            runs: new Set(deployments.map((f) => f.r.runId)).size,
+            fromRelease: deployments.filter((f) => f.releaseDigest !== null).length,
+            perWeek: Math.round((deployments.length / weeks) * 100) / 100,
+        },
+        leadTime: { changes: leads.length, fromRelease, fromCommit: leads.length - fromRelease, unknown, medianSeconds: median(leads) },
+        changeFailure: {
+            deployments: deployments.length,
+            failed: failures.length,
+            revoked: failures.filter((x) => x.revoked !== null).length,
+            rolledBack: failures.filter((x) => x.rolledBackBy !== null).length,
+            rate: deployments.length === 0 ? null : Math.round((failures.length / deployments.length) * 10000) / 10000,
+        },
+        restore: { restored: restored.length, open: failures.length - restored.length, medianSeconds: median(restored.map((x) => x.restoreSeconds)) },
+        failures,
+    };
+}

package/dist/lifecycle/deploy-outcome.d.ts

@@ -0,0 +1,81 @@
+/**
+ * What a promote, rollback or redeploy left behind when it did not deploy
+ * every component it planned (#4035).
+ *
+ * The release ledger records a component only once its deploy succeeded, so
+ * after a run that applied partly it still names the earlier release for
+ * every component that failed, and nothing says that component may be
+ * running part of the new one. A deploy outcome is the record of that run:
+ * one line per run in `<env>/outcomes.jsonl` on `chant/lifecycle`, beside
+ * the environment's `releases.jsonl` and under the same member prefix,
+ * naming each planned component and what happened to it.
+ *
+ * It is written only when the run ended with some components deployed and
+ * others not, or with a component that failed. A run that stopped at a gate
+ * before deploying anything changed nothing in the environment; its pending
+ * gate is what `workspace status` shows for it.
+ *
+ * The file is append-only, like the release ledger. Whether the environment
+ * is still mixed is derived when it is read ({@link ./mixed-environment.ts}):
+ * a component the outcome names as failed or gated stays unsettled until the
+ * release ledger has a newer record of it, which a redeploy, a rollback or
+ * the same promote run again writes.
+ */
+import type { PromotionPlan } from "../components/promote.js";
+import type { DriverRunResult } from "../components/driver.js";
+/** The file a deploy outcome is appended to, under the environment's directory. */
+export declare const OUTCOMES_FILE = "outcomes.jsonl";
+/** What a run did to one component it planned. */
+export type DeployOutcomeState = "deployed" | "failed" | "gated" | "not-run";
+export interface DeployOutcomeComponent {
+    component: string;
+    /** `deployed` (a release record was written), `failed`, `gated` (stopped at a gate after the steps before it ran), or `not-run`. */
+    outcome: DeployOutcomeState;
+    /** The artifact digest the run was deploying. */
+    digest: string;
+    /** The release the run was deploying for this component, or null when it named none. */
+    releaseDigest: string | null;
+}
+/** One line of `<env>/outcomes.jsonl`. */
+export interface DeployOutcome {
+    version: 1;
+    env: string;
+    verb: "promote" | "rollback" | "redeploy";
+    /** The run id the run's release records carry. */
+    runId: string;
+    /** The timestamp the run's release records carry. */
+    timestamp: string;
+    actor: string;
+    /** The release the run deployed under (`--release`), or null. */
+    releaseDigest: string | null;
+    /** How the run ended. */
+    status: "fail" | "gated";
+    components: DeployOutcomeComponent[];
+}
+/**
+ * The outcome to record for a run, or null when there is nothing to record:
+ * every planned component deployed, or the run stopped at a gate with
+ * nothing deployed and nothing failed.
+ */
+export declare function deployOutcomeOf(input: {
+    verb: DeployOutcome["verb"];
+    plan: PromotionPlan;
+    run: Pick<DriverRunResult, "status" | "results">;
+    /** The release the run deployed under, if any. */
+    releaseDigest: string | null;
+    runId: string;
+    timestamp: string;
+    actor: string;
+}): DeployOutcome | null;
+/** Parse the lines of an `outcomes.jsonl`, oldest first. A line that is not an outcome is counted and skipped. */
+export declare function parseDeployOutcomes(text: string | null): {
+    outcomes: DeployOutcome[];
+    malformed: number;
+};
+/** Append one outcome to `<env>/outcomes.jsonl`. Does not push; the caller pushes with the release records. */
+export declare function appendDeployOutcome(outcome: DeployOutcome, opts?: {
+    cwd?: string;
+}): Promise<string>;
+/** Every outcome recorded for `env`, oldest first, read where `readReleaseLedger` reads; `[]` when none is. */
+export declare function readDeployOutcomes(env: string, opts?: import("./git.js").LedgerLocation): Promise<DeployOutcome[]>;
+//# sourceMappingURL=deploy-outcome.d.ts.map

package/dist/lifecycle/deploy-outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-outcome.d.ts","sourceRoot":"","sources":["../../src/lifecycle/deploy-outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,mFAAmF;AACnF,eAAO,MAAM,aAAa,mBAAmB,CAAC;AAE9C,kDAAkD;AAClD,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE7E,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,oIAAoI;IACpI,OAAO,EAAE,kBAAkB,CAAC;IAC5B,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,CAAC,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;IAC1C,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,yBAAyB;IACzB,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,UAAU,EAAE,sBAAsB,EAAE,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5B,IAAI,EAAE,aAAa,CAAC;IACpB,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC;IACjD,kDAAkD;IAClD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,aAAa,GAAG,IAAI,CA2BvB;AAkBD,kHAAkH;AAClH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG;IAAE,QAAQ,EAAE,aAAa,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAazG;AAED,+GAA+G;AAC/G,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1G;AAED,+GAA+G;AAC/G,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAGrH"}

package/dist/lifecycle/deploy-outcome.js

@@ -0,0 +1,101 @@
+/**
+ * What a promote, rollback or redeploy left behind when it did not deploy
+ * every component it planned (#4035).
+ *
+ * The release ledger records a component only once its deploy succeeded, so
+ * after a run that applied partly it still names the earlier release for
+ * every component that failed, and nothing says that component may be
+ * running part of the new one. A deploy outcome is the record of that run:
+ * one line per run in `<env>/outcomes.jsonl` on `chant/lifecycle`, beside
+ * the environment's `releases.jsonl` and under the same member prefix,
+ * naming each planned component and what happened to it.
+ *
+ * It is written only when the run ended with some components deployed and
+ * others not, or with a component that failed. A run that stopped at a gate
+ * before deploying anything changed nothing in the environment; its pending
+ * gate is what `workspace status` shows for it.
+ *
+ * The file is append-only, like the release ledger. Whether the environment
+ * is still mixed is derived when it is read ({@link ./mixed-environment.ts}):
+ * a component the outcome names as failed or gated stays unsettled until the
+ * release ledger has a newer record of it, which a redeploy, a rollback or
+ * the same promote run again writes.
+ */
+import { sortedJsonReplacer } from "../utils.js";
+/** The file a deploy outcome is appended to, under the environment's directory. */
+export const OUTCOMES_FILE = "outcomes.jsonl";
+/**
+ * The outcome to record for a run, or null when there is nothing to record:
+ * every planned component deployed, or the run stopped at a gate with
+ * nothing deployed and nothing failed.
+ */
+export function deployOutcomeOf(input) {
+    const { plan, run } = input;
+    if (run.status === "ok")
+        return null;
+    const components = plan.items.map((item) => {
+        const result = run.results.find((r) => r.component === item.component);
+        const outcome = !result ? "not-run" : result.status === "ok" ? "deployed" : result.status === "gated" ? "gated" : "failed";
+        return {
+            component: item.component,
+            outcome,
+            digest: item.digest,
+            releaseDigest: input.releaseDigest ?? item.source.releaseDigest ?? null,
+        };
+    });
+    const deployed = components.some((c) => c.outcome === "deployed");
+    const failed = components.some((c) => c.outcome === "failed");
+    if (!deployed && !failed)
+        return null;
+    return {
+        version: 1,
+        env: plan.to,
+        verb: input.verb,
+        runId: input.runId,
+        timestamp: input.timestamp,
+        actor: input.actor,
+        releaseDigest: input.releaseDigest,
+        status: run.status,
+        components,
+    };
+}
+const STATES = ["deployed", "failed", "gated", "not-run"];
+function isOutcome(v) {
+    const o = v;
+    return (o !== null &&
+        typeof o === "object" &&
+        o.version === 1 &&
+        typeof o.env === "string" &&
+        typeof o.runId === "string" &&
+        typeof o.timestamp === "string" &&
+        Array.isArray(o.components) &&
+        o.components.every((c) => c && typeof c.component === "string" && STATES.includes(c.outcome) && typeof c.digest === "string"));
+}
+/** Parse the lines of an `outcomes.jsonl`, oldest first. A line that is not an outcome is counted and skipped. */
+export function parseDeployOutcomes(text) {
+    const outcomes = [];
+    let malformed = 0;
+    for (const line of (text ?? "").split("\n").map((l) => l.trim()).filter(Boolean)) {
+        try {
+            const parsed = JSON.parse(line);
+            if (isOutcome(parsed))
+                outcomes.push(parsed);
+            else
+                malformed++;
+        }
+        catch {
+            malformed++;
+        }
+    }
+    return { outcomes, malformed };
+}
+/** Append one outcome to `<env>/outcomes.jsonl`. Does not push; the caller pushes with the release records. */
+export async function appendDeployOutcome(outcome, opts) {
+    const { appendLedgerLine } = await import("./git.js");
+    return appendLedgerLine(outcome.env, OUTCOMES_FILE, JSON.stringify(outcome, sortedJsonReplacer), "Deploy outcome", opts);
+}
+/** Every outcome recorded for `env`, oldest first, read where `readReleaseLedger` reads; `[]` when none is. */
+export async function readDeployOutcomes(env, opts) {
+    const { readBlobFromPath } = await import("./git.js");
+    return parseDeployOutcomes(await readBlobFromPath(env, OUTCOMES_FILE, opts)).outcomes;
+}

package/dist/lifecycle/gate-change-set.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Store the change set a gate binds (#4022), mapped onto the member's graph.
+ *
+ * {@link storeGateChangeSet} is what a gate that binds a change-set document's
+ * digest calls before it decides the gate: `components pr-apply`, and
+ * `components promote --release` before it decides a release gate or writes
+ * an `empty` resolution (#4045). It reads the member's
+ * graph the way `chant workspace graph` reads it, from the member's own
+ * `chant graph --format ir`, maps each entry onto a node
+ * (`../change-set-graph.ts`), and stores the document under its digest
+ * (`./change-set-store.ts`).
+ *
+ * Each entry mapped onto a node that has a source location also records that
+ * file from the repository root as `source` (#4025), which the overlap report
+ * in `workspace status` attributes the entry to work items by.
+ *
+ * The graph is read only when the digest is not stored yet. A graph that
+ * can't be read never stops the gate: the document is stored with `graph:
+ * null` and every `node` null, and the caller gets a warning to print.
+ */
+import type { ChangeSetDocument, ChangeSetGraph } from "../change-set.js";
+/**
+ * Reads the node ids of the graph of the project at `projectDir`, with each
+ * node's source file (relative to `projectDir`) when the graph gives one.
+ */
+export type GraphIdReader = (projectDir: string) => Promise<{
+    ids: string[];
+    sources?: Record<string, string>;
+} | {
+    error: string;
+}>;
+/**
+ * The node ids of `chant graph --format ir` in `projectDir`, run under the
+ * chant that directory resolves (its own `node_modules/.bin/chant`, else this
+ * one), as `chant workspace graph` runs each member. `args` are passed after
+ * `graph --format ir`, such as the run's `--param` flags.
+ */
+export declare function readGraphIds(projectDir: string, args?: readonly string[]): Promise<{
+    ids: string[];
+    sources: Record<string, string>;
+} | {
+    error: string;
+}>;
+/**
+ * Replace how a gate reads the graph wherever the default is taken, such as
+ * in `components pr-apply`; `undefined` restores {@link readGraphIds}. For
+ * tests that drive a gate and read node ids in process, so they don't start a
+ * `chant graph` child process (`gate-change-set.e2e.test.ts` covers that one).
+ */
+export declare function setGraphIdReader(reader: GraphIdReader | undefined): void;
+/** The graph reader a gate uses: the one {@link setGraphIdReader} set, else {@link readGraphIds} with `args`. */
+export declare function gateGraphReader(args?: readonly string[]): GraphIdReader;
+export interface StoreGateChangeSetInput {
+    /** The document whose `digest` the gate binds. */
+    doc: ChangeSetDocument;
+    /** The member's directory: where the graph is read and whose ledger it is stored in. */
+    cwd: string;
+    /** The commit the document was planned at, recorded as the graph's `at`. */
+    at?: string | null;
+    /** How to read the graph. Defaults to {@link gateGraphReader}. */
+    readGraph?: GraphIdReader;
+}
+export interface StoreGateChangeSetResult {
+    digest: string;
+    /** True when this call wrote the document; false when it was stored already. */
+    written: boolean;
+    /** The graph the stored document's nodes come from, null when none could be read. Absent when it was stored already. */
+    graph?: ChangeSetGraph | null;
+    /** Why no graph was read, when none was. */
+    warning?: string;
+}
+/**
+ * Store `doc` under its digest in the member's ledger at `cwd`, mapped onto
+ * the member's graph, unless it is stored already. Does not push; the gate's
+ * pending fact or resolution pushes the branch after it.
+ */
+export declare function storeGateChangeSet(input: StoreGateChangeSetInput): Promise<StoreGateChangeSetResult>;
+//# sourceMappingURL=gate-change-set.d.ts.map

package/dist/lifecycle/gate-change-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-change-set.d.ts","sourceRoot":"","sources":["../../src/lifecycle/gate-change-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAIvE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAIrI;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,SAAS,MAAM,EAAO,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAgCpK;AAID;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,CAExE;AAED,iHAAiH;AACjH,wBAAgB,eAAe,CAAC,IAAI,GAAE,SAAS,MAAM,EAAO,GAAG,aAAa,CAE3E;AAED,MAAM,WAAW,uBAAuB;IACtC,kDAAkD;IAClD,GAAG,EAAE,iBAAiB,CAAC;IACvB,wFAAwF;IACxF,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,kEAAkE;IAClE,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAC;IACjB,wHAAwH;IACxH,KAAK,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAuBD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAuB1G"}

package/dist/lifecycle/gate-change-set.js

@@ -0,0 +1,138 @@
+/**
+ * Store the change set a gate binds (#4022), mapped onto the member's graph.
+ *
+ * {@link storeGateChangeSet} is what a gate that binds a change-set document's
+ * digest calls before it decides the gate: `components pr-apply`, and
+ * `components promote --release` before it decides a release gate or writes
+ * an `empty` resolution (#4045). It reads the member's
+ * graph the way `chant workspace graph` reads it, from the member's own
+ * `chant graph --format ir`, maps each entry onto a node
+ * (`../change-set-graph.ts`), and stores the document under its digest
+ * (`./change-set-store.ts`).
+ *
+ * Each entry mapped onto a node that has a source location also records that
+ * file from the repository root as `source` (#4025), which the overlap report
+ * in `workspace status` attributes the entry to work items by.
+ *
+ * The graph is read only when the digest is not stored yet. A graph that
+ * can't be read never stops the gate: the document is stored with `graph:
+ * null` and every `node` null, and the caller gets a warning to print.
+ */
+import { execFileSync, spawn } from "node:child_process";
+import { posix } from "node:path";
+import { mapChangeSetToGraph } from "../change-set-graph.js";
+import { persistChangeSet, readStoredChangeSet } from "./change-set-store.js";
+import { resolveMemberLedger } from "./member-ledger.js";
+const GRAPH_TIMEOUT_MS = 300000;
+/**
+ * The node ids of `chant graph --format ir` in `projectDir`, run under the
+ * chant that directory resolves (its own `node_modules/.bin/chant`, else this
+ * one), as `chant workspace graph` runs each member. `args` are passed after
+ * `graph --format ir`, such as the run's `--param` flags.
+ */
+export async function readGraphIds(projectDir, args = []) {
+    const { readerToolchain, resolveToolchain } = await import("../workspace/member-commands.js");
+    const { readMemberIr } = await import("../workspace/compose-graph.js");
+    const { findWorkspaceRoot } = await import("../project-root.js");
+    const root = findWorkspaceRoot(projectDir)?.dir ?? projectDir;
+    const toolchain = resolveToolchain(projectDir, root, readerToolchain());
+    const [command, ...pre] = toolchain.command;
+    const out = await new Promise((resolveRun) => {
+        const child = spawn(command, [...pre, "graph", "--format", "ir", ...args], { cwd: projectDir, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => child.kill("SIGKILL"), GRAPH_TIMEOUT_MS);
+        child.stdout.on("data", (d) => (stdout += d));
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolveRun({ code: null, stdout, stderr: err.message });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolveRun({ code, stdout, stderr });
+        });
+    });
+    if (out.code !== 0) {
+        const line = out.stderr.split("\n").map((l) => l.trim()).find(Boolean);
+        return { error: `chant graph --format ir exited ${out.code ?? "on a signal"}${line ? `: ${line}` : ""}` };
+    }
+    const read = readMemberIr(out.stdout);
+    if ("reason" in read)
+        return { error: read.reason.message };
+    const sources = {};
+    for (const n of read.ir.nodes)
+        if (n.sourceLoc?.file)
+            sources[n.id] = n.sourceLoc.file;
+    return { ids: read.ir.nodes.map((n) => n.id), sources };
+}
+let graphReaderOverride;
+/**
+ * Replace how a gate reads the graph wherever the default is taken, such as
+ * in `components pr-apply`; `undefined` restores {@link readGraphIds}. For
+ * tests that drive a gate and read node ids in process, so they don't start a
+ * `chant graph` child process (`gate-change-set.e2e.test.ts` covers that one).
+ */
+export function setGraphIdReader(reader) {
+    graphReaderOverride = reader;
+}
+/** The graph reader a gate uses: the one {@link setGraphIdReader} set, else {@link readGraphIds} with `args`. */
+export function gateGraphReader(args = []) {
+    return graphReaderOverride ?? ((dir) => readGraphIds(dir, args));
+}
+/**
+ * Each node's source file as a path from the repository root (#4025): the
+ * graph gives it relative to the member's directory at `cwd`. Undefined when
+ * the graph gives none or `cwd` is in no git repository.
+ */
+function repoSources(cwd, sources) {
+    if (!sources || Object.keys(sources).length === 0)
+        return undefined;
+    let prefix;
+    try {
+        prefix = execFileSync("git", ["rev-parse", "--show-prefix"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return undefined;
+    }
+    const out = new Map();
+    for (const [id, file] of Object.entries(sources)) {
+        const path = posix.normalize(posix.join(prefix, file.split("\\").join("/")));
+        if (!path.startsWith("../") && path !== "..")
+            out.set(id, path);
+    }
+    return out;
+}
+/**
+ * Store `doc` under its digest in the member's ledger at `cwd`, mapped onto
+ * the member's graph, unless it is stored already. Does not push; the gate's
+ * pending fact or resolution pushes the branch after it.
+ */
+export async function storeGateChangeSet(input) {
+    const { doc, cwd } = input;
+    const loc = { cwd };
+    if ((await readStoredChangeSet(doc.digest, loc)).status !== "missing")
+        return { digest: doc.digest, written: false };
+    const ledger = await resolveMemberLedger(cwd);
+    const member = ledger.members.length > 0 ? ledger.members.join("/") : null;
+    let nodes = null;
+    let warning;
+    try {
+        const read = await (input.readGraph ?? gateGraphReader())(cwd);
+        if ("error" in read)
+            warning = read.error;
+        else
+            nodes = { member, at: input.at ?? null, ids: read.ids, sources: repoSources(cwd, read.sources) };
+    }
+    catch (err) {
+        warning = err instanceof Error ? err.message : String(err);
+    }
+    const mapped = mapChangeSetToGraph(doc, nodes);
+    const { written } = await persistChangeSet(mapped, loc);
+    return {
+        digest: doc.digest,
+        written,
+        graph: mapped.graph ?? null,
+        ...(warning ? { warning: `the change set is stored without graph nodes: ${warning}` } : {}),
+    };
+}

package/dist/lifecycle/gate-ledger.d.ts

@@ -2,6 +2,7 @@ import { type GateOrigin } from "./gate-origin.js";
 import type { GateApprover, GatePolicyDecision, ResolvedGateApproval } from "../op/gate-approval.js";
 import type { GateApprovalSource } from "../op/op-waves.js";
 import type { GateRunLocator } from "../op/gate-run-locator.js";
+import { type LedgerLocation } from "./git.js";
 export { DEFAULT_GATE_EXPIRY, isApprovalUrl, resolveApprovalUrl } from "./gate-pending.js";
 export { isPendingGateExpired, latestPendingGate, latestResolutionForPlan, latestResolutionSince, type PlanBoundResolution, } from "./gate-ledger-select.js";
 /** The directory on the `chant/lifecycle` branch that holds gate ledgers, under a member's prefix when it has one. */
@@ -75,6 +76,16 @@ export interface GateResolutionRecord {
      * such a record proves is that somebody approved *something*.
      */
     planDigest?: string;
+    /**
+     * The commit the gate was waiting on (#4020), copied off the pending fact the
+     * approval answers, or the run's own commit for a resolution a run writes
+     * itself (a decision point's answer, a review, a carried approval). It is not
+     * the approver's checkout, and a seal does not cover it. Absent on a
+     * resolution written before 0.124.28 and when no commit was known.
+     */
+    gitSha?: string;
+    /** The run the gate was waiting on (#4020), copied the same way as {@link GateResolutionRecord.gitSha}. */
+    runId?: string;
     /**
      * The checkpoint this approval lets a run resume from (#3947), copied off
      * the pending fact it answers. Set only on an approval of a gate that
@@ -88,6 +99,26 @@ export interface GateResolutionRecord {
      * recorded for its own environment and plan.
      */
     environment?: string;
+    /**
+     * The release this approval is for (#4045, ws-104 question 2), copied off
+     * the pending fact it answers. Set on a release gate, the gate `chant
+     * components promote --release` passes for an environment. A release gate
+     * counts only a resolution recorded for its own release, environment and
+     * change-set document digest (`planDigest`), so it names the release it
+     * admitted. Absent on every other gate, and on a resolution written before
+     * 0.124.28.
+     */
+    releaseDigest?: string;
+    /**
+     * The resolution passes a release gate over an empty change set (#4045,
+     * ws-104 question 6): the promote wrote it itself, with the actor running
+     * it in `resolvedBy`, because the change set its `planDigest` names changes
+     * nothing. A gate counts it only after it reads the stored document under
+     * `planDigest` and finds it empty, and neither a quorum nor a signing rule
+     * applies to it. It never counts as a person's approval. Absent on every
+     * other resolution.
+     */
+    empty?: true;
     /**
      * The channel this resolution was authored on (chant#2384) — set by the
      * writer, never by the caller. `chant approve` records `"cli"`, the
@@ -220,8 +251,19 @@ export interface PendingGateRecord {
     gate: string;
     /** The gate's human-readable description, when it declared one — what `chant operator status` shows a reader who wasn't there for the run. */
     description?: string;
-    /** The run that reached the gate, when the caller identifies its runs. */
+    /**
+     * The run that reached the gate. An Op run records its own id; a run with no
+     * id of its own (a component gate) records the CI run id when it ran in CI
+     * (#4020). Absent outside CI for a run that mints none.
+     */
     runId?: string;
+    /**
+     * The commit the run reached the gate at (#4020): the checkout's `HEAD`, else
+     * the commit the CI job started for. It is the commit the gate waits on, and
+     * `chant approve` copies it onto the resolution. Absent on a record written
+     * before 0.124.28 and when the run knew no commit.
+     */
+    gitSha?: string;
     /** ISO-8601 timestamp, caller-supplied (library code never calls `Date.now()` internally). */
     timestamp: string;
     /** ISO-8601 expiry, from the gate's `timeout` (default {@link DEFAULT_GATE_EXPIRY}). Past it, the fact is stale and a run re-records it. */
@@ -262,6 +304,13 @@ export interface PendingGateRecord {
      * can pick one.
      */
     environment?: string;
+    /**
+     * The release the run reached this gate for (#4045): on a release gate, the
+     * `releaseDigest` of the release `chant components promote --release`
+     * deploys. `chant approve` copies it onto the approval with the plan.
+     * Absent on every other gate, and on a fact written before 0.124.28.
+     */
+    releaseDigest?: string;
     /**
      * The channel the run that reached this gate was driven from (chant#2384).
      *
@@ -342,9 +391,7 @@ export declare function appendPendingGate(input: PendingGateInput, opts?: {
  * graceful-degradation stance `readConvergeLedger` takes. Returns empty arrays
  * (never throws) when `op` has nothing recorded yet.
  */
-export declare function readGateLedger(op: string, opts?: {
-    cwd?: string;
-}): Promise<{
+export declare function readGateLedger(op: string, opts?: LedgerLocation): Promise<{
     resolutions: GateResolutionRecord[];
     pending: PendingGateRecord[];
     malformed: number;