@intentius/chant 0.106.4 → 0.108.0

package/src/op/local-executor.ts

@@ -28,9 +28,12 @@ import { parseDuration } from "./duration";
 import { stepTimeoutProblem } from "./activity-profiles";
 import { describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "./gate";
 import { gateName } from "./gate-name";
+import { gatePointOf } from "./gate-point";
+import { evaluatePointGate, workspaceGatePointAsker, type GatePointAsker } from "./gate-point-run";
 import type { ResolvedGateApproval } from "./gate-approval";
+import { GATE_PLAN_CONTEXT_KEY, gatePlanSummaryOfResult } from "./gate-plan-context";
 import { withOpRunContext, type OpRunContext, type PassedGate } from "./run-context";
-import type { PendingGateRecord } from "../lifecycle/gate-ledger";
+import type { GateAnswerRef, PendingGateRecord } from "../lifecycle/gate-ledger";
 import { isPointWait, type WaitingPoint } from "./steward-points";
 import { isGateWait } from "./gate-wait";
 import { currentStewardTurn, enterStewardTurn } from "./steward-turn";
@@ -72,10 +75,12 @@ export interface StepRecord {
     resolvedBy: string;
     timestamp: string;
     url?: string;
-    /** On a gate with an `approval` block (#2508): whether a quorum or a policy permit passed it. */
-    via?: "quorum" | "policy";
+    /** On a gate with an `approval` block (#2508): whether a quorum or a policy permit passed it. `"point"` on a gate that asks a decision point (#3170). */
+    via?: "quorum" | "policy" | "point";
     /** On a gate with a quorum (#2508): every approver who counted toward it. */
     approvers?: string[];
+    /** On a gate that asks a decision point (#3170): the answer record that passed it, which the gate ledger's resolution cites too. */
+    answer?: GateAnswerRef;
   };
   /**
    * Why a step declined to proceed on something that is not a failure
@@ -489,6 +494,10 @@ interface GateContext {
   passed?: PassedGate[];
   /** The run's hold on its work item's lease (#2748). Absent in compensation phases, which run whatever the lease did. */
   work?: RunWorkLease;
+  /** How a gate that names a decision point asks it (#3170). */
+  points?: GatePointAsker;
+  /** The environment the run was started for, a point gate's `gate.env` input. */
+  env?: string;
 }
 
 /**
@@ -584,6 +593,13 @@ function resolveGateApproval(
       if (resolved !== undefined && resolved !== null) context[key] = resolved;
     }
   }
+  // #3182: a policy also sees what the plan does. When the gate's `plan`
+  // names the step that planned it and that step returned a change set, its
+  // summary lands under `context.plan` with no context code in the Op.
+  if (authored.policy && isStepOutputRef(step.plan)) {
+    const summary = gatePlanSummaryOfResult(resultsById.get(step.plan.step));
+    if (summary) context = { ...(context ?? {}), [GATE_PLAN_CONTEXT_KEY]: summary };
+  }
   return {
     ...(authored.quorum ? { quorum: authored.quorum } : {}),
     ...(authored.policy ? { policy: authored.policy } : {}),
@@ -604,6 +620,7 @@ async function runGateStep(
   gates: GateContext,
   resultsById: ReadonlyMap<string, unknown> = new Map(),
 ): Promise<{ record: StepRecord; pending?: PendingGateRecord; pushed?: boolean; pushWarning?: string }> {
+  if (step.point !== undefined) return runPointGateStep(step, phaseName, gates, resultsById);
   const start = Date.now();
   // #2300: `plan` is authored as a reference into the Plan phase's result
   // (`plan.out.planDigest`), and is resolved here through the same walk an
@@ -689,6 +706,57 @@ async function runGateStep(
   };
 }
 
+/**
+ * Decide a gate that asks a decision point (#3170, `./gate-point-run.ts`).
+ * An answer it passes on lands on the step record as the approval, citing
+ * the answer record; an open question puts the question on the record, as an
+ * activity's open point does, and the caller ends the run `waiting`; any
+ * other answer fails the step.
+ */
+async function runPointGateStep(
+  step: GateStep,
+  phaseName: string,
+  gates: GateContext,
+  resultsById: ReadonlyMap<string, unknown>,
+): Promise<{ record: StepRecord; pushed?: boolean; pushWarning?: string }> {
+  const start = Date.now();
+  const point = gatePointOf(step.point)!;
+  const base = { phase: phaseName, fn: gateFn(step), args: {} };
+  const resolvedPlan = resolveStepOutputRefs(step.plan, resultsById);
+  const planDigest = typeof resolvedPlan === "string" && resolvedPlan !== "" ? resolvedPlan : undefined;
+  const inputs = point.inputs ? (resolveStepOutputRefs(point.inputs, resultsById) as Record<string, unknown>) : undefined;
+  try {
+    const check = await evaluatePointGate(gates.port, gates.points ?? workspaceGatePointAsker(process.cwd()), {
+      op: gates.op,
+      gate: gateName(step),
+      point,
+      ...(inputs ? { inputs } : {}),
+      ...(step.description ? { description: step.description } : {}),
+      ...(step.timeout ? { timeout: step.timeout } : {}),
+      ...(gates.runId ? { runId: gates.runId } : {}),
+      ...(planDigest !== undefined ? { planDigest } : {}),
+      ...(gates.env !== undefined ? { env: gates.env } : {}),
+      ...(gates.now ? { now: gates.now } : {}),
+    });
+    if (check.satisfied) {
+      const approval: NonNullable<StepRecord["approval"]> = {
+        gate: gateName(step),
+        resolvedBy: check.resolution.resolvedBy,
+        timestamp: check.resolution.timestamp,
+        via: "point",
+        ...(check.answer.answeredBy ? { approvers: check.answer.answeredBy } : {}),
+        answer: check.answer,
+      };
+      gates.passed?.push({ gate: gateName(step), approval });
+      return { record: { ...base, status: "ok", durationMs: Date.now() - start, approval }, pushed: check.pushed, ...(check.pushWarning ? { pushWarning: check.pushWarning } : {}) };
+    }
+    if ("refused" in check) return { record: { ...base, status: "fail", durationMs: Date.now() - start, error: check.refused } };
+    return { record: { ...base, status: "skipped", durationMs: Date.now() - start, point: check.waiting }, pushed: check.pushed, ...(check.pushWarning ? { pushWarning: check.pushWarning } : {}) };
+  } catch (err) {
+    return { record: { ...base, status: "fail", durationMs: Date.now() - start, error: errMessage(err) } };
+  }
+}
+
 /**
  * Run one effect step: read-compare-run-write. On a match the nested steps are
  * recorded as skipped ("effect already applied") and nothing is written. On a
@@ -778,6 +846,11 @@ async function runEffectStep(
         skipRest(i + 1);
         return { records, failed: false, pending, pushed, ...(pushWarning ? { pushWarning } : {}) };
       }
+      if (record.point) {
+        // A gate's open decision point (#3170): as for an activity's.
+        skipRest(i + 1);
+        return { records, failed: false, point: record.point };
+      }
       continue;
     }
     const ran = await runStep(nested, phaseName, activities, profiles, resultsById, signal);
@@ -866,6 +939,13 @@ async function runPhase(
         }
         throw new GateStop(gateRecords, pending, phase.name, pushed, pushWarning);
       }
+      if (record.point) {
+        // A gate's open decision point (#3170): nothing fans out.
+        for (const skipped of phase.steps.filter(isActivity)) {
+          pushRecord(gateRecords, gates, skippedRecord(phase.name, skipped.fn, skipped.args));
+        }
+        throw new PointStop(gateRecords, record.point, phase.name);
+      }
     }
     const steps = phase.steps.filter(isActivity);
     const settled = await Promise.all(steps.map((s) => runStep(s, phase.name, activities, profiles, resultsById, signal)));
@@ -921,6 +1001,12 @@ async function runPhase(
         skipRemaining(i + 1);
         throw new GateStop(records, pending, phase.name, pushed, pushWarning);
       }
+      if (record.point) {
+        // A gate that asks a decision point (#3170) and found it open: the
+        // run waits on the question, as at an activity's open point.
+        skipRemaining(i + 1);
+        throw new PointStop(records, record.point, phase.name);
+      }
       continue;
     }
     if (isEffect(step)) {
@@ -980,6 +1066,11 @@ export interface RunOpOptions {
   now?: string;
   /** Identifies this run on any pending fact it records. */
   runId?: string;
