@cdktn/provider-generator 0.24.0-pre.71 → 0.24.0-pre.73

package/src/get/generator/emitter/attributes-emitter.ts

@@ -1,8 +1,13 @@
 // Copyright (c) HashiCorp, Inc
 // SPDX-License-Identifier: MPL-2.0
 import { CodeMaker } from "codemaker";
-import { AttributeModel } from "../models";
+import {
+  AttributeModel,
+  CollectionAttributeTypeModel,
+  describeTerraformType,
+} from "../models";
 import { CUSTOM_DEFAULTS } from "../custom-defaults";
+import { sanitizedComment } from "../sanitized-comments";
 
 function titleCase(value: string) {
   return value[0].toUpperCase() + value.slice(1);
@@ -34,6 +39,8 @@ export class AttributesEmitter {
       );
     }
 
+    this.emitStoredClassBoundaryDoc(att);
+
     switch (getterType._type) {
       case "plain":
         this.code.openBlock(`public get ${att.name}()`);
@@ -121,6 +128,35 @@ export class AttributesEmitter {
     return att.type.getStoredClassInitializer(att.terraformName);
   }
 
+  // Emits a JSDoc block documenting the Terraform type immediately before getters whose
+  // stored class either collapsed a deeper, unsupported nesting into the nearest typed
+  // "Any"-wrapper, or fell all the way back to a plain, untyped getter because no stored
+  // class (not even a collapsed one) is available. Normal, fully-supported getters get no
+  // such doc, to limit snapshot churn.
+  private emitStoredClassBoundaryDoc(att: AttributeModel) {
+    const boundaryKind = att.storedClassBoundaryKind;
+    if (!boundaryKind) {
+      return;
+    }
+
+    const comment = sanitizedComment(this.code);
+    comment.line(`Terraform type: \`${describeTerraformType(att.type)}\`.`);
+
+    if (boundaryKind === "collapsed") {
+      const collapsedName = (att.type as CollectionAttributeTypeModel)
+        .resolvedStoredClass!.name;
+      comment.line(
+        `This nesting is deeper than the typed wrapper classes in the core cdktn package; it is exposed as \`${collapsedName}\` and values below that boundary are untyped tokens.`,
+      );
+    } else {
+      comment.line(
+        `No typed wrapper class for this shape exists in the core cdktn package; the value is returned as an untyped token (IResolvable).`,
+      );
+    }
+
+    comment.end();
+  }
+
   public determineGetAttCall(att: AttributeModel): string {
     if (att.isProvider) {
       return `this.${att.storageName}`;

package/src/get/generator/models/attribute-model.ts

@@ -1,6 +1,10 @@
 // Copyright (c) HashiCorp, Inc
 // SPDX-License-Identifier: MPL-2.0
-import { AttributeTypeModel } from "./attribute-type-model";
+import { logger } from "@cdktn/commons";
+import {
+  AttributeTypeModel,
+  CollectionAttributeTypeModel,
+} from "./attribute-type-model";
 
 export type GetterType =
   | { _type: "plain" }
@@ -69,6 +73,7 @@ export class AttributeModel {
   public provider: boolean;
   public required: boolean;
   public forcePlainGetterType?: boolean;
+  private loggedStoredClassUnavailable = false;
 
   constructor(options: AttributeModelOptions) {
     this.storageName = options.storageName;
@@ -125,14 +130,63 @@ export class AttributeModel {
       !this.isAssignable &&
       (!this.type.isTokenizable || this.type.typeModelType === "map")
     ) {
-      getterType = {
-        _type: "stored_class",
-      };
+      if (this.type.isStoredClassUnavailable) {
+        // Defensive fallback: neither the composed stored class name (e.g.
+        // "StringListMapMap") nor a collapsed nearest-Any wrapper (e.g. "AnyMapMap")
+        // exists in the core cdktn package for this type. This should be rare - see
+        // resolveStoredClassName in supported-stored-classes.ts - so log it loudly to
+        // make regressions in the collapse logic visible.
+        if (!this.loggedStoredClassUnavailable) {
+          this.loggedStoredClassUnavailable = true;
+          logger.debug(
+            `No stored class (not even a collapsed nearest-Any wrapper) is available for computed attribute "${this.terraformFullName}" (composed storedClassType: "${this.type.storedClassType}"). Falling back to a plain, untyped getter.`,
+          );
+        }
+      } else {
+        getterType = {
+          _type: "stored_class",
+        };
+      }
     }
 
     return getterType;
   }
 
+  // Reports whether this attribute's getter sits at a "stored class boundary" that is
+  // worth documenting: "collapsed" when a deeper, unsupported nesting was collapsed into
+  // the nearest typed "Any"-wrapper (e.g. "AnyMapMap"), or "fallback" when no stored class
+  // at all is available and a plain, untyped getter is emitted instead. Mirrors the same
+  // condition tree as getterType above, so it only ever reports a boundary for attributes
+  // that actually went through that computed-collection branch - plain getters for
+  // ordinary tokenizable types (e.g. list(string)) are never flagged.
+  public get storedClassBoundaryKind(): "collapsed" | "fallback" | undefined {
+    if (this.forcePlainGetterType || this.isProvider) {
+      return undefined;
+    }
+
+    if (this.type.hasReferenceClass) {
+      return undefined;
+    }
+
+    if (
+      this.computed &&
+      !this.isAssignable &&
+      (!this.type.isTokenizable || this.type.typeModelType === "map")
+    ) {
+      if (this.type.isStoredClassUnavailable) {
+        return "fallback";
+      }
+
+      const resolvedStoredClass = (this.type as CollectionAttributeTypeModel)
+        .resolvedStoredClass;
+      if (resolvedStoredClass?.collapsed) {
+        return "collapsed";
+      }
+    }
+
+    return undefined;
+  }
+
   public get isStored(): boolean {
     return this.isAssignable;
   }

package/src/get/generator/models/attribute-type-model.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MPL-2.0
 import { Struct } from "./struct";
 import { uppercaseFirst, downcaseFirst } from "../../../util";
+import { resolveStoredClassName } from "./supported-stored-classes";
 
 export interface AttributeTypeModel {
   readonly struct?: Struct; // complex object type contained within the type
@@ -15,6 +16,37 @@ export interface AttributeTypeModel {
   readonly typeModelType: string; // so we don't need to use instanceof
   readonly hasReferenceClass: boolean; // used to determine if a stored_class getter should be used
   readonly isTokenizable: boolean; // can the type be represented by a token type
+  readonly isStoredClassUnavailable: boolean; // true when no "cdktn.<Name>" stored class (not even a collapsed nearest-Any wrapper) is available for this type
+}
+
+// Describes the Terraform type of an attribute as its `list(...)`/`set(...)`/`map(...)`
+// composed notation (matching how Terraform itself describes nested collection types),
+// for use in generated JSDoc. Used only for collapsed/fallback getters (see
+// AttributesEmitter) so it never needs to be exhaustive/perfectly stable for every shape.
+export function describeTerraformType(model: AttributeTypeModel): string {
+  switch (model.typeModelType) {
+    case "list":
+      return `list(${describeTerraformType(
+        (model as CollectionAttributeTypeModel).elementType,
+      )})`;
+    case "set":
+      return `set(${describeTerraformType(
+        (model as CollectionAttributeTypeModel).elementType,
+      )})`;
+    case "map":
+      return `map(${describeTerraformType(
+        (model as CollectionAttributeTypeModel).elementType,
+      )})`;
+    case "struct":
+      return "object";
+    default:
+      // Covers both SimpleAttributeTypeModel (storedClassType is the Terraform primitive
+      // name, e.g. "string" | "number" | "boolean" | "any") and SkippedAttributeTypeModel
+      // (storedClassType is always "any").
+      return model.storedClassType === "boolean"
+        ? "bool"
+        : model.storedClassType;
+  }
 }
 
 export class SkippedAttributeTypeModel implements AttributeTypeModel {
@@ -64,6 +96,10 @@ export class SkippedAttributeTypeModel implements AttributeTypeModel {
   get isTokenizable() {
     return false;
   }
+
+  get isStoredClassUnavailable() {
+    return false;
+  }
 }
 
 export class SimpleAttributeTypeModel implements AttributeTypeModel {
@@ -117,6 +153,10 @@ export class SimpleAttributeTypeModel implements AttributeTypeModel {
   get isTokenizable() {
     return true;
   }
+
+  get isStoredClassUnavailable() {
+    return false;
+  }
 }
 
 export class StructAttributeTypeModel implements AttributeTypeModel {
@@ -162,10 +202,21 @@ export class StructAttributeTypeModel implements AttributeTypeModel {
   get isTokenizable() {
     return false;
   }
+
+  get isStoredClassUnavailable() {
+    return false;
+  }
 }
 
 export interface CollectionAttributeTypeModel extends AttributeTypeModel {
   elementType: AttributeTypeModel;
+  // Resolves the "cdktn.<name>" stored class to instantiate for this (non-complex)
+  // collection type, and whether that resolution collapsed a deeper, unsupported nesting
+  // into the nearest typed "Any"-wrapper. undefined only defensively - see
+  // resolveStoredClassName in supported-stored-classes.ts.
+  readonly resolvedStoredClass:
+    | { name: string; collapsed: boolean }
+    | undefined;
 }
 
 export class ListAttributeTypeModel implements CollectionAttributeTypeModel {
@@ -198,9 +249,7 @@ export class ListAttributeTypeModel implements CollectionAttributeTypeModel {
       if (this.isComplex) {
         return `new ${this.storedClassType}(this, "${name}", false)`;
       } else {
-        return `new cdktn.${uppercaseFirst(
-          this.storedClassType,
-        )}(this, "${name}", false)`;
+        return `new cdktn.${this.resolvedStoredClass!.name}(this, "${name}", false)`;
       }
     }
   }
@@ -209,6 +258,13 @@ export class ListAttributeTypeModel implements CollectionAttributeTypeModel {
     return `${this.elementType.storedClassType}List`;
   }
 
+  get resolvedStoredClass() {
+    return resolveStoredClassName(
+      this.storedClassType,
+      this.elementType.typeModelType,
+    );
+  }
+
   get inputTypeDefinition() {
     if (this.isSingleItem) {
       return this.elementType.inputTypeDefinition;
@@ -263,6 +319,34 @@ export class ListAttributeTypeModel implements CollectionAttributeTypeModel {
         return false;
     }
   }
+
+  // Complex (struct) elements generate their own class in the provider output, so they
+  // are always fine. Otherwise a stored class is only emitted if resolvedStoredClass
+  // finds one - see getStoredClassInitializer above. Note: hasReferenceClass (which
+  // triggers a stored_class getter) is only ever true here when isSingleItem or isComplex
+  // is true, and isSingleItem is only set for struct/block nesting (which is also
+  // isComplex), so this check only needs to guard the non-complex, non-single-item case.
+  //
+  // storedClassType is itself built up recursively (elementType.storedClassType is
+  // composed the same way for nested collections), so it already fully encodes the
+  // entire nested chain in one string (e.g. map(map(list(string))) composes all the way
+  // up to "stringListMapMap"). resolvedStoredClass first checks this type's own composed
+  // name (e.g. "StringListMapMap") against the fixed set of hand-written core classes; if
+  // that name doesn't exist, it falls back to the nearest typed "Any"-wrapper that still
+  // encodes this type's own layer and its element's layer (e.g. "AnyMapMap"), collapsing
+  // only the unsupported inner shape while preserving typed navigation for the outer
+  // layers; only if neither exists does it fall through to the plain, untyped getter (see
+  // AttributeModel.getterType). It must NOT also OR in
+  // elementType.isStoredClassUnavailable, since an inner element's un-composed name (e.g.
+  // "StringList" for a plain list(string) nested inside a map) is never separately
+  // instantiated and is irrelevant on its own; ORing it in would produce false positives
+  // that regress supported nestings such as map(list(string)) => cdktn.StringListMap.
+  get isStoredClassUnavailable() {
+    if (this.isComplex) {
+      return false;
+    }
+    return this.resolvedStoredClass === undefined;
+  }
 }
 
 export class SetAttributeTypeModel implements CollectionAttributeTypeModel {
@@ -295,9 +379,7 @@ export class SetAttributeTypeModel implements CollectionAttributeTypeModel {
       if (this.isComplex) {
         return `new ${this.storedClassType}(this, "${name}", true)`;
       } else {
-        return `new cdktn.${uppercaseFirst(
-          this.storedClassType,
-        )}(this, "${name}", true)`;
+        return `new cdktn.${this.resolvedStoredClass!.name}(this, "${name}", true)`;
       }
     }
   }
@@ -306,6 +388,13 @@ export class SetAttributeTypeModel implements CollectionAttributeTypeModel {
     return `${this.elementType.storedClassType}List`;
   }
 
+  get resolvedStoredClass() {
+    return resolveStoredClassName(
+      this.storedClassType,
+      this.elementType.typeModelType,
+    );
+  }
+
   get inputTypeDefinition() {
     if (this.isSingleItem) {
       return this.elementType.inputTypeDefinition;
@@ -365,6 +454,15 @@ export class SetAttributeTypeModel implements CollectionAttributeTypeModel {
         return false;
     }
   }
+
+  // See comment on ListAttributeTypeModel.isStoredClassUnavailable above - same
+  // reasoning applies here.
+  get isStoredClassUnavailable() {
+    if (this.isComplex) {
+      return false;
+    }
+    return this.resolvedStoredClass === undefined;
+  }
 }
 
 export class MapAttributeTypeModel implements CollectionAttributeTypeModel {
@@ -386,9 +484,7 @@ export class MapAttributeTypeModel implements CollectionAttributeTypeModel {
     if (this.isComplex) {
       return `new ${this.storedClassType}(this, "${name}")`;
     } else {
-      return `new cdktn.${uppercaseFirst(
-        this.storedClassType,
-      )}(this, "${name}")`;
+      return `new cdktn.${this.resolvedStoredClass!.name}(this, "${name}")`;
     }
   }
 
@@ -396,6 +492,13 @@ export class MapAttributeTypeModel implements CollectionAttributeTypeModel {
     return `${this.elementType.storedClassType}Map`;
   }
 
+  get resolvedStoredClass() {
+    return resolveStoredClassName(
+      this.storedClassType,
+      this.elementType.typeModelType,
+    );
+  }
+
   get inputTypeDefinition() {
     // map of booleans has token support, but booleans don't
     if (this.elementType.storedClassType === "boolean") {
@@ -445,4 +548,13 @@ export class MapAttributeTypeModel implements CollectionAttributeTypeModel {
         return false;
     }
   }
+
+  // See comment on ListAttributeTypeModel.isStoredClassUnavailable above - same
+  // reasoning applies here (MapAttributeTypeModel.hasReferenceClass is just isComplex).
+  get isStoredClassUnavailable() {
+    if (this.isComplex) {
+      return false;
+    }
+    return this.resolvedStoredClass === undefined;
+  }
 }

package/src/get/generator/models/supported-stored-classes.ts

@@ -0,0 +1,88 @@
+// Copyright (c) HashiCorp, Inc
+// SPDX-License-Identifier: MPL-2.0
+import { uppercaseFirst } from "../../../util";
+
+// The core cdktn package (packages/cdktn/src/complex-computed-list.ts) only hand-writes
+// this fixed set of wrapper classes for computed, non-complex collection attributes.
+// Arbitrarily deep nestings of list/set/map (e.g. map(map(list(string)))) compose a
+// storedClassType (e.g. "stringListMapMap") that has no corresponding class. Rather than
+// falling back straight to a plain, untyped getter, resolveStoredClassName below first
+// looks for the nearest typed "Any"-wrapper that still exists in this set, collapsing the
+// unsupported inner shape into an untyped boundary while preserving typed navigation for
+// the outer layers (see https://github.com/open-constructs/cdk-terrain/issues/11).
+const SUPPORTED_STORED_CLASSES = new Set([
+  "StringMap",
+  "NumberMap",
+  "BooleanMap",
+  "AnyMap",
+  "StringMapMap",
+  "NumberMapMap",
+  "BooleanMapMap",
+  "AnyMapMap",
+  "BooleanList",
+  "StringListList",
+  "NumberListList",
+  "BooleanListList",
+  "AnyListList",
+  "StringMapList",
+  "NumberMapList",
+  "BooleanMapList",
+  "AnyMapList",
+  "StringListMap",
+  "NumberListMap",
+  "BooleanListMap",
+  "AnyListMap",
+]);
+
+// Resolves the composed stored class name to use for a collection attribute (list/set/map)
+// whose element is itself a non-complex collection (or simple type).
+//
+// `ownStoredClassType` is this type's own composed storedClassType (e.g. "stringListMapMap"
+// for map(map(list(string)))) and `elementTypeModelType` is the element's typeModelType
+// ("list" | "set" | "map" | "simple" | ...).
+//
+// Resolution order:
+//   1. The own composed name (e.g. "StringListMapMap") - used as-is when it refers to a
+//      class that is hand-written in the core package (not collapsed).
+//   2. Otherwise, the nearest typed "Any"-wrapper that still encodes the outer two layers
+//      (this type's own layer and its element's layer), e.g. "AnyMapMap" - collapsing the
+//      unsupported inner shape into an untyped boundary while preserving typed navigation
+//      for the outer layers.
+//   3. Otherwise (defensively; every depth should resolve via 1 or 2), undefined - the
+//      caller must fall back to a plain, untyped getter.
+export function resolveStoredClassName(
+  ownStoredClassType: string,
+  elementTypeModelType: string,
+): { name: string; collapsed: boolean } | undefined {
+  const candidate1 = uppercaseFirst(ownStoredClassType);
+  if (SUPPORTED_STORED_CLASSES.has(candidate1)) {
+    return { name: candidate1, collapsed: false };
+  }
+
+  let ownLayer: "List" | "Map" | undefined;
+  if (ownStoredClassType.endsWith("List")) {
+    ownLayer = "List";
+  } else if (ownStoredClassType.endsWith("Map")) {
+    ownLayer = "Map";
+  }
+  if (!ownLayer) {
+    return undefined;
+  }
+
+  let innerLayer: "List" | "Map" | undefined;
+  if (elementTypeModelType === "list" || elementTypeModelType === "set") {
+    innerLayer = "List";
+  } else if (elementTypeModelType === "map") {
+    innerLayer = "Map";
+  }
+  if (!innerLayer) {
+    return undefined;
+  }
+
+  const candidate2 = `Any${innerLayer}${ownLayer}`;
+  if (SUPPORTED_STORED_CLASSES.has(candidate2)) {
+    return { name: candidate2, collapsed: true };
+  }
+
+  return undefined;
+}