@intentius/chant 0.124.25 → 0.124.27

package/src/lint/rules/op/ops017-gate-alias.ts

@@ -0,0 +1,89 @@
+/**
+ * OPS017: a gate's aliases (#3949) can stand. An alias admits approvals of
+ * the plan a run planned, so the gate must bind a `plan`, and a gate that
+ * asks a decision point takes none. An alias must not name a gate that still
+ * exists in the build, or one approval would answer two gates, and two gates
+ * must not claim one alias. When the workspace's `identity.gates` names an
+ * alias, the new gate must be named too, with the alias's class, or
+ * approvals that needed a seal would count without one.
+ *
+ * The identity rules come from the caller, as SYS010's decide backends do:
+ * `chant build` and `chant lint` read them with
+ * {@link workspaceIdentityGates}, which loads workspace code only when an Op
+ * has aliases and the project sits in a workspace. Without them that part
+ * is skipped.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "../../post-synth";
+import type { OpConfig } from "../../../op";
+import { gateStepsOf, validateGateAliases } from "../../../op/gate-alias";
+import { findWorkspaceRoot } from "../../../project-root";
+import { isOpEntity } from "./support";
+
+/** The Op configs among a build's entities, each with its entity key and lexicon. */
+function opsOf(entities: Iterable<[string, unknown]>): Array<{ entityKey: string; lexicon?: string; config: OpConfig }> {
+  const ops: Array<{ entityKey: string; lexicon?: string; config: OpConfig }> = [];
+  for (const [entityKey, entity] of entities) {
+    if (!isOpEntity(entity as never)) continue;
+    const rec = entity as Record<string, unknown>;
+    const props = ((entity as { props?: Record<string, unknown> }).props ?? {}) as unknown as OpConfig;
+    if (typeof props.name !== "string" || !Array.isArray(props.phases)) continue;
+    ops.push({ entityKey, ...(typeof rec.lexicon === "string" ? { lexicon: rec.lexicon } : {}), config: props });
+  }
+  return ops;
+}
+
+const hasAliases = (ops: ReadonlyArray<{ config: OpConfig }>): boolean =>
+  ops.some(({ config }) => gateStepsOf(config).some(({ step }) => step.aliases !== undefined));
+
+/**
+ * The gates the workspace around `projectDir` names under `identity.gates`,
+ * each with its class (null for any signer), for OPS017. Undefined when no
+ * Op among `entities` has aliases, outside a workspace, or when the
+ * declaration can't be read, which `chant workspace check` reports. The
+ * workspace modules load only past the first two checks, so a level-0
+ * build loads none.
+ */
+export async function workspaceIdentityGates(
+  projectDir: string,
+  entities: Iterable<[string, unknown]>,
+): Promise<Map<string, string | null> | undefined> {
+  if (!hasAliases(opsOf(entities))) return undefined;
+  const found = findWorkspaceRoot(projectDir);
+  if (!found) return undefined;
+  try {
+    const { readDeclaration } = await import("../../../workspace/declaration");
+    const { workingTree } = await import("../../../workspace/tree");
+    const gates = readDeclaration(workingTree(found.dir)).identity?.gates ?? {};
+    return new Map(Object.values(gates).map((g) => [g.gate, g.class]));
+  } catch {
+    return undefined;
+  }
+}
+
+/** OPS017, judging `identity.gates` by `identityGates` when given. */
+export function ops017Check(identityGates?: ReadonlyMap<string, string | null>): PostSynthCheck {
+  return {
+    id: "OPS017",
+    description:
+      "A gate's aliases need a plan and no decision point, must not name a gate that still exists or another gate's alias, and keep any identity.gates rule an alias had",
+
+    check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+      const ops = opsOf(ctx.entities);
+      if (!hasAliases(ops)) return [];
+      const byName = new Map(ops.map((o) => [o.config.name, o]));
+      return validateGateAliases(ops.map((o) => o.config), identityGates).map((issue) => {
+        const op = byName.get(issue.opName);
+        return {
+          checkId: "OPS017",
+          severity: "error",
+          message: `Op "${issue.opName}", phase "${issue.phase}", gate:${issue.gate}: ${issue.message}`,
+          ...(op ? { entity: op.entityKey } : {}),
+          ...(op?.lexicon ? { lexicon: op.lexicon } : {}),
+        };
+      });
+    },
+  };
+}
+
+/** OPS017 without the workspace's identity rules. */
+export const ops017: PostSynthCheck = ops017Check();

