fix(cloud-assembly-schema): unconfiguredBehavesLike contains info for multiple versions (#782)

The way it's currently specified, the `unconfiguredBehavesLike` field
that's in the Cloud Assembly Schema requires the CLI to know the current
major version of the CDK Library to properly evaluate:

It looks like `unconfiguredBehavesLike: { v1: ..., v2: ... }` subfields,
and that requires the CLI to know whether to look in the `v1` or `v2`
subfield (and in the future `v3`, `v4`, etc...).

That is unnecessary: since the CDK Library knows its own current version
so it could just have communicated `unconfiguredBehavesLike: true` to
accurately reflect its current behavior, without the consumer needing to
know anything about the version.

The CLI code right now is only reading the `v2` field, but that will
become inaccurate if we ever release CDKv3.

In this PR, we're saying that the `v2` subfield is the "official"
location of this value going forward. `v1` should be ignored if present
(but is still included to not trip up any JSON Schema validation).

This leads to the least amount of interference with the existing
ecosystem (no forced upgrade by CDK users and no backwards compatibility
path in the CLI to potentially read 2 fields).

---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

---------

Signed-off-by: github-actions <[email protected]>
Co-authored-by: github-actions <[email protected]>

Author: 2 people

packages/@aws-cdk/cloud-assembly-schema/lib/cloud-assembly/artifact-schema.ts

@@ -238,7 +238,7 @@ export interface FeatureFlagReportProperties {
   /**
    * Information about every feature flag supported by this library.
    */
-  readonly flags: Record<string, FeatureFlag>;
+  readonly flags: { [flagName: string]: FeatureFlag };
 }
 
 /**
@@ -273,11 +273,44 @@ export interface FeatureFlag {
   readonly explanation?: string;
 
   /**
-   * The value of the flag if it is unconfigured
+   * The value of the flag that produces the same behavior as when the flag is not configured at all
    *
-   * @default - No value
+   *The structure of this field is a historical accident. The type of this field
+   *should have been boolean, which should have contained the default value for
+   *the flag appropriate for the *current* version of the CDK library. We are
+   *not rectifying this accident because doing so
+   *
+   * Instead, the canonical way to access this value is by evaluating
+   * `unconfiguredBehavesLike?.v2 ?? false`.
+   *
+   * @default false
+   */
+  readonly unconfiguredBehavesLike?: UnconfiguredBehavesLike;
+}
+
+export interface UnconfiguredBehavesLike {
+  /**
+   * Historical accident, don't use.
+   *
+   * This value may be present, but it should never be used. The actual value is
+   * in the `v2` field, regardless of the version of the CDK library.
+   *
+   * @default - ignore
+   */
+  readonly v1?: any;
+
+  /**
+   * The value of the flag that produces the same behavior as when the flag is not configured at all
+   *
+   * Even though it is called 'v2', this is the official name of this field. In
+   * any future versions of CDK (v3, v4, ...), this field will still be called 'v2'.
+   *
+   * The structure of this field is a historical accident. See the comment on
+   * `unconfiguredBehavesLike` for more information.
+   *
+   * @default false
    */
-  readonly unconfiguredBehavesLike?: { [key: string]: any };
+  readonly v2?: any;
 }
 
 /**

packages/@aws-cdk/cloud-assembly-schema/schema/cloud-assembly.schema.json

@@ -505,17 +505,50 @@
                     "type": "string"
                 },
                 "flags": {
-                    "$ref": "#/definitions/Record<string,FeatureFlag>",
-                    "description": "Information about every feature flag supported by this library."
+                    "description": "Information about every feature flag supported by this library.",
+                    "type": "object",
+                    "additionalProperties": {
+                        "$ref": "#/definitions/FeatureFlag"
+                    }
                 }
             },
             "required": [
                 "flags",
                 "module"
             ]
         },
-        "Record<string,FeatureFlag>": {
-            "type": "object"
+        "FeatureFlag": {
+            "description": "A single feature flag",
+            "type": "object",
+            "properties": {
+                "recommendedValue": {
+                    "description": "The library-recommended value for this flag, if any\n\nIt is possible that there is no recommended value. (Default - No recommended value.)"
+                },
+                "userValue": {
+                    "description": "The value configured by the user\n\nThis is the value configured at the root of the tree. Users may also have\nconfigured values at specific locations in the tree; we don't report on\nthose. (Default - Not configured by the user)"
+                },
+                "explanation": {
+                    "description": "Explanation about the purpose of this flag that can be shown to the user. (Default - No description)",
+                    "type": "string"
+                },
+                "unconfiguredBehavesLike": {
+                    "description": "The value of the flag that produces the same behavior as when the flag is not configured at all\n\nThe structure of this field is a historical accident. The type of this field\nshould have been boolean, which should have contained the default value for\nthe flag appropriate for the *current* version of the CDK library. We are\nnot rectifying this accident because doing so\n\nInstead, the canonical way to access this value is by evaluating\n`unconfiguredBehavesLike?.v2 ?? false`.",
+                    "default": false,
+                    "$ref": "#/definitions/UnconfiguredBehavesLike"
+                }
+            }
+        },
+        "UnconfiguredBehavesLike": {
+            "type": "object",
+            "properties": {
+                "v1": {
+                    "description": "Historical accident, don't use.\n\nThis value may be present, but it should never be used. The actual value is\nin the `v2` field, regardless of the version of the CDK library. (Default - ignore)"
+                },
+                "v2": {
+                    "description": "The value of the flag that produces the same behavior as when the flag is not configured at all\n\nEven though it is called 'v2', this is the official name of this field. In\nany future versions of CDK (v3, v4, ...), this field will still be called 'v2'.\n\nThe structure of this field is a historical accident. See the comment on\n`unconfiguredBehavesLike` for more information.",
+                    "default": false
+                }
+            }
         },
         "MissingContext": {
             "description": "Represents a missing piece of context.",

packages/@aws-cdk/cloud-assembly-schema/schema/version.json

@@ -1,5 +1,5 @@
 {
-  "schemaHash": "0807b42f8220bdafddeb4dad246a696721ed86e99ac6b13aa83359bab834d60d",
+  "schemaHash": "4755f1d1fcb2dc25dd6bff0494afa7d86c517274ffebdf2ac2dcb90ad4b899c4",
   "$comment": "Do not hold back the version on additions: jsonschema validation of the manifest by the consumer will trigger errors on unexpected fields.",
   "revision": 48
 }