@intentius/chant 0.57.0 → 0.59.0

package/src/discovery/param-deps.test.ts

@@ -1,7 +1,7 @@
 import * as ts from "typescript";
 import { describe, expect, test } from "vitest";
 import { collectConsts } from "../fold/fold";
-import { collectParamDependencies } from "./param-deps";
+import { collectCompositeOrigins, collectParamDependencies } from "./param-deps";
 import type { PathOrigin } from "../provenance";
 
 /**
@@ -116,3 +116,114 @@ describe("collectParamDependencies", () => {
     expect(depsOf(source)).toEqual({ name: param("name") });
   });
 });
+
+/**
+ * chant #2161 — the same walk over a composite factory's own parameter.
+ *
+ * The fixture shape is a factory body: the file is `const f = (<param>) => {
+ * <consts> return new Thing({...}); }`, so the body consts are in scope exactly
+ * as {@link import("./fold-import").interpretCompositeFactory} arranges them.
+ */
+function compositeOriginsOf(
+  body: string,
+  scope: { whole?: string[]; destructured?: Record<string, string> } = { whole: ["props"] },
+): Record<string, PathOrigin> {
+  const source = `const f = (p) => { ${body} };`;
+  const file = ts.createSourceFile("factory.ts", source, ts.ScriptTarget.Latest, true);
+
+  const consts = new Map<string, ts.Expression>();
+  let props: ts.ObjectLiteralExpression | undefined;
+  const visit = (node: ts.Node): void => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+      consts.set(node.name.text, node.initializer);
+    }
+    if (ts.isNewExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "Thing") {
+      for (const argument of node.arguments ?? []) {
+        if (ts.isObjectLiteralExpression(argument)) props ??= argument;
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(file);
+  if (!props) throw new Error("fixture has no `new Thing({...})`");
+
+  return collectCompositeOrigins(
+    props,
+    consts,
+    {
+      whole: new Set(scope.whole ?? []),
+      destructured: new Map(Object.entries(scope.destructured ?? {})),
+    },
+    "WebService",
+  );
+}
+
+const fromParam = (...names: string[]): PathOrigin => ({
+  kind: "composite-parameter",
+  composite: "WebService",
+  parameters: names,
+});
+const fixed: PathOrigin = { kind: "composite-literal", composite: "WebService" };
+
+describe("collectCompositeOrigins", () => {
+  test("a parameter read and a fixed literal are both recorded, at their own paths", () => {
+    expect(compositeOriginsOf(`return new Thing({ name: props.name, tier: "prod" });`)).toEqual({
+      name: fromParam("name"),
+      tier: fixed,
+    });
+  });
+
+  test("a nested parameter path keeps its dots", () => {
+    expect(compositeOriginsOf(`return new Thing({ path: props.iam.path });`)).toEqual({
+      path: fromParam("iam.path"),
+    });
+  });
+
+  test("a destructured parameter is the path it was destructured from", () => {
+    expect(
+      compositeOriginsOf(`return new Thing({ name: name, max: scaling.max });`, {
+        destructured: { name: "name", scaling: "scaling" },
+      }),
+    ).toEqual({ name: fromParam("name"), max: fromParam("scaling.max") });
+  });
+
+  test("a value hoisted into a body const is still attributed", () => {
+    expect(
+      compositeOriginsOf("const roleName = `role-for-${props.name}`; return new Thing({ roleName });"),
+    ).toEqual({ roleName: fromParam("name") });
+  });
+
+  test("a const bound to a sibling resource is NOT followed, so the field reads as fixed", () => {
+    expect(
+      compositeOriginsOf(`const b = new Bucket({ BucketName: props.name }); return new Thing({ ref: b.Arn });`),
+    ).toEqual({ ref: fixed });
+  });
+
+  test("an object literal is descended into; an array is attributed whole", () => {
+    expect(
+      compositeOriginsOf(`return new Thing({ v: { Status: "Enabled" }, Tags: [{ Key: "t", Value: props.tier }] });`),
+    ).toEqual({ "v.Status": fixed, Tags: fromParam("tier") });
+  });
+
+  test("a bare props reference names no single parameter", () => {
+    expect(compositeOriginsOf(`return new Thing({ all: props });`)).toEqual({ all: fixed });
+  });
+
+  test("a spread records a parameter it finds and claims nothing when it finds none", () => {
+    expect(compositeOriginsOf(`return new Thing({ ...props.extra, name: "n" });`)).toEqual({
+      "": fromParam("extra"),
+      name: fixed,
+    });
+    expect(compositeOriginsOf(`return new Thing({ ...defaults, name: "n" });`)).toEqual({ name: fixed });
+  });
+
+  test("a factory with no parameters at all fixes everything", () => {
+    expect(compositeOriginsOf(`return new Thing({ name: "n" });`, {})).toEqual({ name: fixed });
+  });
+
+  test("a computed key is skipped rather than guessed at", () => {
+    expect(compositeOriginsOf(`return new Thing({ [props.key]: 1, name: props.name });`)).toEqual({
+      name: fromParam("name"),
+    });
+  });
+});

package/src/discovery/param-deps.ts

@@ -31,6 +31,13 @@ import type { PathOrigin } from "../provenance";
  * consts without scope tracking. That reports a parameter the field could
  * plausibly be governed by rather than one it definitely is, which is the
  * failure the "could affect" reading is written to absorb.
+ *
+ * {@link collectCompositeOrigins} (chant #2161) is the same walk pointed at a
+ * different parameter object: a composite factory's own props, inside a body
+ * the fold interprets. It shares the path grammar, the const-following and the
+ * under-reporting posture, and adds the one answer a build parameter has no use
+ * for — a path that reads no parameter at all, which for a composite means the
+ * field is fixed.
  */
 
 /** The property name a member declares, when it is a literal one. */
@@ -168,3 +175,189 @@ export function collectParamDependencies(
   walk(props, "");
   return out;
 }
+
+/**
+ * The factory-parameter names in scope inside one composite body (chant #2161).
+ *
+ * A `Composite()` factory takes at most one argument, so a parameter path is a
+ * path INTO that argument: `props.scaling.max` is the parameter path
+ * `scaling.max`. Two binding forms reach the same place — `(props) => …` binds
+ * the whole object under one name, `({ name, port }) => …` binds leaves — so
+ * the scope carries both.
+ */
+export interface CompositeParamScope {
+  /** Local names bound to the whole props object (`(props) => …`). */
+  whole: ReadonlySet<string>;
+  /** Local name → the parameter path it was destructured from (`({ name }) => …`). */
+  destructured: ReadonlyMap<string, string>;
+}
+
+/** The parameter path `node` addresses, or `undefined` when it is not rooted at one. */
+function parameterPathOf(node: ts.Expression, scope: CompositeParamScope): string | undefined {
+  const segments: string[] = [];
+  let current: ts.Expression = node;
+  for (;;) {
+    if (ts.isPropertyAccessExpression(current)) {
+      segments.unshift(current.name.text);
+      current = current.expression;
+      continue;
+    }
+    if (ts.isElementAccessExpression(current) && ts.isStringLiteralLike(current.argumentExpression)) {
+      segments.unshift(current.argumentExpression.text);
+      current = current.expression;
+      continue;
+    }
+    break;
+  }
+  if (!ts.isIdentifier(current)) return undefined;
+  if (scope.whole.has(current.text)) {
+    // A bare `props` addresses no single parameter — the same call the
+    // build-param collector makes about a bare `params`.
+    return segments.length === 0 ? undefined : segments.join(".");
+  }
+  const base = scope.destructured.get(current.text);
+  if (base === undefined) return undefined;
+  return segments.length === 0 ? base : `${base}.${segments.join(".")}`;
+}
+
+/**
+ * True for a `const` bound to a sibling ENTITY rather than to a value: a
+ * `new Type(...)`, or a call (a nested composite, a helper).
+ *
+ * Following one would answer the wrong question. `const bucket = new Bucket({
+ * BucketName: props.name })` and then `Description: bucket.Arn` reads a
+ * reference to a sibling the composite wired up, not the value of `name`.
+ * Chasing it would report `Description` as governed by `name`, and the return
+ * leg would propose editing `name` to fix a field that is a cross-reference. A
+ * field wired inside the composite is one the composite fixes, and the refusal
+ * is the right answer.
+ */
+function isEntityBinding(initializer: ts.Expression): boolean {
+  const expr = unwrap(initializer);
+  return ts.isNewExpression(expr) || ts.isCallExpression(expr);
+}
+
+/**
+ * Every factory parameter path `expr` reads, following `consts` so a value
+ * hoisted into a body-local `const` is still attributed.
+ */
+function readCompositeParameters(
+  expr: ts.Expression,
+  consts: ReadonlyMap<string, ts.Expression>,
+  scope: CompositeParamScope,
+  out: Set<string>,
+): void {
+  const followed = new Set<string>();
+
+  const visit = (node: ts.Node): void => {
+    if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+      const path = parameterPathOf(node as ts.Expression, scope);
+      if (path !== undefined) {
+        out.add(path);
+        return;
+      }
+      visit(node.expression);
+      if (ts.isElementAccessExpression(node)) visit(node.argumentExpression);
+      return;
+    }
+
+    if (ts.isIdentifier(node)) {
+      const path = parameterPathOf(node, scope);
+      if (path !== undefined) {
+        out.add(path);
+        return;
+      }
+      if (scope.whole.has(node.text)) return;
+      const initializer = consts.get(node.text);
+      if (initializer && !followed.has(node.text) && !isEntityBinding(initializer)) {
+        followed.add(node.text);
+        visit(initializer);
+      }
+      return;
+    }
+
+    // A property KEY is not a reference — see `readParams` for the same guard.
+    if (ts.isPropertyAssignment(node)) {
+      visit(node.initializer);
+      return;
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  visit(expr);
+}
+
+/**
+ * Path → composite origin for one `new Type({...})` inside an interpreted
+ * composite factory body (chant #2161).
+ *
+ * Same walk, same path grammar and the same under-reporting posture as
+ * {@link collectParamDependencies}, with one added answer: a path whose
+ * expression reads NO parameter is recorded as `composite-literal` rather than
+ * left silent, because "the composite fixes this" is a finding in its own
+ * right — it is what the reconcile refuses on.
+ *
+ * A spread is the one place nothing is recorded when no parameter is found.
+ * Which keys it contributes is not knowable here, so `composite-parameter` at
+ * the containing object is a safe over-approximation of "a parameter governs
+ * something under here", while `composite-literal` would be a claim that every
+ * key it brings is fixed. That claim is left unmade, and those paths come back
+ * `unknown` from ../fold-provenance.ts instead.
+ */
+export function collectCompositeOrigins(
+  props: ts.ObjectLiteralExpression,
+  consts: ReadonlyMap<string, ts.Expression>,
+  scope: CompositeParamScope,
+  composite: string,
+): Record<string, PathOrigin> {
+  const out: Record<string, PathOrigin> = {};
+
+  const parametersOf = (expr: ts.Expression): string[] => {
+    const found = new Set<string>();
+    readCompositeParameters(expr, consts, scope, found);
+    return [...found].sort();
+  };
+
+  const record = (path: string, expr: ts.Expression, spread: boolean): void => {
+    const parameters = parametersOf(expr);
+    if (parameters.length > 0) {
+      const existing = out[path];
+      const merged =
+        existing && existing.kind === "composite-parameter"
+          ? [...new Set([...existing.parameters, ...parameters])].sort()
+          : parameters;
+      out[path] = { kind: "composite-parameter", composite, parameters: merged };
+      return;
+    }
+    if (spread) return;
+    out[path] ??= { kind: "composite-literal", composite };
+  };
+
+  const walk = (object: ts.ObjectLiteralExpression, prefix: string): void => {
+    for (const member of object.properties) {
+      if (ts.isSpreadAssignment(member)) {
+        record(prefix, member.expression, true);
+        continue;
+      }
+      if (ts.isShorthandPropertyAssignment(member)) {
+        const key = member.name.text;
+        record(prefix ? `${prefix}.${key}` : key, member.name, false);
+        continue;
+      }
+      if (!ts.isPropertyAssignment(member)) continue;
+      const key = literalName(member.name);
+      if (key === undefined) continue;
+      const path = prefix ? `${prefix}.${key}` : key;
+      const initializer = unwrap(member.initializer);
+      if (ts.isObjectLiteralExpression(initializer)) {
+        walk(initializer, path);
+        continue;
+      }
+      record(path, member.initializer, false);
+    }
+  };
+
+  walk(props, "");
+  return out;
+}

package/src/discovery/sandbox/bundle.ts

@@ -27,8 +27,22 @@ const require = createRequire(import.meta.url);
  * objects re-export their lint rules eagerly — so bundling ANY run-fallback
  * file that imports a lexicon package pulls `typescript` in transitively,
  * every time, not just for the rare file that uses the compiler itself.
+ *
+ * `@cdktf/hcl2json` is here for the same reason and by a longer road. It is
+ * an OPTIONAL dependency — `../../terraform/parse.ts` reaches it through
+ * `await import(...)` and turns a missing module into an actionable "npm
+ * install -D @cdktf/hcl2json" — but esbuild follows a dynamic import as
+ * eagerly as a static one, and the package ships a Go `wasm_exec` shim whose
+ * `performance` reference does not resolve under `platform: "node"`. So a
+ * bundle that merely *reaches* the carve commands fails outright. Reaching
+ * them is easy: the fountain lexicon's ACP server dynamically imports
+ * `cli/main` to resolve a prompt against chant's verb registry (chant #2125),
+ * so every project that imports `@intentius/chant-lexicon-fountain` and needs
+ * the run fallback — a `Steward` declaration does, since a composite call
+ * cannot fold — pulled the whole CLI, and carve with it, into its sandbox
+ * bundle (chant #2129).
  */
-const EXTERNAL_PACKAGES = ["typescript"];
+const EXTERNAL_PACKAGES = ["typescript", "@cdktf/hcl2json"];
 
 /**
  * Resolve each of {@link EXTERNAL_PACKAGES} to its real, absolute path on

package/src/discovery/sandbox/config-wire.test.ts

@@ -20,9 +20,9 @@ describe("scanConfigWireSafety", () => {
         buildParams: { tier: { type: "string", default: "light", enum: ["light", "prod"] } },
         lint: { rules: { COR001: "error", COR002: ["warning", { max: 3 }] }, policies: ["policies/org.ts"] },
         vulnPolicy: { failSeverity: "critical", license: { allow: ["MIT"], deny: [] } },
-        // A lexicon's passthrough extension (the temporal lexicon's shape) —
+        // A lexicon's passthrough extension —
         // still pure data.
-        temporal: { profiles: { local: { address: "localhost:7233", tls: false } }, defaultProfile: "local" },
+        k8s: { profiles: { local: { context: "kind-chant", namespace: "default" } }, defaultProfile: "local" },
       }),
     ).toEqual([]);
   });

package/src/discovery/sandbox/config-wire.ts

@@ -39,8 +39,8 @@
  *
  * The one way to get there is `ChantConfigSchema`'s `.passthrough()`, which
  * accepts unknown extra keys of any type (that is how a lexicon extends the
- * config — `temporal:` in the temporal lexicon's `TemporalChantConfig`, itself
- * pure data). A project that parks a function under such a key gets a clear
+ * config — a lexicon's own namespace key, itself pure data). A project that
+ * parks a function under such a key gets a clear
  * error naming it, rather than a config that silently lost it.
  *
  * ## The one accepted lossy case: `undefined` object properties

package/src/fold/fold.test.ts

@@ -559,6 +559,62 @@ describe("fold — registered authoring helpers (#1082)", () => {
   });
 });
 
+/**
+ * chant #2171. The ConvergeOp rule language joins the allowlist.
+ *
+ * A `ConvergeOp`'s `rules` table cannot be written without these, so before
+ * this every file declaring a converge rule fell back to run. They fold to the
+ * same symbolic envelope every other registered helper does; nothing is
+ * invoked here, and `../discovery/fold-import.ts` still decides separately
+ * whether the name is bound by an import from chant.
+ */
+describe("fold: the ConvergeOp rule builders are registered helpers (#2171)", () => {
+  test("a whole rule folds to nested envelopes, predicate and action included", () => {
+    const consts = parseConsts(
+      `const x = when(gt("updateCount", 0), report("drift"), { id: "prod-drift", why: "because" });`,
+    );
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(fold(expr, consts)).toEqual({
+      __helper: "when",
+      args: [
+        { __helper: "gt", args: ["updateCount", 0] },
+        { __helper: "report", args: ["drift"] },
+        { id: "prod-drift", why: "because" },
+      ],
+    });
+  });
+
+  test("every comparison, truthiness, combinator and action builder is registered", () => {
+    for (const call of [
+      `eq("status", "drifted")`,
+      `neq("status", "ok")`,
+      `gt("updateCount", 0)`,
+      `gte("updateCount", 1)`,
+      `lt("updateCount", 9)`,
+      `lte("updateCount", 9)`,
+      `truthy("drifted")`,
+      `falsy("drifted")`,
+      `allOf(truthy("drifted"))`,
+      `anyOf(falsy("drifted"))`,
+      `run("prod-apply")`,
+      `report("say so")`,
+    ]) {
+      const consts = parseConsts(`const x = ${call};`);
+      const expr = consts.get("x");
+      if (!expr) throw new Error(`fixture error: ${call}`);
+      expect(fold(expr, consts), call).toMatchObject({ __helper: expect.any(String) });
+    }
+  });
+
+  test("a rule builder SHADOWED by a local const is still rejected", () => {
+    const consts = parseConsts(`const gt = (f, v) => ({ f, v }); const x = gt("updateCount", 0);`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(() => fold(expr, consts)).toThrow(FoldError);
+  });
+});
+
 describe("fold — nullish coalescing, ternary, arithmetic", () => {
   test("?? falls through only on null/undefined", () => {
     expect(foldConst(`const x = null ?? "fallback";`, "x")).toBe("fallback");

package/src/fold/foldable-helpers.ts

@@ -66,7 +66,11 @@
  *     `fold()` already rejects a nested `new Type(...)` used as a value for a
  *     real, differential-caught reason (the envelope leaks into
  *     serialization); a factory that returns one is the same hazard wearing a
- *     call.
+ *     call. Still true after #2171, which registered the ConvergeOp RULE
+ *     builders below. Those return plain data that an Op carries; `Op()`
+ *     itself returns the entity, and a top-level `export const x = Op({...})`
+ *     folds through the composite spine in `../discovery/fold-import.ts`
+ *     rather than through this list, which is why it needs no entry here.
  *   - `propagate()`, `withDefaults()`, `resource()`, `mergeDefaults()`
  *     (`../composite.ts`) are composite *definition* helpers, not value-position
  *     helpers. `propagate()` in particular mutates its argument in place, and
@@ -119,7 +123,7 @@ export const FOLDABLE_AUTHORING_HELPERS: readonly FoldableHelperDef[] = [
   {
     name: "gate",
     module: "components/component.ts, op/builders.ts",
-    note: "Returns a plain `{ kind: 'gate', signalName, ... }` object literal built from its arguments.",
+    note: "Returns a plain `{ kind: 'gate', gate, ... }` object literal built from its arguments.",
   },
   {
     name: "activity",
@@ -136,6 +140,82 @@ export const FOLDABLE_AUTHORING_HELPERS: readonly FoldableHelperDef[] = [
     module: "lexicon-output.ts",
     note: "Constructs a `LexiconOutput` from a real `AttrRef`/`Intrinsic` and a name. Pure, but identity-sensitive: it reads through the ref's `WeakRef` to its parent entity. Only folds when the ref argument revives to a REAL live reference (see fold-import.ts's `requireLiveRefs`); a symbolic `{ __attrRef }` envelope is rejected, not silently wrapped.",
   },
+  // chant #2171. The ConvergeOp rule language (`op/converge-rule.ts`). Its own
+  // module doc is the admission argument: a rule is evaluated per tick against
+  // freshly observed data inside an activity, so it must be plain JSON, and
+  // every builder below is one statement returning an object literal built from
+  // its arguments. `when()` additionally validates `id`, `why` and
+  // `flapThreshold` and throws on a bad rule, which is the same build-time
+  // refusal the run path performs, at the same point in the build.
+  //
+  // These are authoring surface in the same sense `phase`/`activity` are: a
+  // `ConvergeOp`'s `rules` table cannot be written without them, so before this
+  // every file declaring a converge rule fell back to run whatever else it did.
+  {
+    name: "when",
+    module: "op/converge-rule.ts",
+    note: "Returns a plain `{ id, when, then, why, flapThreshold? }` rule record built from its arguments. Throws at construction on a missing `id`/`why` or a non-positive `flapThreshold`, which is the build-time refusal the run path performs too, so a bad rule fails identically either way.",
+  },
+  {
+    name: "eq",
+    module: "op/converge-rule.ts",
+    note: "Returns a plain `{ kind: 'field-comparison', field, op: 'eq', value }` literal built from its arguments.",
+  },
+  {
+    name: "neq",
+    module: "op/converge-rule.ts",
+    note: "Returns a plain `{ kind: 'field-comparison', field, op: 'neq', value }` literal built from its arguments.",
+  },
+  {
+    name: "gt",
+    module: "op/converge-rule.ts",
+    note: "Returns a plain `{ kind: 'field-comparison', field, op: 'gt', value }` literal built from its arguments.",
+  },
+  {
+    name: "gte",
+    module: "op/converge-rule.ts",
+    note: "Returns a plain `{ kind: 'field-comparison', field, op: 'gte', value }` literal built from its arguments.",
+  },
+  {
+    name: "lt",
+    module: "op/converge-rule.ts",
+    note: "Returns a plain `{ kind: 'field-comparison', field, op: 'lt', value }` literal built from its arguments.",
+  },
+  {
+    name: "lte",
+    module: "op/converge-rule.ts",
+    note: "Returns a plain `{ kind: 'field-comparison', field, op: 'lte', value }` literal built from its arguments.",
+  },
+  {
+    name: "truthy",
+    module: "op/converge-rule.ts",
+    note: "Returns a plain `{ kind: 'field-truthiness', field, op: 'truthy' }` literal built from its argument.",
+  },
+  {
+    name: "falsy",
+    module: "op/converge-rule.ts",
+    note: "Returns a plain `{ kind: 'field-truthiness', field, op: 'falsy' }` literal built from its argument.",
+  },
+  {
+    name: "allOf",
+    module: "op/converge-rule.ts",
+    note: "Returns a plain `{ kind: 'all-of', predicates }` literal over its already-folded predicate arguments.",
+  },
+  {
+    name: "anyOf",
+    module: "op/converge-rule.ts",
+    note: "Returns a plain `{ kind: 'any-of', predicates }` literal over its already-folded predicate arguments.",
+  },
+  {
+    name: "run",
+    module: "op/converge-rule.ts",
+    note: "Returns a plain `{ kind: 'run', op }` action literal. Names an Op for a later tick to dispatch; it runs nothing at fold time, or at any other time.",
+  },
+  {
+    name: "report",
+    module: "op/converge-rule.ts",
+    note: "Returns a plain `{ kind: 'report', reason }` action literal built from its argument.",
+  },
 ];
 
 const HELPER_NAMES: ReadonlySet<string> = new Set(FOLDABLE_AUTHORING_HELPERS.map((h) => h.name));