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/api/test/Extractor-custom-tags.test.ts

@@ -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 * as path from 'node:path';
+import { StandardTags } from '@microsoft/tsdoc';
+import { ExtractorConfig } from '../ExtractorConfig.js';
+
+const testDataFolder: string = path.join(__dirname, 'test-data');
+
+describe('Extractor-custom-tags', () => {
+	describe('should use a TSDocConfiguration', () => {
+		it.only("with custom TSDoc tags defined in the package's tsdoc.json", () => {
+			const extractorConfig: ExtractorConfig = ExtractorConfig.loadFileAndPrepare(
+				path.join(testDataFolder, 'custom-tsdoc-tags/api-extractor.json'),
+			);
+			const { tsdocConfiguration } = extractorConfig;
+
+			expect(tsdocConfiguration.tryGetTagDefinition('@block')).not.toBe(undefined);
+			expect(tsdocConfiguration.tryGetTagDefinition('@inline')).not.toBe(undefined);
+			expect(tsdocConfiguration.tryGetTagDefinition('@modifier')).not.toBe(undefined);
+		});
+		it.only("with custom TSDoc tags enabled per the package's tsdoc.json", () => {
+			const extractorConfig: ExtractorConfig = ExtractorConfig.loadFileAndPrepare(
+				path.join(testDataFolder, 'custom-tsdoc-tags/api-extractor.json'),
+			);
+			const { tsdocConfiguration } = extractorConfig;
+			const block = tsdocConfiguration.tryGetTagDefinition('@block')!;
+			const inline = tsdocConfiguration.tryGetTagDefinition('@inline')!;
+			const modifier = tsdocConfiguration.tryGetTagDefinition('@modifier')!;
+
+			expect(tsdocConfiguration.isTagSupported(block)).toBe(true);
+			expect(tsdocConfiguration.isTagSupported(inline)).toBe(true);
+			expect(tsdocConfiguration.isTagSupported(modifier)).toBe(false);
+		});
+		it.only("with standard tags and API Extractor custom tags defined and supported when the package's tsdoc.json extends API Extractor's tsdoc.json", () => {
+			const extractorConfig: ExtractorConfig = ExtractorConfig.loadFileAndPrepare(
+				path.join(testDataFolder, 'custom-tsdoc-tags/api-extractor.json'),
+			);
+			const { tsdocConfiguration } = extractorConfig;
+
+			expect(tsdocConfiguration.tryGetTagDefinition('@inline')).not.toBe(undefined);
+			expect(tsdocConfiguration.tryGetTagDefinition('@block')).not.toBe(undefined);
+			expect(tsdocConfiguration.tryGetTagDefinition('@modifier')).not.toBe(undefined);
+
+			for (const tag of StandardTags.allDefinitions.concat([
+				tsdocConfiguration.tryGetTagDefinition('@betaDocumentation')!,
+				tsdocConfiguration.tryGetTagDefinition('@internalRemarks')!,
+				tsdocConfiguration.tryGetTagDefinition('@preapproved')!,
+			])) {
+				expect(tsdocConfiguration.tagDefinitions.includes(tag));
+				expect(tsdocConfiguration.supportedTagDefinitions.includes(tag));
+			}
+		});
+	});
+});

packages/api-extractor/src/api/test/ExtractorConfig-lookup.test.ts

@@ -0,0 +1,36 @@
+// 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 { Path } from '@rushstack/node-core-library';
+import { ExtractorConfig } from '../ExtractorConfig.js';
+
+const testDataFolder: string = path.join(__dirname, 'test-data');
+
+function expectEqualPaths(path1: string, path2: string): void {
+	if (!Path.isEqual(path1, path2)) {
+		fail('Expected paths to be equal:\npath1: ' + path1 + '\npath2: ' + path2);
+	}
+}
+
+// Tests for expanding the "<lookup>" token for the "projectFolder" setting in api-extractor.json
+describe(`${ExtractorConfig.name}.${ExtractorConfig.loadFileAndPrepare.name}`, () => {
+	it.only('config-lookup1: looks up ./api-extractor.json', () => {
+		const extractorConfig: ExtractorConfig = ExtractorConfig.loadFileAndPrepare(
+			path.join(testDataFolder, 'config-lookup1/api-extractor.json'),
+		);
+		expectEqualPaths(extractorConfig.projectFolder, path.join(testDataFolder, 'config-lookup1'));
+	});
+	it.only('config-lookup2: looks up ./config/api-extractor.json', () => {
+		const extractorConfig: ExtractorConfig = ExtractorConfig.loadFileAndPrepare(
+			path.join(testDataFolder, 'config-lookup2/config/api-extractor.json'),
+		);
+		expectEqualPaths(extractorConfig.projectFolder, path.join(testDataFolder, 'config-lookup2'));
+	});
+	it.only('config-lookup3a: looks up ./src/test/config/api-extractor.json', () => {
+		const extractorConfig: ExtractorConfig = ExtractorConfig.loadFileAndPrepare(
+			path.join(testDataFolder, 'config-lookup3/src/test/config/api-extractor.json'),
+		);
+		expectEqualPaths(extractorConfig.projectFolder, path.join(testDataFolder, 'config-lookup3/src/test/'));
+	});
+});

