@cdktn/provider-generator 0.24.0-pre.87 → 0.24.0-pre.89

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

@@ -43,12 +43,14 @@ export class AttributesEmitter {
 
     switch (getterType._type) {
       case "plain":
+        this.emitWriteOnlyGetterDeprecationNotice(att);
         this.code.openBlock(`public get ${att.name}()`);
         this.code.line(`return ${this.determineGetAttCall(att)};`);
         this.code.closeBlock();
         break;
 
       case "args":
+        this.emitWriteOnlyGetterDeprecationNotice(att);
         this.code.openBlock(
           `public ${att.name}(${getterType.args})${
             getterType.returnType ? ": " + getterType.returnType : ""
@@ -59,6 +61,7 @@ export class AttributesEmitter {
         break;
 
       case "stored_class":
+        this.emitWriteOnlyGetterDeprecationNotice(att);
         this.code.openBlock(`public get ${att.name}()`);
         this.code.line(`return this.${att.storageName};`);
         this.code.closeBlock();
@@ -67,6 +70,10 @@ export class AttributesEmitter {
 
     const setterType = att.setterType;
 
+    // Write-only usage is registered at resolve time instead (see
+    // #emitToTerraform/#emitToHclTerraform and
+    // TerraformResource#markWriteOnlyAttribute), so setters intentionally
+    // emit no registration call here: they only store the value.
     switch (setterType._type) {
       case "set":
         this.code.openBlock(
@@ -123,6 +130,21 @@ export class AttributesEmitter {
     }
   }
 
+  // emits a @deprecated JSDoc block above a write-only attribute's getter:
+  // providers never persist/return write-only values, so the state-backed
+  // getter always reads back null by protocol contract
+  private emitWriteOnlyGetterDeprecationNotice(att: AttributeModel) {
+    if (!att.isWriteOnly) {
+      return;
+    }
+
+    const comment = sanitizedComment(this.code);
+    comment.line(
+      "@deprecated Write-only: the provider never returns this value; reading it always yields null by protocol contract. The getter remains for compatibility and will be removed in a future prebuilt-provider major.",
+    );
+    comment.end();
+  }
+
   // returns an invocation of a stored class, e.g. 'new DeplotmentMetadataOutputReference(this, "metadata")'
   private storedClassInit(att: AttributeModel) {
     return att.type.getStoredClassInitializer(att.terraformName);
@@ -204,7 +226,20 @@ export class AttributesEmitter {
     }
   }
 
-  public emitToHclTerraform(att: AttributeModel, isStruct: boolean) {
+  /**
+   * @param canRegisterProviderFeatureUsage Whether this attribute's mapped
+   * value should be wrapped in `this.markWriteOnlyAttribute(...)` when it is
+   * write-only. Only true for attributes emitted on classes that extend
+   * TerraformResource (managed resources) - struct-level `xToTerraform`/
+   * `xToHclTerraform` functions are standalone functions with no `this` of
+   * that type, so they never pass this (see ResourceEmitter's
+   * `supportsWriteOnlyRegistration`).
+   */
+  public emitToHclTerraform(
+    att: AttributeModel,
+    isStruct: boolean,
+    canRegisterProviderFeatureUsage = false,
+  ) {
     const type = att.type;
     const context = isStruct ? "struct!" : "this";
     const name = isStruct ? att.name : att.storageName;
@@ -223,7 +258,15 @@ export class AttributesEmitter {
         ? `${varReference} === undefined ? ${customDefault} : `
         : "";
 
-    const value = `${defaultCheck}${type.toHclTerraformFunction}(${varReference})`;
+    const mappedValue = `${defaultCheck}${type.toHclTerraformFunction}(${varReference})`;
+    // markWriteOnlyAttribute() passes `undefined`/`null` straight through
+    // unwrapped, so this keeps the "remove undefined attributes" filter in
+    // the caller (which checks `value.value !== undefined`) working exactly
+    // as before for unset/cleared write-only attributes.
+    const value =
+      att.isWriteOnly && canRegisterProviderFeatureUsage
+        ? `this.markWriteOnlyAttribute(${mappedValue})`
+        : mappedValue;
     const isBlock = att.type.isComplex;
     const tt = att.type.typeModelType;
 
@@ -235,7 +278,11 @@ export class AttributesEmitter {
     this.code.close("},");
   }
 
-  public emitToTerraform(att: AttributeModel, isStruct: boolean) {
+  public emitToTerraform(
+    att: AttributeModel,
+    isStruct: boolean,
+    canRegisterProviderFeatureUsage = false,
+  ) {
     const type = att.type;
     const context = isStruct ? "struct!" : "this";
     const name = isStruct ? att.name : att.storageName;
@@ -254,8 +301,16 @@ export class AttributesEmitter {
         ? `${varReference} === undefined ? ${customDefault} : `
         : "";
 
-    this.code.line(
-      `${att.terraformName}: ${defaultCheck}${type.toTerraformFunction}(${varReference}),`,
-    );
+    const mappedValue = `${defaultCheck}${type.toTerraformFunction}(${varReference})`;
+    // markWriteOnlyAttribute() passes `undefined`/`null` straight through
+    // unwrapped, so an unset/cleared write-only attribute still vanishes
+    // from the returned object exactly as before (see the "skip undefined"
+    // step in tokens/private/resolve.ts).
+    const value =
+      att.isWriteOnly && canRegisterProviderFeatureUsage
+        ? `this.markWriteOnlyAttribute(${mappedValue})`
+        : mappedValue;
+
+    this.code.line(`${att.terraformName}: ${value},`);
   }
 }

package/src/get/generator/emitter/index.ts

@@ -1,5 +1,6 @@
 // Copyright (c) HashiCorp, Inc
 // SPDX-License-Identifier: MPL-2.0
 export * from "./attributes-emitter";
+export * from "./provider-functions-emitter";
 export * from "./resource-emitter";
 export * from "./struct-emitter";

package/src/get/generator/emitter/provider-functions-emitter.ts

@@ -0,0 +1,117 @@
+// Copyright (c) HashiCorp, Inc
+// SPDX-License-Identifier: MPL-2.0
+import { CodeMaker } from "codemaker";
+import {
+  ProviderFunctionModel,
+  ProviderFunctionsModel,
+} from "../models/provider-function-model";
+import { sanitizedComment } from "../sanitized-comments";
+
+const PROVIDER_LOCAL_NAME_JSDOC =
+  "The local name of the provider in required_providers; defaults to the registry short name. Override when the provider is declared under a different local name — aliases do not change the namespace, local names do.";
+
+export class ProviderFunctionsEmitter {
+  constructor(private readonly code: CodeMaker) {}
+
+  public emit(model: ProviderFunctionsModel) {
+    this.code.line(`import * as cdktn from 'cdktn';`);
+    this.code.line();
+    this.emitClass(model);
+  }
+
+  private emitClass(model: ProviderFunctionsModel) {
+    const comment = sanitizedComment(this.code);
+    comment.line(
+      `Provider-defined functions of the ${model.providerName} provider.`,
+    );
+    comment.end();
+    this.code.openBlock(`export class ${model.className}`);
+
+    this.emitConstructor();
+
+    for (const fn of model.functions) {
+      this.emitMethod(fn);
+    }
+
+    this.code.closeBlock();
+  }
+
+  private emitConstructor() {
+    // A TypeScript parameter property (`constructor(private readonly x: T)`)
+    // requires the compiler to synthesize a `this.x = x;` assignment - that's
+    // a real transform, not a type-only erasure, so it isn't recognized by
+    // Node's native type-stripping (`node file.ts` with no bundler/transpiler,
+    // e.g. `--experimental-strip-types`), which throws
+    // `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX` on sight of one. Declare the field
+    // and assign it in the constructor body instead, which strips cleanly.
+    this.code.line(`private readonly providerLocalName: string;`);
+    this.code.line();
+    const comment = sanitizedComment(this.code);
+    comment.line(`@param providerLocalName ${PROVIDER_LOCAL_NAME_JSDOC}`);
+    comment.end();
+    this.code.openBlock(`constructor(providerLocalName: string)`);
+    this.code.line(`this.providerLocalName = providerLocalName;`);
+    this.code.closeBlock();
+  }
+
+  private emitMethod(fn: ProviderFunctionModel) {
+    this.code.line();
+
+    const comment = sanitizedComment(this.code);
+    const description = fn.description ?? fn.summary;
+    if (description) comment.line(description);
+    if (fn.deprecationMessage) {
+      comment.line(`@deprecated ${fn.deprecationMessage}`);
+    }
+    // The variadic parameter's docstringType is already wrapped in
+    // `Array<...>` by buildFunctionModel (see provider-function-model.ts),
+    // so it shares this one `@param` emission path with every fixed
+    // parameter instead of needing its own wrapping here.
+    const allParameters = fn.variadicParameter
+      ? [...fn.parameters, fn.variadicParameter]
+      : fn.parameters;
+    for (const param of allParameters) {
+      // Official JSDoc grammar: only the type expression goes inside the
+      // braces; prose (the schema description plus any generated
+      // list/set/nullability guidance - see the model's `docstringNote`)
+      // follows the parameter name after ` - `.
+      const prose = [param.description, param.docstringNote]
+        .filter(Boolean)
+        .join(" ");
+      comment.line(
+        `@param {${param.docstringType}} ${param.name}${prose ? ` - ${prose}` : ""}`,
+      );
+    }
+    comment.line(
+      `@returns {${fn.returnDocstringType}}${fn.returnDocstringNote ? ` ${fn.returnDocstringNote}` : ""}`,
+    );
+    comment.end();
+
+    const methodParams = [
+      ...fn.parameters.map(
+        (p) => `${p.name}${p.optional ? "?" : ""}: ${p.tsType}`,
+      ),
+      ...(fn.variadicParameter
+        ? // `Array<T>` rather than `T[]`: for a union element type (e.g.
+          // `boolean | cdktn.IResolvable`), bare `T[]` binds as `boolean |
+          // (cdktn.IResolvable[])` instead of `(boolean | cdktn.IResolvable)[]`.
+          [
+            `${fn.variadicParameter.name}: Array<${fn.variadicParameter.tsType}>`,
+          ]
+        : []),
+    ];
+
+    const invokeArgs = [
+      ...fn.parameters.map((p) => p.name),
+      ...(fn.variadicParameter ? [`...${fn.variadicParameter.name}`] : []),
+    ];
+
+    const invokeExpression = `cdktn.TerraformProviderFunction.invoke(this.providerLocalName, "${fn.terraformName}", [${invokeArgs.join(", ")}])`;
+
+    this.code.openBlock(
+      `public ${fn.methodName}(${methodParams.join(", ")}): ${fn.returnTsType}`,
+    );
+    this.code.line(`return ${fn.wrapReturn(invokeExpression)};`);
+    this.code.closeBlock();
+  }
+}

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

