fix(pacmak): jsii-pacmak uses incompatible version of jsii-rosetta (#…

…4487)

Fixes #4098 

Previously jsii-pacmak depended on jsii-rosetta 1.x. This is problematic if a different version of the jsii compiler was used, because it introduced different versions of TypeScript into the project.

With this PR, the dependency is changed to a peer dependency. Thus allowing any compatible version jsii-rosetta to be used. 

BREAKING CHANGE: jsii-pacmak now has a peer dependency on jsii-rosetta. Please ensure a version of jsii-rosetta matching your version of jsii is available. Most package managers install peer dependencies automatically and no change is required. However users of yarn v1 or npm v3 to v6 must install jsii-rosetta manually.

---

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

.github/workflows/main.yml

@@ -427,9 +427,17 @@ jobs:
           auto-push: true
 
   pacmak-integration-test:
-    name: Integration test (jsii-pacmak)
     runs-on: ubuntu-latest
     needs: create-release-package
+    strategy:
+      fail-fast: false
+      matrix:
+        rosetta:
+          # this will be the 1.x-dev version build in this repo
+          - ./jsii-rosetta.tgz
+          - 5.2.x
+          - 5.3.x
+          - 5.4.x
     steps:
       # Check out the code
       - name: Download Artifact
@@ -463,19 +471,42 @@ jobs:
         run: sudo apt install -y python3-venv
       # Show time!
       - name: Prepare Work Tree
+        # 1) Move the locally build version of jsii-rosetta somewhere else
+        # 2) Remove @jsii/integ-test because it messed up version dependencies and is not needed
+        # 3) Install aws-cdk-lib, and all locally build packages minus jsii-rosetta & @jsii/integ-test,
+        #    and the specific version of jsii-rosetta
+        #    This ensures we are running jsii-pacmak with the correct peer-dependency
+        # 4) Print the jsii-rosetta version for confirmation
         run: |-
