@cdktn/provider-generator 0.25.0-pre.61 → 0.25.0-pre.64

package/src/get/__tests__/generator/module-docs-registry.test.ts

@@ -0,0 +1,89 @@
+// Copyright (c) HashiCorp, Inc
+// SPDX-License-Identifier: MPL-2.0
+import * as fs from "fs";
+import * as path from "path";
+import { CodeMaker } from "codemaker";
+import {
+  ConstructsMakerModuleTarget,
+  Language,
+  TerraformModuleConstraint,
+  TerraformTargetVersions,
+} from "@cdktn/commons";
+import { ModuleGenerator } from "../../generator/module-generator";
+import { createTmpHelper } from "../util";
+
+const tmp = createTmpHelper();
+
+async function docsComment(
+  source: string,
+  targetVersions?: TerraformTargetVersions,
+): Promise<string> {
+  const workdir = tmp("module-docs-registry");
+  const target = ConstructsMakerModuleTarget.from(
+    new TerraformModuleConstraint(source),
+    Language.TYPESCRIPT,
+  ) as ConstructsMakerModuleTarget;
+  target.spec = { name: target.name, inputs: [], outputs: [] };
+
+  const code = new CodeMaker();
+  new ModuleGenerator(code, [target], targetVersions);
+  await code.save(workdir);
+
+  const emitted = fs.readFileSync(path.join(workdir, target.fileName), "utf-8");
+  const line = emitted
+    .split("\n")
+    .find((l) => l.includes("Docs at") || l.includes("Source at"));
+  return (line ?? "").trim();
+}
+
+describe("generated module docs links", () => {
+  const module = "terraform-aws-modules/vpc/aws@3.19.0";
+  const submodule =
+    "terraform-aws-modules/vpc/aws//modules/vpc-endpoints@3.19.0";
+
+  it("uses the Terraform Registry when nothing is declared", async () => {
+    expect(await docsComment(module)).toContain(
+      "https://registry.terraform.io/modules/terraform-aws-modules/vpc/aws/3.19.0",
+    );
+  });
+
+  it("uses the OpenTofu Registry when only OpenTofu is declared", async () => {
+    const comment = await docsComment(module, { opentofu: ">=1.6.0" });
+    expect(comment).toContain("Docs at OpenTofu Registry");
+    expect(comment).toContain(
+      "https://search.opentofu.org/module/terraform-aws-modules/vpc/aws/v3.19.0",
+    );
+  });
+
+  it("links an OpenTofu submodule with the singular segment", async () => {
+    expect(await docsComment(submodule, { opentofu: ">=1.6.0" })).toContain(
+      "https://search.opentofu.org/module/terraform-aws-modules/vpc/aws/v3.19.0/submodule/vpc-endpoints",
+    );
+  });
+
+  // Registries serve submodule pages only for a direct child of `modules/`
+  // (checked against rendered pages); anything else links to the module.
+  it.each([
+    [
+      "an examples path",
+      "terraform-aws-modules/vpc/aws//examples/complete@3.19.0",
+    ],
+    [
+      "a nested modules path",
+      "terraform-aws-modules/vpc/aws//modules/x/y@3.19.0",
+    ],
+  ])("links %s to the module page", async (_name, source) => {
+    expect(await docsComment(source)).toContain(
+      "{@link https://registry.terraform.io/modules/terraform-aws-modules/vpc/aws/3.19.0 ",
+    );
+    expect(await docsComment(source, { opentofu: ">=1.6.0" })).toContain(
+      "{@link https://search.opentofu.org/module/terraform-aws-modules/vpc/aws/v3.19.0 ",
+    );
+  });
+
+  it("keeps the Terraform submodule shape unchanged", async () => {
+    expect(await docsComment(submodule)).toContain(
+      "https://registry.terraform.io/modules/terraform-aws-modules/vpc/aws/3.19.0/submodules/vpc-endpoints",
+    );
+  });
+});

package/src/get/__tests__/registry-class-invalidation.test.ts

