chore(release): 1.85.0 (#4180)

See [CHANGELOG](https://github.com/aws/jsii/blob/bump/1.85.0/CHANGELOG.md)

.github/dependabot.yml

@@ -8,6 +8,7 @@ updates:
  labels:
  - dependencies
  - language/dotnet
+ - auto-approve
 
  - package-ecosystem: nuget
  directory: '/packages/@jsii/dotnet-runtime-test/test'
@@ -16,6 +17,7 @@ updates:
  labels:
  - dependencies
  - language/dotnet
+ - auto-approve
 
  - package-ecosystem: pip
  directory: '/packages/@jsii/python-runtime'
@@ -24,6 +26,7 @@ updates:
  labels:
  - dependencies
  - language/python
+ - auto-approve
 
  - package-ecosystem: pip
  directory: '/gh-pages'
@@ -32,6 +35,7 @@ updates:
  labels:
  - dependencies
  - language/python
+ - auto-approve
 
  - package-ecosystem: pip
  directory: '/packages/jsii-pacmak/test/generated-code'
@@ -40,6 +44,7 @@ updates:
  labels:
  - dependencies
  - language/python
+ - auto-approve
 
  - package-ecosystem: pip
  directory: '/packages/jsii-pacmak/lib/targets/python'
@@ -48,6 +53,7 @@ updates:
  labels:
  - dependencies
  - language/python
+ - auto-approve
  ignore:
  - dependency-name: "setuptools"
 
@@ -58,6 +64,7 @@ updates:
  labels:
  - dependencies
  - language/go
+ - auto-approve
 
  - package-ecosystem: gomod
  directory: '/packages/@jsii/go-runtime-test/project'
@@ -66,6 +73,7 @@ updates:
  labels:
  - dependencies
  - language/go
+ - auto-approve
  ignore:
  - dependency-name: github.com/aws/jsii-runtime-go
  - dependency-name: github.com/aws/jsii-runtime-go/*
@@ -77,3 +85,4 @@ updates:
  interval: daily
  labels:
  - dependencies
+ - auto-approve

.github/workflows/close-stale-issues.yml

@@ -34,7 +34,7 @@ jobs:
  # Issue timing
  days-before-stale: 2
  days-before-close: 5
- days-before-ancient: 730
+ days-before-ancient: 36500
 
  # If you don't want to mark a issue as being ancient based on a
  # threshold of "upvotes", you can set this here. An "upvote" is

.github/workflows/docker-images.yml

@@ -2,6 +2,7 @@
 name: Docker Images
 
 on:
+ merge_group: {}
  pull_request:
  branches: [main, release]
  push:

.github/workflows/gh-pages.yml

@@ -2,6 +2,7 @@
 name: GitHub Pages
 
 on:
+ merge_group: {}
  pull_request:
  branches: [main]
  push:

.github/workflows/handle-stale-discussions.yml

@@ -0,0 +1,18 @@
+name: HandleStaleDiscussions
+on:
+ schedule:
+ - cron: '0 */4 * * *'
+ discussion_comment:
+ types: [created]
+
+jobs:
+ handle-stale-discussions:
+ name: Handle stale discussions
+ runs-on: ubuntu-latest
+ permissions:
+ discussions: write
+ steps:
+ - name: Stale discussions action
+ uses: aws-github-ops/handle-stale-discussions@v1
+ env:
+ GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.github/workflows/main.yml

@@ -2,6 +2,7 @@
 name: Main
 
 on:
+ merge_group: {}
  pull_request:
  branches: [main, release]
  push:

.github/workflows/pull-request-lint.yml

@@ -1,5 +1,6 @@
 name: pull-request-lint
 on:
+ merge_group: {}
  pull_request_target:
  types:
  - labeled

.github/workflows/yarn-upgrade.yml

@@ -21,7 +21,7 @@ jobs:
  uses: actions/setup-node@v3
  with:
  cache: yarn
- node-version: 14
+ node-version: 16
 
  - name: Install Tools
  run: |-

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [1.85.0](https://github.com/aws/jsii/compare/v1.84.0...v1.85.0) (2023-07-17)
+
+
+### Bug Fixes
+
+* export transliterateAssembly and fix bug with transliterate cli (backport) ([#4166](https://github.com/aws/jsii/issues/4166)) ([6b7eb02](https://github.com/aws/jsii/commit/6b7eb02f3a822941185e8c74be71d677285c741e))
+* **go-runtime:** use fatih/color instead of ANSI Escape Code ([#4109](https://github.com/aws/jsii/issues/4109)) ([28b192a](https://github.com/aws/jsii/commit/28b192aa1a3ecdd3b3ce6ee49a5efd32db01e695))
+
 ## [1.84.0](https://github.com/aws/jsii/compare/v1.83.0...v1.84.0) (2023-06-13)
 
 

CONTRIBUTING.md

@@ -20,7 +20,7 @@ The image can be built for local usage, too:
 
 ```console
 $ IMAGE=superchain
-$ docker build -t ${IMAGE} ./superchain
+$ docker build -t ${IMAGE} -f superchain/Dockerfile .
 ```
 
 In order to get an interactive shell within a Docker container using the

gh-pages/content/overview/features.md

@@ -1,5 +1,24 @@
 # Features
 
+## Use-Cases & Limitations
+
+The _jsii_ toolchain allows developers to author class libraries once in TypeScript, while allowing their customers to
+consume them in various [other languages](#target-languages). This is used for libraries such as the AWS CDK (
+[`aws-cdk-lib`](https://npmjs.com/package/aws-cdk-lib)), and is intended for use in similar contexts: client-side,
+design-time SDKs that do not require long-running processes and is not in the path to serve time-sensitive requests.
+
+Due to limitations of its [runtime architecture](./runtime-architecture.md), _jsii libraries_ for languages other than
+Javascript/TypeScript are best suited for inclusion in short-running processes, outside of performance-sensitive or
+memory-constrained contexts.
+
+While `async` APIs are supported by the _jsii_ type system, support for these should be treated as highly experimental.
+In particular, support in the various [target languages](#target-languages) varies greatly, and users may encounter a
+variety of bugs or surprising behaviors. The current JavaScript-based cross-language interoperability kernel is also
+known to block execution of background micro-tasks when it's waiting for commands from the host process.
+
+The runtime libraries used by _jsii libraries_ are not currently designed for thread safety, and using _jsii libraries_
+in multi-thread contexts is unsupported at the moment.
+
 ## TypeScript Support
 
 The `jsii` compiler leverages the original [TypeScript] compiler API to compile **TypeScript** source files and produce
@@ -11,7 +30,7 @@ To determine the version of **TypeScript** that is in use by the installed relea
 
 ```console
 # jsii --version
-1.15.0 (build 585166b), typescript 3.9.7
+5.1.6 (build d8f400c), typescript 5.1.6
 ```
 
 You can then refer to the [TypeScript] documentation to determine which language features are available in that specific

gh-pages/content/specification/3-kernel-api.md

@@ -471,10 +471,18 @@ such values.
 
 #### Asynchronous method invocation
 
+!!! bug "Largely un-tested"
+ Asynchronous operations are only partially supported in the various target languages, and is currently not widely
+ used. As such, support is not as "battle-tested" as the rest of the jsii interoperability features, and customers
+ may run into usability issues, unexpected bugs, or surprising behaviors when using async.
+
+ In particular, outstanding `Promise`s may not be able to make progress as expected due to specific implementation
+ details of the `@jsii/runtime` event loop, which can result in deadlock situations.
+
 The `invoke` call can only be used to invoke _synchronous_ methods. In order to invoke _asynchronous_ methods, the
-`begin` and `end` calls must be used instead. Once the _host_ app has entered an asynchronous workflow (after it makes
-the first `begin` call), and until it has completed all asynchronous operations (after all `begin` class are matched
-with an `end` call), no _synchronous_ operation (including synchronous callbacks) may be initiated.
+`begin` and `end` calls must be used instead. Once the _host_ app has entered a synchronous workflow (after it makes
+an `invoke` call), and until it has completed that synchronous operation (after all callbacks have been handled and the
+`InvokeResponse` has been received), no _asynchronous_ operation may be initiated by the host app.
 
 ```ts
 interface BeginRequest {

gh-pages/content/user-guides/lib-author/.pages.yml

@@ -4,6 +4,6 @@ nav:
  - index.md
  - quick-start
  - typescript-restrictions.md
- - configuration
  - hints.md
+ - configuration
  - toolchain

gh-pages/content/user-guides/lib-author/hints.md

@@ -1,4 +1,4 @@
-# Type system hints
+# Special TSDoc tags
 
 The `jsii` compiler interprets some documentation tags as hints that influence
 the type system represented in the `.jsii` assembly files.
@@ -13,7 +13,7 @@ another capital letter (which normally would make them be treated as
 [struct]: ../../specification/2-type-system.md#structs
 [interface]: ../../specification/2-type-system.md#behavioral-interfaces
 
-```ts
+```ts hl_lines="2"
 /**
  * @struct
  */
@@ -25,3 +25,27 @@ export interface IPRange {
 !!! important
  The `@struct` hint can only be used on interface declarations. Attempting to
  use them on any other declaration will result in a compilation error.
+
+## Excluding a declaration from multi-language support
+
+The `@jsii ignore` tag causes the documented declaration to be ignored by the
+`jsii` compiler. This has the effect of making the declaration invisible to
+languages other than **TypeScript** and **Javascript**. Developers using this
+tag should consider the implications on the usability of their library in other
+languages.
+
+```ts hl_lines="9"
+export interface Props {
+ public readonly name: string;
+
+ /**
+ * TypeScript/Javascript customers may pass additional properties with this
+ * struct, however this will not be possible in other languages, as jsii does
+ * not support index signatures.
+ *
+ * @jsii ignore
+ */
+ public readonly [key: string]: unknown;
+}
+
+```

gh-pages/content/user-guides/lib-author/typescript-restrictions.md

@@ -160,14 +160,36 @@ export class Child extends Base {
 }
 ```
 
-## Parameterized Types (aka: Generics)
+## Index Signatures
 
-Parameterized types are not consistently supported in all supported target languages. **Go** does not currently support
-generics, and the differences in generic semantics between **TypeScript**, **C#** and **Java** make it difficult to
-correctly represent such types in all those languages. As a consequence, `jsii` does not support declaring parameterized
-types.
+**TypeScript** allows declaring _additional properties_ through the use of index signatures. These are however not
+supported by the _jsii type system_ and are rejected by the compiler.
 
-Only certain *built-in* parameterized types can be used in `jsii` modules:
+!!! info
+ Version `1.x` of the compiler _silently ignores_ index signatures instead of reporting a compilation error. Users
+ with offending APIs migrating from `jsii@1.x` to `jsii@5.0` or newer need to either remove those declarations, or
+ explicitly ignore them using the [`@jsii ignore` tag](./hints.md#excluding-a-declaration-from-multi-language-support).
+
+```ts hl_lines="4-5"
+export interface WithIndexSignature {
+ public readonly name: string;
+
+ // 💥 Index signatures are not supported
+ public [key: string]: unknown;
+}
+```
+
+## TypeScript Mapped Types
+
+!!! info
+ These are also referred to as "Generics", "Parameterized Types", "Utility Types", ...
+
+Parameterized types are not consistently supported in all supported target languages. **Go** support for generics is
+relatively limited (for good reasons) compared to TypeScript and most Object-Oriented languages, and the differences in
+generic semantics between **TypeScript**, **C#** and **Java** make it difficult to correctly represent such types in all
+those languages. As a consequence, `jsii` does not support declaring parameterized types.
+
+Certain *built-in* TypeScript types can however be used in `jsii` modules:
 
 - `Array<T>`, which is equivalent to `T[]`
 - `Record<string, T>`, which is equivalent to `{ [key: string]: T }`
@@ -187,7 +209,35 @@ export interface IAsyncFooMaker {
 }
 ```
 
-# Soft-Reserved Words
+!!! danger "`#!ts Pick<T, Keys>` and `#!ts Omit<T, Keys>`"
+ Users are often tempted to use `#!ts Pick<T, Keys>` and `#!ts Omit<T, Keys>` when creating higher level abstractions
+ of types exposed by their dependencies, and they want to expose all configuration options from the upstream
+ implementation except for some specific properties which are determined fully by the new abstraction.
+
+ `#!ts Pick<T, Keys>` and `#!ts Omit<T, Keys>` are not supported as they would result in open-ended implementation
+ requirements to exist in languages such as **Java** and **C#** where such things are not possible.
+
+ Users with this particular use-case should investigate generating code in order to reproduce the upstream type
+ without the filtered out fields. For example, this can be done with [`projen`](http://npmjs.com/package/projen)
+ using [`jsii-struct-builder`](https://github.com/mrgrain/jsii-struct-builder).
+
+## Type Aliases
+
+TypeScript supports type aliasing using the `#!ts export type Name = ...` syntax. While this is not considered a
+compilation error by the `jsii` compiler, those types are implicitly de-sugared by the compiler for all language targets
+except for **TypeScript**.
+
+```ts hl_lines="1-2 5-6"
+// 👻 Only visible in TypeScript
+export type FooOrBar = Foo | Bar;
+
+export interface Props {
+ // ⚠️ Effectively `readonly fooOrBar: Foo | Bar;` in non-TypeScript
+ readonly fooOrBar: FooOrBar;
+}
+```
+
+## Soft-Reserved Words
 
 In order to guarantee a consistent developer experience across all supported languages, `jsii` emits warnings whenever
 a declaration is named after any target language's *reserved words*, as those will need renaming in target languages:

gh-pages/requirements-dev.txt

@@ -1,4 +1,4 @@
 mkdocs~=1.4.3
 mkdocs-awesome-pages-plugin~=2.9.1
-mkdocs-material~=9.1.15
+mkdocs-material~=9.1.18
 mkdocs-git-revision-date-plugin~=0.3.2

lerna.json

@@ -1,14 +1,17 @@
 {
- "lerna": "3.13.1",
  "npmClient": "yarn",
- "useWorkspaces": true,
+ "rejectCycles": true,
  "packages": [
- "packages/*"
+ "packages/*",
+ "packages/@jsii/*",
+ "packages/@scope/*",
+ "tools/*"
  ],
  "command": {
  "bootstrap": {
  "rejectCycles": true
  }
  },
- "version": "1.84.0"
+ "version": "1.85.0",
+ "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }