@intentius/chant 0.124.44 → 0.124.46

package/src/workspace/capabilities.schema.json

@@ -0,0 +1,229 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json",
+  "title": "chant capabilities catalog",
+  "description": "What `chant search --capabilities --json` prints (#4375): the capability catalog `chant search` answers `cap:` terms and `->[cap=...]` edges with, each capability's rule, and whether each lexicon the project loads can supply it. chant's MCP `capabilities` tool returns the same document. 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.46 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.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "capabilities",
+        "helpers"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": false,
+        "capabilities": {
+          "type": "array",
+          "description": "Every capability the catalog lists, in the order the rule file defines them.",
+          "items": {
+            "$ref": "#/$defs/capability"
+          }
+        },
+        "helpers": {
+          "type": "array",
+          "description": "Rules the capabilities use that the catalog does not list as capabilities of their own.",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "rule"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "rule": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "capability": {
+      "type": "object",
+      "required": [
+        "name",
+        "meaning",
+        "shape",
+        "params",
+        "search",
+        "answers",
+        "depth",
+        "lexicons",
+        "notEvaluated",
+        "uses",
+        "rule"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "meaning": {
+          "type": "string",
+          "description": "What the capability says, in one line."
+        },
+        "shape": {
+          "enum": [
+            "set",
+            "edge"
+          ],
+          "description": "set: a set of nodes, tested with cap:<name>. edge: pairs of nodes, walked with ->[cap=<name>] or <-[cap=<name>]."
+        },
+        "params": {
+          "type": "array",
+          "description": "Arguments, in order: cap:<name>(<a>, <b>). An optional one left out drops the test that reads it.",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "optional",
+              "meaning"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "optional": {
+                "type": "boolean"
+              },
+              "meaning": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "search": {
+          "type": "string",
+          "description": "The search term that asks for it: cap:<name> for a set, ->[cap=<name>] for an edge."
+        },
+        "answers": {
+          "type": "array",
+          "description": "Questions it serves, in people's words.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "depth": {
+          "enum": [
+            "declared",
+            "live",
+            "either"
+          ],
+          "description": "Which observation can supply its facts: declared source, a live read or snapshot, or either."
+        },
+        "lexicons": {
+          "type": "object",
+          "description": "Each lexicon the project loads: supported, or why it can't supply the capability.",
+          "additionalProperties": {
+            "oneOf": [
+              {
+                "const": "supported"
+              },
+              {
+                "type": "object",
+                "required": [
+                  "code",
+                  "message"
+                ],
+                "properties": {
+                  "code": {
+                    "enum": [
+                      "lexicon-has-no-mapping",
+                      "capability-not-derivable",
+                      "lexicon-not-loaded"
+                    ]
+                  },
+                  "message": {
+                    "type": "string"
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "notEvaluated": {
+          "type": "array",
+          "description": "What the rule leaves out. chant search prints this under every answer that uses the capability.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "uses": {
+          "type": "array",
+          "description": "The capabilities and helpers its rule refers to.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "rule": {
+          "type": "string",
+          "description": "The rule as written, one alternative per line."
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "usage-invalid"
+              ]
+            },
+            "message": {
+              "type": "string"
+            },
+            "hint": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/workspace/ci-cloud-identity.test.ts

@@ -50,4 +50,24 @@ describe("declaredCloudIdentity (#4296)", () => {
     const root = workspace({ identity: { cloud: { aws: { rules: [{ plan: "r", apply: "r" }] } } } });
     await expect(declaredCloudIdentity(root, "production")).rejects.toThrow(/plans and applies as r.*\[declaration-invalid\]/);
   });
+
+  test("rules with targets and a name read from the declaration, and a target glob list may not be empty (#4332)", async () => {
+    const root = workspace({
+      identity: {
+        cloud: {
+          aws: {
+            rules: [
+              { members: ["net"], targets: ["envs/prod/**"], name: "prod", plan: "arn:aws:iam::1:role/prod-plan", apply: "arn:aws:iam::1:role/prod-apply" },
+              { plan: "arn:aws:iam::1:role/plan", apply: "arn:aws:iam::1:role/apply" },
+            ],
+          },
+        },
+      },
+    });
+    const net = (await declaredCloudIdentity(join(root, "net"), "production", "net"))!;
+    expect(net.plan.aws).toMatchObject({ role: "arn:aws:iam::1:role/plan", targets: [{ targets: ["envs/prod/**"], role: "arn:aws:iam::1:role/prod-plan" }] });
+    expect((await declaredCloudIdentity(join(root, "app"), "production", "app"))!.plan.aws!.targets).toBeUndefined();
+    const empty = workspace({ identity: { cloud: { aws: { rules: [{ targets: [], plan: "p", apply: "a" }] } } } });
+    await expect(declaredCloudIdentity(empty, "production")).rejects.toThrow(/\[declaration-invalid\]/);
+  });
 });

package/src/workspace/ci-cloud-identity.ts

@@ -7,7 +7,7 @@
  */
 
 import { findWorkspaceRoot } from "../project-root";
-import { resolveCloudIdentity, type PipelineCloudIdentity } from "../ci-identity";
+import { resolveCloudIdentity, resolvePrEnvCloudIdentity, type CloudTradeSpec, type PipelineCloudIdentity } from "../ci-identity";
 
 /** The plan and apply identities of the pipeline for `env` and `member`, or undefined. */
 export async function declaredCloudIdentity(cwd: string, env: string, member?: string): Promise<PipelineCloudIdentity | undefined> {
@@ -21,3 +21,16 @@ export async function declaredCloudIdentity(cwd: string, env: string, member?: s
     throw Object.assign(new Error(`${err.describe()} [${err.code}]`), { code: err.code });
   }
 }
+
+/** The trade a pull request environment's jobs take for `member` (#4330, `resolvePrEnvCloudIdentity`), or undefined. */
+export async function declaredPrEnvCloudIdentity(cwd: string, member?: string): Promise<CloudTradeSpec | undefined> {
+  const found = findWorkspaceRoot(cwd);
+  if (!found) return undefined;
+  const [{ readDeclaration, WorkspaceReadError }, { workingTree }] = await Promise.all([import("./declaration"), import("./tree")]);
+  try {
+    return resolvePrEnvCloudIdentity(readDeclaration(workingTree(found.dir)).ci?.identity?.cloud, member);
+  } catch (err) {
+    if (!(err instanceof WorkspaceReadError)) throw err;
+    throw Object.assign(new Error(`${err.describe()} [${err.code}]`), { code: err.code });
+  }
+}

package/src/workspace/ci-run.test.ts

@@ -26,7 +26,7 @@ import { sshFromEd25519 } from "./trust/dsse";
 import { verifyOpRunStatement } from "./trust/op-run-statement";
 import { readRunLedger } from "../lifecycle/run-ledger";
 import { resolveRunId } from "../lifecycle/release-ledger";
-import { prLoopJobs, PR_LOOP_SETUP } from "../components/pr-pipeline";
+import { prEnvJobs, prLoopJobs, PR_LOOP_SETUP } from "../components/pr-pipeline";
 import { parseArgs } from "../cli/parse-args";
 import { ciSecretsFor, readCiSecrets } from "./ci-secrets";
 import { runEventFileName, runEventsDir } from "../run-event-store";
@@ -1039,3 +1039,76 @@ describe("the plan's steps hold no forge token (#4295)", () => {
     expect(plan!.command.endsWith(" --no-status")).toBe(true);
   });
 });
+
+/**
+ * #4330: a pull request environment's jobs run through `ci run` too. The
+ * stand-in chant keeps each action's arguments, environment, directory and
+ * commit under `.chant/pr-env`, and `up` writes a report and a record there.
+ */
+function fakeEnvChant(): string {
+  const file = join(scratchDir("chant-ci-run-env-bin-"), "chant");
+  writeFileSync(
+    file,
+    [
+      "#!/bin/sh",
+      'action="$3"',
+      "mkdir -p .chant/pr-env",
+      'printf "%s\\n" "$@" > ".chant/pr-env/$action.args"',
+      'env | sort > ".chant/pr-env/$action.env"',
+      'git rev-parse HEAD > ".chant/pr-env/$action.commit"',
+      'ls .chant/pr-env > ".chant/pr-env/$action.found"',
+      'if [ "$action" = up ]; then echo "{\\"stage\\": \\"up\\"}" > .chant/pr-env/pr-env-up.json; echo "{}" > .chant/pr-env/pr-env-record.json; fi',
+      'exit "${FAKE_EXIT:-0}"',
+      "",
+    ].join("\n"),
+  );
+  chmodSync(file, 0o755);
+  return file;
+}
+
+describe("a pull request environment's jobs (#4330)", () => {
+  test("env-up runs with no forge token, then env-post runs at the base commit with it and the report env-up handed on", async () => {
+    const { app, base, sha } = workspace();
+    const out = join(scratchDir("chant-ci-run-env-out-"), "pr-env");
+    const r = await ciRun({ image: JOB_IMAGE, cwd: app, job: "env-up", env: "pr-7", forge: "github", base, pr: 7, chant: fakeEnvChant(), hostEnv: HOST, output: out, push: false });
+    expect(r.op).toBe("pr-env-up");
+    expect(r.status).toBe("ok");
+    const upEnv = envFile(out, "up");
+    for (const name of FORGE_TOKEN_VARS) expect(upEnv[name]).toBeUndefined();
+    expect(upEnv.CHANT_ENV).toBe("pr-7");
+    expect(upEnv.PR_NUMBER).toBe("7");
+    expect(readFileSync(join(out, "up.commit"), "utf-8").trim()).toBe(sha);
+    expect(readFileSync(join(out, "up.args"), "utf-8")).not.toContain("--forge");
+
+    expect(r.post?.op).toBe("pr-env-post");
+    const postEnv = envFile(out, "post");
+    // The token reached env-post, and its copied report is redacted.
+    expect(postEnv.GITHUB_TOKEN).toBe("***");
+    expect(postEnv.HEAD_SHA).toBe(sha);
+    expect(postEnv.UP_RESULT).toBe("success");
+    expect(readFileSync(join(out, "post.commit"), "utf-8").trim()).toBe(base);
+    expect(readFileSync(join(out, "post.found"), "utf-8")).toContain("pr-env-record.json");
+  });
+
+  test("env-down runs with the token and writes its report under .chant/pr-env, and a local env-up posts nothing", async () => {
+    const { app, base } = workspace();
+    const out = join(scratchDir("chant-ci-run-env-out-"), "pr-env");
+    const down = await ciRun({ image: JOB_IMAGE, cwd: app, job: "env-down", env: "pr-7", forge: "github", base, pr: 7, chant: fakeEnvChant(), hostEnv: HOST, output: out, push: false });
+    expect(down.op).toBe("pr-env-down");
+    expect(envFile(out, "down").GITHUB_TOKEN).toBe("***");
+    expect(readFileSync(join(out, "down.args"), "utf-8")).toContain("closed");
+
+    const local = await ciRun({ image: JOB_IMAGE, cwd: app, job: "env-up", env: "pr-7", forge: "github", base, pr: 7, chant: fakeEnvChant(), hostEnv: HOST, output: join(scratchDir("chant-ci-run-env-out-"), "pr-env"), local: true });
+    expect(local.post).toBeUndefined();
+  });
+
+  test("env-post reads the head and the up job's result from flags", () => {
+    expect(() => ciRunEnvJobEnv({})).toThrow(/pass --head <sha>/);
+    expect(ciRunEnvJobEnv({ head: "h".repeat(40), upResult: "failure" })).toMatchObject({ HEAD_SHA: "h".repeat(40), UP_RESULT: "failure", PR_NUMBER: "7" });
+  });
+});
+
+function ciRunEnvJobEnv(values: { head?: string; upResult?: string }): Record<string, string> {
+  const post = prEnvJobs("github", {}, "app").find((j) => j.jobName === "env-post")!;
+  return ciJobEnv(post, { forge: "github", env: "pr-7", values: { pr: 7, base: "b".repeat(40), commit: "b".repeat(40), ...values }, hostEnv: HOST });
+}