@intentius/chant 0.52.1 → 0.53.0

package/src/terraform/carve-provider.ts

@@ -0,0 +1,237 @@
+/**
+ * The carve provider seam (#2016).
+ *
+ * `carve advise|emit|bridge` used to reach into the AWS carve table directly:
+ * the tier map derived from it, the emit gate was `awsCarveType(t) !== undefined`,
+ * the adopter called `applyAwsMapper`, and the emitted project's lexicon was a
+ * constant. A second provider — Kubernetes emit (#999), GCP (#2017) — had
+ * nowhere to land except a parallel path beside the AWS one.
+ *
+ * A provider owns one or more Terraform type prefixes and answers everything
+ * the carve commands ask about the types under them: how each ranks against a
+ * native spec, which HCL attribute carries the physical name, which
+ * sub-resources fold into a parent, which types emit can produce source for,
+ * and how to adopt one from `.tfstate`.
+ *
+ * ── Why the registry lives in core, not behind a `LexiconPlugin` capability ──
+ *
+ * `carve advise` runs against a Terraform directory that is not a chant project:
+ * there is no `chant.config.ts` naming lexicons, so there is nothing to load
+ * plugins from, and `carve emit --state` is deliberately offline (see the
+ * handler). Behind a plugin capability both would have to load plugins to learn
+ * that a type ranks tier 1. Providers are also Terraform-provider knowledge
+ * (`terraform-provider-aws` attribute names), which belongs beside the HCL
+ * parser rather than inside a lexicon.
+ *
+ * `registerCarveProvider` is exported, so a plugin that wants to contribute a
+ * provider at runtime still can — the seam does not foreclose it, it just does
+ * not require plugin loading for the paths that run without one.
+ */
+
+import { BUILTIN_CARVE_PROVIDERS } from "./providers";
+import type { StateResource } from "./state";
+
+export interface TierInfo {
+  tier: 1 | 2 | 3;
+  /** The native spec type a carve would target, for the report. */
+  mapsTo: string;
+}
+
+/**
+ * One deferred outbound input turned into a build parameter (#998). Derived
+ * from the boundary report's outbound edges + the state's resolved attributes
+ * in `carve-emit.ts`; consumed by a provider's `adopt` (source substitution)
+ * and by the scaffold (`chant.config.ts` `buildParams` declaration).
+ */
+export interface DeferredParam {
+  /** Build-parameter name, source-referenceable (`params.<name>`). */
+  name: string;
+  /** The carved resource's own Terraform attribute the value enters through. */
+  tfAttr: string;
+  /** The survivor the Terraform source read, e.g. `aws_vpc.main`. */
+  survivor: string;
+  /** Survivor attribute(s) read, e.g. `["id"]`. */
+  attrs: string[];
+  /** The state-resolved value — the parameter's declared default. */
+  default?: string | number | boolean;
+}
+
+/** What one folded sub-resource contributed to the parent's emitted props (#1637). */
+export interface FoldedContribution {
+  /** The sub-resource's Terraform address, e.g. `aws_s3_bucket_versioning.assets`. */
+  address: string;
+  /** Native properties it added to the parent, e.g. `["VersioningConfiguration"]`. */
+  props: string[];
+}
+
+export interface AdoptedSource {
+  fileName: string;
+  content: string;
+  /** True when at least one attribute was mapped to a native prop. */
+  mapped: boolean;
+  nativeType: string;
+  /** Deferred params actually substituted into the emitted props (#998). */
+  parameterized: string[];
+  /** Folded sub-resources and the props each one joined into the parent (#1637). */
+  folded: FoldedContribution[];
+}
+
+export interface CarveProvider {
+  /** Registry id, unique. Registering a second provider under it replaces the first. */
+  readonly name: string;
+  /**
+   * Terraform type prefixes this provider owns, e.g. `["aws_"]`. Resolution
+   * takes the longest match, so a narrower provider can claim a subset of a
+   * wider one's prefix.
+   */
+  readonly tfTypePrefixes: readonly string[];
+  /**
+   * The chant lexicon emitted source targets — the scaffolded project's
+   * dependency and `--lexicon` flag, and the lexicon the live import runs
+   * against.
+   */
+  readonly lexicon: string;
+  /** Terraform type → native tier, contributed to the advisor's tier map. */
+  readonly tiers: Readonly<Record<string, TierInfo>>;
+  /**
+   * Terraform type → the HCL attribute carrying the physical name. A dotted
+   * entry is a path into nested blocks (`manifest.metadata.name`); the bridge
+   * refuses those, since a data-source body is flat `attr = value`.
+   */
+  readonly identityAttrs?: Readonly<Record<string, string>>;
+  /**
+   * Sub-resource Terraform type → parent type, for types Terraform splits out
+   * of the resource the native spec keeps them in.
+   */
+  readonly foldsInto?: Readonly<Record<string, string>>;
+  /**
+   * Terraform types `carve emit` can produce chant source for — narrower than
+   * `tiers`, which advise also ranks types no emit path can adopt. Absent or
+   * empty means advise-only. Declaring types here obliges the provider to
+   * implement {@link adopt}: both emit paths gate on the same list (#2015), so
+   * a type the live path accepts must be adoptable from state too.
+   */
+  readonly emitTypes?: readonly string[];
+  /** Adopt a resource from Terraform state into chant source. */
+  adopt?(resource: StateResource, params: DeferredParam[], folded: StateResource[]): AdoptedSource | null;
+  /**
+   * The native selector type the live (cloud→code) import filters on, e.g.
+   * `AWS::S3::Bucket`. Undefined when this type has no live adoption path —
+   * `carve emit --env` refuses it rather than importing the wrong thing.
+   */
+  liveSelectorType?(tfType: string): string | undefined;
+}
+
+/**
+ * A provider declaring emit types without an adopter would accept a type on
+ * `--env` and fail it on `--state`, the advise↔emit cliff #2015 closed.
+ */
+function validate(provider: CarveProvider): void {
+  if (provider.emitTypes?.length && !provider.adopt) {
+    throw new Error(`Carve provider "${provider.name}" declares emitTypes but no adopt() — the --state path would refuse what --env accepts.`);
+  }
+  if (!provider.tfTypePrefixes.length) {
+    throw new Error(`Carve provider "${provider.name}" claims no Terraform type prefix, so no type would ever resolve to it.`);
+  }
+}
+
+const providers: CarveProvider[] = [...BUILTIN_CARVE_PROVIDERS];
+for (const p of providers) validate(p);
+
+/** Bumped on every registry mutation, so the derived indexes rebuild. */
+let revision = 0;
+
+/**
+ * Register a carve provider. Returns a function that removes it again, so a
+ * test (or a plugin unloading) leaves the registry as it found it.
+ */
+export function registerCarveProvider(provider: CarveProvider): () => void {
+  validate(provider);
+  const existing = providers.findIndex((p) => p.name === provider.name);
+  if (existing >= 0) providers.splice(existing, 1);
+  providers.push(provider);
+  revision++;
+  return () => {
+    const at = providers.indexOf(provider);
+    if (at < 0) return;
+    providers.splice(at, 1);
+    revision++;
+  };
+}
+
+/** Every registered provider, in registration order. */
+export function carveProviders(): readonly CarveProvider[] {
+  return providers;
+}
+
+interface RegistryIndex {
+  /** Prefixes longest-first, so the narrowest claim wins. */
+  prefixes: Array<{ prefix: string; provider: CarveProvider }>;
+  tiers: Record<string, TierInfo>;
+  identityAttrs: Record<string, string>;
+  foldsInto: Record<string, string>;
+  /** Terraform type → the provider that emits it. */
+  emitters: Map<string, CarveProvider>;
+}
+
+let cached: { revision: number; index: RegistryIndex } | null = null;
+
+function index(): RegistryIndex {
+  if (cached && cached.revision === revision) return cached.index;
+  const built: RegistryIndex = {
+    prefixes: [],
+    tiers: {},
+    identityAttrs: {},
+    foldsInto: {},
+    emitters: new Map(),
+  };
+  for (const provider of providers) {
+    for (const prefix of provider.tfTypePrefixes) built.prefixes.push({ prefix, provider });
+    Object.assign(built.tiers, provider.tiers);
+    if (provider.identityAttrs) Object.assign(built.identityAttrs, provider.identityAttrs);
+    if (provider.foldsInto) Object.assign(built.foldsInto, provider.foldsInto);
+    for (const tfType of provider.emitTypes ?? []) built.emitters.set(tfType, provider);
+  }
+  built.prefixes.sort((a, b) => b.prefix.length - a.prefix.length);
+  cached = { revision, index: built };
+  return built;
+}
+
+/** The provider owning this Terraform type, by longest prefix match. */
+export function resolveCarveProvider(tfType: string): CarveProvider | undefined {
+  return index().prefixes.find((p) => tfType.startsWith(p.prefix))?.provider;
+}
+
+/**
+ * The provider that can emit chant source for this Terraform type. Narrower
+ * than {@link resolveCarveProvider}: a provider owns every type under its
+ * prefix for advise, and only the ones on its `emitTypes` list for emit.
+ */
+export function resolveEmitProvider(tfType: string): CarveProvider | undefined {
+  return index().emitters.get(tfType);
+}
+
+/** Every Terraform type any registered provider can emit, sorted, for user-facing hints. */
+export function carveEmitTypes(): string[] {
+  return [...index().emitters.keys()].sort();
+}
+
+/** The lexicons emit can adopt into, sorted — what the CLI loads plugins for. */
+export function carveEmitLexicons(): string[] {
+  return [...new Set([...index().emitters.values()].map((p) => p.lexicon))].sort();
+}
+
+/** Terraform resource type → native tier, merged over every provider. Read-only: it is the cached index. */
+export function carveTierMap(): Readonly<Record<string, TierInfo>> {
+  return index().tiers;
+}
+
+/** The HCL attribute carrying this type's physical name, if its provider declares one. */
+export function carveIdentityAttr(tfType: string): string | undefined {
+  return index().identityAttrs[tfType];
+}
+
+/** The parent Terraform type this sub-resource folds into, if any. */
+export function carveFoldParent(tfType: string): string | undefined {
+  return index().foldsInto[tfType];
+}

