feat(docs): add api-extractor config

.projenrc.ts

@@ -4,6 +4,7 @@ import type { TypeScriptWorkspaceOptions } from 'cdklabs-projen-project-types/li
 import * as pj from 'projen';
 import { Stability } from 'projen/lib/cdk';
 import { AdcPublishing } from './projenrc/adc-publishing';
+import { ApiExtractorDocsPublishing } from './projenrc/api-extractor-docs-publishing';
 import { BundleCli } from './projenrc/bundle';
 import { CodeCovWorkflow } from './projenrc/codecov';
 import { ESLINT_RULES } from './projenrc/eslint';
@@ -1202,6 +1203,12 @@ new S3DocsPublishing(toolkitLib, {
   roleToAssume: '${{ vars.PUBLISH_TOOLKIT_LIB_DOCS_ROLE_ARN }}',
 });
 
+new ApiExtractorDocsPublishing(toolkitLib, {
+  docsStream: 'toolkit-lib',
+  bucketName: '${{ vars.DOCS_BUCKET_NAME }}',
+  roleToAssume: '${{ vars.PUBLISH_TOOLKIT_LIB_DOCS_ROLE_ARN }}',
+});
+
 // Eslint rules
 toolkitLib.eslint?.addRules({
   '@cdklabs/no-throw-default-error': 'error',
@@ -1282,6 +1289,48 @@ for (const tsconfig of [toolkitLib.tsconfigDev]) {
   }
 }
 
+// Add API Extractor configuration
+new pj.JsonFile(toolkitLib, 'api-extractor.json', {
+  marker: false,
+  obj: {
+    projectFolder: '.',
+    mainEntryPointFilePath: '<projectFolder>/lib/index.d.ts',
+    bundledPackages: [],
+    apiReport: {
+      enabled: false
+    },
+    docModel: {
+      enabled: true,
+      apiJsonFilePath: './dist/<unscopedPackageName>.api.json',
+      projectFolderUrl: 'https://github.com/aws/aws-cdk-cli'
+    },
+    dtsRollup: {
+      enabled: false
+    },
+    tsdocMetadata: {
+      enabled: false
+    },
+    messages: {
+      compilerMessageReporting: {
+        default: {
+          logLevel: 'warning'
+        }
+      },
+      extractorMessageReporting: {
+        default: {
+          logLevel: 'warning'
+        }
+      },
+      tsdocMessageReporting: {
+        default: {
+          logLevel: 'warning'
+        }
+      }
+    }
+  },
+  committed: true,
+});
+
 // Add a command for the docs
 const toolkitLibDocs = toolkitLib.addTask('docs', {
   exec: 'typedoc lib/index.ts',

packages/@aws-cdk/cloud-assembly-schema/README.md

@@ -5,8 +5,8 @@ This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aw
 ## Cloud Assembly
 
 The _Cloud Assembly_ is the output of the synthesis operation. It is produced as part of the
-[`cdk synth`](https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk#cdk-synthesize)
-command, or the [`app.synth()`](https://github.com/aws/aws-cdk/blob/main/packages/@aws-cdk/core/lib/app.ts#L135) method invocation.
+[`cdk synth`](https://github.com/aws/aws-cdk-cli/tree/main/packages/aws-cdk#cdk-synthesize)
+command, or the [`app.synth()`](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/core/lib/stage.ts#L219) method invocation.
 
 Its essentially a set of files and directories, one of which is the `manifest.json` file. It defines the set of instructions that are
 needed in order to deploy the assembly directory.
@@ -51,4 +51,3 @@ cannot be guaranteed because some instructions will be ignored.
 ## Contributing
 
 See [Contribution Guide](./CONTRIBUTING.md)
-

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

@@ -355,20 +355,20 @@ export interface KeyContextQuery extends ContextLookupRoleOptions {
 }
 
 /**
- * Query input for lookup up Cloudformation resources using CC API
+ * Query input for lookup up CloudFormation resources using CC API
  */
 export interface CcApiContextQuery extends ContextLookupRoleOptions {
   /**
-   * The Cloudformation resource type.
+   * The CloudFormation resource type.
    * See https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/supported-resources.html
    */
   readonly typeName: string;
 
   /**
    * Identifier of the resource to look up using `GetResource`.
    *
-   * Specifying exactIdentifier will return exactly one result, or throw an error.
-   *
+   * Specifying exactIdentifier will return exactly one result, or throw an error
+   * unless `ignoreErrorOnMissingContext` is set.
    *
    * @default - Either exactIdentifier or propertyMatch should be specified.
    */
@@ -377,7 +377,10 @@ export interface CcApiContextQuery extends ContextLookupRoleOptions {
   /**
    * Returns any resources matching these properties, using `ListResources`.
    *
-   * Specifying propertyMatch will return 0 or more results.
+   * By default, specifying propertyMatch will successfully return 0 or more
+   * results. To throw an error if the number of results is unexpected (and
+   * prevent the query results from being committed to context), specify
+   * `expectedMatchCount`.
    *
    * ## Notes on property completeness
    *
@@ -413,6 +416,23 @@ export interface CcApiContextQuery extends ContextLookupRoleOptions {
    */
   readonly propertiesToReturn: string[];
 
+  /**
+   * Expected count of results if `propertyMatch` is specified.
+   *
+   * If the expected result count does not match the actual count,
+   * by default an error is produced and the result is not committed to cached
+   * context, and the user can correct the situation and try again without
+   * having to manually clear out the context key using `cdk context --remove`
+   *
+   * If the value of * `ignoreErrorOnMissingContext` is `true`, the value of
+   * `expectedMatchCount` is `at-least-one | exactly-one` and the number
+   * of found resources is 0, `dummyValue` is returned and committed to context
+   * instead.
+   *
+   * @default 'any'
+   */
+  readonly expectedMatchCount?: 'any' | 'at-least-one' | 'at-most-one' | 'exactly-one';
+
   /**
    * The value to return if the resource was not found and `ignoreErrorOnMissingContext` is true.
    *
@@ -432,8 +452,8 @@ export interface CcApiContextQuery extends ContextLookupRoleOptions {
    *
    * - In case of an `exactIdentifier` lookup, return the `dummyValue` if the resource with
    *   that identifier was not found.
-   * - In case of a `propertyMatch` lookup, this setting currently does not have any effect,
-   *   as `propertyMatch` queries can legally return 0 resources.
+   * - In case of a `propertyMatch` lookup, return the `dummyValue` if `expectedMatchCount`
+   *   is `at-least-one | exactly-one` and the number of resources found was 0.
    *
    * if `ignoreErrorOnMissingContext` is set, `dummyValue` should be set and be an array.
    *

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

@@ -1024,19 +1024,19 @@
             ]
         },
         "CcApiContextQuery": {
-            "description": "Query input for lookup up Cloudformation resources using CC API",
+            "description": "Query input for lookup up CloudFormation resources using CC API",
             "type": "object",
             "properties": {
                 "typeName": {
-                    "description": "The Cloudformation resource type.\nSee https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/supported-resources.html",
+                    "description": "The CloudFormation resource type.\nSee https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/supported-resources.html",
                     "type": "string"
                 },
                 "exactIdentifier": {
-                    "description": "Identifier of the resource to look up using `GetResource`.\n\nSpecifying exactIdentifier will return exactly one result, or throw an error. (Default - Either exactIdentifier or propertyMatch should be specified.)",
+                    "description": "Identifier of the resource to look up using `GetResource`.\n\nSpecifying exactIdentifier will return exactly one result, or throw an error\nunless `ignoreErrorOnMissingContext` is set. (Default - Either exactIdentifier or propertyMatch should be specified.)",
                     "type": "string"
                 },
                 "propertyMatch": {
-                    "description": "Returns any resources matching these properties, using `ListResources`.\n\nSpecifying propertyMatch will return 0 or more results.\n\n## Notes on property completeness\n\nCloudControl API's `ListResources` may return fewer properties than\n`GetResource` would, depending on the resource implementation.\n\nThe resources that `propertyMatch` matches against will *only ever* be the\nproperties returned by the `ListResources` call. (Default - Either exactIdentifier or propertyMatch should be specified.)",
+                    "description": "Returns any resources matching these properties, using `ListResources`.\n\nBy default, specifying propertyMatch will successfully return 0 or more\nresults. To throw an error if the number of results is unexpected (and\nprevent the query results from being committed to context), specify\n`expectedMatchCount`.\n\n## Notes on property completeness\n\nCloudControl API's `ListResources` may return fewer properties than\n`GetResource` would, depending on the resource implementation.\n\nThe resources that `propertyMatch` matches against will *only ever* be the\nproperties returned by the `ListResources` call. (Default - Either exactIdentifier or propertyMatch should be specified.)",
                     "$ref": "#/definitions/Record<string,unknown>"
                 },
                 "propertiesToReturn": {
@@ -1046,11 +1046,21 @@
                         "type": "string"
                     }
                 },
+                "expectedMatchCount": {
+                    "description": "Expected count of results if `propertyMatch` is specified.\n\nIf the expected result count does not match the actual count,\nby default an error is produced and the result is not committed to cached\ncontext, and the user can correct the situation and try again without\nhaving to manually clear out the context key using `cdk context --remove`\n\nIf the value of * `ignoreErrorOnMissingContext` is `true`, the value of\n`expectedMatchCount` is `at-least-one | exactly-one` and the number\nof found resources is 0, `dummyValue` is returned and committed to context\ninstead. (Default 'any')",
+                    "enum": [
+                        "any",
+                        "at-least-one",
+                        "at-most-one",
+                        "exactly-one"
+                    ],
+                    "type": "string"
+                },
                 "dummyValue": {
                     "description": "The value to return if the resource was not found and `ignoreErrorOnMissingContext` is true.\n\nIf supplied, `dummyValue` should be an array of objects.\n\n`dummyValue` does not have to have elements, and it may have objects with\ndifferent properties than the properties in `propertiesToReturn`, but it\nwill be easiest for downstream code if the `dummyValue` conforms to\nthe expected response shape. (Default - No dummy value available)"
                 },
                 "ignoreErrorOnMissingContext": {
-                    "description": "Ignore an error and return the `dummyValue` instead if the resource was not found.\n\n- In case of an `exactIdentifier` lookup, return the `dummyValue` if the resource with\n  that identifier was not found.\n- In case of a `propertyMatch` lookup, this setting currently does not have any effect,\n  as `propertyMatch` queries can legally return 0 resources.\n\nif `ignoreErrorOnMissingContext` is set, `dummyValue` should be set and be an array.",
+                    "description": "Ignore an error and return the `dummyValue` instead if the resource was not found.\n\n- In case of an `exactIdentifier` lookup, return the `dummyValue` if the resource with\n  that identifier was not found.\n- In case of a `propertyMatch` lookup, return the `dummyValue` if `expectedMatchCount`\n  is `at-least-one | exactly-one` and the number of resources found was 0.\n\nif `ignoreErrorOnMissingContext` is set, `dummyValue` should be set and be an array.",
                     "default": false,
                     "type": "boolean"
                 },

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

@@ -1,4 +1,4 @@
 {
-  "schemaHash": "5683db246fac20b864d94d7bceef24ebda1a38c8c1f8ef0d5978534097dc9504",
-  "revision": 42
+  "schemaHash": "78936b0f9299bbe47497dd77f8065d71e65d8d739a0413ad7698ad03b22ef83e",
+  "revision": 43
 }

packages/@aws-cdk/node-bundle/README.md

@@ -151,4 +151,4 @@ Note that this will balloon up the package size significantly.
 If you are bundling a CLI application that also has top level exports, we suggest to extract
 the CLI functionality into a function, and add this function as an export to `index.js`.
 
-> See [aws-cdk](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk/bin/cdk.ts) as an example.
+> See [aws-cdk](https://github.com/aws/aws-cdk-cli/blob/main/packages/aws-cdk/bin/cdk) as an example.

packages/aws-cdk/README.md

@@ -536,7 +536,7 @@ and might have breaking changes in the future.
 - `Fn::Split`
 - `Fn::Sub`
 
-> *: `Fn::GetAtt` is only partially supported. Refer to [this implementation](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk/lib/api/evaluate-cloudformation-template.ts#L477-L492) for supported resources and attributes.
+> *: `Fn::GetAtt` is only partially supported. Refer to [this implementation](https://github.com/aws/aws-cdk-cli/blob/main/packages/aws-cdk/lib/api/cloudformation/evaluate-cloudformation-template.ts#L256-L266) for supported resources and attributes.
 
 ### `cdk rollback`