@@ -8,12 +8,26 @@ import { sanitizedComment } from "../sanitized-comments";
 export class ResourceEmitter {
   attributesEmitter: AttributesEmitter;
 
-  constructor(private readonly code: CodeMaker) {
+  constructor(
+    private readonly code: CodeMaker,
+    private readonly importExtension: string,
+  ) {
     this.attributesEmitter = new AttributesEmitter(this.code);
   }
 
   public emit(resource: ResourceModel) {
     this.code.line();
+
+    if (resource.isProvider && resource.providerFunctionsModel) {
+      // Sibling-directory import: providers/<provider>/provider/index.ts
+      // (the emitted file) and providers/<provider>/provider-functions/
+      // index.ts are siblings under providers/<provider>/, so unlike the
+      // child-folder struct imports this one has to step up a level.
+      this.code.line(
+        `import { ${resource.providerFunctionsModel.className} } from '../provider-functions/index${this.importExtension}';`,
+      );
+    }
+
     const comment = sanitizedComment(this.code);
     comment.line(
       `Represents a {@link ${resource.linkToDocs} ${resource.terraformResourceType}}`,
@@ -26,8 +40,10 @@ export class ResourceEmitter {
     this.emitHeader("STATIC PROPERTIES");
     this.emitStaticProperties(resource);
 
-    this.emitHeader("STATIC Methods");
-    this.emitStaticMethods(resource);
+    if (!resource.isEphemeralResource) {
+      this.emitHeader("STATIC Methods");
+      this.emitStaticMethods(resource);
+    }
 
     this.emitHeader("INITIALIZER");
     this.emitInitializer(resource);
@@ -35,6 +51,11 @@ export class ResourceEmitter {
     this.emitHeader("ATTRIBUTES");
     this.emitResourceAttributes(resource);
 
+    if (resource.isProvider && resource.providerFunctionsModel) {
+      this.emitHeader("PROVIDER-DEFINED FUNCTIONS");
+      this.emitFunctionsGetter(resource.providerFunctionsModel);
+    }
+
     // synthesis
     this.emitHeader("SYNTHESIS");
     this.emitResourceSynthesis(resource);
@@ -43,6 +64,38 @@ export class ResourceEmitter {
     this.code.closeBlock(); // construct
   }
 
+  // Emits a memoized `functions` getter on a provider class that declares
+  // provider-defined functions. The local name to invoke functions under is
+  // derived from `this.terraformResourceType`, not baked in as the schema
+  // name constant: terraform-provider.ts keys both `required_providers` and
+  // the `provider` block directly off `terraformResourceType`, so whatever
+  // this instance's `terraformResourceType` is IS its correct
+  // required_providers local name (it already accounts for a `name`
+  // override in the cdktf.json provider constraint, see
+  // ConstructsMakerProviderTarget/TerraformProviderConstraint) - the
+  // instance always knows its own correct local name, so there is no need
+  // for a providerLocalName override parameter here.
+  private emitFunctionsGetter(
+    model: NonNullable<ResourceModel["providerFunctionsModel"]>,
+  ) {
+    this.code.line(`private _functions?: ${model.className};`);
+    this.code.line();
+
+    const comment = sanitizedComment(this.code);
+    comment.line(
+      `Provider-defined functions of the ${model.providerName} provider.`,
+    );
+    comment.end();
+    this.code.openBlock(`public get functions(): ${model.className}`);
+    this.code.openBlock(`if (!this._functions)`);
+    this.code.line(
+      `this._functions = new ${model.className}(this.terraformResourceType);`,
+    );
+    this.code.closeBlock();
+    this.code.line(`return this._functions;`);
+    this.code.closeBlock();
+  }
+
   private emitHeader(title: string) {
     this.code.line();
     this.code.line("// " + "=".repeat(title.length));
@@ -86,8 +139,13 @@ export class ResourceEmitter {
     );
     this.code.open(`const attrs = {`);
 
+    const registerWriteOnlyUsage = this.supportsWriteOnlyRegistration(resource);
     for (const att of resource.synthesizableAttributes) {
-      this.attributesEmitter.emitToHclTerraform(att, false);
+      this.attributesEmitter.emitToHclTerraform(
+        att,
+        false,
+        registerWriteOnlyUsage,
+      );
     }
 
     this.code.close(`};`);
@@ -112,14 +170,38 @@ export class ResourceEmitter {
     );
     this.code.open(`return {`);
 
+    const registerWriteOnlyUsage = this.supportsWriteOnlyRegistration(resource);
     for (const att of resource.synthesizableAttributes) {
-      this.attributesEmitter.emitToTerraform(att, false);
+      this.attributesEmitter.emitToTerraform(
+        att,
+        false,
+        registerWriteOnlyUsage,
+      );
     }
 
     this.code.close(`};`);
     this.code.closeBlock();
   }
 
+  // `markWriteOnlyAttribute` (called from generated `synthesizeAttributes()`/
+  // `synthesizeHclAttributes()` for write-only attributes, see
+  // AttributesEmitter#emitToTerraform/#emitToHclTerraform) lives on
+  // TerraformResource - so only managed resources can register write-only
+  // usage; data sources, providers, and ephemeral resources only get the
+  // deprecated getter.
+  //
+  // write-only is fundamentally a state concept - the value is passed to
+  // the provider but never persisted to state - so gating this on
+  // TerraformResource is a semantic choice, not a capability one: ephemeral
+  // resources have no state at all, and, consistent with that, no provider
+  // schema in the RFC-04 sweep (including vault's 16 ephemeral resources)
+  // marks an ephemeral attribute write_only. So ephemeral classes
+  // deliberately land in the same "getter only" bucket as data sources and
+  // providers.
+  private supportsWriteOnlyRegistration(resource: ResourceModel): boolean {
+    return resource.parentClassName === "TerraformResource";
+  }
+
   private emitResourceAttributes(resource: ResourceModel) {
     for (const att of resource.attributes) {
       this.attributesEmitter.emit(
@@ -136,7 +218,13 @@ export class ResourceEmitter {
     comment.line(
       `Create a new {@link ${resource.linkToDocs} ${
         resource.terraformResourceType
-      }} ${resource.isDataSource ? "Data Source" : "Resource"}`,
+      }} ${
+        resource.isDataSource
+          ? "Data Source"
+          : resource.isEphemeralResource
+            ? "Ephemeral Resource"
+            : "Resource"
+      }`,
     );
     comment.line(``);
     comment.line(`@param scope The scope in which to define this construct`);
@@ -151,6 +239,8 @@ export class ResourceEmitter {
 
     if (resource.isProvider) {
       this.emitProviderSuper(resource);
+    } else if (resource.isEphemeralResource) {
+      this.emitEphemeralResourceSuper(resource);
     } else {
       this.emitResourceSuper(resource);
     }
@@ -185,6 +275,20 @@ export class ResourceEmitter {
     this.code.close(`});`);
   }
 
+  private emitEphemeralResourceSuper(resource: ResourceModel) {
+    this.code.open(`super(scope, id, {`);
+    this.code.line(
+      `terraformResourceType: '${resource.terraformResourceType}',`,
+    );
+    this.emitTerraformGeneratorMetadata(resource);
+    this.code.line(`provider: config.provider,`);
+    this.code.line(`dependsOn: config.dependsOn,`);
+    this.code.line(`count: config.count,`);
+    this.code.line(`lifecycle: config.lifecycle,`);
+    this.code.line(`forEach: config.forEach`);
+    this.code.close(`});`);
+  }
+
   private emitProviderSuper(resource: ResourceModel) {
     this.code.open(`super(scope, id, {`);
     this.code.line(

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

@@ -37,6 +37,7 @@ export interface AttributeModelOptions {
   provider: boolean;
   required: boolean;
   forcePlainGetterType?: boolean; // used for skipping attribute type attributes that use the SkippedAttributeTypeModel which returns an interpolation and has no stored type
+  isWriteOnly?: boolean; // provider protocol write-only attribute: providers never persist/return its value, see RFC-04
 }
 
 export function escapeAttributeName(name: string) {
@@ -74,6 +75,7 @@ export class AttributeModel {
   public required: boolean;
   public forcePlainGetterType?: boolean;
   private loggedStoredClassUnavailable = false;
+  public isWriteOnly: boolean;
 
   constructor(options: AttributeModelOptions) {
     this.storageName = options.storageName;
@@ -87,6 +89,7 @@ export class AttributeModel {
     this.provider = options.provider;
     this.required = options.required;
     this.forcePlainGetterType = options.forcePlainGetterType;
+    this.isWriteOnly = !!options.isWriteOnly;
   }
 
   public get typeDefinition() {

package/src/get/generator/models/index.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MPL-2.0
 export * from "./attribute-model";
 export * from "./attribute-type-model";
+export * from "./provider-function-model";
 export * from "./resource-model";
 export * from "./scope";
 export * from "./struct";