feat(pacmak): support jsii-rosetta 5.7 (#4718)

Adds support for jsii-rosetta 5.7 to jsii-pacmak.

This also changes the peer dependency to simply state the minimal required version.
This will make it less urgent for us to actually release a new version of jsii-pacmak.

Also includes a new script to fully automate the uprade.
A future extension would be to run this script from a workflow.

---

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

[Apache 2.0 license]: https://www.apache.org/licenses/LICENSE-2.0

Author: mrgrain

.github/workflows/main.yml

@@ -1,23 +1,19 @@
 # Workflows pertaining to the main branch
 name: Main
-
 on:
   merge_group: {}
   pull_request:
     branches: [main, release]
   push:
     branches: [main, release]
-
 env:
   DOTNET_NOLOGO: true
   NODE_OPTIONS: --max-old-space-size=4096
-
 # This workflows currently has the following jobs:
 # - build                   : Builds the source tree as-is
 #   - test                  : Runs all unit tests against the build result
 # - create-release-package  : Prepares a release package with the "real" version
 #   - integ-test            : Runs integration tests against the release package
-
 jobs:
   build:
     name: Build
@@ -101,7 +97,6 @@ jobs:
             && echo "Untracked files: ${untracked:-<none>}"                     \
             && test -z "${untracked}"
         shell: bash
-
   create-release-package:
     name: Create Release Package
     permissions:
@@ -182,7 +177,6 @@ jobs:
         with:
           name: release-package
           path: ${{ github.workspace }}/dist/
-
   test:
     permissions:
       contents: none
@@ -291,9 +285,7 @@ jobs:
             java: '8'
             node: '18'
             os: ubuntu-latest
-
     runs-on: ${{ matrix.os }}
-
     steps:
       # Check out the code
       - name: Download Artifact
@@ -366,7 +358,6 @@ jobs:
             && echo "Untracked files: ${untracked:-<none>}"                     \
             && test -z "${untracked}"
         shell: bash
-
   test-ok:
     name: Unit Tests
     runs-on: ubuntu-latest
@@ -379,7 +370,6 @@ jobs:
       - if: ${{ needs.test.result != 'success' }}
         name: Set status based on matrix build
         run: exit 1
-
   pacmak-integration-test:
     runs-on: ubuntu-latest
     needs: create-release-package
@@ -391,6 +381,7 @@ jobs:
           - 5.4.x
           - 5.5.x
           - 5.6.x
+          - 5.7.x
     steps:
       # Check out the code
       - name: Download Artifact
@@ -450,7 +441,6 @@ jobs:
         with:
           name: integtest_aws-cdk-lib
           path: ./node_modules/aws-cdk-lib/dist/
-
   pacmak-integration-test-ok:
     name: Integration test (jsii-pacmak)
     runs-on: ubuntu-latest

.github/workflows/yarn-upgrade.yml

@@ -82,15 +82,15 @@ jobs:
           # Upgrade all production dependencies (and other always major-pinned dependencies)
           lerna exec --parallel ncu -- --upgrade --target=minor                                     \
             --filter='@types/diff,@types/fs-extra,${{ steps.production-dependencies.outputs.list }}'                            \
-            --reject='typescript,@xmldom/xmldom,${{ steps.monorepo-packages.outputs.list }}'
+            --reject='typescript,@xmldom/xmldom,jsii,jsii-rosetta,${{ steps.monorepo-packages.outputs.list }}'
 
           # Upgrade all minor-pinned dependencies
           lerna exec --parallel ncu -- --upgrade --target=patch                                     \
             --filter=typescript,@xmldom/xmldom
 
           # Upgrade all other dependencies (devDependencies) to the latest
           lerna exec --parallel ncu -- --upgrade --target=latest                                    \
-            --reject='@types/diff,@types/inquirer,@types/node,@types/fs-extra,@types/yargs,@xmldom/xmldom,glob,typescript,typescript-json-schema,${{ steps.production-dependencies.outputs.list }},${{ steps.monorepo-packages.outputs.list }}'
+            --reject='@types/diff,@types/inquirer,@types/node,@types/fs-extra,@types/yargs,@xmldom/xmldom,glob,typescript,typescript-json-schema,${{ steps.production-dependencies.outputs.list }},jsii,jsii-rosetta,${{ steps.monorepo-packages.outputs.list }}'
 
       # This will ensure the current lockfile is up-to-date with the dependency specifications (necessary for "yarn update" to run)
       - name: Run "yarn install"

CONTRIBUTING.md

@@ -249,15 +249,25 @@ whether or not it is supported and tested, and produces appropriate warnings in
 - [https://endoflife.date/nodejs](https://endoflife.date/nodejs)
 - [Adding support for node 22 PR](https://github.com/aws/jsii/pull/4489)
 
-## Support for new `jsii-rosetta` versions
+## Support for new `jsii` & `jsii-rosetta` versions
 
 When a new minor version of `jsii-rosetta` (modern) is released, we need to update the `jsii-pacmak` package.
 `jsii-pacmak` uses `jsii-rosetta` to transpile examples in documentation.
 Because every package can use its own version of jsii, TypeScript and jsii-rosetta, it is declared as a peer dependency.
 To ensure compatibility, we also have integration tests.
 
-### Adding a new `jsii-rosetta` version
+### Adding a new `jsii` & `jsii-rosetta` version
 
-1. Add the new version to the `jsii-rosetta` peer dependency in [package.json](./packages/jsii-pacmak/package.json)
-2. Add the new version to the `pacmak-integration-test` matrix in the main build workflow in [main.yml](.github/workflows/main.yml)
-3. Remove any versions for which support has ended (EOS) from both locations
+Run the following command. It takes care of the required changes.
+The script needs `jq` and `yq` installed to run.
+
+```console
+yarn upgrade:jsii
+```
+
+Then you need to run the build and update snapshots locally:
+
+```console
+yarn build
+yarn test:update
+```

package.json

@@ -12,7 +12,8 @@
     "test": "lerna run test --concurrency=1 --stream && yarn compliance",
     "test:integ": "lerna run test:integ --stream",
     "test:update": "lerna run test:update --concurrency=1 --stream",
-    "compliance": "(cd tools/jsii-compliance && yarn report)"
+    "compliance": "(cd tools/jsii-compliance && yarn report)",
+    "upgrade:jsii": "bash scripts/upgrade-jsii.sh"
   },
   "devDependencies": {
     "@jest/types": "^29.6.3",
@@ -32,6 +33,7 @@
     "jest-config": "^28.1.3",
     "jest-expect-message": "^1.1.3",
     "lerna": "^8.1.9",
+    "npm-check-updates": "^9.2.4",
     "prettier": "^3.3.3",
     "standard-version": "^9.5.0",
     "ts-node": "^10.9.2",

packages/@scope/jsii-calc-base-of-base/package.json

@@ -30,9 +30,9 @@
     "test:update": "npm run build && UPDATE_DIFF=1 npm run test"
   },
   "devDependencies": {
-    "jsii": "^5.6.0",
+    "jsii": "^5.7.0",
     "jsii-build-tools": "^0.0.0",
-    "jsii-rosetta": "^5.6.0"
+    "jsii-rosetta": "^5.7.0"
   },
   "jsii": {
     "outdir": "dist",

packages/@scope/jsii-calc-base-of-base/test/assembly.jsii

@@ -9,7 +9,7 @@
   },
   "description": "An example transitive dependency for jsii-calc.",
   "homepage": "https://github.com/aws/jsii",
-  "jsiiVersion": "5.6.0",
+  "jsiiVersion": "5.7.0",
   "license": "Apache-2.0",
   "metadata": {
     "jsii": {
@@ -166,5 +166,5 @@
     }
   },
   "version": "2.1.1",
-  "fingerprint": "itbDtJ87SbwgkYovbu9lFbJPZeKxLga0bRW0aLuyEME="
+  "fingerprint": "PwcsgWKaFz//+WnNgqPa2iYQrz0wG2NLVTTmYtlAe3Q="
 }

packages/@scope/jsii-calc-base/package.json

@@ -35,9 +35,9 @@
     "@scope/jsii-calc-base-of-base": "^2.1.1"
   },
   "devDependencies": {
-    "jsii": "^5.6.0",
+    "jsii": "^5.7.0",
     "jsii-build-tools": "^0.0.0",
-    "jsii-rosetta": "^5.6.0"
+    "jsii-rosetta": "^5.7.0"
   },
   "jsii": {
     "metadata": {

packages/@scope/jsii-calc-base/test/assembly.jsii

@@ -39,7 +39,7 @@
   },
   "description": "An example direct dependency for jsii-calc.",
   "homepage": "https://github.com/aws/jsii",
-  "jsiiVersion": "5.6.0",
+  "jsiiVersion": "5.7.0",
   "license": "Apache-2.0",
   "metadata": {
     "jsii": {
@@ -207,5 +207,5 @@
     }
   },
   "version": "0.0.0",
-  "fingerprint": "YfsMQPprGozJvkv3tDvqfaD0n6nemL/7qgQLBVfozZk="
+  "fingerprint": "owD5dvNwZsCheQcXuO55DpsBC6WVKRk723nURQOT+Dk="
 }

