@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/pr-report.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/pr-report/v1/pr-report.schema.json",
+  "title": "pull-request report",
+  "description": "What one stage of the pull-request loop (#3183) planned or applied: the members a change reaches, the digest the gate binds, where the approval stands and how the stage ended. Written by `chant components pr-plan` (pr-plan.json) and `chant components pr-apply` (pr-apply.json), and built by prReport in @intentius/chant/components/pr-run. The pull-request note is rendered from it by renderPrNote in @intentius/chant/pr-loop. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version.",
+  "type": "object",
+  "required": ["$schema", "contract", "stage", "pr", "env", "base", "head", "op", "gate", "digest", "status", "approval", "selection", "members", "changeSet"],
+  "properties": {
+    "$schema": { "const": "https://intentius.io/chant/schemas/workspace/pr-report/v1/pr-report.schema.json" },
+    "contract": { "const": 1 },
+    "stage": { "enum": ["plan", "apply"] },
+    "pr": {
+      "type": ["integer", "null"],
+      "minimum": 1,
+      "description": "The pull or merge request number. null when an apply found no pull request that merged its commit."
+    },
+    "env": { "type": "string" },
+    "member": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{0,39}$",
+      "description": "The workspace member whose pipeline ran the stage. Absent outside a workspace member."
+    },
+    "base": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The commit the change is measured from: the merge base of the given base and head." },
+    "head": { "type": "string", "pattern": "^[0-9a-f]{40,64}$" },
+    "op": {
+      "type": "string",
+      "description": "The gate's op, pr-<number>, or pr-<number>-<member> for a workspace member's pipeline. Its ledger is _gates/<op>.jsonl on chant/lifecycle. pr-unknown when no pull request was found."
+    },
+    "gate": { "type": "string", "description": "The gate the apply waits on, pr-apply unless the pipeline names another." },
+    "digest": {
+      "type": "string",
+      "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$",
+      "description": "The change-set digest of what this stage planned: computePlanDigest(\"change-set\", ...) over every member's { member, planDigest }. What the gate binds."
+    },
+    "status": {
+      "enum": ["planned", "plan-failed", "nothing", "applied", "failed", "refused"],
+      "description": "planned: every member planned (plan stage). plan-failed: a member failed to plan, so nothing can apply. nothing: no component deploys what the change touches. applied: every member applied. failed: a member failed to apply and its dependents did not run. refused: nothing applied, see refusal."
+    },
+    "refusal": {
+      "enum": ["not-approved", "plan-changed", "not-a-reviewer", "no-pull-request"],
+      "description": "Why an apply refused. plan-changed: an approval stands for another digest, so the plan changed after review."
+    },
+    "message": { "type": "string", "description": "The refusal or failure as printed." },
+    "resumed": {
+      "type": "object",
+      "required": ["applied"],
+      "description": "Apply stage with --resume (#3464): an earlier attempt at the approved set failed partway. This run applied the rest under the same approval.",
+      "properties": {
+        "applied": { "type": "array", "items": { "type": "string" }, "description": "Components the earlier attempt applied, which this run did not run again." }
+      }
+    },
+    "approval": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": { "enum": ["approved", "changed", "pending"], "description": "approved: an approval stands for digest. changed: one stands for another digest. pending: none stands." },
+        "approvedBy": { "type": "array", "items": { "type": "string" }, "description": "Who approved digest, as the approval names them (github:<login>, gitlab:<login>, <forge>@<host>:<login>, or a signer)." },
+        "approved": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "With changed: the digest that was approved." }
+      }
+    },
+    "selection": {
+      "type": "object",
+      "required": ["changed", "dependents", "unclaimed", "indeterminate", "waves"],
+      "description": "Component names. The fan-out derivation the change gives (#2417).",
+      "properties": {
+        "changed": { "type": "array", "items": { "type": "string" }, "description": "Components deploying a unit the change touched, in dependency order." },
+        "dependents": { "type": "array", "items": { "type": "string" }, "description": "Components selected because they depend on a changed one, in dependency order." },
+        "unclaimed": { "type": "array", "items": { "type": "string" }, "description": "Units the change touched that no component deploys." },
+        "indeterminate": { "type": "array", "items": { "type": "string" }, "description": "Components a source diff cannot judge that the walk did not reach." },
+        "waves": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "description": "The selected components in parallel-safe waves, in apply order." }
+      }
+    },
+    "members": {
+      "type": "array",
+      "description": "One entry per change-set member, sorted by member.",
+      "items": {
+        "type": "object",
+        "required": ["member", "component", "planDigest", "status", "counts"],
+        "properties": {
+          "member": { "type": "string", "description": "The member's name in the change set: the root, for a terraform-family step." },
+          "component": { "type": "string" },
+          "planDigest": { "type": ["string", "null"], "description": "What a gate on this member alone binds. null when it failed to plan." },
+          "status": { "enum": ["planned", "plan-failed", "applied", "failed", "blocked"] },
+          "counts": {
+            "type": "object",
+            "required": ["create", "update", "replace", "delete"],
+            "properties": {
+              "create": { "type": "integer", "minimum": 0 },
+              "update": { "type": "integer", "minimum": 0 },
+              "replace": { "type": "integer", "minimum": 0 },
+              "delete": { "type": "integer", "minimum": 0 }
+            }
+          },
+          "error": { "type": "string" },
+          "inputsMoved": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Apply stage: components this one depends on whose outputs changed when they applied. It applied the plan it was approved with; the next run plans it against the new values."
+          }
+        }
+      }
+    },
+    "changeSet": {
+      "type": "object",
+      "description": "The change-set document over every member (change-set.schema.json). Its digest equals digest."
+    }
+  }
+}

