@intentius/chant 0.19.1 → 0.21.0

package/src/cli/commands/build.ts

@@ -1,13 +1,14 @@
 import { build } from "../../build";
-import { loadChantConfig, resolveOwnershipMarker } from "../../config";
+import { loadChantConfig, resolveOwnershipMarker, resolveFoldEnabled, resolveSandboxEnabled } from "../../config";
+import { resolveBuildParams } from "../../build-params";
 import type { Serializer, SerializerResult } from "../../serializer";
 import type { LexiconPlugin } from "../../lexicon";
 import { runPostSynthChecks } from "../../lint/post-synth";
 import { loadPolicyChecks } from "../../lint/policy";
 import { sortedJsonReplacer } from "../../utils";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
-import { writeFileSync, mkdirSync } from "fs";
-import { resolve, dirname, join } from "path";
+import { writeFileSync, mkdirSync, readFileSync } from "fs";
+import { resolve, dirname, join, relative } from "path";
 import { watchDirectory, formatTimestamp, formatChangedFiles } from "../watch";
 
 /**
@@ -32,6 +33,38 @@ export interface BuildOptions {
    * policy can branch on environment.
    */
   env?: string;
+  /**
+   * chant #1022 (epic #1019) — opt-in: fold source modules statically
+   * instead of importing/running them (`chant build --fold`). Falls back to
+   * run per-file for anything the folder can't represent. Merged with the
+   * project's `chant.config.ts` `build.fold` via {@link resolveFoldEnabled}
+   * — this flag, when true, always wins for the invocation.
+   */
+  fold?: boolean;
+
+  /**
+   * chant #1045 Phase 2 — opt-in: run-fallback source files (or, without
+   * `fold`, every file) execute together, isolated, in one sandboxed child
+   * process (`chant build --sandbox`). Merged with the project's
+   * `chant.config.ts` `build.sandbox` via {@link resolveSandboxEnabled} —
+   * this flag, when true, always wins for the invocation.
+   */
+  sandbox?: boolean;
+
+  /**
+   * chant #1064 — `--param name=value` flags (repeatable), parsed to a flat
+   * `{ name: value }` record of raw (unvalidated) strings. Highest
+   * precedence in {@link resolveBuildParams}'s resolution against the
+   * project's declared `chant.config.ts` `buildParams`.
+   */
+  params?: Record<string, string>;
+
+  /**
+   * chant #1064 — `--params-file <path>`: a JSON file of `{ "name": value }`
+   * build-time parameter values, read and parsed here. Second precedence,
+   * after {@link params}.
+   */
+  paramsFile?: string;
 }
 
 /**
@@ -81,6 +114,8 @@ export interface BuildResult {
   errors: string[];
   /** Warning messages */
   warnings: string[];
