@intentius/chant 0.57.0 → 0.59.0

package/src/cli/commands/carve-bridge.test.ts

@@ -5,6 +5,7 @@ import { tmpdir } from "os";
 import { join } from "path";
 import { carveBridge, formatCarveBridge } from "./carve-bridge";
 import { loadHcl2json } from "../../terraform/parse";
+import { registerCarveProvider } from "../../terraform/carve-provider";
 import { readCarveManifest, writeCarveManifest, type CarveManifest } from "../../terraform/manifest";
 
 let parserAvailable = false;
@@ -195,36 +196,258 @@ describe("carveBridge", () => {
     }
   });
 
-  test("refuses a target whose identity attribute is a dotted path (#2015)", async () => {
+  test("refuses a dotted-identity type no provider declares a shape for (#2015, #2034)", async () => {
     if (!parserAvailable) return;
-    const dir = mkdtempSync(join(tmpdir(), "chant-bridge-k8s-"));
+    // A dotted identity attribute is a path into nested values, and a data body
+    // is flat `attr = value` — `spec.metadata.name = "x"` is not valid HCL. The
+    // guard now turns on the missing shape, not on the dot, so the message says
+    // what would lift it.
+    const unregister = registerCarveProvider({
+      name: "carve-bridge-test-nested",
+      tfTypePrefixes: ["nested_"],
+      lexicon: "aws",
+      tiers: { nested_widget: { tier: 1, mapsTo: "Test::Widget" } },
+      identityAttrs: { nested_widget: "spec.metadata.name" },
+    });
+    const dir = mkdtempSync(join(tmpdir(), "chant-bridge-nested-"));
     try {
-      // `kubernetes_manifest` identifies itself by `manifest.metadata.name`.
-      // Rendering that into a data body produced `manifest.metadata.name = "x"`,
-      // which is not valid HCL — and the provider has no manifest data source.
       writeFileSync(
         join(dir, "main.tf"),
-        `resource "kubernetes_manifest" "demo" {\n` +
-          `  manifest = {\n` +
-          `    apiVersion = "v1"\n` +
-          `    kind       = "ConfigMap"\n` +
-          `    metadata = { name = "demo-config" }\n` +
-          `  }\n` +
-          `}\n`,
+        `resource "nested_widget" "demo" {\n  spec {\n    metadata {\n      name = "demo"\n    }\n  }\n}\n`,
       );
       const out = join(dir, "carveout");
-      const res = await carveBridge({ from: dir, select: "kubernetes_manifest.demo", output: out });
+      const res = await carveBridge({ from: dir, select: "nested_widget.demo", output: out });
 
       expect(res.ok).toBe(false);
       expect(res.error).toContain("cannot be bridged");
-      expect(res.error).toContain("manifest.metadata.name");
+      expect(res.error).toContain("spec.metadata.name");
+      expect(res.error).toContain("no carve provider declares a data-source shape for it");
+      expect(res.error).toContain("dataSourceShapes");
       expect(res.plan).toBeUndefined();
       expect(existsSync(out)).toBe(false);
+    } finally {
+      unregister();
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+});
+
+/**
+ * `kubernetes_manifest` reads back through a different type (#2034). The
+ * kubernetes provider ships no `kubernetes_manifest` data source — verified
+ * against hashicorp/kubernetes v3.2.1 — so the bridge renders
+ * `data "kubernetes_resource"` from the manifest's own apiVersion, kind and
+ * metadata, and repoints survivors at that data source's attribute path.
+ */
+describe("carveBridge — kubernetes_manifest (#2034)", () => {
+  const MANIFEST_TF = `resource "kubernetes_manifest" "app_config" {
+  manifest = {
+    apiVersion = "v1"
+    kind       = "ConfigMap"
+    metadata = {
+      name      = "app-config"
+      namespace = "apps"
+    }
+    data = {
+      LOG_LEVEL = "info"
+    }
+  }
+}
+`;
+  // Three shapes of inbound reference: the issue's own example, one deeper into
+  // `object`, and one through `manifest` — the attribute the data source does
+  // NOT have, which is why the rewrite maps it rather than only swapping heads.
+  const SURVIVOR_TF = `resource "kubernetes_config_map" "mirror" {
+  metadata {
+    name      = kubernetes_manifest.app_config.object.metadata.name
+    namespace = "apps"
+  }
+  data = {
+    LOG_LEVEL = kubernetes_manifest.app_config.manifest.data.LOG_LEVEL
+    UPSTREAM  = kubernetes_manifest.app_config.object.data.LOG_LEVEL
+  }
+}
+`;
+  const OUTPUTS_TF = `output "app_config_name" {
+  value = kubernetes_manifest.app_config.object.metadata.name
+}
+`;
+
+  async function withManifestEstate<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+    const dir = mkdtempSync(join(tmpdir(), "chant-bridge-manifest-"));
+    try {
+      writeFileSync(join(dir, "manifest.tf"), MANIFEST_TF);
+      writeFileSync(join(dir, "survivor.tf"), SURVIVOR_TF);
+      writeFileSync(join(dir, "outputs.tf"), OUTPUTS_TF);
+      return await fn(dir);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+
+  test("bridges to a data \"kubernetes_resource\" block built from the manifest body", async () => {
+    if (!parserAvailable) return;
+    await withManifestEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      const res = await carveBridge({ from: dir, select: "kubernetes_manifest.app_config", output: out });
+      expect(res.ok).toBe(true);
+
+      // The data source is the provider's generic read, not the carved type.
+      expect(res.plan!.dataSources).toHaveLength(1);
+      expect(res.plan!.dataSources[0]).toMatchObject({
+        address: "kubernetes_manifest.app_config",
+        type: "kubernetes_resource",
+        name: "app_config",
+      });
+      expect(res.plan!.dataSources[0].hcl).toBe(
+        `data "kubernetes_resource" "app_config" {\n` +
+          `  api_version = "v1"\n` +
+          `  kind        = "ConfigMap"\n` +
+          `\n` +
+          `  metadata {\n` +
+          `    name      = "app-config"\n` +
+          `    namespace = "apps"\n` +
+          `  }\n` +
+          `}`,
+      );
+      expect(formatCarveBridge(res)).toContain(
+        "data.kubernetes_resource.app_config  (was kubernetes_manifest.app_config)",
+      );
+    });
+  });
+
+  test("the emitted data source parses as HCL and is terraform-fmt clean", async () => {
+    if (!parserAvailable) return;
+    await withManifestEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      await carveBridge({ from: dir, select: "kubernetes_manifest.app_config", output: out });
+      const dsPath = join(out, "kubernetes_manifest-app_config-datasources.tf");
+      const hcl = readFileSync(dsPath, "utf-8");
+
+      // The repo's own parser: `metadata` has to come out as a block, since the
+      // provider declares it Block List (Min 1, Max 1), not an attribute.
+      const parsed = await (await loadHcl2json()).parse("datasources.tf", hcl);
+      const ds = (parsed.data as Record<string, Record<string, unknown[]>>).kubernetes_resource.app_config[0] as Record<
+        string,
+        unknown
+      >;
+      expect(ds.api_version).toBe("v1");
+      expect(ds.kind).toBe("ConfigMap");
+      expect(ds.metadata).toEqual([{ name: "app-config", namespace: "apps" }]);
+
+      // And Terraform's own formatter accepts it byte for byte.
+      try {
+        execFileSync("terraform", ["fmt", "-check", "-diff", dsPath], { stdio: "pipe" });
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") return; // no terraform on this machine
+        throw err;
+      }
+    });
+  });
+
+  test("survivor references follow the data source's own attribute path", async () => {
+    if (!parserAvailable) return;
+    await withManifestEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      const res = await carveBridge({ from: dir, select: "kubernetes_manifest.app_config", output: out });
+      expect(res.ok).toBe(true);
+
+      const survivor = readFileSync(join(out, "survivor.tf"), "utf-8");
+      // The issue's example, and a reference that goes deeper into `object`.
+      expect(survivor).toContain("name      = data.kubernetes_resource.app_config.object.metadata.name");
+      expect(survivor).toContain("UPSTREAM  = data.kubernetes_resource.app_config.object.data.LOG_LEVEL");
+      // `manifest` is an attribute of the resource that the data source does not
+      // have; left alone it would be an "Unsupported attribute" at validate.
+      expect(survivor).toContain("LOG_LEVEL = data.kubernetes_resource.app_config.object.data.LOG_LEVEL");
+      expect(survivor).not.toContain(".manifest.");
+      expect(survivor).not.toMatch(/(?<!data\.)\bkubernetes_manifest\.app_config\b/);
+
+      // An output reading the manifest is repointed the same way (#1638).
+      expect(res.plan!.outputRewrites).toEqual(["output.app_config_name"]);
+      expect(readFileSync(join(out, "outputs.tf"), "utf-8")).toContain(
+        "value = data.kubernetes_resource.app_config.object.metadata.name",
+      );
+
+      // The carved block leaves the survivor source, as for any other type.
+      expect(res.plan!.excised).toEqual(["kubernetes_manifest.app_config"]);
+      expect(readFileSync(join(out, "manifest.tf"), "utf-8").trim()).toBe("");
+    });
+  });
+
+  test("a namespace-less manifest omits the optional argument", async () => {
+    if (!parserAvailable) return;
+    const dir = mkdtempSync(join(tmpdir(), "chant-bridge-clusterwide-"));
+    try {
+      // A cluster-scoped kind has no namespace, and `metadata.namespace` is
+      // optional on the data source — so it is left out, not emitted empty.
+      writeFileSync(
+        join(dir, "main.tf"),
+        `resource "kubernetes_manifest" "reader" {\n` +
+          `  manifest = {\n` +
+          `    apiVersion = "rbac.authorization.k8s.io/v1"\n` +
+          `    kind       = "ClusterRole"\n` +
+          `    metadata = {\n` +
+          `      name = "reader"\n` +
+          `    }\n` +
+          `  }\n` +
+          `}\n`,
+      );
+      writeFileSync(
+        join(dir, "outputs.tf"),
+        `output "reader" {\n  value = kubernetes_manifest.reader.object.metadata.name\n}\n`,
+      );
+      const out = join(dir, "carveout");
+      const res = await carveBridge({ from: dir, select: "kubernetes_manifest.reader", output: out });
+      expect(res.ok).toBe(true);
+      const hcl = res.plan!.dataSources[0].hcl;
+      expect(hcl).toContain('api_version = "rbac.authorization.k8s.io/v1"');
+      expect(hcl).toContain('name = "reader"');
+      expect(hcl).not.toContain("namespace");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("an interpolated manifest name falls back to the TODO body, never a half-written block", async () => {
+    if (!parserAvailable) return;
+    const dir = mkdtempSync(join(tmpdir(), "chant-bridge-interp-"));
+    try {
+      writeFileSync(
+        join(dir, "main.tf"),
+        `variable "suffix" {\n  type = string\n}\n\n` +
+          `resource "kubernetes_manifest" "app_config" {\n` +
+          `  manifest = {\n` +
+          `    apiVersion = "v1"\n` +
+          `    kind       = "ConfigMap"\n` +
+          `    metadata = {\n` +
+          `      name = "app-\${var.suffix}"\n` +
+          `    }\n` +
+          `  }\n` +
+          `}\n`,
+      );
+      writeFileSync(
+        join(dir, "outputs.tf"),
+        `output "name" {\n  value = kubernetes_manifest.app_config.object.metadata.name\n}\n`,
+      );
+      const out = join(dir, "carveout");
+      const res = await carveBridge({ from: dir, select: "kubernetes_manifest.app_config", output: out });
+      expect(res.ok).toBe(true);
+      // `metadata.name` is required on the data source; guessing it would be
+      // worse than saying so.
+      expect(res.plan!.dataSources[0].hcl).toContain("# TODO: identify the resource");
+      expect(res.plan!.dataSources[0].hcl).not.toContain("api_version");
+      // The reference is still repointed, so the survivor plan is one edit away.
+      expect(readFileSync(join(out, "outputs.tf"), "utf-8")).toContain(
+        "value = data.kubernetes_resource.app_config.object.metadata.name",
+      );
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+});
 
+describe("carveBridge — formatting", () => {
   test("formatCarveBridge summarizes data sources, rewires, and safety", async () => {
     if (!parserAvailable) return;
     await withEstate(async (dir) => {

package/src/cli/commands/carve-bridge.ts

@@ -14,8 +14,8 @@ import { join, basename, relative, resolve } from "path";
 import { cdkNotSupported, isCloudAssembly } from "../../cdk/assembly";
 import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
 import { boundaryReport, type CarveReport } from "../../terraform/carve";
-import { generateBridge, type BridgePlan, type CarvedIdentity } from "../../terraform/bridge";
-import { identityAttrOf, canBridge } from "../../terraform/tier-map";
+import { generateBridge, type BridgePlan, type CarvedDataSource } from "../../terraform/bridge";
+import { identityAttrOf, canBridge, dataSourceShapeOf } from "../../terraform/tier-map";
 import { resolveCarveManifest, writeCarveManifest, type CarveManifest } from "../../terraform/manifest";
 import { newFileDiff, unifiedDiff } from "../../terraform/unified-diff";
 
@@ -76,13 +76,13 @@ export async function carveBridge(opts: CarveBridgeOptions): Promise<CarveBridge
     if (!found) return { ok: false, error: `${select} not found in ${opts.from}` };
     report = found;
 
-    // Refuse a carve set whose data source cannot be written as valid HCL: a
-    // dotted identity attribute is a path into nested blocks, and a data body
-    // is flat `attr = value`. `kubernetes_manifest` is the standing case — the
-    // provider has no `kubernetes_manifest` data source either; its generic
-    // read is `kubernetes_resource`, a different shape. Emit adopting the type
-    // (#999) does not lift this: reading a manifest out of state and reading it
-    // back through a data source are separate problems (#2034).
+    // Refuse a carve set no provider says how to read back. A dotted identity
+    // attribute is a path into nested values and a data body is flat
+    // `attr = value`, so such a type bridges only once its provider declares a
+    // data-source shape — the data type, its arguments and where each comes
+    // from in the carved body (#2034). `kubernetes_manifest` declares one now:
+    // `data "kubernetes_resource"`, built from the manifest's apiVersion,
+    // kind and metadata.
     const carvedTypes = report.carveSet.map((m) => m.type).filter((t): t is string => t !== undefined);
     const unbridgeable = [...new Set(carvedTypes.filter((t) => !canBridge(t)))];
     if (unbridgeable.length) {
@@ -91,21 +91,25 @@ export async function carveBridge(opts: CarveBridgeOptions): Promise<CarveBridge
         error:
           `${select} cannot be bridged: ${unbridgeable
             .map((t) => `${t} identifies itself by \`${identityAttrOf(t)}\``)
-            .join(", ")}, a path into nested blocks that a Terraform data source body cannot express. ` +
-          `Bridging these types needs a data-source mapping — see chant issue #2034.`,
+            .join(", ")}, a path into nested values that a flat Terraform data source body cannot express, ` +
+          `and no carve provider declares a data-source shape for it. A provider contributes one through ` +
+          `\`dataSourceShapes\` (see \`kubernetes_manifest\` reading back as \`data "kubernetes_resource"\`, chant issue #2034).`,
       };
     }
 
-    // Physical identities for the carved resources, for the data sources.
-    const identities = new Map<string, CarvedIdentity>();
+    // How each carved resource is read back, and the literals to render the
+    // data-source body from. The shape comes from the provider, the values from
+    // the parsed block (`dataSourceValues`, a superset of the old identity).
+    const readBacks = new Map<string, CarvedDataSource>();
     for (const node of graph.nodes) {
-      if (node.type && node.identity) {
-        identities.set(node.address, { attr: identityAttrOf(node.type), value: node.identity });
-      }
+      if (!node.type) continue;
+      const shape = dataSourceShapeOf(node.type);
+      if (!shape) continue;
+      readBacks.set(node.address, { shape, values: node.dataSourceValues ?? {} });
     }
 
     const files = listTfFiles(opts.from).map((path) => ({ path, content: readFileSync(path, "utf-8") }));
-    plan = generateBridge(report, files, identities);
+    plan = generateBridge(report, files, readBacks);
   } catch (err) {
     if (err instanceof Hcl2JsonNotInstalled) return { ok: false, error: err.message };
     return { ok: false, error: `Failed to build the bridge: ${err instanceof Error ? err.message : String(err)}` };

package/src/cli/commands/carve-emit-k8s.test.ts

@@ -239,24 +239,31 @@ describe("carve emit — kubernetes_manifest (#999)", () => {
     });
   });
 
-  test("bridge still refuses the carved manifest, so emit writes no half-bridged estate", async () => {
+  test("emit then bridge compose on the same manifest (#2034)", async () => {
     if (!parserAvailable) return;
     await withEstate(async (dir) => {
       const out = join(dir, "carveout");
       const emitted = await carveEmit(
-        { from: dir, select: "kubernetes_manifest.app_config", statePath: join(dir, "terraform.tfstate"), output: out },
+        { from: dir, select: "kubernetes_manifest.web_cert", statePath: join(dir, "terraform.tfstate"), output: out },
         { plugins: [], liveImport: fakeImport() },
       );
       expect(emitted.ok).toBe(true);
 
-      // Emit does not unlock bridge: `manifest.metadata.name` is a path into
-      // nested blocks and a data-source body is flat `attr = value`, so the
-      // survivors' references cannot be repointed yet.
-      const bridged = await carveBridge({ from: dir, select: "kubernetes_manifest.app_config", output: out });
-      expect(bridged.ok).toBe(false);
-      expect(bridged.error).toContain("cannot be bridged");
-      expect(bridged.error).toContain("manifest.metadata.name");
-      expect(existsSync(join(out, "kubernetes_manifest-app_config-runbook.md"))).toBe(false);
+      // Bridge used to refuse here: `manifest.metadata.name` is a path into the
+      // body, and a data-source body is flat `attr = value`. It now reads the
+      // manifest back through the shape the kubernetes provider declares, so
+      // the target the emit manifest recorded bridges without --select.
+      const bridged = await carveBridge({ from: dir, output: out });
+      expect(bridged.ok).toBe(true);
+      expect(bridged.plan!.target).toBe("kubernetes_manifest.web_cert");
+      expect(existsSync(join(out, "kubernetes_manifest-web_cert-runbook.md"))).toBe(true);
+
+      // Nothing reads the Certificate, so there is no data source to write —
+      // but its own block still has to leave the survivor source, or the next
+      // apply re-creates what `terraform state rm` released.
+      expect(bridged.plan!.dataSources).toEqual([]);
+      expect(bridged.plan!.excised).toEqual(["kubernetes_manifest.web_cert"]);
+      expect(readFileSync(join(out, "main.tf"), "utf-8")).not.toContain('resource "kubernetes_manifest" "web_cert"');
     });
   });
 });

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

@@ -4,7 +4,7 @@
  * The contract used to check documentation by counting files — "at least 1
  * .mdx page" at tier 1, "at least 8" at tier 2 — and never opened one. That
  * counts a page nothing links to exactly the same as a page a reader can
- * actually find, so azure, temporal, helm and github each accumulated
+ * actually find, so azure, helm and github each accumulated
  * hand-added pages that appear in no sidebar and are reachable only by typing
  * their URL. Azure's getting-started, resource reference and composites pages
  * were all invisible while its ≥8-page check passed comfortably — the count

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

@@ -119,7 +119,7 @@ export const plainBucket = new Bucket({
     const results = await checkExamplesBuild(dir);
     const insecure = results.find((r) => r.example === "insecure");
     expect(insecure?.ok).toBe(false);
-    expect(insecure?.detail).toMatch(/post-synth error\(s\) from the lexicon's own checks/);
+    expect(insecure?.detail).toMatch(/post-synth error\(s\)/);
     expect(insecure?.detail).toMatch(/WAW042: \[plainBucket\]/);
   });
 
@@ -141,6 +141,34 @@ export const plainBucket = new Bucket({
     expect(results.find((r) => r.example === "suppressed")).toMatchObject({ ok: true });
   });
 
+  // #2101 — the third axis: core's own Op-model checks run over the example's
+  // result too, so an example carrying an Op has it validated here rather
+  // than only when a user builds the example themselves. The Op below
+  // references a step whose activity has no registered contract anywhere,
+  // which is exactly what OPS013 exists to refuse.
+  test("an example whose Op fails core's own OPS checks fails (#2101)", async () => {
+    writeLexiconDirWithExample(dir, "bad-op", {
+      "bucket.ts": cleanBucketSource,
+      "broken.op.ts": `import { Op, phase, activity, stepOutput } from "@intentius/chant/op";
+
+export const brokenOp = Op({
+  name: "broken",
+  overview: "references a step nothing declares",
+  phases: [
+    phase("Run", [
+      activity("shellCmd", { cmd: stepOutput("nope", "value") }),
+    ]),
+  ],
+});
+`,
+    });
+
+    const results = await checkExamplesBuild(dir);
+    const badOp = results.find((r) => r.example === "bad-op");
+    expect(badOp?.ok).toBe(false);
+    expect(badOp?.detail).toMatch(/OPS013/);
+  });
+
   test("an empty src/ directory is skipped, not reported as a failure", async () => {
     writeLexiconDirWithExample(dir, "empty", {});
     const results = await checkExamplesBuild(dir);

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

@@ -23,6 +23,14 @@
  * diagnostic left at `error` severity fails the example. Warnings do not.
  * An example is what a user copies wholesale; it must not teach a pattern
  * the lexicon it demonstrates flags as an error.
+ *
+ * #2101 added the third axis: core's own Op-model checks (OPS012/OPS013/
+ * OPS014, `../../lint/rules/op/`) run over the same result, as `chant build`
+ * runs them, so an example carrying an Op has that Op validated here rather
+ * than only when a user builds the example themselves. They are given the
+ * activity contracts every loaded lexicon declares, resolved the same way
+ * `chant build` resolves them, so a step calling that lexicon's own activity
+ * validates against its own schemas.
  */
 
 import { existsSync, readdirSync } from "fs";
@@ -31,8 +39,11 @@ import { build, type BuildResult } from "../../build";
 import { findInfraFiles } from "../../discovery/files";
 import { detectLexicons } from "../../detectLexicon";
 import { loadChantConfig } from "../../config";
-import { loadPlugins } from "../plugins";
+import { loadPlugins, collectBuildRootContributors } from "../plugins";
 import { runPostSynthChecks, type PostSynthDiagnostic } from "../../lint/post-synth";
+import { coreOpChecks } from "../../lint/rules/op";
+import { loadActivityContracts } from "../../op/activity-contract-registry";
+import type { ActivityContract } from "../../op/activity-contract";
 import { applyConfiguredSeverity } from "../../lint/config";
 import type { LexiconPlugin } from "../../lexicon";
 import type { SerializerResult } from "../../serializer";
@@ -44,18 +55,31 @@ export interface ExampleBuildResult {
 }
 
 /**
- * Run each plugin's own post-synth checks against that plugin's output —
- * the same per-plugin scoping and `lint.rules` severity resolution
- * `cli/commands/build.ts` applies — and return what is left at `error`
- * severity. Project `lint.policies` are not run here: those are the
- * example author's organizational policy, not the lexicon's contract.
+ * Run core's Op-model checks over the whole result, then each plugin's own
+ * post-synth checks against that plugin's output — the same scoping and
+ * `lint.rules` severity resolution `cli/commands/build.ts` applies — and
+ * return what is left at `error` severity. Project `lint.policies` are not
+ * run here: those are the example author's organizational policy, not the
+ * lexicon's contract.
  */
 export function postSynthErrors(
   plugins: LexiconPlugin[],
   result: BuildResult,
   lintRules: Parameters<typeof applyConfiguredSeverity>[1],
+  activityContracts?: ReadonlyMap<string, ActivityContract>,
 ): PostSynthDiagnostic[] {
   const errors: PostSynthDiagnostic[] = [];
+
+  // Core's Op-model checks first (#2101). An Op is recognized by entity type,
+  // not by which lexicon declared it, so these run over the FULL result the
+  // way `chant build` runs them — unscoped, and regardless of which plugins
+  // loaded. Without this an example's Op reached output unvalidated, which is
+  // why the terraform, aws and render examples kept their Ops outside `src/`.
+  const opDiags = runPostSynthChecks(coreOpChecks(), result, undefined, { activityContracts });
+  for (const diag of applyConfiguredSeverity(opDiags, lintRules).diagnostics) {
+    if (diag.severity === "error") errors.push(diag);
+  }
+
   for (const plugin of plugins) {
     if (!plugin.postSynthChecks) continue;
     const checks = plugin.postSynthChecks();
@@ -66,7 +90,7 @@ export function postSynthErrors(
     const pluginOutput = result.outputs.get(outputKey);
     if (pluginOutput !== undefined) scopedOutputs.set(outputKey, pluginOutput);
 
-    const diags = runPostSynthChecks(checks, { ...result, outputs: scopedOutputs });
+    const diags = runPostSynthChecks(checks, { ...result, outputs: scopedOutputs }, undefined, { activityContracts });
     const { diagnostics } = applyConfiguredSeverity(diags, lintRules);
     for (const diag of diagnostics) {
       if (diag.severity === "error") errors.push(diag);
@@ -129,7 +153,15 @@ export async function checkExamplesBuild(lexiconDir: string): Promise<ExampleBui
       }
 
       const plugins = await loadPlugins(lexiconNames);
-      const result = await build(srcDir, plugins.map((p) => p.serializer));
+      // Bind each plugin's `buildRoots()` hook exactly as `chant build` does
+      // (#2083): a lexicon whose entities come from config-declared roots
+      // rather than typed source (k8s kustomize roots, terraform roots) has
+      // nothing to serialize otherwise, and its example would read as
+      // "produced no output" for a reason that is this harness's, not the
+      // example's.
+      const exampleDir = join(examplesDir, entry.name);
+      const buildRoots = collectBuildRootContributors(plugins, exampleConfig as Record<string, unknown>, exampleDir);
+      const result = await build(srcDir, plugins.map((p) => p.serializer), undefined, { buildRoots });
 
       const structuralErrors = result.errors.map((e) => e.message);
       const producedOutput = result.outputs.size > 0;
@@ -139,7 +171,7 @@ export async function checkExamplesBuild(lexiconDir: string): Promise<ExampleBui
       // already explains the failure, and partial output is not the output
       // the checks are meant to see.
       const postSynth = structurallyOk
-        ? postSynthErrors(plugins, result, exampleConfig.lint?.rules)
+        ? postSynthErrors(plugins, result, exampleConfig.lint?.rules, await loadActivityContracts(plugins))
         : [];
       const ok = structurallyOk && postSynth.length === 0;
 
@@ -152,7 +184,7 @@ export async function checkExamplesBuild(lexiconDir: string): Promise<ExampleBui
             ? structuralErrors.join("; ")
             : !producedOutput
               ? "discovered source but produced no output"
-              : `post-synth error(s) from the lexicon's own checks: ${postSynth.map(formatPostSynthError).join("; ")}`,
+              : `post-synth error(s): ${postSynth.map(formatPostSynthError).join("; ")}`,
       });
     } catch (err) {
       results.push({

package/src/cli/commands/init-lexicon/templates/codegen.ts

@@ -150,6 +150,7 @@ export async function packageLexicon(options?: { verbose?: boolean; force?: bool
     buildManifest: (genResult) => ({
       name: "${name}",
       version: "0.0.1",
+      chantVersion: ">=0.1.0",
     }),
     srcDir,
     collectSkills: () => new Map(),
@@ -161,6 +162,14 @@ export async function packageLexicon(options?: { verbose?: boolean; force?: bool
 `;
 }
 
+export function generateCodegenDocsCliTs(): string {
+  return `#!/usr/bin/env tsx
+import { generateDocs } from "./docs";
+
+await generateDocs({ verbose: true });
+`;
+}
+
 export function generateCodegenDocsTs(name: string): string {
   return `import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
 

package/src/cli/commands/init-lexicon/templates/project.ts

@@ -10,8 +10,16 @@ export function generatePackageJson(name: string, names: { packageName: string }
     private: true,
     files: ["src/", "dist/"],
     exports: {
-      ".": "./src/index.ts",
-      "./*": "./src/*",
+      ".": {
+        development: "./src/index.ts",
+        types: "./dist/index.d.ts",
+        default: "./src/index.ts",
+      },
+      "./*": {
+        development: "./src/*.ts",
+        types: "./dist/*.d.ts",
+        default: "./src/*.ts",
+      },
       "./manifest": "./dist/manifest.json",
       "./meta": "./dist/meta.json",
       "./types": "./dist/types/index.d.ts",
@@ -20,8 +28,9 @@ export function generatePackageJson(name: string, names: { packageName: string }
       generate: "npx tsx src/codegen/generate-cli.ts",
       validate: "npx tsx src/validate-cli.ts",
       docs: "npx tsx src/codegen/docs-cli.ts",
-      build: "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
-      prepack: "npm run generate && npm run validate && npm run build",
+      build: 'tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name "*.js" -o -name "*.js.map" \\) -delete',
+      prepack: "npm run generate && npm run bundle && npm run validate && npm run build",
+      bundle: "tsx src/package-cli.ts",
     },
     devDependencies: {
       // `*` (not `workspace:*`) so a fresh lexicon `npm install`s under plain npm
@@ -211,3 +220,34 @@ import { validate } from "./validate";
 await validate();
 `;
 }
+
+/**
+ * Thin entry point for `npm run bundle`, called from `prepack`. Writes
+ * `src/generated/` (via the generate pipeline) and `dist/` (via the package
+ * pipeline plus `writeBundleSpec`), so `dist/manifest.json` exists before
+ * `npm run validate` and `npm run build` run.
+ */
+export function generatePackageCliTs(): string {
+  return `#!/usr/bin/env tsx
+import { generate, writeGeneratedFiles } from "./codegen/generate";
+import { packageLexicon } from "./codegen/package";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const srcDir = dirname(fileURLToPath(import.meta.url));
+
+// 1. Generate src/generated/ files (writeGeneratedFiles resolves its own target)
+const genResult = await generate({ verbose: true });
+writeGeneratedFiles(genResult);
+
+// 2. Run package pipeline and write dist/
+const { spec, stats } = await packageLexicon({ verbose: true });
+
+const distDir = join(dirname(srcDir), "dist");
+writeBundleSpec(spec, distDir);
+
+console.error(\`Packaged \${stats.resources} resources, \${stats.ruleCount} rules, \${stats.skillCount} skills\`);
+console.error(\`dist/ written to \${distDir}\`);
+`;
+}