@intentius/chant 0.124.28 → 0.124.30

package/dist/workspace/delivery-metrics.schema.json

@@ -0,0 +1,519 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/delivery-metrics/v1/delivery-metrics.schema.json",
+  "title": "chant workspace metrics output",
+  "description": "What `chant workspace metrics --json` prints (#4039): the four DORA metrics (deployment frequency, lead time, change failure rate and time to restore) per member and environment, computed from the deploy records in <env>/releases.jsonl, the releases in _releases/, the release gate's resolutions and the counted ci/revoked/<sha> tags. It reads the local chant/lifecycle branch and local tags and never fetches. behold and a Grafana panel read the same numbers from it, and #3990's metrics contract can adopt it. Version 1 of the read contract. Readers ignore fields they do not know; a field is only ever added within a version. The codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.124.29 and newer; the read contract as a whole by chant 0.81.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "Exit code 0, with or without deploys.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "workspace",
+        "lifecycle",
+        "window",
+        "failureWindowDays",
+        "members"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/delivery-metrics/v1/delivery-metrics.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": false,
+        "workspace": {
+          "description": "The workspace read, or null for a project outside a workspace, whose own ledger is read as one member with member null.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "name"
+              ],
+              "properties": {
+                "name": {
+                  "type": "string"
+                }
+              }
+            }
+          ]
+        },
+        "lifecycle": {
+          "type": "object",
+          "description": "The branch read and its tip, null when the checkout has no chant/lifecycle branch.",
+          "required": [
+            "ref",
+            "commit"
+          ],
+          "properties": {
+            "ref": {
+              "const": "chant/lifecycle"
+            },
+            "commit": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        },
+        "window": {
+          "type": "object",
+          "description": "The span deploys are counted in, both ends inclusive. --since sets since; the default is 56 days (eight weeks) before until, which is now.",
+          "required": [
+            "since",
+            "until",
+            "days"
+          ],
+          "properties": {
+            "since": {
+              "type": "string",
+              "description": "ISO 8601."
+            },
+            "until": {
+              "type": "string",
+              "description": "ISO 8601."
+            },
+            "days": {
+              "type": "number",
+              "description": "The window's length in days, to two decimals."
+            }
+          }
+        },
+        "failureWindowDays": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "The declaration's metrics.failureWindowDays, or 7. A deploy fails when, within this many days after it, the commit it deployed is revoked or the environment is rolled back from it."
+        },
+        "members": {
+          "type": "array",
+          "description": "Each member read, in declaration order. --member keeps only the members it names.",
+          "items": {
+            "$ref": "#/$defs/member"
+          }
+        }
+      }
+    },
+    "member": {
+      "type": "object",
+      "description": "One member's metrics.",
+      "required": [
+        "member",
+        "environments",
+        "reason"
+      ],
+      "properties": {
+        "member": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The member's name, or null for a project outside a workspace."
+        },
+        "environments": {
+          "type": "array",
+          "description": "Each environment the member has a deploy ledger for, sorted by name. --env keeps only that one.",
+          "items": {
+            "$ref": "#/$defs/environment"
+          }
+        },
+        "reason": {
+          "description": "Null when everything was read. ledger-malformed when some deploy record lines or release files could not be read; the rest are counted. ledger-unreadable when the ledger could not be read, and environments is empty.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "code",
+                "message"
+              ],
+              "properties": {
+                "code": {
+                  "enum": [
+                    "ledger-unreadable",
+                    "ledger-malformed"
+                  ]
+                },
+                "message": {
+                  "type": "string"
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "environment": {
+      "type": "object",
+      "description": "The four metrics of one member in one environment. A deploy is one deploy record: one component deployed once, by a promote, a run or a rollback. A redeploy is counted apart.",
+      "required": [
+        "env",
+        "deployments",
+        "leadTime",
+        "changeFailure",
+        "restore",
+        "failures"
+      ],
+      "properties": {
+        "env": {
+          "type": "string"
+        },
+        "deployments": {
+          "type": "object",
+          "description": "Deployment frequency.",
+          "required": [
+            "count",
+            "redeploys",
+            "runs",
+            "fromRelease",
+            "perWeek"
+          ],
+          "properties": {
+            "count": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Deploy records whose timestamp is in the window, leaving out redeploys. Rollbacks count."
+            },
+            "redeploys": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Redeploys in the window (records with redeploys set): they put the running release back, so they are counted here and in no other metric."
+            },
+            "runs": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Distinct runId values among them: a run that deploys several components counts once."
+            },
+            "fromRelease": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Of count, the deploys made from a release: the record names one in releaseDigest, or its release gate admission does."
+            },
+            "perWeek": {
+              "type": "number",
+              "minimum": 0,
+              "description": "count over the window's length in weeks, to two decimals."
+            }
+          }
+        },
+        "leadTime": {
+          "type": "object",
+          "description": "Lead time from commit to running release. A change is a release, timed at the first deploy record in this environment that names it, or a commit deployed from no release, timed at the first deploy record with that gitSha. Its lead time runs from the commit's committer time to that deploy. Only changes whose first deploy here is in the window count.",
+          "required": [
+            "changes",
+            "fromRelease",
+            "fromCommit",
+            "unknown",
+            "medianSeconds"
+          ],
+          "properties": {
+            "changes": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "fromRelease": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Of changes, releases."
+            },
+            "fromCommit": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Of changes, commits deployed from no release."
+            },
+            "unknown": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Changes left out because their commit is not in this repository."
+            },
+            "medianSeconds": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0,
+              "description": "The median lead time, or null when changes is 0."
+            }
+          }
+        },
+        "changeFailure": {
+          "type": "object",
+          "description": "Change failure rate.",
+          "required": [
+            "deployments",
+            "failed",
+            "revoked",
+            "rolledBack",
+            "rate"
+          ],
+          "properties": {
+            "deployments": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "The same as deployments.count."
+            },
+            "failed": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Deploys in the window that failed: the commit they deployed (a release's commit, or the record's gitSha for a deploy made from no release) carries a counted ci/revoked tag made no later than failureWindowDays after the deploy, or the environment was rolled back from them within failureWindowDays. A revoked tag with no time counts whenever it was made."
+            },
+            "revoked": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Of failed, those whose commit was revoked."
+            },
+            "rolledBack": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Of failed, those rolled back from: the next deploy record of the same component in the environment, leaving out redeploys, is a rollback."
+            },
+            "rate": {
+              "type": [
+                "number",
+                "null"
+              ],
+              "minimum": 0,
+              "maximum": 1,
+              "description": "failed over deployments, to four decimals, or null with no deployments."
+            }
+          }
+        },
+        "restore": {
+          "type": "object",
+          "description": "Time to restore. A failed deploy is restored by the next deploy record of the same component in the environment, leaving out redeploys, whose commit is not revoked.",
+          "required": [
+            "restored",
+            "open",
+            "medianSeconds"
+          ],
+          "properties": {
+            "restored": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "open": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Failed deploys with no restore yet."
+            },
+            "medianSeconds": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0,
+              "description": "The median time from a failed deploy to its restore, or null when none is restored."
+            }
+          }
+        },
+        "failures": {
+          "type": "array",
+          "description": "Each failed deploy in the window, oldest first.",
+          "items": {
+            "$ref": "#/$defs/failure-entry"
+          }
+        }
+      }
+    },
+    "failure-entry": {
+      "type": "object",
+      "description": "One failed deploy.",
+      "required": [
+        "component",
+        "timestamp",
+        "runId",
+        "releaseDigest",
+        "label",
+        "commit",
+        "causes",
+        "revoked",
+        "rolledBackBy",
+        "restoredBy",
+        "restoreSeconds"
+      ],
+      "properties": {
+        "component": {
+          "type": "string"
+        },
+        "timestamp": {
+          "type": "string"
+        },
+        "runId": {
+          "type": "string"
+        },
+        "releaseDigest": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The release it deployed, or null for a deploy made from no release."
+        },
+        "label": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "That release's label, or null."
+        },
+        "commit": {
+          "type": "string",
+          "description": "The commit it deployed."
+        },
+        "causes": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "enum": [
+              "revoked",
+              "rolled-back"
+            ]
+          }
+        },
+        "revoked": {
+          "description": "The counted revoked tag on the commit, when revoked is a cause, else null.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "tag",
+                "tagged"
+              ],
+              "properties": {
+                "tag": {
+                  "type": "string"
+                },
+                "tagged": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "When the tag was made, or null for a lightweight tag."
+                }
+              }
+            }
+          ]
+        },
+        "rolledBackBy": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "runId",
+                "timestamp"
+              ],
+              "properties": {
+                "runId": {
+                  "type": "string"
+                },
+                "timestamp": {
+                  "type": "string"
+                }
+              }
+            }
+          ],
+          "description": "The rollback record, named by runId and timestamp, when rolled-back is a cause, else null."
+        },
+        "restoredBy": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "runId",
+                "timestamp"
+              ],
+              "properties": {
+                "runId": {
+                  "type": "string"
+                },
+                "timestamp": {
+                  "type": "string"
+                }
+              }
+            }
+          ],
+          "description": "The deploy record that restored it, or null while it is not restored."
+        },
+        "restoreSeconds": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Nothing was read. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/delivery-metrics/v1/delivery-metrics.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "declaration-ambiguous",
+                "declaration-unparseable",
+                "declaration-invalid",
+                "placement-invalid",
+                "reader-too-old",
+                "root-chant-required",
+                "not-a-git-repository",
+                "environment-invalid"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/workspace/flags-read.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Reading a workspace's feature flags (#4024): every flag of the declared
+ * flag kinds, and the flags of one member by parameter. Kept apart from
+ * `./flags.ts`, which `records.ts` loads, since reading goes through
+ * `records-cli.ts`.
+ */
+import type { FlagValue, WorkspaceFlags } from "./flags.js";
+/**
+ * Every flag of every flag kind the declaration at `root` names, read in the
+ * working tree. A kind without a flag block is skipped without reading its
+ * records. Throws a `RecordReadError` when a flag kind or its records can't
+ * be read, and a `WorkspaceReadError` when the declaration can't.
+ */
+export declare function readWorkspaceFlags(root: string): Promise<WorkspaceFlags>;
+/** One flag-backed parameter, as a build in one environment reads it. */
+export interface FlagBinding {
+    /** The flag's name. */
+    flag: string;
+    /** The flag's value in the environment, or undefined when the record gives it none. */
+    value: FlagValue | undefined;
+}
+/** The flags that back the parameters of the member holding a directory. */
+export interface MemberFlagBindings {
+    /** The member's name in the declaration. */
+    member: string;
+    /** Each flag-backed parameter by name. */
+    byParam: Record<string, FlagBinding>;
+    /** Why a flag of this member can't be trusted: an invalid record that names it, or two flags for one parameter. */
+    errors: string[];
+}
+/**
+ * The flags that back parameters of the member holding `projectDir`, in the
+ * workspace whose declaration is in `root`, with each flag's value for `env`.
+ * Null when no member holds the directory, since only a member has flags.
+ */
+export declare function memberFlagBindings(root: string, projectDir: string, env: string): Promise<MemberFlagBindings | null>;
+//# sourceMappingURL=flags-read.d.ts.map