+  /** This build's resolved build-time parameters (#1064) — see `BuildResult.buildParams` (../../build.ts). Empty when the project declares/supplies none. */
+  buildParams?: import("../../provenance").BuildParamProvenance[];
 }
 
 /**
@@ -110,12 +145,84 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
     ? await loadPolicyChecks(config.lint.policies, configDir)
     : [];
 
+  // #1022 — opt-in fold path: the CLI flag wins over `chant.config.ts`'s
+  // `build.fold`, which wins over the (unchanged) default of running every
+  // module.
+  const fold = resolveFoldEnabled(config, options.fold);
+
+  // #1045 Phase 2 — opt-in sandboxed execution of run-fallback files (or,
+  // without --fold, every file). Same CLI-flag-wins-over-config precedence
+  // as fold, resolved independently.
+  const sandbox = resolveSandboxEnabled(config, options.sandbox);
+
+  // #1064 — resolve declared build-time parameters (chant.config.ts's
+  // buildParams) against this invocation's --param/--params-file/declared
+  // env mapping, BEFORE calling build() — a resolution failure (an unknown
+  // name, a missing required value, a type/enum mismatch) is reported as a
+  // chant build error naming the parameter, never a thrown error from inside
+  // user source (which is what loomster's hand-rolled `tierFromEnv()`-style
+  // validators did before migrating to this mechanism).
+  let paramsFileContent: Record<string, unknown> | undefined;
+  if (options.paramsFile) {
+    try {
+      paramsFileContent = JSON.parse(readFileSync(resolve(options.paramsFile), "utf-8"));
+    } catch (err) {
+      errors.push(
+        formatError({
+          message: `Failed to read/parse --params-file "${options.paramsFile}": ${err instanceof Error ? err.message : String(err)}`,
+        }),
+      );
+    }
+  }
+  const paramsResolution = resolveBuildParams(config.buildParams, {
+    cli: options.params,
+    fromFile: paramsFileContent,
+    env: process.env,
+  });
+  for (const message of paramsResolution.errors) {
+    errors.push(formatError({ message }));
+  }
+  if (errors.length > 0) {
+    return { success: false, resourceCount: 0, fileCount: 0, errors, warnings };
+  }
+  // #1064 — build-provenance visibility: report every resolved build-time
+  // parameter (name, value, and which source won it) the same
+  // unconditional-log-not-gated-on---verbose way #1022's fold decisions are
+  // reported just below, so a build's environment-varying inputs are as
+  // visible as its fold-vs-run choices.
+  for (const p of paramsResolution.provenance) {
+    console.error(formatInfo(`[param] ${p.name} = ${JSON.stringify(p.value)} (${p.source})`));
+  }
+
+  // #1039 — thread each loaded plugin's registered intrinsics (e.g. AWS's
+  // `Sub`) through to the fold path, so a file using a registered intrinsic
+  // tagged template folds instead of unconditionally falling back to run.
+  // `intrinsics` is an optional plugin extension (not every lexicon defines
+  // any), hence the guard.
+  const intrinsics = options.plugins?.flatMap((plugin) => plugin.intrinsics?.() ?? []) ?? [];
+
   // Run the build
   const result = await build(infraPath, options.serializers, undefined, {
     ownership,
     config: config as unknown as Record<string, unknown>,
+    fold,
+    sandbox,
+    intrinsics,
+    buildParams: paramsResolution.provenance,
   });
 
+  // #1022 — report per-file fold vs run so it's visible what still runs.
+  if (fold) {
+    for (const decision of result.foldDecisions) {
+      const rel = relative(infraPath, decision.file) || decision.file;
+      const detail =
+        decision.mode === "fold"
+          ? `${decision.resourceCount ?? 0} resource(s), no module execution`
+          : (decision.reason ?? "fell back to run");
+      console.error(formatInfo(`[fold:${decision.mode}] ${rel} — ${detail}`));
+    }
+  }
+
   // Format errors
   for (const error of result.errors) {
     const formatted = formatError({
@@ -359,6 +466,7 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
     fileCount,
     errors,
     warnings,
+    buildParams: paramsResolution.provenance,
   };
 }
 

package/src/cli/commands/check-lexicon-examples.test.ts

@@ -0,0 +1,92 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { checkExamplesBuild } from "./check-lexicon-examples";
+
+/**
+ * chant #1067 — proof that "every shipped example builds" actually builds
+ * one, rather than counting example directories the way every prior
+ * check-lexicon.ts check did. The fixture reproduces the exact defect
+ * found in `lexicons/aws/examples/core-concepts`: two files in the same
+ * example independently exporting a top-level binding of the same name,
+ * which is fine on its own but a "Duplicate export name" discovery error
+ * the moment the whole `src/` directory is built as one project — which is
+ * exactly what each example's own `npm run build` does.
+ *
+ * These fixtures import the real, already-installed `@intentius/chant-lexicon-aws`
+ * package (workspace-linked), so no lexicon plugin needs to be faked.
+ */
+
+function writeLexiconDirWithExample(
+  lexiconDir: string,
+  exampleName: string,
+  files: Record<string, string>,
+): void {
+  const srcDir = join(lexiconDir, "examples", exampleName, "src");
+  mkdirSync(srcDir, { recursive: true });
+  for (const [name, content] of Object.entries(files)) {
+    writeFileSync(join(srcDir, name), content);
+  }
+}
+
+describe("checkExamplesBuild", () => {
+  let dir: string;
+
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), "chant-check-lexicon-examples-"));
+  });
+  afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+  test("a clean example builds", async () => {
+    writeLexiconDirWithExample(dir, "clean", {
+      "bucket.ts": `import { Bucket } from "@intentius/chant-lexicon-aws";
+
+export const appBucket = new Bucket({
+  BucketName: "my-app-bucket",
+});
+`,
+    });
+
+    const results = await checkExamplesBuild(dir);
+    const clean = results.find((r) => r.example === "clean");
+    expect(clean).toMatchObject({ ok: true });
+  });
+
+  test("two files independently exporting the same top-level name fails to build (the core-concepts defect)", async () => {
+    writeLexiconDirWithExample(dir, "broken", {
+      "a.ts": `import { Bucket } from "@intentius/chant-lexicon-aws";
+
+export const dataBucket = new Bucket({
+  BucketName: "a-bucket",
+});
+`,
+      "b.ts": `import { Bucket } from "@intentius/chant-lexicon-aws";
+
+export const dataBucket = new Bucket({
+  BucketName: "b-bucket",
+});
+`,
+    });
+
+    const results = await checkExamplesBuild(dir);
+    const broken = results.find((r) => r.example === "broken");
+    expect(broken?.ok).toBe(false);
+    expect(broken?.detail).toMatch(/Duplicate export name "dataBucket" found/);
+  });
+
+  test("an empty src/ directory is skipped, not reported as a failure", async () => {
+    writeLexiconDirWithExample(dir, "empty", {});
+    const results = await checkExamplesBuild(dir);
+    expect(results.find((r) => r.example === "empty")).toBeUndefined();
+  });
+
+  test("returns [] when there is no examples/ directory at all", async () => {
+    const noExamplesDir = mkdtempSync(join(tmpdir(), "chant-check-lexicon-examples-none-"));
+    try {
+      expect(await checkExamplesBuild(noExamplesDir)).toEqual([]);
+    } finally {
+      rmSync(noExamplesDir, { recursive: true, force: true });
+    }
+  });
+});