-          npm install --no-save aws-cdk-lib@2 constructs@10                     \
-                                ${{ runner.temp }}/release-package/js/*.tgz     \
-                                ${{ runner.temp }}/release-package/private/*.tgz
+          mv ${{ runner.temp }}/release-package/js/jsii-rosetta.tgz ./jsii-rosetta.tgz
+          rm ${{ runner.temp }}/release-package/private/@jsii-integ-test.tgz
+          npm install --no-save --omit=dev                             \
+                      aws-cdk-lib@2                                    \
+                      constructs@10                                    \
+                      ${{ runner.temp }}/release-package/js/*.tgz      \
+                      ${{ runner.temp }}/release-package/private/*.tgz \
+                      jsii-rosetta@${{ matrix.rosetta }}
+      - name: Display jsii-rosetta version
+        run: npx jsii-rosetta --version
       - name: Run jsii-pacmak on aws-cdk-lib
         env:
           NODE_OPTIONS: --max-old-space-size=6144
         # We run with --no-parallel to avoid running out of memory...
         run: |-
           ./node_modules/.bin/jsii-pacmak --no-parallel ./node_modules/aws-cdk-lib
-      # Upload artifact (we'll tar it up to save time)
+      # Upload artifact only on main and for latest rosetta
       - name: 'Upload Artifact: integtest_aws-cdk-lib'
-        uses: actions/upload-artifact@v3
+        if: github.ref == 'ref/head/main' && matrix.rosetta == '5.4.x'
+        uses: actions/upload-artifact@v4
         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
+    needs: pacmak-integration-test
+    steps:
+      - name: OK
+        # This is just a join target to simplify branch protection setup
+        run: echo OK

gh-pages/content/overview/toolchain.md

@@ -5,19 +5,19 @@
 !!! info
     We are considering creating an "umbrella entrypoint" to make it easier to consume.
 
-| Name            | Release | Stability      | Description                                                           |
-| --------------- | ------- | -------------- | --------------------------------------------------------------------- |
-| [jsii1]         | `1.x`   | [Maintenance]  | Compiles TypeScript to jsii module (TypeScript 3.9 Syntax)            |
-| [jsii]          | `5.0.x` | GA             | Compiles TypeScript to jsii module (TypeScript 5.0 Syntax)            |
-| [jsii-pacmak]   | `1.x`   | GA             | Creates ready-to-publish language-specific packages from jsii modules |
-| [jsii-reflect]  | `1.x`   | GA             | Strong-typed reflection library for jsii type systems                 |
-| [jsii-diff]     | `1.x`   | GA             | API backwards compatibility checker                                   |
-| [jsii-rosetta1] | `1.x`   | [Maintenance]  | Transpile code snippets (in docs) from TypeScript to jsii languages   |
-| [jsii-rosetta]  | `5.0.x` | Experimental   | Transpile code snippets (in docs) from TypeScript to jsii languages   |
-| [jsii-config]   | `1.x`   | Experimental   | Interactive tool for generating jsii configuration                    |
-| [jsii-release]  | `1.x`   | Community      | Publishes jsii modules to all supported package managers              |
-| [jsii-srcmak]   | `1.x`   | Community      | Generates relocatable source code in jsii languages from typescript   |
-| [jsii-docgen]   | `1.x`   | Community      | Generates markdown API documentation for jsii modules                 |
+| Name            | Release | Stability     | Description                                                           |
+| --------------- | ------- | ------------- | --------------------------------------------------------------------- |
+| [jsii1]         | `1.x`   | [Maintenance] | Compiles TypeScript to jsii module (TypeScript 3.9 Syntax)            |
+| [jsii]          | `5.x`   | GA            | Compiles TypeScript to jsii module (TypeScript 5.x Syntax)            |
+| [jsii-pacmak]   | `1.x`   | GA            | Creates ready-to-publish language-specific packages from jsii modules |
+| [jsii-reflect]  | `1.x`   | GA            | Strong-typed reflection library for jsii type systems                 |
+| [jsii-diff]     | `1.x`   | GA            | API backwards compatibility checker                                   |
+| [jsii-rosetta1] | `1.x`   | [Maintenance] | Transpile code snippets (in docs) from TypeScript to jsii languages   |
+| [jsii-rosetta]  | `5.x`   | GA            | Transpile code snippets (in docs) from TypeScript to jsii languages   |
+| [jsii-config]   | `1.x`   | Experimental  | Interactive tool for generating jsii configuration                    |
+| [jsii-release]  | `1.x`   | Community     | Publishes jsii modules to all supported package managers              |
+| [jsii-srcmak]   | `1.x`   | Community     | Generates relocatable source code in jsii languages from typescript   |
+| [jsii-docgen]   | *any*   | Community     | Generates markdown API documentation for jsii modules                 |
 
 ??? question "Stability Definitions"
     - **GA**: Projects that are deemed *Generally Available* and for which customers can expect full support, including
@@ -32,7 +32,6 @@
 
     [semver]: https://semver.org/spec/v2.0.0.html
 
-
 [Maintenance]: ../compiler-and-rosetta-maintenance.md
 [jsii1]: https://github.com/aws/jsii/tree/main/packages/jsii
 [jsii]: https://github.com/aws/jsii-compiler#readme

gh-pages/content/user-guides/language-support/index.md

@@ -163,7 +163,7 @@ declared _Generally Available_. At this point, breaking changes are no longer po
 [`jsii-calc`]: ../../packages/jsii-calc
 [`jsii-config`]: ../../packages/jsii-config
 [`jsii-pacmak`]: ../../packages/jsii-pacmak
-[`jsii-rosetta`]: ../../packages/jsii-rosetta
+[`jsii-rosetta`]: https://github.com/aws/jsii-rosetta
 [standard compliance suite]: ../../specification/4-standard-compliance-suite.md
 [`public.ecr.aws/jsii/superchain`]: ../../superchain
 [`aws-delivlib`]: https://github.com/awslabs/aws-delivlib

packages/jsii-pacmak/.eslintrc.yaml

@@ -3,3 +3,12 @@ extends: ../../eslint-config.yaml
 
 ignorePatterns:
   - test/generated-code/examples/**
+
+rules:
+  'import/no-extraneous-dependencies':
+    - error
+    - devDependencies: # Only allow importing devDependencies from tests
+        - '**/test/**'
+        - '**/*.test.ts'
+      optionalDependencies: false # Disallow importing optional dependencies (those shouldn't be used here)
+      peerDependencies: true # jsii-pacmak has a peer dependency on jsii-rosetta

packages/jsii-pacmak/bin/jsii-pacmak.ts

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 import '@jsii/check-node/run';
-import '../lib/suppress-jsii-upgrade-prompts';
 
 import { UnknownSnippetMode } from 'jsii-rosetta';
 import * as yargs from 'yargs';

packages/jsii-pacmak/lib/builder.ts

@@ -1,4 +1,4 @@
-import { Rosetta } from 'jsii-rosetta';
+import { RosettaTabletReader } from 'jsii-rosetta';
 import * as path from 'path';
 
 import * as logging from './logging';
