@intentius/chant 0.69.0 → 0.70.0

package/dist/cli/handlers/lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/lifecycle.ts"],"names":[],"mappings":"AA6CA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAKlD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAE9E;AAmCD;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAyH/E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA4C3E;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8B/E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAmL3E;AAmrBD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAwQ3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA2L/E;AAsBD;;GAEG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB1E;AAgBD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAmE7E;AAiCD;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9E;AAkBD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA+C/E"}
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/lifecycle.ts"],"names":[],"mappings":"AA6CA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAKlD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAE9E;AAmCD;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAyH/E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA4C3E;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8B/E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAmL3E;AAmrBD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAqR3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA2L/E;AAsBD;;GAEG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB1E;AAgBD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAmE7E;AAiCD;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9E;AAkBD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA+C/E"}

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAMA,OAAO,EAAkB,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAwF9E;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA6VpD;AAgbD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,UAAU,EAkGvC,CAAC;AAgIF;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB5E"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAMA,OAAO,EAAkB,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAwF9E;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA6VpD;AAqbD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,UAAU,EAkGvC,CAAC;AAgIF;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB5E"}

package/dist/discovery/import.d.ts

@@ -1,9 +1,23 @@
+/**
+ * Forget every recorded evaluation failure.
+ *
+ * For a harness that deliberately starts a fresh module graph and wants the
+ * failures forgotten with it. Nothing in chant calls this: a real build
+ * imports once, and a second import inside one process is supposed to see what
+ * the first one saw.
+ *
+ * It does not make a module re-evaluate. Node's own registry still holds the
+ * failed record and still re-throws; this only clears chant's memory of it. A
+ * caller wanting genuine re-evaluation needs a fresh process.
+ */
+export declare function resetImportFailures(): void;
 /**
  * Dynamically import a module and return its exports.
  *
  * @param path - The file path to import
  * @returns The module exports
- * @throws {DiscoveryError} with type "import" if the import fails
+ * @throws {DiscoveryError} with type "import" if the import fails, including
+ *   on every later import of a module whose evaluation has already failed
  */
 export declare function importModule(path: string): Promise<Record<string, unknown>>;
 //# sourceMappingURL=import.d.ts.map

package/dist/discovery/import.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../src/discovery/import.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAQlC"}
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../src/discovery/import.ts"],"names":[],"mappings":"AA4BA;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAalC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.69.0",
+  "version": "0.70.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/handlers/lifecycle.test.ts