package/src/cli/commands/check-lexicon-examples.ts

@@ -0,0 +1,103 @@
+/**
+ * "Every shipped example builds" (chant #1067).
+ *
+ * `check-lexicon.ts`'s existing example checks only count directories
+ * ("At least 1 example", "At least 3 examples", "At least 5 examples with
+ * tests") — nothing ever tries to build one. `lexicons/aws/examples/core-concepts`
+ * shipped with a discovery-time error (two files independently exporting a
+ * top-level `dataBucket`) and `chant dev check-lexicon lexicons/aws` still
+ * reported "All tier-1 checks passed," because none of its 29 checks touch
+ * build output. This module closes that gap directly: for every non-empty
+ * `examples/<name>/src/` directory, run the same discover-and-serialize
+ * pipeline `chant build` runs and report whether it produced output with no
+ * structural error.
+ *
+ * Scope, deliberately: "builds" here means discovery + serialization
+ * succeed (no `DiscoveryError`/`BuildError`, real output produced) — the
+ * same thing a `Duplicate export name` failure blocks. It does not
+ * additionally require the output to pass every post-synth/lint check
+ * (WAW0xx and friends). Those are a separate, already-gated contract
+ * (`chant lint`, the post-synth pipeline) with their own severity model and
+ * their own CI step; several existing AWS examples (docs-snippets,
+ * lambda-api, lambda-s3, shared-alb) currently fail one or more post-synth
+ * checks for reasons unrelated to this issue (e.g. WAW042, a TLS-only
+ * bucket policy check added after those examples were written). Folding
+ * that axis into "does it build" would fail this new check for all of them
+ * on its very first run, for defects this issue never set out to fix.
+ * Tracked separately; not silently absorbed here.
+ */
+
+import { existsSync, readdirSync } from "fs";
+import { join } from "path";
+import { build } from "../../build";
+import { findInfraFiles } from "../../discovery/files";
+import { detectLexicons } from "../../detectLexicon";
+import { loadPlugins } from "../plugins";
+
+export interface ExampleBuildResult {
+  example: string;
+  ok: boolean;
+  detail?: string;
+}
+
+/**
+ * Build every non-empty example under `<lexiconDir>/examples/*\/src` and
+ * report per-example pass/fail. Returns `[]` when the lexicon has no
+ * `examples/` directory at all (a separate tier-1 check already covers
+ * that).
+ */
+export async function checkExamplesBuild(lexiconDir: string): Promise<ExampleBuildResult[]> {
+  const examplesDir = join(lexiconDir, "examples");
+  if (!existsSync(examplesDir)) return [];
+
+  const results: ExampleBuildResult[] = [];
+  const entries = readdirSync(examplesDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+
+  for (const entry of entries) {
+    const srcDir = join(examplesDir, entry.name, "src");
+    if (!existsSync(srcDir)) continue;
+
+    const contents = readdirSync(srcDir);
+    if (contents.length === 0 || (contents.length === 1 && contents[0] === ".gitkeep")) continue;
+
+    try {
+      const files = await findInfraFiles(srcDir);
+      if (files.length === 0) continue;
+
+      const lexiconNames = await detectLexicons(files);
+      if (lexiconNames.length === 0) {
+        results.push({
+          example: entry.name,
+          ok: false,
+          detail: "no lexicon imports detected in src/ — cannot determine which plugin(s) to build with",
+        });
+        continue;
+      }
+
+      const plugins = await loadPlugins(lexiconNames);
+      const result = await build(srcDir, plugins.map((p) => p.serializer));
+
+      const structuralErrors = result.errors.map((e) => e.message);
+      const producedOutput = result.outputs.size > 0;
+      const ok = structuralErrors.length === 0 && producedOutput;
+
+      results.push({
+        example: entry.name,
+        ok,
+        detail: ok
+          ? undefined
+          : structuralErrors.length > 0
+            ? structuralErrors.join("; ")
+            : "discovered source but produced no output",
+      });
+    } catch (err) {
+      results.push({
+        example: entry.name,
+        ok: false,
+        detail: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  return results;
+}

package/src/cli/commands/check-lexicon-intrinsics.test.ts

@@ -0,0 +1,179 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { auditIntrinsics } from "./check-lexicon-intrinsics";
+
+/**
+ * chant #1067 — proof that the intrinsic-foldability audit actually
+ * validates, rather than just counting. Each case here is a small,
+ * synthetic lexicon (plugin.ts + index.ts + intrinsics.ts) so the
+ * fixtures encode the exact failure shapes #1039 shipped: a genuine
+ * tagged template registered with the wrong `isTag`, and a plain call
+ * registered with the wrong `isTag`, in both directions — plus a
+ * registration naming something the package never exports.
+ */
+
+function writeFixture(dir: string): void {
+  mkdirSync(join(dir, "src"), { recursive: true });
+
+  writeFileSync(
+    join(dir, "src/plugin.ts"),
+    `export const testPlugin = {
+  name: "test",
+  intrinsics() {
+    return [
+      { name: "Tag1", description: "a genuine tagged template", isTag: true },
+      { name: "Plain1", description: "a genuine plain call", isTag: false },
+      { name: "Mismatch1", description: "claims tag but is a plain call", isTag: true },
+      { name: "Mismatch2", description: "claims plain but is a tagged template", isTag: false },
+      { name: "Missing1", description: "registered but never exported", isTag: false },
+      { name: "Plain2", description: "a plain call opted into call-form folding", isTag: false, foldsAsCall: true },
+      { name: "Tag2", description: "a tagged template wrongly opted into call-form folding", isTag: true, foldsAsCall: true },
+    ];
+  },
+};
+`,
+  );
+
+  writeFileSync(
+    join(dir, "src/index.ts"),
+    `export { Tag1, Plain1, Mismatch1, Mismatch2, Plain2, Tag2 } from "./intrinsics";
+`,
+  );
+
+  writeFileSync(
+    join(dir, "src/intrinsics.ts"),
+    `export function Tag1(strings: TemplateStringsArray, ...values: unknown[]): string {
+  return strings.join("");
+}
+
+export function Plain1(x: string): string {
+  return x;
+}
+
+// Registered as isTag: true above — this is the #1039 "aws Sub" shape,
+// inverted: a plain call wrongly claimed as a tag.
+export function Mismatch1(x: string): string {
+  return x;
+}
+
+// Registered as isTag: false above — this is the #1039 "gitlab reference()"
+// shape: a genuine tagged template wrongly claimed as a plain call.
+export function Mismatch2(strings: TemplateStringsArray, ...values: unknown[]): string {
+  return strings.join("");
+}
+
+export function Plain2(x: string): string {
+  return x;
+}
+
+// chant #1044 — registered with foldsAsCall: true above, but authored as a
+// tagged template, so there is no plain-call form to opt in.
+export function Tag2(strings: TemplateStringsArray, ...values: unknown[]): string {
+  return strings.join("");
+}
+`,
+  );
+}
+
+describe("auditIntrinsics", () => {
+  let dir: string;
+
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), "chant-check-lexicon-intrinsics-"));
+    writeFixture(dir);
+  });
+  afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+  test("a genuine tagged template registered as isTag: true passes", () => {
+    const items = auditIntrinsics(dir);
+    const item = items.find((i) => i.name === "Tag1");
+    expect(item).toMatchObject({ exported: true, actualIsTag: true, ok: true });
+  });
+
+  test("a genuine plain call registered as isTag: false passes", () => {
+    const items = auditIntrinsics(dir);
+    const item = items.find((i) => i.name === "Plain1");
+    expect(item).toMatchObject({ exported: true, actualIsTag: false, ok: true });
+  });
+
+  test("a plain call wrongly registered as isTag: true fails (aws Sub shape, inverted)", () => {
+    const items = auditIntrinsics(dir);
+    const item = items.find((i) => i.name === "Mismatch1");
+    expect(item?.ok).toBe(false);
+    expect(item?.exported).toBe(true);
+    expect(item?.actualIsTag).toBe(false);
+    expect(item?.detail).toMatch(/plain call.*but registered with isTag: true/);
+  });
+
+  test("a tagged template wrongly registered as isTag: false fails (gitlab reference() shape)", () => {
+    const items = auditIntrinsics(dir);
+    const item = items.find((i) => i.name === "Mismatch2");
+    expect(item?.ok).toBe(false);
+    expect(item?.exported).toBe(true);
+    expect(item?.actualIsTag).toBe(true);
+    expect(item?.detail).toMatch(/authored as a tagged template.*isTag: false/);
+  });
+
+  test("a registered intrinsic that isn't exported fails, distinctly from a signature mismatch", () => {
+    const items = auditIntrinsics(dir);
+    const item = items.find((i) => i.name === "Missing1");
+    expect(item?.exported).toBe(false);
+    expect(item?.ok).toBe(false);
+    expect(item?.detail).toMatch(/not exported from src\/index\.ts/);
+  });
+
+  test("a plain call opted into call-form folding passes (chant #1044)", () => {
+    const items = auditIntrinsics(dir);
+    const item = items.find((i) => i.name === "Plain2");
+    expect(item).toMatchObject({ exported: true, actualIsTag: false, ok: true, declaredFoldsAsCall: true, callFormOk: true });
+  });
+
+  test("a tagged template registered with foldsAsCall: true fails — the opt-in is for plain calls only (chant #1044)", () => {
+    const items = auditIntrinsics(dir);
+    const item = items.find((i) => i.name === "Tag2");
+    // The isTag half is fine (it really is a tag); the call-form half is not.
+    expect(item?.ok).toBe(true);
+    expect(item?.callFormOk).toBe(false);
+    expect(item?.callFormDetail).toMatch(/authored as a tagged template.*foldsAsCall: true/);
+  });
+
+  test("an intrinsic with no foldsAsCall at all is simply not opted in — absent, not false (chant #1044)", () => {
+    const items = auditIntrinsics(dir);
+    const item = items.find((i) => i.name === "Plain1");
+    expect(item?.declaredFoldsAsCall).toBeUndefined();
+    expect(item?.callFormOk).toBe(true);
+  });
+
+  test("returns [] for a lexicon with no intrinsics() method", () => {
+    const emptyDir = mkdtempSync(join(tmpdir(), "chant-check-lexicon-intrinsics-empty-"));
+    try {
+      mkdirSync(join(emptyDir, "src"), { recursive: true });
+      writeFileSync(join(emptyDir, "src/plugin.ts"), `export const testPlugin = { name: "test" };\n`);
+      expect(auditIntrinsics(emptyDir)).toEqual([]);
+    } finally {
+      rmSync(emptyDir, { recursive: true, force: true });
+    }
+  });
+
+  test("returns [] for a lexicon whose intrinsics() legitimately registers none (gcp/k8s shape)", () => {
+    const emptyArrayDir = mkdtempSync(join(tmpdir(), "chant-check-lexicon-intrinsics-emptyarray-"));
+    try {
+      mkdirSync(join(emptyArrayDir, "src"), { recursive: true });
+      writeFileSync(
+        join(emptyArrayDir, "src/plugin.ts"),
+        `export const testPlugin = {
+  name: "test",
+  intrinsics() {
+    return [];
+  },
+};
+`,
+      );
+      expect(auditIntrinsics(emptyArrayDir)).toEqual([]);
+    } finally {
+      rmSync(emptyArrayDir, { recursive: true, force: true });
+    }
+  });
+});