build: separate legacy/no-legacy api-extractor configs (#21448)

- packages without /legacy exports use
api-extractor-base.*.no-legacy.json
- packages with /legacy exports use api-extractor-base.esm.cuurent.json

api-extractor-base.*.primary.json are replaced.
 - cjs version is exactly .csj.no-legacy.json.
- esm version is now .esm.json but is used via .esm.no-legacy.json or
.esm.current.json.

The few direct references to api-extractor-base.json are replaced with
one of the new three files. api-extractor-base.json no longer specifies
reportVariants as api-extractor config inheritance does not handle array
overrides well.

Future: .esm.legacy.json will be added for packages with /legacy exports
and handle those APIs specifically.

Author: jason-ha

azure/packages/azure-service-utils/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

common/build/build-common/README.md

@@ -3,7 +3,8 @@
 	"extends": "./api-extractor-base.json",
 	"mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
 	"apiReport": {
-		"enabled": true
+		"enabled": true,
+		"reportVariants": ["public", "beta", "alpha"] // TODO: add "complete"?
 	},
 	// API-Extractor uses the presence of this file in an npm package to determine whether or not its API members
 	// should be considered when making decisions about reports and rollups in consuming packages.

common/build/build-common/api-extractor-base.cjs.primary.json renamed to common/build/build-common/api-extractor-base.cjs.no-legacy.json

@@ -0,0 +1,7 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "./api-extractor-base.esm.json",
+	"apiReport": {
+		"reportVariants": ["public", "beta", "alpha"] // TODO: add "complete"?
+	}
+}

common/build/build-common/api-extractor-base.esm.current.json

@@ -0,0 +1,7 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "./api-extractor-base.esm.json",
+	"apiReport": {
+		"reportVariants": ["public", "beta", "alpha"] // TODO: add "complete"?
+	}
+}

common/build/build-common/api-extractor-base.esm.primary.json renamed to common/build/build-common/api-extractor-base.esm.json

@@ -20,8 +20,11 @@
 		"enabled": true,
 		"reportFileName": "<unscopedPackageName>",
 		"reportFolder": "<projectFolder>/api-report/",
-		"reportTempFolder": "<projectFolder>/_api-extractor-temp/",
-		"reportVariants": ["public", "beta", "alpha"] // TODO: add "complete"?
+		"reportTempFolder": "<projectFolder>/_api-extractor-temp/"
+		// https://github.com/microsoft/rushstack/issues/4786 requires the derived configs
+		// to have the same length reportVariants or longer. Otherwise, later array entries
+		// bleed thru. So reportVariants should only be set in derived configs.
+		// "reportVariants": set-in-derived-configs
 	},
 
 	/**

common/build/build-common/api-extractor-base.esm.no-legacy.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../build/build-common/api-extractor-base.json"
+	"extends": "../../build/build-common/api-extractor-base.cjs.no-legacy.json"
 }

common/build/build-common/api-extractor-base.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

common/lib/common-utils/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

common/lib/protocol-definitions/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

examples/utils/example-utils/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

experimental/PropertyDDS/packages/property-dds/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

experimental/dds/attributable-map/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

experimental/dds/ot/ot/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

experimental/dds/ot/sharejs/json1/api-extractor.json

@@ -1,6 +1,6 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.json",
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json",
 	"apiReport": {
 		"enabled": true,
 		// Note: `tree.api.md` is the file used for the upcoming tree DDS's API report.

experimental/dds/sequence-deprecated/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

experimental/dds/tree/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

experimental/framework/data-objects/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

experimental/framework/last-edited/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

experimental/framework/tree-react-api/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/common/client-utils/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/common/container-definitions/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/common/core-interfaces/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/common/core-utils/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

packages/common/driver-definitions/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/dds/cell/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

packages/dds/counter/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/dds/ink/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/dds/map/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/dds/matrix/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/dds/merge-tree/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

packages/dds/ordered-collection/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/dds/pact-map/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/dds/register-collection/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/dds/sequence/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/dds/shared-object-base/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/dds/shared-summary-block/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

packages/dds/task-manager/api-extractor.json

@@ -1,6 +1,6 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json",
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json",
 	"compiler": {
 		// api-extractor has trouble with Node16 moduleResolution, but Bundler looks okay.
 		"overrideTsconfig": {

packages/dds/test-dds-utils/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/dds/tree/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

packages/drivers/debugger/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/drivers/driver-base/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

packages/drivers/driver-web-cache/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/drivers/file-driver/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/drivers/local-driver/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/drivers/odsp-driver-definitions/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

packages/drivers/odsp-driver/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

packages/drivers/odsp-urlResolver/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/drivers/replay-driver/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

packages/drivers/routerlicious-driver/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

packages/drivers/routerlicious-urlResolver/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/drivers/tinylicious-driver/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.current.json"
 }

packages/framework/agent-scheduler/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

packages/framework/aqueduct/api-extractor.json

@@ -1,6 +1,6 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../../common/build/build-common/api-extractor-base.esm.primary.json",
+	"extends": "../../../../common/build/build-common/api-extractor-base.esm.no-legacy.json",
 	"messages": {
 		// The following overrides are workarounds for API-Extractor incorrectly running analysis on our application
 		// insights dependency.

packages/framework/attributor/api-extractor.json

@@ -1,6 +1,6 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../../common/build/build-common/api-extractor-base.esm.primary.json",
+	"extends": "../../../../common/build/build-common/api-extractor-base.esm.current.json",
 	"messages": {
 		// The following overrides are workarounds for API-Extractor incorrectly running analysis on our application
 		// insights dependency.

packages/framework/client-logger/app-insights-logger/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }

packages/framework/client-logger/fluid-telemetry/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.no-legacy.json"
 }