build: package api-extractor and -model (#9920)

* fix(ExceptText): don't display import("d..-types/v10"). in return type

* Squashed 'packages/api-extractor-model/' content from commit 39ecb196c

git-subtree-dir: packages/api-extractor-model
git-subtree-split: 39ecb196ca210bdf84ba6c9cadb1bb93571849d7

* Squashed 'packages/api-extractor/' content from commit 341ad6c51

git-subtree-dir: packages/api-extractor
git-subtree-split: 341ad6c51b01656d4f73b74ad4bdb3095f9262c4

* feat(api-extractor): add api-extractor and -model

* fix: package.json docs script

* fix(SourcLink): use <> instead of function syntax

* fix: make packages private

* fix: rest params showing in docs, added labels

* fix: missed two files

* fix: cpy-cli & pnpm-lock

* fix: increase icon size

* fix: icon size again

packages/api-extractor/src/cli/ApiExtractorCommandLine.ts

@@ -0,0 +1,57 @@
+// 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 { InternalError } from '@rushstack/node-core-library';
+import { CommandLineParser, type CommandLineFlagParameter } from '@rushstack/ts-command-line';
+import colors from 'colors';
+import { InitAction } from './InitAction.js';
+import { RunAction } from './RunAction.js';
+
+export class ApiExtractorCommandLine extends CommandLineParser {
+	private readonly _debugParameter: CommandLineFlagParameter;
+
+	public 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',
+		});
+	}
+
+	protected override async onExecute(): Promise<void> {
+		// override
+		if (this._debugParameter.value) {
+			InternalError.breakInDebugger = true;
+		}
+
+		try {
+			await super.onExecute();
+		} catch (error: any) {
+			if (this._debugParameter.value) {
+				console.error(os.EOL + error.stack);
+			} else {
+				console.error(os.EOL + colors.red('ERROR: ' + error.message.trim()));
+			}
+
+			// eslint-disable-next-line no-restricted-globals, n/prefer-global/process
+			process.exitCode = 1;
+		}
+	}
+
+	private _populateActions(): void {
+		this.addAction(new InitAction(this));
+		this.addAction(new RunAction(this));
+	}
+}

packages/api-extractor/src/cli/InitAction.ts

@@ -0,0 +1,45 @@
+// 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 colors from 'colors';
+import { ExtractorConfig } from '../api/ExtractorConfig.js';
+import type { ApiExtractorCommandLine } from './ApiExtractorCommandLine.js';
+
+export class InitAction extends CommandLineAction {
+	public constructor(_parser: ApiExtractorCommandLine) {
+		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.`,
+		});
+	}
+
+	protected async onExecute(): Promise<void> {
+		// override
+		const inputFilePath: string = path.resolve(__dirname, './schemas/api-extractor-template.json');
+		const outputFilePath: string = path.resolve(ExtractorConfig.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.',
+		);
+	}
+}

packages/api-extractor/src/cli/RunAction.ts

@@ -0,0 +1,156 @@
+/* eslint-disable n/prefer-global/process */
+/* eslint-disable no-restricted-globals */
+// 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, type IPackageJson, Path } from '@rushstack/node-core-library';
+import {
+	CommandLineAction,
+	type CommandLineStringParameter,
+	type CommandLineFlagParameter,
+} from '@rushstack/ts-command-line';
+import colors from 'colors';
+import { Extractor, type ExtractorResult } from '../api/Extractor.js';
+import { ExtractorConfig, type IExtractorConfigPrepareOptions } from '../api/ExtractorConfig.js';
+import type { ApiExtractorCommandLine } from './ApiExtractorCommandLine.js';
+
+export class RunAction extends CommandLineAction {
+	private readonly _configFileParameter: CommandLineStringParameter;
+
+	private readonly _localParameter: CommandLineFlagParameter;
+
+	private readonly _verboseParameter: CommandLineFlagParameter;
+
+	private readonly _diagnosticsParameter: CommandLineFlagParameter;
+
+	private readonly _typescriptCompilerFolder: CommandLineStringParameter;
+
+	public constructor(_parser: ApiExtractorCommandLine) {
+		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._localParameter = 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._verboseParameter = 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._typescriptCompilerFolder = 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.",
+		});
+	}
+
+	protected async onExecute(): Promise<void> {
+		// override
+		const lookup: PackageJsonLookup = new PackageJsonLookup();
+		let configFilename: string;
+
+		let typescriptCompilerFolder: string | undefined = this._typescriptCompilerFolder.value;
+		if (typescriptCompilerFolder) {
+			typescriptCompilerFolder = path.normalize(typescriptCompilerFolder);
+
+			if (FileSystem.exists(typescriptCompilerFolder)) {
+				typescriptCompilerFolder = lookup.tryGetPackageFolderFor(typescriptCompilerFolder);
+				const typescriptCompilerPackageJson: IPackageJson | undefined = typescriptCompilerFolder
+					? lookup.tryLoadPackageJsonFor(typescriptCompilerFolder)
+					: undefined;
+				if (!typescriptCompilerPackageJson) {
+					throw new Error(
+						`The path specified in the ${this._typescriptCompilerFolder.longName} parameter is not a package.`,
+					);
+				} else if (typescriptCompilerPackageJson.name !== 'typescript') {
+					throw new Error(
+						`The path specified in the ${this._typescriptCompilerFolder.longName} parameter is not a TypeScript` +
+							' compiler package.',
+					);
+				}
+			} else {
+				throw new Error(
+					`The path specified in the ${this._typescriptCompilerFolder.longName} parameter does not exist.`,
+				);
+			}
+		}
+
+		let extractorConfig: 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: IExtractorConfigPrepareOptions | undefined = ExtractorConfig.tryLoadForFolder({
+				startingFolder: '.',
+			});
+
+			if (!prepareOptions?.configObjectFullPath) {
+				throw new Error(`Unable to find an ${ExtractorConfig.FILENAME} file`);
+			}
+
+			const configObjectShortPath: string = Path.formatConcisely({
+				pathToConvert: prepareOptions.configObjectFullPath,
+				baseFolder: process.cwd(),
+			});
+			console.log(`Using configuration from ${configObjectShortPath}`);
+
+			extractorConfig = ExtractorConfig.prepare(prepareOptions);
+		}
+
+		const extractorResult: ExtractorResult = Extractor.invoke(extractorConfig, {
+			localBuild: this._localParameter.value,
+			showVerboseMessages: this._verboseParameter.value,
+			showDiagnostics: this._diagnosticsParameter.value,
+			typescriptCompilerFolder,
+		});
+
+		if (extractorResult.succeeded) {
+			console.log(os.EOL + 'API Extractor completed successfully');
+		} else {
+			process.exitCode = 1;
+
+			if (extractorResult.errorCount > 0) {
+				console.log(os.EOL + colors.red('API Extractor completed with errors'));
+			} else {
+				console.log(os.EOL + colors.yellow('API Extractor completed with warnings'));
+			}
+		}
+	}
+}