Extend metadata with descriptors of CF Ref handling (#1836)

CloudFormation Ref intrinsic behavior varies from resource to resource.
This change is an attempt to schematize behavior and expose is in the
provider metadata. One intended use case is `pulumi/pulumi-cdk` CF
emulator.

This change implies the `ref-db.json` becomes the source of truth for
this metadata and we maintain it as well as possible.

About 1/2 of CF resources are currently covered in the file, including
81 of the top used resources
(pulumi/pulumi-cdk#237). Data cleaning and
data label attachment helper code is included but is not intended to be
used in production but only to maintain `ref-db.json`.

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