fix(jsii-config): update jsii-config and docs with latest settings (#…

…4515)

Updates jsii-config and the website with the latest settings for user-provided TypeScript configs.

The update to jsii-config includes some other changes that have previously been missed, including support for go and fixing a the outdir configuration.

---

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

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,55 @@ 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"
+  }
+}
+```
+
+#### :test_tube:  `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 +330,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

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/

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.

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` :warn: | 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` :warn:     | 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
+:warn: 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.

packages/jsii-config/lib/prompt.ts

@@ -29,7 +29,11 @@ export default async function getAnswers(
   const answers = (await inquirer.prompt(
     getQuestions(current),
   )) as PromptAnswers;
-  const { jsiiTargets: _, ...config } = removeEmptyValues(answers);
+  const {
+    jsiiTargets: _1,
+    tsconfig: _2,
+    ...config
+  } = removeEmptyValues(answers);
   const confirmInput = await inquirer.prompt({
     type: 'confirm',
     message: `Confirm Jsii Config\n${JSON.stringify(

packages/jsii-config/lib/questions.ts

@@ -1,4 +1,4 @@
-import { QuestionCollection } from 'inquirer';
+import { QuestionCollection, Separator } from 'inquirer';
 
 import schema, { ConfigPromptsSchema, BasePackageJson } from './schema';
 import { getNestedValue, flattenKeys } from './util';
@@ -55,8 +55,28 @@ function buildQuestions(
     choices: Object.keys(schema.jsii.targets),
     default: Object.keys(currentTargets),
   };
+  const tsconfigPrompt: QuestionCollection = {
+    name: 'tsconfig',
+    message:
+      'Typescript config - should jsii generate a compatible tsconfig or do you want to manage it yourself',
+    type: 'list',
+    choices: [
+      'jsii-managed',
+      new Separator('tsconfig will be managed and generated for you by jsii'),
+      new Separator(),
+      'user-provided',
+      new Separator(
+        'bring your own user-provided tsconfig for advanced setups',
+      ),
+    ],
+    default: 'jsii-managed',
+  };
 
-  return [targetsPrompt, ...flattenNestedQuestions(schema, current)];
+  return [
+    targetsPrompt,
+    tsconfigPrompt,
+    ...flattenNestedQuestions(schema, current),
+  ];
 }
 
 export default (current: BasePackageJson) => buildQuestions(schema, current);