@intentius/chant 0.80.0 → 0.81.0

package/src/workspace/trust/verify.ts

@@ -0,0 +1,194 @@
+/**
+ * Verify a change against the policy at its base (#2524 D5, Threat model).
+ *
+ * This is what CI runs on a protected branch: every commit in `base..head` is
+ * asked of the attestors with the policy read at base, so nothing the change
+ * does to its own copy of the policy counts. A change that edits the policy
+ * (the signers file or `.chant/trust.json`) is a protected write: every commit
+ * that touches those files must be attested by a signer the base policy
+ * trusts, and by an admin when the base policy grants the admin role.
+ *
+ * Attestation is opt-in (#2525 rule 6). Without a signers file at base the
+ * check passes and says so, unless `--require attested` asks for more.
+ */
+
+import { execFileSync } from "node:child_process";
+import { type CommitAttestor, type ProvenanceLevel } from "./attestor";
+import { policyAtBase, commitProvenance, resolveBase, type BaseSource, type RecordProvenance } from "./provenance";
+import { policyWriters, protectedPaths, type ExcludedSigner, type TrustPolicy } from "./policy";
+
+export interface CommitVerdict extends RecordProvenance {
+  commit: string;
+  subject: string;
+  /** A merge that changes nothing of its own; its parents are checked instead. */
+  skipped?: string;
+}
+
+export interface ProtectedWrite {
+  commit: string;
+  paths: string[];
+  level: ProvenanceLevel;
+  principal?: string;
+  allowed: boolean;
+  reason: string;
+}
+
+export interface ChangeReport {
+  base: string | null;
+  baseFrom: BaseSource | null;
+  head: string | null;
+  policy: {
+    active: boolean;
+    signersPath: string;
+    principals: string[];
+    excluded: ExcludedSigner[];
+    writers: string[];
+    problems: string[];
+  };
+  require: ProvenanceLevel | null;
+  commits: CommitVerdict[];
+  protectedPaths: string[];
+  /** Protected paths whose content differs between the merge base and head. */
+  protectedChanged: string[];
+  protectedWrites: ProtectedWrite[];
+  notes: string[];
+  failures: string[];
+  ok: boolean;
+}
+
+export interface VerifyOptions {
+  repo: string;
+  base?: string;
+  head?: string;
+  require?: ProvenanceLevel;
+  attestors: readonly CommitAttestor[];
+}
+
+function git(repo: string, args: string[]): string {
+  return execFileSync("git", args, { cwd: repo, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+}
+
+/**
+ * Commits in `range` that change any of `paths`, each with the paths it
+ * changes. Merges count only for what they change beyond every parent.
+ */
+export function commitsTouching(repo: string, range: string, paths: string[]): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  const log = git(repo, ["--literal-pathspecs", "log", "-c", "--name-only", "--no-renames", "--format=%x00%H", range, "--", ...paths]);
+  const wanted = new Set(paths);
+  let commit = "";
+  for (const line of log.split("\n")) {
+    if (line.startsWith("\0")) commit = line.slice(1).trim();
+    else if (line && wanted.has(line)) out.set(commit, [...(out.get(commit) ?? []), line]);
+  }
+  return out;
+}
+
+/** Whether a merge commit changes nothing beyond what its parents bring. */
+function mergeWithoutOwnChanges(repo: string, commit: string, parents: number): boolean {
+  if (parents < 2) return false;
+  return git(repo, ["diff-tree", "-c", "--name-only", "--no-commit-id", "-r", commit]).trim() === "";
+}
+
+export function verifyChange(opts: VerifyOptions): ChangeReport {
+  const { repo } = opts;
+  const base = resolveBase(repo, opts.base);
+  const policy: TrustPolicy = policyAtBase(repo, base);
+  const report: ChangeReport = {
+    base: base.commit,
+    baseFrom: base.from,
+    head: null,
+    policy: {
+      active: policy.active,
+      signersPath: policy.signersPath,
+      principals: [...new Set(policy.signers.map((s) => s.principal))].sort(),
+      excluded: policy.excluded,
+      writers: [...policyWriters(policy)].sort(),
+      problems: policy.problems,
+    },
+    require: opts.require ?? null,
+    commits: [],
+    protectedPaths: protectedPaths(policy),
+    protectedChanged: [],
+    protectedWrites: [],
+    notes: [],
+    failures: [],
+    ok: false,
+  };
+  const headRev = opts.head ?? "HEAD";
+  let head: string | undefined;
+  try {
+    head = headRev.startsWith("-") ? undefined : git(repo, ["rev-parse", "--verify", "--quiet", `${headRev}^{commit}`]).trim() || undefined;
+  } catch {
+    head = undefined;
+  }
+  if (!base.commit) report.failures.push(base.problem ?? "no base revision");
+  if (!head) report.failures.push(`--head ${headRev} names no commit in this repository`);
+  if (!base.commit || !head) return report;
+  report.head = head;
+  if (policy.problems.length > 0) {
+    report.failures.push(...policy.problems.map((p) => `the policy at base cannot be read, so nothing verifies: ${p}`));
+    return report;
+  }
+
+  const mergeBase = git(repo, ["merge-base", base.commit, head]).trim();
+  const changedPaths = git(repo, ["--literal-pathspecs", "diff", "--name-only", "--no-renames", mergeBase, head, "--", ...report.protectedPaths])
+    .split("\n")
+    .filter(Boolean);
+  report.protectedChanged = changedPaths;
+
+  if (!policy.active) {
+    report.notes.push(`no signers file (${policy.signersPath}) at base ${base.commit.slice(0, 8)}: attestation is off and nothing is verified`);
+    if (changedPaths.includes(policy.signersPath)) {
+      report.notes.push(`this change adds ${policy.signersPath}; it applies to changes made after it is merged, never to this one`);
+    }
+    if (opts.require) report.failures.push(`--require ${opts.require} was given, and there is no signers file at base to attest anything`);
+    report.ok = report.failures.length === 0;
+    return report;
+  }
+
+  // Every commit in the change, judged by the policy at base.
+  const listing = git(repo, ["rev-list", "--reverse", "--parents", `${base.commit}..${head}`]).split("\n").filter(Boolean);
+  const verdicts = new Map<string, CommitVerdict>();
+  for (const line of listing) {
+    const [commit, ...parents] = line.split(" ");
+    const subject = git(repo, ["log", "-1", "--format=%s", commit]).trim();
+    const p = commitProvenance(repo, policy, commit, opts.attestors);
+    const v: CommitVerdict = { ...p, commit, subject };
+    if (p.level !== "attested" && mergeWithoutOwnChanges(repo, commit, parents.length)) {
+      v.skipped = "a merge with no changes of its own; the commits it brings are checked instead";
+    }
+    verdicts.set(commit, v);
+    report.commits.push(v);
+  }
+
+  // Protected writes: every commit that touches the policy needs a writer's signature.
+  if (changedPaths.length > 0) {
+    const writers = policyWriters(policy);
+    const touching = commitsTouching(repo, `${base.commit}..${head}`, report.protectedPaths);
+    if (touching.size === 0) {
+      report.failures.push(`the policy files ${changedPaths.join(", ")} differ from base, and no commit in the change accounts for it`);
+    }
+    for (const [commit, paths] of touching) {
+      const v = verdicts.get(commit) ?? { ...commitProvenance(repo, policy, commit, opts.attestors), commit, subject: "" };
+      const allowed = v.level === "attested" && v.principal !== undefined && writers.has(v.principal);
+      const who = policy.roles.admin?.length ? "an admin the policy at base names" : "a signer the policy at base lists";
+      const reason = allowed
+        ? `signed by ${v.principal}, ${who.replace(/^an? /, "")}`
+        : v.level === "attested"
+          ? `signed by ${v.principal}, who is not ${who}`
+          : `${paths.join(", ")} is protected and needs a signature by ${who}: ${v.reason}`;
+      report.protectedWrites.push({ commit, paths, level: v.level, ...(v.principal ? { principal: v.principal } : {}), allowed, reason });
+      if (!allowed) report.failures.push(`${commit.slice(0, 8)} changes ${paths.join(", ")}: ${reason}`);
+    }
+  }
+
+  if (opts.require) {
+    for (const v of report.commits) {
+      if (v.skipped || v.level === opts.require) continue;
+      report.failures.push(`${v.commit.slice(0, 8)} is ${v.level}, and --require ${opts.require} was given: ${v.reason}`);
+    }
+  }
+  report.ok = report.failures.length === 0;
+  return report;
+}

package/src/workspace/which-chant.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Which chant reads the declaration (#2536; #2524 D15, ws-021): the root's
+ * chant, named by a `@intentius/chant` pin; without a pin, the reader's own
+ * chant, if it meets `minReader`.
+ */
+
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, declaration, REPO, repo } from "./__fixtures__/contract-repo";
+import { readerVersion } from "./declaration";
+import { workspaceGraph } from "./graph-cli";
+import { runChecks } from "./lineage-check";
+import { listWorkspace } from "./ls";
+import { workspaceStatus } from "./status";
+import { handToRootChant, HANDED_TO_ROOT_ENV, locateWorkspace, rootChantBin } from "./which-chant";
+
+afterAll(cleanScratch);
+
+const MAIN = join(REPO, "packages", "core", "src", "cli", "main.ts");
+const LOADER = pathToFileURL(join(REPO, "node_modules", "tsx", "dist", "loader.mjs")).href;
+
+/** An installed @intentius/chant at `version` whose bin reports how it was called, and exits 7. */
+const installedChant = (version: string) => ({
+  "node_modules/@intentius/chant/package.json": JSON.stringify({ name: "@intentius/chant", version, bin: { chant: "bin/chant" } }),
+  "node_modules/@intentius/chant/bin/chant": { text: `#!/bin/sh\necho "root chant ${version}: $* ($${HANDED_TO_ROOT_ENV})"\nexit 7\n`, mode: 0o755 },
+});
+
+const pins = (version: string) => ({ pins: [{ package: "@intentius/chant", version }] });
+
+/** The error code each read-contract command gives for the workspace at `cwd`, or "ok". */
+async function codes(cwd: string): Promise<string[]> {
+  const ls = listWorkspace({ cwd });
+  const graph = (await workspaceGraph({ cwd })).doc;
+  const status = await workspaceStatus({ cwd, env: "dev", readLedger: async () => ({ records: [], malformed: 0 }) });
+  const check = await runChecks(cwd);
+  const checkCode = "error" in check ? check.error.code : (check.declaration?.diagnostics.find((d) => d.ruleId === "WSP001")?.code ?? "ok");
+  return [...[ls, graph, status].map((d) => ("error" in d ? d.error.code : "ok")), checkCode];
+}
+
+function chant(cwd: string, ...args: string[]) {
+  return spawnSync(process.execPath, ["--import", LOADER, MAIN, ...args], {
+    cwd,
+    encoding: "utf-8",
+    timeout: 120_000,
+    env: { ...process.env, TSX_DISABLE_CACHE: "1", NO_COLOR: "1", [HANDED_TO_ROOT_ENV]: "" },
+  });
+}
+
+describe("a root that pins no chant", () => {
+  test("the reader's own chant reads the declaration when it meets minReader", async () => {
+    const root = repo({ "chant.workspace.json": declaration([], { minReader: readerVersion() }) });
+    expect(await codes(root)).toEqual(["ok", "ok", "ok", "ok"]);
+  });
+
+  test("and refuses with reader-too-old when it doesn't", async () => {
+    const root = repo({ "chant.workspace.json": declaration([], { minReader: "999.0.0" }) });
+    expect(await codes(root)).toEqual(["reader-too-old", "reader-too-old", "reader-too-old", "reader-too-old"]);
+  });
+});
+
+describe("a root that pins a chant", () => {
+  test("the pinned version reads it when it is this chant", async () => {
+    const root = repo({ "chant.workspace.json": declaration([], pins(readerVersion())) });
+    expect(await codes(root)).toEqual(["ok", "ok", "ok", "ok"]);
+  });
+
+  test("any other chant refuses with root-chant-required, before minReader and the schema", async () => {
+    const root = repo({ "chant.workspace.json": declaration([], { ...pins("0.0.1"), minReader: "999.0.0", "x-new": true, newField: 1 }) });
+    expect(await codes(root)).toEqual(["root-chant-required", "root-chant-required", "root-chant-required", "root-chant-required"]);
+    const ls = listWorkspace({ cwd: root });
+    if (!("error" in ls)) throw new Error("expected a failure");
+    expect(ls.error.message).toMatch(/pins @intentius\/chant 0\.0\.1, and this is chant .*install @intentius\/chant@0\.0\.1 at the workspace root/);
+    expect(ls.error.location).toMatchObject({ file: "chant.workspace.json" });
+  });
+
+  test("the root's chant is the one installed there at the pinned version", () => {
+    const root = repo({ "chant.workspace.json": declaration([], pins("0.0.1")), ...installedChant("0.0.1") });
+    expect(rootChantBin(root, "0.0.1")).toBe(join(root, "node_modules", "@intentius", "chant", "bin", "chant"));
+    expect(rootChantBin(root, "0.0.2")).toBeUndefined();
+    expect(rootChantBin(repo({}), "0.0.1")).toBeUndefined();
+  });
+
+  test("handToRootChant runs the command under the root's chant, once at most", async () => {
+    const root = repo({ "chant.workspace.json": declaration([], pins("0.0.1")), ...installedChant("0.0.1") });
+    const saved = process.env[HANDED_TO_ROOT_ENV];
+    delete process.env[HANDED_TO_ROOT_ENV];
+    try {
+      expect(await handToRootChant(root, undefined, ["workspace", "ls"])).toBe(7);
+      // Not installed at the pinned version, or this chant is the pinned one: nothing to hand to.
+      const other = repo({ "chant.workspace.json": declaration([], pins("0.0.2")), ...installedChant("0.0.1") });
+      expect(await handToRootChant(other, undefined, ["workspace", "ls"])).toBeUndefined();
+      const same = repo({ "chant.workspace.json": declaration([], pins(readerVersion())), ...installedChant("0.0.1") });
+      expect(await handToRootChant(same, undefined, ["workspace", "ls"])).toBeUndefined();
+      process.env[HANDED_TO_ROOT_ENV] = "0.0.1";
+      expect(await handToRootChant(root, undefined, ["workspace", "ls"])).toBeUndefined();
+    } finally {
+      if (saved === undefined) delete process.env[HANDED_TO_ROOT_ENV];
+      else process.env[HANDED_TO_ROOT_ENV] = saved;
+    }
+  });
+
+  test(
+    "chant workspace ls, graph, check and status hand themselves to it, with --at reading the pin at the revision",
+    () => {
+      const root = repo({ "chant.workspace.json": declaration([], pins("0.0.1")), ...installedChant("0.0.1"), ".gitignore": "node_modules\n" }, true);
+      for (const args of [["workspace", "ls", "--json"], ["workspace", "graph"], ["workspace", "check", "--json"], ["workspace", "status", "dev"], ["workspace", "ls", "--at", "HEAD"]]) {
+        const r = chant(root, ...args);
+        expect(r.status, `${args.join(" ")}: ${r.stderr}`).toBe(7);
+        expect(r.stdout.trim()).toBe(`root chant 0.0.1: ${args.join(" ")} (0.0.1)`);
+      }
+      expect(locateWorkspace(root, "HEAD").at).toMatch(/^[0-9a-f]{40}$/);
+    },
+    240_000,
+  );
+});

package/src/workspace/which-chant.ts

@@ -0,0 +1,151 @@
+/**
+ * Where a workspace read starts, and which chant does it (#2536; #2524 D15,
+ * ws-016, ws-021).
+ *
+ * {@link locateWorkspace} finds the declaration from a directory, in the
+ * working tree or in one commit's git objects (`--at <rev>`), and gives the
+ * tree every read-contract command reads from.
+ *
+ * Which chant reads the declaration: the root's. The root names its chant by
+ * pinning `@intentius/chant` in the declaration's `pins`. When it pins one,
+ * that version reads the declaration, and any other chant refuses with
+ * `root-chant-required` (`parseDeclaration`'s `rootChant` option). The CLI
+ * first hands the whole command to the pinned chant when the root has it
+ * installed ({@link handToRootChant}), so a user sees the refusal only when
+ * it isn't. When the root pins no chant, the reader's own chant reads the
+ * declaration if it meets `minReader`, and refuses with `reader-too-old`
+ * otherwise. Members are always read by their own toolchains.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { findWorkspaceRoot } from "../project-root";
+import { CHANT_PACKAGE, DECLARATION_FILES, findDeclarationDir, pinnedChant, readerVersion, WorkspaceReadError } from "./declaration";
+import { parseJsonText } from "./jsonc";
+import { findInstalledPackage } from "./kinds";
+import { gitTop, gitTree, resolveCommit, workingTree, type WorkspaceTree } from "./tree";
+
+export interface LocatedWorkspace {
+  /** The files, rooted at the workspace root. */
+  tree: WorkspaceTree;
+  /** The workspace root relative to the git root, `"."` for the git root itself. Absolute outside git. */
+  root: string;
+  /** The workspace root on disk, where pinned packages and toolchains are installed. Also for `--at`. */
+  rootOnDisk: string;
+  /** The full commit id for `--at`, or null for the working tree. */
+  at: string | null;
+  /** The top of the git repository, when there is one. */
+  top: string | undefined;
+}
+
+const posix = (p: string) => p.split("\\").join("/");
+
+/**
+ * Find the workspace whose declaration is nearest above `cwd`, in the working
+ * tree or at revision `at`. Throws a {@link WorkspaceReadError}:
+ * `declaration-missing`, or for `--at`, `not-a-git-repository` and
+ * `revision-unknown`.
+ */
+export function locateWorkspace(cwd: string, at?: string): LocatedWorkspace {
+  const top = gitTop(cwd);
+  if (at !== undefined) {
+    if (!top) throw new WorkspaceReadError("not-a-git-repository", "--at reads git objects, and this directory is not in a git repository");
+    const commit = resolveCommit(top, at);
+    if (!commit) throw new WorkspaceReadError("revision-unknown", `--at ${at} names no commit in this repository`);
+    const whole = gitTree(top, commit);
+    const start = posix(relative(top, realpathSync(resolve(cwd))));
+    const found = findDeclarationDir(whole, start.startsWith("..") ? "" : start);
+    if (found === undefined) {
+      throw new WorkspaceReadError("declaration-missing", `no chant.workspace.json or .jsonc between ${start || "."} and the git root at ${commit.slice(0, 8)}`);
+    }
+    return {
+      tree: found === "" ? whole : gitTree(top, commit, found),
+      root: found === "" ? "." : found,
+      rootOnDisk: join(top, ...found.split("/")),
+      at: commit,
+      top,
+    };
+  }
+  const found = findWorkspaceRoot(cwd);
+  if (!found) {
+    throw new WorkspaceReadError(
+      "declaration-missing",
+      top
+        ? "no chant.workspace.json or .jsonc between this directory and the git root; chant workspace init proposes one"
+        : "no chant.workspace.json or .jsonc in this directory; chant workspace init proposes one",
+    );
+  }
+  // git reports the top with symlinks resolved (/private/var on macOS), so compare like with like.
+  const rel = top ? posix(relative(top, realpathSync(found.dir))) : found.dir;
+  return { tree: workingTree(found.dir), root: rel === "" ? "." : rel, rootOnDisk: found.dir, at: null, top };
+}
+
+/**
+ * The `bin/chant` of `@intentius/chant` at `version`, installed where the
+ * workspace root resolves packages. Undefined when it isn't installed there,
+ * or is installed at another version.
+ */
+export function rootChantBin(rootOnDisk: string, version: string): string | undefined {
+  const dir = findInstalledPackage(CHANT_PACKAGE, rootOnDisk);
+  if (!dir) return undefined;
+  let pkg: { version?: unknown; bin?: unknown };
+  try {
+    pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as typeof pkg;
+  } catch {
+    return undefined;
+  }
+  if (pkg.version !== version) return undefined;
+  const rel = typeof pkg.bin === "string" ? pkg.bin : (pkg.bin as Record<string, unknown> | undefined)?.chant;
+  if (typeof rel !== "string") return undefined;
+  const bin = join(dir, rel);
+  return existsSync(bin) ? bin : undefined;
+}
+
+/** Set in the environment of a command handed to the root's chant, so it is handed on once at most. */
+export const HANDED_TO_ROOT_ENV = "CHANT_WORKSPACE_ROOT_CHANT";
+
+/** The version the declaration at `located` pins for `@intentius/chant`, or undefined. Never throws. */
+export function declaredChantPin(located: LocatedWorkspace): string | undefined {
+  const file = DECLARATION_FILES.find((f) => located.tree.stat(f) === "file");
+  if (!file) return undefined;
+  let text: string;
+  try {
+    text = located.tree.read(file);
+  } catch {
+    return undefined;
+  }
+  const parsed = parseJsonText(text, { jsonc: file.endsWith(".jsonc") });
+  if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object" || Array.isArray(parsed.value)) return undefined;
+  return pinnedChant(parsed.value as Record<string, unknown>)?.version;
+}
+
+/**
+ * Hand a read-contract command to the root's chant (ws-021). When the
+ * declaration above `cwd` (at `at`, for `--at`) pins a chant other than this
+ * one, and the root has that chant installed, run the same command line
+ * under it and return its exit code. Otherwise return undefined, and this
+ * chant runs the command: it reads the declaration itself, or refuses with
+ * `root-chant-required` when the pinned chant isn't installed.
+ */
+export async function handToRootChant(cwd: string, at: string | undefined, argv: string[] = process.argv.slice(2)): Promise<number | undefined> {
+  if (process.env[HANDED_TO_ROOT_ENV]) return undefined;
+  let located: LocatedWorkspace;
+  try {
+    located = locateWorkspace(cwd, at);
+  } catch {
+    return undefined;
+  }
+  const pinned = declaredChantPin(located);
+  if (pinned === undefined || pinned === readerVersion()) return undefined;
+  const bin = rootChantBin(located.rootOnDisk, pinned);
+  if (!bin) return undefined;
+  return new Promise((done) => {
+    const child = spawn(bin, argv, { stdio: "inherit", env: { ...process.env, [HANDED_TO_ROOT_ENV]: pinned } });
+    child.on("error", (e) => {
+      process.stderr.write(`could not start the root's chant ${pinned} at ${bin}: ${e.message}\n`);
+      done(1);
+    });
+    child.on("close", (code) => done(code ?? 1));
+  });
+}