@@ -916,6 +916,71 @@ describe("runLifecyclePlan", () => {
   // #2162 — a held property is not an action, so the plan carries it beside
   // `entries` rather than inside one, attributed to its lexicon the same way
   // an entry is.
+  test("without --deep the pass does not run, and the entries are unchanged (#2405)", async () => {
+    // The property that makes `--deep` safe to default off: a held property is
+    // never a proposal, so the change set is identical either way and the only
+    // thing the flag buys is the HELD section. If that stops being true, this
+    // is where it shows.
+    const makeBuild = () => {
+      const b = makeBuildResult({ k8s: ["web"] });
+      b.entities.set("web", {
+        lexicon: "k8s",
+        entityType: "K8s::Apps::Deployment",
+        props: { spec: { replicas: heldElsewhere<number>({ by: "hpa", reason: "the autoscaler owns replicas after the first apply" }) } },
+      } as never);
+      return b;
+    };
+    let deepCalls = 0;
+    const makePlugins = (): LexiconPlugin[] => {
+      const inner = staticDeepObservation({
+        web: { type: "K8s::Apps::Deployment", properties: { spec: { replicas: 5 } } },
+      });
+      return [
+        createMockPlugin({
+          name: "k8s",
+          describeResources: staticObservation({ web: meta({ type: "K8s::Apps::Deployment" }) }),
+          // Counting wrapper: the helper's return type is the plugin member's,
+          // which is optional, so it is narrowed once here rather than at the
+          // call.
+          observeResourcesDeep: ((opts: never) => {
+            deepCalls += 1;
+            return inner!(opts);
+          }) as never,
+        }),
+      ];
+    };
+
+    const run = async (deep: boolean) => {
+      stdoutBuf.length = 0;
+      buildMock.mockResolvedValue(makeBuild());
+      const plugins = makePlugins();
+      const exit = await runLifecyclePlan({
+        args: makeArgs({ path: "plan", extraPositional: "prod", json: true, ...(deep ? { deep: true } : {}) }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      } as never);
+      expect(exit).toBe(0);
+      return JSON.parse(stdoutBuf.join("\n"));
+    };
+
+    deepCalls = 0;
+    const shallow = await run(false);
+    const callsWithoutDeep = deepCalls;
+
+    deepCalls = 0;
+    const deep = await run(true);
+
+    // The cost: the pass is not run at all without the flag.
+    expect(callsWithoutDeep).toBe(0);
+    expect(deepCalls).toBeGreaterThan(0);
+
+    // The correctness: the same proposals either way, and the held section
+    // only when it was asked for.
+    expect(shallow.entries).toEqual(deep.entries);
+    expect(shallow.held).toBeUndefined();
+    expect(deep.held).toBeDefined();
+  });
+
   test("--json carries the held set beside entries, attributed to its lexicon", async () => {
     const build = makeBuildResult({ k8s: ["web"] });
     build.entities.set("web", {
@@ -934,7 +999,7 @@ describe("runLifecyclePlan", () => {
       }),
     ];
     const exit = await runLifecyclePlan({
-      args: makeArgs({ path: "plan", extraPositional: "prod", json: true }),
+      args: makeArgs({ path: "plan", extraPositional: "prod", json: true, deep: true }),
       plugins,
       serializers: plugins.map((p) => p.serializer),
     });
@@ -971,7 +1036,7 @@ describe("runLifecyclePlan", () => {
       }),
     ];
     const exit = await runLifecyclePlan({
-      args: makeArgs({ path: "plan", extraPositional: "prod" }),
+      args: makeArgs({ path: "plan", extraPositional: "prod", deep: true }),
       plugins,
       serializers: plugins.map((p) => p.serializer),
     });

package/src/cli/handlers/lifecycle.ts

@@ -1319,11 +1319,24 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
 
       Object.assign(allObservedResources, observed.resources);
 
-      // Held properties (#2162): opt-in on the same capability the deep diff
-      // path gates on. A held property is never a proposal, so it is
-      // computed here (once per lexicon, against this same observation) and
-      // carried on the plan beside `entries` rather than folded into one.
-      if (plugin.observeResourcesDeep) {
+      // Held properties (#2162), behind `--deep` since #2405.
+      //
+      // A held property is never a proposal: it is computed against this same
+      // observation and carried on the plan beside `entries`, never folded
+      // into one. So the entries a plan proposes are identical whether this
+      // ran or not, and the only thing `--deep` buys is the HELD section.
+      //
+      // It used to run whenever the lexicon could, which made the read's cost
+      // a function of how many resources an estate holds rather than how it is
+      // organised. Measured on 528 resources across 8 stacks: 24 stack-shaped
+      // calls, and 496 from this pass. At ten thousand resources that is
+      // roughly twenty thousand calls against eighty, for a section the caller
+      // did not ask for.
+      //
+      // `--deep` is the flag `lifecycle snapshot` already uses for the same
+      // choice, and `lifecycle diff` still runs the pass unconditionally
+      // because property drift is the question it exists to answer.
+      if (args.deep && plugin.observeResourcesDeep) {
         const deep = await deepDiffForLexicon(plugin, {
           environment,
           buildOutput,

package/src/cli/main.ts

@@ -593,6 +593,11 @@ Lifecycle (alias: lc):
                             property-level drift; --update-baseline records
                             what it reports as accepted so it stops alerting)
   lifecycle plan <env>      Typed change set (create/update/delete/adopt) vs live
+                            --deep: also report properties declared
+                            heldElsewhere(). Never changes what the plan
+                            proposes; costs a provider call pair per readable
+                            resource, so the read's cost becomes a function of
+                            estate size rather than stack count (#2405)
   lifecycle affected        Stacks a change affects (--base <ref> [--include-dependents])
                             --json: emit the ChangeSet as JSON
   lifecycle whoami <env>    Who chant would act as in each configured lexicon,

package/src/discovery/import.test.ts

@@ -1,9 +1,10 @@
 import { describe, test, expect } from "vitest";
-import { importModule } from "./import";
+import { importModule, resetImportFailures } from "./import";
+import { discover } from "./index";
 import { DiscoveryError } from "../errors";
 import { withTestDir, expectToThrow } from "@intentius/chant-test-utils";
 import { writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 
 describe("importModule", () => {
 
@@ -198,3 +199,110 @@ describe("importModule", () => {
     });
   });
 });
+
+describe("a module whose evaluation threw stays thrown (#2368)", () => {
+  /**
+   * The spec records an evaluation failure on the module record and re-throws
+   * it on every later import, forever. Node does that; vitest's module runner
+   * does not, and hands the second importer a namespace holding whatever was
+   * initialized before the throw.
+   *
+   * These assert the contract directly. They do not reproduce the runner bug —
+   * a module written to a temp directory is outside vitest's transform root and
+   * is imported by Node, which already records the failure. The reproduction is
+   * the corpus-backed test at the bottom of this file, which is the one that
+   * fails without the failure map.
+   */
+  test("a second import throws the same error, not a half-initialized namespace", async () => {
+    await withTestDir(async (testDir) => {
+      const filePath = join(testDir, "throws.ts");
+      await writeFile(filePath, `const o = undefined as unknown as { k: string };\nexport const value = o.k;\n`);
+
+      const first = await expectToThrow(() => importModule(filePath), DiscoveryError);
+      const second = await expectToThrow(() => importModule(filePath), DiscoveryError);
+
+      expect(second.message).toBe(first.message);
+      expect(second.file).toBe(filePath);
+      // The same error object, because it is the recorded one being replayed
+      // rather than a second failure that happened to look alike.
+      expect(second).toBe(first);
+    });
+  });
+
+  test("a third and fourth import keep throwing", async () => {
+    await withTestDir(async (testDir) => {
+      const filePath = join(testDir, "throws-again.ts");
+      await writeFile(filePath, `const o = undefined as unknown as { k: string };\nexport const value = o.k;\n`);
+
+      await expectToThrow(() => importModule(filePath), DiscoveryError);
+      await expectToThrow(() => importModule(filePath), DiscoveryError);
+      await expectToThrow(() => importModule(filePath), DiscoveryError);
+      await expectToThrow(() => importModule(filePath), DiscoveryError);
+    });
+  });
+
+  test("a module that imports cleanly is unaffected and is not cached as failed", async () => {
+    await withTestDir(async (testDir) => {
+      const filePath = join(testDir, "fine.ts");
+      await writeFile(filePath, `export const value = "ok";\n`);
+
+      const a = await importModule(filePath);
+      const b = await importModule(filePath);
+      expect(a.value).toBe("ok");
+      expect(b.value).toBe("ok");
+    });
+  });
+
+  test("resetImportFailures forgets the record, and does not make the module re-evaluate", async () => {
+    await withTestDir(async (testDir) => {
+      const filePath = join(testDir, "throws-reset.ts");
+      await writeFile(filePath, `const o = undefined as unknown as { k: string };\nexport const value = o.k;\n`);
+
+      const first = await expectToThrow(() => importModule(filePath), DiscoveryError);
+      resetImportFailures();
+
+      // Under Node the registry still holds the failed record and throws
+      // again; under vitest the module is served from its cache. Either way
+      // the escape hatch only clears chant's memory, which is what its doc
+      // says — so this asserts the clearing, not a re-evaluation.
+      let replayedSameObject = false;
+      try {
+        await importModule(filePath);
+      } catch (err) {
+        replayedSameObject = err === first;
+      }
+      expect(replayedSameObject).toBe(false);
+    });
+  });
+});
+
+describe("discover() reports the same errors on a second pass (#2368)", () => {
+  /**
+   * The reproduction from the issue, over the corpus entry that exposed it.
+   *
+   * It has to be a file inside the project: vitest transforms and caches those,
+   * and it is that cache which forgets an evaluation failure. A module written
+   * to a temp directory outside the runner's root is imported by Node natively
+   * and already behaves correctly, so a fixture built with `withTestDir` would
+   * pass with or without the fix and prove nothing.
+   *
+   * `examples/fold-adversarial/src/nullish-property-read.ts` folds to a refusal
+   * and then throws a TypeError when the run path imports it (#2328). Before
+   * the failure map: `discover #1 errors=1`, `discover #2 errors=0`.
+   */
+  const ADVERSARIAL = resolve(import.meta.dirname, "../../../../examples/fold-adversarial/src");
+
+  test("the corpus entry with a throwing file reports it on every pass", async () => {
+    const first = await discover(ADVERSARIAL);
+    const second = await discover(ADVERSARIAL);
+    const third = await discover(ADVERSARIAL);
+
+    expect(first.errors.length).toBeGreaterThan(0);
+    expect(second.errors.length).toBe(first.errors.length);
+    expect(third.errors.length).toBe(first.errors.length);
+
+    const named = (r: { errors: unknown[] }): boolean =>
+      (r.errors[0] as { file?: string }).file?.endsWith("nullish-property-read.ts") === true;
+    expect(named(first) && named(second) && named(third)).toBe(true);
+  });
+});

package/src/discovery/import.ts

@@ -1,20 +1,68 @@
 import { DiscoveryError } from "../errors";
 
+/**
+ * Modules whose evaluation threw, and the error each threw with (#2368).
+ *
+ * The ES module spec says an evaluation failure is recorded on the module
+ * record and re-thrown on every later import of the same specifier, forever,
+ * in that realm. Node implements it — including after the file is edited, so a
+ * module that threw keeps throwing until the process restarts.
+ *
+ * Vitest's module runner does not. It caches the module as *evaluated* and
+ * hands later importers a namespace carrying whichever bindings were
+ * initialized before the throw, so the second import resolves with
+ * half-initialized exports and no error at all.
+ *
+ * That divergence is invisible to `chant build`, which imports a directory
+ * once per process, and highly visible to anything that builds the same
+ * directory twice and compares: whichever build ran first carried the error
+ * and every build after it reported none, so error parity came out of the
+ * ordering rather than out of the tool.
+ *
+ * This map is what makes the answer the same either way. Under Node it never
+ * fires — `import()` throws again before the lookup matters — so it costs
+ * nothing and changes nothing there. Under a runner that forgets, it supplies
+ * the memory the spec requires.
+ */
+const evaluationFailures = new Map<string, DiscoveryError>();
+
+/**
+ * Forget every recorded evaluation failure.
+ *
+ * For a harness that deliberately starts a fresh module graph and wants the
+ * failures forgotten with it. Nothing in chant calls this: a real build
+ * imports once, and a second import inside one process is supposed to see what
+ * the first one saw.
+ *
+ * It does not make a module re-evaluate. Node's own registry still holds the
+ * failed record and still re-throws; this only clears chant's memory of it. A
+ * caller wanting genuine re-evaluation needs a fresh process.
+ */
+export function resetImportFailures(): void {
+  evaluationFailures.clear();
+}
+
 /**
  * Dynamically import a module and return its exports.
  *
  * @param path - The file path to import
  * @returns The module exports
- * @throws {DiscoveryError} with type "import" if the import fails
+ * @throws {DiscoveryError} with type "import" if the import fails, including
+ *   on every later import of a module whose evaluation has already failed
  */
 export async function importModule(
   path: string
 ): Promise<Record<string, unknown>> {
+  const failed = evaluationFailures.get(path);
+  if (failed) throw failed;
+
   try {
     return await import(path);
   } catch (error) {
     const message =
       error instanceof Error ? error.message : "Unknown import error";
-    throw new DiscoveryError(path, message, "import");
+    const discoveryError = new DiscoveryError(path, message, "import");
+    evaluationFailures.set(path, discoveryError);
+    throw discoveryError;
   }
 }