Merge pull request #2237 from iclanton/ianc/strict-rigs

Enable strict compiler checks in heft rigs.

apps/api-documenter/src/cli/BaseAction.ts

@@ -3,7 +3,7 @@
 
 import * as path from 'path';
 import * as tsdoc from '@microsoft/tsdoc';
-import * as colors from 'colors';
+import colors from 'colors';
 
 import { CommandLineAction, CommandLineStringParameter } from '@rushstack/ts-command-line';
 import { FileSystem } from '@rushstack/node-core-library';
@@ -15,12 +15,15 @@ import {
   IResolveDeclarationReferenceResult
 } from '@microsoft/api-extractor-model';
 
-export abstract class BaseAction extends CommandLineAction {
-  protected inputFolder: string;
-  protected outputFolder: string;
+export interface IBuildApiModelResult {
+  apiModel: ApiModel;
+  inputFolder: string;
+  outputFolder: string;
+}
 
-  private _inputFolderParameter: CommandLineStringParameter;
-  private _outputFolderParameter: CommandLineStringParameter;
+export abstract class BaseAction extends CommandLineAction {
+  private _inputFolderParameter!: CommandLineStringParameter;
+  private _outputFolderParameter!: CommandLineStringParameter;
 
   protected onDefineParameters(): void {
     // override
@@ -44,28 +47,28 @@ export abstract class BaseAction extends CommandLineAction {
     });
   }
 
-  protected buildApiModel(): ApiModel {
+  protected buildApiModel(): IBuildApiModelResult {
     const apiModel: ApiModel = new ApiModel();
 
-    this.inputFolder = this._inputFolderParameter.value || './input';
-    if (!FileSystem.exists(this.inputFolder)) {
-      throw new Error('The input folder does not exist: ' + this.inputFolder);
+    const inputFolder: string = this._inputFolderParameter.value || './input';
+    if (!FileSystem.exists(inputFolder)) {
+      throw new Error('The input folder does not exist: ' + inputFolder);
     }
 
-    this.outputFolder = this._outputFolderParameter.value || `./${this.actionName}`;
-    FileSystem.ensureFolder(this.outputFolder);
+    const outputFolder: string = this._outputFolderParameter.value || `./${this.actionName}`;
+    FileSystem.ensureFolder(outputFolder);
 
-    for (const filename of FileSystem.readFolder(this.inputFolder)) {
+    for (const filename of FileSystem.readFolder(inputFolder)) {
       if (filename.match(/\.api\.json$/i)) {
         console.log(`Reading ${filename}`);
-        const filenamePath: string = path.join(this.inputFolder, filename);
+        const filenamePath: string = path.join(inputFolder, filename);
         apiModel.loadPackage(filenamePath);
       }
     }
 
     this._applyInheritDoc(apiModel, apiModel);
 
-    return apiModel;
+    return { apiModel, inputFolder, outputFolder };
   }
 
   // TODO: This is a temporary workaround.  The long term plan is for API Extractor's DocCommentEnhancer

apps/api-documenter/src/cli/GenerateAction.ts

@@ -8,7 +8,6 @@ import { BaseAction } from './BaseAction';
 import { DocumenterConfig } from '../documenters/DocumenterConfig';
 import { ExperimentalYamlDocumenter } from '../documenters/ExperimentalYamlDocumenter';
 
-import { ApiModel } from '@microsoft/api-extractor-model';
 import { FileSystem } from '@rushstack/node-core-library';
 import { MarkdownDocumenter } from '../documenters/MarkdownDocumenter';
 
@@ -42,17 +41,21 @@ export class GenerateAction extends BaseAction {
 
     const documenterConfig: DocumenterConfig = DocumenterConfig.loadFile(configFilePath);
 
-    const apiModel: ApiModel = this.buildApiModel();
+    const { apiModel, outputFolder } = this.buildApiModel();
 
     if (documenterConfig.configFile.outputTarget === 'markdown') {
-      const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter(apiModel, documenterConfig);
-      markdownDocumenter.generateFiles(this.outputFolder);
+      const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter({
+        apiModel,
+        documenterConfig,
+        outputFolder
+      });
+      markdownDocumenter.generateFiles();
     } else {
       const yamlDocumenter: ExperimentalYamlDocumenter = new ExperimentalYamlDocumenter(
         apiModel,
         documenterConfig
       );
-      yamlDocumenter.generateFiles(this.outputFolder);
+      yamlDocumenter.generateFiles(outputFolder);
     }
 
     return Promise.resolve();

apps/api-documenter/src/cli/MarkdownAction.ts

@@ -4,7 +4,6 @@
 import { ApiDocumenterCommandLine } from './ApiDocumenterCommandLine';
 import { BaseAction } from './BaseAction';
 import { MarkdownDocumenter } from '../documenters/MarkdownDocumenter';
-import { ApiModel } from '@microsoft/api-extractor-model';
 
 export class MarkdownAction extends BaseAction {
   public constructor(parser: ApiDocumenterCommandLine) {
@@ -19,10 +18,14 @@ export class MarkdownAction extends BaseAction {
 
   protected onExecute(): Promise<void> {
     // override
-    const apiModel: ApiModel = this.buildApiModel();
+    const { apiModel, outputFolder } = this.buildApiModel();
 
-    const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter(apiModel, undefined);
-    markdownDocumenter.generateFiles(this.outputFolder);
+    const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter({
+      apiModel,
+      documenterConfig: undefined,
+      outputFolder
+    });
+    markdownDocumenter.generateFiles();
     return Promise.resolve();
   }
 }

apps/api-documenter/src/cli/YamlAction.ts

@@ -8,11 +8,10 @@ import { BaseAction } from './BaseAction';
 
 import { YamlDocumenter } from '../documenters/YamlDocumenter';
 import { OfficeYamlDocumenter } from '../documenters/OfficeYamlDocumenter';
-import { ApiModel } from '@microsoft/api-extractor-model';
 
 export class YamlAction extends BaseAction {
-  private _officeParameter: CommandLineFlagParameter;
-  private _newDocfxNamespacesParameter: CommandLineFlagParameter;
+  private _officeParameter!: CommandLineFlagParameter;
+  private _newDocfxNamespacesParameter!: CommandLineFlagParameter;
 
   public constructor(parser: ApiDocumenterCommandLine) {
     super({
@@ -45,13 +44,13 @@ export class YamlAction extends BaseAction {
 
   protected onExecute(): Promise<void> {
     // override
-    const apiModel: ApiModel = this.buildApiModel();
+    const { apiModel, inputFolder, outputFolder } = this.buildApiModel();
 
     const yamlDocumenter: YamlDocumenter = this._officeParameter.value
-      ? new OfficeYamlDocumenter(apiModel, this.inputFolder, this._newDocfxNamespacesParameter.value)
+      ? new OfficeYamlDocumenter(apiModel, inputFolder, this._newDocfxNamespacesParameter.value)
       : new YamlDocumenter(apiModel, this._newDocfxNamespacesParameter.value);
 
-    yamlDocumenter.generateFiles(this.outputFolder);
+    yamlDocumenter.generateFiles(outputFolder);
     return Promise.resolve();
   }
 }

apps/api-documenter/src/documenters/ExperimentalYamlDocumenter.ts

@@ -16,7 +16,7 @@ import { DocumenterConfig } from './DocumenterConfig';
 export class ExperimentalYamlDocumenter extends YamlDocumenter {
   private _config: IConfigTableOfContents;
   private _tocPointerMap: { [key: string]: IYamlTocItem };
-  private _catchAllPointer: IYamlTocItem;
+  private _catchAllPointer: IYamlTocItem | undefined;
 
   public constructor(apiModel: ApiModel, documenterConfig: DocumenterConfig) {
     super(apiModel, documenterConfig.configFile.newDocfxNamespaces);

apps/api-documenter/src/documenters/MarkdownDocumenter.ts

@@ -57,6 +57,12 @@ import {
 import { DocumenterConfig } from './DocumenterConfig';
 import { MarkdownDocumenterAccessor } from '../plugin/MarkdownDocumenterAccessor';
 
+export interface IMarkdownDocumenterOptions {
+  apiModel: ApiModel;
+  documenterConfig: DocumenterConfig | undefined;
+  outputFolder: string;
+}
+
 /**
  * Renders API documentation in the Markdown file format.
  * For more info:  https://en.wikipedia.org/wiki/Markdown
@@ -66,26 +72,25 @@ export class MarkdownDocumenter {
   private readonly _documenterConfig: DocumenterConfig | undefined;
   private readonly _tsdocConfiguration: TSDocConfiguration;
   private readonly _markdownEmitter: CustomMarkdownEmitter;
-  private _outputFolder: string;
+  private readonly _outputFolder: string;
   private readonly _pluginLoader: PluginLoader;
 
-  public constructor(apiModel: ApiModel, documenterConfig: DocumenterConfig | undefined) {
-    this._apiModel = apiModel;
-    this._documenterConfig = documenterConfig;
+  public constructor(options: IMarkdownDocumenterOptions) {
+    this._apiModel = options.apiModel;
+    this._documenterConfig = options.documenterConfig;
+    this._outputFolder = options.outputFolder;
     this._tsdocConfiguration = CustomDocNodes.configuration;
     this._markdownEmitter = new CustomMarkdownEmitter(this._apiModel);
 
     this._pluginLoader = new PluginLoader();
   }
 
-  public generateFiles(outputFolder: string): void {
-    this._outputFolder = outputFolder;
-
+  public generateFiles(): void {
     if (this._documenterConfig) {
       this._pluginLoader.load(this._documenterConfig, () => {
         return new MarkdownDocumenterFeatureContext({
           apiModel: this._apiModel,
-          outputFolder: outputFolder,
+          outputFolder: this._outputFolder,
           documenter: new MarkdownDocumenterAccessor({
             getLinkForApiItem: (apiItem: ApiItem) => {
               return this._getLinkFilenameForApiItem(apiItem);

apps/api-documenter/src/documenters/OfficeYamlDocumenter.ts

@@ -1,7 +1,7 @@
 // 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 colors from 'colors';
 import * as path from 'path';
 import yaml = require('js-yaml');
 

apps/api-documenter/src/documenters/YamlDocumenter.ts

@@ -89,7 +89,6 @@ export class YamlDocumenter {
 
   private _apiItemsByCanonicalReference: Map<string, ApiItem>;
   private _yamlReferences: IYamlReferences | undefined;
-  private _outputFolder: string;
 
   public constructor(apiModel: ApiModel, newDocfxNamespaces: boolean = false) {
     this._apiModel = apiModel;
@@ -102,17 +101,15 @@ export class YamlDocumenter {
 
   /** @virtual */
   public generateFiles(outputFolder: string): void {
-    this._outputFolder = outputFolder;
-
     console.log();
-    this._deleteOldOutputFiles();
+    this._deleteOldOutputFiles(outputFolder);
 
     for (const apiPackage of this._apiModel.packages) {
       console.log(`Writing ${apiPackage.name} package`);
-      this._visitApiItems(apiPackage, undefined);
+      this._visitApiItems(outputFolder, apiPackage, undefined);
     }
 
-    this._writeTocFile(this._apiModel.packages);
+    this._writeTocFile(outputFolder, this._apiModel.packages);
   }
 
   /** @virtual */
@@ -130,7 +127,11 @@ export class YamlDocumenter {
     // (overridden by child class)
   }
 
-  private _visitApiItems(apiItem: ApiDocumentedItem, parentYamlFile: IYamlApiFile | undefined): boolean {
+  private _visitApiItems(
+    outputFolder: string,
+    apiItem: ApiDocumentedItem,
+    parentYamlFile: IYamlApiFile | undefined
+  ): boolean {
     let savedYamlReferences: IYamlReferences | undefined;
     if (!this._shouldEmbed(apiItem.kind)) {
       savedYamlReferences = this._yamlReferences;
@@ -158,7 +159,7 @@ export class YamlDocumenter {
       const children: ApiItem[] = this._getLogicalChildren(apiItem);
       for (const child of children) {
         if (child instanceof ApiDocumentedItem) {
-          if (this._visitApiItems(child, newYamlFile)) {
+          if (this._visitApiItems(outputFolder, child, newYamlFile)) {
             if (!yamlItem.children) {
               yamlItem.children = [];
             }
@@ -173,7 +174,7 @@ export class YamlDocumenter {
 
       this._yamlReferences = savedYamlReferences;
 
-      const yamlFilePath: string = this._getYamlFilePath(apiItem);
+      const yamlFilePath: string = this._getYamlFilePath(outputFolder, apiItem);
 
       if (apiItem.kind === ApiItemKind.Package) {
         console.log('Writing ' + yamlFilePath);
@@ -270,10 +271,10 @@ export class YamlDocumenter {
   /**
    * Write the table of contents
    */
-  private _writeTocFile(apiItems: ReadonlyArray<ApiItem>): void {
+  private _writeTocFile(outputFolder: string, apiItems: ReadonlyArray<ApiItem>): void {
     const tocFile: IYamlTocFile = this.buildYamlTocFile(apiItems);
 
-    const tocFilePath: string = path.join(this._outputFolder, 'toc.yml');
+    const tocFilePath: string = path.join(outputFolder, 'toc.yml');
     console.log('Writing ' + tocFilePath);
     this._writeYamlFile(tocFile, tocFilePath, '', undefined);
   }
@@ -994,7 +995,7 @@ export class YamlDocumenter {
     }
   }
 
-  private _getYamlFilePath(apiItem: ApiItem): string {
+  private _getYamlFilePath(outputFolder: string, apiItem: ApiItem): string {
     let result: string = '';
 
     for (const current of apiItem.getHierarchy()) {
@@ -1021,11 +1022,11 @@ export class YamlDocumenter {
       disambiguator = `-${apiItem.kind.toLowerCase()}`;
     }
 
-    return path.join(this._outputFolder, result + disambiguator + '.yml');
+    return path.join(outputFolder, result + disambiguator + '.yml');
   }
 
-  private _deleteOldOutputFiles(): void {
-    console.log('Deleting old output from ' + this._outputFolder);
-    FileSystem.ensureEmptyFolder(this._outputFolder);
+  private _deleteOldOutputFiles(outputFolder: string): void {
+    console.log('Deleting old output from ' + outputFolder);
+    FileSystem.ensureEmptyFolder(outputFolder);
   }
 }

apps/api-documenter/src/markdown/CustomMarkdownEmitter.ts

@@ -1,7 +1,7 @@
 // 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 colors from 'colors';
 
 import { DocNode, DocLinkTag, StringBuilder } from '@microsoft/tsdoc';
 import { ApiModel, IResolveDeclarationReferenceResult, ApiItem } from '@microsoft/api-extractor-model';

apps/api-documenter/src/plugin/MarkdownDocumenterFeature.ts

@@ -74,7 +74,7 @@ const uuidMarkdownDocumenterFeature: string = '34196154-9eb3-4de0-a8c8-7e9539dfe
  */
 export class MarkdownDocumenterFeature extends PluginFeature {
   /** {@inheritdoc PluginFeature.context} */
-  public context: MarkdownDocumenterFeatureContext;
+  public context!: MarkdownDocumenterFeatureContext;
 
   /**
    * This event occurs before each markdown file is written.  It provides an opportunity to customize the

apps/api-documenter/src/plugin/PluginFeature.ts

@@ -13,7 +13,7 @@ import { TypeUuid } from '@rushstack/node-core-library';
  */
 export class PluginFeatureInitialization {
   /** @internal */
-  public _context: PluginFeatureContext;
+  public _context!: PluginFeatureContext;
 
   /** @internal */
   public constructor() {

apps/api-documenter/src/plugin/PluginLoader.ts

@@ -30,23 +30,23 @@ export class PluginLoader {
         });
 
         // Load the package
-        const entryPoint: object | undefined = require(resolvedEntryPointPath);
+        const entryPoint:
+          | { apiDocumenterPluginManifest?: IApiDocumenterPluginManifest }
+          | undefined = require(resolvedEntryPointPath);
 
         if (!entryPoint) {
           throw new Error('Invalid entry point');
         }
 
-        const manifest: IApiDocumenterPluginManifest =
-          // eslint-disable-next-line dot-notation
-          entryPoint['apiDocumenterPluginManifest'] as IApiDocumenterPluginManifest;
-
-        if (!manifest) {
+        if (!entryPoint.apiDocumenterPluginManifest) {
           throw new Error(
             `The package is not an API documenter plugin;` +
               ` the "apiDocumenterPluginManifest" export was not found`
           );
         }
 
+        const manifest: IApiDocumenterPluginManifest = entryPoint.apiDocumenterPluginManifest;
+
         if (manifest.manifestVersion !== 1000) {
           throw new Error(
             `The plugin is not compatible with this version of API Documenter;` +

apps/api-documenter/src/start.ts

@@ -2,7 +2,7 @@
 // See LICENSE in the project root for license information.
 
 import * as os from 'os';
-import * as colors from 'colors';
+import colors from 'colors';
 
 import { PackageJsonLookup } from '@rushstack/node-core-library';
 

apps/api-extractor-model/package.json

@@ -18,7 +18,7 @@
     "@rushstack/node-core-library": "workspace:*"
   },
   "devDependencies": {
-    "@microsoft/rush-stack-compiler-3.5": "0.8.10",
+    "@microsoft/rush-stack-compiler-3.9": "0.4.21",
     "@rushstack/eslint-config": "workspace:*",
     "@rushstack/heft": "0.8.0",
     "@types/heft-jest": "1.0.1",