@intentius/chant 0.124.28 → 0.124.29

package/dist/workspace/declaration.schema.json

@@ -179,6 +179,58 @@
           "$ref": "#/$defs/ciGreen"
         }
       }
+    },
+    "retention": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": true
+      },
+      "description": "How long chant lifecycle gc keeps each kind of stored record (#4036). A kind or field left out keeps its default: changeSets 14 days; releases 14 days and the newest 10 of each member; runEvents 14 days and the newest 100. Whatever the policy, gc never prunes a release an environment runs, what a pending gate binds, or a change set a gate names with a kept release. Read from the declaration at base. Added in schema 1 by chant 0.124.29, so a declaration that uses it sets minReader to 0.124.29 or newer.",
+      "properties": {
+        "changeSets": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Stored change sets, _change-sets/<digest>.json on chant/lifecycle.",
+          "properties": {
+            "days": { "$ref": "#/$defs/retentionDays" }
+          }
+        },
+        "releases": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Releases, _releases/<digest>.json on chant/lifecycle, with the template bytes only they name. A release stays promotable for days after its newest cut, and the newest keep releases of each member stay promotable at any age, unless their commit is revoked.",
+          "properties": {
+            "days": { "$ref": "#/$defs/retentionDays" },
+            "keep": { "$ref": "#/$defs/retentionKeep" }
+          }
+        },
+        "runEvents": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Run event files, <git-common-dir>/chant/run-events/<run>.jsonl on each host. A file is kept for days after its last write, and the newest keep files at any age.",
+          "properties": {
+            "days": { "$ref": "#/$defs/retentionDays" },
+            "keep": { "$ref": "#/$defs/retentionKeep" }
+          }
+        }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": true
+      },
+      "description": "How chant workspace metrics counts the DORA metrics (#4039). Added in schema 1 by chant 0.124.29, so a declaration that uses it sets minReader to 0.124.29 or newer.",
+      "properties": {
+        "failureWindowDays": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 365,
+          "description": "A deploy counts as failed when, within this many days after it, the commit it deployed is revoked or the environment is rolled back from it. The default is 7."
+        }
+      }
     }
   },
   "patternProperties": {
@@ -186,6 +238,18 @@
   },
   "additionalProperties": false,
   "$defs": {
+    "retentionDays": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 36500,
+      "description": "Days a record is kept past its last write or use. 0 lets every record go that no never-prune rule keeps."
+    },
+    "retentionKeep": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 100000,
+      "description": "How many of the newest are kept at any age."
+    },
     "name": {
       "type": "string",
       "pattern": "^[a-z0-9][a-z0-9-]{0,39}$",

package/dist/workspace/declared-kinds.d.ts

@@ -47,6 +47,21 @@ export interface DeclaredKind {
      * and when its records can't be read (`records` reports why).
      */
     acceptance?: DeclaredAcceptance[];
+    /**
+     * For a flag kind (#4024), read with `flags: true`: each current flag
+     * record, with its `flag-stale` warning when it is due for removal. Absent
+     * for any other kind, when the kind wasn't loaded, and when its records
+     * can't be read (`records` reports why).
+     */
+    flags?: DeclaredFlag[];
+}
+/** One flag record, as `check` reads it for WSP118 (#4024). */
+export interface DeclaredFlag {
+    flag: string;
+    /** The record file on disk, absolute. */
+    file: string;
+    /** The record's `flag-stale` warning, when the flag is due for removal; null otherwise. */
+    stale: string | null;
 }
 /** One work record's acceptance criteria, counted, as `ls`, `status` and `check` read them (#2772). */
 export interface DeclaredAcceptance {
@@ -70,6 +85,7 @@ export declare function declaredKindFile(declared: RecordKindDeclaration, rootOn
 export declare function loadDeclaredKinds(declaration: Declaration, tree: WorkspaceTree, rootOnDisk: string, options?: {
     load?: boolean;
     acceptance?: boolean;
+    flags?: boolean;
     at?: string;
 }): Promise<DeclaredKind[]>;
 //# sourceMappingURL=declared-kinds.d.ts.map

package/dist/workspace/declared-kinds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"declared-kinds.d.ts","sourceRoot":"","sources":["../../src/workspace/declared-kinds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAuB,KAAK,WAAW,EAAE,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAElG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,oHAAoH;AACpH,eAAO,MAAM,0BAA0B,yFAA0H,CAAC;AAClK,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjF,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,qBAAqB,CAAC;IAChC,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,uCAAuC;IACvC,MAAM,EAAE;QAAE,IAAI,EAAE,sBAAsB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACjE;;;;OAIG;IACH,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE;YAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;IACjF;;;;;OAKG;IACH,UAAU,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACnC;AAED,uGAAuG;AACvG,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,4GAA4G;IAC5G,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,qBAAqB,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE5F;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,WAAW,EACxB,IAAI,EAAE,aAAa,EACnB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE,OAAO,CAAC,YAAY,EAAE,CAAC,CA+BzB"}
+{"version":3,"file":"declared-kinds.d.ts","sourceRoot":"","sources":["../../src/workspace/declared-kinds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAuB,KAAK,WAAW,EAAE,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAElG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,oHAAoH;AACpH,eAAO,MAAM,0BAA0B,yFAA0H,CAAC;AAClK,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjF,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,qBAAqB,CAAC;IAChC,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,uCAAuC;IACvC,MAAM,EAAE;QAAE,IAAI,EAAE,sBAAsB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACjE;;;;OAIG;IACH,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE;YAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;IACjF;;;;;OAKG;IACH,UAAU,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAClC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,uGAAuG;AACvG,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,4GAA4G;IAC5G,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,qBAAqB,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE5F;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,WAAW,EACxB,IAAI,EAAE,aAAa,EACnB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GACnF,OAAO,CAAC,YAAY,EAAE,CAAC,CAmCzB"}

package/dist/workspace/declared-kinds.js

@@ -52,6 +52,11 @@ export async function loadDeclaredKinds(declaration, tree, rootOnDisk, options =
                 if (counted)
                     entry.acceptance = counted;
             }
+            if (loaded.kind.flag && options.flags) {
+                const flags = await readFlags(file, rootOnDisk, options.at);
+                if (flags)
+                    entry.flags = flags;
+            }
             out.push(entry);
         }
         catch (err) {
@@ -86,6 +91,26 @@ async function countAcceptance(file, rootOnDisk, at) {
         throw err;
     }
 }
+/** A flag kind's current records with their stale warnings (#4024), or undefined when they can't be read. */
+async function readFlags(file, rootOnDisk, at) {
+    const { readRecordsFor } = await import("./records-cli.js");
+    const { RecordReadError } = await import("./records.js");
+    try {
+        const read = await readRecordsFor({ kind: file, cwd: rootOnDisk, current: true, ...(at !== undefined ? { at } : {}) });
+        return read.result.records
+            .filter((r) => r.id !== null)
+            .map((r) => ({
+            flag: r.id,
+            file: join(read.root, ...r.path.split("/")),
+            stale: r.warnings.find((w) => w.code === "flag-stale")?.message ?? null,
+        }));
+    }
+    catch (err) {
+        if (err instanceof RecordReadError)
+            return undefined;
+        throw err;
+    }
+}
 /** An answer kind's points file (ws-058), read from `tree` and validated as `points ask` reads it. */
 async function checkPoints(abs, rootOnDisk, tree) {
     const file = relative(rootOnDisk, abs).split(sep).join("/");

package/dist/workspace/delivery-metrics.d.ts

@@ -0,0 +1,91 @@
+/**
+ * `chant workspace metrics [--env <env>] [--member <name>] [--since <date>] [--json]`
+ * (#4039): the four DORA metrics per member and environment, from the deploy
+ * records, the releases and their revocations on `chant/lifecycle`.
+ *
+ * The `--json` document is `delivery-metrics.schema.json`, a read-contract
+ * output, so behold, a Grafana panel and terragucci's own estate read the
+ * same numbers. The metrics are computed in `../lifecycle/delivery-metrics.ts`;
+ * this module reads what they need:
+ *
+ * - each member's `<env>/releases.jsonl`, every environment it has, read in
+ *   full, since deploys before the window decide lead times and deploys after
+ *   a failure decide its restore;
+ * - its releases, for the commit each was cut from, and the release gate's
+ *   resolutions, for a deploy that names its release only through its
+ *   admission (`releaseOfDeploy`, #4043);
+ * - the counted `ci/revoked/<sha>` tags, judged as `release cut` judges them
+ *   (`readRevokedCommits`, #4033), and each commit's committer time from git.
+ *
+ * Outside a workspace the project's own ledger is read as one member, `null`.
+ * It reads the local branch and the local tags, and never fetches.
+ */
+import type { CommandContext } from "../cli/registry.js";
+import { type EnvironmentMetrics, type MetricsWindow } from "../lifecycle/delivery-metrics.js";
+export declare const DELIVERY_METRICS_CONTRACT_VERSION = 1;
+export declare const DELIVERY_METRICS_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/delivery-metrics/v1/delivery-metrics.schema.json";
+/** The window when `--since` is not given: eight weeks back from now. */
+export declare const DEFAULT_METRICS_DAYS = 56;
+/** Why the read stopped. Closed. Outside a workspace there is no declaration to fail, so `declaration-missing` never comes back. */
+export declare const METRICS_ERROR_CODES: readonly ["declaration-ambiguous", "declaration-unparseable", "declaration-invalid", "placement-invalid", "reader-too-old", "root-chant-required", "not-a-git-repository", "environment-invalid"];
+export type MetricsErrorCode = (typeof METRICS_ERROR_CODES)[number];
+/** Why a member's metrics are missing or partial. Closed. */
+export declare const METRICS_REASON_CODES: readonly ["ledger-unreadable", "ledger-malformed"];
+export type MetricsReasonCode = (typeof METRICS_REASON_CODES)[number];
+/** One member's metrics. */
+export interface MemberMetrics {
+    /** The member's name, or null for a project outside a workspace. */
+    member: string | null;
+    /** Each environment with a deploy ledger, sorted by name. */
+    environments: EnvironmentMetrics[];
+    /** Null when everything was read. */
+    reason: {
+        code: MetricsReasonCode;
+        message: string;
+    } | null;
+}
+export type DeliveryMetricsDocument = {
+    $schema: string;
+    contract: number;
+    chant: string;
+    /** The workspace's name, or null for a project outside a workspace. */
+    workspace: {
+        name: string;
+    } | null;
+    lifecycle: {
+        ref: string;
+        commit: string | null;
+    };
+    window: MetricsWindow & {
+        days: number;
+    };
+    failureWindowDays: number;
+    members: MemberMetrics[];
+} | {
+    $schema: string;
+    contract: number;
+    chant: string;
+    error: {
+        code: MetricsErrorCode;
+        message: string;
+    };
+};
+export interface MetricsQuery {
+    cwd: string;
+    /** Only this environment. */
+    env?: string;
+    /** Only these members. */
+    members?: string[];
+    /** ISO-8601 date or time; the default is {@link DEFAULT_METRICS_DAYS} days before `now`. */
+    since?: string;
+    /** For tests: the end of the window. */
+    now?: string;
+}
+/** Read the metrics document for the workspace or project holding `query.cwd`. */
+export declare function deliveryMetrics(query: MetricsQuery): Promise<DeliveryMetricsDocument>;
+/** The text view: one line per member and environment. */
+export declare function formatMetrics(doc: Extract<DeliveryMetricsDocument, {
+    members: unknown;
+}>): string;
+export declare function runWorkspaceMetrics(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=delivery-metrics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-metrics.d.ts","sourceRoot":"","sources":["../../src/workspace/delivery-metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAmD,KAAK,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAQ7I,eAAO,MAAM,iCAAiC,IAAI,CAAC;AACnD,eAAO,MAAM,0BAA0B,kGAAkG,CAAC;AAE1I,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,oIAAoI;AACpI,eAAO,MAAM,mBAAmB,mMASU,CAAC;AAC3C,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,6DAA6D;AAC7D,eAAO,MAAM,oBAAoB,oDAAqF,CAAC;AACvH,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAMtE,4BAA4B;AAC5B,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,6DAA6D;IAC7D,YAAY,EAAE,kBAAkB,EAAE,CAAC;IACnC,qCAAqC;IACrC,MAAM,EAAE;QAAE,IAAI,EAAE,iBAAiB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC7D;AAED,MAAM,MAAM,uBAAuB,GAC/B;IACE,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACnC,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAClD,MAAM,EAAE,aAAa,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B,GACD;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAE7G,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,4FAA4F;IAC5F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAmBD,kFAAkF;AAClF,wBAAsB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA+D3F;AAsED,0DAA0D;AAC1D,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,uBAAuB,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,GAAG,MAAM,CAcjG;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB9E"}

package/dist/workspace/delivery-metrics.js

@@ -0,0 +1,217 @@
+/**
+ * `chant workspace metrics [--env <env>] [--member <name>] [--since <date>] [--json]`
+ * (#4039): the four DORA metrics per member and environment, from the deploy
+ * records, the releases and their revocations on `chant/lifecycle`.
+ *
+ * The `--json` document is `delivery-metrics.schema.json`, a read-contract
+ * output, so behold, a Grafana panel and terragucci's own estate read the
+ * same numbers. The metrics are computed in `../lifecycle/delivery-metrics.ts`;
+ * this module reads what they need:
+ *
+ * - each member's `<env>/releases.jsonl`, every environment it has, read in
+ *   full, since deploys before the window decide lead times and deploys after
+ *   a failure decide its restore;
+ * - its releases, for the commit each was cut from, and the release gate's
+ *   resolutions, for a deploy that names its release only through its
+ *   admission (`releaseOfDeploy`, #4043);
+ * - the counted `ci/revoked/<sha>` tags, judged as `release cut` judges them
+ *   (`readRevokedCommits`, #4033), and each commit's committer time from git.
+ *
+ * Outside a workspace the project's own ledger is read as one member, `null`.
+ * It reads the local branch and the local tags, and never fetches.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { formatError } from "../cli/format.js";
+import { DEFAULT_FAILURE_WINDOW_DAYS, environmentMetrics } from "../lifecycle/delivery-metrics.js";
+import { findWorkspaceRoot } from "../project-root.js";
+import { readDeclaration, readerVersion, WorkspaceReadError } from "./declaration.js";
+import { gitTop, workingTree } from "./tree.js";
+import { handToRootChant } from "./which-chant.js";
+export const DELIVERY_METRICS_CONTRACT_VERSION = 1;
+export const DELIVERY_METRICS_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/delivery-metrics/v1/delivery-metrics.schema.json";
+/** The window when `--since` is not given: eight weeks back from now. */
+export const DEFAULT_METRICS_DAYS = 56;
+/** Why the read stopped. Closed. Outside a workspace there is no declaration to fail, so `declaration-missing` never comes back. */
+export const METRICS_ERROR_CODES = [
+    "declaration-ambiguous",
+    "declaration-unparseable",
+    "declaration-invalid",
+    "placement-invalid",
+    "reader-too-old",
+    "root-chant-required",
+    "not-a-git-repository",
+    "environment-invalid",
+];
+/** Why a member's metrics are missing or partial. Closed. */
+export const METRICS_REASON_CODES = ["ledger-unreadable", "ledger-malformed"];
+const ENV_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const USAGE = "chant workspace metrics [dir] [--env <env>] [--member <name>] [--since <date>] [--json]";
+class MetricsError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function tryGit(cwd, args) {
+    try {
+        return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** Read the metrics document for the workspace or project holding `query.cwd`. */
+export async function deliveryMetrics(query) {
+    const head = { $schema: DELIVERY_METRICS_SCHEMA_ID, contract: DELIVERY_METRICS_CONTRACT_VERSION, chant: readerVersion() };
+    try {
+        if (query.env !== undefined && (!ENV_PATTERN.test(query.env) || query.env.includes(".."))) {
+            throw new MetricsError("environment-invalid", `--env ${JSON.stringify(query.env)} can't be an environment: use letters, digits, ".", "_" and "-", starting with a letter or digit`);
+        }
+        const top = gitTop(query.cwd);
+        if (!top)
+            throw new MetricsError("not-a-git-repository", `${query.cwd} is not in a git repository, so it has no chant/lifecycle branch to read`);
+        const found = findWorkspaceRoot(query.cwd);
+        const declaration = found ? readDeclaration(workingTree(found.dir), "", { rootChant: true }) : null;
+        const root = found?.dir ?? query.cwd;
+        const failureWindowDays = declaration?.metrics?.failureWindowDays ?? DEFAULT_FAILURE_WINDOW_DAYS;
+        const until = query.now ?? new Date().toISOString();
+        const since = query.since ?? new Date(Date.parse(until) - DEFAULT_METRICS_DAYS * 86400000).toISOString();
+        const window = { since: new Date(Date.parse(since)).toISOString(), until: new Date(Date.parse(until)).toISOString() };
+        const days = Math.round(((Date.parse(window.until) - Date.parse(window.since)) / 86400000) * 100) / 100;
+        // The revoked commits, judged against ci.green at base (#4033). Tags that
+        // can't be judged stop the read: the failure rate would be wrong otherwise.
+        const { readRevokedCommits } = await import("../lifecycle/release-revocation.js");
+        const revoked = await readRevokedCommits(root);
+        const commitTimes = new Map();
+        const commitTime = (sha) => {
+            if (!commitTimes.has(sha)) {
+                const iso = tryGit(top, ["show", "-s", "--format=%cI", `${sha}^{commit}`]);
+                commitTimes.set(sha, iso ? Date.parse(iso) : null);
+            }
+            return commitTimes.get(sha);
+        };
+        let ledgers;
+        if (declaration) {
+            const wanted = query.members && query.members.length > 0 ? new Set(query.members) : null;
+            if (wanted) {
+                const unknown = [...wanted].filter((n) => !declaration.members.some((m) => m.name === n));
+                if (unknown.length > 0)
+                    throw new WorkspaceReadError("declaration-invalid", `--member ${unknown.join(", ")} names no member of the workspace`);
+            }
+            ledgers = declaration.members
+                .filter((m) => !wanted || wanted.has(m.name))
+                .map((m) => ({ member: m.name, loc: { cwd: root, member: m.dir === "." ? "." : m.name } }));
+        }
+        else {
+            ledgers = [{ member: null, loc: { cwd: query.cwd } }];
+        }
+        const members = [];
+        for (const l of ledgers)
+            members.push(await memberMetrics(l.member, l.loc, { env: query.env, window, failureWindowDays, revoked, commitTime }));
+        return {
+            ...head,
+            workspace: declaration ? { name: declaration.name } : null,
+            lifecycle: { ref: "chant/lifecycle", commit: tryGit(top, ["rev-parse", "--verify", "--quiet", "refs/heads/chant/lifecycle"]) || null },
+            window: { ...window, days },
+            failureWindowDays,
+            members,
+        };
+    }
+    catch (err) {
+        if (err instanceof WorkspaceReadError)
+            return { ...head, error: { code: err.code, message: err.message } };
+        if (err instanceof MetricsError)
+            return { ...head, error: { code: err.code, message: err.message } };
+        throw err;
+    }
+}
+async function memberMetrics(member, loc, ctx) {
+    try {
+        const { listReleaseEnvironments, readReleaseLedger } = await import("../lifecycle/release-ledger.js");
+        const { readAllReleases, readCuts, labelsByDigest } = await import("../lifecycle/release-store.js");
+        const { readGateLedger } = await import("../lifecycle/gate-ledger.js");
+        const { releaseOfDeploy } = await import("../lifecycle/release-join.js");
+        const { RELEASE_GATE_OP } = await import("../op/gate-name.js");
+        let envs = (await listReleaseEnvironments(loc)).sort();
+        if (ctx.env !== undefined)
+            envs = envs.filter((e) => e === ctx.env);
+        if (envs.length === 0)
+            return { member, environments: [], reason: null };
+        const { releases, malformed: badReleases } = await readAllReleases(loc);
+        const commits = new Map(releases.map((r) => [r.releaseDigest, r.commit]));
+        const labels = labelsByDigest((await readCuts(loc)).cuts);
+        const { resolutions } = await readGateLedger(RELEASE_GATE_OP, loc);
+        const environments = [];
+        let badLines = 0;
+        for (const env of envs) {
+            const { records, malformed } = await readReleaseLedger(env, loc);
+            badLines += malformed;
+            environments.push(environmentMetrics(env, records, {
+                releaseOf: (r) => releaseOfDeploy(r, resolutions),
+                commitOfRelease: (d) => commits.get(d) ?? null,
+                labelOf: (d) => labels.get(d) ?? null,
+                revocationOf: (sha) => {
+                    const r = ctx.revoked.get(sha);
+                    return r ? { tag: r.tag, tagged: r.tagged } : null;
+                },
+                commitTime: ctx.commitTime,
+            }, ctx.window, ctx.failureWindowDays));
+        }
+        const reason = badLines + badReleases > 0
+            ? { code: "ledger-malformed", message: `${badLines} deploy record line(s) and ${badReleases} release file(s) could not be read and are left out` }
+            : null;
+        return { member, environments, reason };
+    }
+    catch (err) {
+        return { member, environments: [], reason: { code: "ledger-unreadable", message: `reading the ledger failed: ${err instanceof Error ? err.message : String(err)}` } };
+    }
+}
+const seconds = (s) => {
+    if (s === null)
+        return "none";
+    if (s < 3600)
+        return `${Math.round(s / 60)}m`;
+    if (s < 86400)
+        return `${Math.round((s / 3600) * 10) / 10}h`;
+    return `${Math.round((s / 86400) * 10) / 10}d`;
+};
+/** The text view: one line per member and environment. */
+export function formatMetrics(doc) {
+    const lines = [`window ${doc.window.since} to ${doc.window.until} (${doc.window.days} days), failure window ${doc.failureWindowDays} days`];
+    for (const m of doc.members) {
+        if (m.reason)
+            lines.push(`${m.member ?? "."}: ${m.reason.code}: ${m.reason.message}`);
+        for (const e of m.environments) {
+            const rate = e.changeFailure.rate === null ? "-" : `${Math.round(e.changeFailure.rate * 1000) / 10}%`;
+            lines.push(`${m.member ?? "."} ${e.env}: ${e.deployments.count} deploys (${e.deployments.perWeek}/week), lead time ${seconds(e.leadTime.medianSeconds)}, ` +
+                `change failure ${rate} (${e.changeFailure.failed}/${e.changeFailure.deployments}), restore ${seconds(e.restore.medianSeconds)}` +
+                (e.restore.open > 0 ? `, ${e.restore.open} open` : ""));
+        }
+    }
+    return lines.join("\n");
+}
+export async function runWorkspaceMetrics(ctx) {
+    const { args } = ctx;
+    if (args.since !== undefined && (args.since === "" || Number.isNaN(Date.parse(args.since)))) {
+        console.error(formatError({ message: `--since ${JSON.stringify(args.since)} is not a date: give an ISO-8601 date such as 2026-09-01`, hint: USAGE }));
+        return 1;
+    }
+    const cwd = resolve(args.extraPositional ?? ".");
+    if (!existsSync(cwd)) {
+        console.error(formatError({ message: `${cwd} does not exist`, hint: USAGE }));
+        return 1;
+    }
+    const handed = await handToRootChant(cwd, undefined);
+    if (handed !== undefined)
+        return handed;
+    const doc = await deliveryMetrics({ cwd, ...(args.env ? { env: args.env } : {}), ...(args.members ? { members: args.members } : {}), ...(args.since ? { since: args.since } : {}) });
+    if (args.json)
+        console.log(JSON.stringify(doc, null, 2));
+    else if ("error" in doc)
+        console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+    else
+        console.log(formatMetrics(doc));
+    return "error" in doc ? 1 : 0;
+}