Extend metadata with descriptors of CF Ref handling

Makefile

@@ -185,4 +185,19 @@ install_sdks:: install_dotnet_sdk install_python_sdk install_nodejs_sdk
 # Required for the codegen action that runs in pulumi/pulumi
 only_build:: build
 
+ref-db::
+	mkdir -p bin
+	(cd provider/tools/ref-parser && go build -o ../../../bin/ref-parser)
+	./bin/ref-parser -guide ./aws-cloudformation-user-guide -schema ./aws-cloudformation-schema -db ./meta/ref-db.json
+
+ref-db-auto::
+	mkdir -p bin
+	(cd provider/tools/ref-parser && go build -o ../../../bin/ref-parser)
+	./bin/ref-parser -guide ./aws-cloudformation-user-guide -schema ./aws-cloudformation-schema -db ./meta/ref-db.json -auto
+
+ref-db-report::
+	mkdir -p bin
+	(cd provider/tools/ref-parser && go build -o ../../../bin/ref-parser)
+	./bin/ref-parser -guide ./aws-cloudformation-user-guide -schema ./aws-cloudformation-schema -db ./meta/ref-db.json -report
+
 .PHONY: ensure generate_schema generate build_provider build

meta/README.md

@@ -0,0 +1,21 @@
+# meta
+
+Reference data used by the `pulumi-aws-native` provider.
+
+## ref-db.json
+
+Metadata describing the behavior of the [CloudFormation Ref Intrinsic](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html).
+
+What Ref returns varies from resource to resource. The only available information on this is free-form text in CloudFormation documentation and anything that can be extracted experimentally. To facilitate building tooling such as `pulumi/pulumi-cdk` that emulates CF behavior, `ref-db.json` collects schematized information describing the behavior of `Ref`.
+
+`ref-db.json` can be edited directly to correct errors or add entries for resources not yet covered.
+
+## regions.json
+
+AWS regions and their names.
+
+Please do not edit this file directly.
+
+This list can be refreshed by extracting from `botocore`. See `.botocore.version`.
+
+    make docs