feat!: Library mode

Gerrit0 · Gerrit0 · commit 362138e01fb4 · 2020-01-18T15:54:25.000-07:00
BREAKING CHANGE: Renames external modules to modules, and modules to namespaces. Closes #109.
diff --git a/scripts/rebuild_specs.js b/scripts/rebuild_specs.js
@@ -42,6 +42,10 @@ const conversions = [
         () => app.options.setValue('categorizeByGroup', false),
         () => app.options.setValue('categorizeByGroup', true)
     ],
+    ['specs.lib',
+        () => app.options.setValue('mode', 'library'),
+        () => app.options.setValue('mode', 'modules'),
+    ]
 ];
 
 /**
diff --git a/src/lib/converter/converter.ts b/src/lib/converter/converter.ts
@@ -7,7 +7,7 @@ import { Reflection, Type, ProjectReflection } from '../models/index';
 import { Context } from './context';
 import { ConverterComponent, ConverterNodeComponent, ConverterTypeComponent, TypeTypeConverter, TypeNodeConverter } from './components';
 import { Component, ChildableComponent, ComponentClass } from '../utils/component';
-import { BindOption } from '../utils';
+import { BindOption, SourceFileMode } from '../utils';
 import { normalizePath } from '../utils/fs';
 import { createMinimatch } from '../utils/paths';
 
@@ -366,9 +366,20 @@ export class Converter extends ChildableComponent<Application, ConverterComponen
             .filter(file => !isExcluded(file));
         const isRelevantError = ({ file }: ts.Diagnostic) => !file || includedSourceFiles.includes(file);
 
-        includedSourceFiles.forEach((sourceFile) => {
-            this.convertNode(context, sourceFile);
-        });
+        if (this.application.options.getValue('mode') === SourceFileMode.Library) {
+            for (const fileName of context.fileNames) {
+                const sourceFile = includedSourceFiles.find(file => fileName === file.fileName);
+                if (sourceFile) {
+                    this.convertNode(context, sourceFile);
+                } else {
+                    this.application.logger.warn(`Failed to find source file of entry point ${fileName}`);
+                }
+            }
+        } else {
+            includedSourceFiles.forEach((sourceFile) => {
+                this.convertNode(context, sourceFile);
+            });
+        }
 
         if (this.application.ignoreCompilerErrors) {
             return [];
diff --git a/src/lib/converter/factories/declaration.ts b/src/lib/converter/factories/declaration.ts
@@ -11,7 +11,7 @@ import { createReferenceType } from './reference';
 const nonStaticKinds = [
     ReflectionKind.Class,
     ReflectionKind.Interface,
-    ReflectionKind.Module
+    ReflectionKind.Namespace
 ];
 
 /**
@@ -71,12 +71,12 @@ export function createDeclaration(context: Context, node: ts.Declaration, kind:
 
     // Test whether the node is exported
     let isExported: boolean;
-    if (kind === ReflectionKind.ExternalModule || kind === ReflectionKind.Global) {
+    if (kind === ReflectionKind.Module || kind === ReflectionKind.Global) {
         isExported = true;
     } else if (container.kind === ReflectionKind.Global) {
         // In file mode, everything is exported.
         isExported = true;
-    } else if (container.kindOf([ReflectionKind.Module, ReflectionKind.ExternalModule])) {
+    } else if (container.kindOf([ReflectionKind.Namespace, ReflectionKind.Module])) {
         const symbol = context.getSymbolAtLocation(node);
         if (!symbol) {
             isExported = false;
@@ -213,7 +213,7 @@ function canMergeReflectionsByKind(kind1: ReflectionKind, kind2: ReflectionKind)
  */
 function mergeDeclarations(context: Context, reflection: DeclarationReflection, node: ts.Node, kind: ReflectionKind) {
     if (reflection.kind !== kind) {
-        const weights = [ReflectionKind.Module, ReflectionKind.Enum, ReflectionKind.Class];
+        const weights = [ReflectionKind.Namespace, ReflectionKind.Enum, ReflectionKind.Class];
         const kindWeight = weights.indexOf(kind);
         const childKindWeight = weights.indexOf(reflection.kind);
         if (kindWeight > childKindWeight) {
diff --git a/src/lib/converter/nodes/block.ts b/src/lib/converter/nodes/block.ts
@@ -55,11 +55,17 @@ export class BlockConverter extends ConverterNodeComponent<ts.SourceFile|ts.Bloc
 
         context.withSourceFile(node, () => {
             if (this.mode === SourceFileMode.Modules) {
-                result = createDeclaration(context, node, ReflectionKind.ExternalModule, node.fileName);
+                result = createDeclaration(context, node, ReflectionKind.Module, node.fileName);
                 context.withScope(result, () => {
                     this.convertStatements(context, node);
                     result!.setFlag(ReflectionFlag.Exported);
                 });
+            } else if (this.mode === SourceFileMode.Library) {
+                result = createDeclaration(context, node, ReflectionKind.Module, node.fileName);
+                context.withScope(result, () => {
+                    this.convertVisibleDeclarations(context, node);
+                    result!.setFlag(ReflectionFlag.Exported);
+                });
             } else {
                 this.convertStatements(context, node);
             }
@@ -85,4 +91,18 @@ export class BlockConverter extends ConverterNodeComponent<ts.SourceFile|ts.Bloc
             });
         }
     }
+
+    private convertVisibleDeclarations(context: Context, node: ts.SourceFile) {
+        const moduleSymbol = context.getSymbolAtLocation(node);
+        if (!moduleSymbol) {
+            this.application.logger.warn(`File ${node.fileName} is not a module and cannot be converted in library mode`);
+            return;
+        }
+
+        for (const symbol of context.checker.getExportsOfModule(moduleSymbol)) {
+            for (const declaration of symbol.declarations) {
+                this.owner.convertNode(context, declaration);
+            }
+        }
+    }
 }