package/dist/workspace/principal-classes.js

@@ -0,0 +1,245 @@
+/**
+ * Principal classes (#2524 D5; #3080, ws-079).
+ *
+ * A principal class names a set of principals so the declaration can scope
+ * what they write. Four are core: `agent`, `runner` and `service`, each the
+ * holders of the role of that name in the trust policy at base, and `human`,
+ * everyone else. A plugin adds domain classes as data, the way it adds member
+ * kinds: a JSON file at its `./workspace-principals` subpath, read through
+ * the package's `package.json` and never imported. Each class it supplies
+ * names the role whose grant puts a principal in it.
+ *
+ * A principal's classes are read only from role grants at base, through
+ * {@link classesOf}. Core classes are tried first, then the domain classes
+ * in pin order and file order; the first that holds is the class write scope
+ * judges the principal as, and `human` is the rest. A gate or a record that
+ * asks whether a principal is in a class (#3163) asks {@link classesOf},
+ * which lists every class the principal's grants put it in.
+ *
+ * A path-pinned plugin's classes are read from the base revision when the
+ * caller has it (write scope does), so a change can't remap a class by
+ * editing its own copy of the plugin. A package pin is read from the
+ * installed package, which must be at the version the base pins.
+ */
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, posix } from "node:path";
+import { kindsExportTarget, pinnedPackageDir } from "./kinds.js";
+import schema from "./workspace-principals.schema.json" with { type: "json" };
+import { joinPath } from "./tree.js";
+import { CORE_CLASSES, CORE_PRINCIPAL_CLASSES, grantedClasses } from "./identity-gate-rule.js";
+export const PRINCIPALS_SCHEMA_ID = schema.$id;
+/** The subpath a package publishes its principal classes at. */
+export const PRINCIPALS_SUBPATH = "./workspace-principals";
+export { CORE_CLASSES, CORE_PRINCIPAL_CLASSES } from "./identity-gate-rule.js";
+/** The grammar of a class name, as `workspace-principals.schema.json` and the declaration's writeScope keys say it. */
+export const CLASS_NAME = /^(?!x-)[a-z][a-z0-9-]{0,39}$/;
+const CORE_ROLES = new Set(CORE_CLASSES.map((c) => c.role).filter((r) => r !== null));
+export function createClassRegistry(extra = []) {
+    const all = [...CORE_CLASSES, ...extra];
+    const byName = new Map(all.map((c) => [c.name, c]));
+    return {
+        get: (name) => byName.get(name),
+        names: () => all.map((c) => c.name),
+        all: () => all,
+    };
+}
+/** The four core classes and nothing else: what a workspace whose pins supply no class has. */
+export function coreClassRegistry() {
+    return createClassRegistry();
+}
+/**
+ * The role grants a class is read from. Every read of roles for a class goes
+ * through here, so where the grants live (`.chant/trust.json` today,
+ * possibly the declaration, #2547) is decided in one place: the policy.
+ */
+export function roleGrants(policy) {
+    return policy.roles;
+}
+/**
+ * Every class `principal`'s role grants at base put it in, in registry order
+ * (core first). Empty for a principal in no class but `human`, and for null.
+ * Names compare as `normalisePrincipal` (`./records.ts`) folds them.
+ */
+export function classesOf(classes, policy, principal) {
+    return grantedClasses(classes.all(), roleGrants(policy), principal);
+}
+/** The class write scope judges `principal` as: the first class its grants put it in, or `human`. */
+export function principalClass(policy, principal, classes = coreClassRegistry()) {
+    return classesOf(classes, policy, principal)[0] ?? "human";
+}
+let compiled;
+function validator() {
+    if (compiled)
+        return compiled;
+    const require = createRequire(import.meta.url);
+    // ajv is CommonJS; its class is the default export, or that export's own default.
+    const mod = require("ajv/dist/2020");
+    const Ajv = (mod.default ?? mod);
+    compiled = new Ajv({ allErrors: true, strict: true }).compile(schema);
+    return compiled;
+}
+/**
+ * Check the text of a principals file against
+ * `workspace-principals.schema.json` and the rules the schema can't say: no
+ * core name or core role, and no name or role twice. `source` names the pin
+ * in the classes and in the messages.
+ */
+export function parseClassData(text, source) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        return { classes: [], problems: [`${source}: the principals file is not JSON (${err.message})`] };
+    }
+    const validate = validator();
+    if (!validate(raw)) {
+        const problems = (validate.errors ?? []).map((e) => `${source}: ${e.instancePath || "the principals file"} ${e.message ?? "is invalid"}`);
+        return { classes: [], problems: [...new Set(problems)] };
+    }
+    const problems = [];
+    const classes = [];
+    const names = new Set();
+    const roles = new Set();
+    for (const c of raw.classes) {
+        if (CORE_PRINCIPAL_CLASSES.includes(c.name)) {
+            problems.push(`${source}: class ${c.name} is a core class and can't be supplied by a package`);
+            continue;
+        }
+        if (CORE_ROLES.has(c.role)) {
+            problems.push(`${source}: class ${c.name} names the role ${c.role}, which puts a principal in the core ${c.role} class`);
+            continue;
+        }
+        if (names.has(c.name)) {
+            problems.push(`${source}: class ${c.name} is listed twice`);
+            continue;
+        }
+        if (roles.has(c.role)) {
+            problems.push(`${source}: class ${c.name} names the role ${c.role}, which another class in the file names; a role puts a principal in one class`);
+            continue;
+        }
+        names.add(c.name);
+        roles.add(c.role);
+        classes.push({ name: c.name, description: c.description, role: c.role, source });
+    }
+    return { classes, problems };
+}
+/** A package directory on disk. */
+export function diskFiles(dir) {
+    return (path) => {
+        try {
+            return readFileSync(join(dir, ...path.split("/")), "utf-8");
+        }
+        catch {
+            return undefined;
+        }
+    };
+}
+/** A package directory at `dir` in `tree`, such as the workspace at the base revision. */
+export function treeFiles(tree, dir) {
+    return (path) => {
+        const full = joinPath(dir, path);
+        if (tree.stat(full) !== "file")
+            return undefined;
+        try {
+            return tree.read(full);
+        }
+        catch {
+            return undefined;
+        }
+    };
+}
+/** Read the classes a package publishes at `./workspace-principals`. Reads files only; imports nothing. A package that publishes none supplies none. */
+export function readPackageClasses(files, source) {
+    const manifest = files("package.json");
+    if (manifest === undefined)
+        return { classes: [], problems: [`${source}: no readable package.json`] };
+    let pkg;
+    try {
+        pkg = JSON.parse(manifest);
+    }
+    catch {
+        return { classes: [], problems: [`${source}: package.json is not JSON`] };
+    }
+    const target = kindsExportTarget(pkg, PRINCIPALS_SUBPATH);
+    if (target === undefined)
+        return { classes: [], problems: [] };
+    if (typeof target !== "string")
+        return { classes: [], problems: [`${source}: ${target.problem}`] };
+    const inside = posix.normalize(target.slice(2));
+    if (inside.startsWith("../") || inside === "..")
+        return { classes: [], problems: [`${source}: exports["${PRINCIPALS_SUBPATH}"] points outside the package`] };
+    const text = files(inside);
+    if (text === undefined)
+        return { classes: [], problems: [`${source}: exports["${PRINCIPALS_SUBPATH}"] names ${target}, which does not exist`] };
+    return parseClassData(text, source);
+}
+/**
+ * The classes a workspace knows: the core four plus every class its pins
+ * supply. A package pin is read from the installed package, looked up from
+ * `workspaceRoot`, and must be at the pinned version. A path pin is read
+ * through `tree` when given (the base revision, for write scope), else from
+ * `workspaceRoot` on disk, checked against its integrity digest. A class
+ * name, or a role, two pins both supply is a problem, and every class
+ * involved is left out, so a writeScope entry for it reads as unknown and
+ * fails closed. Never throws.
+ */
+export function loadClassRegistry(pins, workspaceRoot, opts = {}) {
+    const problems = [];
+    const extra = [];
+    const byName = new Map();
+    const byRole = new Map();
+    const clashing = new Set();
+    pins.forEach((pin, i) => {
+        let files;
+        let source;
+        if (pin.path && opts.tree) {
+            files = treeFiles(opts.tree, pin.path);
+            source = pin.path;
+        }
+        else {
+            const found = pinnedPackageDir(pin, workspaceRoot);
+            if (found === null)
+                return;
+            if ("problem" in found) {
+                problems.push({ pin: i, message: found.problem });
+                return;
+            }
+            files = diskFiles(found.dir);
+            source = found.source;
+        }
+        const read = readPackageClasses(files, source);
+        for (const p of read.problems)
+            problems.push({ pin: i, message: p });
+        for (const c of read.classes) {
+            const named = byName.get(c.name);
+            const roled = byRole.get(c.role);
+            if (named !== undefined || roled !== undefined) {
+                clashing.add(c.name);
+                if (named !== undefined) {
+                    problems.push({ pin: i, message: `class ${c.name} is supplied by both ${named} and ${source}; a class name has one source` });
+                }
+                else {
+                    const other = extra.find((e) => e.role === c.role);
+                    clashing.add(other.name);
+                    problems.push({ pin: i, message: `class ${c.name} (${source}) names the role ${c.role}, which class ${other.name} (${roled}) names; a role puts a principal in one class` });
+                }
+                continue;
+            }
+            byName.set(c.name, source);
+            byRole.set(c.role, source);
+            extra.push(c);
+        }
+    });
+    // A name or role two pins both supply is left out altogether: neither reading is safe.
+    return { registry: createClassRegistry(extra.filter((c) => !clashing.has(c.name))), problems };
+}
+/**
+ * The writeScope keys no class in `classes` has, in file order. A writer
+ * judged `human` may be in such a class, since nothing says which role puts
+ * a principal in it, so write scope refuses that writer (fail closed).
+ */
+export function unknownScopeClasses(writeScope, classes) {
+    return Object.keys(writeScope ?? {}).filter((name) => classes.get(name) === undefined);
+}