[api-extractor] Allow generating API reports for different release levels

apps/api-extractor/src/api/Extractor.ts

@@ -29,6 +29,7 @@ import { MessageRouter } from '../collector/MessageRouter';
 import { ConsoleMessageId } from './ConsoleMessageId';
 import { TSDocConfigFile } from '@microsoft/tsdoc-config';
 import { SourceMapper } from '../collector/SourceMapper';
+import { ApiReportVariant } from './IConfigFile';
 
 /**
  * Runtime options for Extractor.
@@ -285,100 +286,23 @@ export class Extractor {
  });
  }
 
- let apiReportChanged: boolean = false;
-
- if (extractorConfig.apiReportEnabled) {
- const actualApiReportPath: string = extractorConfig.reportTempFilePath;
- const actualApiReportShortPath: string = extractorConfig._getShortFilePath(
- extractorConfig.reportTempFilePath
- );
-
- const expectedApiReportPath: string = extractorConfig.reportFilePath;
- const expectedApiReportShortPath: string = extractorConfig._getShortFilePath(
- extractorConfig.reportFilePath
+ function writeApiReport(reportFileName: string, reportVariant: ApiReportVariant): boolean {
+ return Extractor._writeApiReport(
+ collector,
+ extractorConfig,
+ messageRouter,
+ extractorConfig.reportDirectoryPath,
+ extractorConfig.reportTempDirectoryPath,
+ reportFileName,
+ reportVariant,
+ localBuild
  );
+ }
 
- const actualApiReportContent: string = ApiReportGenerator.generateReviewFileContent(collector);
-
- // Write the actual file
- FileSystem.writeFile(actualApiReportPath, actualApiReportContent, {
- ensureFolderExists: true,
- convertLineEndings: extractorConfig.newlineKind
- });
-
- // Compare it against the expected file
- if (FileSystem.exists(expectedApiReportPath)) {
- const expectedApiReportContent: string = FileSystem.readFile(expectedApiReportPath);
-
- if (
- !ApiReportGenerator.areEquivalentApiFileContents(actualApiReportContent, expectedApiReportContent)
- ) {
- apiReportChanged = true;
-
- if (!localBuild) {
- // For a production build, issue a warning that will break the CI build.
- messageRouter.logWarning(
- ConsoleMessageId.ApiReportNotCopied,
- 'You have changed the public API signature for this project.' +
- ` Please copy the file "${actualApiReportShortPath}" to "${expectedApiReportShortPath}",` +
- ` or perform a local build (which does this automatically).` +
- ` See the Git repo documentation for more info.`
- );
- } else {
- // For a local build, just copy the file automatically.
- messageRouter.logWarning(
- ConsoleMessageId.ApiReportCopied,
- 'You have changed the public API signature for this project.' +
- ` Updating ${expectedApiReportShortPath}`
- );
-
- FileSystem.writeFile(expectedApiReportPath, actualApiReportContent, {
- ensureFolderExists: true,
- convertLineEndings: extractorConfig.newlineKind
- });
- }
- } else {
- messageRouter.logVerbose(
- ConsoleMessageId.ApiReportUnchanged,
- `The API report is up to date: ${actualApiReportShortPath}`
- );
- }
- } else {
- // The target file does not exist, so we are setting up the API review file for the first time.
- //
- // NOTE: People sometimes make a mistake where they move a project and forget to update the "reportFolder"
- // setting, which causes a new file to silently get written to the wrong place. This can be confusing.
- // Thus we treat the initial creation of the file specially.
- apiReportChanged = true;
-
- if (!localBuild) {
- // For a production build, issue a warning that will break the CI build.
- messageRouter.logWarning(
- ConsoleMessageId.ApiReportNotCopied,
- 'The API report file is missing.' +
- ` Please copy the file "${actualApiReportShortPath}" to "${expectedApiReportShortPath}",` +
- ` or perform a local build (which does this automatically).` +
- ` See the Git repo documentation for more info.`
- );
- } else {
- const expectedApiReportFolder: string = path.dirname(expectedApiReportPath);
- if (!FileSystem.exists(expectedApiReportFolder)) {
- messageRouter.logError(
- ConsoleMessageId.ApiReportFolderMissing,
- 'Unable to create the API report file. Please make sure the target folder exists:\n' +
- expectedApiReportFolder
- );
- } else {
- FileSystem.writeFile(expectedApiReportPath, actualApiReportContent, {
- convertLineEndings: extractorConfig.newlineKind
- });
- messageRouter.logWarning(
- ConsoleMessageId.ApiReportCreated,
- 'The API report file was missing, so a new file was created. Please add this file to Git:\n' +
- expectedApiReportPath
- );
- }
- }
+ let anyReportChanged: boolean = false;
+ if (extractorConfig.apiReportEnabled) {
+ for (const reportConfig of extractorConfig.reportConfigs) {
+ anyReportChanged = writeApiReport(reportConfig.fileName, reportConfig.variant) || anyReportChanged;
  }
  }
 
@@ -434,12 +358,133 @@ export class Extractor {
  compilerState,
  extractorConfig,
  succeeded,
- apiReportChanged,
+ apiReportChanged: anyReportChanged,
  errorCount: messageRouter.errorCount,
  warningCount: messageRouter.warningCount
  });
  }
 
+ /**
+ * Generates the API report at the specified release level, writes it to the specified file path, and compares
+ * the output to the existing report (if one exists).
+ *
+ * @param reportTempDirectoryPath - The path to the directory under which the temp report file will be written prior
+ * to comparison with an existing report.
+ * @param reportDirectoryPath - The path to the directory under which the existing report file is located, and to
+ * which the new report will be written post-comparison.
+ * @param reportVariant - Determines which API members will be included in the report, based on their tagged release levels.
+ *
+ * @returns Whether or not the newly generated report differs from the existing report (if one exists).
+ */
+ private static _writeApiReport(
+ collector: Collector,
+ extractorConfig: ExtractorConfig,
+ messageRouter: MessageRouter,
+ reportTempDirectoryPath: string,
+ reportDirectoryPath: string,
+ reportFileName: string,
+ reportVariant: ApiReportVariant,
+ localBuild: boolean
+ ): boolean {
+ let apiReportChanged: boolean = false;
+
+ const actualApiReportPath: string = path.resolve(reportTempDirectoryPath, reportFileName);
+ const actualApiReportShortPath: string = extractorConfig._getShortFilePath(actualApiReportPath);
+
+ const expectedApiReportPath: string = path.resolve(reportDirectoryPath, reportFileName);
+ const expectedApiReportShortPath: string = extractorConfig._getShortFilePath(expectedApiReportPath);
+
+ collector.messageRouter.logVerbose(
+ ConsoleMessageId.WritingDtsRollup,
+ `Generating ${reportVariant} API report : ${expectedApiReportPath}`
+ );
+
+ const actualApiReportContent: string = ApiReportGenerator.generateReviewFileContent(collector, {
+ reportVariant: reportVariant
+ });
+
+ // Write the actual file
+ FileSystem.writeFile(actualApiReportPath, actualApiReportContent, {
+ ensureFolderExists: true,
+ convertLineEndings: extractorConfig.newlineKind
+ });
+
+ // Compare it against the expected file
+ if (FileSystem.exists(expectedApiReportPath)) {
+ const expectedApiReportContent: string = FileSystem.readFile(expectedApiReportPath);
+
+ if (
+ !ApiReportGenerator.areEquivalentApiFileContents(actualApiReportContent, expectedApiReportContent)
+ ) {
+ apiReportChanged = true;
+
+ if (!localBuild) {
+ // For a production build, issue a warning that will break the CI build.
+ messageRouter.logWarning(
+ ConsoleMessageId.ApiReportNotCopied,
+ 'You have changed the API signature for this project.' +
+ ` Please copy the file "${actualApiReportShortPath}" to "${expectedApiReportShortPath}",` +
+ ` or perform a local build (which does this automatically).` +
+ ` See the Git repo documentation for more info.`
+ );
+ } else {
+ // For a local build, just copy the file automatically.
+ messageRouter.logWarning(
+ ConsoleMessageId.ApiReportCopied,
+ `You have changed the API signature for this project. Updating ${expectedApiReportShortPath}`
+ );
+
+ FileSystem.writeFile(expectedApiReportPath, actualApiReportContent, {
+ ensureFolderExists: true,
+ convertLineEndings: extractorConfig.newlineKind
+ });
+ }
+ } else {
+ messageRouter.logVerbose(
+ ConsoleMessageId.ApiReportUnchanged,
+ `The API report is up to date: ${actualApiReportShortPath}`
+ );
+ }
+ } else {
+ // The target file does not exist, so we are setting up the API review file for the first time.
+ //
+ // NOTE: People sometimes make a mistake where they move a project and forget to update the "reportFolder"
+ // setting, which causes a new file to silently get written to the wrong place. This can be confusing.
+ // Thus we treat the initial creation of the file specially.
+ apiReportChanged = true;
+
+ if (!localBuild) {
+ // For a production build, issue a warning that will break the CI build.
+ messageRouter.logWarning(
+ ConsoleMessageId.ApiReportNotCopied,
+ 'The API report file is missing.' +
+ ` Please copy the file "${actualApiReportShortPath}" to "${expectedApiReportShortPath}",` +
+ ` or perform a local build (which does this automatically).` +
+ ` See the Git repo documentation for more info.`
+ );
+ } else {
+ const expectedApiReportFolder: string = path.dirname(expectedApiReportPath);
+ if (!FileSystem.exists(expectedApiReportFolder)) {
+ messageRouter.logError(
+ ConsoleMessageId.ApiReportFolderMissing,
+ 'Unable to create the API report file. Please make sure the target folder exists:\n' +
+ expectedApiReportFolder
+ );
+ } else {
+ FileSystem.writeFile(expectedApiReportPath, actualApiReportContent, {
+ convertLineEndings: extractorConfig.newlineKind
+ });
+ messageRouter.logWarning(
+ ConsoleMessageId.ApiReportCreated,
+ 'The API report file was missing, so a new file was created. Please add this file to Git:\n' +
+ expectedApiReportPath
+ );
+ }
+ }
+ }
+ return apiReportChanged;
+ }
+
  private static _checkCompilerCompatibility(
  extractorConfig: ExtractorConfig,
  messageRouter: MessageRouter