feat: handle nested submodules

src/cli.ts

@@ -1,7 +1,7 @@
 import * as fs from 'fs/promises';
 import * as path from 'node:path';
 import * as yargs from 'yargs';
-import { Language } from './docgen/transpile/transpile';
+import { Language, submoduleRelName } from './docgen/transpile/transpile';
 import { Documentation } from './index';
 
 type GenerateOptions = {
@@ -41,12 +41,12 @@ async function generateForLanguage(docs: Documentation, options: GenerateOptions
     for (const submodule of submodules) {
       const content = await docs.toMarkdown({
         ...options,
-        submodule: submodule.name,
+        submodule: submodule.fqn,
         allSubmodules: false,
-        header: { title: `\`${submodule.name}\` Submodule`, id: submodule.fqn },
+        header: { title: `\`${submoduleRelName(submodule)}\` Submodule`, id: submodule.fqn },
       });
 
-      await fs.writeFile(path.join(outputPath, `${submodule.name}.${submoduleSuffix}`), content.render());
+      await fs.writeFile(path.join(outputPath, `${submoduleRelName(submodule)}.${submoduleSuffix}`), content.render());
     }
 
     await fs.writeFile(`${outputFileName}.${fileSuffix}`, await (await docs.toIndexMarkdown(submoduleSuffix, options)).render());
@@ -102,3 +102,4 @@ main().catch(e => {
   console.error(e);
   process.exit(1);
 });
+

src/docgen/render/markdown-render.ts

@@ -1,7 +1,7 @@
 import * as reflect from 'jsii-reflect';
 import { MarkdownDocument } from './markdown-doc';
 import { ApiReferenceSchema, AssemblyMetadataSchema, ClassSchema, ConstructSchema, EnumMemberSchema, EnumSchema, InitializerSchema, InterfaceSchema, JsiiEntity, MethodSchema, ParameterSchema, PropertySchema, Schema, CURRENT_SCHEMA_VERSION, StructSchema, TypeSchema } from '../schema';
-import { Language } from '../transpile/transpile';
+import { Language, submoduleRelName } from '../transpile/transpile';
 
 export interface MarkdownFormattingOptions {
   /**
@@ -150,7 +150,7 @@ export class MarkdownRenderer {
     const md = new MarkdownDocument({ header: { title: 'Submodules' }, id: 'submodules' });
     md.lines('The following submodules are available:');
     for (const submodule of submodules) {
-      md.lines(`- [${submodule.name}](./${submodule.name}.${fileSuffix})`);
+      md.lines(`- [${submoduleRelName(submodule)}](./${submoduleRelName(submodule)}.${fileSuffix})`);
     }
     return md;
   }

src/docgen/transpile/transpile.ts

@@ -847,7 +847,7 @@ export abstract class TranspileBase implements Transpile {
       // if the type is in a submodule, the submodule name is the first
       // part of the namespace. we construct the full submodule fqn and search for it.
       const submoduleFqn = `${type.assembly.name}.${type.namespace.split('.')[0]}`;
-      const submodules = type.assembly.submodules.filter(
+      const submodules = type.assembly.allSubmodules.filter(
         (s) => s.fqn === submoduleFqn,
       );
 
@@ -894,3 +894,12 @@ export abstract class TranspileBase implements Transpile {
     return 0;
   }
 }
+
+/**
+ * Return the root-relative name for a submodule
+ *
+ * Ex: for a submodule `asm.sub1.sub2`, return `sub1.sub2`.
+ */
+export function submoduleRelName(submodule: reflect.Submodule) {
+  return submodule.fqn.split('.').slice(1).join('.');
+}

src/docgen/view/api-reference.ts

@@ -26,9 +26,9 @@ export class ApiReference {
     let interfaces: reflect.InterfaceType[];
     let enums: reflect.EnumType[];
     if (allSubmodules ?? false) {
-      classes = this.sortByName([...assembly.classes, ...flatMap(assembly.submodules, submod => [...submod.classes])]);
-      interfaces = this.sortByName([...assembly.interfaces, ...flatMap(assembly.submodules, submod => [...submod.interfaces])]);
-      enums = this.sortByName([...assembly.enums, ...flatMap(assembly.submodules, submod => [...submod.enums])]);
+      classes = this.sortByName([...assembly.classes, ...flatMap(assembly.allSubmodules, submod => [...submod.classes])]);
+      interfaces = this.sortByName([...assembly.interfaces, ...flatMap(assembly.allSubmodules, submod => [...submod.interfaces])]);
+      enums = this.sortByName([...assembly.enums, ...flatMap(assembly.allSubmodules, submod => [...submod.enums])]);
     } else {
       classes = this.sortByName(submodule ? submodule.classes : assembly.classes);
       interfaces = this.sortByName(submodule ? submodule.interfaces : assembly.interfaces);

src/docgen/view/documentation.ts

@@ -201,7 +201,7 @@ export class Documentation {
    */
   public async listSubmodules() {
     const tsAssembly = await this.createAssembly(undefined, { loose: true, validate: false });
-    return tsAssembly.submodules;
+    return tsAssembly.allSubmodules;
   }
 
   public async toIndexMarkdown(fileSuffix:string, options: RenderOptions) {
@@ -234,7 +234,9 @@ export class Documentation {
       throw new LanguageNotSupportedError(`Laguage ${language} is not supported for package ${this.assemblyFqn}`);
     }
 
-    if (allSubmodules && options?.submodule) {
+    let submoduleStr = options.submodule;
+
+    if (allSubmodules && submoduleStr) {
       throw new Error('Cannot call toJson with allSubmodules and a specific submodule both selected.');
     }
 
@@ -245,7 +247,7 @@ export class Documentation {
       throw new Error(`Assembly ${this.assemblyFqn} does not have any targets defined`);
     }
 
-    const submodule = options?.submodule ? this.findSubmodule(assembly, options.submodule) : undefined;
+    const submodule = submoduleStr ? this.findSubmodule(assembly, submoduleStr) : undefined;
 
     let readme: MarkdownDocument | undefined;
     if (options?.readme ?? false) {
@@ -313,21 +315,48 @@ export class Documentation {
 
   /**
    * Lookup a submodule by a submodule name.
+   *
+   * The contract of this function is historically quite confused: the submodule
+   * name can be either an FQN (`asm.sub1.sub2`) or just a submodule name
+   * (`sub1` or `sub1.sub2`).
+   *
+   * This is sligthly complicated by ambiguity: `asm.asm.package` and
+   * `asm.package` can both exist, and which one do you mean when you say
+   * `asm.package`?
+   *
+   * We prefer an FQN match if possible (`asm.sub1.sub2`), but will accept a
+   * root-relative submodule name as well (`sub1.sub2`).
    */
   private findSubmodule(assembly: reflect.Assembly, submodule: string): reflect.Submodule {
-    const submodules = assembly.submodules.filter(
-      (s) => s.name === submodule,
+    // If 'submodule' does not have a '.' in it, we know exactly what is intended.
+
+
+
+    const fqnSubs = assembly.allSubmodules.filter(
+      (s) => s.fqn === submodule,
     );
+    if (fqnSubs.length === 1) {
+      return fqnSubs[0];
+    }
 
-    if (submodules.length === 0) {
-      throw new Error(`Submodule ${submodule} not found in assembly ${assembly.name}@${assembly.version}`);
+    // Fallback: assembly-relative name
+    const relSubs = assembly.allSubmodules.filter(
+      (s) => s.fqn === `${assembly.name}.${submodule}`,
+    );
+    if (relSubs.length === 1) {
+      console.error(`[WARNING] findSubmodule() is being called with a relative submodule name: '${submodule}'. Prefer the absolute name: '${assembly.name}.${submodule}'`);
+      return relSubs[0];
     }
 
-    if (submodules.length > 1) {
-      throw new Error(`Found multiple submodules with name: ${submodule} in assembly ${assembly.name}@${assembly.version}`);
+    if (fqnSubs.length + relSubs.length === 0) {
+      throw new Error(`Submodule ${submodule} not found in assembly ${assembly.name}@${assembly.version} (neither as '${submodule}' nor as '${assembly.name}.${submodule})`);
     }
 
-    return submodules[0];
+    // Almost impossible that this would be true
+    if (fqnSubs.length > 1) {
+      throw new Error(`Found multiple submodules with FQN: ${submodule} in assembly ${assembly.name}@${assembly.version}`);
+    }
+    throw new Error(`Found multiple submodules with relative name: ${submodule} in assembly ${assembly.name}@${assembly.version}`);
   }
 
   private async createAssembly(