@intentius/chant 0.91.0 → 0.94.0

package/src/op/activities/activity-contracts.ts

@@ -25,6 +25,7 @@
 
 import { z } from "zod";
 import { activityContract } from "../activity-contract";
+import { backendSchema } from "../decide-config";
 
 export const lifecycleSnapshotContract = activityContract(
   "lifecycleSnapshot",
@@ -54,8 +55,14 @@ export const shellCmdContract = activityContract(
     env: z.record(z.string(), z.string()).optional(),
     cwd: z.string().optional(),
     okExit: z.array(z.number()).optional(),
+    gatedExit: z.number().optional(),
+    gate: z.strictObject({ op: z.string(), gate: z.string() }).optional(),
+    json: z.boolean().optional(),
   }),
-  z.object({ stdout: z.string(), stderr: z.string(), exitCode: z.number() }),
+  // `json` is stdout parsed, when the step sets `json` (#2787): whatever the
+  // command printed, so its shape is the author's and only the whole value is
+  // a reference target (`sh.out.json`).
+  z.object({ stdout: z.string(), stderr: z.string(), exitCode: z.number(), json: z.unknown().optional() }),
 );
 
 export const httpCheckContract = activityContract(
@@ -166,3 +173,185 @@ export const proposeWorkspaceUpgradeContract = activityContract(
     summary: z.string(),
   }),
 );
