@microsoft/api-extractor 7.56.3 → 7.57.0

package/lib-esm/cli/ApiExtractorCommandLine.js

@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import * as os from 'node:os';
+import { CommandLineParser } from '@rushstack/ts-command-line';
+import { AlreadyReportedError, InternalError } from '@rushstack/node-core-library';
+import { Colorize } from '@rushstack/terminal';
+import { RunAction } from './RunAction';
+import { InitAction } from './InitAction';
+export class ApiExtractorCommandLine extends CommandLineParser {
+    constructor() {
+        super({
+            toolFilename: 'api-extractor',
+            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();
+        this._debugParameter = this.defineFlagParameter({
+            parameterLongName: '--debug',
+            parameterShortName: '-d',
+            description: 'Show the full call stack if an error occurs while executing the tool'
+        });
+    }
+    async onExecuteAsync() {
+        if (this._debugParameter.value) {
+            InternalError.breakInDebugger = true;
+        }
+        process.exitCode = 1;
+        try {
+            await super.onExecuteAsync();
+            process.exitCode = 0;
+        }
+        catch (error) {
+            if (!(error instanceof AlreadyReportedError)) {
+                if (this._debugParameter.value) {
+                    console.error(os.EOL + error.stack);
+                }
+                else {
+                    console.error(os.EOL + Colorize.red('ERROR: ' + error.message.trim()));
+                }
+            }
+        }
+    }
+    _populateActions() {
+        this.addAction(new InitAction(this));
+        this.addAction(new RunAction(this));
+    }
+}
+//# sourceMappingURL=ApiExtractorCommandLine.js.map

package/lib-esm/cli/ApiExtractorCommandLine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiExtractorCommandLine.js","sourceRoot":"","sources":["../../src/cli/ApiExtractorCommandLine.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9B,OAAO,EAAE,iBAAiB,EAAiC,MAAM,4BAA4B,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AACnF,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,MAAM,OAAO,uBAAwB,SAAQ,iBAAiB;IAG5D;QACE,KAAK,CAAC;YACJ,YAAY,EAAE,eAAe;YAC7B,eAAe,EACb,wFAAwF;gBACxF,0GAA0G;gBAC1G,qGAAqG;gBACrG,oGAAoG;gBACpG,wEAAwE;SAC3E,CAAC,CAAC;QACH,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAExB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,mBAAmB,CAAC;YAC9C,iBAAiB,EAAE,SAAS;YAC5B,kBAAkB,EAAE,IAAI;YACxB,WAAW,EAAE,sEAAsE;SACpF,CAAC,CAAC;IACL,CAAC;IAEkB,KAAK,CAAC,cAAc;QACrC,IAAI,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;YAC/B,aAAa,CAAC,eAAe,GAAG,IAAI,CAAC;QACvC,CAAC;QAED,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,cAAc,EAAE,CAAC;YAC7B,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,CAAC,KAAK,YAAY,oBAAoB,CAAC,EAAE,CAAC;gBAC7C,IAAI,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;oBAC/B,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;gBACtC,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;gBACzE,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAEO,gBAAgB;QACtB,IAAI,CAAC,SAAS,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;QACrC,IAAI,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport * as os from 'node:os';\n\nimport { CommandLineParser, type CommandLineFlagParameter } from '@rushstack/ts-command-line';\nimport { AlreadyReportedError, InternalError } from '@rushstack/node-core-library';\nimport { Colorize } from '@rushstack/terminal';\n\nimport { RunAction } from './RunAction';\nimport { InitAction } from './InitAction';\n\nexport class ApiExtractorCommandLine extends CommandLineParser {\n  private readonly _debugParameter: CommandLineFlagParameter;\n\n  public constructor() {\n    super({\n      toolFilename: 'api-extractor',\n      toolDescription:\n        'API Extractor helps you build better TypeScript libraries.  It analyzes the main entry' +\n        ' point for your package, collects the inventory of exported declarations, and then generates three kinds' +\n        ' of output:  an API report file (.api.md) to facilitate reviews, a declaration rollup (.d.ts) to be' +\n        ' published with your NPM package, and a doc model file (.api.json) to be used with a documentation' +\n        ' tool such as api-documenter.  For details, please visit the web site.'\n    });\n    this._populateActions();\n\n    this._debugParameter = this.defineFlagParameter({\n      parameterLongName: '--debug',\n      parameterShortName: '-d',\n      description: 'Show the full call stack if an error occurs while executing the tool'\n    });\n  }\n\n  protected override async onExecuteAsync(): Promise<void> {\n    if (this._debugParameter.value) {\n      InternalError.breakInDebugger = true;\n    }\n\n    process.exitCode = 1;\n    try {\n      await super.onExecuteAsync();\n      process.exitCode = 0;\n    } catch (error) {\n      if (!(error instanceof AlreadyReportedError)) {\n        if (this._debugParameter.value) {\n          console.error(os.EOL + error.stack);\n        } else {\n          console.error(os.EOL + Colorize.red('ERROR: ' + error.message.trim()));\n        }\n      }\n    }\n  }\n\n  private _populateActions(): void {\n    this.addAction(new InitAction(this));\n    this.addAction(new RunAction(this));\n  }\n}\n"]}

package/lib-esm/cli/InitAction.js

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import * as path from 'node:path';
+import { FileSystem } from '@rushstack/node-core-library';
+import { CommandLineAction } from '@rushstack/ts-command-line';
+import { Colorize } from '@rushstack/terminal';
+import { ExtractorConfig } from '../api/ExtractorConfig';
+export class InitAction extends CommandLineAction {
+    constructor(parser) {
+        super({
+            actionName: 'init',
+            summary: `Create an ${ExtractorConfig.FILENAME} config file`,
+            documentation: `Use this command when setting up API Extractor for a new project.  It writes an` +
+                ` ${ExtractorConfig.FILENAME} config file template with code comments that describe all the settings.` +
+                ` The file will be written in the current directory.`
+        });
+    }
+    async onExecuteAsync() {
+        const inputFilePath = path.resolve(__dirname, '../schemas/api-extractor-template.json');
+        const outputFilePath = path.resolve(ExtractorConfig.FILENAME);
+        if (FileSystem.exists(outputFilePath)) {
+            console.log(Colorize.red('The output file already exists:'));
+            console.log('\n  ' + outputFilePath + '\n');
+            throw new Error('Unable to write output file');
+        }
+        console.log(Colorize.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.');
+    }
+}
+//# sourceMappingURL=InitAction.js.map

package/lib-esm/cli/InitAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InitAction.js","sourceRoot":"","sources":["../../src/cli/InitAction.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,OAAO,UAAW,SAAQ,iBAAiB;IAC/C,YAAmB,MAA+B;QAChD,KAAK,CAAC;YACJ,UAAU,EAAE,MAAM;YAClB,OAAO,EAAE,aAAa,eAAe,CAAC,QAAQ,cAAc;YAC5D,aAAa,EACX,iFAAiF;gBACjF,IAAI,eAAe,CAAC,QAAQ,0EAA0E;gBACtG,qDAAqD;SACxD,CAAC,CAAC;IACL,CAAC;IAEkB,KAAK,CAAC,cAAc;QACrC,MAAM,aAAa,GAAW,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,wCAAwC,CAAC,CAAC;QAChG,MAAM,cAAc,GAAW,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;QAEtE,IAAI,UAAU,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;YACtC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC,CAAC;YAC7D,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QACjD,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,gBAAgB,CAAC,GAAG,cAAc,CAAC,CAAC;QAC/D,UAAU,CAAC,QAAQ,CAAC;YAClB,UAAU,EAAE,aAAa;YACzB,eAAe,EAAE,cAAc;SAChC,CAAC,CAAC;QAEH,OAAO,CAAC,GAAG,CACT,qFAAqF;YACnF,oDAAoD,CACvD,CAAC;IACJ,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport * as path from 'node:path';\n\nimport { FileSystem } from '@rushstack/node-core-library';\nimport { CommandLineAction } from '@rushstack/ts-command-line';\nimport { Colorize } from '@rushstack/terminal';\n\nimport type { ApiExtractorCommandLine } from './ApiExtractorCommandLine';\nimport { ExtractorConfig } from '../api/ExtractorConfig';\n\nexport class InitAction extends CommandLineAction {\n  public constructor(parser: ApiExtractorCommandLine) {\n    super({\n      actionName: 'init',\n      summary: `Create an ${ExtractorConfig.FILENAME} config file`,\n      documentation:\n        `Use this command when setting up API Extractor for a new project.  It writes an` +\n        ` ${ExtractorConfig.FILENAME} config file template with code comments that describe all the settings.` +\n        ` The file will be written in the current directory.`\n    });\n  }\n\n  protected override async onExecuteAsync(): Promise<void> {\n    const inputFilePath: string = path.resolve(__dirname, '../schemas/api-extractor-template.json');\n    const outputFilePath: string = path.resolve(ExtractorConfig.FILENAME);\n\n    if (FileSystem.exists(outputFilePath)) {\n      console.log(Colorize.red('The output file already exists:'));\n      console.log('\\n  ' + outputFilePath + '\\n');\n      throw new Error('Unable to write output file');\n    }\n\n    console.log(Colorize.green('Writing file: ') + outputFilePath);\n    FileSystem.copyFile({\n      sourcePath: inputFilePath,\n      destinationPath: outputFilePath\n    });\n\n    console.log(\n      '\\nThe recommended location for this file is in the project\\'s \"config\" subfolder,\\n' +\n        'or else in the top-level folder with package.json.'\n    );\n  }\n}\n"]}

package/lib-esm/cli/RunAction.js

@@ -0,0 +1,123 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { PackageJsonLookup, FileSystem, Path, AlreadyReportedError } from '@rushstack/node-core-library';
+import { Colorize } from '@rushstack/terminal';
+import { CommandLineAction } from '@rushstack/ts-command-line';
+import { Extractor } from '../api/Extractor';
+import { ExtractorConfig } from '../api/ExtractorConfig';
+export class RunAction extends CommandLineAction {
+    constructor(parser) {
+        super({
+            actionName: 'run',
+            summary: 'Invoke API Extractor on a project',
+            documentation: 'Invoke API Extractor on a project'
+        });
+        this._configFileParameter = this.defineStringParameter({
+            parameterLongName: '--config',
+            parameterShortName: '-c',
+            argumentName: 'FILE',
+            description: `Use the specified ${ExtractorConfig.FILENAME} file path, rather than guessing its location`
+        });
+        this._localFlag = this.defineFlagParameter({
+            parameterLongName: '--local',
+            parameterShortName: '-l',
+            description: 'Indicates that API Extractor is running as part of a local build,' +
+                " e.g. on a developer's machine. This disables certain validation that would" +
+                ' normally be performed for a ship/production build. For example, the *.api.md' +
+                ' report file is automatically copied in a local build.'
+        });
+        this._verboseFlag = this.defineFlagParameter({
+            parameterLongName: '--verbose',
+            parameterShortName: '-v',
+            description: 'Show additional informational messages in the output.'
+        });
+        this._diagnosticsParameter = this.defineFlagParameter({
+            parameterLongName: '--diagnostics',
+            description: 'Show diagnostic messages used for troubleshooting problems with API Extractor.' +
+                '  This flag also enables the "--verbose" flag.'
+        });
+        this._typescriptCompilerFolderParameter = this.defineStringParameter({
+            parameterLongName: '--typescript-compiler-folder',
+            argumentName: 'PATH',
+            description: 'API Extractor uses its own TypeScript compiler engine to analyze your project.  If your project' +
+                ' is built with a significantly different TypeScript version, sometimes API Extractor may report compilation' +
+                ' errors due to differences in the system typings (e.g. lib.dom.d.ts).  You can use the' +
+                ' "--typescriptCompilerFolder" option to specify the folder path where you installed the TypeScript package,' +
+                " and API Extractor's compiler will use those system typings instead."
+        });
+        this._printApiReportDiffFlag = this.defineFlagParameter({
+            parameterLongName: '--print-api-report-diff',
+            description: 'If provided, then any differences between the actual and expected API reports will be ' +
+                'printed on the console. Note that the diff is not printed if the expected API report file has not been ' +
+                'created yet.'
+        });
+    }
+    async onExecuteAsync() {
+        const lookup = new PackageJsonLookup();
+        let configFilename;
+        let typescriptCompilerFolder = this._typescriptCompilerFolderParameter.value;
+        if (typescriptCompilerFolder) {
+            typescriptCompilerFolder = path.normalize(typescriptCompilerFolder);
+            if (FileSystem.exists(typescriptCompilerFolder)) {
+                typescriptCompilerFolder = lookup.tryGetPackageFolderFor(typescriptCompilerFolder);
+                const typescriptCompilerPackageJson = typescriptCompilerFolder
+                    ? lookup.tryLoadPackageJsonFor(typescriptCompilerFolder)
+                    : undefined;
+                if (!typescriptCompilerPackageJson) {
+                    throw new Error(`The path specified in the ${this._typescriptCompilerFolderParameter.longName} parameter is not a package.`);
+                }
+                else if (typescriptCompilerPackageJson.name !== 'typescript') {
+                    throw new Error(`The path specified in the ${this._typescriptCompilerFolderParameter.longName} parameter is not a TypeScript` +
+                        ' compiler package.');
+                }
+            }
+            else {
+                throw new Error(`The path specified in the ${this._typescriptCompilerFolderParameter.longName} parameter does not exist.`);
+            }
+        }
+        let extractorConfig;
+        if (this._configFileParameter.value) {
+            configFilename = path.normalize(this._configFileParameter.value);
+            if (!FileSystem.exists(configFilename)) {
+                throw new Error('Config file not found: ' + this._configFileParameter.value);
+            }
+            extractorConfig = ExtractorConfig.loadFileAndPrepare(configFilename);
+        }
+        else {
+            const prepareOptions = ExtractorConfig.tryLoadForFolder({
+                startingFolder: '.'
+            });
+            if (!prepareOptions || !prepareOptions.configObjectFullPath) {
+                throw new Error(`Unable to find an ${ExtractorConfig.FILENAME} file`);
+            }
+            const configObjectShortPath = Path.formatConcisely({
+                pathToConvert: prepareOptions.configObjectFullPath,
+                baseFolder: process.cwd()
+            });
+            console.log(`Using configuration from ${configObjectShortPath}`);
+            extractorConfig = ExtractorConfig.prepare(prepareOptions);
+        }
+        const extractorResult = Extractor.invoke(extractorConfig, {
+            localBuild: this._localFlag.value,
+            showVerboseMessages: this._verboseFlag.value,
+            showDiagnostics: this._diagnosticsParameter.value,
+            typescriptCompilerFolder: typescriptCompilerFolder,
+            printApiReportDiff: this._printApiReportDiffFlag.value
+        });
+        if (extractorResult.succeeded) {
+            console.log(os.EOL + 'API Extractor completed successfully');
+        }
+        else {
+            if (extractorResult.errorCount > 0) {
+                console.log(os.EOL + Colorize.red('API Extractor completed with errors'));
+            }
+            else {
+                console.log(os.EOL + Colorize.yellow('API Extractor completed with warnings'));
+            }
+            throw new AlreadyReportedError();
+        }
+    }
+}
+//# sourceMappingURL=RunAction.js.map

package/lib-esm/cli/RunAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunAction.js","sourceRoot":"","sources":["../../src/cli/RunAction.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EACL,iBAAiB,EACjB,UAAU,EAEV,IAAI,EACJ,oBAAoB,EACrB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EACL,iBAAiB,EAGlB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,SAAS,EAAwB,MAAM,kBAAkB,CAAC;AAEnE,OAAO,EAAE,eAAe,EAAuC,MAAM,wBAAwB,CAAC;AAE9F,MAAM,OAAO,SAAU,SAAQ,iBAAiB;IAQ9C,YAAmB,MAA+B;QAChD,KAAK,CAAC;YACJ,UAAU,EAAE,KAAK;YACjB,OAAO,EAAE,mCAAmC;YAC5C,aAAa,EAAE,mCAAmC;SACnD,CAAC,CAAC;QAEH,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC,qBAAqB,CAAC;YACrD,iBAAiB,EAAE,UAAU;YAC7B,kBAAkB,EAAE,IAAI;YACxB,YAAY,EAAE,MAAM;YACpB,WAAW,EAAE,qBAAqB,eAAe,CAAC,QAAQ,+CAA+C;SAC1G,CAAC,CAAC;QAEH,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,mBAAmB,CAAC;YACzC,iBAAiB,EAAE,SAAS;YAC5B,kBAAkB,EAAE,IAAI;YACxB,WAAW,EACT,mEAAmE;gBACnE,6EAA6E;gBAC7E,+EAA+E;gBAC/E,wDAAwD;SAC3D,CAAC,CAAC;QAEH,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,mBAAmB,CAAC;YAC3C,iBAAiB,EAAE,WAAW;YAC9B,kBAAkB,EAAE,IAAI;YACxB,WAAW,EAAE,uDAAuD;SACrE,CAAC,CAAC;QAEH,IAAI,CAAC,qBAAqB,GAAG,IAAI,CAAC,mBAAmB,CAAC;YACpD,iBAAiB,EAAE,eAAe;YAClC,WAAW,EACT,gFAAgF;gBAChF,gDAAgD;SACnD,CAAC,CAAC;QAEH,IAAI,CAAC,kCAAkC,GAAG,IAAI,CAAC,qBAAqB,CAAC;YACnE,iBAAiB,EAAE,8BAA8B;YACjD,YAAY,EAAE,MAAM;YACpB,WAAW,EACT,iGAAiG;gBACjG,6GAA6G;gBAC7G,wFAAwF;gBACxF,6GAA6G;gBAC7G,sEAAsE;SACzE,CAAC,CAAC;QAEH,IAAI,CAAC,uBAAuB,GAAG,IAAI,CAAC,mBAAmB,CAAC;YACtD,iBAAiB,EAAE,yBAAyB;YAC5C,WAAW,EACT,wFAAwF;gBACxF,yGAAyG;gBACzG,cAAc;SACjB,CAAC,CAAC;IACL,CAAC;IAEkB,KAAK,CAAC,cAAc;QACrC,MAAM,MAAM,GAAsB,IAAI,iBAAiB,EAAE,CAAC;QAC1D,IAAI,cAAsB,CAAC;QAE3B,IAAI,wBAAwB,GAAuB,IAAI,CAAC,kCAAkC,CAAC,KAAK,CAAC;QACjG,IAAI,wBAAwB,EAAE,CAAC;YAC7B,wBAAwB,GAAG,IAAI,CAAC,SAAS,CAAC,wBAAwB,CAAC,CAAC;YAEpE,IAAI,UAAU,CAAC,MAAM,CAAC,wBAAwB,CAAC,EAAE,CAAC;gBAChD,wBAAwB,GAAG,MAAM,CAAC,sBAAsB,CAAC,wBAAwB,CAAC,CAAC;gBACnF,MAAM,6BAA6B,GAA6B,wBAAwB;oBACtF,CAAC,CAAC,MAAM,CAAC,qBAAqB,CAAC,wBAAwB,CAAC;oBACxD,CAAC,CAAC,SAAS,CAAC;gBACd,IAAI,CAAC,6BAA6B,EAAE,CAAC;oBACnC,MAAM,IAAI,KAAK,CACb,6BAA6B,IAAI,CAAC,kCAAkC,CAAC,QAAQ,8BAA8B,CAC5G,CAAC;gBACJ,CAAC;qBAAM,IAAI,6BAA6B,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;oBAC/D,MAAM,IAAI,KAAK,CACb,6BAA6B,IAAI,CAAC,kCAAkC,CAAC,QAAQ,gCAAgC;wBAC3G,oBAAoB,CACvB,CAAC;gBACJ,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CACb,6BAA6B,IAAI,CAAC,kCAAkC,CAAC,QAAQ,4BAA4B,CAC1G,CAAC;YACJ,CAAC;QACH,CAAC;QAED,IAAI,eAAgC,CAAC;QAErC,IAAI,IAAI,CAAC,oBAAoB,CAAC,KAAK,EAAE,CAAC;YACpC,cAAc,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;YACjE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;gBACvC,MAAM,IAAI,KAAK,CAAC,yBAAyB,GAAG,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;YAC/E,CAAC;YAED,eAAe,GAAG,eAAe,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAC;QACvE,CAAC;aAAM,CAAC;YACN,MAAM,cAAc,GAA+C,eAAe,CAAC,gBAAgB,CAAC;gBAClG,cAAc,EAAE,GAAG;aACpB,CAAC,CAAC;YAEH,IAAI,CAAC,cAAc,IAAI,CAAC,cAAc,CAAC,oBAAoB,EAAE,CAAC;gBAC5D,MAAM,IAAI,KAAK,CAAC,qBAAqB,eAAe,CAAC,QAAQ,OAAO,CAAC,CAAC;YACxE,CAAC;YAED,MAAM,qBAAqB,GAAW,IAAI,CAAC,eAAe,CAAC;gBACzD,aAAa,EAAE,cAAc,CAAC,oBAAoB;gBAClD,UAAU,EAAE,OAAO,CAAC,GAAG,EAAE;aAC1B,CAAC,CAAC;YACH,OAAO,CAAC,GAAG,CAAC,4BAA4B,qBAAqB,EAAE,CAAC,CAAC;YAEjE,eAAe,GAAG,eAAe,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QAC5D,CAAC;QAED,MAAM,eAAe,GAAoB,SAAS,CAAC,MAAM,CAAC,eAAe,EAAE;YACzE,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,KAAK;YACjC,mBAAmB,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK;YAC5C,eAAe,EAAE,IAAI,CAAC,qBAAqB,CAAC,KAAK;YACjD,wBAAwB,EAAE,wBAAwB;YAClD,kBAAkB,EAAE,IAAI,CAAC,uBAAuB,CAAC,KAAK;SACvD,CAAC,CAAC;QAEH,IAAI,eAAe,CAAC,SAAS,EAAE,CAAC;YAC9B,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,sCAAsC,CAAC,CAAC;QAC/D,CAAC;aAAM,CAAC;YACN,IAAI,eAAe,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;gBACnC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,qCAAqC,CAAC,CAAC,CAAC;YAC5E,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,uCAAuC,CAAC,CAAC,CAAC;YACjF,CAAC;YACD,MAAM,IAAI,oBAAoB,EAAE,CAAC;QACnC,CAAC;IACH,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport * as os from 'node:os';\nimport * as path from 'node:path';\n\nimport {\n  PackageJsonLookup,\n  FileSystem,\n  type IPackageJson,\n  Path,\n  AlreadyReportedError\n} from '@rushstack/node-core-library';\nimport { Colorize } from '@rushstack/terminal';\nimport {\n  CommandLineAction,\n  type CommandLineStringParameter,\n  type CommandLineFlagParameter\n} from '@rushstack/ts-command-line';\n\nimport { Extractor, type ExtractorResult } from '../api/Extractor';\nimport type { ApiExtractorCommandLine } from './ApiExtractorCommandLine';\nimport { ExtractorConfig, type IExtractorConfigPrepareOptions } from '../api/ExtractorConfig';\n\nexport class RunAction extends CommandLineAction {\n  private readonly _configFileParameter: CommandLineStringParameter;\n  private readonly _localFlag: CommandLineFlagParameter;\n  private readonly _verboseFlag: CommandLineFlagParameter;\n  private readonly _diagnosticsParameter: CommandLineFlagParameter;\n  private readonly _typescriptCompilerFolderParameter: CommandLineStringParameter;\n  private readonly _printApiReportDiffFlag: CommandLineFlagParameter;\n\n  public constructor(parser: ApiExtractorCommandLine) {\n    super({\n      actionName: 'run',\n      summary: 'Invoke API Extractor on a project',\n      documentation: 'Invoke API Extractor on a project'\n    });\n\n    this._configFileParameter = this.defineStringParameter({\n      parameterLongName: '--config',\n      parameterShortName: '-c',\n      argumentName: 'FILE',\n      description: `Use the specified ${ExtractorConfig.FILENAME} file path, rather than guessing its location`\n    });\n\n    this._localFlag = this.defineFlagParameter({\n      parameterLongName: '--local',\n      parameterShortName: '-l',\n      description:\n        'Indicates that API Extractor is running as part of a local build,' +\n        \" e.g. on a developer's machine. This disables certain validation that would\" +\n        ' normally be performed for a ship/production build. For example, the *.api.md' +\n        ' report file is automatically copied in a local build.'\n    });\n\n    this._verboseFlag = this.defineFlagParameter({\n      parameterLongName: '--verbose',\n      parameterShortName: '-v',\n      description: 'Show additional informational messages in the output.'\n    });\n\n    this._diagnosticsParameter = this.defineFlagParameter({\n      parameterLongName: '--diagnostics',\n      description:\n        'Show diagnostic messages used for troubleshooting problems with API Extractor.' +\n        '  This flag also enables the \"--verbose\" flag.'\n    });\n\n    this._typescriptCompilerFolderParameter = this.defineStringParameter({\n      parameterLongName: '--typescript-compiler-folder',\n      argumentName: 'PATH',\n      description:\n        'API Extractor uses its own TypeScript compiler engine to analyze your project.  If your project' +\n        ' is built with a significantly different TypeScript version, sometimes API Extractor may report compilation' +\n        ' errors due to differences in the system typings (e.g. lib.dom.d.ts).  You can use the' +\n        ' \"--typescriptCompilerFolder\" option to specify the folder path where you installed the TypeScript package,' +\n        \" and API Extractor's compiler will use those system typings instead.\"\n    });\n\n    this._printApiReportDiffFlag = this.defineFlagParameter({\n      parameterLongName: '--print-api-report-diff',\n      description:\n        'If provided, then any differences between the actual and expected API reports will be ' +\n        'printed on the console. Note that the diff is not printed if the expected API report file has not been ' +\n        'created yet.'\n    });\n  }\n\n  protected override async onExecuteAsync(): Promise<void> {\n    const lookup: PackageJsonLookup = new PackageJsonLookup();\n    let configFilename: string;\n\n    let typescriptCompilerFolder: string | undefined = this._typescriptCompilerFolderParameter.value;\n    if (typescriptCompilerFolder) {\n      typescriptCompilerFolder = path.normalize(typescriptCompilerFolder);\n\n      if (FileSystem.exists(typescriptCompilerFolder)) {\n        typescriptCompilerFolder = lookup.tryGetPackageFolderFor(typescriptCompilerFolder);\n        const typescriptCompilerPackageJson: IPackageJson | undefined = typescriptCompilerFolder\n          ? lookup.tryLoadPackageJsonFor(typescriptCompilerFolder)\n          : undefined;\n        if (!typescriptCompilerPackageJson) {\n          throw new Error(\n            `The path specified in the ${this._typescriptCompilerFolderParameter.longName} parameter is not a package.`\n          );\n        } else if (typescriptCompilerPackageJson.name !== 'typescript') {\n          throw new Error(\n            `The path specified in the ${this._typescriptCompilerFolderParameter.longName} parameter is not a TypeScript` +\n              ' compiler package.'\n          );\n        }\n      } else {\n        throw new Error(\n          `The path specified in the ${this._typescriptCompilerFolderParameter.longName} parameter does not exist.`\n        );\n      }\n    }\n\n    let extractorConfig: ExtractorConfig;\n\n    if (this._configFileParameter.value) {\n      configFilename = path.normalize(this._configFileParameter.value);\n      if (!FileSystem.exists(configFilename)) {\n        throw new Error('Config file not found: ' + this._configFileParameter.value);\n      }\n\n      extractorConfig = ExtractorConfig.loadFileAndPrepare(configFilename);\n    } else {\n      const prepareOptions: IExtractorConfigPrepareOptions | undefined = ExtractorConfig.tryLoadForFolder({\n        startingFolder: '.'\n      });\n\n      if (!prepareOptions || !prepareOptions.configObjectFullPath) {\n        throw new Error(`Unable to find an ${ExtractorConfig.FILENAME} file`);\n      }\n\n      const configObjectShortPath: string = Path.formatConcisely({\n        pathToConvert: prepareOptions.configObjectFullPath,\n        baseFolder: process.cwd()\n      });\n      console.log(`Using configuration from ${configObjectShortPath}`);\n\n      extractorConfig = ExtractorConfig.prepare(prepareOptions);\n    }\n\n    const extractorResult: ExtractorResult = Extractor.invoke(extractorConfig, {\n      localBuild: this._localFlag.value,\n      showVerboseMessages: this._verboseFlag.value,\n      showDiagnostics: this._diagnosticsParameter.value,\n      typescriptCompilerFolder: typescriptCompilerFolder,\n      printApiReportDiff: this._printApiReportDiffFlag.value\n    });\n\n    if (extractorResult.succeeded) {\n      console.log(os.EOL + 'API Extractor completed successfully');\n    } else {\n      if (extractorResult.errorCount > 0) {\n        console.log(os.EOL + Colorize.red('API Extractor completed with errors'));\n      } else {\n        console.log(os.EOL + Colorize.yellow('API Extractor completed with warnings'));\n      }\n      throw new AlreadyReportedError();\n    }\n  }\n}\n"]}

package/lib-esm/collector/ApiItemMetadata.js

@@ -0,0 +1,55 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { VisitorState } from './VisitorState';
+/**
+ * Stores the Collector's additional analysis for an `AstDeclaration`.  This object is assigned to
+ * `AstDeclaration.apiItemMetadata` but consumers must always obtain it by calling `Collector.fetchApiItemMetadata()`.
+ *
+ * @remarks
+ * Note that ancillary declarations share their `ApiItemMetadata` with the main declaration,
+ * whereas a separate `DeclarationMetadata` object is created for each declaration.
+ *
+ * Consider this example:
+ * ```ts
+ * export declare class A {
+ *   get b(): string;
+ *   set b(value: string);
+ * }
+ * export declare namespace A { }
+ * ```
+ *
+ * In this example, there are two "symbols": `A` and `b`
+ *
+ * There are four "declarations": `A` class, `A` namespace, `b` getter, `b` setter
+ *
+ * There are three "API items": `A` class, `A` namespace, `b` property.  The property getter is the main declaration
+ * for `b`, and the setter is the "ancillary" declaration.
+ */
+export class ApiItemMetadata {
+    constructor(options) {
+        /**
+         * Tracks whether or not the associated API item is known to be missing sufficient documentation.
+         *
+         * @remarks
+         *
+         * An "undocumented" item is one whose TSDoc comment which either does not contain a summary comment block, or
+         * has an `@inheritDoc` tag that resolves to another "undocumented" API member.
+         *
+         * If there is any ambiguity (e.g. if an `@inheritDoc` comment points to an external API member, whose documentation,
+         * we can't parse), "undocumented" will be `false`.
+         *
+         * @remarks Assigned by {@link DocCommentEnhancer}.
+         */
+        this.undocumented = true;
+        this.docCommentEnhancerVisitorState = VisitorState.Unvisited;
+        this.declaredReleaseTag = options.declaredReleaseTag;
+        this.effectiveReleaseTag = options.effectiveReleaseTag;
+        this.releaseTagSameAsParent = options.releaseTagSameAsParent;
+        this.isEventProperty = options.isEventProperty;
+        this.isOverride = options.isOverride;
+        this.isSealed = options.isSealed;
+        this.isVirtual = options.isVirtual;
+        this.isPreapproved = options.isPreapproved;
+    }
+}
+//# sourceMappingURL=ApiItemMetadata.js.map

package/lib-esm/collector/ApiItemMetadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiItemMetadata.js","sourceRoot":"","sources":["../../src/collector/ApiItemMetadata.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAK3D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAgB9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,eAAe;IAiD1B,YAAmB,OAAgC;QAjBnD;;;;;;;;;;;;WAYG;QACI,iBAAY,GAAY,IAAI,CAAC;QAE7B,mCAA8B,GAAiB,YAAY,CAAC,SAAS,CAAC;QAG3E,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;QACrD,IAAI,CAAC,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC;QACvD,IAAI,CAAC,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC;QAC7D,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC/C,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAC7C,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport type * as tsdoc from '@microsoft/tsdoc';\nimport type { ReleaseTag } from '@microsoft/api-extractor-model';\n\nimport { VisitorState } from './VisitorState';\n\n/**\n * Constructor parameters for `ApiItemMetadata`.\n */\nexport interface IApiItemMetadataOptions {\n  declaredReleaseTag: ReleaseTag;\n  effectiveReleaseTag: ReleaseTag;\n  releaseTagSameAsParent: boolean;\n  isEventProperty: boolean;\n  isOverride: boolean;\n  isSealed: boolean;\n  isVirtual: boolean;\n  isPreapproved: boolean;\n}\n\n/**\n * Stores the Collector's additional analysis for an `AstDeclaration`.  This object is assigned to\n * `AstDeclaration.apiItemMetadata` but consumers must always obtain it by calling `Collector.fetchApiItemMetadata()`.\n *\n * @remarks\n * Note that ancillary declarations share their `ApiItemMetadata` with the main declaration,\n * whereas a separate `DeclarationMetadata` object is created for each declaration.\n *\n * Consider this example:\n * ```ts\n * export declare class A {\n *   get b(): string;\n *   set b(value: string);\n * }\n * export declare namespace A { }\n * ```\n *\n * In this example, there are two \"symbols\": `A` and `b`\n *\n * There are four \"declarations\": `A` class, `A` namespace, `b` getter, `b` setter\n *\n * There are three \"API items\": `A` class, `A` namespace, `b` property.  The property getter is the main declaration\n * for `b`, and the setter is the \"ancillary\" declaration.\n */\nexport class ApiItemMetadata {\n  /**\n   * This is the release tag that was explicitly specified in the original doc comment, if any.\n   */\n  public readonly declaredReleaseTag: ReleaseTag;\n\n  /**\n   * The \"effective\" release tag is a normalized value that is based on `declaredReleaseTag`,\n   * but may be inherited from a parent, or corrected if the declared value was somehow invalid.\n   * When actually trimming .d.ts files or generating docs, API Extractor uses the \"effective\" value\n   * instead of the \"declared\" value.\n   */\n  public readonly effectiveReleaseTag: ReleaseTag;\n\n  // If true, then it would be redundant to show this release tag\n  public readonly releaseTagSameAsParent: boolean;\n\n  // NOTE: In the future, the Collector may infer or error-correct some of these states.\n  // Generators should rely on these instead of tsdocComment.modifierTagSet.\n  public readonly isEventProperty: boolean;\n  public readonly isOverride: boolean;\n  public readonly isSealed: boolean;\n  public readonly isVirtual: boolean;\n\n  public readonly isPreapproved: boolean;\n\n  /**\n   * This is the TSDoc comment for the declaration.  It may be modified (or constructed artificially) by\n   * the DocCommentEnhancer.\n   */\n  public tsdocComment: tsdoc.DocComment | undefined;\n\n  /**\n   * Tracks whether or not the associated API item is known to be missing sufficient documentation.\n   *\n   * @remarks\n   *\n   * An \"undocumented\" item is one whose TSDoc comment which either does not contain a summary comment block, or\n   * has an `@inheritDoc` tag that resolves to another \"undocumented\" API member.\n   *\n   * If there is any ambiguity (e.g. if an `@inheritDoc` comment points to an external API member, whose documentation,\n   * we can't parse), \"undocumented\" will be `false`.\n   *\n   * @remarks Assigned by {@link DocCommentEnhancer}.\n   */\n  public undocumented: boolean = true;\n\n  public docCommentEnhancerVisitorState: VisitorState = VisitorState.Unvisited;\n\n  public constructor(options: IApiItemMetadataOptions) {\n    this.declaredReleaseTag = options.declaredReleaseTag;\n    this.effectiveReleaseTag = options.effectiveReleaseTag;\n    this.releaseTagSameAsParent = options.releaseTagSameAsParent;\n    this.isEventProperty = options.isEventProperty;\n    this.isOverride = options.isOverride;\n    this.isSealed = options.isSealed;\n    this.isVirtual = options.isVirtual;\n    this.isPreapproved = options.isPreapproved;\n  }\n}\n"]}