feat(jsii): introduce submodules feature

docs/specifications/2-type-system.md

@@ -308,6 +308,86 @@ document.
 }
 ```
 
+## Submodules
+
+> :construction: The *submodules* feature is still under active development and
+> the specific behavior around it (in particular with respects to code
+> generation) are still subject to change.
+
+### Overview
+
+Typescript allows grouping declarations together in *namespaces*, which are
+interpreted by *jsii* as *submodules*. *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* may use different [code-generation configuration](#code-generation)
+than their parent submodule or package.
+
+> :construction: *Submodule*-level code-generation configuration is not yet
+> implemented.
+
+### Restrictions
+
+*Submodules* cannot be involved in dependency cycles. While it is possible to
+build such cycles in **JavaScript**, that configuration cannot be reliably
+reprensented in certain other programming languages (e.g: **Python**).
+
+> :construction: [`jsii`] does not currently check for circular submodule
+> dependencies. Invalid dependency patterns may result in errors at code
+> generation by [`jsii-pacmak`], or at runtime.
+
+Since this would result in ambiguity that cannot be consistently resolved, a
+given type can only be exported as part of one *submodule*.
+
+[`jsii`]: ../../packages/jsii
+[`jsii-pacmak`]: ../../packages/jsii-pacmak
+
+### Declaration
+
+There are two supported ways to introduce *submodules*:
+* Using the namespaced export syntax:
+  ```ts
+  export * as ns from './module';
+  ```
+* Using an explicit namespace declaration:
+  ```ts
+  export namespace ns { /* ... */ }
+  ```
+
+*Submodules* declared using the `export * as ns from './module';` syntax can be
+documented using a markdown document located at `./module/README.md`.
+
+> :construction: The `./module/README.md` file support is not yet implemented.
+
+### Code Generation
+
+In languages where this is relevant (e.g: **Python**), *submodules* are rendered
+as native *submodules*. In languages where a namespace system exists (**Java**
+uses *packages*, **C#** uses *namespaces*, ...), *submodules* are rendered using
+that.
+
+## Code Generation
+
+In order to generate code in various programming languages, [`jsii-pacmak`]
+needs configuration that provides naming directives (e.g: **Java** package
+names, **C#** namespaces, **Python** module names, ...). This configuration is
+language-specific and each language implementation specifies and documents its
+own configuration schema.
+
+Configuration is sourced in the `package.json` file at the root of the npm
+package, under the special `jsii` key. The general schema is described in the
+[configuration] document.
+
+> :construction: There is a proposition to allow this configuration to be placed
+> in a `.jsiirc.json` file, which would take precedence over what is specified
+> in `package.json`. *Submodules* introduced using the
+> `export * as ns from './module';` syntax would then be able to define
+> *submodule*-local configuration using the `./module/.jsiirc.json` file.
+
+[configuration]: ../configuration.md
+
 ## References
 
 The [**TypeScript** Handbook] describes the language's type system and syntax

packages/@jsii/dotnet-runtime-test/test/Amazon.JSII.Runtime.IntegrationTests/ComplianceTests.cs

@@ -3,7 +3,7 @@
 using System.Linq;
 using Amazon.JSII.Runtime.Deputy;
 using Amazon.JSII.Tests.CalculatorNamespace;
-using CompositeOperation = Amazon.JSII.Tests.CalculatorNamespace.composition.CompositeOperation;
+using CompositeOperation = Amazon.JSII.Tests.CalculatorNamespace.Composition.CompositeOperation;
 using Amazon.JSII.Tests.CalculatorNamespace.LibNamespace;
 using Newtonsoft.Json.Linq;
 using Xunit;
@@ -1413,11 +1413,11 @@ public void AbstractMembersAreCorrectlyHandled()
             var abstractSuite = new AbstractSuiteImpl();
             Assert.Equal("Wrapped<String<Oomf!>>", abstractSuite.WorkItAll("Oomf!"));
         }
-        
+
         private sealed class AbstractSuiteImpl : AbstractSuite
         {
             private string _property = "";
-            
+
             public AbstractSuiteImpl() {}
 
             protected override string SomeMethod(string str)
@@ -1440,7 +1440,7 @@ public void CollectionOfInterfaces_ListOfStructs()
                 Assert.IsAssignableFrom<IStructA>(elt);
             }
         }
-        
+
         [Fact(DisplayName = Prefix + nameof(CollectionOfInterfaces_ListOfInterfaces))]
         public void CollectionOfInterfaces_ListOfInterfaces()
         {
@@ -1449,7 +1449,7 @@ public void CollectionOfInterfaces_ListOfInterfaces()
                 Assert.IsAssignableFrom<IBell>(elt);
             }
         }
-        
+
         [Fact(DisplayName = Prefix + nameof(CollectionOfInterfaces_MapOfStructs))]
         public void CollectionOfInterfaces_MapOfStructs()
         {
@@ -1458,7 +1458,7 @@ public void CollectionOfInterfaces_MapOfStructs()
                 Assert.IsAssignableFrom<IStructA>(elt);
             }
         }
-        
+
         [Fact(DisplayName = Prefix + nameof(CollectionOfInterfaces_MapOfInterfaces))]
         public void CollectionOfInterfaces_MapOfInterfaces()
         {

packages/jsii-calc/lib/index.ts

@@ -3,3 +3,5 @@ export * from './compliance';
 export * from './documented';
 export * from './erasures';
 export * from './stability';
+
+export * as submodule from './submodule';

packages/jsii-calc/lib/submodule/child/index.ts

@@ -0,0 +1,12 @@
+export interface Structure {
+  readonly bool: boolean;
+}
+
+export enum Goodness {
+  /** It's pretty good */
+  PRETTY_GOOD,
+  /** It's really good */
+  REALLY_GOOD,
+  /** It's amazingly good */
+  AMAZINGLY_GOOD
+}

packages/jsii-calc/lib/submodule/index.ts

@@ -0,0 +1,4 @@
+export * as child from './child';
+export * from './my-class';
+export * from './nested_submodule';
+export * as back_references from './refers-to-parent';

packages/jsii-calc/lib/submodule/my-class.ts

@@ -0,0 +1,11 @@
+import { nested_submodule } from './nested_submodule';
+import { Goodness } from './child';
+import { AllTypes } from '..';
+
+export class MyClass implements nested_submodule.deeplyNested.INamespaced {
+  public readonly definedAt = __filename;
+  public readonly goodness = Goodness.AMAZINGLY_GOOD;
+  public allTypes?: AllTypes;
+
+  public constructor() { }
+}

packages/jsii-calc/lib/submodule/nested_submodule.ts

@@ -0,0 +1,16 @@
+import { Goodness } from './child';
+
+export namespace nested_submodule {
+  export namespace deeplyNested {
+    export interface INamespaced {
+      readonly definedAt: string;
+    }
+  }
+
+  export abstract class Namespaced implements deeplyNested.INamespaced {
+    public readonly definedAt = __filename;
+    public abstract readonly goodness: Goodness;
+
+    private constructor() { }
+  }
+}

packages/jsii-calc/lib/submodule/refers-to-parent/index.ts

@@ -0,0 +1,5 @@
+import { MyClass } from '..';
+
+export interface MyClassReference {
+  readonly reference: MyClass;
+}