@intentius/chant 0.52.2 → 0.53.1

package/src/cdk/types.ts

@@ -0,0 +1,115 @@
+/**
+ * The parts of a CDK cloud assembly the carve advisor reads (#1056).
+ *
+ * A cloud assembly is already JSON, so there is no parser to install and no
+ * expression AST to resolve — the Terraform path's two hardest layers do not
+ * exist here. Three files carry everything the advisor needs:
+ *
+ *  - `manifest.json` — which artifacts are stacks, which template file each
+ *    one synthesized to, and (crucially) whether any context lookup went
+ *    unresolved.
+ *  - `tree.json` — the construct tree, so CloudFormation resources can be
+ *    grouped back under the construct that emitted them. Optional: CDK can be
+ *    told not to write it, and the advisor degrades to a coarser grouping.
+ *  - `*.template.json` — the CloudFormation templates themselves, already in
+ *    `AWS::*` type space, which is exactly what the AWS tier map keys on.
+ *
+ * Everything here is post-jsii, so a Python or Java CDK app reads through the
+ * same code path as a TypeScript one. Nothing in this module reads CDK source.
+ *
+ * The declarations are deliberately loose — every field optional, unknown keys
+ * tolerated — because the assembly schema is not chant's to own and gains
+ * fields between CDK releases.
+ */
+
+/** A CloudFormation resource as it appears in a synthesized template. */
+export interface CfnResource {
+  Type?: string;
+  Properties?: Record<string, unknown>;
+  /** `aws:cdk:path` names the emitting construct; `aws:asset:*` marks an asset. */
+  Metadata?: Record<string, unknown>;
+  DependsOn?: string | string[];
+  /** Names a template `Condition` — the CloudFormation analogue of `count`. */
+  Condition?: string;
+  [k: string]: unknown;
+}
+
+/** A CloudFormation `Outputs` entry. */
+export interface CfnOutput {
+  Value?: unknown;
+  Export?: { Name?: unknown };
+  [k: string]: unknown;
+}
+
+export interface CfnTemplate {
+  Parameters?: Record<string, Record<string, unknown>>;
+  Conditions?: Record<string, unknown>;
+  Resources?: Record<string, CfnResource>;
+  Outputs?: Record<string, CfnOutput>;
+  [k: string]: unknown;
+}
+
+/** One artifact in `manifest.json`. */
+export interface CdkArtifact {
+  type?: string;
+  properties?: { templateFile?: string; [k: string]: unknown };
+  displayName?: string;
+  dependencies?: string[];
+  environment?: string;
+  [k: string]: unknown;
+}
+
+/** One unresolved context lookup, as `cdk synth` records it. */
+export interface CdkMissingContext {
+  key?: string;
+  provider?: string;
+  props?: Record<string, unknown>;
+}
+
+export interface CdkManifest {
+  version?: string;
+  artifacts?: Record<string, CdkArtifact>;
+  /**
+   * Context queries synthesis could not answer. Non-empty means the templates
+   * hold placeholder values rather than the real account's, so nothing
+   * synthesized from them describes real infrastructure.
+   */
+  missing?: CdkMissingContext[];
+  [k: string]: unknown;
+}
+
+/** A node of `tree.json`. Children are keyed by construct id. */
+export interface CdkTreeNode {
+  id?: string;
+  path?: string;
+  children?: Record<string, CdkTreeNode>;
+  /** `fqn` is the construct class — the L1/L2/L3 signal. */
+  constructInfo?: { fqn?: string; version?: string };
+  attributes?: Record<string, unknown>;
+}
+
+export interface CdkTreeFile {
+  version?: string;
+  tree?: CdkTreeNode;
+}
+
+/** One CloudFormation stack artifact, with its template read. */
+export interface CdkStack {
+  /** Artifact id in `manifest.json`, e.g. `Stage-AppStack`. */
+  id: string;
+  /** Construct path of the stack, e.g. `Stage/AppStack`. */
+  path: string;
+  templateFile: string;
+  template: CfnTemplate;
+}
+
+/** A read cloud assembly: the manifest, the construct tree, the stacks. */
+export interface CloudAssembly {
+  dir: string;
+  manifest: CdkManifest;
+  /** Absent when the app was synthesized without tree metadata. */
+  tree?: CdkTreeNode;
+  stacks: CdkStack[];
+  /** Everything that went wrong or is worth saying about the read itself. */
+  diagnostics: string[];
+}

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