+  /**
+   * How a gate that names a decision point asks it (#3170). Defaults to the
+   * workspace holding `cwd` (`workspaceGatePointAsker`); a test passes a stub.
+   */
+  points?: GatePointAsker;
   /**
    * The environment the run was started for (`--env`, #2522). The executor
    * only hands it to activities through the run context (`./run-context.ts`).
@@ -1102,6 +1193,8 @@ async function runOpInTurn(
     runId,
     ...(options.onRecord ? { onRecord: options.onRecord } : {}),
     passed: run.passedGates,
+    points: options.points ?? workspaceGatePointAsker(options.cwd ?? process.cwd()),
+    ...(options.env !== undefined ? { env: options.env } : {}),
   };
 
   // Effect steps are ordered (read-compare-run-write): refuse them in a

package/src/op/op-ir.ts

@@ -149,6 +149,8 @@ export interface OpIRGateStep {
   plan?: GateStep["plan"];
   /** Quorum, roles and policy (#2508), carried as authored. Absent on a gate that passes on one approval. */
   approval?: GateStep["approval"];
+  /** The decision point the gate asks (#3170), carried as authored. Absent on a gate that `chant approve` passes. */
+  point?: GateStep["point"];
 }
 
 export interface OpIREffectStep {
@@ -258,6 +260,7 @@ function irGateStep(step: GateStep): OpIRGateStep {
     ...(step.description ? { description: step.description } : {}),
     ...(step.plan !== undefined ? { plan: step.plan } : {}),
     ...(step.approval !== undefined ? { approval: step.approval } : {}),
+    ...(step.point !== undefined ? { point: step.point } : {}),
   };
 }
 
