@intentius/chant 0.58.0 → 0.59.0

package/src/graph-ops.test.ts

@@ -54,7 +54,7 @@ describe("mergeProjectOps (#1675)", () => {
     expect(node?.attrs.name).toBe("deploy");
     expect(node?.attrs.depends).toEqual(["inner"]);
     expect(node?.attrs.phases).toEqual([
-      { name: "Apply", steps: [{ kind: "activity", fn: "build" }, { kind: "gate", signalName: "approve" }] },
+      { name: "Apply", steps: [{ kind: "activity", fn: "build" }, { kind: "gate", gate: "approve" }] },
     ]);
     // The sourceDir op discovery already loaded is untouched, not duplicated.
     expect(ir.nodes.filter((n) => n.kind === "Chant::Op")).toHaveLength(2);

package/src/lexicon.ts

@@ -492,9 +492,14 @@ export interface ComponentPipelineResult {
  * into the Op's own activity args at build time and is never re-passed on the
  * generated CI invocation; here it decides only what token/permission wiring
  * the generated job needs to act on a finding — elevated write access for
- * `issue`/`pull-request`/`merge-request`, none for `report`.
+ * `issue`/`comment`/`pull-request`/`merge-request`, none for `report`.
+ *
+ * `comment` posts the finding on the pull request that triggered the run
+ * (#2231), so unlike every other mode it constrains the trigger: the github
+ * generator refuses it by name on anything but `pull_request`, and the gitlab
+ * and forgejo generators refuse it outright.
  */
-export type OpFindingMode = "report" | "issue" | "pull-request" | "merge-request";
+export type OpFindingMode = "report" | "issue" | "comment" | "pull-request" | "merge-request";
 
 /**
  * The CI-native trigger driving a scheduled Op's generated workflow. `cron`
@@ -509,6 +514,43 @@ export type OpTrigger =
   | { kind: "pull_request"; branches?: string[] }
   | { kind: "push"; branches?: string[] };
 
+/**
+ * One step a generated Op job runs between the checkout and the
+ * `beforeScript` lines (#2242). Two shapes, matching what a GitHub Actions
+ * step can be: a marketplace action (`uses`, with its `with:` inputs and
+ * `env:`), or a shell line (`run`). The `uses` shape is the reason this
+ * exists at all: `beforeScript` covers everything a shell line can install,
+ * but an action like `aws-actions/configure-aws-credentials` is not a shell
+ * line, and OIDC has no shell equivalent.
+ *
+ * A CI provider with no action concept degrades by name rather than
+ * silently: the gitlab generator refuses a `uses` entry at build time and
+ * emits a `run` entry as an ordinary script line.
+ */
+export type OpSetupStep = OpSetupUsesStep | OpSetupRunStep;
+
+/** A marketplace-action setup step (`uses:` with its inputs). */
+export interface OpSetupUsesStep {
+  /**
+   * `owner/repo[/subpath]@ref`. The ref is required and must not be the
+   * action repository's own default branch — see the github generator's
+   * `assertSetupSteps`, which refuses both at build time.
+   */
+  uses: string;
+  /** The action's inputs, emitted as the step's `with:` mapping. */
+  with?: Record<string, string | number | boolean>;
+  /** Environment for this step alone, emitted as the step's `env:` mapping. */
+  env?: Record<string, string>;
+}
+
+/** A shell setup step, the same shape a `beforeScript` line emits as. */
+export interface OpSetupRunStep {
+  /** The shell line, emitted as the step's `run:`. */
+  run: string;
+  /** Environment for this step alone, emitted as the step's `env:` mapping. */
+  env?: Record<string, string>;
+}
+
 /** One scheduled Op to generate CI for — the cron-triggered counterpart to a component (generate mode). */
 export interface ScheduledOpSpec {
   /** Op name (`*.op.ts`'s `Op({ name })`) — what `chant run <name>` targets. */
@@ -535,6 +577,23 @@ export interface ScheduledOpSpec {
   opSchedule?: OpSchedule;
   /** This Op's finding-mode, for permission/token wiring only (see {@link OpFindingMode}). Default: "report" — no elevated permissions. */
   findingMode?: OpFindingMode;
+  /**
+   * Steps this Op's generated job runs between the checkout and the
+   * `beforeScript` lines (#2242), in the order given. Per-Op rather than a
+   * `ComponentPipelineOptions` knob because the setup an Op needs is a
+   * property of that Op: a plan job assumes a read-only role, an apply job
+   * assumes the one that can write.
+   */
+  setup?: OpSetupStep[];
+  /**
+   * Scopes added to the ones this Op's finding-mode already grants (#2242).
+   * Strictly additive: the generator refuses a scope the mode's own set
+   * already names, at any value, so this can neither downgrade nor restate
+   * least privilege, and it refuses `write-all`/`read-all` outright. The
+   * motivating value is `{ "id-token": "write" }`, which no finding-mode
+   * grants and OIDC cannot work without.
+   */
+  permissions?: Record<string, "read" | "write">;
 }
 
 /**
@@ -663,6 +722,29 @@ export type BuildRootContributor = (
   ctx: Pick<BuildRootContext, "entities">,
 ) => Promise<BuildRootContribution>;
 
+/**
+ * Where the content handed to `auditEntities` came from (#2217).
+ *
+ * The hook's first argument is the text audit discovery classified for a
+ * lexicon. For most lexicons that is the whole unit of parsing. For terraform
+ * it is not: a root module's `module` blocks name sibling directories, and a
+ * rule about what a CHILD module may contain cannot be answered from one
+ * directory's text. So the discovery facts a lexicon may need to read further
+ * travel with the content.
+ *
+ * `dir` and `baseDir` are set only when discovery walked a local filesystem.
+ * A remote tree fetch leaves both undefined, and a lexicon that finds them
+ * undefined parses the content it was given and nothing else.
+ */
+export interface AuditEntitiesInput {
+  /** The input's path as discovery recorded it, relative to the audited root. `"."` for the root itself. */
+  path: string;
+  /** Absolute path of the directory this input's files were read from. */
+  dir?: string;
+  /** Absolute path of the audited root: the boundary a lexicon may read within. */
+  baseDir?: string;
+}
+
 export interface LexiconPlugin {
   // ── Required ──────────────────────────────────────────────
   /** Human-readable name (e.g. "aws", "gcp") */
@@ -791,8 +873,17 @@ export interface LexiconPlugin {
    * return a `Promise` for a lexicon whose parser is inherently async (e.g.
    * terraform's HCL parser, a lazy-loaded wasm module). `auditLexicon` awaits
    * it before reading `ctx.entities`.
+   *
+   * `input` says where the content came from (#2217). It is optional so a
+   * caller can still parse a bare string, and a lexicon that only needs the
+   * text ignores it. A lexicon whose unit of parsing is a directory rather
+   * than a file (terraform: a root module and the local modules it calls)
+   * reads `dir` to descend, and stays inside `baseDir` while doing it.
    */
-  auditEntities?(content: string): Map<string, Declarable> | Promise<Map<string, Declarable>>;
+  auditEntities?(
+    content: string,
+    input?: AuditEntitiesInput,
+  ): Map<string, Declarable> | Promise<Map<string, Declarable>>;
 
   /**
    * Machine-readable spec-coverage accounting for `check-lexicon` (#1330).
@@ -1146,6 +1237,39 @@ export interface LexiconPlugin {
     region?: string;
   }): Promise<Record<string, ResourceMetadata>>;
 
+  /**
+   * Subscribe to this substrate's own change notifications (#1981), so an
+   * operator tick can run when something moved instead of only when the timer
+   * came round. Optional, and consumed by exactly one caller: `chant
+   * operator`'s loop (`./op/operator.ts`). A lexicon that does not implement
+   * it behaves exactly as it did: the loop keeps its timer and never asks.
+   *
+   * Three rules make the seam honest, and the types are shaped to enforce the
+   * first one rather than describe it.
+   *
+   * - **The signal is a trigger, never a fact.** {@link
+   *   SubscribeChangesOptions.onChange} takes no arguments and returns
+   *   nothing, so there is no channel through which a watch event could reach
+   *   a change set, a snapshot row or a diff line. The tick that follows an
+   *   early wake re-observes and re-derives from scratch, exactly as a
+   *   timer-driven tick does; waking early changes *when* a tick runs and
+   *   nothing about what it concludes.
+   * - **A dropped subscription degrades to the timer and says so.** Report it
+   *   through {@link SubscribeChangesOptions.onError} and stop; the operator
+   *   logs one line and re-subscribes on its next round. Losing the stream
+   *   slows detection back to the interval. It must never stop the loop, and
+   *   must never read as a clean estate.
+   * - **The timer stays.** A signal shortens the sleep, it does not replace
+   *   it, so a substrate that silently stops sending still converges on the
+   *   interval.
+   *
+   * Only implement it where the substrate has a change stream that needs
+   * nothing deployed into the account being observed. See the per-lexicon
+   * verdict table in the operator guide for where that holds and where it does
+   * not.
+   */
+  subscribeChanges?(options: SubscribeChangesOptions): Promise<ChangeSubscription>;
+
   /**
    * Read the full live *property tree* for each declared entity (#1014). Opt-in,
    * and strictly deeper than {@link describeResources}, which reports existence
@@ -1568,6 +1692,56 @@ export interface DependencyObservation {
   edges?: IREdge[];
 }
 
+/**
+ * What {@link LexiconPlugin.subscribeChanges} is handed (#1981).
+ *
+ * `onChange` is the whole payload channel, and it has no payload. That is the
+ * point: a substrate's change notification is a reason to look again, never
+ * evidence of what is there. An implementation that wanted to pass the watch
+ * event through would have nowhere to put it.
+ */
+export interface SubscribeChangesOptions {
+  /** chant environment being watched. Resolves the same binding a read does. */
+  environment: string;
+  /** Directory whose `chant.config.ts` carries the binding. Defaults to cwd. */
+  cwd?: string;
+  /**
+   * Declared entities for this lexicon, keyed by chant entity name. The same
+   * map {@link LexiconPlugin.describeResources} receives, and the bound on
+   * what a subscription may watch. An implementation scopes its streams to the
+   * kinds and namespaces these entities name; it must never subscribe to the
+   * whole substrate. Absent, or empty, means there is nothing in scope to
+   * watch and the implementation should say so through {@link onError} rather
+   * than widening.
+   */
+  entities?: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  /**
+   * Something moved. No arguments, deliberately (see {@link
+   * LexiconPlugin.subscribeChanges}). The caller re-observes from scratch and
+   * nothing about the notification reaches what it reports.
+   */
+  onChange(): void;
+  /**
+   * The subscription died, or could not be established for part of its scope.
+   * Reported once per occurrence; the caller logs it and falls back to its
+   * timer. Never a throw once the subscription is live: a stream that ends is
+   * a degradation, not a crash.
+   */
+  onError?(message: string): void;
+  /** Aborts the subscription. Closing on abort is the implementation's job. */
+  signal: AbortSignal;
+}
+
+/**
+ * A live subscription handed back by {@link LexiconPlugin.subscribeChanges}
+ * (#1981). `close()` releases every stream the subscription holds and resolves
+ * once they are gone; it must be safe to call twice, and safe to call after
+ * the subscription has already died on its own.
+ */
+export interface ChangeSubscription {
+  close(): Promise<void>;
+}
+
 export interface ResourceMetadata {
   /** Entity type (e.g. AWS::S3::Bucket, K8s::Apps::Deployment) */
   type: string;

package/src/lifecycle/gate-ledger.ts

@@ -142,7 +142,7 @@ export interface PendingGateRecord {
   kind: "pending";
   /** The op (or, on the component driver, the component) the gate belongs to. */
   op: string;
-  /** The gate's signal name (matches `GateStep.signalName`). */
+  /** The gate's name (matches `GateStep.gate`). */
   gate: string;
   /** The gate's human-readable description, when it declared one — what `chant operator status` shows a reader who wasn't there for the run. */
   description?: string;
@@ -173,6 +173,17 @@ function filename(op: string): string {
   return `${op}.jsonl`;
 }
 
+/**
+ * Where an Op's gate ledger lives, as a path a human can go and read:
+ * `_gates/<op>.jsonl` on the `chant/lifecycle` orphan branch. Exported so a
+ * renderer that tells someone a gate is pending can name the file the pending
+ * fact was appended to (#2243) rather than describing it in prose that drifts
+ * from `DIR`.
+ */
+export function gateLedgerPath(op: string): string {
+  return `${DIR}/${filename(op)}`;
+}
+
 /** Append one immutable gate-resolution record. Does not push to the remote — call `pushLifecycle` (./git.ts) afterward, same two-step shape every other ledger write here uses. Retries on `RefCASConflictError` the same way `appendConvergeRecord` does (./converge-ledger.ts) — a concurrent writer to a different op's/env's file on the same orphan branch is the ordinary case, not an edge case. The baseline read must be `readPathSha` + `readBlobBySha` rather than `readBlobFromPath`, so the exact sha `existing` came from can be passed as `expectPriorPathSha` — see `writeBlobToPath` (./git.ts) for the race that closes. */
 export async function appendGateResolution(
   input: GateResolutionInput,

package/src/lint/pipeline-change-gate.test.ts

@@ -44,7 +44,7 @@ describe("classifyComponentPipelineChange (#1569)", () => {
 
   test("gate steps are never mistaken for an escape hatch", () => {
     const withGate = component([
-      { phase: "Approve", steps: [{ kind: "gate", signalName: "release-approved" }] },
+      { phase: "Approve", steps: [{ kind: "gate", gate: "release-approved" }] },
     ]);
     expect(classifyComponentPipelineChange(withGate, { knownKinds: KNOWN })).toEqual({
       pipelineChange: false,
@@ -78,7 +78,7 @@ describe("componentVerbSet (#1569)", () => {
     const c = component([
       {
         phase: "Deploy",
-        steps: [{ kind: "cfn-deploy" }, { kind: "gate", signalName: "go" }, { kind: "wait-for-stack" }],
+        steps: [{ kind: "cfn-deploy" }, { kind: "gate", gate: "go" }, { kind: "wait-for-stack" }],
       },
     ]);
     expect(componentVerbSet(c)).toEqual(new Set(["cfn-deploy", "wait-for-stack"]));

package/src/lint/rules/comp/comp.test.ts

@@ -267,6 +267,32 @@ describe("COMP004: gate-needs-durable-runtime", () => {
     const hits = diagnostics.filter((d) => d.checkId === "COMP004" && d.component === "neo4j-cluster");
     expect(hits).toHaveLength(1);
   });
+
+  // #2202: the message names the gate whichever key carries the name, so the
+  // "chant approve <component> <gate>" line it prints stays copy-pasteable.
+  it("names a gate still using the deprecated `signalName` key", () => {
+    const [comp004] = checks.filter((c) => c.id === "COMP004");
+    const ctx = {
+      rollbackPolicies: FIXTURE_ROLLBACK_POLICIES,
+      components: new Map([
+        [
+          "svc",
+          {
+            component: {
+              name: "svc",
+              dependsOn: [],
+              deploy: [{ phase: "Approve", steps: [{ kind: "gate", signalName: "release-approval" }] }],
+            },
+            filePath: "svc.component.ts",
+          },
+        ],
+      ]),
+    };
+    const diagnostics = comp004.check(ctx as never);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].message).toContain('gate "release-approval"');
+    expect(diagnostics[0].message).toContain("chant approve svc release-approval");
+  });
 });
 
 describe("COMP005: capability-kind-is-noun", () => {

package/src/lint/rules/comp/comp004-gate-needs-durable-runtime.ts

@@ -41,6 +41,7 @@
  */
 
 import type { ComponentCheck, ComponentCheckContext, ComponentCheckDiagnostic } from "../../component-checks";
+import { gateName } from "../../../op/gate-name";
 import { walkComponent } from "./support";
 
 export const comp004GateNeedsDurableRuntimeRule: ComponentCheck = {
@@ -54,15 +55,16 @@ export const comp004GateNeedsDurableRuntimeRule: ComponentCheck = {
     for (const [name, { component, filePath }] of ctx.components) {
       const { gates } = walkComponent(component);
       for (const { gate, phaseName } of gates) {
+        const label = gateName(gate);
         diagnostics.push({
           checkId: "COMP004",
           severity: "error",
           component: name,
           file: filePath,
           message:
-            `Component "${name}": gate "${gate.signalName}" (phase "${phaseName}") ends the run pending approval — ` +
+            `Component "${name}": gate "${label}" (phase "${phaseName}") ends the run pending approval — ` +
             `a run that reaches it records the gate as a fact and stops there until someone runs ` +
-            `"chant approve ${name} ${gate.signalName}", and no later phase runs. If that wait is intended, ` +
+            `"chant approve ${name} ${label}", and no later phase runs. If that wait is intended, ` +
             `suppress with a file-level "// chant-disable COMP004 -- <reason>" comment anywhere in this file to ` +
             `document who approves it and why.`,
         });

package/src/lint/rules/op/ops014-converge-rule-refusals.test.ts

@@ -72,7 +72,7 @@ function destructiveOpEntity(name: string, opts?: { gated?: boolean }) {
   ];
   const phases = opts?.gated
     ? [
-        { name: "Approve", steps: [{ kind: "gate", signalName: "approve-x" }] },
+        { name: "Approve", steps: [{ kind: "gate", gate: "approve-x" }] },
         { name: "Apply", steps },
       ]
     : [{ name: "Apply", steps }];

package/src/op/activities/index.ts

@@ -43,8 +43,8 @@ export type { EnvTeardownArgs, EnvTeardownResult, EnvTeardownDeps } from "./env-
 // the registry imports this module statically, so a project that installs
 // nothing but chant still resolves every step below.
 
-export { reconcilePr } from "./reconcile";
-export type { ReconcilePrArgs, ReconcileResult, ReconcileMode, ReconcileEntry } from "./reconcile";
+export { reconcilePr, commentMarker, pullRequestContextFrom, resolvePullRequestContext } from "./reconcile";
+export type { ReconcilePrArgs, ReconcileResult, ReconcileMode, ReconcileEntry, PullRequestContext } from "./reconcile";
 
 export { nativeApply, compensateApply, hasNativeRollback } from "./apply";
 export type {

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

@@ -1,5 +1,12 @@
-import { describe, test, expect } from "vitest";
-import { reconcilePr, reconcileSummary, reconcileBranchName, entriesFromPlan } from "./reconcile";
+import { describe, test, expect, vi } from "vitest";
+import {
+  reconcilePr,
+  reconcileSummary,
+  reconcileBranchName,
+  entriesFromPlan,
+  commentMarker,
+  pullRequestContextFrom,
+} from "./reconcile";
 
 const entries = [
   { name: "bucket", action: "adopt", type: "AWS::S3::Bucket" },
@@ -79,3 +86,76 @@ describe("reconcilePr pre-built body (#2087)", () => {
     expect(result.entries).toEqual(entries);
   });
 });
+
+describe("reconcilePr comment mode: the marker (#2231)", () => {
+  test("the marker is deterministic per env, so a re-run finds its own comment", () => {
+    expect(commentMarker("app")).toBe("<!-- chant-reconcile:app -->");
+    expect(commentMarker("app")).toBe(commentMarker("app"));
+    expect(commentMarker("app")).not.toBe(commentMarker("db"));
+  });
+
+  test("the marker slugifies the env, so nothing it is interpolated next to can be escaped out of", () => {
+    // The marker is interpolated into a jq `startswith("…")` string and into a
+    // shell word. A quote or a backslash surviving into it would break both.
+    const marker = commentMarker('us-east/1" or true; #');
+    expect(marker).toBe("<!-- chant-reconcile:us-east-1-or-true- -->");
+    expect(marker).not.toMatch(/["'\\]/);
+  });
+});
+
+describe("pullRequestContextFrom (#2231)", () => {
+  const repo = "INTENTIUS/chant";
+
+  test("reads the number off a pull_request event payload", () => {
+    expect(pullRequestContextFrom({ GITHUB_REPOSITORY: repo }, { number: 2231 })).toEqual({
+      repo,
+      number: 2231,
+    });
+  });
+
+  test("accepts the nested pull_request.number the same payload also carries", () => {
+    expect(
+      pullRequestContextFrom({ GITHUB_REPOSITORY: repo }, { pull_request: { number: 7 } }),
+    ).toEqual({ repo, number: 7 });
+  });
+
+  test("falls back to GITHUB_REF when the payload is unreadable", () => {
+    expect(
+      pullRequestContextFrom({ GITHUB_REPOSITORY: repo, GITHUB_REF: "refs/pull/42/merge" }),
+    ).toEqual({ repo, number: 42 });
+  });
+
+  test("a push run has no pull request", () => {
+    expect(
+      pullRequestContextFrom(
+        { GITHUB_REPOSITORY: repo, GITHUB_REF: "refs/heads/main" },
+        { ref: "refs/heads/main", after: "abc" },
+      ),
+    ).toBeUndefined();
+  });
+
+  test("a cron run off any forge has neither variable", () => {
+    expect(pullRequestContextFrom({})).toBeUndefined();
+    expect(pullRequestContextFrom({ GITHUB_REF: "refs/pull/1/merge" })).toBeUndefined();
+  });
+});
+
+describe("reconcilePr comment mode refuses a run with no pull request (#2231)", () => {
+  test("the message names the mode and every variable it looked for", async () => {
+    vi.stubEnv("GITHUB_REPOSITORY", "");
+    vi.stubEnv("GITHUB_REF", "");
+    vi.stubEnv("GITHUB_EVENT_PATH", "");
+    try {
+      // No `gh` is ever reached: the context check runs first, so a failure
+      // here is the refusal rather than a missing binary.
+      await expect(reconcilePr({ env: "app", mode: "comment", body: "plan" })).rejects.toThrow(
+        /mode "comment".*GITHUB_REPOSITORY.*GITHUB_EVENT_PATH.*GITHUB_REF/s,
+      );
+      await expect(reconcilePr({ env: "app", mode: "comment", body: "plan" })).rejects.toThrow(
+        /findingMode "issue" or "report"/,
+      );
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+});