@@ -11,10 +11,12 @@
 
 import { existsSync, statSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
+import { cdkNotSupported, isCloudAssembly } from "../../cdk/assembly";
 import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
 import { boundaryReport } from "../../terraform/carve";
 import { graduationPlan, stampOwnershipIntoSource, type GraduationPlan } from "../../terraform/graduate";
 import { resolveCarveManifest, updateCarveManifest } from "../../terraform/manifest";
+import { resolveEmitProvider } from "../../terraform/carve-provider";
 
 export interface CarveApplyOptions {
   from?: string;
@@ -48,6 +50,7 @@ export async function carveApply(opts: CarveApplyOptions): Promise<CarveApplyRes
   if (!existsSync(opts.from) || !statSync(opts.from).isDirectory()) {
     return { ok: false, error: `Not a directory: ${opts.from}` };
   }
+  if (isCloudAssembly(opts.from)) return { ok: false, error: cdkNotSupported(opts.from, "apply") };
 
   // Compose with the manifest emit/bridge persisted: it supplies the target
   // (and tfstate) when --select is absent, and its persisted boundary stands in
@@ -63,7 +66,12 @@ export async function carveApply(opts: CarveApplyOptions): Promise<CarveApplyRes
     const graph = await parseTerraformDir(opts.from, { statePath });
     const report = boundaryReport(graph, select) ?? resolved.manifest?.boundary ?? null;
     if (!report) return { ok: false, error: `${select} not found in ${opts.from}` };
-    plan = graduationPlan(report, { stack: opts.stack, env: opts.env });
+    // The carved type decides what the apply step even looks like: a
+    // CloudFormation deploy for aws, a cluster apply for k8s (#999). The
+    // manifest records the type; the graph has it when there is no manifest.
+    const tfType = resolved.manifest?.tfType ?? graph.nodes.find((n) => n.address === select)?.type;
+    const lexicon = tfType ? resolveEmitProvider(tfType)?.lexicon : undefined;
+    plan = graduationPlan(report, { stack: opts.stack, env: opts.env, lexicon });
   } catch (err) {
     if (err instanceof Hcl2JsonNotInstalled) return { ok: false, error: err.message };
     return { ok: false, error: `Failed to plan graduation: ${err instanceof Error ? err.message : String(err)}` };
@@ -85,7 +93,15 @@ export async function carveApply(opts: CarveApplyOptions): Promise<CarveApplyRes
     for (const file of files) {
       if (!existsSync(file)) return { ok: false, error: `Emitted source not found: ${file}` };
       const result = stampOwnershipIntoSource(readFileSync(file, "utf-8"), plan.ownershipTags);
-      if (!result) return { ok: false, error: `No constructor to stamp in ${file}.` };
+      if (!result) {
+        return {
+          ok: false,
+          error:
+            `No constructor to stamp in ${file}. Tag-based ownership is a property of a native constructor call; ` +
+            `on a Kubernetes object the marker is a label the k8s build merges in (defaultLabels), not a tag in the ` +
+            `emitted source. Re-run without --write-source to get the marker and the graduation plan.`,
+        };
+      }
       if (result.changed) writeFileSync(file, result.content);
       stamped.push(file);
     }
@@ -114,7 +130,7 @@ function renderGraduationDoc(plan: GraduationPlan): string {
   L.push("");
   L.push(`Ownership marker: stack=${plan.marker.stack}${plan.marker.env ? `, env=${plan.marker.env}` : ""}`);
   L.push("");
-  L.push("## Ownership tags (stamped on apply so chant owns the resource)");
+  L.push(`## Ownership ${plan.markerKind} (stamped on apply so chant owns the resource)`);
   for (const [k, v] of Object.entries(plan.ownershipTags)) L.push(`- ${k} = ${v}`);
   L.push("");
   L.push("## Steps");
@@ -133,7 +149,7 @@ export function formatCarveApply(result: CarveApplyResult): string {
   const L: string[] = [];
   L.push(`Apply graduation for ${p.target} (dial-turn: observe → apply)${result.selectFromManifest ? " — target from the carve manifest" : ""}.`);
   L.push(`  Ownership marker: stack=${p.marker.stack}${p.marker.env ? `, env=${p.marker.env}` : ""}`);
-  L.push("  Ownership tags (stamped on apply):");
+  L.push(`  Ownership ${p.markerKind} (stamped on apply):`);
   for (const [k, v] of Object.entries(p.ownershipTags)) L.push(`    ${k} = ${v}`);
   L.push("");
   for (const s of p.steps) L.push(`  ${s}`);

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

@@ -11,10 +11,11 @@
 
 import { existsSync, statSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
 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 { IDENTITY_ATTR, canBridge } from "../../terraform/tier-map";
+import { identityAttrOf, canBridge } from "../../terraform/tier-map";
 import { resolveCarveManifest, writeCarveManifest, type CarveManifest } from "../../terraform/manifest";
 import { newFileDiff, unifiedDiff } from "../../terraform/unified-diff";
 
@@ -57,6 +58,7 @@ export async function carveBridge(opts: CarveBridgeOptions): Promise<CarveBridge
   if (!existsSync(opts.from) || !statSync(opts.from).isDirectory()) {
     return { ok: false, error: `Not a directory: ${opts.from}` };
   }
+  if (isCloudAssembly(opts.from)) return { ok: false, error: cdkNotSupported(opts.from, "bridge") };
 
   // Compose with the carve state manifest `carve emit` persisted: without
   // --select it supplies the target (and tfstate), with it it is updated below.
@@ -78,7 +80,9 @@ export async function carveBridge(opts: CarveBridgeOptions): Promise<CarveBridge
     // 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 (#999).
+    // 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).
     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) {
@@ -86,9 +90,9 @@ export async function carveBridge(opts: CarveBridgeOptions): Promise<CarveBridge
         ok: false,
         error:
           `${select} cannot be bridged: ${unbridgeable
-            .map((t) => `${t} identifies itself by \`${IDENTITY_ATTR[t]}\``)
+            .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 #999.`,
+          `Bridging these types needs a data-source mapping — see chant issue #2034.`,
       };
     }
 
@@ -96,7 +100,7 @@ export async function carveBridge(opts: CarveBridgeOptions): Promise<CarveBridge
     const identities = new Map<string, CarvedIdentity>();
     for (const node of graph.nodes) {
       if (node.type && node.identity) {
-        identities.set(node.address, { attr: IDENTITY_ATTR[node.type], value: node.identity });
+        identities.set(node.address, { attr: identityAttrOf(node.type), value: node.identity });
       }
     }
 

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

@@ -0,0 +1,262 @@
+import { describe, test, expect, vi } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync, readFileSync, existsSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { carveEmit, formatCarveEmit } from "./carve-emit";
+import { carveBridge } from "./carve-bridge";
+import { loadHcl2json } from "../../terraform/parse";
+import type { ImportResult, LiveImportOptions } from "./import";
+import type { LexiconPlugin } from "../../lexicon";
+
+/**
+ * `carve emit` over the kubernetes provider (#999), end to end: a Terraform
+ * estate that manages Kubernetes objects through `kubernetes_manifest`, carved
+ * into a buildable chant project for the k8s lexicon.
+ *
+ * The point of the fixture is the second resource. A `kubernetes_manifest` has
+ * no fixed entity type — the kind is inside the body — so a cert-manager
+ * Certificate and a core ConfigMap go through the identical path, which is what
+ * "one rule covers every CRD" has to mean in practice.
+ */
+let parserAvailable = false;
+try {
+  await loadHcl2json();
+  parserAvailable = true;
+} catch {
+  parserAvailable = false;
+}
+
+const ESTATE = `
+resource "kubernetes_namespace" "web" {
+  metadata {
+    name = "web"
+  }
+}
+
+resource "kubernetes_manifest" "app_config" {
+  manifest = {
+    apiVersion = "v1"
+    kind       = "ConfigMap"
+    metadata = {
+      name      = "app-config"
+      namespace = kubernetes_namespace.web.metadata[0].name
+    }
+    data = {
+      LOG_LEVEL = "info"
+    }
+  }
+}
+
+resource "kubernetes_manifest" "web_cert" {
+  manifest = {
+    apiVersion = "cert-manager.io/v1"
+    kind       = "Certificate"
+    metadata = {
+      name      = "web-tls"
+      namespace = "web"
+    }
+    spec = {
+      secretName = "web-tls"
+      dnsNames   = ["web.example.com"]
+    }
+  }
+}
+
+resource "kubernetes_config_map" "legacy" {
+  metadata {
+    name      = "legacy"
+    namespace = "web"
+  }
+  data = {
+    OLD = "true"
+  }
+}
+`;
+
+const TFSTATE = JSON.stringify({
+  version: 4,
+  resources: [
+    {
+      mode: "managed",
+      type: "kubernetes_manifest",
+      name: "app_config",
+      instances: [
+        {
+          attributes: {
+            manifest: {
+              apiVersion: "v1",
+              kind: "ConfigMap",
+              metadata: { name: "app-config", namespace: "web", labels: { "app.kubernetes.io/name": "web" } },
+              data: { LOG_LEVEL: "info" },
+            },
+            computed_fields: ["metadata.labels", "metadata.annotations"],
+            field_manager: null,
+          },
+        },
+      ],
+    },
+    {
+      mode: "managed",
+      type: "kubernetes_manifest",
+      name: "web_cert",
+      instances: [
+        {
+          attributes: {
+            manifest: {
+              apiVersion: "cert-manager.io/v1",
+              kind: "Certificate",
+              metadata: { name: "web-tls", namespace: "web" },
+              spec: { secretName: "web-tls", dnsNames: ["web.example.com"] },
+            },
+          },
+        },
+      ],
+    },
+    {
+      mode: "managed",
+      type: "kubernetes_config_map",
+      name: "legacy",
+      instances: [{ attributes: { id: "web/legacy", data: { OLD: "true" } } }],
+    },
+  ],
+});
+
+const fakeImport = () =>
+  vi.fn(
+    async (_plugins: LexiconPlugin[], _options: LiveImportOptions): Promise<ImportResult> => ({
+      success: true,
+      generatedFiles: ["infra/main.ts"],
+      warnings: [],
+    }),
+  );
+
+async function withEstate<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = mkdtempSync(join(tmpdir(), "chant-carve-k8s-"));
+  try {
+    writeFileSync(join(dir, "main.tf"), ESTATE);
+    writeFileSync(join(dir, "terraform.tfstate"), TFSTATE);
+    return await fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+describe("carve emit — kubernetes_manifest (#999)", () => {
+  test("carves a ConfigMap manifest into a buildable k8s project", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      const liveImport = fakeImport();
+      const res = await carveEmit(
+        { from: dir, select: "kubernetes_manifest.app_config", statePath: join(dir, "terraform.tfstate"), output: out },
+        { plugins: [], liveImport },
+      );
+
+      expect(res.ok).toBe(true);
+      expect(res.source).toBe("tfstate");
+      expect(liveImport).not.toHaveBeenCalled();
+
+      const source = readFileSync(join(out, "src", "app_config.ts"), "utf-8");
+      expect(source).toContain('import { k8sManifest } from "@intentius/chant-lexicon-k8s";');
+      expect(source).toContain("export const app_config = k8sManifest({");
+      expect(source).toContain('apiVersion: "v1"');
+      expect(source).toContain('kind: "ConfigMap"');
+      expect(source).toContain('"app.kubernetes.io/name": "web"');
+      expect(source).toContain("-> v1 ConfigMap");
+
+      // The scaffold targets the provider's lexicon, so the emitted project
+      // builds with `npm install && npm run build` as it stands.
+      const pkg = JSON.parse(readFileSync(join(out, "package.json"), "utf-8"));
+      expect(pkg.scripts.build).toBe("chant build src --lexicon k8s");
+      expect(Object.keys(pkg.dependencies)).toEqual(["@intentius/chant", "@intentius/chant-lexicon-k8s"]);
+      expect(readFileSync(join(out, "chant.config.ts"), "utf-8")).toContain('lexicons: ["k8s"]');
+
+      // The namespace the manifest read is a survivor, so it is an outbound
+      // edge and becomes a declared build parameter.
+      expect(res.params?.map((p) => p.name)).toEqual(["manifest"]);
+      expect(source).toContain("Deferred deploy-time input: manifest read kubernetes_namespace.web");
+      // Nothing is substituted: state resolved `manifest` to the whole object.
+      expect(source).not.toContain("params.");
+
+      expect(res.manifestPath).toBe(join(out, "kubernetes_manifest-app_config.carve.json"));
+      expect(formatCarveEmit(res)).toContain("Adopted from Terraform state (offline).");
+    });
+  });
+
+  test("a CRD manifest carves through the same path as a core kind", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      const res = await carveEmit(
+        { from: dir, select: "kubernetes_manifest.web_cert", statePath: join(dir, "terraform.tfstate"), output: out },
+        { plugins: [], liveImport: fakeImport() },
+      );
+
+      expect(res.ok).toBe(true);
+      const source = readFileSync(join(out, "src", "web_cert.ts"), "utf-8");
+      expect(source).toContain("-> cert-manager.io/v1 Certificate");
+      expect(source).toContain('apiVersion: "cert-manager.io/v1"');
+      expect(source).toContain('kind: "Certificate"');
+      expect(source).toContain('secretName: "web-tls"');
+      expect(source).toContain('"web.example.com",');
+      // No CRD-specific mapping was needed, so nothing was left behind.
+      expect(source).not.toContain("TODO");
+    });
+  });
+
+  test("--env refuses: the kind is in the body, so a live export has nothing to filter on", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const liveImport = fakeImport();
+      const res = await carveEmit(
+        { from: dir, select: "kubernetes_manifest.app_config", env: "prod" },
+        { plugins: [], liveImport },
+      );
+      expect(res.ok).toBe(false);
+      expect(res.error).toContain("no live adoption path");
+      expect(res.error).toContain("--state");
+      expect(liveImport).not.toHaveBeenCalled();
+    });
+  });
+
+  test("a typed kubernetes resource ranks but is refused identically on both paths", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const liveImport = fakeImport();
+      const live = await carveEmit(
+        { from: dir, select: "kubernetes_config_map.legacy", env: "prod" },
+        { plugins: [], liveImport },
+      );
+      const state = await carveEmit(
+        { from: dir, select: "kubernetes_config_map.legacy", statePath: join(dir, "terraform.tfstate") },
+        { plugins: [], liveImport },
+      );
+      expect(live.ok).toBe(false);
+      expect(state.error).toBe(live.error);
+      expect(live.error).toContain("kubernetes_config_map cannot be emitted yet");
+      expect(live.error).toContain("kubernetes_manifest");
+      expect(liveImport).not.toHaveBeenCalled();
+    });
+  });
+
+  test("bridge still refuses the carved manifest, so emit writes no half-bridged estate", 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 },
+        { 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);
+    });
+  });
+});