build(api-markdown-documenter): Build and output ESM (only) (#20096)

Updates the package to target ESM (exclusively) instead of CommonJS.

Since this package is an internal build tool, it's safe to make this
change, and will allow future updates which leverage ESM-only libraries.

Used `ts2esm` to translate imports.

Author: Josmithr

tools/api-markdown-documenter/.gitignore

@@ -1,5 +1,6 @@
 # Build output
 dist
+lib
 *.tsbuildinfo
 
 # npm dependencies

tools/api-markdown-documenter/.prettierignore

@@ -3,6 +3,7 @@ package-lock.json
 
 # Build output
 dist/*
+lib/*
 
 # Test output
 src/**/test/snapshots/*

tools/api-markdown-documenter/CHANGELOG.md

@@ -2,13 +2,16 @@
 
 ## 0.14.0
 
+-   Updated the package to emit ESM only.
 -   Fixed a bug where [inline tags](https://tsdoc.org/pages/spec/tag_kinds/#inline-tags) (other than `{@link}` and `{@inheritDoc}`, which are handled specially by API-Extractor) were not handled and resulted in errors being logged to the console.
     Such tags are now handled in the following way:
     -   [{@label}](https://tsdoc.org/pages/tags/label/) tags are simply omitted from the output (they are intended as metadata, not documentation content).
     -   Other custom inline tags are emitted as italicized text.
 
 ### ⚠ BREAKING CHANGES
 
+-   The package now outputs ESM only.
+    Consumers will have to migrate accordingly.
 -   `DocumentationNode` now has a required `isEmpty` property.
     Implementations will need to provide this.
 

tools/api-markdown-documenter/api-extractor.json

@@ -1,4 +1,8 @@
 {
 	"$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.primary.json",
+	"tsdocMetadata": {
+		"enabled": true,
+		"tsdocMetadataFilePath": "<projectFolder>/lib/tsdoc-metadata.json"
+	}
 }

tools/api-markdown-documenter/package.json

@@ -11,8 +11,17 @@
 	"license": "MIT",
 	"author": "Microsoft and contributors",
 	"sideEffects": false,
-	"main": "dist/index.js",
-	"types": "dist/index.d.ts",
+	"type": "module",
+	"exports": {
+		".": {
+			"import": "./lib/index.js",
+			"types": "./lib/api-markdown-documenter-public.d.ts"
+		},
+		"./beta": {
+			"import": "./lib/index.js",
+			"types": "./lib/api-markdown-documenter-beta.d.ts"
+		}
+	},
 	"scripts": {
 		"api": "fluid-build . --task api",
 		"build": "concurrently npm:build:compile npm:lint && npm run build:readme && npm run build:docs",
@@ -23,7 +32,7 @@
 		"build:tsc": "npm run tsc",
 		"check:release-tags": "api-extractor run --local --config ./api-extractor-lint.json",
 		"ci:build:docs": "api-extractor run && copyfiles -u 1 \"./_api-extractor-temp/doc-models/*\" ../../_api-extractor-temp/",
-		"clean": "rimraf --glob _api-extractor-temp nyc dist \"**/*.tsbuildinfo\" \"**/*.build.log\"",
+		"clean": "rimraf --glob _api-extractor-temp nyc dist lib \"**/*.tsbuildinfo\" \"**/*.build.log\"",
 		"eslint": "eslint src",
 		"eslint:fix": "eslint src --fix",
 		"format": "npm run prettier:fix",
@@ -37,7 +46,7 @@
 		"rebuild": "npm run clean && npm run build",
 		"test": "npm run test:mocha",
 		"test:coverage": "c8 npm test:mocha",
-		"test:mocha": "mocha \"dist/**/test/**/*.test.js\" --reporter-option maxDiffSize=100000",
+		"test:mocha": "mocha \"lib/**/test/**/*.test.js\" --reporter-option maxDiffSize=100000",
 		"test:mocha:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:mocha",
 		"test:verbose": "npm run test:mocha:verbose",
 		"tsc": "tsc"
@@ -47,12 +56,12 @@
 		"cache-dir": "nyc/.cache",
 		"exclude": [
 			"src/**/test/**/*.*ts",
-			"dist/**/test/**/*.*js"
+			"lib/**/test/**/*.*js"
 		],
 		"exclude-after-remap": false,
 		"include": [
 			"src/**/*.*ts",
-			"dist/**/*.*js"
+			"lib/**/*.*js"
 		],
 		"report-dir": "nyc/report",
 		"reporter": [

tools/api-markdown-documenter/src/ApiItemUtilitiesModule.ts

@@ -13,7 +13,7 @@ export {
 	getHeadingForApiItem,
 	getLinkForApiItem,
 	shouldItemBeIncluded,
-} from "./api-item-transforms";
+} from "./api-item-transforms/index.js";
 export {
 	getDefaultValueBlock,
 	getDeprecatedBlock,
@@ -29,4 +29,4 @@ export {
 	isOptional,
 	isReadonly,
 	isStatic,
-} from "./utilities";
+} from "./utilities/index.js";

tools/api-markdown-documenter/src/ConfigurationBase.ts

@@ -2,7 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { type Logger } from "./Logging";
+import { type Logger } from "./Logging.js";
 
 /**
  * Common base interface for configuration interfaces.

tools/api-markdown-documenter/src/HtmlRendererModule.ts

@@ -10,9 +10,9 @@
 export {
 	renderApiModelAsHtml as renderApiModel,
 	renderDocumentsAsHtml as renderDocuments,
-} from "./RenderHtml";
+} from "./RenderHtml.js";
 export {
 	renderDocumentAsHtml as renderDocument,
 	renderNodeAsHtml as renderNode,
 	renderNodesAsHtml as renderNodes,
-} from "./renderers";
+} from "./renderers/index.js";

tools/api-markdown-documenter/src/LayoutUtilitiesModule.ts

@@ -20,4 +20,4 @@ export {
 	createSummaryParagraph,
 	createThrowsSection,
 	createTypeParametersSection,
-} from "./api-item-transforms";
+} from "./api-item-transforms/index.js";

tools/api-markdown-documenter/src/LoadModel.ts

@@ -14,7 +14,7 @@ import {
 import { type DocComment, type DocInheritDocTag } from "@microsoft/tsdoc";
 import { FileSystem } from "@rushstack/node-core-library";
 
-import { type Logger } from "./Logging";
+import { type Logger } from "./Logging.js";
 
 /**
  * Reads API reports generated by {@link https://api-extractor.com/ | API-Extractor} (.api.json files)

tools/api-markdown-documenter/src/MarkdownRendererModule.ts

@@ -10,9 +10,9 @@
 export {
 	renderApiModelAsMarkdown as renderApiModel,
 	renderDocumentsAsMarkdown as renderDocuments,
-} from "./RenderMarkdown";
+} from "./RenderMarkdown.js";
 export {
 	renderDocumentAsMarkdown as renderDocument,
 	renderNodeAsMarkdown as renderNode,
 	renderNodesAsMarkdown as renderNodes,
-} from "./renderers";
+} from "./renderers/index.js";

tools/api-markdown-documenter/src/RenderHtml.ts

@@ -6,11 +6,14 @@ import * as Path from "node:path";
 
 import { FileSystem, NewlineKind } from "@rushstack/node-core-library";
 
-import { type ApiItemTransformationConfiguration, transformApiModel } from "./api-item-transforms";
-import { type DocumentNode } from "./documentation-domain";
-import { type Logger } from "./Logging";
-import { type HtmlRenderConfiguration, renderDocumentAsHtml } from "./renderers";
-import { type FileSystemConfiguration } from "./FileSystemConfiguration";
+import {
+	type ApiItemTransformationConfiguration,
+	transformApiModel,
+} from "./api-item-transforms/index.js";
+import { type DocumentNode } from "./documentation-domain/index.js";
+import { type Logger } from "./Logging.js";
+import { type HtmlRenderConfiguration, renderDocumentAsHtml } from "./renderers/index.js";
+import { type FileSystemConfiguration } from "./FileSystemConfiguration.js";
 
 /**
  * Renders the provided model and its contents, and writes each document to a file on disk.

tools/api-markdown-documenter/src/RenderMarkdown.ts

@@ -6,11 +6,14 @@ import * as Path from "node:path";
 
 import { FileSystem, NewlineKind } from "@rushstack/node-core-library";
 
-import { type ApiItemTransformationConfiguration, transformApiModel } from "./api-item-transforms";
-import { type DocumentNode } from "./documentation-domain";
-import { type Logger } from "./Logging";
-import { type MarkdownRenderConfiguration, renderDocumentAsMarkdown } from "./renderers";
-import { type FileSystemConfiguration } from "./FileSystemConfiguration";
+import {
+	type ApiItemTransformationConfiguration,
+	transformApiModel,
+} from "./api-item-transforms/index.js";
+import { type DocumentNode } from "./documentation-domain/index.js";
+import { type Logger } from "./Logging.js";
+import { type MarkdownRenderConfiguration, renderDocumentAsMarkdown } from "./renderers/index.js";
+import { type FileSystemConfiguration } from "./FileSystemConfiguration.js";
 
 /**
  * Renders the provided model and its contents, and writes each document to a file on disk.

tools/api-markdown-documenter/src/api-item-transforms/ApiItemTransformUtilities.ts

@@ -6,14 +6,14 @@ import * as Path from "node:path";
 
 import { type ApiItem, ApiItemKind, ReleaseTag } from "@microsoft/api-extractor-model";
 
-import { type Heading } from "../Heading";
-import { type Link } from "../Link";
-import { getQualifiedApiItemName, getReleaseTag } from "../utilities";
+import { type Heading } from "../Heading.js";
+import { type Link } from "../Link.js";
+import { getQualifiedApiItemName, getReleaseTag } from "../utilities/index.js";
 import {
 	type ApiItemTransformationConfiguration,
 	type DocumentBoundaries,
 	type HierarchyBoundaries,
-} from "./configuration";
+} from "./configuration/index.js";
 
 /**
  * This module contains `ApiItem`-related utilities for use in transformation logic.

tools/api-markdown-documenter/src/api-item-transforms/TransformApiItem.ts

@@ -22,11 +22,11 @@ import {
 	type ApiVariable,
 } from "@microsoft/api-extractor-model";
 
-import { type DocumentNode, type SectionNode } from "../documentation-domain";
-import { doesItemRequireOwnDocument, shouldItemBeIncluded } from "./ApiItemTransformUtilities";
-import { createDocument } from "./Utilities";
-import { type ApiItemTransformationConfiguration } from "./configuration";
-import { createBreadcrumbParagraph, wrapInSection } from "./helpers";
+import { type DocumentNode, type SectionNode } from "../documentation-domain/index.js";
+import { doesItemRequireOwnDocument, shouldItemBeIncluded } from "./ApiItemTransformUtilities.js";
+import { createDocument } from "./Utilities.js";
+import { type ApiItemTransformationConfiguration } from "./configuration/index.js";
+import { createBreadcrumbParagraph, wrapInSection } from "./helpers/index.js";
 
 /**
  * Creates a {@link DocumentNode} for the specified `apiItem`.

tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts

@@ -9,15 +9,15 @@ import {
 	type ApiPackage,
 } from "@microsoft/api-extractor-model";
 
-import { type DocumentNode, type SectionNode } from "../documentation-domain";
-import { createDocument } from "./Utilities";
+import { type DocumentNode, type SectionNode } from "../documentation-domain/index.js";
+import { createDocument } from "./Utilities.js";
 import {
 	type ApiItemTransformationConfiguration,
 	getApiItemTransformationConfigurationWithDefaults,
-} from "./configuration";
-import { doesItemRequireOwnDocument, shouldItemBeIncluded } from "./ApiItemTransformUtilities";
-import { createBreadcrumbParagraph, createEntryPointList, wrapInSection } from "./helpers";
-import { apiItemToDocument, apiItemToSections } from "./TransformApiItem";
+} from "./configuration/index.js";
+import { doesItemRequireOwnDocument, shouldItemBeIncluded } from "./ApiItemTransformUtilities.js";
+import { createBreadcrumbParagraph, createEntryPointList, wrapInSection } from "./helpers/index.js";
+import { apiItemToDocument, apiItemToSections } from "./TransformApiItem.js";
 
 /**
  * Renders the provided model and its contents to a series of {@link DocumentNode}s.

tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts

@@ -19,7 +19,7 @@ import {
 	type DocInlineTag,
 } from "@microsoft/tsdoc";
 
-import { type Link } from "../Link";
+import { type Link } from "../Link.js";
 import {
 	CodeSpanNode,
 	type DocumentationNode,
@@ -32,10 +32,10 @@ import {
 	type SingleLineDocumentationNode,
 	SingleLineSpanNode,
 	SpanNode,
-} from "../documentation-domain";
-import { type ConfigurationBase } from "../ConfigurationBase";
-import { getTsdocNodeTransformationOptions } from "./Utilities";
-import { type ApiItemTransformationConfiguration } from "./configuration";
+} from "../documentation-domain/index.js";
+import { type ConfigurationBase } from "../ConfigurationBase.js";
+import { getTsdocNodeTransformationOptions } from "./Utilities.js";
+import { type ApiItemTransformationConfiguration } from "./configuration/index.js";
 
 /**
  * Library of transformations from {@link https://github.com/microsoft/tsdoc/blob/main/tsdoc/src/nodes/DocNode.ts| DocNode}s

tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts

@@ -10,12 +10,12 @@ import {
 } from "@microsoft/api-extractor-model";
 import { type DocDeclarationReference } from "@microsoft/tsdoc";
 
-import { DocumentNode, type SectionNode } from "../documentation-domain";
-import { type Link } from "../Link";
-import { getDocumentPathForApiItem, getLinkForApiItem } from "./ApiItemTransformUtilities";
-import { type TsdocNodeTransformOptions } from "./TsdocNodeTransforms";
-import { type ApiItemTransformationConfiguration } from "./configuration";
-import { wrapInSection } from "./helpers";
+import { DocumentNode, type SectionNode } from "../documentation-domain/index.js";
+import { type Link } from "../Link.js";
+import { getDocumentPathForApiItem, getLinkForApiItem } from "./ApiItemTransformUtilities.js";
+import { type TsdocNodeTransformOptions } from "./TsdocNodeTransforms.js";
+import { type ApiItemTransformationConfiguration } from "./configuration/index.js";
+import { wrapInSection } from "./helpers/index.js";
 
 /**
  * Creates a {@link DocumentNode} representing the provided API item.

tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts

@@ -4,16 +4,16 @@
  */
 import { type ApiModel } from "@microsoft/api-extractor-model";
 
-import { type ConfigurationBase } from "../../ConfigurationBase";
-import { defaultConsoleLogger } from "../../Logging";
+import { type ConfigurationBase } from "../../ConfigurationBase.js";
+import { defaultConsoleLogger } from "../../Logging.js";
 import {
 	type DocumentationSuiteOptions,
 	getDocumentationSuiteOptionsWithDefaults,
-} from "./DocumentationSuiteOptions";
+} from "./DocumentationSuiteOptions.js";
 import {
 	type ApiItemTransformationOptions,
 	getApiItemTransformationOptionsWithDefaults,
-} from "./TransformationOptions";
+} from "./TransformationOptions.js";
 
 /**
  * API Item transformation configuration.

tools/api-markdown-documenter/src/api-item-transforms/configuration/DocumentationSuiteOptions.ts

@@ -19,7 +19,7 @@ import {
 	releaseTagToString,
 	getSafeFilenameForName,
 	getConciseSignature,
-} from "../../utilities";
+} from "../../utilities/index.js";
 
 /**
  * List of item kinds for which separate documents should be generated.

tools/api-markdown-documenter/src/api-item-transforms/configuration/TransformationOptions.ts

@@ -23,9 +23,9 @@ import {
 	type ApiVariable,
 } from "@microsoft/api-extractor-model";
 
-import { type SectionNode } from "../../documentation-domain";
-import * as DefaultTransformationImplementations from "../default-implementations";
-import { type ApiItemTransformationConfiguration } from "./Configuration";
+import { type SectionNode } from "../../documentation-domain/index.js";
+import * as DefaultTransformationImplementations from "../default-implementations/index.js";
+import { type ApiItemTransformationConfiguration } from "./Configuration.js";
 
 /**
  * Signature for a function which generates one or more {@link SectionNode}s describing an

tools/api-markdown-documenter/src/api-item-transforms/configuration/index.ts

@@ -6,18 +6,18 @@
 export {
 	type ApiItemTransformationConfiguration,
 	getApiItemTransformationConfigurationWithDefaults,
-} from "./Configuration";
+} from "./Configuration.js";
 export {
 	// Consumers should not use this, it exists externally for documentation purposes only.
 	type DefaultDocumentationSuiteOptions,
 	type DocumentBoundaries,
 	type DocumentationSuiteOptions,
 	getDocumentationSuiteOptionsWithDefaults,
 	type HierarchyBoundaries,
-} from "./DocumentationSuiteOptions";
+} from "./DocumentationSuiteOptions.js";
 export {
 	type ApiItemTransformationOptions,
 	getApiItemTransformationOptionsWithDefaults,
 	type TransformApiItemWithChildren,
 	type TransformApiItemWithoutChildren,
-} from "./TransformationOptions";
+} from "./TransformationOptions.js";

tools/api-markdown-documenter/src/api-item-transforms/default-implementations/CreateDefaultLayout.ts

@@ -4,9 +4,9 @@
  */
 import { type ApiItem, ReleaseTag } from "@microsoft/api-extractor-model";
 
-import { type SectionNode } from "../../documentation-domain";
-import { doesItemRequireOwnDocument, getHeadingForApiItem } from "../ApiItemTransformUtilities";
-import { type ApiItemTransformationConfiguration } from "../configuration";
+import { type SectionNode } from "../../documentation-domain/index.js";
+import { doesItemRequireOwnDocument, getHeadingForApiItem } from "../ApiItemTransformUtilities.js";
+import { type ApiItemTransformationConfiguration } from "../configuration/index.js";
 import {
 	alphaWarningSpan,
 	betaWarningSpan,
@@ -18,8 +18,8 @@ import {
 	createSummaryParagraph,
 	createThrowsSection,
 	wrapInSection,
-} from "../helpers";
-import { getReleaseTag } from "../../utilities";
+} from "../helpers/index.js";
+import { getReleaseTag } from "../../utilities/index.js";
 
 /**
  * Default content layout for all API items.