fix(provider-generator): pick the docs registry from targetVersions

[jsteinich]

Related issue

Fixes #393. Introduces the registry mechanism that #208 will reuse.

Description

ResourceModel.linkToDocs built documentation links from the FQPN hostname, which comes from whichever CLI fetched the schema. Under OpenTofu that produced registry.opentofu.org/providers/.../docs links, which return a hard 404 — that host does not serve the Terraform registry's path shape.

The deeper defect was that the host came from the fetching CLI at all: the same provider at the same version produced different generated output depending on whether cdktn get ran under terraform or tofu. Now that both run in CI, that is a real problem. The project's declared targetVersions is the stable signal, so linkToDocs keys off that instead.

declared targetVersions	registry
opentofu only	OpenTofu
terraform only	Terraform
both	Terraform
nothing declared	Terraform (DEFAULT_TARGET_VERSIONS declares both)

The undefined case matters most, since it is what most projects hit: it resolves to Terraform, deterministically, regardless of CLI. That is why no snapshots move — every fixture in the suite has undefined targets.

The registries are not a hostname swap

Taken from getDocumentationUrl.ts in opentofu/registry-ui — the registry's own URL builder — and each shape confirmed against a live render rather than an HTTP status, because both registry front-ends soft-404 (they return 200 for nonsense paths, so curl proves nothing):

	Terraform	OpenTofu
host	registry.terraform.io	search.opentofu.org
path	/providers/{ns}/{n}/{v}/docs	/provider/{ns}/{n}/**v**{v}/docs
data sources	data-sources/	datasources/
ephemeral	ephemeral-resources/	no route

The v prefix is required — the unprefixed form renders "Page Not Found".

OpenTofu's registry has no ephemeral-resource page (opentofu/registry-ui#348), so those fall back to the provider page: it always resolves, keeps one host per project, and upgrades cleanly if upstream adds the route.

Why the helper lives in @cdktn/commons

@cdktn/cli-core needs the same mapping for #208 — both the provider-browse URL in its "could not find a version" error text, and the hostname it resolves providers from. Commons is depended on by both packages and already owns the targetVersions type re-export.

Testing

• New registry.test.ts: 7 tests covering the selection rule for all four target shapes and the URL builders for both registries, including the ephemeral fallback.
• @cdktn/provider-generator: 23 suites / 117 tests / 101 snapshots, none changed.

The URL shapes were verified by rendering each in a browser — …/docs/resources/password renders "random_password Resource", …/docs/datasources/file renders "local_file Data Source", …/docs/functions/rfc3339_parse renders the function page, while …/docs/data-sources/file errors.

Follow-up

An issue to revisit the ephemeral fallback once opentofu/registry-ui#348 lands.

Note search.opentofu.org self-describes as a beta preview of the OpenTofu Registry Search, so this URL shape sits on a surface that could still move.

🤖 Generated with Claude Code

[so0k]

i think the second finding belongs here

#447 (comment)

[sakul-learning]

I found this while reviewing the stacked follow-up PR #445: #445

ResourceModel.linkToDocs in packages/@cdktn/provider-generator/src/get/generator/models/resource-model.ts now selects a documentation registry solely through registryForTargetVersions(this.targetVersions) and discards the hostname parsed from this.fqpn. This redirects explicitly hosted and private providers to an unrelated public registry. For example, registry.example.com/acme/custom in a Terraform-targeted project produces a registry.terraform.io/providers/acme/custom/... documentation link; an explicitly qualified OpenTofu provider in a Terraform-targeted project similarly links to Terraform documentation even though the provider source and available versions may differ.

The previous implementation preserved the FQPN hostname. I understand that simply reverting to the fetched schema hostname would reintroduce the CLI-dependent output this PR is fixing, so the source identity may need to be threaded separately: use the project-selected registry for implicit public sources, but preserve an explicitly declared or private source when constructing documentation links.

Could this include a generator-level regression test for an explicit public host and a private host? The current registry.test.ts verifies each public URL builder in isolation but does not exercise this source-selection behavior.