docs(cloudformation): generate the supported resource-type table - #2739
docs(cloudformation): generate the supported resource-type table#2739hectorvent wants to merge 1 commit into
Conversation
|
| Filename | Overview |
|---|---|
| tools/docs/regen_cfn_resource_types.py | Generates and validates the resource-type table, but its previously reported CDI annotation detector remains based on brittle source substrings. |
| tools/docs/cfn_resource_types.yaml | Defines table ordering, labels, annotations, namespace merging, and justified non-inventory capabilities. |
| tools/docs/test_regen_cfn_resource_types.py | Covers rendering, ordering, warnings, inventory parsing, and marker splicing. |
| docs/services/cloudformation.md | Adds generated markers and documents the provisioner-backed resource types currently represented by the inventory. |
| Makefile | Integrates resource-table generation and strict validation into the existing documentation commands. |
| .github/workflows/docs-actions.yml | Runs documentation validation when the CloudFormation test inventory changes. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart LR
I[Provisioner inventory TSV] --> G[CloudFormation docs generator]
C[Presentation YAML] --> G
G --> D[Supported resource-type table]
M[make docs-check] --> G
G --> W[Inventory ownership and CDI checks]
D --> S[Staleness check]
W --> R[CI result]
S --> R
Reviews (2): Last reviewed commit: "docs(cloudformation): generate the suppo..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| for path in sorted(PROVISIONER_DIR.glob("*CfnProvisioner.java")): | ||
| src = path.read_text(encoding="utf-8") | ||
| if "implements CfnResourceProvisioner" not in src: | ||
| continue |
There was a problem hiding this comment.
The raw substring check rejects a correctly scoped provisioner written as @jakarta.enterprise.context.ApplicationScoped, while the same substring in a comment satisfies the check without applying the annotation. Because docs-check runs this detector in strict mode, valid annotation syntax can fail CI and comments can bypass the intended early warning.
Context Used: AGENTS.md (source)
pgermosen
added
cloudformation
pgermosen
left a comment
pgermosen
left a comment
There was a problem hiding this comment.
Approving the content — read the generator script and its full test suite, the doc drift it's closing is real, and the double-ownership/@ApplicationScoped checks are a nice complement to #2732's guardrails.
One thing before this lands, though: the base branch here is refactor/cfn-wave0-enablers, and #2732 was squash-merged into main rather than fast-forwarded — ac71876 (this branch's parent) isn't actually an ancestor of main. So merging as-is would land this into the now-orphaned feature branch, not main. Could you retarget the base to main (and rebase — the diff right now still carries all of #2732's already-merged changes)?
The "Supported Resource Types" table was hand-maintained, and had drifted: ten provisioned types were undocumented, including the whole CloudFront row, Lambda's Permission/MicrovmImage/NetworkConnector, RDS DBProxy and DBProxyTargetGroup, ECS capacity providers, EC2 VPCEndpoint and ApiGatewayV2 Authorizer. Generate it from the provisioner inventory TSV that CfnResourceInventoryTest already pins to the CDI-resolved registry, so the table cannot drift from what Floci actually provisions. Wired into docs-sync and docs-check, with the inventory path added to the workflow filters: it lives under src/test/resources, which src/main/** did not cover, so a slice that moved a type between owners would have skipped the gate. The table is prose as much as data, so presentation stays configurable in cfn_resource_types.yaml: service labels, curated type order (types not listed there are appended alphabetically, so a new type still appears), per-type notes, and extra_types for capabilities that are real but are not provisioner types, each needing a stated reason. Nested Stack and the Custom::* wildcard are the two such entries; the wildcard cannot be an inventory type because the registry is keyed by exact type. The generator reads the TSV rather than the Java because several provisioners return Set.of(CONSTANT, CONSTANT) from resourceTypes(), which a source regex only partly sees. Also flags two things cheaply, before anyone waits on a Quarkus boot: a provisioner missing @ApplicationScoped, and a type claimed by both the legacy switch and a provisioner.
6338b33 to
4482420
Compare
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
| from __future__ import annotations | ||
|
|
||
| import argparse | ||
| import re |
2 participants
Summary
The CloudFormation Supported Resource Types table was hand-maintained, and had drifted. Ten
provisioned types were undocumented:
Distribution(the entire row was missing)Permission,MicrovmImage,NetworkConnectorDBProxy,DBProxyTargetGroupCapacityProvider,ClusterCapacityProviderAssociationsVPCEndpointAuthorizerThis generates the table from the provisioner inventory TSV that
CfnResourceInventoryTestalreadypins to the CDI-resolved registry (added in #2732), so it can no longer drift from what Floci
actually provisions.
make docs-syncwrites it,make docs-checkgates it.Stacked on #2732 — review that first; this branch contains its commit.
Why the TSV and not the Java
Several provisioners return
Set.of(CONSTANT, CONSTANT)fromresourceTypes(), so a source regexsees only a subset (22 of 33 today). The TSV is the one representation that is both machine-checked
against the running registry and readable without a JVM.
The table is prose as much as data
A naive generator would have destroyed real information, so presentation stays configurable in
cfn_resource_types.yaml:type_orderkeeps the curated reading order (VPC,Subnet,SecurityGroup… notalphabetical). Types not listed are appended alphabetically, so a newly provisioned type still
appears without touching the config.
notes/row_notespreserve the existing annotations, including the Lambda row'sexplanation of
cfn-responseinjection.extra_typescovers capabilities that are real but are not provisioner types, each requiringa stated reason. Nested
Stackand theCustom::*wildcard are the two: the wildcard cannotbe an inventory type, because the registry is keyed by exact type.
Also gated, cheaply
Two checks that otherwise need a Quarkus boot now run in
docs-check: a provisioner missing@ApplicationScoped(CDI silently never registers it), and a type claimed by both the legacy switchand a provisioner (the registry wins, leaving a switch arm that looks live but is dead).
The workflow's path filters gained
src/test/resources/cloudformation/**. The inventory lives undersrc/test, whichsrc/main/**did not cover, so a migration slice that only moved a type betweenowners would have skipped this gate entirely.
Type of change
fix:)feat:)feat!:orfix!:)AWS Compatibility
N/A. Documentation and build tooling only; no Java changed, so no emulated surface is affected.
Checklist
./mvnw testpasses locallymake docs-test50 passed (16 new).make docs-checkclean. No Java touched, so the Java suite isunaffected and was not re-run beyond #2732's full green run.
Gate mutation-tested rather than trusted for passing:
--checkfails: table stale, plus a warning that the namespace has no label@ApplicationScopedfromSqsCfnProvisioner--strictfails naming the file and the consequence