package/src/workspace/workspace-kinds.schema.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/kinds/v1/workspace-kinds.schema.json",
+  "title": "workspace-kinds.json",
+  "description": "Member kinds a plugin supplies (#2524 D3, #2535, ws-031). A package publishes this file as data at its ./workspace-kinds subpath. chant reads it with the file system and never imports the package, so reading kinds never loads a lexicon.",
+  "type": "object",
+  "required": [
+    "schema",
+    "kinds"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "An editor hint. chant ignores it."
+    },
+    "$comment": {
+      "type": "string",
+      "description": "A note for people. chant ignores it."
+    },
+    "schema": {
+      "const": 1,
+      "description": "The kinds format version."
+    },
+    "kinds": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/kind"
+      }
+    }
+  },
+  "patternProperties": {
+    "^x-": true
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "kind": {
+      "type": "object",
+      "required": [
+        "name",
+        "description",
+        "precedence",
+        "probe"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{0,39}$",
+          "description": "The kind's name, as a member's kind field names it. chant, workspace, other and examples are built in and can't be supplied."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "One line saying what the member's directory holds, for listings and error messages."
+        },
+        "precedence": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 999,
+          "description": "When the probes of several kinds claim one directory, the highest precedence decides. Two claiming kinds with the same highest precedence are a tie, and a tie fails. The built-in chant kind has 500 and workspace has 1000."
+        },
+        "probe": {
+          "$ref": "#/$defs/probe"
+        },
+        "outputs": {
+          "type": "array",
+          "uniqueItems": true,
+          "description": "The outputs every member of this kind exposes as link targets (#2524 D6, #2539). A member entry of the kind may list more in its own outputs field. Without this field the kind exposes only what each entry lists.",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 255,
+            "pattern": "^[^\\u0000-\\u001f]+$"
+          }
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    },
+    "probe": {
+      "type": "object",
+      "description": "What the probe checks in a member's directory. It runs no code. It passes when any of its clauses does, and it needs at least one.",
+      "minProperties": 1,
+      "properties": {
+        "anyFile": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "description": "The directory passes when a file matching one of these names sits directly in it. A * in a name matches any run of characters, so *.tf matches every Terraform file.",
+          "items": {
+            "$ref": "#/$defs/fileName"
+          }
+        },
+        "anyBlock": {
+          "type": "object",
+          "description": "The directory passes when a file directly in it, whose name matches one of in, has a line opening an unlabelled block named in blocks: leading space, the name, optional space, then {. No file is parsed.",
+          "required": [
+            "in",
+            "blocks"
+          ],
+          "properties": {
+            "in": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/fileName"
+              }
+            },
+            "blocks": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$"
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "fileName": {
+      "type": "string",
+      "description": "A file name, with no directory part. A * matches any run of characters.",
+      "pattern": "^(?!\\.\\.?$)[^/\\\\]+$"
+    }
+  }
+}

