Merge branch 'main' into documentation-fix

.github/workflows/codecov.yml

@@ -0,0 +1,35 @@
+name: Codecov
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  collect:
+    name: collect
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: cd packages/aws-cdk && yarn install
+
+      - name: Build CLI
+        run: cd packages/aws-cdk && npx lerna run build --scope=aws-cdk
+
+      - name: Run tests
+        run: cd packages/aws-cdk && yarn test
+
+      - name: Upload results to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          directory: packages/aws-cdk/coverage
+          fail_ci_if_error: true
+          flags: suite.unit
+          token: ${{ secrets.CODECOV_TOKEN }}

.mergify.yml

@@ -15,6 +15,10 @@ queue_rules:
       - "#changes-requested-reviews-by=0"
       - status-success~=AWS CodeBuild us-east-1
       - status-success=validate-pr
+      - status-success=codecov/patch
+      - status-success=codecov/patch/packages/aws-cdk
+      - status-success=codecov/project
+      - status-success=codecov/project/packages/aws-cdk      
     commit_message_template: |-
       {{ title }} (#{{ number }})
       {{ body }}
@@ -33,6 +37,10 @@ queue_rules:
       - "#changes-requested-reviews-by=0"
       - status-success~=AWS CodeBuild us-east-1
       - status-success=validate-pr
+      - status-success=codecov/patch
+      - status-success=codecov/patch/packages/aws-cdk
+      - status-success=codecov/project
+      - status-success=codecov/project/packages/aws-cdk      
     commit_message_template: |-
       {{ title }} (#{{ number }})
       {{ body }}
@@ -64,6 +72,10 @@ pull_request_rules:
       - "#changes-requested-reviews-by=0"
       - status-success~=AWS CodeBuild us-east-1
       - status-success=validate-pr
+      - status-success=codecov/patch
+      - status-success=codecov/patch/packages/aws-cdk
+      - status-success=codecov/project
+      - status-success=codecov/project/packages/aws-cdk      
   - name: automatic merge (2+ approvers)
     actions:
       comment:
@@ -84,6 +96,10 @@ pull_request_rules:
       - "#changes-requested-reviews-by=0"
       - status-success~=AWS CodeBuild us-east-1
       - status-success=validate-pr
+      - status-success=codecov/patch
+      - status-success=codecov/patch/packages/aws-cdk
+      - status-success=codecov/project
+      - status-success=codecov/project/packages/aws-cdk      
   - name: automatic merge (no-squash)
     actions:
       comment:
@@ -104,6 +120,10 @@ pull_request_rules:
       - "#changes-requested-reviews-by=0"
       - status-success~=AWS CodeBuild us-east-1
       - status-success=validate-pr
+      - status-success=codecov/patch
+      - status-success=codecov/patch/packages/aws-cdk
+      - status-success=codecov/project
+      - status-success=codecov/project/packages/aws-cdk      
   - name: remove stale reviews
     actions:
       dismiss_reviews:
@@ -143,3 +163,7 @@ pull_request_rules:
       - "#changes-requested-reviews-by=0"
       - status-success~=AWS CodeBuild us-east-1
       - status-success=validate-pr
+      - status-success=codecov/patch
+      - status-success=codecov/patch/packages/aws-cdk
+      - status-success=codecov/project
+      - status-success=codecov/project/packages/aws-cdk      

CONTRIBUTING.md

@@ -764,6 +764,40 @@ You can find the dependabot config file [here](./.github/dependabot.yml).
 **If you think your PR introduces a new unconventional dependency, make sure to call it
 out in the description so that we can discuss the best way to manage that dependency.**
 
+### Addressing Code Coverage Gaps
+
+We leverage [Codecov](https://about.codecov.io/) to track code coverage of the project.
+If your PR doesn't meet the coverage requirements, you'll see failing status checks, which will prevent the PR from merging.
+
+There are two requirements we define, each are enforced both on the overall 
+project as well as individual packages.
+
+1. Coverage percentage must not decrease.
+2. Patch percentage must be at least 95%.
+
+Following is an example of status checks for a PR that violates both requirements:
+
+![](./images/codecov-violations.png)
+
+To fix and diagnose coverage gaps in your PR, there are two options:
+
+1. Push your changes to the PR and wait for Codecov to comment on the PR.
+2. If you find option 1 too slow, you can open a local coverage report located in `<path-to-package>/coverage/index.html`
+
+> [!NOTE]
+> Coverage percentage in local reports differs slightly from the percentage you'll see on Codecov.
+> This is ok, and is related to how Codecov handles function signatures (probably).
+> Ultimately Codecov is the source of truth, but you can still use local reports to locate uncovered
+> lines and address them.
+
+Even though it should be rare, sometimes specific lines will be hard to cover by tests.
+To disable coverage of specific lines, you can use:
+
+```ts
+/* istanbul ignore next */
+console.log('This cannot be covered')
+```
+
 ### Step 5: Merge
 
 * Make sure your PR builds successfully (we have CodeBuild setup to automatically build all PRs).

codecov.yml

@@ -0,0 +1,32 @@
+# https://docs.codecov.com/docs/codecovyml-reference#coverage
+coverage:
+  status:
+    project:
+      default:
+        # require the overall project coverage to never decrease
+        target: auto
+    patch:
+      default:
+        # require the overall patch coverage to be at least 95%
+        target: 95
+
+
+# https://docs.codecov.com/docs/codecovyml-reference#comment
+comment:
+  layout: "header, diff, flags, components"
+
+# https://docs.codecov.com/docs/codecovyml-reference#component_management
+component_management:
+  default_rules:
+    statuses:
+      # every component will produce its own status check that requires overall coverage doesnt decrease
+      - type: project
+        target: auto
+      # every component will produce its own status check that requires patch coverage of at least 95%
+      - type: patch
+        target: 95
+  individual_components:
+    - component_id: packages_aws_cdk  # identifier that should not be changed
+      name: packages/aws-cdk # display name that can change freely
+      paths:
+        - packages/aws-cdk/**

packages/@aws-cdk/cloudformation-diff/package.json

@@ -23,8 +23,8 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@aws-cdk/aws-service-spec": "^0.1.31",
-    "@aws-cdk/service-spec-types": "^0.0.98",
+    "@aws-cdk/aws-service-spec": "^0.1.32",
+    "@aws-cdk/service-spec-types": "^0.0.99",
     "chalk": "^4",
     "diff": "^5.2.0",
     "fast-deep-equal": "^3.1.3",

packages/@aws-cdk/integ-runner/package.json

@@ -75,7 +75,7 @@
     "@aws-cdk/cloudformation-diff": "0.0.0",
     "@aws-cdk/cx-api": "0.0.0",
     "cdk-assets": "^2.155.20",
-    "@aws-cdk/aws-service-spec": "^0.1.31",
+    "@aws-cdk/aws-service-spec": "^0.1.32",
     "@aws-cdk/cdk-cli-wrapper": "0.0.0",
     "aws-cdk": "0.0.0",
     "chalk": "^4",

packages/aws-cdk-lib/package.json

@@ -136,7 +136,7 @@
     "mime-types": "^2.1.35"
   },
   "devDependencies": {
-    "@aws-cdk/aws-service-spec": "^0.1.31",
+    "@aws-cdk/aws-service-spec": "^0.1.32",
     "@aws-cdk/cdk-build-tools": "0.0.0",
     "@aws-cdk/custom-resource-handlers": "0.0.0",
     "@aws-cdk/pkglint": "0.0.0",

tools/@aws-cdk/cdk-build-tools/config/jest.config.js

@@ -28,7 +28,11 @@ module.exports = {
     },
   },
   collectCoverage: true,
-  coverageReporters: ['lcov', 'html', 'text-summary', ['text', { file: 'coverage.txt' }]],
+  coverageReporters: [
+    'text-summary', // for console summary
+    'cobertura', // for codecov. see https://docs.codecov.com/docs/code-coverage-with-javascript
+    'html' // for local deep dive
+  ],
   coveragePathIgnorePatterns: ['\\.generated\\.[jt]s$', '<rootDir>/test/', '.warnings.jsii.js$', '/node_modules/'],
   reporters: ['default', ['jest-junit', { suiteName: 'jest tests', outputDirectory: 'coverage' }]],
   /**

tools/@aws-cdk/spec2cdk/package.json

@@ -32,9 +32,9 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@aws-cdk/aws-service-spec": "^0.1.31",
+    "@aws-cdk/aws-service-spec": "^0.1.32",
     "@aws-cdk/service-spec-importers": "^0.0.54",
-    "@aws-cdk/service-spec-types": "^0.0.98",
+    "@aws-cdk/service-spec-types": "^0.0.99",
     "@cdklabs/tskb": "^0.0.3",
     "@cdklabs/typewriter": "^0.0.3",
     "camelcase": "^6",

yarn.lock

@@ -63,12 +63,12 @@
   resolved "https://registry.npmjs.org/@aws-cdk/asset-node-proxy-agent-v6/-/asset-node-proxy-agent-v6-2.1.0.tgz#6d3c7860354d4856a7e75375f2f0ecab313b4989"
   integrity sha512-7bY3J8GCVxLupn/kNmpPc5VJz8grx+4RKfnnJiO1LG+uxkZfANZG3RMHhE+qQxxwkyQ9/MfPtTpf748UhR425A==
 
-"@aws-cdk/aws-service-spec@^0.1.31":
-  version "0.1.31"
-  resolved "https://registry.npmjs.org/@aws-cdk/aws-service-spec/-/aws-service-spec-0.1.31.tgz#ba9758fcc6612b12b4ac55cc83c6fdf272d91d47"
-  integrity sha512-rNVxorA653qon8ArCqL32hpXggk7XdZmHXzGTkLSq8TkYHyuejlbsJO8GCL5I8UvelFwCbGNDCHz+OtZeevZxw==
+"@aws-cdk/aws-service-spec@^0.1.32":
+  version "0.1.32"
+  resolved "https://registry.npmjs.org/@aws-cdk/aws-service-spec/-/aws-service-spec-0.1.32.tgz#11cb000107ef8e7d27736de2a4e4a76b5452d48f"
+  integrity sha512-IaRbCSoplK83syAcccz05hgbW2q2o39qgYoHo9IZSchse9SyTiFjr8BSxHhis4U7LwfT21mXqgnW0JyuzOOqjw==
   dependencies:
-    "@aws-cdk/service-spec-types" "^0.0.98"
+    "@aws-cdk/service-spec-types" "^0.0.99"
     "@cdklabs/tskb" "^0.0.3"
 
 "@aws-cdk/cloud-assembly-schema@^38.0.1":
@@ -129,6 +129,13 @@
   dependencies:
     "@cdklabs/tskb" "^0.0.3"
 
+"@aws-cdk/service-spec-types@^0.0.99":
+  version "0.0.99"
+  resolved "https://registry.npmjs.org/@aws-cdk/service-spec-types/-/service-spec-types-0.0.99.tgz#4d7f7ead4bd66268772ad5e534cb6217caa3364a"
+  integrity sha512-mpTLo2HvTt72TVPMSUBNJ/PoPCT97iMX52NJkw4AJ8Xm45WSOhP0INAYZsIZPdjeM3YJxmWFTAtPQZv5+esQoQ==
+  dependencies:
+    "@cdklabs/tskb" "^0.0.3"
+
 "@aws-crypto/[email protected]":
   version "5.2.0"
   resolved "https://registry.npmjs.org/@aws-crypto/crc32/-/crc32-5.2.0.tgz#cfcc22570949c98c6689cfcbd2d693d36cdae2e1"