package/src/terraform/carve.test.ts

@@ -1,6 +1,6 @@
 import { describe, test, expect } from "vitest";
 import { buildFixtureGraph } from "./__fixtures__/build-graph";
-import { resolveCarveSet, boundaryReport } from "./carve";
+import { resolveCarveSet, boundaryReport, dedupeEdges, type BoundaryEdge } from "./carve";
 import type { Hcl2JsonTree } from "./types";
 
 // #197 worked example: a bucket a Lambda reads, with a versioning sub-resource.
@@ -131,3 +131,57 @@ describe("boundaryReport", () => {
     expect(boundaryReport(buildFixtureGraph(workedExample), "aws_s3_bucket.nope")).toBeNull();
   });
 });
+
+// #2025: dedupeEdges joins survivor/carved with a separator no Terraform
+// address can contain. A survivor/carved pair with no separator at all would
+// collide across the two edges below (both concatenate to the same string),
+// so this pins the separator's job, not just the byte that used to be a NUL.
+describe("dedupeEdges", () => {
+  const edge = (over: Partial<BoundaryEdge>): BoundaryEdge => ({
+    direction: "inbound",
+    survivor: "a",
+    carved: "b",
+    attrs: [],
+    via: [],
+    bridge: "tf-data-source",
+    required: "immediately",
+    ...over,
+  });
+
+  test("does not merge distinct pairs whose plain concatenation collides", () => {
+    const edges = [
+      edge({ survivor: "aws_instance.ab", carved: "aws_s3_bucket.x", attrs: ["arn"] }),
+      edge({ survivor: "aws_instance.a", carved: "baws_s3_bucket.x", attrs: ["id"] }),
+    ];
+    // Both concatenate (survivor + carved, no separator) to the same string.
+    expect(edges[0].survivor + edges[0].carved).toBe(edges[1].survivor + edges[1].carved);
+
+    const result = dedupeEdges(edges);
+    expect(result).toHaveLength(2);
+    // Sorted by survivor: "aws_instance.a" sorts before "aws_instance.ab".
+    expect(result.map((e) => e.attrs)).toEqual([["id"], ["arn"]]);
+  });
+
+  test("merges edges that share the same survivor/carved pair, unioning attrs and via", () => {
+    const edges = [
+      edge({ survivor: "aws_lambda_function.api", carved: "aws_s3_bucket.assets", attrs: ["arn"], via: ["env"] }),
+      edge({
+        survivor: "aws_lambda_function.api",
+        carved: "aws_s3_bucket.assets",
+        attrs: ["bucket"],
+        via: ["tags"],
+      }),
+    ];
+    const result = dedupeEdges(edges);
+    expect(result).toHaveLength(1);
+    expect(result[0].attrs).toEqual(["arn", "bucket"]);
+    expect(result[0].via).toEqual(["env", "tags"]);
+  });
+
+  test("the separator is outside the alphabet a Terraform address component can use", () => {
+    // Mirrors graph.ts's NAME (`/^[A-Za-z_][A-Za-z0-9_-]*$/`), the grammar an
+    // address segment must match, plus the literal `.` that joins segments.
+    const addressChars = /^[A-Za-z0-9_.-]*$/;
+    expect(addressChars.test("")).toBe(false);
+  });
+});