package/src/op/activity-contract.ts

@@ -89,6 +89,26 @@ export interface ActivityContract<Args = unknown, Return = unknown> {
    * stack members internally) simply declares none.
    */
   entities?: string[];
+  /**
+   * What the activity returns that is secret (#3947): `true` for the whole
+   * return value, or the names of its top-level fields that are. A gate that
+   * resumes never stores a secret output in its checkpoint, so a gate whose
+   * later steps reference one doesn't resume, and OPS016 says so at build.
+   */
+  secret?: true | string[];
+}
+
+/**
+ * Whether a reference into `contract`'s return value at `path` reads a value
+ * the contract marks secret (#3947). A whole-value reference reads every
+ * field, so it is secret when any field is.
+ */
+export function readsSecretOutput(contract: Pick<ActivityContract, "secret"> | undefined, path?: string): boolean {
+  const secret = contract?.secret;
+  if (secret === undefined) return false;
+  if (secret === true) return true;
+  if (!path) return secret.length > 0;
+  return secret.includes(path.split(".")[0]!);
 }
 
 /** Declare an activity contract. */
@@ -96,7 +116,7 @@ export function activityContract<ArgsSchema extends z.ZodTypeAny, ReturnSchema e
   name: string,
   args: ArgsSchema,
   returns?: ReturnSchema,
-  opts?: { entities?: string[] },
+  opts?: { entities?: string[]; secret?: true | string[] },
 ): ActivityContract<z.infer<ArgsSchema>, ReturnSchema extends z.ZodTypeAny ? z.infer<ReturnSchema> : unknown> {
   return {
     [CONTRACT_BRAND]: true,
@@ -104,6 +124,7 @@ export function activityContract<ArgsSchema extends z.ZodTypeAny, ReturnSchema e
     args,
     ...(returns ? { returns } : {}),
     ...(opts?.entities && opts.entities.length > 0 ? { entities: opts.entities } : {}),
+    ...(opts?.secret === true || (Array.isArray(opts?.secret) && opts.secret.length > 0) ? { secret: opts!.secret } : {}),
   } as ActivityContract<z.infer<ArgsSchema>, ReturnSchema extends z.ZodTypeAny ? z.infer<ReturnSchema> : unknown>;
 }
 

package/src/op/activity-registry.ts

@@ -4,13 +4,15 @@
  *
  * The base activities are core's own (`./activities`): plain async functions
  * taking a single args object, with no workflow engine anywhere in the call
