Feature: Logging (#37)

Martynas Žilinskas · web-flow · commit abd21be39103 · 2018-02-01T22:55:22.000+02:00
diff --git a/common/config/rush/npm-shrinkwrap.json b/common/config/rush/npm-shrinkwrap.json
diff --git a/packages/ts-docs-gen/README.md b/packages/ts-docs-gen/README.md
@@ -39,13 +39,15 @@ ts-docs-gen --config ./docs-gen.json
 ## Configuration
 JSON config properties and CLI flags.
 
-| Property            | CLI Flag              | Required   | Type     | Default     | Description                                                                           |
-| ------------------- | --------------------- | ---------- | -------- | ----------- | ------------------------------------------------------------------------------------- |
-|                     | `--config`            | _optional_ | string   |             | Relative path to config json file.                                                    |
-| `entryFile`         | `--entryFile`         | _required_ | string[] |             | TypeScript project entry files.                                                       |
-| `project`           | `--project`, `-p`     | _optional_ | string   | cwd         | Full path to TypeScript project directory.                                            |
-| `output`            | `--output`, `-o`      | _optional_ | string   | ./docs/api/ | Documentation output directory.                                                       |
-| `plugin`            | `--plugin`            | _optional_ | string[] |             | Package name or path to plugin.                                                       |
-| `exclude`           | `--exclude`           | _optional_ | string[] |             | File locations that should not be included generated documentation.                   |
-| `externalPackage`   | `--externalPackage`   | _optional_ | string[] |             | External package names to include in extracted data.                                  |
-| `excludePrivateApi` | `--excludePrivateApi` | _optional_ | boolean  | `true`      | Excludes api items that has access modifier set to "private" or JSDoc tag "@private". |
+| Property            | CLI Flag              | Required   | Type                                                                    | Default       | Description                                                                                |
+| ------------------- | --------------------- | ---------- | ----------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------ |
+|                     | `--config`            | _optional_ | string                                                                  |               | Relative path to config json file.                                                         |
+| `entryFile`         | `--entryFile`         | _required_ | string[]                                                                |               | TypeScript project entry files.                                                            |
+| `project`           | `--project`, `-p`     | _optional_ | string                                                                  | cwd           | Full path to TypeScript project directory.                                                 |
+| `output`            | `--output`, `-o`      | _optional_ | string                                                                  | ./docs/api/   | Documentation output directory.                                                            |
+| `plugin`            | `--plugin`            | _optional_ | string[]                                                                |               | Package name or path to plugin.                                                            |
+| `exclude`           | `--exclude`           | _optional_ | string[]                                                                |               | File locations that should not be included generated documentation.                        |
+| `externalPackage`   | `--externalPackage`   | _optional_ | string[]                                                                |               | External package names to include in extracted data.                                       |
+| `excludePrivateApi` | `--excludePrivateApi` | _optional_ | boolean                                                                 | `true`        | Excludes api items that has access modifier set to "private" or JSDoc tag "@private".      |
+| `verbosity`         | `--verbosity`         | _optional_ | "None", "Critical", "Error", "Warning", "Information", "Debug", "Trace" | "Information" | Verbosity of output.                                                                       |
+| `dryRun`            | `--dryRun`            | _optional_ | boolean                                                                 |               | Generates markdown files but not writes them. Outputs generated data in `Debug` log level. |
diff --git a/packages/ts-docs-gen/package.json b/packages/ts-docs-gen/package.json
@@ -29,8 +29,8 @@
         "@types/yargs": "^10.0.1",
         "fs-extra": "^5.0.0",
         "simplr-logger": "^1.0.1",
-        "ts-extractor": "^4.0.0-rc.2",
-        "typescript": "^2.6.2",
+        "ts-extractor": "^4.0.0-rc.4",
+        "typescript": "^2.7.1",
         "yargs": "^11.0.0"
     },
     "devDependencies": {
diff --git a/packages/ts-docs-gen/src/api-items/api-callable.ts b/packages/ts-docs-gen/src/api-items/api-callable.ts
@@ -11,7 +11,7 @@ import { ReferenceRenderHandler } from "../contracts/serialized-api-item";
  * Base class for callable api items.
  */
 export abstract class ApiCallable<TKind extends Contracts.ApiCallableBaseDefinition> extends ApiDefinitionBase<TKind> {
-    private parameters: ApiParameter[];
+    private parameters: ApiParameter[] | undefined;
 
     public get Parameters(): ApiParameter[] {
         if (this.parameters == null) {
@@ -23,7 +23,7 @@ export abstract class ApiCallable<TKind extends Contracts.ApiCallableBaseDefinit
         return this.parameters;
     }
 
-    private typeParameters: ApiTypeParameter[];
+    private typeParameters: ApiTypeParameter[] | undefined;
 
     public get TypeParameters(): ApiTypeParameter[] {
         if (this.typeParameters == null) {
diff --git a/packages/ts-docs-gen/src/api-items/api-definition-container.ts b/packages/ts-docs-gen/src/api-items/api-definition-container.ts
@@ -11,7 +11,7 @@ export type ApiBaseItemContainerDto = Contracts.ApiBaseDefinition & { Members: C
 export abstract class ApiDefinitionContainer<TKind extends ApiBaseItemContainerDto = ApiBaseItemContainerDto>
     extends ApiDefinitionBase<TKind> {
 
-    private members: ApiDefinitions[];
+    private members: ApiDefinitions[] | undefined;
 
     public get Members(): ApiDefinitions[] {
         if (this.members == null) {
diff --git a/packages/ts-docs-gen/src/api-items/api-definition-with-type.ts b/packages/ts-docs-gen/src/api-items/api-definition-with-type.ts
@@ -8,7 +8,7 @@ export type ApiBaseItemWithTypeDto = Contracts.ApiBaseDefinition & { Type: Contr
 export abstract class ApiDefinitionWithType<TKind extends ApiBaseItemWithTypeDto = ApiBaseItemWithTypeDto>
     extends ApiDefinitionBase<TKind> {
 
-    private type: ApiTypes;
+    private type: ApiTypes | undefined;
 
     public get Type(): ApiTypes {
         if (this.type == null) {
diff --git a/packages/ts-docs-gen/src/api-items/api-type-members-base.ts b/packages/ts-docs-gen/src/api-items/api-type-members-base.ts
@@ -4,7 +4,7 @@ import { GeneratorHelpers } from "../generator-helpers";
 import { ApiTypes } from "./api-type-list";
 
 export abstract class ApiTypeMembersBase<TKind extends Contracts.ApiMembersBaseType> extends ApiTypeBase<TKind> {
-    private members: ApiTypes[];
+    private members: ApiTypes[] | undefined;
 
     public get Members(): ApiTypes[] {
         if (this.members == null) {
diff --git a/packages/ts-docs-gen/src/api-items/definitions/api-class.ts b/packages/ts-docs-gen/src/api-items/definitions/api-class.ts
@@ -6,7 +6,7 @@ import { ApiTypeParameter } from "./api-type-parameter";
 import { ReferenceRenderHandler } from "../../contracts/serialized-api-item";
 
 export class ApiClass extends ApiDefinitionContainer<Contracts.ApiClassDto> {
-    private typeParameters: ApiTypeParameter[];
+    private typeParameters: ApiTypeParameter[] | undefined;
 
     public get TypeParameters(): ApiTypeParameter[] {
         if (this.typeParameters == null) {
@@ -23,7 +23,7 @@ export class ApiClass extends ApiDefinitionContainer<Contracts.ApiClassDto> {
         return this.extends;
     }
 
-    private implements: ApiTypes[];
+    private implements: ApiTypes[] | undefined;
 
     public get Implements(): ApiTypes[] {
         if (this.implements == null) {
diff --git a/packages/ts-docs-gen/src/api-items/definitions/api-enum.ts b/packages/ts-docs-gen/src/api-items/definitions/api-enum.ts
@@ -7,7 +7,7 @@ import { ApiItemReference } from "../../contracts/api-item-reference";
 import { ReferenceRenderHandler } from "../../contracts/serialized-api-item";
 
 export class ApiEnum extends ApiDefinitionBase<Contracts.ApiEnumDto> {
-    private enumMembers: ApiEnumMember[];
+    private enumMembers: ApiEnumMember[] | undefined;
 
     public get EnumMembers(): ApiEnumMember[] {
         if (this.enumMembers == null) {
diff --git a/packages/ts-docs-gen/src/api-items/definitions/api-index.ts b/packages/ts-docs-gen/src/api-items/definitions/api-index.ts
@@ -5,7 +5,7 @@ import { ApiDefinitionWithType } from "../api-definition-with-type";
 import { ReferenceRenderHandler } from "../../contracts/serialized-api-item";
 
 export class ApiIndex extends ApiDefinitionWithType<Contracts.ApiIndexDto> {
-    private parameter: ApiParameter;
+    private parameter: ApiParameter | undefined;
 
     public get Parameter(): ApiParameter {
         if (this.parameter == null) {
diff --git a/packages/ts-docs-gen/src/api-items/definitions/api-interface.ts b/packages/ts-docs-gen/src/api-items/definitions/api-interface.ts
@@ -6,7 +6,7 @@ import { ApiTypeParameter } from "./api-type-parameter";
 import { ReferenceRenderHandler } from "../../contracts/serialized-api-item";
 
 export class ApiInterface extends ApiDefinitionContainer<Contracts.ApiInterfaceDto> {
-    private typeParameters: ApiTypeParameter[];
+    private typeParameters: ApiTypeParameter[] | undefined;
 
     public get TypeParameters(): ApiTypeParameter[] {
         if (this.typeParameters == null) {
@@ -17,7 +17,7 @@ export class ApiInterface extends ApiDefinitionContainer<Contracts.ApiInterfaceD
         return this.typeParameters;
     }
 
-    private extends: ApiTypes[];
+    private extends: ApiTypes[] | undefined;
 
     public get Extends(): ApiTypes[] {
         if (this.extends == null) {
diff --git a/packages/ts-docs-gen/src/api-items/definitions/api-type-alias.ts b/packages/ts-docs-gen/src/api-items/definitions/api-type-alias.ts
@@ -6,7 +6,7 @@ import { GeneratorHelpers } from "../../generator-helpers";
 import { ReferenceRenderHandler } from "../../contracts/serialized-api-item";
 
 export class ApiTypeAlias extends ApiDefinitionWithType<Contracts.ApiTypeAliasDto> {
-    private typeParameters: ApiTypeParameter[];
+    private typeParameters: ApiTypeParameter[] | undefined;
 
     public get TypeParameters(): ApiTypeParameter[] {
         if (this.typeParameters == null) {
diff --git a/packages/ts-docs-gen/src/api-items/types/api-type-array.ts b/packages/ts-docs-gen/src/api-items/types/api-type-array.ts
@@ -8,7 +8,7 @@ import { ReferenceRenderHandler } from "../../contracts/serialized-api-item";
  * Example: `Foo[]`
  */
 export class ApiTypeArray extends ApiTypeBase<Contracts.ArrayTypeDto> {
-    private type: ApiTypes;
+    private type: ApiTypes | undefined;
 
     public get Type(): ApiTypes {
         if (this.type == null) {
diff --git a/packages/ts-docs-gen/src/api-items/types/api-type-indexed-access.ts b/packages/ts-docs-gen/src/api-items/types/api-type-indexed-access.ts
@@ -7,7 +7,7 @@ import { SerializedApiType, ReferenceRenderHandler } from "../../contracts/seria
  * Example: `Foo[T]`
  */
 export class ApiIndexedAccess extends ApiTypeBase<Contracts.IndexedAccessTypeDto> {
-    private objectType: SerializedApiType;
+    private objectType: SerializedApiType | undefined;
 
     public get ObjectType(): SerializedApiType {
         if (this.objectType == null) {
@@ -16,7 +16,7 @@ export class ApiIndexedAccess extends ApiTypeBase<Contracts.IndexedAccessTypeDto
         return this.objectType;
     }
 
-    private indexType: SerializedApiType;
+    private indexType: SerializedApiType | undefined;
 
     public get IndexType(): SerializedApiType {
         if (this.indexType == null) {
diff --git a/packages/ts-docs-gen/src/api-items/types/api-type-operator.ts b/packages/ts-docs-gen/src/api-items/types/api-type-operator.ts
@@ -8,7 +8,7 @@ import { ReferenceRenderHandler } from "../../contracts/serialized-api-item";
  * Example: `keyof Foo`
  */
 export class ApiTypeOperator extends ApiTypeBase<Contracts.TypeOperatorTypeDto> {
-    private type: ApiTypes;
+    private type: ApiTypes | undefined;
 
     public get Type(): ApiTypes {
         if (this.type == null) {
diff --git a/packages/ts-docs-gen/src/api-items/types/api-type-parenthesized.ts b/packages/ts-docs-gen/src/api-items/types/api-type-parenthesized.ts
@@ -8,7 +8,7 @@ import { ReferenceRenderHandler } from "../../contracts/serialized-api-item";
  * Example: `(string | number)`
  */
 export class ApiTypeParenthesized extends ApiTypeBase<Contracts.ParenthesizedTypeDto> {
-    private type: ApiTypes;
+    private type: ApiTypes | undefined;
 
     public get Type(): ApiTypes {
         if (this.type == null) {
diff --git a/packages/ts-docs-gen/src/api-items/types/api-type-predicate.ts b/packages/ts-docs-gen/src/api-items/types/api-type-predicate.ts
@@ -8,7 +8,7 @@ import { ReferenceRenderHandler } from "../../contracts/serialized-api-item";
  * Example: `arg is string`
  */
 export class ApiTypePredicate extends ApiTypeBase<Contracts.TypePredicateTypeDto> {
-    private type: ApiTypes;
+    private type: ApiTypes | undefined;
 
     public get Type(): ApiTypes {
         if (this.type == null) {
diff --git a/packages/ts-docs-gen/src/builders/generator-configuration-builder.ts b/packages/ts-docs-gen/src/builders/generator-configuration-builder.ts
@@ -9,6 +9,7 @@ import { Plugin } from "../contracts/plugin";
 import { PluginRegistry } from "../registries/plugin-registry";
 import { DefaultPlugins } from "../default-plugins";
 import { GeneratorHelpers } from "../generator-helpers";
+import { LoggerHelpers } from "../utils/logger";
 
 export class GeneratorConfigurationBuilder {
     constructor(private projectDirectory: string) {
@@ -18,7 +19,7 @@ export class GeneratorConfigurationBuilder {
     private configuration: Partial<WorkingGeneratorConfiguration> = {
         excludePrivateApi: true
     };
-    private compilerOptions: Partial<ts.CompilerOptions>;
+    private compilerOptions: Partial<ts.CompilerOptions> | undefined;
     private tsConfigLocation: string | undefined;
 
     private resolveProjectDirectory(): string {
@@ -95,6 +96,10 @@ export class GeneratorConfigurationBuilder {
     }
 
     public async Build(entryFiles: string[]): Promise<GeneratorConfiguration> {
+        // Verbosity level.
+        if (this.configuration.verbosity != null) {
+            LoggerHelpers.SetLogLevel(this.configuration.verbosity);
+        }
 
         // Register all plugins.
         const pluginManager = new PluginRegistry();
@@ -124,7 +129,8 @@ export class GeneratorConfigurationBuilder {
             Exclude: this.configuration.exclude,
             OutputPathSeparator: this.configuration.outputPathSeparator,
             ExternalPackages: this.configuration.externalPackage,
-            FilterApiItems: this.extractorFilterApiItem
+            FilterApiItems: this.extractorFilterApiItem,
+            Verbosity: this.configuration.verbosity
         });
 
         // Output directory
diff --git a/packages/ts-docs-gen/src/cli/arguments.ts b/packages/ts-docs-gen/src/cli/arguments.ts
@@ -1,4 +1,6 @@
 import * as yargs from "yargs";
+import { LogLevel } from "simplr-logger";
+import { LoggerHelpers } from "../utils/logger";
 
 export interface CliFlags {
     project: string;
@@ -8,6 +10,8 @@ export interface CliFlags {
     exclude?: string[];
     externalPackage?: string[];
     excludePrivateApi?: boolean;
+    verbosity?: string;
+    dryRun?: boolean;
 }
 
 export type CliArguments = CliFlags & yargs.Arguments;
@@ -59,4 +63,14 @@ export const ArgsHandler = yargs
         describe: "Package name or path to plugin.",
         type: "array"
     })
+    .option(flagName("verbosity"), {
+        describe: "Verbosity of output.",
+        type: "string",
+        choices: LoggerHelpers.GetLogLevelKeys(),
+        default: LogLevel[LogLevel.Information]
+    })
+    .option(flagName("dryRun"), {
+        describe: "Generates markdown files but not writes them.",
+        type: "boolean"
+    })
     .argv as CliArguments;
diff --git a/packages/ts-docs-gen/src/cli/launcher.ts b/packages/ts-docs-gen/src/cli/launcher.ts
diff --git a/packages/ts-docs-gen/src/contracts/generator-configuration.ts b/packages/ts-docs-gen/src/contracts/generator-configuration.ts
diff --git a/packages/ts-docs-gen/src/generator.ts b/packages/ts-docs-gen/src/generator.ts
diff --git a/packages/ts-docs-gen/src/utils/logger.ts b/packages/ts-docs-gen/src/utils/logger.ts
diff --git a/packages/ts-docs-gen/tests/cases/__tests__/__snapshots__/simple-project-1.test.ts.snap b/packages/ts-docs-gen/tests/cases/__tests__/__snapshots__/simple-project-1.test.ts.snap
diff --git a/packages/ts-docs-gen/tests/cases/__tests__/__snapshots__/simple-project-2.test.ts.snap b/packages/ts-docs-gen/tests/cases/__tests__/__snapshots__/simple-project-2.test.ts.snap
diff --git a/packages/ts-docs-gen/tests/cases/simple-project-2/src/boo.ts b/packages/ts-docs-gen/tests/cases/simple-project-2/src/boo.ts
