Add an "api-extractor init" command that writes out api-extractor-template.json

octogonz · octogonz · commit fe225d2233c8 · 2019-04-02T20:52:48.000-07:00
diff --git a/apps/api-extractor/src/cli/ApiExtractorCommandLine.ts b/apps/api-extractor/src/cli/ApiExtractorCommandLine.ts
@@ -8,14 +8,19 @@ import { CommandLineParser, CommandLineFlagParameter } from '@microsoft/ts-comma
 import { InternalError } from '@microsoft/node-core-library';
 
 import { RunAction } from './RunAction';
+import { InitAction } from './InitAction';
 
 export class ApiExtractorCommandLine extends CommandLineParser {
   private _debugParameter: CommandLineFlagParameter;
 
   constructor() {
     super({
       toolFilename: 'api-extractor',
-      toolDescription: 'This is an experimental command line interface for the API Extractor tool.'
+      toolDescription: 'API Extractor helps you build better TypeScript libraries.  It analyzes the main entry'
+        + ' point for your package, collects the inventory of exported declarations, and then generates three kinds'
+        + ' of output:  an API report file (.api.md) to facilitate reviews, a declaration rollup (.d.ts) to be'
+        + ' published with your NPM package, and a doc model file (.api.json) to be used with a documentation'
+        + ' tool such as api-documenter.  For details, please visit the web site.'
     });
     this._populateActions();
   }
@@ -46,6 +51,7 @@ export class ApiExtractorCommandLine extends CommandLineParser {
   }
 
   private _populateActions(): void {
+    this.addAction(new InitAction(this));
     this.addAction(new RunAction(this));
   }
 }
diff --git a/apps/api-extractor/src/cli/InitAction.ts b/apps/api-extractor/src/cli/InitAction.ts
@@ -0,0 +1,50 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import * as colors from 'colors';
+import * as path from 'path';
+import { FileSystem } from '@microsoft/node-core-library';
+import { CommandLineAction } from '@microsoft/ts-command-line';
+
+import { ApiExtractorCommandLine } from './ApiExtractorCommandLine';
+
+const AE_CONFIG_FILENAME: string = 'api-extractor.json';
+
+export class InitAction extends CommandLineAction {
+
+  constructor(parser: ApiExtractorCommandLine) {
+    super({
+      actionName: 'init',
+      summary: `Create an ${AE_CONFIG_FILENAME} config file`,
+      documentation: `Use this command when setting up API Extractor for a new project.  It writes an`
+        + ` ${AE_CONFIG_FILENAME} config file template with code comments that describe all the settings.`
+        + ` The file will be written in the current directory.`
+    });
+  }
+
+  protected onDefineParameters(): void { // override
+    // No parameters yet
+  }
+
+  protected onExecute(): Promise<void> { // override
+    const inputFilePath: string = path.resolve(__dirname, '../schemas/api-extractor-template.json');
+    const outputFilePath: string = path.resolve(AE_CONFIG_FILENAME);
+
+    if (FileSystem.exists(outputFilePath)) {
+      console.log(colors.red('The output file already exists:'));
+      console.log('\n  ' + outputFilePath + '\n');
+      throw new Error('Unable to write output file');
+    }
+
+    console.log(colors.green('Writing file: ') + outputFilePath);
+    FileSystem.copyFile({
+      sourcePath: inputFilePath,
+      destinationPath: outputFilePath
+    });
+
+    console.log('\nThe recommended location for this file is in the project\'s "config" subfolder,\n'
+      + 'or else in the top-level folder with package.json.');
+
+    return Promise.resolve();
+  }
+}
diff --git a/apps/api-extractor/src/schemas/api-extractor-template.json b/apps/api-extractor/src/schemas/api-extractor-template.json
@@ -122,7 +122,7 @@
      *
      * DEFAULT VALUE: "./temp/<packageBaseName>.api.json"
      */
-    "apiJsonFilePath": "./temp/<packageBaseName>.api.json"
+    // "apiJsonFilePath": "./temp/<packageBaseName>.api.json"
   },
 
   /**
@@ -146,7 +146,7 @@
      *
      * DEFAULT VALUE: "./dist/<packageBaseName>.d.ts"
      */
-    "untrimmedFilePath": "./dist/<packageBaseName>.d.ts",
+    // "untrimmedFilePath": "./dist/<packageBaseName>.d.ts",
 
     /**
      * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.

Original file line number	Diff line number	Diff line change
`@@ -8,14 +8,19 @@ import { CommandLineParser, CommandLineFlagParameter } from '@microsoft/ts-comma`
`8`	`8`	`import { InternalError } from '@microsoft/node-core-library';`
`9`	`9`
`10`	`10`	`import { RunAction } from './RunAction';`
	`11`	`+import { InitAction } from './InitAction';`
`11`	`12`
`12`	`13`	`export class ApiExtractorCommandLine extends CommandLineParser {`
`13`	`14`	`private _debugParameter: CommandLineFlagParameter;`
`14`	`15`
`15`	`16`	`constructor() {`
`16`	`17`	`super({`
`17`	`18`	`toolFilename: 'api-extractor',`
`18`		`- toolDescription: 'This is an experimental command line interface for the API Extractor tool.'`
	`19`	`+ toolDescription: 'API Extractor helps you build better TypeScript libraries. It analyzes the main entry'`
	`20`	`+ + ' point for your package, collects the inventory of exported declarations, and then generates three kinds'`
	`21`	`+ + ' of output: an API report file (.api.md) to facilitate reviews, a declaration rollup (.d.ts) to be'`
	`22`	`+ + ' published with your NPM package, and a doc model file (.api.json) to be used with a documentation'`
	`23`	`+ + ' tool such as api-documenter. For details, please visit the web site.'`
`19`	`24`	`});`
`20`	`25`	`this._populateActions();`
`21`	`26`	`}`
`@@ -46,6 +51,7 @@ export class ApiExtractorCommandLine extends CommandLineParser {`
`46`	`51`	`}`
`47`	`52`
`48`	`53`	`private _populateActions(): void {`
	`54`	`+ this.addAction(new InitAction(this));`
`49`	`55`	`this.addAction(new RunAction(this));`
`50`	`56`	`}`
`51`	`57`	`}`