@cdktn/provider-generator 0.25.0-pre.9 → 0.25.0

package/src/get/constructs-maker.ts

@@ -17,7 +17,11 @@ import {
   type LanguageOptions,
   type TerraformTargetVersions,
 } from "@cdktn/commons";
-import { DISPLAY_VERSION, Language } from "@cdktn/commons";
+import {
+  DISPLAY_VERSION,
+  Language,
+  registryForTargetVersions,
+} from "@cdktn/commons";
 import { TerraformProviderGenerator } from "./generator/provider-generator";
 import { ModuleGenerator } from "./generator/module-generator";
 import { glob } from "glob";
@@ -275,11 +279,13 @@ type ConstraintFile = {
   providers: Record<string, string>;
   cdktf: string;
   /**
-   * The project's declared targetVersions (cdktf.json), stamped for
-   * diagnostics/cache debugging. Purely informational - never read back to
-   * decide whether cached output is stale, since it doesn't affect the
-   * generated surface (the full surface is always generated; narrowing
-   * happens at synth).
+   * The project's declared targetVersions (cdktf.json). Read back by
+   * `filterAlreadyGenerated` to compare registry *classes*: which registry the
+   * generated docs links point at follows from this, so output produced for the
+   * other class is stale. The version ranges themselves do not affect the
+   * generated surface - the full surface is always generated and narrowing
+   * happens at synth - so a range moving within a class is not a reason to
+   * regenerate.
    */
   targetVersions?: TerraformTargetVersions;
   /**
@@ -315,6 +321,8 @@ export class ConstructsMaker {
   private readonly codeMakerOutdir: string;
   private readonly code: CodeMaker;
   private versions: { [providerName: string]: string | undefined };
+  /** Resource directory names emitted per provider folder during this run */
+  public emittedResourceFolders: { [providerName: string]: string[] };
 
   constructor(
     private readonly options: GetOptions,
@@ -328,6 +336,7 @@ export class ConstructsMaker {
     fs.mkdirpSync(this.codeMakerOutdir);
     this.code = new CodeMaker();
     this.versions = {};
+    this.emittedResourceFolders = {};
   }
   private async generateTypescriptProvider(
     target: ConstructsMakerProviderTarget,
@@ -336,10 +345,15 @@ export class ConstructsMaker {
     const endTSTimer = logTimespan(`Generate Typescript for ${target.name}`);
     const generator = new TerraformProviderGenerator(this.code, schema, {
       importExtension: this.options.languageOptions?.importExtension,
+      targetVersions: this.options.targetVersions,
     });
     generator.generate(target);
 
     this.versions = { ...this.versions, ...generator.versions };
+    this.emittedResourceFolders = {
+      ...this.emittedResourceFolders,
+      ...generator.emittedResourceFolders,
+    };
     endTSTimer();
   }
 
@@ -399,6 +413,22 @@ export class ConstructsMaker {
       return constraints;
     }
 
+    // Generated docs links, and the prose naming the registry around them, follow
+    // the project's declared targets, so output from the other registry class is
+    // stale even when every provider version still matches.
+    const previousRegistry = registryForTargetVersions(
+      previousConstraints.targetVersions,
+    );
+    const currentRegistry = registryForTargetVersions(
+      this.options.targetVersions,
+    );
+    if (previousRegistry.hostname !== currentRegistry.hostname) {
+      logger.info(
+        `The target registry has changed from ${previousRegistry.displayName} to ${currentRegistry.displayName}, generating all constraints.`,
+      );
+      return constraints;
+    }
+
     const constraintsToGenerate = constraints.filter((constraint) => {
       const constraintMatches =
         previousConstraints.providers![constraint.fqn] === constraint.version;
@@ -449,7 +479,7 @@ export class ConstructsMaker {
   ) {
     const endTSTimer = logTimespan(`Generate Typescript for ${target.name}`);
     target.spec = schema;
-    new ModuleGenerator(this.code, [target]);
+    new ModuleGenerator(this.code, [target], this.options.targetVersions);
     endTSTimer();
   }
 
@@ -521,7 +551,21 @@ export class ConstructsMaker {
       );
     }
 
+    // Keys are fully qualified and the host is whichever registry the fetching CLI
+    // resolved from, so a provider regenerated this run can arrive under a different
+    // host than the file already holds. Carrying the old key forward as well would
+    // leave two entries for one provider, and the stale one sorts first.
+    const regenerated = new Set(
+      Object.keys(this.versions).map((fqpn) =>
+        fqpn.split("/").slice(1).join("/"),
+      ),
+    );
+
     const versions = allowedConstraints.reduce((acc, constraint) => {
+      if (regenerated.has(constraint.fqn)) {
+        return acc;
+      }
+
       const provider = Object.entries(previousVersions).find(([name]) =>
         // This could be more refined, but it's good enough for now
         name.endsWith(constraint.fqn),
@@ -595,6 +639,62 @@ export class ConstructsMaker {
     });
   }
 
+  /**
+   * Delete resource directories under `providers/` that this run did not emit, so each provider folder holds
+   * exactly the resources in the version it was generated against.
+   *
+   * Walks only providers present in `emittedResourceFolders`, keeping any provider this run skipped. Within those,
+   * removes every subdirectory not emitted and leaves provider-level files (`index.ts`, `lazy-index.ts`) in place.
+   * Deletes files, so it must run after `save()` has written the current run's output.
+   *
+   * TypeScript only: `providers/<name>/<resource>/` maps one-to-one onto the emitted index exports. Other languages
+   * co-locate providers and modules in the same folders, which makes a dropped resource indistinguishable from a
+   * hand-written construct.
+   */
+  public async removeOrphanedResourceFolders() {
+    if (!this.isJavascriptTarget) {
+      return;
+    }
+
+    for (const [provider, emittedFolders] of Object.entries(
+      this.emittedResourceFolders,
+    )) {
+      const providerFolder = path.resolve(
+        this.codeMakerOutdir,
+        "providers",
+        provider,
+      );
+
+      let entries: string[] = [];
+      try {
+        entries = await fs.readdir(providerFolder);
+      } catch (e) {
+        logger.debug(
+          `Could not list resource folders in '${providerFolder}': ${e}`,
+        );
+        continue;
+      }
+
+      const expected = new Set(emittedFolders);
+      for (const entry of entries) {
+        if (expected.has(entry)) {
+          continue;
+        }
+
+        const entryPath = path.resolve(providerFolder, entry);
+        if (!fs.statSync(entryPath).isDirectory()) {
+          // Leave index.ts / lazy-index.ts and any other provider-level files alone.
+          continue;
+        }
+
+        logger.debug(
+          `Removing orphaned resource folder '${entry}' from provider '${provider}': it was not emitted for the current provider version`,
+        );
+        await fs.remove(entryPath);
+      }
+    }
+  }
+
   // emits a constraints.json file with a map of the used provider fqpns and version constraints
   // this is used for caching purposes
   private emitConstraintsFile(
@@ -757,6 +857,7 @@ a NODE_OPTIONS variable, we won't override it. Hence, the provider generation mi
 
     if (this.isJavascriptTarget) {
       await this.save();
+      await this.removeOrphanedResourceFolders();
     }
 
     if (!this.isJavascriptTarget || this.options.outputJsii) {

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

@@ -61,13 +61,13 @@ export class StructEmitter {
         comment.line(att.description);
         comment.line(``);
         comment.line(
-          `Docs at Terraform Registry: {@link ${resource.linkToDocs}#${att.terraformName} ${resource.className}#${att.terraformName}}`,
+          `Docs at ${resource.docsRegistryName}: {@link ${resource.linkToDocs}#${att.terraformName} ${resource.className}#${att.terraformName}}`,
         );
         this.warnAboutIdField(att);
         comment.end();
       } else {
         comment.line(
-          `Docs at Terraform Registry: {@link ${resource.linkToDocs}#${att.terraformName} ${resource.className}#${att.terraformName}}`,
+          `Docs at ${resource.docsRegistryName}: {@link ${resource.linkToDocs}#${att.terraformName} ${resource.className}#${att.terraformName}}`,
         );
         this.warnAboutIdField(att);
         comment.end();

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

@@ -215,8 +215,7 @@ export interface CollectionAttributeTypeModel extends AttributeTypeModel {
   // into the nearest typed "Any"-wrapper. undefined only defensively - see
   // resolveStoredClassName in supported-stored-classes.ts.
   readonly resolvedStoredClass:
-    | { name: string; collapsed: boolean }
-    | undefined;
+    { name: string; collapsed: boolean } | undefined;
 }
 
 export class ListAttributeTypeModel implements CollectionAttributeTypeModel {

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

@@ -5,7 +5,11 @@ import path from "path";
 import { FQPN, parseFQPN, ProviderName } from "@cdktn/provider-schema";
 import { AttributeModel } from "./attribute-model";
 import { Struct, ConfigStruct } from "./struct";
-import { Schema } from "@cdktn/commons";
+import {
+  Schema,
+  TerraformTargetVersions,
+  registryForTargetVersions,
+} from "@cdktn/commons";
 import { ProviderFunctionsModel } from "./provider-function-model";
 
 // Limit is 1200 to prevent stack size error.
@@ -25,6 +29,7 @@ interface ResourceModelOptions {
   schema: Schema;
   terraformSchemaType: string;
   configStructName: string;
+  targetVersions?: TerraformTargetVersions;
 }
 
 type DefinitionPath = string;
@@ -35,6 +40,7 @@ export class ResourceModel {
   public baseName: string;
   public provider: ProviderName;
   public fqpn: FQPN;
+  private readonly targetVersions?: TerraformTargetVersions;
   public providerVersionConstraint?: string;
   public providerVersion?: string;
   public terraformProviderSource?: string;
@@ -68,6 +74,7 @@ export class ResourceModel {
     this.attributes = options.attributes;
     this.schema = options.schema;
     this.fqpn = options.fqpn;
+    this.targetVersions = options.targetVersions;
     this.provider = parseFQPN(options.fqpn).name;
     this.terraformProviderName = this.provider;
     this.fileName = options.fileName;
@@ -108,16 +115,32 @@ export class ResourceModel {
     return this.escapeSchema(JSON.stringify(this.schema, undefined, 2));
   }
 
+  /** Registry that linkToDocs points at, for use in the surrounding prose. */
+  public get docsRegistryName(): string {
+    return registryForTargetVersions(this.targetVersions).displayName;
+  }
+
   public get linkToDocs(): string {
-    const { hostname, namespace, name } = parseFQPN(this.fqpn);
+    // Keyed off the project's declared targets, not the FQPN hostname: that
+    // hostname reflects whichever CLI fetched the schema, which would make the
+    // generated link differ between a terraform and a tofu `cdktn get`.
+    const registry = registryForTargetVersions(this.targetVersions);
+    const { namespace, name } = parseFQPN(this.fqpn);
     const version = this.providerVersion || "latest";
-    const base = `https://${hostname}/providers/${namespace}/${name}/${version}/docs`;
-    if (this.isProvider) return base;
-    if (this.isDataSource)
-      return `${base}/data-sources/${this.terraformDocName}`;
-    if (this.isEphemeralResource)
-      return `${base}/ephemeral-resources/${this.terraformDocName}`;
-    return `${base}/resources/${this.terraformDocName}`;
+    const kind = this.isProvider
+      ? "provider"
+      : this.isDataSource
+        ? "data-source"
+        : this.isEphemeralResource
+          ? "ephemeral-resource"
+          : "resource";
+    return registry.docsUrl(
+      namespace,
+      name,
+      version,
+      kind,
+      this.terraformDocName,
+    );
   }
 
   public get isProvider(): boolean {

package/src/get/generator/module-generator.ts

@@ -3,12 +3,17 @@
 import { CodeMaker, toCamelCase } from "codemaker";
 import { AttributeModel } from "./models";
 import { sanitizedComment } from "./sanitized-comments";
-import { ConstructsMakerModuleTarget } from "@cdktn/commons";
+import {
+  ConstructsMakerModuleTarget,
+  TerraformTargetVersions,
+  registryForTargetVersions,
+} from "@cdktn/commons";
 
 export class ModuleGenerator {
   constructor(
     private readonly code: CodeMaker,
     private readonly targets: ConstructsMakerModuleTarget[],
+    private readonly targetVersions?: TerraformTargetVersions,
   ) {
     this.code.indentation = 2;
 
@@ -76,22 +81,19 @@ export class ModuleGenerator {
     // ... and more
     // ../module and ./module (local paths)
     const isNonRegistryModule = target.source.includes(".");
-    let registryPath;
-    // Submodules also exist (e.g. terraform-aws-modules/vpc/aws//modules/vpc-endpoints)
-    // And linking directly to them in the Registry requires including the version
-    // like e.g. https://registry.terraform.io/modules/terraform-aws-modules/vpc/aws/latest/submodules/vpc-endpoints
-    if (target.source.includes("//")) {
-      registryPath = target.source.replace(
-        "//modules",
-        `/${target.version || "latest"}/submodules`,
-      );
-      // terraform-aws-modules/vpc/aws//modules/vpc-endpoints
-      // ->
-      // terraform-aws-modules/vpc/aws/latest/submodules/vpc-endpoints
-    } else {
-      // not submodule specified, just append the version
-      registryPath = `${target.source}/${target.version || "latest"}`;
-    }
+    // Keyed off the project's declared targets rather than a fixed registry, so
+    // the link matches the product the project builds for.
+    const registry = registryForTargetVersions(this.targetVersions);
+    // Registries only have pages for a direct child of `modules/`, e.g.
+    // terraform-aws-modules/vpc/aws//modules/vpc-endpoints; any other `//` path
+    // links to the module itself.
+    const [moduleSource, subPath] = target.source.split("//", 2);
+    const submodule = subPath?.match(/^modules\/([^/]+)$/)?.[1];
+    const docsUrl = registry.moduleDocsUrl(
+      moduleSource,
+      target.version,
+      submodule,
+    );
 
     const comment = sanitizedComment(this.code);
     comment.line(`Defines an ${baseName} based on a Terraform module`);
@@ -99,7 +101,7 @@ export class ModuleGenerator {
     comment.line(
       isNonRegistryModule
         ? `Source at ${target.source}`
-        : `Docs at Terraform Registry: {@link https://registry.terraform.io/modules/${registryPath} ${target.source}}`,
+        : `Docs at ${registry.displayName}: {@link ${docsUrl} ${target.source}}`,
     );
     comment.end();
     this.code.openBlock(`export class ${baseName} extends TerraformModule`);

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

@@ -8,6 +8,7 @@ import {
   logger,
   ProviderSchema,
   TerraformProviderConstraint,
+  TerraformTargetVersions,
 } from "@cdktn/commons";
 import { FQPN, parseFQPN, ProviderName } from "@cdktn/provider-schema";
 import {
@@ -29,6 +30,8 @@ export interface TerraformProviderGeneratorOptions {
    * Defaults to "" (CommonJS).
    */
   readonly importExtension?: string;
+  /** Project's declared targetVersions; selects the docs registry. */
+  readonly targetVersions?: TerraformTargetVersions;
 }
 
 interface ProviderData {
@@ -107,12 +110,17 @@ export interface ProviderConstraints {
 }
 
 export class TerraformProviderGenerator {
-  private resourceParser = new ResourceParser();
+  private resourceParser: ResourceParser;
   private resourceEmitter: ResourceEmitter;
   private structEmitter: StructEmitter;
   private providerFunctionsEmitter: ProviderFunctionsEmitter;
   private readonly importExtension: string;
   public versions: { [fqpn: string]: string | undefined } = {};
+  /**
+   * Resource directory names emitted per provider folder Used to prune directories
+   * left over from a previous provider version.
+   */
+  public emittedResourceFolders: { [provider: string]: string[] } = {};
 
   constructor(
     private readonly code: CodeMaker,
@@ -121,6 +129,7 @@ export class TerraformProviderGenerator {
   ) {
     this.code.indentation = 2;
     this.importExtension = options.importExtension ?? "";
+    this.resourceParser = new ResourceParser(options.targetVersions);
     this.resourceEmitter = new ResourceEmitter(this.code, this.importExtension);
     this.structEmitter = new StructEmitter(this.code, this.importExtension);
     this.providerFunctionsEmitter = new ProviderFunctionsEmitter(this.code);
@@ -298,6 +307,20 @@ export class TerraformProviderGenerator {
 
     this.emitIndexFile(name, files);
     this.emitLazyIndexFile(name, files);
+
+    // Record exactly what this run emitted, derived the same way the index
+    // files derive their exports, so pruning can never disagree with them.
+    this.emittedResourceFolders[name] = files.map((file) =>
+      this.resourceFolderName(name, file),
+    );
+  }
+
+  /**
+   * Map an emitted file path to the resource directory name it lives in, e.g.
+   * `providers/mongodbatlas/teams/index.ts` -> `teams`.
+   */
+  private resourceFolderName(provider: ProviderName, file: string): string {
+    return file.replace(`providers/${provider}/`, "").replace("/index.ts", "");
   }
 
   private emitProviderFunctions(
@@ -322,7 +345,7 @@ export class TerraformProviderGenerator {
       ? resource.provider
       : resource.terraformType;
     this.code.line(
-      `Refer to the Terraform Registry for docs: [\`${type}\`](${resource.linkToDocs}).`,
+      `Refer to the ${resource.docsRegistryName} for docs: [\`${type}\`](${resource.linkToDocs}).`,
     );
     this.code.closeFile(filePath);
   }
@@ -333,7 +356,7 @@ export class TerraformProviderGenerator {
     this.code.openFile(filePath);
     this.code.line("// generated by cdktn get");
     for (const file of files) {
-      const dirName = file.replace(`${folder}/`, "").replace("/index.ts", "");
+      const dirName = this.resourceFolderName(provider, file);
       this.code.line(
         `export * as ${toCamelCase(dirName)} from './${dirName}/index${this.importExtension}';`,
       );
@@ -348,7 +371,7 @@ export class TerraformProviderGenerator {
     this.code.openFile(filePath);
     this.code.line("// generated by cdktn get");
     for (const file of files) {
-      const dirName = file.replace(`${folder}/`, "").replace("/index.ts", "");
+      const dirName = this.resourceFolderName(provider, file);
       this.code.line(
         `Object.defineProperty(exports, '${toCamelCase(
           dirName,

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

@@ -11,6 +11,7 @@ import {
   isAttributeNestedType,
   isNestedTypeAttribute,
   Schema,
+  TerraformTargetVersions,
 } from "@cdktn/commons";
 import { ProviderName, FQPN, parseFQPN } from "@cdktn/provider-schema";
 import {
@@ -82,8 +83,17 @@ export function sanitizeClassOrNamespaceName(
   isProvider = false,
 ) {
   const resourceIsNamedProvider = !isProvider && baseName === "provider";
-
-  if (isReservedClassOrNamespaceName(baseName) || resourceIsNamedProvider) {
+  // A resource named `<provider>_provider_functions` maps to the same
+  // providers/<provider>/provider-functions/ directory that the provider's
+  // functions submodule is emitted to, and would silently overwrite it.
+  const resourceIsNamedProviderFunctions =
+    !isProvider && baseName === "provider_functions";
+
+  if (
+    isReservedClassOrNamespaceName(baseName) ||
+    resourceIsNamedProvider ||
+    resourceIsNamedProviderFunctions
+  ) {
     return `${baseName}_resource`;
   } else {
     return baseName;
@@ -114,6 +124,7 @@ class Parser {
   constructor(
     private classNames: string[],
     private usedBaseNames: Map<string, string>,
+    private targetVersions?: TerraformTargetVersions,
   ) {}
 
   private uniqueClassName(className: string): string {
@@ -285,6 +296,7 @@ class Parser {
       terraformSchemaType,
       structs: this.structs,
       configStructName,
+      targetVersions: this.targetVersions,
     });
 
     return resourceModel;
@@ -718,6 +730,8 @@ export class ResourceParser {
   private uniqueBaseNames: Map<string, string> = new Map();
   private resources: Record<string, ResourceModel> = {};
 
+  constructor(private readonly targetVersions?: TerraformTargetVersions) {}
+
   public parse(
     fqpn: FQPN,
     type: string,
@@ -729,7 +743,11 @@ export class ResourceParser {
       return this.resources[type];
     }
 
-    const parser = new Parser(this.uniqueClassnames, this.uniqueBaseNames);
+    const parser = new Parser(
+      this.uniqueClassnames,
+      this.uniqueBaseNames,
+      this.targetVersions,
+    );
     const resource = parser.resourceFrom(
       fqpn,
       type,

package/tsconfig.json

@@ -24,6 +24,10 @@
     "stripInternal": true,
     "skipLibCheck": true,
     "target": "ES2018",
+    "types": [
+      "node",
+      "jest"
+    ],
     "incremental": true,
     "esModuleInterop": true,
     "rootDir": "./src",