@@ -0,0 +1,123 @@
+// Copyright (c) HashiCorp, Inc
+// SPDX-License-Identifier: MPL-2.0
+import * as fs from "fs-extra";
+import * as path from "path";
+import {
+  Language,
+  TerraformProviderConstraint,
+  TerraformTargetVersions,
+} from "@cdktn/commons";
+import { createTmpHelper } from "./util";
+
+const mockReadSchema = jest.fn();
+jest.mock("@cdktn/provider-schema", () => ({
+  readSchema: (...args: unknown[]) => mockReadSchema(...args),
+}));
+
+// Imported after the mock so ConstructsMaker picks up the mocked readSchema.
+import { ConstructsMaker } from "../constructs-maker";
+
+const tmp = createTmpHelper();
+
+// No resources, so generation stays in TypeScript emission.
+const fakeSchema = {
+  providerSchema: {
+    format_version: "0.2" as const,
+    provider_schemas: {
+      "registry.terraform.io/hashicorp/random": {
+        resource_schemas: null,
+        data_source_schemas: null,
+      },
+    },
+    provider_versions: { "registry.terraform.io/hashicorp/random": "3.2.0" },
+    cli_name: "terraform",
+    cli_version: "1.7.5",
+  },
+};
+
+describe("filterAlreadyGenerated: registry class", () => {
+  const constraint = new TerraformProviderConstraint("hashicorp/random@=3.2.0");
+  let outdir: string;
+
+  const maker = (targetVersions?: TerraformTargetVersions) =>
+    new ConstructsMaker({
+      codeMakerOutput: outdir,
+      targetLanguage: Language.TYPESCRIPT,
+      targetVersions,
+    });
+
+  /** A real previous `cdktn get`, so constraints.json is what generation writes. */
+  const generateWith = (targetVersions?: TerraformTargetVersions) =>
+    maker(targetVersions).generate([constraint]);
+
+  beforeEach(() => {
+    mockReadSchema.mockReset();
+    mockReadSchema.mockResolvedValue(fakeSchema);
+    outdir = tmp("registry-class");
+  });
+
+  it.each<
+    [
+      string,
+      TerraformTargetVersions | undefined,
+      TerraformTargetVersions | undefined,
+    ]
+  >([
+    ["nothing changed", undefined, undefined],
+    [
+      "both products declared, the same class as nothing",
+      undefined,
+      { terraform: ">=1.5.7", opentofu: ">=1.6.0" },
+    ],
+    [
+      "a range moving within the OpenTofu class",
+      { opentofu: ">=1.6.0" },
+      { opentofu: ">=1.8.0" },
+    ],
+  ])("skips regeneration: %s", async (_name, before, after) => {
+    await generateWith(before);
+
+    await expect(
+      maker(after).filterAlreadyGenerated([constraint]),
+    ).resolves.toEqual([]);
+  });
+
+  it("regenerates when the project switches to OpenTofu-only", async () => {
+    await generateWith(undefined);
+
+    await expect(
+      maker({ opentofu: ">=1.6.0" }).filterAlreadyGenerated([constraint]),
+    ).resolves.toEqual([constraint]);
+  });
+
+  it("regenerates when the project switches away from OpenTofu-only", async () => {
+    await generateWith({ opentofu: ">=1.6.0" });
+
+    await expect(
+      maker({ terraform: ">=1.5.7" }).filterAlreadyGenerated([constraint]),
+    ).resolves.toEqual([constraint]);
+  });
+
+  // constraints.json written before targetVersions was stamped has no such field;
+  // it must read as the Terraform class, which is what it was generated for.
+  describe("constraints.json from before targetVersions was recorded", () => {
+    beforeEach(async () => {
+      await generateWith({ terraform: ">=1.5.7" });
+      const file = path.join(outdir, "constraints.json");
+      const { targetVersions: _dropped, ...older } = fs.readJsonSync(file);
+      fs.writeJsonSync(file, older);
+    });
+
+    it("is fresh for a Terraform project", async () => {
+      await expect(
+        maker().filterAlreadyGenerated([constraint]),
+      ).resolves.toEqual([]);
+    });
+
+    it("is stale for an OpenTofu-only project", async () => {
+      await expect(
+        maker({ opentofu: ">=1.6.0" }).filterAlreadyGenerated([constraint]),
+      ).resolves.toEqual([constraint]);
+    });
+  });
+});

package/src/get/__tests__/target-versions.test.ts

@@ -3,8 +3,10 @@
 import * as fs from "fs-extra";
 import * as path from "path";
 import {
+  ConstructsMakerModuleTarget,
   Language,
   TerraformDependencyConstraint,
+  TerraformModuleConstraint,
   TerraformTargetVersions,
 } from "@cdktn/commons";
 import { createTmpHelper } from "./util";
@@ -204,3 +206,44 @@ describe("targetVersions threading through 'cdktn get'", () => {
     expect(toGenerate).toEqual([]);
   });
 });
+
+describe("targetVersions reaching generated module bindings", () => {
+  const moduleConstraint = new TerraformModuleConstraint(
+    "terraform-aws-modules/vpc/aws@3.19.0",
+  );
+
+  const emittedSources = (dir: string): string[] =>
+    fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) return emittedSources(full);
+      return entry.name.endsWith(".ts") ? [fs.readFileSync(full, "utf8")] : [];
+    });
+
+  beforeEach(() => {
+    mockReadSchema.mockReset();
+    const target = ConstructsMakerModuleTarget.from(
+      moduleConstraint,
+      Language.TYPESCRIPT,
+    ) as ConstructsMakerModuleTarget;
+    mockReadSchema.mockResolvedValue({
+      moduleSchema: {
+        [target.moduleKey]: { name: target.name, inputs: [], outputs: [] },
+      },
+    });
+  });
+
+  it("links an OpenTofu-only project's modules to the OpenTofu registry", async () => {
+    const workdir = tmp("target-versions-module.test");
+    const maker = new ConstructsMaker({
+      codeMakerOutput: workdir,
+      targetLanguage: Language.TYPESCRIPT,
+      targetVersions: { opentofu: ">=1.6.0" },
+    });
+
+    await maker.generate([moduleConstraint]);
+
+    expect(emittedSources(workdir).join("\n")).toContain(
+      "https://search.opentofu.org/module/terraform-aws-modules/vpc/aws/v3.19.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;
   /**
@@ -407,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;
@@ -457,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();
   }
 
@@ -529,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),

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`);