packages/api-extractor/src/api/test/test-data/config-lookup1/api-extractor.json

@@ -0,0 +1,17 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+	"mainEntryPointFilePath": "<projectFolder>/index.d.ts",
+
+	"apiReport": {
+		"enabled": true
+	},
+
+	"docModel": {
+		"enabled": true
+	},
+
+	"dtsRollup": {
+		"enabled": true
+	}
+}

packages/api-extractor/src/api/test/test-data/config-lookup1/index.d.ts

@@ -0,0 +1,2 @@
+/* eslint-disable unicorn/no-empty-file */
+// empty file

packages/api-extractor/src/api/test/test-data/config-lookup1/package.json

@@ -0,0 +1,4 @@
+{
+	"name": "config-lookup1",
+	"version": "1.0.0"
+}

packages/api-extractor/src/api/test/test-data/config-lookup1/tsconfig.json

@@ -0,0 +1,25 @@
+{
+	"$schema": "http://json.schemastore.org/tsconfig",
+
+	"compilerOptions": {
+		"outDir": "lib",
+		"rootDir": "src",
+
+		"forceConsistentCasingInFileNames": true,
+		"jsx": "react",
+		"declaration": true,
+		"sourceMap": true,
+		"declarationMap": true,
+		"inlineSources": true,
+		"experimentalDecorators": true,
+		"strictNullChecks": true,
+		"noUnusedLocals": true,
+		"types": ["heft-jest", "node"],
+
+		"module": "commonjs",
+		"target": "es2017",
+		"lib": ["es2017"]
+	},
+	"include": ["src/**/*.ts", "src/**/*.tsx"],
+	"exclude": ["node_modules", "lib"]
+}

packages/api-extractor/src/api/test/test-data/config-lookup2/config/api-extractor.json

@@ -0,0 +1,17 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+	"mainEntryPointFilePath": "<projectFolder>/index.d.ts",
+
+	"apiReport": {
+		"enabled": true
+	},
+
+	"docModel": {
+		"enabled": true
+	},
+
+	"dtsRollup": {
+		"enabled": true
+	}
+}

packages/api-extractor/src/api/test/test-data/config-lookup2/index.d.ts

@@ -0,0 +1,2 @@
+/* eslint-disable unicorn/no-empty-file */
+// empty file

packages/api-extractor/src/api/test/test-data/config-lookup2/package.json

@@ -0,0 +1,4 @@
+{
+	"name": "config-lookup2",
+	"version": "1.0.0"
+}

packages/api-extractor/src/api/test/test-data/config-lookup2/tsconfig.json

@@ -0,0 +1,25 @@
+{
+	"$schema": "http://json.schemastore.org/tsconfig",
+
+	"compilerOptions": {
+		"outDir": "lib",
+		"rootDir": "src",
+
+		"forceConsistentCasingInFileNames": true,
+		"jsx": "react",
+		"declaration": true,
+		"sourceMap": true,
+		"declarationMap": true,
+		"inlineSources": true,
+		"experimentalDecorators": true,
+		"strictNullChecks": true,
+		"noUnusedLocals": true,
+		"types": ["heft-jest", "node"],
+
+		"module": "commonjs",
+		"target": "es2017",
+		"lib": ["es2017"]
+	},
+	"include": ["src/**/*.ts", "src/**/*.tsx"],
+	"exclude": ["node_modules", "lib"]
+}

packages/api-extractor/src/api/test/test-data/config-lookup3/config/api-extractor.json

@@ -0,0 +1,17 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+	"mainEntryPointFilePath": "<projectFolder>/index.d.ts",
+
+	"apiReport": {
+		"enabled": true
+	},
+
+	"docModel": {
+		"enabled": true
+	},
+
+	"dtsRollup": {
+		"enabled": true
+	}
+}

packages/api-extractor/src/api/test/test-data/config-lookup3/index.d.ts

@@ -0,0 +1,2 @@
+/* eslint-disable unicorn/no-empty-file */
+// empty file

packages/api-extractor/src/api/test/test-data/config-lookup3/package.json

@@ -0,0 +1,4 @@
+{
+	"name": "config-lookup3",
+	"version": "1.0.0"
+}

packages/api-extractor/src/api/test/test-data/config-lookup3/src/test/config/api-extractor.json

