@cdktn/provider-generator 0.24.0-pre.9 → 0.24.0-pre.91

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

@@ -0,0 +1,316 @@
+// Copyright (c) HashiCorp, Inc
+// SPDX-License-Identifier: MPL-2.0
+import { CodeMaker } from "codemaker";
+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);
+}
+
+export class AttributesEmitter {
+  constructor(private code: CodeMaker) {}
+
+  public emit(att: AttributeModel, escapeReset: boolean, escapeInput: boolean) {
+    this.code.line();
+    this.code.line(
+      `// ${att.terraformName} - computed: ${att.computed}, optional: ${att.isOptional}, required: ${att.isRequired}`,
+    );
+
+    const isStored = att.isStored;
+    const hasResetMethod =
+      isStored && !att.isRequired && att.setterType._type !== "none";
+    const hasInputMethod = isStored && att.setterType._type !== "none";
+
+    const getterType = att.getterType;
+
+    if (getterType._type === "stored_class") {
+      this.code.line(
+        `private ${att.storageName} = ${this.storedClassInit(att)};`,
+      );
+    } else if (isStored) {
+      this.code.line(
+        `private ${att.storageName}?: ${att.type.inputTypeDefinition}; `,
+      );
+    }
+
+    this.emitStoredClassBoundaryDoc(att);
+
+    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 : ""
+          }`,
+        );
+        this.code.line(`return ${getterType.returnStatement};`);
+        this.code.closeBlock();
+        break;
+
+      case "stored_class":
+        this.emitWriteOnlyGetterDeprecationNotice(att);
+        this.code.openBlock(`public get ${att.name}()`);
+        this.code.line(`return this.${att.storageName};`);
+        this.code.closeBlock();
+        break;
+    }
+
+    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(
+          `public set ${att.name}(value: ${setterType.type})`,
+        );
+        this.code.line(`this.${att.storageName} = value;`);
+        this.code.closeBlock();
+        break;
+
+      case "put":
+        this.code.openBlock(
+          `public put${titleCase(att.name)}(value: ${setterType.type})`,
+        );
+        this.code.line(`this.${att.storageName} = value;`);
+        this.code.closeBlock();
+        break;
+
+      case "stored_class":
+        this.code.openBlock(
+          `public put${titleCase(att.name)}(value: ${setterType.type})`,
+        );
+        this.code.line(`this.${att.storageName}.internalValue = value;`);
+        this.code.closeBlock();
+        break;
+    }
+
+    if (hasResetMethod) {
+      this.code.openBlock(
+        `public ${this.getResetName(att.name, escapeReset)}()`,
+      );
+
+      if (setterType._type === "stored_class") {
+        this.code.line(`this.${att.storageName}.internalValue = undefined;`);
+      } else {
+        this.code.line(`this.${att.storageName} = undefined;`);
+      }
+
+      this.code.closeBlock();
+    }
+
+    if (hasInputMethod) {
+      this.code.line(`// Temporarily expose input value. Use with caution.`);
+      this.code.openBlock(
+        `public get ${this.getInputName(att, escapeInput)}()`,
+      );
+
+      if (setterType._type === "stored_class") {
+        this.code.line(`return this.${att.storageName}.internalValue;`);
+      } else {
+        this.code.line(`return this.${att.storageName};`);
+      }
+
+      this.code.closeBlock();
+    }
+  }
+
+  // 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);
+  }
+
+  // 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}`;
+    }
+
+    return att.type.getAttributeAccessFunction(att.terraformName);
+  }
+
+  public needsInputEscape(
+    att: AttributeModel,
+    attributes: AttributeModel[],
+  ): boolean {
+    return (
+      attributes.find((a) =>
+        a.terraformName.match(`^${att.terraformName}_input$`),
+      ) instanceof AttributeModel
+    );
+  }
+
+  public getInputName(att: AttributeModel, escape: boolean) {
+    if (escape) {
+      return `${att.name}TfInput`;
+    } else {
+      return `${att.name}Input`;
+    }
+  }
+
+  public needsResetEscape(
+    att: AttributeModel,
+    attributes: AttributeModel[],
+  ): boolean {
+    return (
+      attributes.find((a) =>
+        a.terraformName.match(`^reset_${att.terraformName}$`),
+      ) instanceof AttributeModel
+    );
+  }
+
+  public getResetName(name: string, escape: boolean) {
+    if (!name) return name;
+    if (escape) {
+      return `resetTf${titleCase(name)}`;
+    } else {
+      return `reset${titleCase(name)}`;
+    }
+  }
+
+  /**
+   * @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;
+    const customDefault = CUSTOM_DEFAULTS[att.terraformFullName];
+
+    const varReference = `${context}.${name}${
+      !isStruct &&
+      type.isComplex &&
+      !att.isProvider &&
+      (type.struct?.isClass || att.getterType._type === "stored_class")
+        ? ".internalValue"
+        : ""
+    }`;
+    const defaultCheck =
+      customDefault !== undefined
+        ? `${varReference} === undefined ? ${customDefault} : `
+        : "";
+
+    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;
+
+    this.code.open(`${att.terraformName}: {`);
+    this.code.line(`value: ${value},`);
+    this.code.line(`isBlock: ${isBlock},`);
+    this.code.line(`type: "${tt}",`);
+    this.code.line(`storageClassType: "${att.type.storedClassType}",`);
+    this.code.close("},");
+  }
+
+  public emitToTerraform(
+    att: AttributeModel,
+    isStruct: boolean,
+    canRegisterProviderFeatureUsage = false,
+  ) {
+    const type = att.type;
+    const context = isStruct ? "struct!" : "this";
+    const name = isStruct ? att.name : att.storageName;
+    const customDefault = CUSTOM_DEFAULTS[att.terraformFullName];
+
+    const varReference = `${context}.${name}${
+      !isStruct &&
+      type.isComplex &&
+      !att.isProvider &&
+      (type.struct?.isClass || att.getterType._type === "stored_class")
+        ? ".internalValue"
+        : ""
+    }`;
+    const defaultCheck =
+      customDefault !== undefined
+        ? `${varReference} === undefined ? ${customDefault} : `
+        : "";
+
+    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

@@ -0,0 +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();
+  }
+}