@intentius/chant 0.52.2 → 0.53.0

package/src/terraform/score.ts

@@ -18,13 +18,20 @@
  * expression in a block that manages no infrastructure, the same order of work
  * as recording an outbound deferred input. Hence 4, not 12.
  *
- * Sub-resources that inline into a parent (see `FOLDS_INTO`) are folded into the
+ * Sub-resources that inline into a parent (see `foldParentOf`) are folded into the
  * parent's carve set: they are removed from the ranking and their edge to the
  * parent is not counted as inbound — inlining them is free, not boundary work.
+ *
+ * The model itself is not Terraform-specific — the CDK cloud-assembly advisor
+ * (#1056) scores construct units with the same arithmetic. What differs per
+ * source is the type→tier lookup and the extra signals that source can see, so
+ * both are injectable via `ScoreOptions` rather than forked into a second
+ * scorer. Everything else — the six penalty terms, the clamp, the bands — is
+ * shared verbatim.
  */
 
 import { inboundEdges, outboundEdges } from "./graph";
-import { FOLDS_INTO, resolveTier } from "./tier-map";
+import { foldParentOf, resolveTier, type TierInfo } from "./tier-map";
 import type { TfGraph, TfNode } from "./types";
 
 export type PeelabilityBand = "clean leaf" | "carvable w/ edits" | "leave in Terraform";
@@ -38,7 +45,12 @@ export interface PeelabilityBreakdown {
   tier: 1 | 2 | 3 | null;
   hasDynamic: boolean;
   instances: number;
-  /** Signed penalty contributions, for report transparency. */
+  /**
+   * Signed penalty contributions, for report transparency. The six shared terms
+   * are always present; a source-specific scorer may add its own keys (the CDK
+   * advisor's `asset`, say). A reader that sums the values reproduces the score;
+   * a reader that only knows the six named terms still reads those correctly.
+   */
   penalties: {
     inbound: number;
     outbound: number;
@@ -46,9 +58,28 @@ export interface PeelabilityBreakdown {
     tier: number;
     dynamic: number;
     instances: number;
+    [term: string]: number;
   };
 }
 
+/**
+ * One unit of source a scored node stands for, when the node is a fold of
+ * several (#1056). A CDK construct emits 1..n CloudFormation resources and
+ * ranks once; this names the resources that carve with it. Absent on the
+ * Terraform path, where a fold is expressed by the child's absence from the
+ * ranking instead.
+ */
+export interface CarveUnitMember {
+  /** Identifier within its template/estate — a CFN logical ID. */
+  id: string;
+  /** Resource type, e.g. `AWS::IAM::Role`. */
+  type: string;
+  /** The template/stack the member lives in. */
+  stack?: string;
+  /** The member's own source path, e.g. a CDK construct path. */
+  path?: string;
+}
+
 export interface Peelability {
   address: string;
   kind: "resource" | "module";
@@ -57,10 +88,53 @@ export interface Peelability {
   /** Native spec type a carve would target; undefined for modules/unsupported. */
   mapsTo?: string;
   breakdown: PeelabilityBreakdown;
+  /**
+   * Source-specific facts about this node that the six penalty terms do not
+   * carry — why it was disqualified, what folded into it, what it is. Plain
+   * prose, for the report's benefit; nothing keys on it.
+   */
+  notes?: string[];
+  /** The source units folded into this node (#1056). */
+  members?: CarveUnitMember[];
+}
+
+/**
+ * Source-specific scoring input for one node, layered on the shared model.
+ * Everything here is optional: with no signals a node scores exactly as the
+ * Terraform path scores it.
+ */
+export interface ScoreSignals {
+  /** Extra penalty terms, merged into `breakdown.penalties` and the total. */
+  penalties?: Record<string, number>;
+  notes?: string[];
+  members?: CarveUnitMember[];
+  /**
+   * When set, the node scores 0 and this is the stated reason. For claims the
+   * arithmetic cannot express — a CDK assembly synthesized from dummy lookup
+   * values is not a faithful picture of anything, so no score it produces is
+   * worth reading.
+   */
+  disqualified?: string;
+}
+
+export interface ScoreOptions {
+  /**
+   * Resource type → native tier. Defaults to the Terraform tier map; the CDK
+   * advisor passes a CloudFormation-keyed one. Modules keep the built-in
+   * {@link MODULE_TIER} treatment either way.
+   */
+  tierOf?: (type: string) => TierInfo | null;
+  signalsFor?: (node: TfNode) => ScoreSignals;
 }
 
 const clamp = (n: number): number => Math.max(0, Math.min(100, n));
 
+/**
+ * `-12 * 0` is `-0`, and JSON has no notation for it — a report written to a
+ * file would not equal the one held in memory. A term that costs nothing is 0.
+ */
+const term = (n: number): number => (n === 0 ? 0 : n);
+
 export function bandFor(score: number): PeelabilityBand {
   if (score >= 80) return "clean leaf";
   if (score >= 50) return "carvable w/ edits";
@@ -81,7 +155,7 @@ function computeFolds(graph: TfGraph): { folded: Set<string>; childrenOf: Map<st
   const childrenOf = new Map<string, Set<string>>();
   for (const node of graph.nodes) {
     if (node.kind !== "resource" || !node.type) continue;
-    const parentType = FOLDS_INTO[node.type];
+    const parentType = foldParentOf(node.type);
     if (!parentType) continue;
     const parentAddress = `${parentType}.${node.name}`;
     if (!byAddress.has(parentAddress)) continue; // sub-resource without its parent → score it on its own
@@ -92,7 +166,12 @@ function computeFolds(graph: TfGraph): { folded: Set<string>; childrenOf: Map<st
   return { folded, childrenOf };
 }
 
-function scoreNode(node: TfNode, graph: TfGraph, foldedChildren: Set<string>): Peelability {
+function scoreNode(
+  node: TfNode,
+  graph: TfGraph,
+  foldedChildren: Set<string>,
+  opts: ScoreOptions,
+): Peelability {
   // Inbound excludes edges from this node's own folded sub-resources, and
   // counts output blocks separately — they cost less to bridge (#1638).
   const inboundAll = inboundEdges(graph, node.address).filter((e) => !foldedChildren.has(e.from));
@@ -100,45 +179,51 @@ function scoreNode(node: TfNode, graph: TfGraph, foldedChildren: Set<string>): P
   const outputs = inboundAll.length - inbound;
   const outbound = outboundEdges(graph, node.address).length;
 
-  const tierInfo = node.kind === "module" ? { tier: MODULE_TIER, mapsTo: undefined } : resolveTier(node.type!);
+  const signals = opts.signalsFor?.(node) ?? {};
+  const extra = { ...(signals.penalties ?? {}) };
+  const trimmings = {
+    ...(signals.notes?.length ? { notes: signals.notes } : {}),
+    ...(signals.members?.length ? { members: signals.members } : {}),
+  };
+
+  const tierOf = opts.tierOf ?? resolveTier;
+  const tierInfo = node.kind === "module" ? { tier: MODULE_TIER, mapsTo: undefined } : node.type ? tierOf(node.type) : null;
   const tier = tierInfo ? tierInfo.tier : null;
 
-  // Unsupported provider/type → 0, no partial credit.
-  if (tier === null) {
+  // Unsupported provider/type, or a source-specific disqualification → 0, no
+  // partial credit. The extra penalties are dropped with the rest of the
+  // arithmetic: there is no score left for them to reduce.
+  if (tier === null || signals.disqualified) {
     return {
       address: node.address,
       kind: node.kind,
       score: 0,
       band: "leave in Terraform",
+      ...(tier === null ? {} : { mapsTo: tierInfo && "mapsTo" in tierInfo ? tierInfo.mapsTo : undefined }),
       breakdown: {
         inbound,
         outbound,
         outputs,
-        tier: null,
+        tier,
         hasDynamic: node.hasDynamic,
         instances: node.instances,
         penalties: { inbound: 0, outbound: 0, outputs: 0, tier: 0, dynamic: 0, instances: 0 },
       },
+      ...trimmings,
+      ...(signals.disqualified ? { notes: [signals.disqualified, ...(signals.notes ?? [])] } : {}),
     };
   }
 
   const penalties = {
-    inbound: -12 * inbound,
-    outbound: -4 * outbound,
-    outputs: -4 * outputs,
-    tier: -15 * (tier - 1),
+    inbound: term(-12 * inbound),
+    outbound: term(-4 * outbound),
+    outputs: term(-4 * outputs),
+    tier: term(-15 * (tier - 1)),
     dynamic: node.hasDynamic ? -10 : 0,
-    instances: -3 * Math.max(0, node.instances - 1),
+    instances: term(-3 * Math.max(0, node.instances - 1)),
+    ...Object.fromEntries(Object.entries(extra).map(([key, value]) => [key, term(value)])),
   };
-  const score = clamp(
-    100 +
-      penalties.inbound +
-      penalties.outbound +
-      penalties.outputs +
-      penalties.tier +
-      penalties.dynamic +
-      penalties.instances,
-  );
+  const score = clamp(100 + Object.values(penalties).reduce((sum, n) => sum + n, 0));
 
   return {
     address: node.address,
@@ -155,6 +240,7 @@ function scoreNode(node: TfNode, graph: TfGraph, foldedChildren: Set<string>): P
       instances: node.instances,
       penalties,
     },
+    ...trimmings,
   };
 }
 
@@ -162,10 +248,10 @@ function scoreNode(node: TfNode, graph: TfGraph, foldedChildren: Set<string>): P
  * Score every carvable node in the estate, ranked most-peelable first. Folded
  * sub-resources are omitted (they carve with their parent, not on their own).
  */
-export function scoreEstate(graph: TfGraph): Peelability[] {
+export function scoreEstate(graph: TfGraph, opts: ScoreOptions = {}): Peelability[] {
   const { folded, childrenOf } = computeFolds(graph);
   return graph.nodes
     .filter((n) => !folded.has(n.address))
-    .map((n) => scoreNode(n, graph, childrenOf.get(n.address) ?? new Set()))
+    .map((n) => scoreNode(n, graph, childrenOf.get(n.address) ?? new Set(), opts))
     .sort((a, b) => b.score - a.score || (a.address < b.address ? -1 : a.address > b.address ? 1 : 0));
 }

package/src/terraform/tier-map.ts

@@ -1,139 +1,77 @@
 /**
- * Terraform-type → native-spec tier map for the carve-out advisor (#214 T3).
+ * Terraform-type → native-spec ranking for the carve-out advisor (#214 T3),
+ * resolved through the carve provider registry (`carve-provider.ts`, #2016).
  *
- * The AWS entries are derived from the single AWS carve-out table
- * (`aws-resources.ts`), so the advisor ranks exactly the AWS types `carve emit`
- * can produce — no advise↔emit cliff. Non-AWS entries (e.g. `kubernetes_manifest`)
- * are listed here directly; emit for those is a separate target.
+ * Every entry comes from a registered provider: the AWS ones from the single
+ * AWS carve-out table (`providers/aws.ts` over `aws-resources.ts`), so the
+ * advisor ranks exactly the AWS types `carve emit` can produce — no advise↔emit
+ * cliff — and the Kubernetes ones from `providers/kubernetes.ts`, which emits
+ * `kubernetes_manifest` and ranks the typed provider resources it does not.
  *
  *   tier 1 — a clean 1:1 native resource
  *   tier 2 — maps, but with reshaping
  *   tier 3 — a hard/partial map
  *   null   — no known native mapping (unsupported provider/type) → score 0
+ *
+ * These are functions, not frozen constants: the registry is open, so a
+ * provider registered after module load has to be visible here.
  */
 
-import { AWS_CARVE_TYPES, awsCarveType } from "./aws-resources";
-
-export interface TierInfo {
-  tier: 1 | 2 | 3;
-  /** The native spec type a carve would target, for the report. */
-  mapsTo: string;
-}
+import {
+  carveFoldParent,
+  carveIdentityAttr,
+  carveTierMap,
+  resolveEmitProvider,
+  type TierInfo,
+} from "./carve-provider";
 
-/**
- * Kubernetes provider types with a native k8s-lexicon target. `kubernetes_manifest`
- * IS the manifest (tier 1). The typed provider resources (`kubernetes_deployment`,
- * ...) reshape their HCL schema back into a manifest, so they rank tier 2; the
- * common `_v1` aliases share their base type's entry.
- */
-const K8S_TIER_BASE: Record<string, TierInfo> = {
-  kubernetes_manifest: { tier: 1, mapsTo: "k8s:manifest" },
-  kubernetes_namespace: { tier: 2, mapsTo: "k8s:Namespace" },
-  kubernetes_config_map: { tier: 2, mapsTo: "k8s:ConfigMap" },
-  kubernetes_secret: { tier: 2, mapsTo: "k8s:Secret" },
-  kubernetes_service: { tier: 2, mapsTo: "k8s:Service" },
-  kubernetes_service_account: { tier: 2, mapsTo: "k8s:ServiceAccount" },
-  kubernetes_deployment: { tier: 2, mapsTo: "k8s:Deployment" },
-  kubernetes_stateful_set: { tier: 2, mapsTo: "k8s:StatefulSet" },
-  kubernetes_daemon_set: { tier: 2, mapsTo: "k8s:DaemonSet" },
-  kubernetes_job: { tier: 2, mapsTo: "k8s:Job" },
-  kubernetes_cron_job: { tier: 2, mapsTo: "k8s:CronJob" },
-  kubernetes_ingress: { tier: 2, mapsTo: "k8s:Ingress" },
-  kubernetes_network_policy: { tier: 2, mapsTo: "k8s:NetworkPolicy" },
-  kubernetes_persistent_volume_claim: { tier: 2, mapsTo: "k8s:PersistentVolumeClaim" },
-  kubernetes_role: { tier: 2, mapsTo: "k8s:Role" },
-  kubernetes_role_binding: { tier: 2, mapsTo: "k8s:RoleBinding" },
-  kubernetes_cluster_role: { tier: 2, mapsTo: "k8s:ClusterRole" },
-  kubernetes_cluster_role_binding: { tier: 2, mapsTo: "k8s:ClusterRoleBinding" },
-  kubernetes_resource_quota: { tier: 2, mapsTo: "k8s:ResourceQuota" },
-  kubernetes_limit_range: { tier: 2, mapsTo: "k8s:LimitRange" },
-  kubernetes_priority_class: { tier: 2, mapsTo: "k8s:PriorityClass" },
-  kubernetes_pod_disruption_budget: { tier: 2, mapsTo: "k8s:PodDisruptionBudget" },
-  kubernetes_horizontal_pod_autoscaler: { tier: 2, mapsTo: "k8s:HorizontalPodAutoscaler" },
-};
+export { carveEmitTypes, type TierInfo } from "./carve-provider";
 
-const K8S_TIER: Record<string, TierInfo> = Object.fromEntries(
-  Object.entries(K8S_TIER_BASE).flatMap(([type, info]) =>
-    type === "kubernetes_manifest" ? [[type, info]] : [[type, info], [`${type}_v1`, info]],
-  ),
-);
-// The one provider type whose current alias is _v2, not _v1.
-K8S_TIER.kubernetes_horizontal_pod_autoscaler_v2 = K8S_TIER_BASE.kubernetes_horizontal_pod_autoscaler;
+/** TF resource type → native tier, over every registered provider. Absent = unsupported (score 0). */
+export function tierMap(): Readonly<Record<string, TierInfo>> {
+  return carveTierMap();
+}
 
-/** TF resource type → native tier. Absent = unsupported (score 0). */
-export const TIER_MAP: Record<string, TierInfo> = {
-  // AWS: derived from the carve-out table so advise and emit stay in lockstep.
-  ...Object.fromEntries(AWS_CARVE_TYPES.map((t) => [t.tfType, { tier: t.tier, mapsTo: t.nativeType }])),
-  // Kubernetes — ranked by advise; emit support is a separate target.
-  ...K8S_TIER,
-};
+export function resolveTier(tfType: string): TierInfo | null {
+  return carveTierMap()[tfType] ?? null;
+}
 
 /**
- * TF "sub-resource" types that inline into a parent resource rather than
- * standing alone (TF splits config the native spec keeps in one resource).
- * A sub-resource that shares its parent's name is folded into the parent's
- * carve set: it is not ranked on its own, and its edge to the parent does not
- * count as inbound boundary work — inlining it is free.
- *
- * Maps sub-resource TF type → parent TF type.
+ * The HCL attribute carrying a resource's physical name. A dotted entry is a
+ * path into nested blocks (`manifest.metadata.name`). Used for the graph's
+ * identity and the live-import hint. Absent → fall back to the TF logical name.
  */
-export const FOLDS_INTO: Record<string, string> = {
-  aws_s3_bucket_versioning: "aws_s3_bucket",
-  aws_s3_bucket_acl: "aws_s3_bucket",
-  aws_s3_bucket_policy: "aws_s3_bucket",
-  aws_s3_bucket_public_access_block: "aws_s3_bucket",
-  aws_s3_bucket_server_side_encryption_configuration: "aws_s3_bucket",
-  aws_s3_bucket_lifecycle_configuration: "aws_s3_bucket",
-  aws_s3_bucket_website_configuration: "aws_s3_bucket",
-  aws_s3_bucket_cors_configuration: "aws_s3_bucket",
-  aws_s3_bucket_logging: "aws_s3_bucket",
-  aws_s3_bucket_ownership_controls: "aws_s3_bucket",
-  aws_s3_bucket_notification: "aws_s3_bucket",
-  aws_s3_bucket_accelerate_configuration: "aws_s3_bucket",
-  aws_s3_bucket_request_payment_configuration: "aws_s3_bucket",
-  aws_s3_bucket_intelligent_tiering_configuration: "aws_s3_bucket",
-  aws_ecr_lifecycle_policy: "aws_ecr_repository",
-  aws_ecr_repository_policy: "aws_ecr_repository",
-};
+export function identityAttrOf(tfType: string): string | undefined {
+  return carveIdentityAttr(tfType);
+}
 
 /**
- * The HCL attribute carrying a resource's physical name, per type — AWS entries
- * derived from the carve-out table, non-AWS listed directly. A dotted entry is
- * a path into nested blocks (`manifest.metadata.name`). Used for the graph's
- * identity and the live-import hint. Absent → fall back to the TF logical name.
+ * The parent Terraform type a sub-resource folds into, if any. Terraform splits
+ * configuration the native spec keeps in one resource; a sub-resource sharing
+ * its parent's name carves with the parent rather than being ranked on its own.
  */
-export const IDENTITY_ATTR: Record<string, string> = {
-  ...Object.fromEntries(AWS_CARVE_TYPES.filter((t) => t.identityAttr).map((t) => [t.tfType, t.identityAttr!])),
-  kubernetes_manifest: "manifest.metadata.name",
-};
-
-export function resolveTier(tfType: string): TierInfo | null {
-  return TIER_MAP[tfType] ?? null;
+export function foldParentOf(tfType: string): string | undefined {
+  return carveFoldParent(tfType);
 }
 
 /**
  * Can `chant carve emit` produce chant source for this type? Narrower than
- * `resolveTier`: the tier map also ranks the kubernetes types, which advise
- * bands but no emit path can adopt (#999, blocked on the provider seam #2016).
- * Both emit paths — `--state` and `--env` — gate on this, so a type either
- * command refuses is refused by the other with the same message.
+ * `resolveTier`: providers also rank types no emit path can adopt (the typed
+ * `kubernetes_*` resources, whose manifest only the provider schema knows how
+ * to reassemble). Both emit paths — `--state` and `--env` — gate on this, so a
+ * type either command refuses is refused by the other with the same message.
  */
 export function canCarveEmit(tfType: string): boolean {
-  return awsCarveType(tfType) !== undefined;
-}
-
-/** The types `canCarveEmit` accepts, sorted, for user-facing hints. */
-export function carveEmitTypes(): string[] {
-  return AWS_CARVE_TYPES.map((t) => t.tfType).sort();
+  return resolveEmitProvider(tfType) !== undefined;
 }
 
 /**
  * Can `chant carve bridge` render a Terraform `data` source for this type? A
- * dotted `IDENTITY_ATTR` is a path into nested blocks, and a data source body
- * is flat `attr = value` — `manifest.metadata.name = "x"` is not valid HCL.
- * An absent entry is fine: the bridge writes a TODO comment for the identity.
+ * dotted identity attribute is a path into nested blocks, and a data source
+ * body is flat `attr = value` — `manifest.metadata.name = "x"` is not valid
+ * HCL. An absent entry is fine: the bridge writes a TODO comment instead.
  */
 export function canBridge(tfType: string): boolean {
-  const attr = IDENTITY_ATTR[tfType];
+  const attr = carveIdentityAttr(tfType);
   return attr === undefined || !attr.includes(".");
 }

package/src/terraform/types.ts

@@ -64,6 +64,12 @@ export interface TfEdge {
    * parameter. Empty when the reference came from a non-object block shape.
    */
   via: string[];
+  /**
+   * The two ends live in different templates — a CloudFormation
+   * `Fn::ImportValue` resolved through the exporting stack's `Outputs` (#1056).
+   * Never set on the Terraform path, where a single estate is one namespace.
+   */
+  crossStack?: boolean;
 }
 
 export interface TfGraph {