package/dist/workspace/flags-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags-read.d.ts","sourceRoot":"","sources":["../../src/workspace/flags-read.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AASzD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CA4C9E;AAED,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,KAAK,EAAE,SAAS,GAAG,SAAS,CAAC;CAC9B;AAED,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrC,mHAAmH;IACnH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CA2B1H"}

package/dist/workspace/flags-read.js

@@ -0,0 +1,103 @@
+/**
+ * Reading a workspace's feature flags (#4024): every flag of the declared
+ * flag kinds, and the flags of one member by parameter. Kept apart from
+ * `./flags.ts`, which `records.ts` loads, since reading goes through
+ * `records-cli.ts`.
+ */
+import { join, relative, resolve, sep } from "node:path";
+import { loadRecordKind } from "./records.js";
+const str = (v) => (typeof v === "string" && v !== "" ? v : null);
+/** A flag value as the record writes it, or undefined for one a build-time parameter can't hold. */
+function flagValue(v) {
+    return typeof v === "string" || typeof v === "number" || typeof v === "boolean" ? v : undefined;
+}
+/**
+ * Every flag of every flag kind the declaration at `root` names, read in the
+ * working tree. A kind without a flag block is skipped without reading its
+ * records. Throws a `RecordReadError` when a flag kind or its records can't
+ * be read, and a `WorkspaceReadError` when the declaration can't.
+ */
+export async function readWorkspaceFlags(root) {
+    const { readDeclaration, declaredRecordKinds } = await import("./declaration.js");
+    const { workingTree } = await import("./tree.js");
+    const declaration = readDeclaration(workingTree(root));
+    const out = { flags: [], invalid: [] };
+    const declared = declaredRecordKinds(declaration);
+    if (declared.length === 0)
+        return out;
+    const { readRecordsFor } = await import("./records-cli.js");
+    for (const d of declared) {
+        const file = join(root, ...d.path.split("/"));
+        const loaded = await loadRecordKind(file, root);
+        const flag = loaded.kind.flag;
+        if (!flag)
+            continue;
+        const { result, root: repo } = await readRecordsFor({ kind: file, cwd: root, current: true });
+        for (const r of result.records) {
+            const path = relative(root, join(repo, ...r.path.split("/"))).split(sep).join("/");
+            const member = r.data ? str(r.data[flag.member]) : null;
+            if (!r.valid || r.id === null || r.data === null) {
+                out.invalid.push({ kind: d.path, path, member, message: r.reasons.map((x) => `${x.code}: ${x.message}`).join("; ") || "the record can't be read" });
+                continue;
+            }
+            const values = {};
+            const raw = r.data[flag.values];
+            if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+                for (const [env, v] of Object.entries(raw)) {
+                    const value = flagValue(v);
+                    if (value !== undefined)
+                        values[env] = value;
+                }
+            }
+            out.flags.push({
+                id: r.id,
+                kind: d.path,
+                path,
+                member: member ?? "",
+                param: str(r.data[flag.param]) ?? "",
+                owner: str(r.data[flag.owner]) ?? "",
+                values,
+                work: r.flag?.work ?? null,
+                implements: r.flag?.implements ?? [],
+                stale: r.flag?.stale ?? false,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * The flags that back parameters of the member holding `projectDir`, in the
+ * workspace whose declaration is in `root`, with each flag's value for `env`.
+ * Null when no member holds the directory, since only a member has flags.
+ */
+export async function memberFlagBindings(root, projectDir, env) {
+    const { readDeclaration, resolveGroups, ownerOf } = await import("./declaration.js");
+    const { workingTree } = await import("./tree.js");
+    const tree = workingTree(root);
+    const declaration = readDeclaration(tree);
+    const rel = relative(root, resolve(projectDir)).split(sep).join("/");
+    const owner = ownerOf(declaration, resolveGroups(declaration, tree), rel === "" ? "" : rel);
+    if (!owner || !("member" in owner))
+        return null;
+    const member = owner.member.name;
+    const read = await readWorkspaceFlags(root);
+    const errors = [];
+    for (const bad of read.invalid) {
+        if (bad.member === member || bad.member === null)
+            errors.push(`flag record ${bad.path} is not valid, so no build reads it: ${bad.message}`);
+    }
+    const byParam = {};
+    const seen = new Map();
+    for (const f of read.flags) {
+        if (f.member !== member)
+            continue;
+        const other = seen.get(f.param);
+        if (other !== undefined) {
+            errors.push(`flags ${other} and ${f.id} both set build parameter "${f.param}" of member ${member}; one flag backs one parameter`);
+            continue;
+        }
+        seen.set(f.param, f.id);
+        byParam[f.param] = { flag: f.id, value: f.values[env] };
+    }
+    return { member, byParam, errors };
+}