+
+/**
+ * The forward coverage check over an Op's own diff (#2773). `args` mirrors
+ * `ChangeCoverageArgs`. `returns` names what a step reads: whether the check
+ * passed, the range and work item checked, and each finding with the
+ * `triage` a work item seeded from it takes as its `source`.
+ */
+export const changeCoverageContract = activityContract(
+  "changeCoverage",
+  z.strictObject({
+    cwd: z.string().optional(),
+    range: z.string().optional(),
+    work: z.string().optional(),
+    severity: z.enum(["off", "warn", "fail"]).optional(),
+  }),
+  z.object({
+    ok: z.boolean(),
+    range: z.object({ spec: z.string(), base: z.string(), head: z.string() }),
+    work: z.string().nullable(),
+    severity: z.enum(["off", "warn", "fail"]),
+    findings: z.array(
+      z.object({
+        code: z.enum(["change-uncovered", "change-out-of-scope"]),
+        path: z.string(),
+        message: z.string(),
+        severity: z.enum(["warn", "fail"]),
+        records: z.array(z.string()),
+        triage: z.object({ finding: z.enum(["change-uncovered", "change-out-of-scope"]), region: z.string() }),
+      }),
+    ),
+    summary: z.object({
+      paths: z.number(),
+      covered: z.number(),
+      uncovered: z.number(),
+      outOfScope: z.number(),
+      ignored: z.number(),
+      records: z.number(),
+    }),
+  }),
+);
+
+/**
+ * Evidence for an acceptance criterion, under the run's work lease (#2772).
+ * `lease` is the run's lease, a reference the builder fills in, so it is not
+ * checked here. `returns` names what a step reads: the item, the record's
+ * path, the entry appended and the criteria counted with it.
+ */
+export const workEvidenceContract = activityContract(
+  "workEvidence",
+  z.strictObject({
+    lease: z.unknown(),
+    criterion: z.string(),
+    result: z.enum(["pass", "fail"]),
+    title: z.string(),
+    url: z.string().optional(),
+    path: z.string().optional(),
+    kind: z.string().optional(),
+    cwd: z.string().optional(),
+  }),
+  z.object({
+    item: z.string(),
+    path: z.string(),
+    evidence: z.record(z.string(), z.unknown()),
+    acceptance: z.object({ met: z.number(), total: z.number(), criteria: z.array(z.object({ id: z.string(), verification: z.string(), met: z.boolean() })) }),
+  }),
+);
+
+/**
+ * The source-release activities (#2782, ./source-release.ts). A release Op
+ * reads `archive.out.digest` into its plan, `plan.out.digest` into its gate
+ * and its ship step, and `plan.out.file` into its record step.
+ */
+export const sourceArchiveContract = activityContract(
+  "sourceArchive",
+  z.strictObject({ path: z.string(), ref: z.string().optional(), out: z.string().optional(), cwd: z.string().optional() }),
+  z.object({ digest: z.string(), archive: z.string(), commit: z.string(), dir: z.string(), files: z.number(), bytes: z.number() }),
+);
+
+export const releasePlanContract = activityContract(
+  "releasePlan",
+  z.strictObject({
+    component: z.string(),
+    env: z.string(),
+    gitSha: z.string(),
+    content: z.record(z.string(), z.unknown()),
+    dir: z.string().optional(),
+    cwd: z.string().optional(),
+  }),
+  z.object({ digest: z.string(), file: z.string(), gitSha: z.string() }),
+);
+
+export const releaseRecordContract = activityContract(
+  "releaseRecord",
+  z.strictObject({
+    plan: z.string(),
+    digest: z.string().optional(),
+    approval: z.strictObject({ op: z.string(), gate: z.string() }).optional(),
+    actor: z.string().optional(),
+    runId: z.string().optional(),
+    cwd: z.string().optional(),
+  }),
+  z.object({ recorded: z.boolean(), digest: z.string(), env: z.string(), component: z.string(), approver: z.string().nullable() }),
+);
+
+/**
+ * `decide` (#2740, core's since #2828). OPS012 checks a step's args against
+ * it and OPS013 a later step's reference into its result, so a misspelled
+ * `point` or a key written as a literal string fails `chant build` rather
+ * than a run.
+ */
+const decideEscalation = z.object({ kind: z.enum(["table", "model"]), reason: z.string() }).loose();
+
+export const decideContract = activityContract(
+  "decide",
+  z.strictObject({
+    point: z.string().min(1),
+    inputs: z.record(z.string(), z.unknown()).optional(),
+    read: z.record(z.string(), z.string()).optional(),
+    subject: z.string().optional(),
+    kind: z.string().optional(),
+    cwd: z.string().optional(),
+    backends: z.record(z.string(), backendSchema).optional(),
+    dryRun: z.boolean().optional(),
+  }),
+  z.strictObject({
+    id: z.string(),
+    path: z.string(),
+    state: z.enum(["escalated", "proposed", "answered"]),
+    open: z.boolean(),
+    answer: z.union([z.string(), z.boolean(), z.null()]),
+    decider: z.string(),
+    model: z.string().nullable(),
+    backend: z.string().nullable(),
+    confidence: z.number().nullable(),
+    threshold: z.number().nullable(),
+    answeredBy: z.array(z.string()),
+    escalations: z.array(decideEscalation),
+    missing: z.array(z.string()),
+  }),
+  { entities: ["point"] },
+);
+
+/**
+ * The rollback activities for a source release (#2800, ./source-rollback.ts).
+ * A rollback Op reads `plan.out.digest` into its gate, `plan.out.to` and the
+ * archive fields into the step that restores the Machine, and
+ * `plan.out.file` into its record step.
+ */
+export const releaseRollbackPlanContract = activityContract(
+  "releaseRollbackPlan",
+  z.strictObject({
+    component: z.string(),
+    env: z.string(),
+    to: z.string().optional(),
+    path: z.string().optional(),
+    dir: z.string().optional(),
+    cwd: z.string().optional(),
+  }),
+  z.object({
+    digest: z.string(),
+    file: z.string(),
+    to: z.string(),
+    from: z.string(),
+    gitSha: z.string(),
+    archive: z.string(),
+    archiveDigest: z.string(),
+    dir: z.string(),
+  }),
+);
+
+export const releaseRollbackRecordContract = activityContract(
+  "releaseRollbackRecord",
+  z.strictObject({
+    plan: z.string(),
+    digest: z.string().optional(),
+    approval: z.strictObject({ op: z.string(), gate: z.string() }).optional(),
+    actor: z.string().optional(),
+    runId: z.string().optional(),
+    cwd: z.string().optional(),
+  }),
+  z.object({ recorded: z.boolean(), digest: z.string(), env: z.string(), component: z.string(), approver: z.string().nullable() }),
+);

