feat: document function availability validation and cross-product Fn coverage#16
Open
so0k wants to merge 3 commits into
Open
feat: document function availability validation and cross-product Fn coverage#16so0k wants to merge 3 commits into
so0k wants to merge 3 commits into
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Merged
5 tasks
…coverage - concepts/functions: availability matrix across Terraform/OpenTofu, the validateFunctionVersions feature flag, error/warning behavior, limitations - release/function-availability: what's-new page incl. new Fn functions and the format/formatlist return-type refinement - release/index: What's New + Feature Flags sections Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
so0k
force-pushed
the
generate-function-bindings
branch
from
4ac2e4e to
17deed6
Compare
AWS Adapter will not be ported to CDKTN
Add the canonical "Declare Target Runtimes" section (anchor #declare-target-runtimes, already linked from functions.mdx and release/function-availability.mdx) covering the targetVersions cdktf.json field and the opt-in validateInstalledBinary binary check on diff/deploy/destroy. Cross-link the feature from the CLI reference, architecture, deployment-patterns CI, HCL interop, and custom-construct design pages. Also fix release/index.mdx drift: the validateFunctionVersions check is declarative against the declared targetVersions at synth time, not against the installed CLI version. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
so0k
added a commit
to open-constructs/cdk-terrain
that referenced
this pull request
Jun 26, 2026
## Summary > Stacked on #269 (declared `targetVersions` foundation). Terraform and OpenTofu have diverged in their built-in function sets, and the checked-in function metadata predated Terraform 1.8 — so `Fn` was missing every function added since, and using a function your targeted runtimes don't support only failed at `terraform plan` time. This PR fixes the bindings generator, regenerates the bindings to cover **both products**, and adds an opt-in synth-time validation of function usage against the project's declared targets. Full Source data: [open-constructs/cdktn-planning - RFCS/03-function-availability/PROPOSAL.md](https://github.com/open-constructs/cdktn-planning/blob/f4fbc15510ab83d1f2378a04bcb1f9ef7908c89a/RFCS/03-function-availability/PROPOSAL.md) Full function matrix: https://cdktn.io/function-matrix.html ### Commits (reviewable independently) 1. **chore(lib): function availability dataset + tooling** — swept `metadata functions -json` across every stable Terraform (1.5.7→1.15.6, 66 releases) and OpenTofu (1.6.0→1.12.1, 54 releases) release into `functions-matrix.json`. Includes a `pnpm update-function-matrix` delta updater for new releases (downloads only unseen versions) and the generator for the availability map. Baseline sweep scripts are marked linguist-generated and excluded from copywrite/prettier/eslint. 1. **feat(lib): regenerate function bindings from Terraform 1.15.6** — filters `core::` aliases (terraform ≥1.8 reports every builtin twice; not valid identifiers), merges OpenTofu-only functions from the matrix. New on `Fn` and the `cdktn convert` map: `convert`, `ephemeralasnull`, `issensitive`, `templatestring`, `base64gunzip`, `cidrcontains`, `urldecode`. None are variadic, so no new `INTERNAL_METHODS`. Upstream metadata also refined `format`/`formatlist` return types (`any` → `string`/`string[]`; rendered expressions unchanged). 1. **feat(lib): validate Fn usage against declared targets (`validateFunctionVersions` flag)** — a usage registry records `Fn` calls at the `terraformFunction()` chokepoint (~5ns/call, 0.04% of an `Fn` call); `ValidateFunctionVersionSupport` checks used functions from the generated availability map against the project's declared `targetVersions` via `checkFeatureSupportedByTargets` (range subset), with an availability hint pointing at the products/versions that do support the function. **Purely declarative — no binary is ever executed**; synth behaves identically in CI and environments without Terraform/OpenTofu installed. Added to `FUTURE_FLAGS` so `cdktn init` enables it for new projects. 1. **chore(tests): integration test + cross-version docs** — every synth runs with a nonexistent `TERRAFORM_BINARY_NAME`, proving no binary involvement: the default baseline targets deterministically reject `issensitive` (introduced TF 1.8 / Tofu 1.7), and raising the declared floor in `cdktf.json` makes it pass. Example validation error: ``` Validation failed with the following errors: [MyStack/resource] Terraform function "templatestring" requires terraform >=1.9.0, but the project targets terraform >=1.5.7. It is available in terraform >=1.9.0 and opentofu >=1.7.0. ``` Companion docs PR: [open-constructs/cdk-terrain-docs](open-constructs/cdk-terrain-docs#16) ## Test plan - [x] `pnpm nx test cdktn` — 433/434 pass (the one failure is `matchers.test.ts` `toPlanSuccessfully`, which requires a running Docker daemon; environmental, unrelated) - [x] 8 new unit tests in `validations.test.ts`: baseline functions never resolve targets (execSync spy), default-baseline rejection, declared-targets pass (no exec), product-exclusive with availability hint, OpenTofu-only targeting, malformed declared targets, flag on/off wiring - [x] jsii build clean (`nx run cdktn:build`) - [x] Delta updater verified: rewinding the matrix one release and re-running reconstructs it byte-identically - [ ] Integration test requires `pnpm package` dist (runs in CI); deterministic across the version matrix — no binary is executed 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documentation for open-constructs/cdk-terrain#268 —
Fnbindings now cover both Terraform and OpenTofu, with synth-time validation of function usage behind thevalidateFunctionVersionsfeature flag.Fnfunctions per product, validation behavior,format/formatlistreturn-type refinement, flag enablement for existing projectsfailOnConstructsOutsideOfStacks,validateFunctionVersions)Should merge together with (or after) open-constructs/cdk-terrain#268.
🤖 Generated with Claude Code