package/dist/components/unbound-gate-approval.d.ts

@@ -1,24 +0,0 @@
-/**
- * The warning a release ahead of environment- and plan-bound component gate
- * approvals (chant #2574).
- *
- * A component gate approval is keyed by the component and the gate name only,
- * so an approval given for one environment, or for one deploy, can pass the
- * same gate later on another environment or on a promote or rollback. The
- * next release binds each approval to the environment and the plan digest it
- * was given for, the way Op gates bind a plan since #2300, and refuses an
- * approval that records neither.
- *
- * This release only says so. When a component gate passes on an approval that
- * records no plan, the driver prints one warning per component and gate, per
- * process. The decision itself is unchanged.
- */
-import type { GateResolutionRecord } from "../lifecycle/gate-ledger.js";
-/** Forget which gates were warned about. For tests. */
-export declare function resetUnboundGateApprovalWarnings(): void;
-/**
- * Warn once for `component`'s `gate` when the approval that just passed it in
- * `env` records no plan. Returns whether a warning was printed.
- */
-export declare function warnOnUnboundComponentApproval(component: string, gate: string, env: string, resolution: GateResolutionRecord): boolean;
-//# sourceMappingURL=unbound-gate-approval.d.ts.map

package/dist/components/unbound-gate-approval.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"unbound-gate-approval.d.ts","sourceRoot":"","sources":["../../src/components/unbound-gate-approval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAMrE,uDAAuD;AACvD,wBAAgB,gCAAgC,IAAI,IAAI,CAEvD;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,oBAAoB,GAC/B,OAAO,CAcT"}