feat(api-extractor): support multiple entrypoints (#10829)

* feat(api-extractor): support multiple entrypoints * chore: initial support in generateSplitDocumentation * chore: bring in line with upstream * refactor: multiple entrypoints in scripts * fix: split docs * feat: website * fix: docs failing on next * fix: don't include dtypes for now * refactor: don't fetch entrypoint if there is none --------- Co-authored-by: iCrawl <buechler.noel@outlook.com>
2026-03-13 10:03:31 +01:00 · 2025-05-12 23:48:41 +02:00
parent 4f5e5c7c14
commit b3db92edfb
93 changed files with 2330 additions and 1956 deletions
--- a/packages/api-extractor/src/schemas/api-extractor-template.json
+++ b/packages/api-extractor/src/schemas/api-extractor-template.json
@@ -138,15 +138,31 @@
 		"enabled": true

 		/**
-		 * The filename for the API report files.  It will be combined with "reportFolder" or "reportTempFolder" to produce
-		 * a full file path.
+		 * The base filename for the API report files, to be combined with "reportFolder" or "reportTempFolder"
+		 * to produce the full file path.  The "reportFileName" should not include any path separators such as
+		 * "\" or "/".  The "reportFileName" should not include a file extension, since API Extractor will automatically
+		 * append an appropriate file extension such as ".api.md".  If the "reportVariants" setting is used, then the
+		 * file extension includes the variant name, for example "my-report.public.api.md" or "my-report.beta.api.md".
+		 * The "complete" variant always uses the simple extension "my-report.api.md".
 		 *
-		 * The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/".
+		 * Previous versions of API Extractor required "reportFileName" to include the ".api.md" extension explicitly;
+		 * for backwards compatibility, that is still accepted but will be discarded before applying the above rules.
 		 *
 		 * SUPPORTED TOKENS: <packageName>, <unscopedPackageName>
-		 * DEFAULT VALUE: "<unscopedPackageName>.api.md"
+		 * DEFAULT VALUE: "<unscopedPackageName>"
 		 */
-		// "reportFileName": "<unscopedPackageName>.api.md",
+		// "reportFileName": "<unscopedPackageName>",
+
+		/**
+		 * To support different approval requirements for different API levels, multiple "variants" of the API report can
+		 * be generated.  The "reportVariants" setting specifies a list of variants to be generated.  If omitted,
+		 * by default only the "complete" variant will be generated, which includes all @internal, @alpha, @beta,
+		 * and @public items.  Other possible variants are "alpha" (@alpha + @beta + @public), "beta" (@beta + @public),
+		 * and "public" (@public only).
+		 *
+		 * DEFAULT VALUE: [ "complete" ]
+		 */
+		// "reportVariants": ["public", "beta"],

 		/**
 		 * Specifies the folder where the API report file is written.  The file name portion is determined by
@@ -159,9 +175,9 @@
 		 * prepend a folder token such as "<projectFolder>".
 		 *
 		 * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-		 * DEFAULT VALUE: "<projectFolder>/temp/"
+		 * DEFAULT VALUE: "<projectFolder>/etc/"
 		 */
-		// "reportFolder": "<projectFolder>/temp/",
+		// "reportFolder": "<projectFolder>/etc/",

 		/**
 		 * Specifies the folder where the temporary report file is written.  The file name portion is determined by
@@ -226,7 +242,7 @@
 		 * item's file path is "api/ExtractorConfig.ts", the full URL file path would be
 		 * "https://github.com/microsoft/rushstack/tree/main/apps/api-extractor/api/ExtractorConfig.js".
 		 *
-		 * Can be omitted if you don't need source code links in your API documentation reference.
+		 * This setting can be omitted if you don't need source code links in your API documentation reference.
 		 *
 		 * SUPPORTED TOKENS: none
 		 * DEFAULT VALUE: ""
@@ -261,6 +277,8 @@
 		 * Specifies the output path for a .d.ts rollup file to be generated with trimming for an "alpha" release.
 		 * This file will include only declarations that are marked as "@public", "@beta", or "@alpha".
 		 *
+		 * If the path is an empty string, then this file will not be written.
+		 *
 		 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
 		 * prepend a folder token such as "<projectFolder>".
 		 *
@@ -273,6 +291,8 @@
 		 * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
 		 * This file will include only declarations that are marked as "@public" or "@beta".
 		 *
+		 * If the path is an empty string, then this file will not be written.
+		 *
 		 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
 		 * prepend a folder token such as "<projectFolder>".
 		 *
--- a/packages/api-extractor/src/schemas/api-extractor.schema.json
+++ b/packages/api-extractor/src/schemas/api-extractor.schema.json
@@ -23,6 +23,14 @@
 			"type": "string"
 		},

+		"additionalEntryPoints": {
+			"description": "Specifies the .d.ts files to be used as the starting points for analysis.",
+			"type": "array",
+			"items": {
+				"type": "object"
+			}
+		},
+
 		"bundledPackages": {
 			"description": "A list of NPM package names whose exports should be treated as part of this package.",
 			"type": "array",
@@ -68,8 +76,17 @@
 				},

 				"reportFileName": {
-					"description": "The filename for the API report files.  It will be combined with \"reportFolder\" or \"reportTempFolder\" to produce a full file path. The file extension should be \".api.md\", and the string should not contain a path separator such as \"\\\" or \"/\".",
-					"type": "string"
+					"description": "The base filename for the API report files, to be combined with \"reportFolder\" or \"reportTempFolder\" to produce the full file path.  The \"reportFileName\" should not include any path separators such as \"\\\" or \"/\".  The \"reportFileName\" should not include a file extension, since API Extractor will automatically append an appropriate file extension such as \".api.md\".  If the \"reportVariants\" setting is used, then the file extension includes the variant name, for example \"my-report.public.api.md\" or \"my-report.beta.api.md\".  The \"complete\" variant always uses the simple extension \"my-report.api.md\".\n\nPrevious versions of API Extractor required \"reportFileName\" to include the \".api.md\" extension explicitly; for backwards compatibility, that is still accepted but will be discarded before applying the above rules.",
+					"type": ["string"]
+				},
+
+				"reportVariants": {
+					"description": "To support different approval requirements for different API levels, multiple \"variants\" of the API report can be generated.  The \"reportVariants\" setting specifies a list of variants to be generated.  If omitted, by default only the \"complete\" variant will be generated, which includes all @internal, @alpha, @beta, and @public items.  Other possible variants are \"alpha\" (@alpha + @beta + @public), \"beta\" (@beta + @public), and \"public\" (@public only).",
+					"type": "array",
+					"items": {
+						"type": "string",
+						"enum": ["public", "beta", "alpha", "complete"]
+					}
 				},

 				"reportFolder": {
@@ -85,6 +102,17 @@
 				"includeForgottenExports": {
 					"description": "Whether \"forgotten exports\" should be included in the API report file. Forgotten exports are declarations flagged with `ae-forgotten-export` warnings. See https://api-extractor.com/pages/messages/ae-forgotten-export/ to learn more.",
 					"type": "boolean"
+				},
+
+				"tagsToReport": {
+					"description": "Specifies a list of TSDoc tags that should be reported in the API report file for items whose documentation contains them.  This can be used to include standard TSDoc tags or custom ones.  Specified tag names must begin with \"@\".  By default, the following tags are reported: [@sealed, @virtual, @override, @eventProperty, @deprecated].  Tags will appear in the order they are specified in this list.  Note that an item's release tag will always reported; this behavior cannot be overridden.",
+					"type": "object",
+					"patternProperties": {
+						"^@[^\\s]*$": {
+							"type": "boolean"
+						}
+					},
+					"additionalProperties": false
 				}
 			},
 			"required": ["enabled"],
@@ -110,6 +138,14 @@
 				"projectFolderUrl": {
 					"description": "The base URL where the project's source code can be viewed on a website such as GitHub or Azure DevOps. This URL path corresponds to the `<projectFolder>` path on disk. This URL is concatenated with the file paths serialized to the doc model to produce URL file paths to individual API items. For example, if the `projectFolderUrl` is \"https://github.com/microsoft/rushstack/tree/main/apps/api-extractor\" and an API item's file path is \"api/ExtractorConfig.ts\", the full URL file path would be \"https://github.com/microsoft/rushstack/tree/main/apps/api-extractor/api/ExtractorConfig.js\". Can be omitted if you don't need source code links in your API documentation reference.",
 					"type": "string"
+				},
+				"releaseTagsToTrim": {
+					"description": "Specifies a list of release tags that will be trimmed from the doc model. The default value is `[\"@internal\"]`.",
+					"type": "array",
+					"items": {
+						"enum": ["@internal", "@alpha", "@beta", "@public"]
+					},
+					"uniqueItems": true
 				}
 			},
 			"required": ["enabled"],