package/src/terraform/emit-source.ts

@@ -0,0 +1,39 @@
+/**
+ * Source rendering shared by constructor-shaped carve providers (#2016).
+ *
+ * A provider that adopts into a typed chant constructor call — aws today, gcp
+ * next (#2017) — renders the same literal: an import, an exported `new Ctor({
+ * ...props })`, and a reference comment carrying whatever the mapping could not
+ * place. Only the lexicon import path and the property mapping differ, so the
+ * rendering lives here rather than being copied per provider.
+ *
+ * A provider whose native shape is not a constructor call (a Kubernetes
+ * manifest, #999) renders its own source and does not use this.
+ */
+
+/** The core subpath the emitted source reads build parameters from. */
+export const PARAMS_IMPORT = "@intentius/chant/params";
+
+/** Marker for a prop whose value is a `params.<name>` reference, not a literal. */
+export class ParamRef {
+  constructor(
+    readonly name: string,
+    readonly type: "string" | "number" | "boolean",
+  ) {}
+}
+
+/** Render a JS object literal with stable key order and given indent. */
+export function renderObject(obj: Record<string, unknown>, indent: number): string {
+  const keys = Object.keys(obj);
+  if (keys.length === 0) return "{}";
+  const pad = " ".repeat(indent);
+  const body = keys
+    .map((k) => `${pad}${k}: ${renderValue(obj[k])},`)
+    .join("\n");
+  return `{\n${body}\n}`;
+}
+
+/** A prop value: a `params.<name>` reference (cast keeps the project tsc-clean) or a literal. */
+export function renderValue(value: unknown): string {
+  return value instanceof ParamRef ? `params.${value.name} as ${value.type}` : JSON.stringify(value);
+}

