chore(release): 1.99.0 (#4528)

See [CHANGELOG](https://github.com/aws/jsii/blob/bump/1.99.0/CHANGELOG.md)
aws · Jun 3, 2024 · 8f757e4 · 8f757e4
2 parents 00b106d + 63f24d7
commit 8f757e4
Show file tree

Hide file tree

Showing 51 changed files with 2,100 additions and 1,631 deletions.
diff --git a/.github/workflows/docker-images.yml b/.github/workflows/docker-images.yml
@@ -24,7 +24,7 @@ jobs:
         debian:
           - 'bullseye' # 11
           - 'bookworm' # 12
-        node: ['18', '20', '22']
+        node: ['18', '20', '22'] # STOP! Before adding anything here, check our maintenance policy in the README
         exclude:
           # We publish bullseye only with Node >= 20
           - debian: 'bullseye'

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,13 @@
 
 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.99.0](https://github.com/aws/jsii/compare/v1.98.0...v1.99.0) (2024-06-03)
+
+
+### Bug Fixes
+
+* **jsii-config:** update jsii-config and docs with latest settings ([#4515](https://github.com/aws/jsii/issues/4515)) ([6e00874](https://github.com/aws/jsii/commit/6e00874c9a70890b9291a4fa534eb497e7a186f9))
+
 ## [1.98.0](https://github.com/aws/jsii/compare/v1.97.0...v1.98.0) (2024-04-30)
 
 

diff --git a/gh-pages/content/specification/2-type-system.md b/gh-pages/content/specification/2-type-system.md
@@ -325,7 +325,7 @@ Typescript allows grouping declarations together in _namespaces_, which are inte
 _Submodules_ names are the fully qualified name of the namespace from the package's root (if a package `foo` defines a
 namespace `ns1`, which itself contains `ns2`, the submodule for `ns2` will be named `foo.ns1.ns2`).
 
-_Submodules_ are delcared in the _jsii_ assembly under the `submodules` key. This is also where specific
+_Submodules_ are declared in the _jsii_ assembly under the `submodules` key. This is also where specific
 [configuration](#submodule-configuration) is registered, if different from the parent submodule or package.
 
 _Submodules_ are hierarchical, and their fully qualified name is representative of the relationship. For example the

diff --git a/gh-pages/content/specification/3-kernel-api.md b/gh-pages/content/specification/3-kernel-api.md
@@ -246,7 +246,7 @@ Sometimes, the _host_ app will extend a _jsii_ class and implement new _jsii_ in
 original type. Such interfaces must be declared by providing their _jsii_ fully qualified name as an entry in the
 `interfaces` list.
 
-Providing interfaces in this list that are implicitly present from another delcaration (either because they are already
+Providing interfaces in this list that are implicitly present from another declaration (either because they are already
 implemented by the class denoted by the `fqn` field, or because another entry in the `interfaces` list extends it) is
 valid, but not necessary. The `@jsii/kernel` is responsible for correctly handling redundant declarations.
 

diff --git a/gh-pages/content/user-guides/lib-author/configuration/index.md b/gh-pages/content/user-guides/lib-author/configuration/index.md
@@ -17,8 +17,8 @@ optional in the standard [package.json schema] are required by `jsii`.
 For example, Maven Central requires packages to carry [sufficient metadata], such as _developer information_ and
 _license_, in order to be valid for publishing.
 
-| Field        | Required                        | Extensions                       |
-| ------------ |:-------------------------------:| -------------------------------- |
+| Field        |            Required             | Extensions                       |
+| ------------ | :-----------------------------: | -------------------------------- |
 | `author`     | :octicons-check-circle-fill-24: | `author.organization`            |
 | `license`    | :octicons-check-circle-fill-24: |                                  |
 | `main`       | :octicons-check-circle-fill-24: |                                  |
@@ -135,32 +135,20 @@ package maintainer, the generic interpretation for those on packages is:
 In order to configure the behavior of `jsii`, the `package.json` file must include a `jsii` section that can contain the
 following entries:
 
-| Field               | Type                    | Required                        | Default                              |
-| ------------------- | ----------------------- |:-------------------------------:| ------------------------------------ |
-| `excludeTypescript` | `#!ts string[]`         |                                 | _none_                               |
-| `metadata`          | `#!ts object`           |                                 | _none_                               |
-| `projectReferences` | `#!ts boolean`          |                                 | `#!ts true`                          |
-| `targets`           | `#!ts object`           | :octicons-check-circle-fill-24: |                                      |
-| `tsc`               | `#!ts object`           |                                 | `#!ts { outDir: '.', rootDir: '.' }` |
-| `versionFormat`     | `#!ts 'short' | 'full'` |                                 | `#!ts 'full'`                        |
+| Field               | Type                                              |            Required             | Default                              | Supported versions |
+| ------------------- | ------------------------------------------------- | :-----------------------------: | ------------------------------------ | ------------------ |
+| `excludeTypescript` | `#!ts string[]`                                   |                                 | _none_                               | _all_              |
+| `metadata`          | `#!ts object`                                     |                                 | _none_                               | _all_              |
+| `projectReferences` | `#!ts boolean`                                    |                                 | `#!ts true`                          | _all_              |
+| `targets`           | `#!ts object`                                     | :octicons-check-circle-fill-24: |                                      | _all_              |
+| `tsc`               | `#!ts object`                                     |                                 | `#!ts { outDir: '.', rootDir: '.' }` | _all_              |
+| `tsconfig`          | `#!ts string`                                     |                                 | _none_                               | `>= 5.2`           |
+| `validateTsconfig`  | `#!ts 'strict' | 'generated' | 'minimal' | 'off'` |                                 | _none_                               | `>= 5.2`           |
+| `versionFormat`     | `#!ts 'short' | 'full'`                           |                                 | `#!ts 'full'`                        | _all_              |
 
-### `excludeTypescript`
+### Language targets
 
-By default, `jsii` will include _all_ `*.ts` files (except `.d.ts` files) in the `TypeScript` compiler input. This can
-be problematic for example when the package's build or test procedure generates `.ts` files that cannot be compiled with
-`jsii`'s compiler settings.
-
-The `excludeTypescript` configuration accepts a list of glob patterns. Files matching any of those patterns will be
-excluded from the `TypeScript` compiler input.
-
-### `metadata`
-
-The `metadata` section can be used to record additional metadata as key-value pairs that will be recorded as-is into the
-`.jsii` assembly file. That metadata can later be inspected using [`jsii-reflect`][jsii-reflect] utilities, for example.
-
-[jsii-reflect]: https://github.com/aws/jsii/tree/main/packages/jsii-reflect
-
-### `targets`
+#### `targets`
 
 The `targets` section is where `jsii` packages define which target languages they support. This provides the package
 generators with the additional information they require in order to name generated artifacts. Configuration is provided
@@ -173,7 +161,31 @@ The specific configuration accepted for each supported language is presented in
 - [:octicons-book-24: Java Target](targets/java.md)
 - [:octicons-book-24: Python Target](targets/python.md)
 
-### `tsc`
+### Typescript configuration
+
+By default, `jsii` generates a `tsconfig.json` for you, using best practice settings that are optimized for
+widespread support and backwards compatibility. Use the `excludeTypescript` and `tsc` settings to configure
+some supported typescript compiler options.
+
+You may want to customize the typescript configuration even further. In this case, use the `tsconfig` setting
+to instruct the jsii compiler to use user-owned typescript configuration file. Such a user-provider tsconfig must
+follow certain rules to be a valid config for use with jsii. These rules are enforced via the `validateTsconfig`
+setting. You may choose the level of validation to match your use case.
+
+!!! info
+    Using a user-provider tsconfig and configuration via `excludeTypescript` and `tsc` are mutually exclusive.
+    Specifically when using a user-provided tsconfig, any other configuration settings will be ignored.
+
+#### `excludeTypescript`
+
+By default, `jsii` will include _all_ `*.ts` files (except `.d.ts` files) in the `TypeScript` compiler input. This can
+be problematic for example when the package's build or test procedure generates `.ts` files that cannot be compiled with
+`jsii`'s compiler settings.
+
+The `excludeTypescript` configuration accepts a list of glob patterns. Files matching any of those patterns will be
+excluded from the `TypeScript` compiler input.
+
+#### `tsc`
 
 In order to the generated `javascript` can be properly loaded by the `jsii` runtimes, `jsii` generates a
 [`tsconfig.json`] file with fixed settings at the beginning of the compilation pass. Certain configuration options can
@@ -188,11 +200,11 @@ are set in the `jsii.tsc` section of the `package.json` file, but use the same n
 - `forceConsistentCasingInFileNames` - if `true`, will make the `TypeScript` compiler care about the casing of files
    specified in `import` statements. This is helpful if you're developing on a filesystem that is case-insensitive
    (Mac/Win), but building/deploying on a filesystem that is case-sensitive (Linux).
-- `declarationMap`, `inlineSourceMap`, `inlineSources`, and `sourceMap` allow confifuring the source map generation.
+- `declarationMap`, `inlineSourceMap`, `inlineSources`, and `sourceMap` allow configuring the source map generation.
   This option can be useful to finely control your local development experience (for example, by enabling
   `declarationMap`), or to optimize the emitted code size (by disabling source maps entirely).
-  + if any of these options is specified, the source map configuration will exactly match what is being provided here
-  + If none are specified, the default settings will be used: `#!ts { inlineSourceMap: true, inlineSources: true }`
+  - if any of these options is specified, the source map configuration will exactly match what is being provided here
+  - If none are specified, the default settings will be used: `#!ts { inlineSourceMap: true, inlineSources: true }`
 - `types` allows limiting which visible type libraries get loaded in the global scope by the typescript compiler. By
   default, all visible `@types/*` packages will be loaded, which can be undesirable (in particular in monorepos, where
   some type libraries are not compatible with the TypeScript compiler version that `jsii` uses). The value specified
@@ -204,7 +216,59 @@ Refer to the [TypeScript compiler options reference][ts-options] for more inform
 [`tsconfig.json`]: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html
 [ts-options]: https://www.typescriptlang.org/docs/handbook/compiler-options.html
 
-### `versionFormat`
+#### `tsconfig`
+
+_Available from jsii >= 5.2_
+
+!!! warn
+    :test_tube: This features is experimental. Behavior may change as bugs are addressed, and requirements are clarified
+    through early adopters. Use at your own risk, and please any [report bugs].
+
+Provide this setting, to use a user-provided typescript configuration with `jsii`. Set to the name of the tsconfig
+file that should be used. Usually this will be `"tsconfig.json"`, but can be set to any filename.
+The provided tsconfig is subject to validation rules, see below for more details.
+
+```json
+{
+  "jsii": {
+    "tsconfig": "tsconfig.json"
+  }
+}
+```
+
+#### `validateTsconfig`
+
+_Available from jsii >= 5.2_
+
+!!! warn
+    :test_tube: This features is experimental. Behavior may change as bugs are addressed, and requirements are clarified
+    through early adopters. Use at your own risk, and please any [report bugs].
+
+A user-provider typescript config must follow certain rules to be a valid config for use with jsii.
+By default the tsconfig is validated against the `strict` rule set.
+If needed, you can change the level of enforcement with the `validateTsconfig` setting.
+
+--8<-- "partials/tsconfig-rulesets.md"
+
+```json
+{
+  "jsii": {
+    "tsconfig": "tsconfig.json",
+    "validateTsconfig": "generated" // ensure user tsconfig is similar to jsii-generated tsconfig
+  }
+}
+```
+
+### Metadata
+
+#### `metadata`
+
+The `metadata` section can be used to record additional metadata as key-value pairs that will be recorded as-is into the
+`.jsii` assembly file. That metadata can later be inspected using [`jsii-reflect`][jsii-reflect] utilities, for example.
+
+[jsii-reflect]: https://github.com/aws/jsii/tree/main/packages/jsii-reflect
+
+#### `versionFormat`
 
 Determines the format of the `jsii` toolchain version string that will be included in the `.jsii` assembly file's
 `jsiiVersion` attribute.
@@ -270,3 +334,4 @@ modules, **must** also be referenced in the [`bundledDependencies`][npm-bundled]
 within the NPM package.
 
 [npm-bundled]: https://docs.npmjs.com/files/package.json#bundleddependencies
+[report bugs]: https://github.com/aws/jsii/issues/new/choose
diff --git a/gh-pages/content/user-guides/lib-author/index.md b/gh-pages/content/user-guides/lib-author/index.md
@@ -14,27 +14,27 @@ must be available. Current `node` runtime versions support status is as follows:
 When developing _jsii modules_, the SDK for each desired target language must be available for `jsii-pacmak` to be able
 to produce releasable artifacts.
 
-| Language/Platform | SDK Requirement              |
-| ----------------- | ---------------------------- |
-| .NET              | .NET ≥ 6.0                   |
-| Go                | Go ≥ 1.18                    |
-| Java              | JDK ≥ 8 *and* Maven ≥ 3.6    |
-| Python            | Python ≥ 3.8                 |
-
+| Language/Platform | SDK Requirement           |
+| ----------------- | ------------------------- |
+| .NET              | .NET ≥ 6.0                |
+| Go                | Go ≥ 1.18                 |
+| Java              | JDK ≥ 8 _and_ Maven ≥ 3.6 |
+| Python            | Python ≥ 3.8              |
 
 ## :octicons-desktop-download-24: Download Locations
 
 This table provides typical download locations for the prerequisites mentioned in this document. Most of these tools can
 also be installed using traditional package managers (standard for the operating system and platform).
 
 | Tool            | Description                              | Location                |
-| --------------- | ---------------------------------------- | ------------------------|
+| --------------- | ---------------------------------------- | ----------------------- |
 | .NET            | Official Microsoft .NET SDK distribution | [Download][dl-dotnet]   |
 | Amazon Corretto | Amazon's free OpenJDK distribution       | [Download][dl-corretto] |
 | Go              | Official Go distribution                 | [Download][dl-go]       |
-| OpenJDK         | Oracle OpenJDK distribution              | [Download][dl-openjdk]  |
 | Maven           | Official Maven distribution              | [Download][dl-mvn]      |
-| Node            | Official NodeJS distribution             | [Download][dl-node]     |
+| Node            | Official Node.js distribution            | [Download][dl-node]     |
+| OpenJDK         | Oracle OpenJDK distribution              | [Download][dl-openjdk]  |
+| Python          | Official Python distribution             | [Download][dl-python]   |
 
 [dl-dotnet]: https://dotnet.microsoft.com/download
 [dl-go]: https://golang.org/dl/

diff --git a/gh-pages/content/user-guides/lib-author/toolchain/jsii.md b/gh-pages/content/user-guides/lib-author/toolchain/jsii.md
@@ -59,6 +59,22 @@ reserved words in an identifier.
 
     [report bugs]: https://github.com/aws/jsii/issues/new/choose
 
+#### `--tsconfig`, `--validate-tsconfig` _(available from jsii >= 5.2)_
+
+By default, jsii will generate a `tsconfig.json` for you, using best practice
+settings that are optimized for widespread support and backwards compatibility.
+In some situations it can be useful to provide a custom typescript
+configuration file to compile the jsii project.
+
+Use the `--tsconfig` option to provide a path the config file, usually this
+will be `--tsconfig=tsconfig.json`.
+
+A user-provider typescript config must follow certain rules to be a valid
+config for use with jsii. These rules are enforced by the `--validate-tsconfig`
+option. You may choose the level of validation to suit your use case.
+
+--8<-- "partials/tsconfig-rulesets.md"
+
 #### `--strip-deprecated`
 
 The `--strip-deprecated` option modifies the compilation flow such that all
@@ -105,4 +121,4 @@ or `quiet` to either fail at runtime or silence these warnings, respectively.
 By default, this is set to `warn`.
 
 The `JSII_DEPRECATED` environment variable is respected only on modules compiled
-with the `--add-deprecated-warnings` flag.
+with the `--add-deprecated-warnings` flag.
diff --git a/gh-pages/partials/tsconfig-rulesets.md b/gh-pages/partials/tsconfig-rulesets.md
@@ -0,0 +1,11 @@
+| Rule set            | Description                                                                                                                                                                               |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `strict` :star:     | (Default) Validates the provided config against a strict rule set designed for widespread support and backwards-compatibility.                                                            |
+| `generated`         | Enforces a tsconfig as if it were generated by jsii. Use this to stay compatible with the generated config, but have full ownership over the file.                                        |
+| `minimal` :warning: | Only reject options that are known to be incompatible with jsii. This rule set is likely to be incomplete and new rules will be added without notice as incompatibilities are discovered. |
+| `off` :warning:     | Disables all config validation, including options that are known to be incompatible with jsii. Intended for experimentation only. Use at your own risk.                                   |
+
+:star: Recommended setting\
+:warning: Resulting jsii assembly/package may be incompatible with wider ecosystem
+
+There is currently no easy way to inspect these rule sets, however detailed error messages are returned if a provided tsconfig fails validation.
diff --git a/gh-pages/requirements-dev.txt b/gh-pages/requirements-dev.txt
@@ -1,4 +1,4 @@
 mkdocs~=1.6.0
 mkdocs-awesome-pages-plugin~=2.9.2
-mkdocs-material~=9.5.20
+mkdocs-material~=9.5.25
 mkdocs-git-revision-date-plugin~=0.3.2
diff --git a/jest.config.mjs b/jest.config.mjs
@@ -64,7 +64,7 @@ export function overriddenConfig(overrides) {
       ]);
 
       // TypeScript appears to choke if we do the "as any" in the same
-      // expression as the key access, so we delcare surrogate varibales...
+      // expression as the key access, so we declare surrogate variables...
       for (const key of Array.from(allKeys).sort()) {
         const originalValue = original[key];
         const overrideValue = override[key];

diff --git a/lerna.json b/lerna.json
@@ -12,6 +12,6 @@
       "rejectCycles": true
     }
   },
-  "version": "1.98.0",
+  "version": "1.99.0",
   "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }