feat: support class covariant overrides in kernel, tools and docs (#4925)

Updates docs and additional tools with support for class covariant
overrides.

---

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

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

@@ -18,7 +18,7 @@ coexist in the same closure, it is recommended to also declare all such dependen
 
 Occasionally, a dependency on a *non-jsii module* is useful. Since such dependencies do not have generated bindings in
 all the supported languages, they must be bundled with the *jsii module* that depends on them, by adding the library
-into the `bundleDependencies` array in `package.json`. 
+into the `bundleDependencies` array in `package.json`.
 
 The API of the *jsii module* can not expose any type from bundled dependencies, since those types would not be available in other languages.
 TypeScript files that include a non-jsii dependency (e.g. a lambda handler for an AWS CDK Construct) cannot be exported from the `main`/`types` entry point.
@@ -137,40 +137,53 @@ export class Subclass extends Base {
 ### Covariant Overrides & Parameter List Changes
 
 In **TypeScript**, overriding members can have a signature that differs from the overridden member as long as the new
-signature is compatible with the parent. This is however not supported as:
+signature is compatible with the parent. This is only partially supported in jsii as:
 
-- **Java** and **C#** do not support omitting parameters when overriding or implementing a member
-- **C#** does not support overriding or implementing a member using covariant parameter or return types
+- In **C#** when implementing interfaces, you cannot override members or change return types
+- **C#** only supports covariant overrides to `readonly` properties
+- Both **Java** and **C#** do not support omitting parameters when overriding or implementing a method
+- In **C#** you cannot override method parameters
 
-!!! note
-    **C# 9** introduces support for covariant return types, which would allow relaxing this restriction, however `jsii`
-    must build code targetting the `.NET Core 3.1` runtime, which only supports **C# 8**. Once `.NET Core 3.1` becomes
-    end-of-life, this may change.
+As a consequence, changes to member signatures are only allowed in very few cases.
+All overrides must be covariant to the parent type.
+
+- Return type of (non-static) methods
+- `readonly` properties
+
+```ts hl_lines="10-11 13-14 16-17 19-20 22-23"
+export class SuperClass {}
+export class SubClass extends SuperClass {}
 
-```ts hl_lines="6-7 9-10 12-13"
 export class Base {
-  public method(param: any): any { /* ... */ }
+  public readonly prop: SuperClass;
+  public method(param: SuperClass): SuperClass { /* ... */ }
 }
 
 export class Child extends Base {
   // 💥 Parameter signatures do not match
   public method(): any { /* ... */ }
 
   // 💥 Parameter types do not match, even though they are covariant
-  public method(param: string): any { /* ... */ }
+  public method(param: SubClass): any { /* ... */ }
+
+  // 💥 Property types do not match
+  public readonly prop: string;
+
+  // ✅ Return type is covariant
+  public method(param: SuperClass): SubClass { /* ... */ }
 
-  // 💥 Return type does not match, even though it is covariant
-  public method(param: any): string { /* ... */ }
+  // ✅ Property is readonly and override type is covariant
+  public readonly prop: SubClass;
 }
 ```
 
 ## Index Signatures
 
-**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.
+**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.
 
 !!! info
-    Version `1.x` of the compiler _silently ignores_ index signatures instead of reporting a compilation error. Users
+    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).
 

packages/@jsii/kernel/src/kernel.ts

@@ -14,6 +14,7 @@ import * as tar from './tar-cache';
 
 export const ASSEMBLY_SUPPORTED_FEATURES: spec.JsiiFeature[] = [
   'intersection-types',
+  'class-covariant-overrides',
 ];
 
 export const enum JsiiErrorType {

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

@@ -30,9 +30,9 @@
     "test:update": "yarn build && UPDATE_DIFF=1 yarn test"
   },
   "devDependencies": {
-    "jsii": "5.9.6",
+    "jsii": "5.9.10" ,
     "jsii-build-tools": "^0.0.0",
-    "jsii-rosetta": "^5.9.6"
+    "jsii-rosetta": "^5.9.10" 
   },
   "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.9.6",
+  "jsiiVersion": "5.9.10",
   "license": "Apache-2.0",
   "metadata": {
     "jsii": {
@@ -169,5 +169,5 @@
     }
   },
   "version": "2.1.1",
-  "fingerprint": "xT3ki285s4Oa3XH7pWYl1ZcUwKM/TNBnRDafyUmYtHI="
+  "fingerprint": "AbBUV89p1JNPINTe/piccMNNl5747p+idp5yBUhPLDs="
 }

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

@@ -35,9 +35,9 @@
     "@scope/jsii-calc-base-of-base": "^2.1.1"
   },
   "devDependencies": {
-    "jsii": "5.9.6",
+    "jsii": "5.9.10" ,
     "jsii-build-tools": "^0.0.0",
-    "jsii-rosetta": "^5.9.6"
+    "jsii-rosetta": "^5.9.10" 
   },
   "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.9.6",
+  "jsiiVersion": "5.9.10",
   "license": "Apache-2.0",
   "metadata": {
     "jsii": {
@@ -210,5 +210,5 @@
     }
   },
   "version": "0.0.0",
-  "fingerprint": "uC/anzvNeUVZQRLakfLl74E6VUDzG7IrE8IlleLhl0E="
+  "fingerprint": "HHXEe85+CLPcZkhBH2jorRzc70ystyidBOchIn4e5ZY="
 }

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

@@ -39,9 +39,9 @@
     "@scope/jsii-calc-base-of-base": "^2.1.1"
   },
   "devDependencies": {
-    "jsii": "5.9.6",
+    "jsii": "5.9.10" ,
     "jsii-build-tools": "^0.0.0",
-    "jsii-rosetta": "^5.9.6"
+    "jsii-rosetta": "^5.9.10" 
   },
   "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.9.6",
+  "jsiiVersion": "5.9.10",
   "license": "Apache-2.0",
   "metadata": {
     "jsii": {
@@ -1164,5 +1164,5 @@
     }
   },
   "version": "0.0.0",
-  "fingerprint": "8chnxF4yP6o6nmn+pwW/moRmLso8MgyFcPoNyGJhA+Y="
+  "fingerprint": "YiI6GOYJnt4wjMhkzNuI09K72cTolvyrLVauNPkW6nI="
 }

packages/jsii-calc/lib/covariant-overrides/class-overrides.ts

@@ -0,0 +1,51 @@
+/**
+ * This module demonstrates covariant overrides support in jsii.
+ *
+ * Covariant overrides allow derived classes to override methods with more specific return types.
+ * This was previously not supported because C# didn't allow it, but newer versions of C# (9.0+) do.
+ */
+
+/** Base class in the inheritance hierarchy */
+export class Superclass {}
+
+/** Derived class that extends Superclass */
+export class Subclass extends Superclass {}
+
+/** Further derived class that extends Subclass */
+export class SubSubclass extends Subclass {}
+
+export interface IBase {
+  readonly something: Superclass;
+}
+
+/** Base class with methods and properties that will be overridden with covariant return types */
+export class Base implements IBase {
+  public readonly something: Superclass = new Superclass();
+  public readonly list: Superclass[] = new Array<Superclass>();
+
+  public createSomething(): Superclass {
+    return new Superclass();
+  }
+}
+
+/** Middle class in the inheritance chain - doesn't override anything */
+export class Middle extends Base {
+  public addUnrelatedMember = 3;
+}
+
+/**
+ * Derived class that demonstrates covariant overrides.
+ *
+ * Both property and method overrides are covariant and will work in C# 9.0+
+ * when the covariant-overrides feature is enabled.
+ */
+export class Derived extends Middle {
+  // This property override is covariant (SubSubclass extends Superclass)
+  public readonly something: SubSubclass = new SubSubclass();
+  public readonly list: Superclass[] = new Array<SubSubclass>();
+
+  // This method override is covariant and will work in C# 9.0+
+  public createSomething(): SubSubclass {
+    return new SubSubclass();
+  }
+}

packages/jsii-calc/lib/covariant-overrides/index.ts

@@ -0,0 +1 @@
+export * as classOverrides from './class-overrides';