@@ -0,0 +1,17 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+	"mainEntryPointFilePath": "<projectFolder>/index.d.ts",
+
+	"apiReport": {
+		"enabled": true
+	},
+
+	"docModel": {
+		"enabled": true
+	},
+
+	"dtsRollup": {
+		"enabled": true
+	}
+}

packages/api-extractor/src/api/test/test-data/config-lookup3/src/test/index.d.ts

@@ -0,0 +1,2 @@
+/* eslint-disable unicorn/no-empty-file */
+// empty file

packages/api-extractor/src/api/test/test-data/config-lookup3/src/test/tsconfig.json

@@ -0,0 +1,25 @@
+{
+	"$schema": "http://json.schemastore.org/tsconfig",
+
+	"compilerOptions": {
+		"outDir": "lib",
+		"rootDir": "src",
+
+		"forceConsistentCasingInFileNames": true,
+		"jsx": "react",
+		"declaration": true,
+		"sourceMap": true,
+		"declarationMap": true,
+		"inlineSources": true,
+		"experimentalDecorators": true,
+		"strictNullChecks": true,
+		"noUnusedLocals": true,
+		"types": ["heft-jest", "node"],
+
+		"module": "commonjs",
+		"target": "es2017",
+		"lib": ["es2017"]
+	},
+	"include": ["src/**/*.ts", "src/**/*.tsx"],
+	"exclude": ["node_modules", "lib"]
+}

packages/api-extractor/src/api/test/test-data/config-lookup3/tsconfig.json

@@ -0,0 +1,25 @@
+{
+	"$schema": "http://json.schemastore.org/tsconfig",
+
+	"compilerOptions": {
+		"outDir": "lib",
+		"rootDir": "src",
+
+		"forceConsistentCasingInFileNames": true,
+		"jsx": "react",
+		"declaration": true,
+		"sourceMap": true,
+		"declarationMap": true,
+		"inlineSources": true,
+		"experimentalDecorators": true,
+		"strictNullChecks": true,
+		"noUnusedLocals": true,
+		"types": ["heft-jest", "node"],
+
+		"module": "commonjs",
+		"target": "es2017",
+		"lib": ["es2017"]
+	},
+	"include": ["src/**/*.ts", "src/**/*.tsx"],
+	"exclude": ["node_modules", "lib"]
+}

packages/api-extractor/src/api/test/test-data/custom-tsdoc-tags/api-extractor.json

@@ -0,0 +1,17 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+	"mainEntryPointFilePath": "<projectFolder>/index.d.ts",
+
+	"apiReport": {
+		"enabled": true
+	},
+
+	"docModel": {
+		"enabled": true
+	},
+
+	"dtsRollup": {
+		"enabled": true
+	}
+}

packages/api-extractor/src/api/test/test-data/custom-tsdoc-tags/index.d.ts

@@ -0,0 +1,7 @@
+/* eslint-disable @typescript-eslint/no-empty-interface,tsdoc/syntax */
+/**
+ * @block
+ * @inline test
+ * @modifier
+ */
+interface CustomTagsTestInterface {}

packages/api-extractor/src/api/test/test-data/custom-tsdoc-tags/package.json

@@ -0,0 +1,4 @@
+{
+	"name": "config-lookup1",
+	"version": "1.0.0"
+}

packages/api-extractor/src/api/test/test-data/custom-tsdoc-tags/tsconfig.json

@@ -0,0 +1,25 @@
+{
+	"$schema": "http://json.schemastore.org/tsconfig",
+
+	"compilerOptions": {
+		"outDir": "lib",
+		"rootDir": "src",
+
+		"forceConsistentCasingInFileNames": true,
+		"jsx": "react",
+		"declaration": true,
+		"sourceMap": true,
+		"declarationMap": true,
+		"inlineSources": true,
+		"experimentalDecorators": true,
+		"strictNullChecks": true,
+		"noUnusedLocals": true,
+		"types": ["heft-jest", "node"],
+
+		"module": "commonjs",
+		"target": "es2017",
+		"lib": ["es2017"]
+	},
+	"include": ["src/**/*.ts", "src/**/*.tsx"],
+	"exclude": ["node_modules", "lib"]
+}

packages/api-extractor/src/api/test/test-data/custom-tsdoc-tags/tsdoc.json

@@ -0,0 +1,24 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+	"extends": ["../../../../../extends/tsdoc-base.json"],
+	"tagDefinitions": [
+		{
+			"tagName": "@block",
+			"syntaxKind": "block"
+		},
+		{
+			"tagName": "@inline",
+			"syntaxKind": "inline",
+			"allowMultiple": true
+		},
+		{
+			"tagName": "@modifier",
+			"syntaxKind": "modifier"
+		}
+	],
+	"supportForTags": {
+		"@block": true,
+		"@inline": true,
+		"@modifier": false
+	}
+}