@intentius/chant 0.20.0 → 0.22.0

package/src/discovery/index.ts

@@ -56,6 +56,19 @@ export interface DiscoveryOptions {
    */
   intrinsics?: IntrinsicDef[];
 
+  /**
+   * chant #1063 — the lexicon NAMES loaded for this build (`["aws", "k8s"]`),
+   * i.e. what `resolveProjectLexicons()` returned and `loadPlugins()` then
+   * imported. Threaded into the fold session as the ALLOWLIST of packages a
+   * bare import specifier may be resolved into, so a lexicon's plain data
+   * exports (`Azure`/`GCP`'s pseudo-parameter namespaces, AWS's `S3Actions`,
+   * gitlab's `CI`) fold as identifier values instead of failing the file.
+   * Only meaningful when {@link fold} is set. Default: none — a caller that
+   * doesn't say which lexicons are active gets no bare-specifier resolution
+   * at all, rather than a looser fallback.
+   */
+  lexicons?: readonly string[];
+
   /**
    * chant #1045 Phase 2 — opt-in: whatever would otherwise reach the
    * in-process `importModule` step (every file, when {@link fold} isn't set;
@@ -156,7 +169,9 @@ export async function discover(path: string, options?: DiscoveryOptions): Promis
   // a project file imported by several others is folded exactly once, so
   // every referrer shares the identical constructed Declarable/
   // CompositeInstance objects rather than each building its own copy.
-  const foldSession = options?.fold ? createFoldSession(options.intrinsics, buildParamValuesMap) : undefined;
+  const foldSession = options?.fold
+    ? createFoldSession(options.intrinsics, buildParamValuesMap, options.lexicons)
+    : undefined;
   if (options?.fold) {
     for (const file of files) {
       foldAttempts.set(file, await tryFoldFile(file, options.intrinsics, foldSession));
@@ -166,6 +181,15 @@ export async function discover(path: string, options?: DiscoveryOptions): Promis
     ? await planFoldTaint(
         files,
         new Map(files.map((file) => [file, foldAttempts.get(file)?.ok === true])),
+        // chant #1044 — which files' OBJECTS each successful fold captured,
+        // so a file forced back to run also invalidates the folds that
+        // already hold its instances (see planFoldTaint's doc).
+        new Map(
+          files.flatMap((file) => {
+            const attempt = foldAttempts.get(file);
+            return attempt?.ok === true ? [[file, attempt.liveSources] as const] : [];
+          }),
+        ),
       )
     : new Set<string>();
 

package/src/fold/fold.test.ts

@@ -283,6 +283,237 @@ describe("fold — intrinsic tagged templates", () => {
   });
 });
 
+/**
+ * chant #1044 — registered lexicon intrinsics in PLAIN-CALL form.
+ *
+ * The registry is the whole door: a name folds as a call only when an active
+ * lexicon registered it AND set `foldsAsCall`. Everything below that pairs a
+ * folding case with the near-miss that must keep rejecting.
+ */
+describe("fold — registered call-form intrinsics (#1044)", () => {
+  /** Shaped like aws's real registration (lexicons/aws/src/plugin.ts). */
+  const REF: IntrinsicDef = { name: "Ref", isTag: false, foldsAsCall: true };
+  const JOIN: IntrinsicDef = { name: "Join", isTag: false, foldsAsCall: true };
+  /** Registered, but its lexicon never opted the call form in — the default. */
+  const NOT_OPTED_IN: IntrinsicDef = { name: "Reference", isTag: false };
+  const SUB: IntrinsicDef = { name: "Sub", isTag: true };
+
+  test("an opted-in call folds to the intrinsic node form, arguments folded in order", () => {
+    const consts = parseConsts(`const env = "prod"; const x = Ref(env);`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(fold(expr, consts, [REF])).toEqual({ __intrinsic: "Ref", args: ["prod"] });
+  });
+
+  test("the envelope is the same family the tagged-template form produces — same __intrinsic key, positional args", () => {
+    const consts = parseConsts(`const x = Join("-", ["a", "b"]);`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(fold(expr, consts, [JOIN])).toEqual({ __intrinsic: "Join", args: ["-", ["a", "b"]] });
+  });
+
+  test("calls nest, and a call-form intrinsic folds inside a registered tag's interpolation", () => {
+    const consts = parseConsts(`const env = "prod"; const x = Sub\`\${Ref(env)}-fn\`;`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(fold(expr, consts, [SUB, REF])).toEqual({
+      __intrinsic: "Sub",
+      strings: ["", "-fn"],
+      values: [{ __intrinsic: "Ref", args: ["prod"] }],
+    });
+  });
+
+  test("an argument nothing can resolve stays symbolic, exactly as inside a tag", () => {
+    const consts = parseConsts(`const x = Ref(AWS.StackName);`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(fold(expr, consts, [REF])).toEqual({
+      __intrinsic: "Ref",
+      args: [{ __symbol: "AWS.StackName" }],
+    });
+  });
+
+  test("an already-resolved cross-file binding wins over the symbolic path — identity must survive", () => {
+    const consts = parseConsts(`const x = Ref(environment);`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    const live = { marker: "the real, shared Parameter instance" };
+    const folded = fold(expr, consts, [REF], new Map([["environment", live]])) as {
+      __intrinsic: string;
+      args: unknown[];
+    };
+    expect(folded.args[0]).toBe(live);
+  });
+
+  test("a REGISTERED intrinsic that was never opted in is still rejected — the opt-in is the door, not registration", () => {
+    const consts = parseConsts(`const x = Reference("db");`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    let error: unknown;
+    try {
+      fold(expr, consts, [NOT_OPTED_IN]);
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeInstanceOf(FoldError);
+    expect((error as FoldError).message).toContain("function call as a value is not foldable: Reference(...)");
+  });
+
+  test("an opted-in name is rejected when its lexicon isn't among the active ones", () => {
+    const consts = parseConsts(`const x = Ref("db");`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(() => fold(expr, consts)).toThrow(FoldError);
+  });
+
+  test("a TAGGED-TEMPLATE intrinsic called as a plain function is rejected — the two forms are disjoint", () => {
+    const consts = parseConsts(`const x = Sub("literal");`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(() => fold(expr, consts, [SUB])).toThrow(FoldError);
+  });
+
+  test("a call-form intrinsic used as a TAG is rejected too — opting the call in doesn't register a tag", () => {
+    const consts = parseConsts(`const x = Ref\`literal\`;`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    let error: unknown;
+    try {
+      fold(expr, consts, [REF]);
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeInstanceOf(FoldError);
+    expect((error as FoldError).message).toContain("unregistered tagged template intrinsic: Ref");
+  });
+
+  test("a registered name reached as a METHOD (`ns.Ref(...)`) is rejected — only a bare identifier callee folds", () => {
+    const consts = parseConsts(`const x = aws.Ref("db");`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(() => fold(expr, consts, [REF])).toThrow(FoldError);
+  });
+
+  test("an array method taking a closure is rejected — .map is arbitrary JS, not a registered intrinsic", () => {
+    const consts = parseConsts(`const cidrs = ["10.0.0.0/24"]; const x = cidrs.map((c) => Ref(c));`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    let error: unknown;
+    try {
+      fold(expr, consts, [REF]);
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeInstanceOf(FoldError);
+    expect((error as FoldError).message).toContain("cidrs.map(...)");
+  });
+
+  test("a user-defined function is rejected however it's named", () => {
+    const consts = parseConsts(`const x = makeName("a", "b");`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(() => fold(expr, consts, [REF])).toThrow(FoldError);
+  });
+
+  test("a registered name SHADOWED by a local const is rejected — the local binding wins, and it isn't the lexicon's", () => {
+    const consts = parseConsts(`const Ref = (n) => ({ mine: n }); const x = Ref("db");`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(() => fold(expr, consts, [REF])).toThrow(FoldError);
+  });
+
+  test("an unfoldable argument still rejects the whole call", () => {
+    const consts = parseConsts(`const x = Ref(getName());`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    let error: unknown;
+    try {
+      fold(expr, consts, [REF]);
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeInstanceOf(FoldError);
+    expect((error as FoldError).message).toContain("getName(...)");
+  });
+
+  test("a same-file resource passed to an intrinsic call rejects rather than folding to a look-alike envelope", () => {
+    const consts = parseConsts(`const bucket = new S3Bucket({ name: "b" }); const x = Ref(bucket);`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(() => fold(expr, consts, [REF])).toThrow(FoldError);
+  });
+});
+
+describe("fold — registered authoring helpers (#1082)", () => {
+  test("a registered helper call folds to the helper-call node form, arguments folded in order", () => {
+    const consts = parseConsts(`const stack = "web"; const x = phase("Apply", [{ kind: "cfn-deploy", stack }]);`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(fold(expr, consts)).toEqual({
+      __helper: "phase",
+      args: ["Apply", [{ kind: "cfn-deploy", stack: "web" }]],
+    });
+  });
+
+  test("helper calls nest, so a fan-out phase folds to nested envelopes", () => {
+    const consts = parseConsts(`const x = phase("Outer", [phase("Inner", []), gate("approve")]);`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(fold(expr, consts)).toEqual({
+      __helper: "phase",
+      args: [
+        "Outer",
+        [
+          { __helper: "phase", args: ["Inner", []] },
+          { __helper: "gate", args: ["approve"] },
+        ],
+      ],
+    });
+  });
+
+  test("an unfoldable argument still rejects the whole call", () => {
+    const consts = parseConsts(`const x = phase("Apply", [{ stack: getName() }]);`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(() => fold(expr, consts)).toThrow(FoldError);
+  });
+
+  test("an UNREGISTERED name is still rejected — the allowlist is closed, not a general call case", () => {
+    const consts = parseConsts(`const x = compose("Apply", []);`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    let error: unknown;
+    try {
+      fold(expr, consts);
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeInstanceOf(FoldError);
+    expect((error as FoldError).message).toContain("function call as a value is not foldable: compose(...)");
+  });
+
+  test("a registered name SHADOWED by a local const is rejected — the local binding wins, and it isn't chant's", () => {
+    const consts = parseConsts(`const phase = (n) => ({ phase: n }); const x = phase("Apply");`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(() => fold(expr, consts)).toThrow(FoldError);
+  });
+
+  test("a registered name used as a METHOD (`ns.phase(...)`) is rejected — only a bare identifier callee folds", () => {
+    const consts = parseConsts(`const x = helpers.phase("Apply", []);`);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture error");
+    expect(() => fold(expr, consts)).toThrow(FoldError);
+  });
+
+  test("a spread argument is rejected — fold has no case for one, registered callee or not", () => {
+    const consts = parseConsts(`const steps = []; const x = phase(...steps);`);
+    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");
@@ -428,6 +659,52 @@ describe("fold — rejections", () => {
   });
 });
 
+describe("foldResource — constructor argument positions (#1082)", () => {
+  test("a props object that isn't the FIRST argument still folds, reported as a positional arg list", () => {
+    // AWS's deploy-time Parameter is `(type, props)` — lexicons/aws/src/parameter.ts.
+    const src = `export const p = new Parameter("String", { description: "vpc id", defaultValue: "" });`;
+    const result = foldModule(src);
+    expect(result.p).toEqual({
+      ok: true,
+      spec: {
+        __resource: "Parameter",
+        props: { description: "vpc id", defaultValue: "" },
+        args: ["String", { description: "vpc id", defaultValue: "" }],
+      },
+    });
+  });
+
+  test("a constructor with no object-literal argument at all folds to its bare argument list", () => {
+    const src = `export const p = new Parameter("String");`;
+    const result = foldModule(src);
+    expect(result.p).toEqual({ ok: true, spec: { __resource: "Parameter", props: {}, args: ["String"] } });
+  });
+
+  test("the classic (props) shape is unchanged — no `args` list", () => {
+    const src = `export const b = new S3Bucket({ name: "b" });`;
+    const result = foldModule(src);
+    expect(result.b).toEqual({ ok: true, spec: { __resource: "S3Bucket", props: { name: "b" } } });
+  });
+
+  test("the classic (props, attributes) shape is unchanged — no `args` list", () => {
+    const src = `export const b = new S3Bucket({ name: "b" }, { DependsOn: "other" });`;
+    const result = foldModule(src);
+    expect(result.b).toEqual({
+      ok: true,
+      spec: { __resource: "S3Bucket", props: { name: "b" }, attributes: { DependsOn: "other" } },
+    });
+  });
+
+  test("a non-object-literal argument is folded, not rejected for its position — but must still be foldable", () => {
+    const src = `export const p = new Parameter(getType(), { description: "x" });`;
+    const result = foldModule(src);
+    expect(result.p?.ok).toBe(false);
+    if (result.p && !result.p.ok) {
+      expect(result.p.error).toContain("getType(...)");
+    }
+  });
+});
+
 describe("foldModule", () => {
   test("folds an exported const resource to { ok: true, spec }", () => {
     const src = `