package/src/op/activities/apply.ts

@@ -35,6 +35,7 @@
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
 import { normalizeApply, type ApplyResult } from "../../apply";
+import { importLexiconPackage } from "../../lexicon-module";
 
 const execAsync = promisify(exec);
 
@@ -241,7 +242,7 @@ async function loadK8sApplier(): Promise<K8sApplier> {
   const spec = "@intentius/chant-lexicon-k8s/op/activities";
   let mod: { applyManifest?: K8sApplier };
   try {
-    mod = (await import(spec)) as { applyManifest?: K8sApplier };
+    mod = (await importLexiconPackage(spec)) as { applyManifest?: K8sApplier };
   } catch (err) {
     throw new Error(
       `apply target "kubectl" needs @intentius/chant-lexicon-k8s, which could not be loaded ` +
@@ -269,7 +270,7 @@ async function loadAzureApplier(): Promise<AzureApplier> {
   };
   let mod: AzureModule;
   try {
-    mod = (await import(spec)) as AzureModule;
+    mod = (await importLexiconPackage(spec)) as AzureModule;
   } catch (err) {
     throw new Error(
       `apply target "arm" needs @intentius/chant-lexicon-azure, which could not be loaded ` +
@@ -304,7 +305,7 @@ async function loadGcpApplier(): Promise<GcpApplier> {
   };
   let mod: GcpModule;
   try {
-    mod = (await import(spec)) as GcpModule;
+    mod = (await importLexiconPackage(spec)) as GcpModule;
   } catch (err) {
     throw new Error(
       `apply target "gcp" needs @intentius/chant-lexicon-gcp, which could not be loaded ` +
@@ -339,7 +340,7 @@ async function loadFlyApplier(): Promise<FlyApplier> {
   };
   let mod: FlyModule;
   try {
-    mod = (await import(spec)) as FlyModule;
+    mod = (await importLexiconPackage(spec)) as FlyModule;
   } catch (err) {
     throw new Error(
       `apply target "fly" needs @intentius/chant-lexicon-fly, which could not be loaded ` +
@@ -370,7 +371,7 @@ async function loadAwsApplier(): Promise<AwsApplier> {
   const spec = "@intentius/chant-lexicon-aws/op/activities";
   let mod: { awsApply?: AwsApplier };
   try {
-    mod = (await import(spec)) as { awsApply?: AwsApplier };
+    mod = (await importLexiconPackage(spec)) as { awsApply?: AwsApplier };
   } catch (err) {
     throw new Error(
       `apply target "cloudformation" needs @intentius/chant-lexicon-aws, which could not be loaded ` +
@@ -395,7 +396,7 @@ async function loadAwsRollback(): Promise<AwsRollback> {
   const spec = "@intentius/chant-lexicon-aws/op/activities";
   let mod: { rollbackStack?: AwsRollback };
   try {
-    mod = (await import(spec)) as { rollbackStack?: AwsRollback };
+    mod = (await importLexiconPackage(spec)) as { rollbackStack?: AwsRollback };
   } catch (err) {
     throw new Error(
       `rollback for target "cloudformation" needs @intentius/chant-lexicon-aws, which could not be ` +

package/src/op/activities/change-coverage.ts

@@ -0,0 +1,60 @@
+/**
+ * changeCoverage — the forward coverage check (#2773) as an Op activity, for
+ * an Op that changes the checkout (#2748) to run on its own diff.
+ *
+ * Such an Op's leased steps work in a worktree of their own on
+ * `chant/work/[<member>/]<item>`. Given that worktree as `cwd`
+ * (`workLeaseOutput("worktree")`) and no `range`, the activity checks the
+ * commits the branch holds beyond the main worktree's HEAD, with the branch's
+ * item as the work item in hand, exactly as `chant workspace check --changes
+ * <base>..HEAD --work <item>` would. A `range` or `work` given replaces what
+ * the branch says.
+ *
+ * The step fails when the check's severity is `fail` and it has a finding,
+ * or when the check can't run; otherwise it returns the document's findings
+ * and summary for later steps. The workspace code loads on first call, so
+ * importing core's activities loads nothing under `workspace/` (#2525 rule 5).
+ */
+
+import type { ChangeFinding, ChangesDocument } from "../../workspace/changes";
+
+export interface ChangeCoverageArgs {
+  /** The checkout to check: the Op's worktree. Default: the working directory. */
+  cwd?: string;
+  /** `<base>..<head>`, `<base>...<head>` or `<base>`. Default: the work branch's own commits. */
+  range?: string;
+  /** The work item in hand. Default: the work branch's item. */
+  work?: string;
+  /** In place of the declaration's `changes.severity`. */
+  severity?: "off" | "warn" | "fail";
+}
+
+export interface ChangeCoverageResult {
+  ok: boolean;
+  range: { spec: string; base: string; head: string };
+  work: string | null;
+  severity: "off" | "warn" | "fail";
+  findings: Pick<ChangeFinding, "code" | "path" | "message" | "severity" | "records" | "triage">[];
+  summary: Exclude<ChangesDocument, { error: unknown }>["summary"];
+}
+
+export async function changeCoverage(args: ChangeCoverageArgs = {}): Promise<ChangeCoverageResult> {
+  const { checkChanges, workBranchChanges } = await import("../../workspace/changes");
+  const cwd = args.cwd ?? process.cwd();
+  const branch = args.range === undefined ? workBranchChanges(cwd) : undefined;
+  const range = args.range ?? branch?.range;
+  if (range === undefined) throw new Error(`changeCoverage: ${cwd} is not on a chant/work/ branch, so give the range to check`);
+  const work = args.work ?? branch?.work;
+  const { doc } = await checkChanges({ cwd, range, ...(work !== undefined ? { work } : {}), ...(args.severity ? { severity: args.severity } : {}) });
+  if ("error" in doc) throw new Error(`changeCoverage: ${doc.error.code}: ${doc.error.message}`);
+  const result: ChangeCoverageResult = {
+    ok: doc.ok,
+    range: doc.range,
+    work: doc.work?.record ?? null,
+    severity: doc.severity,
+    findings: doc.findings.map(({ code, path, message, severity, records, triage }) => ({ code, path, message, severity, records, triage })),
+    summary: doc.summary,
+  };
+  if (!doc.ok) throw new Error(`changeCoverage: ${doc.findings.length} change ${doc.findings.length === 1 ? "finding" : "findings"} at severity fail: ${doc.findings.map((f) => `${f.code} ${f.path}`).join(", ")}`);
+  return result;
+}

package/src/op/activities/converge.test.ts

@@ -1,9 +1,11 @@
 import { describe, test, expect } from "vitest";
 import { eq, gt, run, report, when } from "../converge-rule";
-import type { ConvergeSymptom } from "../../lifecycle/symptoms";
+import { parseResourceObservation, type ConvergeSymptom, type ObservedResource, type ResourceSymptom } from "../../lifecycle/symptoms";
 import type { ConvergeTickRecord, ConvergeRuleOutcome } from "../../lifecycle/converge-ledger";
 import {
   planConvergeTick,
+  planResourceTick,
+  consecutiveResourceFires,
   verbClassAllowedToDispatch,
   enforceVerbClassAtDispatch,
   sanitizeOneLine,
@@ -354,3 +356,55 @@ describe("classifyDispatchFailure", () => {
     expect(classifyDispatchFailure("")).toBeUndefined();
   });
 });
+
+describe("planResourceTick — rules evaluated once per observed resource (#2778)", () => {
+  const restart = when<ResourceSymptom>(eq("status", "drifted"), run("restart-service"), { id: "restart-drifted", why: "Restart a drifted service." });
+  const unknownR = when<ResourceSymptom>(eq("status", "unknown"), report("not observed"), { id: "report-unknown", why: "unknown never remediates." });
+  const resources: ObservedResource[] = [
+    { name: "app", status: "drifted", detail: "stopped" },
+    { name: "hud", status: "in-sync" },
+    { name: "door", status: "drifted" },
+    { name: "site", status: "unknown", detail: "no health" },
+  ];
+
+  test("a fired run() is planned for each drifted resource, and names it", () => {
+    const plan = planResourceTick("box", resources, [restart, unknownR], [], "box-converge", "apply", 3);
+    expect(plan.firedRuleIds).toEqual(["restart-drifted", "report-unknown"]);
+    expect(plan.outcomes).toEqual([
+      { ruleId: "restart-drifted", resource: "app", action: "ran", op: "restart-service" },
+      { ruleId: "restart-drifted", resource: "door", action: "ran", op: "restart-service" },
+      { ruleId: "report-unknown", resource: "site", action: "reported", reason: "not observed" },
+    ]);
+  });
+
+  test("unknown never remediates, the dial and the budget hold per tick", () => {
+    const anyStatus = when<ResourceSymptom>(eq("env", "box"), run("restart-service"), { id: "restart-all", why: "x" });
+    const plan = planResourceTick("box", [{ name: "site", status: "unknown" }], [anyStatus], [], "box-converge", "apply", 3);
+    expect(plan.outcomes[0]).toMatchObject({ action: "reported", resource: "site", reason: expect.stringMatching(/unknown never remediates/) });
+    expect(planResourceTick("box", resources, [restart], [], "box-converge", "observe", 3).outcomes.map((o) => o.action)).toEqual(["reported", "reported"]);
+    expect(planResourceTick("box", resources, [restart], [], "box-converge", "apply", 1).outcomes.map((o) => o.action)).toEqual(["ran", "skipped-budget"]);
+  });
+
+  test("flap damping counts one rule's fires for one resource, on this op's ticks", () => {
+    const fired = (resource: string, op = "box-converge") =>
+      tick({ op, firedRuleIds: ["restart-drifted"], outcomes: [{ ruleId: "restart-drifted", action: "ran", op: "restart-service", resource }] });
+    const prior = [fired("app"), fired("app"), fired("hud", "other-converge"), fired("app")];
+    expect(consecutiveResourceFires(prior, "box-converge", "restart-drifted", "app")).toBe(3);
+    expect(consecutiveResourceFires(prior, "box-converge", "restart-drifted", "door")).toBe(0);
+    const plan = planResourceTick("box", resources, [restart], prior, "box-converge", "apply", 3);
+    expect(plan.outcomes.map((o) => [o.resource, o.action])).toEqual([["app", "skipped-flap"], ["door", "ran"]]);
+  });
+});
+
+describe("parseResourceObservation (#2778)", () => {
+  test("reads an observation, or a shell result that prints one, and refuses anything else", () => {
+    const observation = { resources: [{ name: "app", status: "drifted", detail: "stopped" }] };
+    expect(parseResourceObservation(observation)).toEqual(observation);
+    expect(parseResourceObservation({ stdout: JSON.stringify(observation), stderr: "", exitCode: 0 })).toEqual(observation);
+    expect(() => parseResourceObservation({ stdout: "nope", stderr: "", exitCode: 0 })).toThrow(/not JSON/);
+    expect(() => parseResourceObservation({})).toThrow(/no `resources` array/);
+    expect(() => parseResourceObservation({ resources: [{ name: "app", status: "down" }] })).toThrow(/in-sync, drifted or unknown/);
+    expect(() => parseResourceObservation({ resources: [{ status: "drifted" }] })).toThrow(/has no name/);
+    expect(() => parseResourceObservation({ resources: [{ name: "a", status: "drifted" }, { name: "a", status: "in-sync" }] })).toThrow(/twice/);
+  });
+});