packages/@scope/jsii-calc-lib/package.json

@@ -39,9 +39,9 @@
     "@scope/jsii-calc-base-of-base": "^2.1.1"
   },
   "devDependencies": {
-    "jsii": "^5.6.0",
+    "jsii": "^5.7.0",
     "jsii-build-tools": "^0.0.0",
-    "jsii-rosetta": "^5.6.0"
+    "jsii-rosetta": "^5.7.0"
   },
   "jsii": {
     "outdir": "dist",

packages/@scope/jsii-calc-lib/test/assembly.jsii

@@ -71,7 +71,7 @@
     "stability": "deprecated"
   },
   "homepage": "https://github.com/aws/jsii",
-  "jsiiVersion": "5.6.0",
+  "jsiiVersion": "5.7.0",
   "license": "Apache-2.0",
   "metadata": {
     "jsii": {
@@ -1107,5 +1107,5 @@
     }
   },
   "version": "0.0.0",
-  "fingerprint": "/ufqnDvVVWtV63VSBrPx4dm5v42FAKQp4aDxKl1/f6c="
+  "fingerprint": "YbFe4GUOj1bMi4Nfb//EVD6W94vthn7qqgjK99omHZk="
 }

packages/jsii-calc/package.json

@@ -51,9 +51,9 @@
     "@scope/jsii-calc-lib": "^0.0.0"
   },
   "devDependencies": {
-    "jsii": "^5.6.0",
+    "jsii": "^5.7.0",
     "jsii-build-tools": "^0.0.0",
-    "jsii-rosetta": "^5.6.0"
+    "jsii-rosetta": "^5.7.0"
   },
   "jsii": {
     "outdir": "dist",

packages/jsii-calc/test/assembly.jsii

@@ -146,7 +146,7 @@
     "stability": "stable"
   },
   "homepage": "https://github.com/aws/jsii",