diff --git a/src/lib/converter/nodes/module.ts b/src/lib/converter/nodes/module.ts
@@ -24,7 +24,7 @@ export class ModuleConverter extends ConverterNodeComponent<ts.ModuleDeclaration
     convert(context: Context, node: ts.ModuleDeclaration): Reflection | undefined {
         const reflection = context.isInherit && context.inheritParent === node
             ? <DeclarationReflection> context.scope
-            : createDeclaration(context, node, ReflectionKind.Module);
+            : createDeclaration(context, node, ReflectionKind.Namespace);
         context.withScope(reflection, () => {
             if (node.body) {
                 this.owner.convertNode(context, node.body);
diff --git a/src/lib/converter/plugins/CommentPlugin.ts b/src/lib/converter/plugins/CommentPlugin.ts
@@ -111,7 +111,7 @@ export class CommentPlugin extends ConverterComponent {
             CommentPlugin.removeTags(comment, 'event');
         }
 
-        if (reflection.kindOf(ReflectionKind.ExternalModule)) {
+        if (reflection.kindOf(ReflectionKind.Module)) {
             CommentPlugin.removeTags(comment, 'packagedocumentation');
         }
     }
@@ -172,7 +172,7 @@ export class CommentPlugin extends ConverterComponent {
         if (reflection.kindOf(ReflectionKind.FunctionOrMethod) || (reflection.kindOf(ReflectionKind.Event) && reflection['signatures'])) {
             const comment = parseComment(rawComment, reflection.comment);
             this.applyModifiers(reflection, comment);
-        } else if (reflection.kindOf(ReflectionKind.Module)) {
+        } else if (reflection.kindOf(ReflectionKind.Namespace)) {
             this.storeModuleComment(rawComment, reflection);
         } else {
             const comment = parseComment(rawComment, reflection.comment);
diff --git a/src/lib/converter/plugins/DynamicModulePlugin.ts b/src/lib/converter/plugins/DynamicModulePlugin.ts
@@ -52,7 +52,7 @@ export class DynamicModulePlugin extends ConverterComponent {
      * @param node  The node that is currently processed if available.
      */
     private onDeclaration(context: Context, reflection: Reflection, node?: ts.Node) {
-        if (reflection.kindOf(ReflectionKind.ExternalModule)) {
+        if (reflection.kindOf(ReflectionKind.Module)) {
             let name = reflection.name;
             if (!name.includes('/')) {
                 return;
diff --git a/src/lib/converter/plugins/GroupPlugin.ts b/src/lib/converter/plugins/GroupPlugin.ts
@@ -17,8 +17,8 @@ export class GroupPlugin extends ConverterComponent {
      */
     static WEIGHTS = [
         ReflectionKind.Global,
-        ReflectionKind.ExternalModule,
         ReflectionKind.Module,
+        ReflectionKind.Namespace,
         ReflectionKind.Enum,
         ReflectionKind.EnumMember,
         ReflectionKind.Class,
diff --git a/src/lib/models/reflections/abstract.ts b/src/lib/models/reflections/abstract.ts
@@ -36,8 +36,8 @@ export function resetReflectionID() {
  */
 export enum ReflectionKind {
     Global = 0,
-    ExternalModule = 1 << 0,
-    Module = 1 << 1,
+    Module = 1 << 0,
+    Namespace = 1 << 1,
     Enum = 1 << 2,
     EnumMember = 1 << 4,
     Variable = 1 << 5,
@@ -66,7 +66,7 @@ export enum ReflectionKind {
     FunctionOrMethod = ReflectionKind.Function | Method,
     ClassMember = Accessor | Constructor | Method | Property | Event,
     SomeSignature = CallSignature | IndexSignature | ConstructorSignature | GetSignature | SetSignature,
-    SomeModule = Module | ExternalModule,
+    SomeModule = Namespace | Module,
     SomeType = Interface | TypeLiteral | TypeParameter | TypeAlias,
     SomeValue = Variable | Function | ObjectLiteral
 }
diff --git a/src/lib/output/themes/DefaultTheme.ts b/src/lib/output/themes/DefaultTheme.ts
@@ -61,7 +61,7 @@ export class DefaultTheme extends Theme {
         directory: 'enums',
         template:  'reflection.hbs'
     }, {
-        kind:      [ReflectionKind.Module, ReflectionKind.ExternalModule],
+        kind:      [ReflectionKind.Namespace, ReflectionKind.Module],
         isLeaf:    false,
         directory: 'modules',
         template:  'reflection.hbs'
@@ -375,7 +375,7 @@ export class NavigationBuilder {
             let target = someModule.parent;
             let inScope = (someModule === this.entryPoint);
             while (target) {
-                if (target.kindOf(ReflectionKind.ExternalModule)) {
+                if (target.kindOf(ReflectionKind.Module)) {
                     return;
                 }
                 if (this.entryPoint === target) {
diff --git a/src/lib/utils/options/declaration.ts b/src/lib/utils/options/declaration.ts
@@ -31,7 +31,7 @@ export type TypeDocAndTSOptions = TypeDocOptions
     & Pick<CompilerOptions, Exclude<KnownKeys<CompilerOptions>, IgnoredTsOptionKeys>>;
 
 export enum SourceFileMode {
-    File, Modules
+    File, Modules, Library
 }
 
 /**
@@ -43,7 +43,7 @@ export interface TypeDocOptionMap {
     tsconfig: string;
 
     inputFiles: string[];
-    mode: { file: SourceFileMode.File, modules: SourceFileMode.Modules };
+    mode: { file: SourceFileMode.File, modules: SourceFileMode.Modules, library: SourceFileMode.Library };
     includeDeclarations: boolean;
     entryPoint: string;
     exclude: string[];
diff --git a/src/lib/utils/options/sources/typedoc.ts b/src/lib/utils/options/sources/typedoc.ts
@@ -26,8 +26,9 @@ export function addTypeDocOptions(options: Options) {
         help: "Specifies the output mode the project is used to be compiled with: 'file' or 'modules'",
         type: ParameterType.Map,
         map: {
-            'file': SourceFileMode.File,
-            'modules': SourceFileMode.Modules
+            file: SourceFileMode.File,
+            modules: SourceFileMode.Modules,
+            library: SourceFileMode.Library
         },
         defaultValue: SourceFileMode.Modules
     });
diff --git a/src/test/converter.test.ts b/src/test/converter.test.ts
@@ -35,6 +35,10 @@ describe('Converter', function() {
         ['specs-with-lump-categories',
             () => app.options.setValue('categorizeByGroup', false),
             () => app.options.setValue('categorizeByGroup', true)
+        ],
+        ['specs.lib',
+            () => app.options.setValue('mode', 'library'),
+            () => app.options.setValue('mode', 'modules')
         ]
     ];
 

Original file line number	Diff line number	Diff line change
`@@ -111,7 +111,7 @@ export class CommentPlugin extends ConverterComponent {`
`111`	`111`	`CommentPlugin.removeTags(comment, 'event');`
`112`	`112`	`}`
`113`	`113`
`114`		`- if (reflection.kindOf(ReflectionKind.ExternalModule)) {`
	`114`	`+ if (reflection.kindOf(ReflectionKind.Module)) {`
`115`	`115`	`CommentPlugin.removeTags(comment, 'packagedocumentation');`
`116`	`116`	`}`
`117`	`117`	`}`
`@@ -172,7 +172,7 @@ export class CommentPlugin extends ConverterComponent {`
`172`	`172`	`if (reflection.kindOf(ReflectionKind.FunctionOrMethod) \|\| (reflection.kindOf(ReflectionKind.Event) && reflection['signatures'])) {`
`173`	`173`	`const comment = parseComment(rawComment, reflection.comment);`
`174`	`174`	`this.applyModifiers(reflection, comment);`
`175`		`- } else if (reflection.kindOf(ReflectionKind.Module)) {`
	`175`	`+ } else if (reflection.kindOf(ReflectionKind.Namespace)) {`
`176`	`176`	`this.storeModuleComment(rawComment, reflection);`
`177`	`177`	`} else {`
`178`	`178`	`const comment = parseComment(rawComment, reflection.comment);`