package/src/terraform/graduate.test.ts

@@ -2,6 +2,7 @@ import { describe, test, expect } from "vitest";
 import { buildFixtureGraph } from "./__fixtures__/build-graph";
 import { boundaryReport } from "./carve";
 import { graduationPlan, stampOwnershipIntoSource, DEFAULT_TAG_OWNERSHIP_KEYS } from "./graduate";
+import { LABEL_OWNERSHIP_KEYS } from "../ownership";
 import type { Hcl2JsonTree } from "./types";
 
 const bucketTree: Hcl2JsonTree = {
@@ -40,6 +41,23 @@ describe("graduationPlan", () => {
     expect(runbook).toMatch(/lifecycle diff --live/);
   });
 
+  test("a k8s carve graduates in labels and kubectl, not tags and CloudFormation (#999)", () => {
+    const report = boundaryReport(buildFixtureGraph(bucketTree), "aws_s3_bucket.assets")!;
+    const plan = graduationPlan(report, { stack: "assets", env: "prod", lexicon: "k8s" });
+
+    // The channel the k8s serializer actually merges in, not the AWS tag keys.
+    expect(plan.markerKind).toBe("labels");
+    expect(plan.ownershipTags).toEqual({
+      [LABEL_OWNERSHIP_KEYS.managedBy]: "chant",
+      [LABEL_OWNERSHIP_KEYS.stack]: "assets",
+      [LABEL_OWNERSHIP_KEYS.env]: "prod",
+    });
+    const runbook = plan.steps.join("\n");
+    expect(runbook).toContain("kubectl apply -f");
+    expect(runbook).toContain("--lexicon k8s");
+    expect(runbook).not.toContain("cloudformation deploy");
+  });
+
   test("warns when outbound edges leave deferred inputs to wire", () => {
     // Carve the Lambda: it depends on the bucket (survivor) → outbound/deferred.
     const report = boundaryReport(buildFixtureGraph(bucketTree), "aws_lambda_function.api")!;
@@ -113,4 +131,23 @@ describe("stampOwnershipIntoSource", () => {
   test("returns null when there is no constructor to stamp", () => {
     expect(stampOwnershipIntoSource("// nothing here\n", TAGS)).toBeNull();
   });
+
+  test("refuses a carved manifest rather than inventing a top-level Tags field (#999)", () => {
+    // The props of a `k8sManifest` call ARE the object. A `Tags: [...]` line
+    // spliced before the closing `});` would be a field the API server never
+    // heard of, applied as if an author had written it.
+    const src = [
+      'import { k8sManifest } from "@intentius/chant-lexicon-k8s";',
+      "",
+      "export const app_config = k8sManifest({",
+      '  apiVersion: "v1",',
+      '  kind: "ConfigMap",',
+      "  metadata: {",
+      '    name: "app-config",',
+      "  },",
+      "});",
+      "",
+    ].join("\n");
+    expect(stampOwnershipIntoSource(src, TAGS)).toBeNull();
+  });
 });

package/src/terraform/graduate.ts

@@ -14,7 +14,7 @@
  * emitted source now carries.
  */
 
-import { ownershipEntries, type ChannelKeys, type OwnershipMarker } from "../ownership";
+import { ownershipEntries, LABEL_OWNERSHIP_KEYS, type ChannelKeys, type OwnershipMarker } from "../ownership";
 import type { CarveReport } from "./carve";
 
 /**
@@ -32,8 +32,10 @@ export const DEFAULT_TAG_OWNERSHIP_KEYS: ChannelKeys = {
 export interface GraduationPlan {
   target: string;
   marker: OwnershipMarker;
-  /** The ownership tags the emitted resource must carry to be chant-owned. */
+  /** The ownership entries the emitted resource must carry to be chant-owned. */
   ownershipTags: Record<string, string>;
+  /** What that channel is called on this target: `tags`, or `labels` for k8s. */
+  markerKind: string;
   /** The finalized, ordered apply runbook. */
   steps: string[];
   warnings: string[];
@@ -46,12 +48,48 @@ export interface GraduationOptions {
   env?: string;
   /** Override the tag channel (e.g. for a non-AWS lexicon). */
   channel?: ChannelKeys;
+  /**
+   * The lexicon the emitted source targets, from the carve provider that
+   * adopted the type. It decides how the build and the apply are spelled: a
+   * CloudFormation template and `aws cloudformation deploy` for aws, a manifest
+   * and `kubectl apply` for k8s (#999). Unknown falls back to the aws wording,
+   * which is what every carve was before there was a second provider.
+   */
+  lexicon?: string;
+}
+
+/**
+ * How the marker, the build output and the BYOL apply are spelled, per emitted
+ * lexicon. A Kubernetes object carries the marker as labels — the same
+ * `LABEL_OWNERSHIP_KEYS` the k8s serializer merges in — so a runbook promising
+ * `chant:managed-by` tags would name a channel nothing stamps.
+ */
+function applyVocabulary(
+  lexicon: string | undefined,
+  target: string,
+  stack: string,
+): { channel: ChannelKeys; markerKind: string; build: string; apply: string } {
+  if (lexicon === "k8s") {
+    return {
+      channel: LABEL_OWNERSHIP_KEYS,
+      markerKind: "labels",
+      build: `chant build <emitted-src> --lexicon k8s > ${target}.yaml`,
+      apply: `kubectl apply -f ${target}.yaml`,
+    };
+  }
+  return {
+    channel: DEFAULT_TAG_OWNERSHIP_KEYS,
+    markerKind: "tags",
+    build: `chant build <emitted-src> -o ${target}.template.json`,
+    apply: `aws cloudformation deploy --template-file ${target}.template.json --stack-name ${stack} ...`,
+  };
 }
 
 export function graduationPlan(report: CarveReport, opts: GraduationOptions = {}): GraduationPlan {
   const stack = opts.stack ?? (report.target.split(".").slice(1).join(".") || report.target);
   const marker: OwnershipMarker = { stack, env: opts.env };
-  const ownershipTags = ownershipEntries(opts.channel ?? DEFAULT_TAG_OWNERSHIP_KEYS, marker);
+  const vocabulary = applyVocabulary(opts.lexicon, report.target, stack);
+  const ownershipTags = ownershipEntries(opts.channel ?? vocabulary.channel, marker);
 
   const warnings: string[] = [];
   if (report.outbound.length) {
@@ -65,18 +103,27 @@ export function graduationPlan(report: CarveReport, opts: GraduationOptions = {}
     .join(", ");
 
   const steps = [
-    `1. Confirm the emitted source builds spec-true:  chant build <emitted-src> -o ${report.target}.template.json`,
-    `2. Add the ownership marker so chant owns the resource — tags: ${tagList}`,
+    `1. Confirm the emitted source builds spec-true:  ${vocabulary.build}`,
+    `2. Add the ownership marker so chant owns the resource — ${vocabulary.markerKind}: ${tagList}`,
     `3. Apply with your lifecycle (BYOL), e.g.:`,
-    `     aws cloudformation deploy --template-file ${report.target}.template.json --stack-name ${stack} ...`,
+    `     ${vocabulary.apply}`,
     `   or graduate to an ApplyOp for a durable, gated apply.`,
     `4. Verify chant now owns it:  chant lifecycle diff --live <env>   (expect: unchanged, owned)`,
     `Rollback before this point:  terraform import ${report.target} <physical-id>`,
   ];
 
-  return { target: report.target, marker, ownershipTags, steps, warnings };
+  return { target: report.target, marker, ownershipTags, markerKind: vocabulary.markerKind, steps, warnings };
 }
 
+/**
+ * A constructor-shaped emitted file: `export const x = new Ctor(`. Tag-based
+ * ownership is a property of that shape — a carved `kubernetes_manifest` is a
+ * `k8sManifest({ ... })` call whose props are the manifest, where a top-level
+ * `Tags` array would be an invented field on the object, not a marker (#999).
+ * Such a file is refused rather than stamped.
+ */
+const CONSTRUCTOR_SHAPE = /^export const \w+ = new \w+\(/m;
+
 /**
  * Stamp the ownership tags into an emitted chant source file (`carve apply
  * --write-source`). The emitted source is machine-generated (`adoptFromState`),
@@ -89,6 +136,7 @@ export function stampOwnershipIntoSource(
   content: string,
   tags: Record<string, string>,
 ): { content: string; changed: boolean } | null {
+  if (!CONSTRUCTOR_SHAPE.test(content)) return null;
   const entries = Object.entries(tags).map(([Key, Value]) => ({ Key, Value }));
   const keys = new Set(Object.keys(tags));
   const lines = content.split("\n");

package/src/terraform/graph.ts

@@ -11,7 +11,7 @@
  * graph building stays unit-testable on hand-written fixtures.
  */
 
-import { IDENTITY_ATTR } from "./tier-map";
+import { identityAttrOf } from "./tier-map";
 import type { Hcl2JsonTree, TfEdge, TfGraph, TfNode } from "./types";
 
 /**
@@ -143,12 +143,12 @@ function blockHasMeta(block: unknown, key: string): boolean {
 
 /**
  * The resource's physical name, if its identity attribute is a plain literal
- * (not interpolated). A dotted `IDENTITY_ATTR` entry walks nested blocks —
+ * (not interpolated). A dotted identity attribute walks nested blocks —
  * hcl2json renders a nested block as a one-element array, so arrays step
  * through their first element (`manifest.metadata.name`).
  */
 function literalIdentity(block: unknown, type: string): string | undefined {
-  const attr = IDENTITY_ATTR[type];
+  const attr = identityAttrOf(type);
   if (!attr || !block || typeof block !== "object") return undefined;
   let value: unknown = block;
   for (const segment of attr.split(".")) {