-  "jsiiVersion": "5.6.0",
+  "jsiiVersion": "5.7.0",
   "keywords": [
     "aws",
     "jsii",
@@ -18996,5 +18996,5 @@
     }
   },
   "version": "3.20.120",
-  "fingerprint": "IBXWPJXjzXcQygsQrgkTTCthomDag1ZWYMQ5Sz5X70E="
+  "fingerprint": "0tG7jS936WALug3+Z3mkb+Zts9YiQ1Nqy+xGmWhCzls="
 }

packages/jsii-diff/package.json

@@ -44,7 +44,7 @@
     "@types/fs-extra": "^9.0.13",
     "@types/tar-fs": "^2.0.4",
     "jest-expect-message": "^1.1.3",
-    "jsii": "^5.6.0",
+    "jsii": "^5.7.0",
     "jsii-build-tools": "^0.0.0"
   }
 }

packages/jsii-pacmak/package.json

@@ -52,23 +52,23 @@
   },
   "devDependencies": {
     "@jsii/dotnet-runtime": "^0.0.0",
-    "@jsii/java-runtime": "^0.0.0",
     "@jsii/go-runtime": "^0.0.0",
+    "@jsii/java-runtime": "^0.0.0",
     "@scope/jsii-calc-lib": "^0.0.0",
     "@types/clone": "^2.1.4",
-    "@types/diff": "^5.2.3",
     "@types/commonmark": "^0.27.9",
+    "@types/diff": "^5.2.3",
     "@types/fs-extra": "^9.0.13",
     "@types/semver": "^7.5.8",
     "diff": "^5.2.0",
-    "jsii": "^5.6.0",
+    "jsii": "^5.7.0",
     "jsii-build-tools": "^0.0.0",
     "jsii-calc": "^3.20.120",
-    "jsii-rosetta": "~5.6.0",
+    "jsii-rosetta": "~5.7.0",
     "pyright": "^1.1.389"
   },
   "peerDependencies": {
-    "jsii-rosetta": "~5.4.0 || ~5.5.0 || ~5.6.0"
+    "jsii-rosetta": ">=5.4.0"
   },
   "keywords": [
     "jsii",

packages/jsii-reflect/package.json

@@ -44,7 +44,7 @@
   "devDependencies": {
     "@scope/jsii-calc-lib": "^0.0.0",
     "@types/fs-extra": "^9.0.13",
-    "jsii": "^5.6.0",
+    "jsii": "^5.7.0",
     "jsii-build-tools": "^0.0.0",
     "jsii-calc": "^3.20.120"
   }

scripts/upgrade-jsii.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+#------------------------------------------------------------------------
+# updates all package.json files to the latest jsii
+# and jsii-rosetta versions
+# updates the jsii-pacmak peer dep to the latest supported version
+# updates the build matrix in the .github/workflows/main.yml file
+#------------------------------------------------------------------------
+set -euo pipefail
+scriptdir=$(cd $(dirname $0) && pwd)
+
+# go to repo root
+cd ${scriptdir}/..
+
+# load version data
+tomorrow=$(date -v+1d +%s)
+supported=$(curl -sS https://raw.githubusercontent.com/aws/jsii-rosetta/refs/heads/main/releases.json |\
+  jq "(.maintenance | to_entries | sort_by(.value) | .[] | select(.value | .[0:19] +\"Z\" | fromdateiso8601 >= $tomorrow) | .key), .current")
+latest=$(echo $supported | jq -sr '.[-1]')
+oldest=$(echo $supported | jq -sr '.[0]')
+
+echo "Latest supported jsii & jsii-rosetta version: $latest"
+echo "Oldest supported jsii & jsii-rosetta version: $oldest"
+echo ""
+
+# Set jsii-pacmak minimal dependency
+echo "Updating jsii-pacmak peerDependency to >=$oldest.0"
+echo ""
+npm --prefix packages/jsii-pacmak pkg set peerDependencies.jsii-rosetta=">=$oldest.0"
+
+# GitHub Actions
+matrix=$(echo $supported | jq -rs '["latest"] + map(. + ".x") | @csv')
+echo "Updating GitHub Actions workflow to run jsii-pacmak integration tests for $matrix"
+echo ""
+yq -i ".jobs.pacmak-integration-test.strategy.matrix.rosetta = [$matrix]" .github/workflows/main.yml
+
+# update jsii and jsii-rosetta versions
+echo "Upgrading jsii & jsii-rosetta to latest"
+echo ""
+npx lerna exec --parallel ncu -- --upgrade --target=latest --dep=prod,dev --filter=jsii,jsii-rosetta