@intentius/chant 0.124.12 → 0.124.14

package/dist/workspace/declared-kinds.js

@@ -0,0 +1,106 @@
+/**
+ * The record kinds a declaration names, loaded (#2680).
+ *
+ * `chant.workspace.json` may name the workspace's record kinds, in the
+ * top-level `records` and in each member's `records`, so a reader never has to
+ * guess which kind files exist. `chant workspace ls` lists them, `check` fails
+ * on one that doesn't load (WSP115), and `records` and `graph --intent` read
+ * every one of them when `--kind` is not given.
+ *
+ * A kind file is looked for in the tree read, which is the revision under
+ * `--at`, and loaded from the working tree, as `records --kind` loads one.
+ * Loading imports the file, so it runs only where a command already runs a
+ * kind file.
+ */
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { declaredRecordKinds } from "./declaration.js";
+/** Why a declared kind can't be loaded: the codes `loadRecordKind` fails with. Closed, like every list of codes. */
+export const DECLARED_KIND_REASON_CODES = ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch"];
+/** The kind file of `declared` on disk, under the workspace root `rootOnDisk`. */
+export function declaredKindFile(declared, rootOnDisk) {
+    return join(rootOnDisk, ...declared.path.split("/"));
+}
+/**
+ * Every kind the declaration names, in {@link declaredRecordKinds} order, each
+ * with its name or the reason it can't be loaded. A kind file missing from
+ * `tree` is `kind-unreadable` without a load. With `load: false`, nothing is
+ * imported and only that is checked.
+ */
+export async function loadDeclaredKinds(declaration, tree, rootOnDisk, options = {}) {
+    const declared = declaredRecordKinds(declaration);
+    if (declared.length === 0)
+        return [];
+    const records = options.load === false ? undefined : await import("./records.js");
+    const out = [];
+    for (const d of declared) {
+        const file = declaredKindFile(d, rootOnDisk);
+        if (tree.stat(d.path) !== "file") {
+            out.push({ declared: d, file, kind: null, reason: { code: "kind-unreadable", message: `kind file ${d.path} does not exist${tree.label}` } });
+            continue;
+        }
+        if (!records) {
+            out.push({ declared: d, file, kind: null, reason: null });
+            continue;
+        }
+        try {
+            const loaded = await records.loadRecordKind(file);
+            const entry = { declared: d, file, kind: loaded.kind.name, reason: null };
+            if (loaded.kind.answers)
+                entry.points = await checkPoints(resolve(dirname(file), loaded.kind.answers.points), rootOnDisk, tree);
+            if (loaded.kind.work?.acceptance && options.acceptance) {
+                const counted = await countAcceptance(file, rootOnDisk, options.at);
+                if (counted)
+                    entry.acceptance = counted;
+            }
+            out.push(entry);
+        }
+        catch (err) {
+            if (!(err instanceof records.RecordReadError))
+                throw err;
+            // loadRecordKind names the file as it was given, here an absolute path: name it from the workspace root instead.
+            out.push({ declared: d, file, kind: null, reason: { code: err.code, message: err.message.split(file).join(d.path) } });
+        }
+    }
+    return out;
+}
+/** The acceptance counts of a work kind's current records, or undefined when they can't be read. */
+async function countAcceptance(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 && r.acceptance != null)
+            .map((r) => ({
+            item: r.id,
+            state: r.state,
+            met: r.acceptance.met,
+            total: r.acceptance.total,
+            file: join(read.root, ...r.path.split("/")),
+            unmet: r.warnings.find((w) => w.code === "work-acceptance-unmet")?.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("/");
+    if (file.startsWith("../"))
+        return { file, problems: [{ field: null, message: "is outside the workspace" }] };
+    if (tree.stat(file) !== "file")
+        return { file, problems: [{ field: null, message: `does not exist${tree.label}` }] };
+    const { parsePoints, PointsError } = await import("./points.js");
+    try {
+        parsePoints(tree.read(file), file);
+        return { file, problems: [] };
+    }
+    catch (err) {
+        if (err instanceof PointsError)
+            return { file, problems: err.problems };
+        throw err;
+    }
+}

package/dist/workspace/environments.js

@@ -0,0 +1,164 @@
+/**
+ * The environments a member's components may deploy to, for `chant workspace
+ * graph --composites` (#2695), so a reader such as hud can offer staging or
+ * prod beside the default without guessing a name.
+ *
+ * Each environment comes from one of three places, and says which:
+ *
+ * - `config`: a name the member's `chant.config.ts` declares in
+ *   `environments`. A pattern such as `pr-*` names no environment by itself
+ *   and is not listed, but it legalizes the ledger's `pr-42`.
+ * - `ledger`: an environment with a release ledger for the member on
+ *   `chant/lifecycle` (`_members/<member>/<env>/releases.jsonl`, or the flat
+ *   `<env>/releases.jsonl`, read the way `workspace status` reads it).
+ * - `builtin`: `local`, which `chant run --components` uses without `--env`
+ *   (`../cli/handlers/run.ts`), when neither the config nor the ledger names
+ *   it.
+ *
+ * A component may also declare environments of its own (#3153, ws-095),
+ * each with the site a release goes to there: the runtime that hosts it, its
+ * URL, a custom domain and the git remote its lifecycle records are pushed
+ * to. Each declared environment the member already lists carries that site,
+ * and one it doesn't is added with source `component` when `chant run --env`
+ * would take it, or left out with `environments-component-undeclared` when
+ * the config's environments don't cover it.
+ *
+ * `chant run --env` refuses a name the config's `environments` doesn't cover
+ * whenever it declares any (`unknownEnvError` in `../env.ts`), so a ledger
+ * environment the config no longer covers is left out, with a reason. The
+ * default is `local`: `chant.config.ts` has no default environment, and
+ * `chant run` without `--env` deploys to `local` even when the config's
+ * `environments` leaves it out.
+ *
+ * The config is the one `runtimes.ts` loads, in the working tree or the tree
+ * `--at` exported. The ledger is always the local `chant/lifecycle` branch,
+ * as for `workspace status`, and is never fetched.
+ */
+import { execFileSync } from "node:child_process";
+import { environmentName, isEnvironmentPattern, matchesDeclaredEnvironment } from "../config.js";
+import { LOCAL_RUNTIME } from "./runtimes.js";
+import { ENV_PATTERN, LIFECYCLE_REF, MEMBERS_DIR } from "./status.js";
+/** The environment `chant run --components` deploys to without `--env`. */
+export const LOCAL_ENVIRONMENT = "local";
+/** Why a member's environments are only `local`, or leave out one the ledger has. Closed: part of the read contract. */
+export const ENVIRONMENT_REASON_CODES = [
+    /** The member's chant.config.ts could not be read: the same read and the same code as its runtimes. */
+    "runtimes-config-unreadable",
+    /** The config declares no environments, so only local and the ledger's environments are listed. */
+    "environments-none-declared",
+    /** The ledger has releases in an environment the config's environments no longer cover, so chant run --env would refuse it. */
+    "environments-ledger-undeclared",
+    /** The chant/lifecycle branch exists and the member's ledger directories could not be listed. */
+    "environments-ledger-unreadable",
+    /** A component declares an environment the config's environments don't cover, so chant run --env would refuse it (#3153). */
+    "environments-component-undeclared",
+];
+function git(cwd, args, input) {
+    return execFileSync("git", args, { cwd, encoding: "utf-8", input, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"] });
+}
+function exists(cwd, spec) {
+    try {
+        git(cwd, ["rev-parse", "--verify", "--quiet", spec]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The environments with a release ledger for `member` on the local
+ * `chant/lifecycle` branch: the directories under `_members/<member>/` when it
+ * exists (the root member never has one), else the flat layout's top-level
+ * directories, that hold a `releases.jsonl`.
+ */
+export const readLedgerEnvironments = (member, cwd) => {
+    if (!exists(cwd, `refs/heads/${LIFECYCLE_REF}`))
+        return { envs: [], reason: null };
+    const own = member.dir !== "." && exists(cwd, `refs/heads/${LIFECYCLE_REF}:${MEMBERS_DIR}/${member.name}`);
+    const base = own ? `${MEMBERS_DIR}/${member.name}/` : "";
+    try {
+        const dirs = git(cwd, ["ls-tree", "--full-tree", `refs/heads/${LIFECYCLE_REF}:${base}`])
+            .split("\n")
+            .map((line) => line.match(/^\d+ tree [0-9a-f]+\t(.+)$/)?.[1])
+            .filter((name) => !!name && ENV_PATTERN.test(name));
+        if (dirs.length === 0)
+            return { envs: [], reason: null };
+        const checked = git(cwd, ["cat-file", "--batch-check"], dirs.map((d) => `refs/heads/${LIFECYCLE_REF}:${base}${d}/releases.jsonl\n`).join(""))
+            .split("\n")
+            .filter(Boolean);
+        return { envs: dirs.filter((_, i) => checked[i] !== undefined && !checked[i].endsWith(" missing")).sort(), reason: null };
+    }
+    catch (err) {
+        const message = (err instanceof Error ? err.message : String(err)).split("\n")[0];
+        return { envs: [], reason: { code: "environments-ledger-unreadable", message: `${LIFECYCLE_REF}:${base || "."}: ${message}` } };
+    }
+};
+/** Join a member's config and ledger into its environment list, `local` first, then config order, then the ledger's. */
+export function memberEnvironments(runtimes, ledger) {
+    const reasons = [];
+    const declared = runtimes?.environments ?? null;
+    if (runtimes && declared === null) {
+        const unreadable = runtimes.reasons.find((r) => r.code === "runtimes-config-unreadable");
+        reasons.push({ code: "runtimes-config-unreadable", message: unreadable?.message ?? "chant.config.ts could not be read" });
+    }
+    else if (declared && declared.length === 0) {
+        reasons.push({ code: "environments-none-declared", message: "chant.config.ts declares no environments, so only local and the environments in the ledger are listed" });
+    }
+    if (ledger?.reason)
+        reasons.push(ledger.reason);
+    const literals = (declared ?? []).map(environmentName).filter((n) => !isEnvironmentPattern(n));
+    const ledgerEnvs = ledger?.envs ?? [];
+    const covered = (env) => !declared || declared.length === 0 || matchesDeclaredEnvironment(declared, env);
+    const undeclared = ledgerEnvs.filter((e) => e !== LOCAL_ENVIRONMENT && !covered(e));
+    if (undeclared.length > 0) {
+        reasons.push({
+            code: "environments-ledger-undeclared",
+            message: `the ledger has releases in ${undeclared.join(", ")}, which chant.config.ts's environments don't cover, so chant run --env refuses ${undeclared.length === 1 ? "it" : "them"}`,
+        });
+    }
+    const out = [];
+    const add = (name, source) => {
+        if (!out.some((e) => e.name === name))
+            out.push({ name, default: name === LOCAL_ENVIRONMENT, source });
+    };
+    add(LOCAL_ENVIRONMENT, literals.includes(LOCAL_ENVIRONMENT) ? "config" : ledgerEnvs.includes(LOCAL_ENVIRONMENT) ? "ledger" : "builtin");
+    for (const name of literals)
+        add(name, "config");
+    for (const name of ledgerEnvs)
+        if (covered(name))
+            add(name, "ledger");
+    return { environments: out, reasons, declared };
+}
+/**
+ * The environments one component may deploy to, each with its command line.
+ * `declared` is what the component's contract says (#3153): an environment
+ * the member lists takes its site, and one it doesn't is added after the
+ * member's when `chant run --env` takes it. `reasons` collects the declared
+ * environments left out because the config's environments don't cover them.
+ * `hosts` are the runtimes the member configures; a site's runtime is used
+ * for the command only when it is one of them.
+ */
+export function componentEnvironments(component, member, runtime = LOCAL_RUNTIME, declared = [], hosts = [], reasons = []) {
+    const list = [...(member?.environments ?? [{ name: LOCAL_ENVIRONMENT, default: true, source: "builtin" }])];
+    const config = member?.declared;
+    const takes = (env) => !config || config.length === 0 || matchesDeclaredEnvironment(config, env);
+    const sites = new Map();
+    for (const d of declared) {
+        sites.set(d.name, { runtime: d.runtime ?? null, url: d.url ?? null, domain: d.domain ?? null, lifecycle: d.lifecycle ?? null });
+        if (list.some((e) => e.name === d.name))
+            continue;
+        if (takes(d.name))
+            list.push({ name: d.name, default: false, source: "component" });
+        else {
+            reasons.push({
+                code: "environments-component-undeclared",
+                message: `component ${component} declares environment ${d.name}, which chant.config.ts's environments don't cover, so chant run --env refuses it`,
+            });
+        }
+    }
+    return list.map((e) => {
+        const site = sites.get(e.name) ?? null;
+        const on = site?.runtime && (site.runtime === LOCAL_RUNTIME || hosts.includes(site.runtime)) ? site.runtime : runtime;
+        return { ...e, site, command: `chant run --components ${component}${on === LOCAL_RUNTIME ? "" : ` --on ${on}`}${e.default ? "" : ` --env ${e.name}`}` };
+    });
+}

package/dist/workspace/evidence.schema.json

@@ -0,0 +1,279 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/evidence/v1/evidence.schema.json",
+  "title": "chant workspace evidence output",
+  "description": "What `chant workspace evidence verify --json` prints (#2553), and what a refused `chant workspace evidence sign --json` prints: runner evidence, an in-toto statement over record hashes in a DSSE envelope, checked offline against the runner keys `.chant/trust.json` lists at the base revision. Version 1 of the read contract. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, each in the one closed list of `reason-codes.ts`.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "A runner key the policy at base lists signed the envelope. `status` says whether the records still hash as signed; it exits 1 when they don't.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "at",
+        "ok",
+        "status",
+        "runner",
+        "class",
+        "keyid",
+        "statement",
+        "subjects"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/evidence/v1/evidence.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "at": {
+          "type": "string",
+          "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$",
+          "description": "The commit the subjects were compared at."
+        },
+        "ok": {
+          "const": true
+        },
+        "status": {
+          "enum": [
+            "current",
+            "stale"
+          ],
+          "description": "current when every subject hashes the same at `at`; stale otherwise. Stale evidence is never reused."
+        },
+        "runner": {
+          "type": "string",
+          "description": "The runner principal whose key signed."
+        },
+        "class": {
+          "enum": [
+            "runner",
+            "service"
+          ],
+          "description": "A CI runner or a service, as `.chant/trust.json` lists it."
+        },
+        "keyid": {
+          "type": "string",
+          "description": "The ssh SHA256 fingerprint of the key that signed."
+        },
+        "statement": {
+          "$ref": "#/$defs/statement"
+        },
+        "subjects": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/subject"
+          }
+        }
+      }
+    },
+    "statement": {
+      "type": "object",
+      "description": "The in-toto Statement v1 the runner signed.",
+      "required": [
+        "_type",
+        "subject",
+        "predicateType",
+        "predicate"
+      ],
+      "properties": {
+        "_type": {
+          "const": "https://in-toto.io/Statement/v1"
+        },
+        "subject": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "digest"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "digest": {
+                "type": "object",
+                "required": [
+                  "sha256"
+                ],
+                "properties": {
+                  "sha256": {
+                    "type": "string",
+                    "pattern": "^[0-9a-f]{64}$"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "predicateType": {
+          "const": "https://intentius.io/chant/runner-evidence/v1"
+        },
+        "predicate": {
+          "type": "object",
+          "required": [
+            "runner",
+            "commit",
+            "tree",
+            "check"
+          ],
+          "properties": {
+            "runner": {
+              "type": "string"
+            },
+            "commit": {
+              "type": "string",
+              "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
+            },
+            "tree": {
+              "type": "string",
+              "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
+            },
+            "check": {
+              "type": "string",
+              "description": "The check's id, as given to --check-id."
+            },
+            "claim": {
+              "type": "object",
+              "required": [
+                "sha256"
+              ],
+              "properties": {
+                "sha256": {
+                  "type": "string",
+                  "pattern": "^[0-9a-f]{64}$"
+                }
+              }
+            },
+            "environment": {
+              "type": "object",
+              "required": [
+                "sha256"
+              ],
+              "properties": {
+                "sha256": {
+                  "type": "string",
+                  "pattern": "^[0-9a-f]{64}$"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "subject": {
+      "type": "object",
+      "required": [
+        "name",
+        "signed",
+        "now",
+        "matches"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The record's path from the repository root."
+        },
+        "signed": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "now": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$"
+            }
+          ],
+          "description": "The record's hash at `at`, or null when it is not there."
+        },
+        "matches": {
+          "type": "boolean"
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "The evidence was refused, or could not be checked. Exits 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "at",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/evidence/v1/evidence.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "at": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "string",
+              "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
+            }
+          ]
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "not-a-git-repository",
+                "revision-unknown",
+                "trust-policy-unreadable",
+                "envelope-unreadable",
+                "envelope-invalid",
+                "envelope-untrusted",
+                "evidence-payload-type",
+                "evidence-statement-invalid",
+                "evidence-runner-mismatch",
+                "runner-key-invalid",
+                "runner-key-is-signer",
+                "runner-key-unlisted",
+                "kind-unreadable",
+                "kind-invalid",
+                "schema-unreadable",
+                "schema-id-mismatch",
+                "schema-invalid",
+                "location-missing"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}