@intentius/chant 0.19.1 → 0.20.0

package/src/build.ts

@@ -1,12 +1,16 @@
 import type { Declarable } from "./declarable";
 import type { Serializer, SerializerResult } from "./serializer";
 import type { OwnershipMarker } from "./ownership";
-import type { DiscoveryError, BuildError } from "./errors";
-import { BuildError as BuildErrorClass } from "./errors";
+import type { BuildError, DiscoveryErrorType } from "./errors";
+import type { IntrinsicDef } from "./lexicon";
+import type { BuildParamProvenance } from "./provenance";
+import { DiscoveryError, BuildError as BuildErrorClass } from "./errors";
 import { LexiconOutput, isLexiconOutput } from "./lexicon-output";
 import { AttrRef } from "./attrref";
 import { isChildProject, type ChildProjectInstance } from "./child-project";
-import { discover } from "./discovery/index";
+import { discover, type DiscoveryResult, type FoldDecision } from "./discovery/index";
+import { decodeEntitySet, type DiscoveredEntitiesJson } from "./discovery/entity-wire";
+import { buildDependencyGraph } from "./discovery/graph";
 import { topologicalSort } from "./sort";
 import { resolve } from "node:path";
 
@@ -149,6 +153,45 @@ export interface BuildOptions {
    * {@link SerializeContext} so a dialect can read its lexicon-scoped settings.
    */
   config?: Record<string, unknown>;
+
+  /**
+   * chant #1022 (epic #1019) — opt-in: fold source modules statically
+   * instead of importing/running them, falling back to run per-file for
+   * anything the folder can't represent. Default `false` (unchanged
+   * behavior). See {@link DiscoveryOptions.fold} in `./discovery/index`.
+   */
+  fold?: boolean;
+
+  /**
+   * chant #1039 — lexicon-registered intrinsic tags (e.g. AWS's `Sub`) to
+   * recognize while folding. Passed straight through to
+   * {@link DiscoveryOptions.intrinsics}; ignored unless {@link fold} is set.
+   * The CLI populates this from `options.plugins.flatMap(p => p.intrinsics?.() ?? [])`.
+   */
+  intrinsics?: IntrinsicDef[];
+
+  /**
+   * chant #1045 Phase 2 — opt-in: run-fallback files (or, when {@link fold}
+   * isn't set, every file) execute together, isolated, in one sandboxed
+   * child process instead of in-process. Passed straight through to
+   * {@link DiscoveryOptions.sandbox} in `./discovery/index`. Default `false`
+   * (unchanged behavior/performance).
+   */
+  sandbox?: boolean;
+
+  /**
+   * chant #1064 — this build's resolved build-time parameter values (see
+   * ./build-params.ts's `resolveBuildParams`, driven by the CLI's
+   * `--param`/`--params-file`/declared `env` mapping/`chant.config.ts`
+   * `buildParams` defaults). Threaded through to `discover()`, which
+   * populates `./params.ts`'s shared `params` object before any project file
+   * is imported or folded, and into the fold session so a `params.<name>`
+   * reference resolves to a literal. Passed through verbatim onto
+   * {@link BuildResult.buildParams} — `build()` itself does no
+   * declaration/validation (that's the CLI/config layer's job); it only
+   * carries the already-resolved records for provenance.
+   */
+  buildParams?: BuildParamProvenance[];
 }
 
 export interface BuildResult {
@@ -166,6 +209,20 @@ export interface BuildResult {
   manifest: BuildManifest;
   /** Number of source files processed */
   sourceFileCount: number;
+  /**
+   * Per-file fold-vs-run decisions (#1022). Empty unless
+   * {@link BuildOptions.fold} was set.
+   */
+  foldDecisions: FoldDecision[];
+
+  /**
+   * This build's resolved build-time parameters (#1064) — the build
+   * provenance record for `params.<name>` values, alongside the existing
+   * entity-level provenance (./provenance.ts). Passed through verbatim from
+   * {@link BuildOptions.buildParams}; empty when the project declares/
+   * supplies none.
+   */
+  buildParams: BuildParamProvenance[];
 }
 
 /**
@@ -451,13 +508,43 @@ export async function build(
   serializers: Serializer[],
   parentBuildStack?: Set<string>,
   options?: BuildOptions,
+): Promise<BuildResult> {
+  // Step 1: Discover entities and dependencies
+  const discoveryResult = await discover(path, {
+    fold: options?.fold,
+    intrinsics: options?.intrinsics,
+    sandbox: options?.sandbox,
+    buildParams: options?.buildParams,
+  });
+
+  return buildFromDiscoveryResult(discoveryResult, path, serializers, parentBuildStack, options);
+}
+
+/**
+ * chant #1045 (Phase 1) — build from a discovery result produced OUTSIDE the
+ * normal `discover(path)` call, i.e. decoded from {@link DiscoveredEntitiesJson}
+ * (see {@link buildFromEntitiesJson}). Everything from here on (topological
+ * sort, recursive child-project builds, partitioning, output detection,
+ * serialization, manifest) is exactly what `build()` already does after its
+ * own `discover()` call — extracted so the JSON path reuses it verbatim
+ * instead of forking it.
+ *
+ * @param resolvedPathForChildStack - Used only to seed the circular-nested-
+ *   stack detection (`buildStack`); the JSON path has no single directory a
+ *   decoded entity set came from, so callers without one may pass any stable
+ *   label (child projects aren't supported by the JSON boundary yet — see
+ *   `discovery/entity-wire.ts` — so this is inert for that path today).
+ */
+async function buildFromDiscoveryResult(
+  discoveryResult: DiscoveryResult,
+  resolvedPathForChildStack: string,
+  serializers: Serializer[],
+  parentBuildStack?: Set<string>,
+  options?: BuildOptions,
 ): Promise<BuildResult> {
   const warnings: string[] = [];
   const errors: Array<DiscoveryError | BuildError> = [];
 
-  // Step 1: Discover entities and dependencies
-  const discoveryResult = await discover(path);
-
   // Collect discovery errors
   errors.push(...discoveryResult.errors);
 
@@ -486,7 +573,7 @@ export async function build(
   }
 
   // Step 4: Recursively build child projects
-  const resolvedPath = resolve(path);
+  const resolvedPath = resolve(resolvedPathForChildStack);
   const buildStack = parentBuildStack
     ? new Set(parentBuildStack)
     : new Set<string>();
@@ -596,5 +683,55 @@ export async function build(
     errors,
     manifest,
     sourceFileCount: discoveryResult.sourceFiles.length,
+    foldDecisions: discoveryResult.foldDecisions,
+    buildParams: options?.buildParams ?? [],
   };
 }
+
+/**
+ * chant #1045 (Phase 1) — build directly from a JSON-encoded discovery
+ * result (see {@link discoverEntitySetJson} in `./discovery/entity-wire.ts`)
+ * instead of pointing `build()` at a directory.
+ *
+ * Decodes the wire entity set back into a live entities map — see
+ * `decodeEntitySet`'s doc for why the decoded entities are functionally
+ * indistinguishable from what `discover()` produces in-process (real
+ * `AttrRef` instances, whole-entity identity preserved by reference, not by
+ * clone) — then runs the exact same post-discovery pipeline `build()` uses
+ * ({@link buildFromDiscoveryResult}), so partitioning, output detection,
+ * serialization, and the manifest are the SAME code path, not a fork of it.
+ *
+ * Dependencies aren't part of the wire format: unlike entities, a dependency
+ * graph is plain name-to-name data with no identity problem, so it's cheaper
+ * and more honest to recompute it from the decoded entities via the same
+ * `buildDependencyGraph()` `discover()` itself uses than to carry a second,
+ * redundant wire shape across the boundary.
+ *
+ * @param label - Used only to seed circular-nested-stack detection; a JSON
+ *   entity set has no single source directory the way a `build(path, …)`
+ *   call does. Inert today — child projects (`nestedStack()`) aren't
+ *   supported by the JSON boundary yet (see `discovery/entity-wire.ts`).
+ */
+export async function buildFromEntitiesJson(
+  json: DiscoveredEntitiesJson,
+  serializers: Serializer[],
+  label = "<json-entity-set>",
+  parentBuildStack?: Set<string>,
+  options?: BuildOptions,
+): Promise<BuildResult> {
+  const entities = decodeEntitySet(json.entitySet);
+  const dependencies = buildDependencyGraph(entities);
+  const errors: DiscoveryError[] = json.errors.map(
+    (e) => new DiscoveryError(e.file, e.message, e.type as DiscoveryErrorType),
+  );
+
+  const discoveryResult: DiscoveryResult = {
+    entities,
+    dependencies,
+    sourceFiles: json.sourceFiles,
+    errors,
+    foldDecisions: json.foldDecisions,
+  };
+
+  return buildFromDiscoveryResult(discoveryResult, label, serializers, parentBuildStack, options);
+}

package/src/cli/commands/build.test.ts

@@ -1,11 +1,12 @@
-import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
 import { buildCommand, resolveBuildFormat, type BuildOptions } from "./build";
 import type { Serializer } from "../../serializer";
 import { parseYAML } from "../../yaml";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, dirname, resolve as resolvePath } from "node:path";
 import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
 
 describe("buildCommand", () => {
   let testDir: string;
@@ -133,6 +134,223 @@ export const testEntity = {
     expect(result.fileCount).toBeDefined();
   });
 
+  test("#1022 — --fold folds a leaf-only module and logs the fold decision", async () => {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const runtimePath = resolvePath(thisDir, "../../runtime");
+
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `
+    );
+    await writeFile(
+      join(testDir, "main.ts"),
+      `
+        import { Bucket } from "./resources";
+        throw new Error("must never execute — sentinel for #1022 fold verification");
+        export const bucket = new Bucket({ name: "my-bucket" });
+      `
+    );
+
+    const awsSerializer: Serializer = {
+      name: "aws",
+      rulePrefix: "TEST",
+      serialize: (entities) => JSON.stringify([...entities.keys()]),
+    };
+
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const result = await buildCommand({
+        path: testDir,
+        format: "json",
+        serializers: [awsSerializer],
+        fold: true,
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.resourceCount).toBe(1);
+
+      const loggedFoldLine = errorSpy.mock.calls
+        .map((call) => String(call[0]))
+        .some((line) => line.includes("[fold:fold]") && line.includes("main.ts"));
+      expect(loggedFoldLine).toBe(true);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  test("#1064 — a declared build-time parameter binds to params.<name> and folds to a literal", async () => {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const runtimePath = resolvePath(thisDir, "../../runtime");
+    const paramsPath = resolvePath(thisDir, "../../params");
+
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `
+        export default {
+          buildParams: {
+            tier: { type: "string", enum: ["light", "production"], default: "light" },
+          },
+        };
+      `,
+    );
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `,
+    );
+    await writeFile(
+      join(testDir, "main.ts"),
+      `
+        import { Bucket } from "./resources";
+        import { params } from ${JSON.stringify(paramsPath)};
+        throw new Error("must never execute — sentinel for #1064 fold verification");
+        export const bucket = new Bucket({ name: params.tier });
+      `,
+    );
+
+    const awsSerializer: Serializer = {
+      name: "aws",
+      rulePrefix: "TEST",
+      serialize: (entities) => JSON.stringify([...entities.values()].map((e) => (e as unknown as { props: unknown }).props)),
+    };
+
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const result = await buildCommand({
+        path: testDir,
+        format: "json",
+        serializers: [awsSerializer],
+        fold: true,
+        params: { tier: "production" },
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.resourceCount).toBe(1);
+      expect(result.buildParams).toEqual([{ name: "tier", value: "production", source: "cli" }]);
+
+      const loggedParamLine = errorSpy.mock.calls
+        .map((call) => String(call[0]))
+        .some((line) => line.includes("[param] tier") && line.includes("production") && line.includes("cli"));
+      expect(loggedParamLine).toBe(true);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  test("#1064 — an unresolved required build-time parameter is a build error naming the parameter, not a thrown error", async () => {
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `
+        export default {
+          buildParams: { tier: { type: "string" } },
+        };
+      `,
+    );
+
+    const result = await buildCommand({
+      path: testDir,
+      format: "json",
+      serializers: [mockSerializer],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.errors.some((e) => e.includes('"tier"') && e.includes("--param"))).toBe(true);
+  });
+
+  test("#1064 — an enum violation is a build error naming the parameter and the allowed values", async () => {
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `
+        export default {
+          buildParams: { tier: { type: "string", enum: ["light", "production"] } },
+        };
+      `,
+    );
+
+    const result = await buildCommand({
+      path: testDir,
+      format: "json",
+      serializers: [mockSerializer],
+      params: { tier: "bogus" },
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.errors.some((e) => e.includes('"tier"') && e.includes("bogus"))).toBe(true);
+  });
+
+  test("#1064 — --params-file supplies values from a JSON file, second precedence after --param", async () => {
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `
+        export default {
+          buildParams: {
+            tier: { type: "string", default: "light" },
+            env: { type: "string", default: "dev" },
+          },
+        };
+      `,
+    );
+    await writeFile(
+      join(testDir, "test.infra.ts"),
+      `
+        export const testEntity = {
+          lexicon: "test",
+          entityType: "TestEntity",
+          [Symbol.for("chant.declarable")]: true,
+        };
+      `,
+    );
+    const paramsFilePath = join(testDir, "params.json");
+    await writeFile(paramsFilePath, JSON.stringify({ tier: "production", env: "from-file" }));
+
+    const result = await buildCommand({
+      path: testDir,
+      format: "json",
+      serializers: [mockSerializer],
+      params: { tier: "from-cli" },
+      paramsFile: paramsFilePath,
+    });
+
+    expect(result.success).toBe(true);
+    const byName = new Map((result.buildParams ?? []).map((p) => [p.name, p]));
+    expect(byName.get("tier")).toEqual({ name: "tier", value: "from-cli", source: "cli" });
+    expect(byName.get("env")).toEqual({ name: "env", value: "from-file", source: "params-file" });
+  });
+
+  test("--fold is opt-in: omitting it builds via the unchanged run path", async () => {
+    await writeFile(
+      join(testDir, "test.infra.ts"),
+      `
+        export const testEntity = {
+          lexicon: "test",
+          entityType: "TestEntity",
+          [Symbol.for("chant.declarable")]: true,
+        };
+      `
+    );
+
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const result = await buildCommand({
+        path: testDir,
+        format: "json",
+        serializers: [mockSerializer],
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.resourceCount).toBe(1);
+      const anyFoldLine = errorSpy.mock.calls.map((call) => String(call[0])).some((line) => line.includes("[fold:"));
+      expect(anyFoldLine).toBe(false);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
   test("creates parent directories for the primary output path (#38)", async () => {
     // Write into a nested temp path whose parent dirs don't yet exist —
     // chant build should mkdir -p the parents rather than fail with ENOENT.

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 });
+    }
+  });
+});