@@ -44,7 +44,7 @@ export interface BuildOptions {
   /**
    * The Rosetta instance to load examples from
    */
-  readonly rosetta: Rosetta;
+  readonly rosetta: RosettaTabletReader;
 
   /**
    * Whether to generate runtime type checking code in places where compile-time

packages/jsii-pacmak/lib/index.ts

@@ -1,7 +1,5 @@
-import './suppress-jsii-upgrade-prompts';
-
 import { TypeSystem } from 'jsii-reflect';
-import { Rosetta, UnknownSnippetMode } from 'jsii-rosetta';
+import { RosettaTabletReader, UnknownSnippetMode } from 'jsii-rosetta';
 import { resolve } from 'path';
 import { cwd } from 'process';
 
@@ -41,7 +39,7 @@ export async function pacmak({
   updateNpmIgnoreFiles = false,
   validateAssemblies = false,
 }: PacmakOptions): Promise<void> {
-  const rosetta = new Rosetta({
+  const rosetta = new RosettaTabletReader({
     unknownSnippets: rosettaUnknownSnippets,
     prefixDisclaimer: true,
   });
@@ -315,7 +313,7 @@ async function buildTargetsForLanguage(
     fingerprint: boolean;
     force: boolean;
     perLanguageDirectory: boolean;
-    rosetta: Rosetta;
+    rosetta: RosettaTabletReader;
     runtimeTypeChecking: boolean;
   },
 ): Promise<void> {

packages/jsii-pacmak/lib/target.ts

@@ -1,7 +1,7 @@
 import * as spec from '@jsii/spec';
 import * as fs from 'fs-extra';
 import * as reflect from 'jsii-reflect';
-import { Rosetta } from 'jsii-rosetta';
+import { RosettaTabletReader } from 'jsii-rosetta';
 import * as path from 'path';
 import * as spdx from 'spdx-license-list/full';
 
@@ -16,7 +16,7 @@ export abstract class Target {
   protected readonly arguments: { [name: string]: any };
   protected readonly targetName: string;
   protected readonly assembly: reflect.Assembly;
-  protected readonly rosetta: Rosetta;
+  protected readonly rosetta: RosettaTabletReader;
   protected readonly runtimeTypeChecking: boolean;
 
   protected abstract readonly generator: IGenerator;
@@ -211,7 +211,7 @@ export interface TargetOptions {
   assembly: reflect.Assembly;
 
   /** The Rosetta instance */
-  rosetta: Rosetta;
+  rosetta: RosettaTabletReader;
 
   /** Whether to generate runtime type-checking code */
   runtimeTypeChecking: boolean;

packages/jsii-pacmak/lib/targets/dotnet/dotnetdocgenerator.ts

@@ -1,7 +1,7 @@
 import * as spec from '@jsii/spec';
 import { CodeMaker } from 'codemaker';
 import {
-  Rosetta,
+  RosettaTabletReader,
   TargetLanguage,
   enforcesStrictMode,
   markDownToXmlDoc,
@@ -23,7 +23,7 @@ export class DotNetDocGenerator {
 
   public constructor(
     code: CodeMaker,
-    private readonly rosetta: Rosetta,
+    private readonly rosetta: RosettaTabletReader,
     private readonly assembly: spec.Assembly,
   ) {
     this.code = code;
@@ -106,7 +106,7 @@ export class DotNetDocGenerator {
   }
 
   /**
-   * Returns the lines that should go into the <remarks> section
+   * Returns the lines that should go into the <remarks> section {@link http://www.google.com|Google}
    */
   private renderRemarks(docs: spec.Docs, apiLocation: ApiLocation): string[] {
     const ret: string[] = [];

packages/jsii-pacmak/lib/targets/dotnet/dotnetgenerator.ts

@@ -4,7 +4,7 @@ import * as fs from 'fs-extra';
 import * as http from 'http';
 import * as https from 'https';
 import * as reflect from 'jsii-reflect';
-import { Rosetta } from 'jsii-rosetta';
+import { RosettaTabletReader } from 'jsii-rosetta';
 import * as path from 'path';
 
 import { Generator, Legalese } from '../../generator';
@@ -23,7 +23,7 @@ import { ParameterValidator } from './runtime-type-checking';
 export class DotNetGenerator extends Generator {
   private readonly nameutils: DotNetNameUtils = new DotNetNameUtils();
 
-  private readonly rosetta: Rosetta;
+  private readonly rosetta: RosettaTabletReader;
 
   // Flags that tracks if we have already wrote the first member of the class
   private firstMemberWritten = false;
@@ -37,7 +37,7 @@ export class DotNetGenerator extends Generator {
   public constructor(
     private readonly assembliesCurrentlyBeingCompiled: string[],
     options: {
-      readonly rosetta: Rosetta;
+      readonly rosetta: RosettaTabletReader;
       readonly runtimeTypeChecking: boolean;
     },
   ) {

packages/jsii-pacmak/lib/targets/go.ts

@@ -1,7 +1,7 @@
 import { CodeMaker } from 'codemaker';
 import * as fs from 'fs-extra';
 import { Assembly } from 'jsii-reflect';
-import { Rosetta } from 'jsii-rosetta';
+import { RosettaTabletReader } from 'jsii-rosetta';
 import * as path from 'path';
 
 import { IGenerator, Legalese } from '../generator';
@@ -150,11 +150,11 @@ class GoGenerator implements IGenerator {
   });
   private readonly documenter: Documentation;
 
-  private readonly rosetta: Rosetta;
+  private readonly rosetta: RosettaTabletReader;
   private readonly runtimeTypeChecking: boolean;
 
   public constructor(options: {
-    readonly rosetta: Rosetta;
+    readonly rosetta: RosettaTabletReader;
     readonly runtimeTypeChecking: boolean;
   }) {
     this.rosetta = options.rosetta;

packages/jsii-pacmak/lib/targets/go/documentation.ts

@@ -1,12 +1,12 @@
 import { Stability } from '@jsii/spec';
 import { CodeMaker } from 'codemaker';
 import { Docs } from 'jsii-reflect';
-import { ApiLocation, Rosetta, TargetLanguage } from 'jsii-rosetta';
+import { ApiLocation, RosettaTabletReader, TargetLanguage } from 'jsii-rosetta';
 
 export class Documentation {
   public constructor(
     private readonly code: CodeMaker,
-    private readonly rosetta: Rosetta,
+    private readonly rosetta: RosettaTabletReader,
   ) {}
 
   /**

packages/jsii-pacmak/lib/targets/java.ts

@@ -6,7 +6,7 @@ import { createHash } from 'crypto';
 import * as fs from 'fs-extra';
 import * as reflect from 'jsii-reflect';
 import {
-  Rosetta,
+  RosettaTabletReader,
   TargetLanguage,
   enforcesStrictMode,
   markDownToJavaDoc,
@@ -633,10 +633,10 @@ class JavaGenerator extends Generator {
     [name: string]: spec.AssemblyConfiguration;
   } = {};
 
-  private readonly rosetta: Rosetta;
+  private readonly rosetta: RosettaTabletReader;
 
   public constructor(options: {
-    readonly rosetta: Rosetta;
+    readonly rosetta: RosettaTabletReader;
     readonly runtimeTypeChecking: boolean;
   }) {
     super({ ...options, generateOverloadsForMethodWithOptionals: true });

packages/jsii-pacmak/lib/targets/python.ts

@@ -7,7 +7,7 @@ import * as fs from 'fs-extra';
 import * as reflect from 'jsii-reflect';
 import {
   TargetLanguage,
-  Rosetta,
+  RosettaTabletReader,
   enforcesStrictMode,
   ApiLocation,
 } from 'jsii-rosetta';
@@ -2406,7 +2406,7 @@ class PythonGenerator extends Generator {
   private readonly types: Map<string, PythonType>;
 
   public constructor(
-    private readonly rosetta: Rosetta,
+    private readonly rosetta: RosettaTabletReader,
     options: GeneratorOptions,
   ) {
     super(options);

packages/jsii-pacmak/package.json

@@ -45,7 +45,6 @@
     "escape-string-regexp": "^4.0.0",
     "fs-extra": "^10.1.0",
     "jsii-reflect": "^0.0.0",
-    "jsii-rosetta": "^0.0.0",
     "semver": "^7.5.4",
     "spdx-license-list": "^6.8.0",
     "xmlbuilder": "^15.1.1",
@@ -65,8 +64,12 @@
     "jsii": "^0.0.0",
     "jsii-build-tools": "^0.0.0",
     "jsii-calc": "^3.20.120",
+    "jsii-rosetta": "^0.0.0",
     "pyright": "^1.1.332"
   },
+  "peerDependencies": {
+    "jsii-rosetta": "^0.0.0 || ~5.2.0 || ~5.3.0 || ~5.4.0"
+  },
   "keywords": [
     "jsii",
     "aws"

packages/jsii-pacmak/test/targets/go.test.ts

@@ -1,6 +1,6 @@
 import { promises as fs } from 'fs';
 import { TypeSystem } from 'jsii-reflect';
-import { Rosetta } from 'jsii-rosetta';
+import { RosettaTabletReader } from 'jsii-rosetta';
 import { tmpdir } from 'os';
 import { join } from 'path';
 
@@ -18,7 +18,7 @@ test('does not generate imports for unused types', async () => {
       require.resolve('./fixtures/dependent.jsii.json'),
     );
 
-    const rosetta = new Rosetta();
+    const rosetta = new RosettaTabletReader();
     const subject = new Golang({
       arguments: {},
       assembly,

packages/jsii-reflect/lib/class.ts

@@ -122,7 +122,7 @@ export class ClassType extends ReferenceType {
     return out;
   }
 
-  public isClassType() {
+  public isClassType(): this is ClassType {
     return true;
   }