- * path. They are imported statically, so `loadActivities([])` works in a
- * project that has installed nothing but chant. Product-specific appliers stay
+ * path. They ship with core, so `loadActivities([])` works in a project that
+ * has installed nothing but chant. They are imported when activities are
+ * loaded, not when this module is: their implementations reach lint, codegen
+ * and `typescript`, and every `*.op.ts` imports `@intentius/chant/op`, which
+ * re-exports this module (#3982). Product-specific appliers stay
  * in their owning lexicon (#809) and are pulled in dynamically per the
  * project's configured lexicon list.
  */
 
-import * as baseActivities from "./activities";
 import { ACTIVITY_PROFILES, type ActivityProfile } from "./activity-profiles";
 import { importLexiconModule, importLexiconPackage } from "../lexicon-module";
 
@@ -63,13 +65,13 @@ function collectActivities(mod: Record<string, unknown>, into: Map<string, Activ
  * lexicon's activity of the same name; otherwise a later lexicon's export
  * replaces an earlier one's.
  *
- * Never throws: the base library is a static import, so there is no "no
+ * Never throws: the base library ships with core, so there is no "no
  * activities registered" state to report.
  */
 export async function loadActivities(lexicons: string[] = []): Promise<Map<string, ActivityFn>> {
   const activities = new Map<string, ActivityFn>();
 
-  collectActivities(baseActivities as unknown as Record<string, unknown>, activities);
+  collectActivities((await import("./activities")) as unknown as Record<string, unknown>, activities);
 
   for (const name of lexicons) {
     try {

package/src/op/builders.ts

@@ -5,6 +5,7 @@ import { isEffectReceipt, type EffectReceiptDeclaration } from "../effect-receip
 import { receiptCheckInput } from "./receipt-store";
 import { gateApprovalProblems } from "./gate-approval";
 import { gatePointProblems } from "./gate-point";
+import { gateAliasProblems } from "./gate-alias";
 import { makeOutProxy, stepOutput, type StepOutputRef, type WithStepRefs } from "./step-output-ref";
 import type { ChantBuildArgs } from "./activities/build";
 import type { ShellCmdArgs } from "./activities/shell";
@@ -135,10 +136,23 @@ export function activity(
  * The point's deciders and quorum decide, `chant workspace points answer`
  * answers an open question, and the run passes on the answer. See
  * {@link GateStep.point}.
+ *
+ * Pass `aliases` to keep the approvals recorded under the gate's old names
+ * after an Op is restructured (#3949): `gate("approve-tier-1", { plan:
+ * plan.out.planDigest, aliases: [{ op: "upgrade-tier-1", gate: "approve" }] })`.
+ * A gate with aliases must bind a plan. See {@link GateStep.aliases}.
  */
 export function gate(
   name: string,
-  opts?: { timeout?: string; description?: string; plan?: GateStep["plan"]; approval?: GateStep["approval"]; point?: GateStep["point"] },
+  opts?: {
+    timeout?: string;
+    description?: string;
+    plan?: GateStep["plan"];
+    approval?: GateStep["approval"];
+    point?: GateStep["point"];
+    resume?: boolean;
+    aliases?: GateStep["aliases"];
+  },
 ): GateStep {
   if (opts?.approval !== undefined) {
     const problems = gateApprovalProblems(opts.approval);
@@ -148,6 +162,10 @@ export function gate(
     const problems = gatePointProblems(opts.point, opts.approval !== undefined);
     if (problems.length > 0) throw new Error(`gate(${JSON.stringify(name)}): ${problems[0]}`);
   }
+  if (opts?.aliases !== undefined) {
+    const problems = gateAliasProblems(opts.aliases, { plan: opts.plan, point: opts.point });
+    if (problems.length > 0) throw new Error(`gate(${JSON.stringify(name)}): ${problems[0]}`);
+  }
   return {
     kind: "gate",
     gate: name,
@@ -156,6 +174,8 @@ export function gate(
     ...(opts?.plan !== undefined ? { plan: opts.plan } : {}),
     ...(opts?.approval !== undefined ? { approval: opts.approval } : {}),
     ...(opts?.point !== undefined ? { point: opts.point } : {}),
+    ...(opts?.resume ? { resume: true } : {}),
+    ...(opts?.aliases !== undefined && opts.aliases.length > 0 ? { aliases: opts.aliases.map((a) => ({ ...(a.op !== undefined ? { op: a.op } : {}), gate: a.gate })) } : {}),
   };
 }
 

package/src/op/discover-root.test.ts

@@ -170,3 +170,42 @@ describe("discoverOps: an Op may be exported by name (#2171)", () => {
     expect(errors[0]).toContain(`Duplicate Op name "twice" declared twice in`);
   });
 });
+
+/**
+ * #3976. Reading the project's `exclude`/`include` evaluates its config,
+ * which registers tsx, so discovery reads them only when an Op file could be
+ * found. An `exclude` that is not a list is an error whenever the config is
+ * read, which is how these tests tell whether it was.
+ */
+describe("discoverOps reads the config's globs only when there is an Op file (#3976)", () => {
+  let checkout: string;
+  beforeEach(() => {
+    checkout = realpathSync(mkdtempSync(join(tmpdir(), "chant-op-globs-")));
+    fakeGitRoot = checkout;
+    mkdirSync(join(checkout, "src"), { recursive: true });
+    writeFileSync(join(checkout, "src", "infra.ts"), "export const x = 1;\n");
+  });
+  afterEach(() => rmSync(checkout, { recursive: true, force: true }));
+
+  test("a project with no Op file has its config left unread", async () => {
+    writeFileSync(join(checkout, "chant.config.json"), JSON.stringify({ lexicons: ["aws"], exclude: 42 }));
+    const { ops, errors } = await discoverOps({ cwd: checkout });
+    expect(errors).toEqual([]);
+    expect([...ops.keys()]).toEqual([]);
+  });
+
+  test("with an Op file the config is read", async () => {
+    writeFileSync(join(checkout, "chant.config.json"), JSON.stringify({ lexicons: ["aws"], exclude: 42 }));
+    writeFileSync(join(checkout, "src", "run.op.ts"), OP_FILE("run"));
+    await expect(discoverOps({ cwd: checkout })).rejects.toThrow(/exclude/);
+  });
+
+  test("an Op file only `include` re-admits is still found", async () => {
+    writeFileSync(join(checkout, "chant.config.json"), JSON.stringify({ lexicons: ["aws"], include: [".ops"] }));
+    mkdirSync(join(checkout, ".ops"));
+    writeFileSync(join(checkout, ".ops", "hidden.op.ts"), OP_FILE("hidden"));
+    const { ops, errors } = await discoverOps({ cwd: checkout });
+    expect(errors).toEqual([]);
+    expect([...ops.keys()]).toEqual(["hidden"]);
+  });
+});

package/src/op/discover.ts

@@ -57,22 +57,29 @@ async function findDiscoveryRoot(cwd?: string): Promise<string> {
   return gitRoot;
 }
 
+const isOpFile = (name: string, full: string): boolean =>
+  name.endsWith(".op.ts") && !name.endsWith(".test.ts") && !name.endsWith(".spec.ts") && !hasDiscoveryMarkerSync(full);
+
 /**
  * Every `*.op.ts` file below the Op root, through the one discovery walk
  * (`../discovery/walk.ts`, #2527). The walk down stops at child projects
  * whatever the root is, so a configless layout whose Op root is the git root
  * no longer collects its sibling projects' Ops. The project's
  * `exclude`/`include` globs and the skip marker apply.
+ *
+ * The globs come from evaluating the project config, which registers tsx
+ * (#3976), so they are resolved only when an Op file could be found. A walk
+ * that includes `**` first reaches every path any `include` could re-admit,
+ * and stops at the first Op file. When it finds none, no globs could find
+ * one either.
  */
 async function collectOpFiles(root: string): Promise<string[]> {
-  return walkDiscovery({
-    walker: "ops",
-    root,
-    globs: await resolveDiscoveryGlobs(root),
-    excludeDirs: await workspaceMemberDirs(root),
-    accept: (name, full) =>
-      name.endsWith(".op.ts") && !name.endsWith(".test.ts") && !name.endsWith(".spec.ts") && !hasDiscoveryMarkerSync(full),
-  });
+  const excludeDirs = await workspaceMemberDirs(root);
+  // A limit of 0 ends the walk at the first file it accepts.
+  const any = { max: 0, truncated: false };
+  walkDiscovery({ walker: "ops", root, globs: { root, exclude: [], include: ["**"] }, excludeDirs, limit: any, accept: isOpFile });
+  if (!any.truncated) return [];
+  return walkDiscovery({ walker: "ops", root, globs: await resolveDiscoveryGlobs(root), excludeDirs, accept: isOpFile });
 }
 
 /** The `OpConfig` behind an exported value, or `undefined` when the value is not an Op. An Op entity carries its config on `.props` (`./resource.ts`); `name` and `phases` are what every consumer of a discovered Op reads. */

package/src/op/gate-alias.e2e.test.ts

@@ -0,0 +1,78 @@
+/**
+ * #3949 against a real `chant/lifecycle` branch: an approval recorded under
+ * a per-tier Op's gate passes the merged Op's gate that lists it as an
+ * alias. The run reads the old Op's ledger file, writes the carried line to
+ * its own, and the next run passes on that line alone.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, commitAll, git, repo } from "../workspace/__fixtures__/contract-repo";
+import { appendGateResolution, appendPendingGate, readGateLedger } from "../lifecycle/gate-ledger";
+import { runOpLocally } from "./local-executor";
+import { gitGateLedgerPort } from "./gate";
+import { stepOutput } from "./step-output-ref";
+import type { ActivityFn } from "./activity-registry";
+import type { OpConfig } from "./types";
+
+const PLAN = `jcs1-sha256:${"a".repeat(64)}`;
+
+let root: string;
+beforeAll(() => {
+  root = repo({ "chant.config.json": "{}\n" }, false);
+  git(root, "config", "user.name", "Gate Test");
+  git(root, "config", "user.email", "gate@example.com");
+  commitAll(root, "c0");
+});
+afterAll(cleanScratch);
+
+const applied: string[] = [];
+const ACTIVITIES = new Map<string, ActivityFn>([
+  ["plan", async () => ({ planDigest: PLAN })],
+  ["apply", async (args) => (applied.push(String((args as { tier: string }).tier)), { ok: true })],
+]);
+
+const merged: OpConfig = {
+  name: "upgrade",
+  overview: "upgrade every tier, one wave each",
+  phases: [
+    { name: "Plan", steps: [{ kind: "activity", id: "plan", fn: "plan" }] },
+    {
+      name: "Wave 1",
+      steps: [{ kind: "gate", gate: "approve-tier-1", plan: stepOutput("plan", "planDigest"), aliases: [{ op: "upgrade-tier-1", gate: "approve" }] }],
+    },
+    { name: "Apply 1", steps: [{ kind: "activity", fn: "apply", args: { tier: "1" } }] },
+  ],
+};
+
+describe("a gate alias on a real ledger", () => {
+  test("the merged Op passes on the old Op's approval, and keeps passing on the carried line", async () => {
+    const now = Date.now();
+    const iso = (s: number) => new Date(now + s * 1000).toISOString();
+    await appendPendingGate(
+      { op: "upgrade-tier-1", gate: "approve", timestamp: iso(-60), expiresAt: iso(3600), planDigest: PLAN, runId: "old-run" },
+      { cwd: root },
+    );
+    await appendGateResolution({ op: "upgrade-tier-1", gate: "approve", resolvedBy: "alice", timestamp: iso(-30), planDigest: PLAN }, { cwd: root });
+
+    const port = gitGateLedgerPort({ cwd: root });
+    const first = await runOpLocally(merged, ACTIVITIES, {}, undefined, { cwd: root, gates: port, runId: "run-1" });
+    expect(first.status).toBe("ok");
+    expect(first.records.find((r) => r.fn === "gate:approve-tier-1")?.approval).toMatchObject({ resolvedBy: "alice", via: "alias" });
+
+    const ledger = await readGateLedger("upgrade", { cwd: root });
+    expect(ledger.resolutions).toHaveLength(1);
+    expect(ledger.resolutions[0]).toMatchObject({
+      op: "upgrade",
+      gate: "approve-tier-1",
+      resolvedBy: "alice",
+      planDigest: PLAN,
+      carriedFrom: { op: "upgrade-tier-1", gate: "approve", timestamp: iso(-30) },
+    });
+
+    const second = await runOpLocally(merged, ACTIVITIES, {}, undefined, { cwd: root, gates: port, runId: "run-2" });
+    expect(second.status).toBe("ok");
+    expect(second.records.find((r) => r.fn === "gate:approve-tier-1")?.approval?.via).toBeUndefined();
+    expect((await readGateLedger("upgrade", { cwd: root })).resolutions).toHaveLength(1);
+    expect(applied).toEqual(["1", "1"]);
+  });
+});