@@ -412,6 +415,7 @@ function opStepFromIR(step: OpIRStep): StepDefinition {
       ...(step.description ? { description: step.description } : {}),
       ...(step.plan !== undefined ? { plan: step.plan } : {}),
       ...(step.approval !== undefined ? { approval: step.approval } : {}),
+      ...(step.point !== undefined ? { point: step.point } : {}),
     };
   }
   return {

package/src/op/types.ts

@@ -9,6 +9,7 @@ import type { EffectReceiptRef } from "./receipt-store";
 import type { ActivityProfileName } from "./activity-profiles";
 import type { StepOutputRef } from "./step-output-ref";
 import type { GateApproval } from "./gate-approval";
+import type { GatePoint } from "./gate-point";
 
 export interface OpConfig {
   /** Kebab-case identifier. Names the Op's output directory (`dist/ops/<name>/`), and is the name `chant run <name>` and another Op's `depends` refer to. */
@@ -276,6 +277,16 @@ export interface GateStepBase {
    * `./gate-approval.ts`.
    */
   approval?: GateApproval;
+  /**
+   * A declared decision point this gate asks (#3170), by name or as a
+   * {@link GatePoint}. Reaching the gate asks the point: its deciders and
+   * quorum decide, the answer is an answer record, and `chant workspace
+   * points answer` answers an open question. The run passes the gate on an
+   * answer in `pass`, and the resolution it writes cites the record. A gate
+   * with a point takes no `approval`: the point's quorum is the gate's. See
+   * `./gate-point.ts`.
+   */
+  point?: string | GatePoint;
 }
 
 /**

package/src/project-codegen.test.ts

@@ -0,0 +1,208 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  checkProjectCodegen,
+  generateProjectCode,
+  GENERATED_TS_HEADER,
+  prepareProjectCodegen,
+  readStamp,
+  resolveCodegenRoot,
+  STAMP_FILE,
+  type ProjectCodegen,
+  type ProjectCodegenPlugin,
+} from "./project-codegen";
+import { collectBuildRootContributors } from "./cli/plugins";
+import { mergeBuildRootEntities } from "./build";
+import { GENERATED_MARKER } from "./discovery/files";
+import { runGenerate } from "./cli/handlers/generate";
+import type { LexiconPlugin } from "./lexicon";
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+function project(): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-project-codegen-"));
+  dirs.push(dir);
+  return dir;
+}
+
+/**
+ * A lexicon whose declared input is one local file, `widgets.txt`, named by
+ * `config.fake.source`. Each line becomes a generated file.
+ */
+function fakePlugin(onLoad?: () => void): ProjectCodegenPlugin {
+  const codegen: ProjectCodegen = {
+    inputs(ctx) {
+      const source = (ctx.config.fake as { source?: string } | undefined)?.source;
+      if (!source) return undefined;
+      return { source, content: readFileSync(join(ctx.projectRoot, source), "utf8") };
+    },
+    async generate(ctx) {
+      const source = (ctx.config.fake as { source: string }).source;
+      const names = readFileSync(join(ctx.projectRoot, source), "utf8").split("\n").filter(Boolean);
+      const files: Record<string, string> = { "index.ts": `${GENERATED_TS_HEADER}\nexport const names = ${JSON.stringify(names)};\n` };
+      for (const n of names) files[`parts/${n}.ts`] = `export const ${n} = 1;\n`;
+      return { files, summary: names };
+    },
+    load: onLoad,
+  };
+  return { name: "fake", projectCodegen: () => codegen };
+}
+
+describe("project codegen", () => {
+  test("the generated header carries discovery's generated-file marker", () => {
+    expect(GENERATED_TS_HEADER).toContain(GENERATED_MARKER);
+  });
+
+  test("outDir defaults to src/generated and follows codegen.outDir", () => {
+    expect(resolveCodegenRoot("/p", {})).toBe("/p/src/generated");
+    expect(resolveCodegenRoot("/p", { codegen: { outDir: "gen" } })).toBe("/p/gen");
+  });
+
+  test("generate writes the files and a stamp; the check is then current", async () => {
+    const root = project();
+    writeFileSync(join(root, "widgets.txt"), "a\nb\n");
+    const config = { fake: { source: "widgets.txt" } };
+    const plugin = fakePlugin();
+
+    const result = await generateProjectCode(plugin, root, config);
+    expect(result?.status).toBe("written");
+    expect(result?.files).toEqual(["index.ts", "parts/a.ts", "parts/b.ts"]);
+    const outDir = join(root, "src/generated/fake");
+    expect(readFileSync(join(outDir, "index.ts"), "utf8")).toContain('["a","b"]');
+    expect(readStamp(outDir)?.inputs).toMatch(/^sha256:[0-9a-f]{64}$/);
+
+    expect(await checkProjectCodegen(plugin, root, config)).toEqual({ status: "current" });
+  });
+
+  test("editing a declared source without regenerating is drift", async () => {
+    const root = project();
+    writeFileSync(join(root, "widgets.txt"), "a\n");
+    const config = { fake: { source: "widgets.txt" } };
+    const plugin = fakePlugin();
+    await generateProjectCode(plugin, root, config);
+
+    writeFileSync(join(root, "widgets.txt"), "a\nc\n");
+    const check = await checkProjectCodegen(plugin, root, config);
+    expect(check.status).toBe("drift");
+    expect("message" in check && check.message).toMatch(/src\/generated\/fake is out of date.*Run `chant generate`/);
+  });
+
+  test("declared sources with no output, or a recorded file deleted, is missing", async () => {
+    const root = project();
+    writeFileSync(join(root, "widgets.txt"), "a\n");
+    const config = { fake: { source: "widgets.txt" } };
+    const plugin = fakePlugin();
+    expect((await checkProjectCodegen(plugin, root, config)).status).toBe("missing");
+
+    await generateProjectCode(plugin, root, config);
+    rmSync(join(root, "src/generated/fake/parts/a.ts"));
+    const check = await checkProjectCodegen(plugin, root, config);
+    expect(check.status).toBe("missing");
+    expect("message" in check && check.message).toContain("parts/a.ts");
+  });
+
+  test("regenerating deletes files the previous run wrote and this one did not", async () => {
+    const root = project();
+    writeFileSync(join(root, "widgets.txt"), "a\nb\n");
+    const config = { fake: { source: "widgets.txt" } };
+    const plugin = fakePlugin();
+    await generateProjectCode(plugin, root, config);
+    writeFileSync(join(root, "src/generated/fake/hand-written.ts"), "// mine\n");
+
+    writeFileSync(join(root, "widgets.txt"), "a\n");
+    await generateProjectCode(plugin, root, config);
+    expect(existsSync(join(root, "src/generated/fake/parts/b.ts"))).toBe(false);
+    expect(existsSync(join(root, "src/generated/fake/parts/a.ts"))).toBe(true);
+    // Only files a run recorded are ever removed.
+    expect(existsSync(join(root, "src/generated/fake/hand-written.ts"))).toBe(true);
+  });
+
+  test("with nothing declared, leftover output is an orphan and generate removes it", async () => {
+    const root = project();
+    writeFileSync(join(root, "widgets.txt"), "a\n");
+    const plugin = fakePlugin();
+    await generateProjectCode(plugin, root, { fake: { source: "widgets.txt" } });
+
+    expect((await checkProjectCodegen(plugin, root, {})).status).toBe("orphan");
+    const result = await generateProjectCode(plugin, root, {});
+    expect(result?.status).toBe("removed");
+    expect(existsSync(join(root, "src/generated/fake"))).toBe(false);
+    expect(await checkProjectCodegen(plugin, root, {})).toEqual({ status: "none" });
+  });
+
+  test("prepare loads current output and throws on drift", async () => {
+    const root = project();
+    writeFileSync(join(root, "widgets.txt"), "a\n");
+    const config = { fake: { source: "widgets.txt" } };
+    const load = vi.fn();
+    const plugin = fakePlugin(load);
+    await generateProjectCode(plugin, root, config);
+
+    await prepareProjectCodegen(plugin, root, config);
+    expect(load).toHaveBeenCalledTimes(1);
+
+    writeFileSync(join(root, "widgets.txt"), "b\n");
+    await expect(prepareProjectCodegen(plugin, root, config)).rejects.toThrow(/out of date/);
+    expect(load).toHaveBeenCalledTimes(1);
+  });
+
+  test("the build-root contributors carry the check, so a drifted build reports an error", async () => {
+    const root = project();
+    writeFileSync(join(root, "widgets.txt"), "a\n");
+    const config = { fake: { source: "widgets.txt" } };
+    const plugin = fakePlugin() as unknown as LexiconPlugin;
+    await generateProjectCode(plugin, root, config);
+
+    const current = await mergeBuildRootEntities(new Map(), collectBuildRootContributors([plugin], config, root));
+    expect(current.errors).toEqual([]);
+
+    writeFileSync(join(root, "widgets.txt"), "b\n");
+    const drifted = await mergeBuildRootEntities(new Map(), collectBuildRootContributors([plugin], config, root));
+    expect(drifted.errors).toHaveLength(1);
+    expect(drifted.errors[0]).toMatch(/out of date/);
+  });
+});
+
+describe("chant generate", () => {
+  function args(path: string, extra: Record<string, unknown> = {}) {
+    return { command: "generate", path, ...extra } as never;
+  }
+
+  test("writes each lexicon's code, and --check reports drift with exit 1", async () => {
+    const root = project();
+    writeFileSync(join(root, "chant.config.json"), JSON.stringify({ fake: { source: "widgets.txt" } }));
+    writeFileSync(join(root, "widgets.txt"), "a\n");
+    const plugins = [fakePlugin() as unknown as LexiconPlugin];
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const err = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      expect(await runGenerate({ args: args(root), plugins, serializers: [] })).toBe(0);
+      expect(existsSync(join(root, "src/generated/fake", STAMP_FILE))).toBe(true);
+      expect(await runGenerate({ args: args(root, { check: true }), plugins, serializers: [] })).toBe(0);
+
+      writeFileSync(join(root, "widgets.txt"), "z\n");
+      expect(await runGenerate({ args: args(root, { check: true }), plugins, serializers: [] })).toBe(1);
+      expect(err.mock.calls.flat().join("\n")).toMatch(/out of date/);
+    } finally {
+      log.mockRestore();
+      err.mockRestore();
+    }
+  });
+
+  test("--lexicon naming a lexicon with no project codegen fails", async () => {
+    const root = project();
+    writeFileSync(join(root, "chant.config.json"), "{}");
+    const err = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const code = await runGenerate({ args: args(root, { lexicon: "aws" }), plugins: [fakePlugin() as unknown as LexiconPlugin], serializers: [] });
+      expect(code).toBe(1);
+    } finally {
+      err.mockRestore();
+    }
+  });
+});