@microsoft/api-documenter 7.28.9 → 7.29.1

package/CHANGELOG.json

@@ -1,6 +1,64 @@
 {
   "name": "@microsoft/api-documenter",
   "entries": [
+    {
+      "version": "7.29.1",
+      "tag": "@microsoft/api-documenter_v7.29.1",
+      "date": "Fri, 20 Feb 2026 00:15:03 GMT",
+      "comments": {
+        "patch": [
+          {
+            "comment": "Add `\"node\"` condition before `\"import\"` in the `\"exports\"` map so that Node.js uses the CJS output (which handles extensionless imports), while bundlers still use ESM via `\"import\"`. Fixes https://github.com/microsoft/rushstack/issues/5644."
+          }
+        ],
+        "dependency": [
+          {
+            "comment": "Updating dependency \"@microsoft/api-extractor-model\" to `7.33.1`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/node-core-library\" to `5.20.1`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/terminal\" to `0.22.1`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/ts-command-line\" to `5.3.1`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/heft\" to `1.2.1`"
+          }
+        ]
+      }
+    },
+    {
+      "version": "7.29.0",
+      "tag": "@microsoft/api-documenter_v7.29.0",
+      "date": "Thu, 19 Feb 2026 00:04:52 GMT",
+      "comments": {
+        "minor": [
+          {
+            "comment": "Normalize package layout. CommonJS is now under `lib-commonjs`, DTS is now under `lib-dts`, and ESM is now under `lib-esm`. Imports to `lib` still work as before, handled by the `\"exports\"` field in `package.json`."
+          }
+        ],
+        "dependency": [
+          {
+            "comment": "Updating dependency \"@microsoft/api-extractor-model\" to `7.33.0`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/node-core-library\" to `5.20.0`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/terminal\" to `0.22.0`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/ts-command-line\" to `5.3.0`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/heft\" to `1.2.0`"
+          }
+        ]
+      }
+    },
     {
       "version": "7.28.9",
       "tag": "@microsoft/api-documenter_v7.28.9",

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Change Log - @microsoft/api-documenter
 
-This log was last generated on Sat, 07 Feb 2026 01:13:26 GMT and should not be manually modified.
+This log was last generated on Fri, 20 Feb 2026 00:15:03 GMT and should not be manually modified.
+
+## 7.29.1
+Fri, 20 Feb 2026 00:15:03 GMT
+
+### Patches
+
+- Add `"node"` condition before `"import"` in the `"exports"` map so that Node.js uses the CJS output (which handles extensionless imports), while bundlers still use ESM via `"import"`. Fixes https://github.com/microsoft/rushstack/issues/5644.
+
+## 7.29.0
+Thu, 19 Feb 2026 00:04:52 GMT
+
+### Minor changes
+
+- Normalize package layout. CommonJS is now under `lib-commonjs`, DTS is now under `lib-dts`, and ESM is now under `lib-esm`. Imports to `lib` still work as before, handled by the `"exports"` field in `package.json`.
 
 ## 7.28.9
 Sat, 07 Feb 2026 01:13:26 GMT

package/bin/api-documenter

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-require('../lib/start.js');
+require('../lib-commonjs/start.js');

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.56.2"
+      "packageVersion": "7.57.0"
     }
   ]
 }

package/lib-esm/cli/ApiDocumenterCommandLine.js

@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { CommandLineParser } from '@rushstack/ts-command-line';
+import { MarkdownAction } from './MarkdownAction';
+import { YamlAction } from './YamlAction';
+import { GenerateAction } from './GenerateAction';
+export class ApiDocumenterCommandLine extends CommandLineParser {
+    constructor() {
+        super({
+            toolFilename: 'api-documenter',
+            toolDescription: 'Reads *.api.json files produced by api-extractor, ' +
+                ' and generates API documentation in various output formats.'
+        });
+        this._populateActions();
+    }
+    _populateActions() {
+        this.addAction(new MarkdownAction(this));
+        this.addAction(new YamlAction(this));
+        this.addAction(new GenerateAction(this));
+    }
+}
+//# sourceMappingURL=ApiDocumenterCommandLine.js.map

package/lib-esm/cli/ApiDocumenterCommandLine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiDocumenterCommandLine.js","sourceRoot":"","sources":["../../src/cli/ApiDocumenterCommandLine.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAE/D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,OAAO,wBAAyB,SAAQ,iBAAiB;IAC7D;QACE,KAAK,CAAC;YACJ,YAAY,EAAE,gBAAgB;YAC9B,eAAe,EACb,oDAAoD;gBACpD,6DAA6D;SAChE,CAAC,CAAC;QACH,IAAI,CAAC,gBAAgB,EAAE,CAAC;IAC1B,CAAC;IAEO,gBAAgB;QACtB,IAAI,CAAC,SAAS,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,IAAI,CAAC,SAAS,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;QACrC,IAAI,CAAC,SAAS,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3C,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport { CommandLineParser } from '@rushstack/ts-command-line';\n\nimport { MarkdownAction } from './MarkdownAction';\nimport { YamlAction } from './YamlAction';\nimport { GenerateAction } from './GenerateAction';\n\nexport class ApiDocumenterCommandLine extends CommandLineParser {\n  public constructor() {\n    super({\n      toolFilename: 'api-documenter',\n      toolDescription:\n        'Reads *.api.json files produced by api-extractor, ' +\n        ' and generates API documentation in various output formats.'\n    });\n    this._populateActions();\n  }\n\n  private _populateActions(): void {\n    this.addAction(new MarkdownAction(this));\n    this.addAction(new YamlAction(this));\n    this.addAction(new GenerateAction(this));\n  }\n}\n"]}

package/lib-esm/cli/BaseAction.js

@@ -0,0 +1,93 @@
+// 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 { CommandLineAction } from '@rushstack/ts-command-line';
+import { FileSystem } from '@rushstack/node-core-library';
+import { ApiModel, ApiItemContainerMixin, ApiDocumentedItem } from '@microsoft/api-extractor-model';
+import { Colorize } from '@rushstack/terminal';
+export class BaseAction extends CommandLineAction {
+    constructor(options) {
+        super(options);
+        this._inputFolderParameter = this.defineStringParameter({
+            parameterLongName: '--input-folder',
+            parameterShortName: '-i',
+            argumentName: 'FOLDER1',
+            description: `Specifies the input folder containing the *.api.json files to be processed.` +
+                ` If omitted, the default is "./input"`
+        });
+        this._outputFolderParameter = this.defineStringParameter({
+            parameterLongName: '--output-folder',
+            parameterShortName: '-o',
+            argumentName: 'FOLDER2',
+            description: `Specifies the output folder where the documentation will be written.` +
+                ` ANY EXISTING CONTENTS WILL BE DELETED!` +
+                ` If omitted, the default is "./${this.actionName}"`
+        });
+    }
+    buildApiModel() {
+        const apiModel = new ApiModel();
+        const inputFolder = this._inputFolderParameter.value || './input';
+        if (!FileSystem.exists(inputFolder)) {
+            throw new Error('The input folder does not exist: ' + inputFolder);
+        }
+        const outputFolder = this._outputFolderParameter.value || `./${this.actionName}`;
+        FileSystem.ensureFolder(outputFolder);
+        for (const filename of FileSystem.readFolderItemNames(inputFolder)) {
+            if (filename.match(/\.api\.json$/i)) {
+                console.log(`Reading ${filename}`);
+                const filenamePath = path.join(inputFolder, filename);
+                apiModel.loadPackage(filenamePath);
+            }
+        }
+        this._applyInheritDoc(apiModel, apiModel);
+        return { apiModel, inputFolder, outputFolder };
+    }
+    // TODO: This is a temporary workaround.  The long term plan is for API Extractor's DocCommentEnhancer
+    // to apply all @inheritDoc tags before the .api.json file is written.
+    // See DocCommentEnhancer._applyInheritDoc() for more info.
+    _applyInheritDoc(apiItem, apiModel) {
+        if (apiItem instanceof ApiDocumentedItem) {
+            if (apiItem.tsdocComment) {
+                const inheritDocTag = apiItem.tsdocComment.inheritDocTag;
+                if (inheritDocTag && inheritDocTag.declarationReference) {
+                    // Attempt to resolve the declaration reference
+                    const result = apiModel.resolveDeclarationReference(inheritDocTag.declarationReference, apiItem);
+                    if (result.errorMessage) {
+                        console.log(Colorize.yellow(`Warning: Unresolved @inheritDoc tag for ${apiItem.displayName}: ` + result.errorMessage));
+                    }
+                    else {
+                        if (result.resolvedApiItem instanceof ApiDocumentedItem &&
+                            result.resolvedApiItem.tsdocComment &&
+                            result.resolvedApiItem !== apiItem) {
+                            this._copyInheritedDocs(apiItem.tsdocComment, result.resolvedApiItem.tsdocComment);
+                        }
+                    }
+                }
+            }
+        }
+        // Recurse members
+        if (ApiItemContainerMixin.isBaseClassOf(apiItem)) {
+            for (const member of apiItem.members) {
+                this._applyInheritDoc(member, apiModel);
+            }
+        }
+    }
+    /**
+     * Copy the content from `sourceDocComment` to `targetDocComment`.
+     * This code is borrowed from DocCommentEnhancer as a temporary workaround.
+     */
+    _copyInheritedDocs(targetDocComment, sourceDocComment) {
+        targetDocComment.summarySection = sourceDocComment.summarySection;
+        targetDocComment.remarksBlock = sourceDocComment.remarksBlock;
+        targetDocComment.params.clear();
+        for (const param of sourceDocComment.params) {
+            targetDocComment.params.add(param);
+        }
+        for (const typeParam of sourceDocComment.typeParams) {
+            targetDocComment.typeParams.add(typeParam);
+        }
+        targetDocComment.returnsBlock = sourceDocComment.returnsBlock;
+        targetDocComment.inheritDocTag = undefined;
+    }
+}
+//# sourceMappingURL=BaseAction.js.map

package/lib-esm/cli/BaseAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseAction.js","sourceRoot":"","sources":["../../src/cli/BaseAction.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport * as path from 'node:path';\n\nimport type * as tsdoc from '@microsoft/tsdoc';\nimport {\n  CommandLineAction,\n  type CommandLineStringParameter,\n  type ICommandLineActionOptions\n} from '@rushstack/ts-command-line';\nimport { FileSystem } from '@rushstack/node-core-library';\nimport {\n  ApiModel,\n  type ApiItem,\n  ApiItemContainerMixin,\n  ApiDocumentedItem,\n  type IResolveDeclarationReferenceResult\n} from '@microsoft/api-extractor-model';\nimport { Colorize } from '@rushstack/terminal';\n\nexport interface IBuildApiModelResult {\n  apiModel: ApiModel;\n  inputFolder: string;\n  outputFolder: string;\n}\n\nexport abstract class BaseAction extends CommandLineAction {\n  private readonly _inputFolderParameter: CommandLineStringParameter;\n  private readonly _outputFolderParameter: CommandLineStringParameter;\n\n  protected constructor(options: ICommandLineActionOptions) {\n    super(options);\n\n    this._inputFolderParameter = this.defineStringParameter({\n      parameterLongName: '--input-folder',\n      parameterShortName: '-i',\n      argumentName: 'FOLDER1',\n      description:\n        `Specifies the input folder containing the *.api.json files to be processed.` +\n        ` If omitted, the default is \"./input\"`\n    });\n\n    this._outputFolderParameter = this.defineStringParameter({\n      parameterLongName: '--output-folder',\n      parameterShortName: '-o',\n      argumentName: 'FOLDER2',\n      description:\n        `Specifies the output folder where the documentation will be written.` +\n        ` ANY EXISTING CONTENTS WILL BE DELETED!` +\n        ` If omitted, the default is \"./${this.actionName}\"`\n    });\n  }\n\n  protected buildApiModel(): IBuildApiModelResult {\n    const apiModel: ApiModel = new ApiModel();\n\n    const inputFolder: string = this._inputFolderParameter.value || './input';\n    if (!FileSystem.exists(inputFolder)) {\n      throw new Error('The input folder does not exist: ' + inputFolder);\n    }\n\n    const outputFolder: string = this._outputFolderParameter.value || `./${this.actionName}`;\n    FileSystem.ensureFolder(outputFolder);\n\n    for (const filename of FileSystem.readFolderItemNames(inputFolder)) {\n      if (filename.match(/\\.api\\.json$/i)) {\n        console.log(`Reading ${filename}`);\n        const filenamePath: string = path.join(inputFolder, filename);\n        apiModel.loadPackage(filenamePath);\n      }\n    }\n\n    this._applyInheritDoc(apiModel, apiModel);\n\n    return { apiModel, inputFolder, outputFolder };\n  }\n\n  // TODO: This is a temporary workaround.  The long term plan is for API Extractor's DocCommentEnhancer\n  // to apply all @inheritDoc tags before the .api.json file is written.\n  // See DocCommentEnhancer._applyInheritDoc() for more info.\n  private _applyInheritDoc(apiItem: ApiItem, apiModel: ApiModel): void {\n    if (apiItem instanceof ApiDocumentedItem) {\n      if (apiItem.tsdocComment) {\n        const inheritDocTag: tsdoc.DocInheritDocTag | undefined = apiItem.tsdocComment.inheritDocTag;\n\n        if (inheritDocTag && inheritDocTag.declarationReference) {\n          // Attempt to resolve the declaration reference\n          const result: IResolveDeclarationReferenceResult = apiModel.resolveDeclarationReference(\n            inheritDocTag.declarationReference,\n            apiItem\n          );\n\n          if (result.errorMessage) {\n            console.log(\n              Colorize.yellow(\n                `Warning: Unresolved @inheritDoc tag for ${apiItem.displayName}: ` + result.errorMessage\n              )\n            );\n          } else {\n            if (\n              result.resolvedApiItem instanceof ApiDocumentedItem &&\n              result.resolvedApiItem.tsdocComment &&\n              result.resolvedApiItem !== apiItem\n            ) {\n              this._copyInheritedDocs(apiItem.tsdocComment, result.resolvedApiItem.tsdocComment);\n            }\n          }\n        }\n      }\n    }\n\n    // Recurse members\n    if (ApiItemContainerMixin.isBaseClassOf(apiItem)) {\n      for (const member of apiItem.members) {\n        this._applyInheritDoc(member, apiModel);\n      }\n    }\n  }\n\n  /**\n   * Copy the content from `sourceDocComment` to `targetDocComment`.\n   * This code is borrowed from DocCommentEnhancer as a temporary workaround.\n   */\n  private _copyInheritedDocs(targetDocComment: tsdoc.DocComment, sourceDocComment: tsdoc.DocComment): void {\n    targetDocComment.summarySection = sourceDocComment.summarySection;\n    targetDocComment.remarksBlock = sourceDocComment.remarksBlock;\n\n    targetDocComment.params.clear();\n    for (const param of sourceDocComment.params) {\n      targetDocComment.params.add(param);\n    }\n    for (const typeParam of sourceDocComment.typeParams) {\n      targetDocComment.typeParams.add(typeParam);\n    }\n    targetDocComment.returnsBlock = sourceDocComment.returnsBlock;\n\n    targetDocComment.inheritDocTag = undefined;\n  }\n}\n"]}

package/lib-esm/cli/GenerateAction.js

@@ -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 { BaseAction } from './BaseAction';
+import { DocumenterConfig } from '../documenters/DocumenterConfig';
+import { ExperimentalYamlDocumenter } from '../documenters/ExperimentalYamlDocumenter';
+import { MarkdownDocumenter } from '../documenters/MarkdownDocumenter';
+export class GenerateAction extends BaseAction {
+    constructor(parser) {
+        super({
+            actionName: 'generate',
+            summary: 'EXPERIMENTAL',
+            documentation: 'EXPERIMENTAL - This action is a prototype of a new config file driven mode of operation for' +
+                ' API Documenter.  It is not ready for general usage yet.  Its design may change in the future.'
+        });
+    }
+    async onExecuteAsync() {
+        // Look for the config file under the current folder
+        let configFilePath = path.join(process.cwd(), DocumenterConfig.FILENAME);
+        // First try the current folder
+        if (!FileSystem.exists(configFilePath)) {
+            // Otherwise try the standard "config" subfolder
+            configFilePath = path.join(process.cwd(), 'config', DocumenterConfig.FILENAME);
+            if (!FileSystem.exists(configFilePath)) {
+                throw new Error(`Unable to find ${DocumenterConfig.FILENAME} in the current folder or in a "config" subfolder`);
+            }
+        }
+        const documenterConfig = DocumenterConfig.loadFile(configFilePath);
+        const { apiModel, outputFolder } = this.buildApiModel();
+        if (documenterConfig.configFile.outputTarget === 'markdown') {
+            const markdownDocumenter = new MarkdownDocumenter({
+                apiModel,
+                documenterConfig,
+                outputFolder
+            });
+            markdownDocumenter.generateFiles();
+        }
+        else {
+            const yamlDocumenter = new ExperimentalYamlDocumenter(apiModel, documenterConfig);
+            yamlDocumenter.generateFiles(outputFolder);
+        }
+    }
+}
+//# sourceMappingURL=GenerateAction.js.map

package/lib-esm/cli/GenerateAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GenerateAction.js","sourceRoot":"","sources":["../../src/cli/GenerateAction.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAG1D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAEvE,MAAM,OAAO,cAAe,SAAQ,UAAU;IAC5C,YAAmB,MAAgC;QACjD,KAAK,CAAC;YACJ,UAAU,EAAE,UAAU;YACtB,OAAO,EAAE,cAAc;YACvB,aAAa,EACX,6FAA6F;gBAC7F,gGAAgG;SACnG,CAAC,CAAC;IACL,CAAC;IAEkB,KAAK,CAAC,cAAc;QACrC,oDAAoD;QAEpD,IAAI,cAAc,GAAW,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAEjF,+BAA+B;QAC/B,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;YACvC,gDAAgD;YAChD,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;YAC/E,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;gBACvC,MAAM,IAAI,KAAK,CACb,kBAAkB,gBAAgB,CAAC,QAAQ,mDAAmD,CAC/F,CAAC;YACJ,CAAC;QACH,CAAC;QAED,MAAM,gBAAgB,GAAqB,gBAAgB,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;QAErF,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QAExD,IAAI,gBAAgB,CAAC,UAAU,CAAC,YAAY,KAAK,UAAU,EAAE,CAAC;YAC5D,MAAM,kBAAkB,GAAuB,IAAI,kBAAkB,CAAC;gBACpE,QAAQ;gBACR,gBAAgB;gBAChB,YAAY;aACb,CAAC,CAAC;YACH,kBAAkB,CAAC,aAAa,EAAE,CAAC;QACrC,CAAC;aAAM,CAAC;YACN,MAAM,cAAc,GAA+B,IAAI,0BAA0B,CAC/E,QAAQ,EACR,gBAAgB,CACjB,CAAC;YACF,cAAc,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport * as path from 'node:path';\n\nimport { FileSystem } from '@rushstack/node-core-library';\n\nimport type { ApiDocumenterCommandLine } from './ApiDocumenterCommandLine';\nimport { BaseAction } from './BaseAction';\nimport { DocumenterConfig } from '../documenters/DocumenterConfig';\nimport { ExperimentalYamlDocumenter } from '../documenters/ExperimentalYamlDocumenter';\nimport { MarkdownDocumenter } from '../documenters/MarkdownDocumenter';\n\nexport class GenerateAction extends BaseAction {\n  public constructor(parser: ApiDocumenterCommandLine) {\n    super({\n      actionName: 'generate',\n      summary: 'EXPERIMENTAL',\n      documentation:\n        'EXPERIMENTAL - This action is a prototype of a new config file driven mode of operation for' +\n        ' API Documenter.  It is not ready for general usage yet.  Its design may change in the future.'\n    });\n  }\n\n  protected override async onExecuteAsync(): Promise<void> {\n    // Look for the config file under the current folder\n\n    let configFilePath: string = path.join(process.cwd(), DocumenterConfig.FILENAME);\n\n    // First try the current folder\n    if (!FileSystem.exists(configFilePath)) {\n      // Otherwise try the standard \"config\" subfolder\n      configFilePath = path.join(process.cwd(), 'config', DocumenterConfig.FILENAME);\n      if (!FileSystem.exists(configFilePath)) {\n        throw new Error(\n          `Unable to find ${DocumenterConfig.FILENAME} in the current folder or in a \"config\" subfolder`\n        );\n      }\n    }\n\n    const documenterConfig: DocumenterConfig = DocumenterConfig.loadFile(configFilePath);\n\n    const { apiModel, outputFolder } = this.buildApiModel();\n\n    if (documenterConfig.configFile.outputTarget === 'markdown') {\n      const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter({\n        apiModel,\n        documenterConfig,\n        outputFolder\n      });\n      markdownDocumenter.generateFiles();\n    } else {\n      const yamlDocumenter: ExperimentalYamlDocumenter = new ExperimentalYamlDocumenter(\n        apiModel,\n        documenterConfig\n      );\n      yamlDocumenter.generateFiles(outputFolder);\n    }\n  }\n}\n"]}

package/lib-esm/cli/MarkdownAction.js

@@ -0,0 +1,24 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { BaseAction } from './BaseAction';
+import { MarkdownDocumenter } from '../documenters/MarkdownDocumenter';
+export class MarkdownAction extends BaseAction {
+    constructor(parser) {
+        super({
+            actionName: 'markdown',
+            summary: 'Generate documentation as Markdown files (*.md)',
+            documentation: 'Generates API documentation as a collection of files in' +
+                ' Markdown format, suitable for example for publishing on a GitHub site.'
+        });
+    }
+    async onExecuteAsync() {
+        const { apiModel, outputFolder } = this.buildApiModel();
+        const markdownDocumenter = new MarkdownDocumenter({
+            apiModel,
+            documenterConfig: undefined,
+            outputFolder
+        });
+        markdownDocumenter.generateFiles();
+    }
+}
+//# sourceMappingURL=MarkdownAction.js.map

package/lib-esm/cli/MarkdownAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MarkdownAction.js","sourceRoot":"","sources":["../../src/cli/MarkdownAction.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAG3D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAEvE,MAAM,OAAO,cAAe,SAAQ,UAAU;IAC5C,YAAmB,MAAgC;QACjD,KAAK,CAAC;YACJ,UAAU,EAAE,UAAU;YACtB,OAAO,EAAE,iDAAiD;YAC1D,aAAa,EACX,yDAAyD;gBACzD,yEAAyE;SAC5E,CAAC,CAAC;IACL,CAAC;IAEkB,KAAK,CAAC,cAAc;QACrC,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QAExD,MAAM,kBAAkB,GAAuB,IAAI,kBAAkB,CAAC;YACpE,QAAQ;YACR,gBAAgB,EAAE,SAAS;YAC3B,YAAY;SACb,CAAC,CAAC;QACH,kBAAkB,CAAC,aAAa,EAAE,CAAC;IACrC,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport type { ApiDocumenterCommandLine } from './ApiDocumenterCommandLine';\nimport { BaseAction } from './BaseAction';\nimport { MarkdownDocumenter } from '../documenters/MarkdownDocumenter';\n\nexport class MarkdownAction extends BaseAction {\n  public constructor(parser: ApiDocumenterCommandLine) {\n    super({\n      actionName: 'markdown',\n      summary: 'Generate documentation as Markdown files (*.md)',\n      documentation:\n        'Generates API documentation as a collection of files in' +\n        ' Markdown format, suitable for example for publishing on a GitHub site.'\n    });\n  }\n\n  protected override async onExecuteAsync(): Promise<void> {\n    const { apiModel, outputFolder } = this.buildApiModel();\n\n    const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter({\n      apiModel,\n      documenterConfig: undefined,\n      outputFolder\n    });\n    markdownDocumenter.generateFiles();\n  }\n}\n"]}

package/lib-esm/cli/YamlAction.js

@@ -0,0 +1,43 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { BaseAction } from './BaseAction';
+import { YamlDocumenter } from '../documenters/YamlDocumenter';
+import { OfficeYamlDocumenter } from '../documenters/OfficeYamlDocumenter';
+export class YamlAction extends BaseAction {
+    constructor(parser) {
+        super({
+            actionName: 'yaml',
+            summary: 'Generate documentation as universal reference YAML files (*.yml)',
+            documentation: 'Generates API documentation as a collection of files conforming' +
+                ' to the universal reference YAML format, which is used by the docs.microsoft.com' +
+                ' pipeline.'
+        });
+        this._officeParameter = this.defineFlagParameter({
+            parameterLongName: '--office',
+            description: `Enables some additional features specific to Office Add-ins`
+        });
+        this._newDocfxNamespacesParameter = this.defineFlagParameter({
+            parameterLongName: '--new-docfx-namespaces',
+            description: `This enables an experimental feature that will be officially released with the next major version` +
+                ` of API Documenter.  It requires DocFX 2.46 or newer.  It enables documentation for namespaces and` +
+                ` adds them to the table of contents.  This will also affect file layout as namespaced items will be nested` +
+                ` under a directory for the namespace instead of just within the package.`
+        });
+        this._yamlFormatParameter = this.defineChoiceParameter({
+            parameterLongName: '--yaml-format',
+            alternatives: ['udp', 'sdp'],
+            defaultValue: 'sdp',
+            description: `Specifies the YAML format - udp or sdp. Universal Document Processor (udp) should be used if you generating` +
+                ` YAML files for DocFX 2.x. Schema Driven Processor (sdp) should be used with DocFX 3.x.` +
+                ` NOTE: This parameter is ignored if you use --office.`
+        });
+    }
+    async onExecuteAsync() {
+        const { apiModel, inputFolder, outputFolder } = this.buildApiModel();
+        const yamlDocumenter = this._officeParameter.value
+            ? new OfficeYamlDocumenter(apiModel, inputFolder, this._newDocfxNamespacesParameter.value)
+            : new YamlDocumenter(apiModel, this._newDocfxNamespacesParameter.value, this._yamlFormatParameter.value);
+        yamlDocumenter.generateFiles(outputFolder);
+    }
+}
+//# sourceMappingURL=YamlAction.js.map

package/lib-esm/cli/YamlAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"YamlAction.js","sourceRoot":"","sources":["../../src/cli/YamlAction.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAQ3D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAmB,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAE3E,MAAM,OAAO,UAAW,SAAQ,UAAU;IAKxC,YAAmB,MAAgC;QACjD,KAAK,CAAC;YACJ,UAAU,EAAE,MAAM;YAClB,OAAO,EAAE,kEAAkE;YAC3E,aAAa,EACX,iEAAiE;gBACjE,kFAAkF;gBAClF,YAAY;SACf,CAAC,CAAC;QAEH,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,mBAAmB,CAAC;YAC/C,iBAAiB,EAAE,UAAU;YAC7B,WAAW,EAAE,6DAA6D;SAC3E,CAAC,CAAC;QACH,IAAI,CAAC,4BAA4B,GAAG,IAAI,CAAC,mBAAmB,CAAC;YAC3D,iBAAiB,EAAE,wBAAwB;YAC3C,WAAW,EACT,mGAAmG;gBACnG,oGAAoG;gBACpG,4GAA4G;gBAC5G,0EAA0E;SAC7E,CAAC,CAAC;QACH,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC,qBAAqB,CAAa;YACjE,iBAAiB,EAAE,eAAe;YAClC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC;YAC5B,YAAY,EAAE,KAAK;YACnB,WAAW,EACT,6GAA6G;gBAC7G,yFAAyF;gBACzF,uDAAuD;SAC1D,CAAC,CAAC;IACL,CAAC;IAEkB,KAAK,CAAC,cAAc;QACrC,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QAErE,MAAM,cAAc,GAAmB,IAAI,CAAC,gBAAgB,CAAC,KAAK;YAChE,CAAC,CAAC,IAAI,oBAAoB,CAAC,QAAQ,EAAE,WAAW,EAAE,IAAI,CAAC,4BAA4B,CAAC,KAAK,CAAC;YAC1F,CAAC,CAAC,IAAI,cAAc,CAChB,QAAQ,EACR,IAAI,CAAC,4BAA4B,CAAC,KAAK,EACvC,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAChC,CAAC;QAEN,cAAc,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;IAC7C,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport type {\n  CommandLineFlagParameter,\n  IRequiredCommandLineChoiceParameter\n} from '@rushstack/ts-command-line';\n\nimport type { ApiDocumenterCommandLine } from './ApiDocumenterCommandLine';\nimport { BaseAction } from './BaseAction';\nimport { YamlDocumenter, type YamlFormat } from '../documenters/YamlDocumenter';\nimport { OfficeYamlDocumenter } from '../documenters/OfficeYamlDocumenter';\n\nexport class YamlAction extends BaseAction {\n  private readonly _officeParameter: CommandLineFlagParameter;\n  private readonly _newDocfxNamespacesParameter: CommandLineFlagParameter;\n  private readonly _yamlFormatParameter: IRequiredCommandLineChoiceParameter<YamlFormat>;\n\n  public constructor(parser: ApiDocumenterCommandLine) {\n    super({\n      actionName: 'yaml',\n      summary: 'Generate documentation as universal reference YAML files (*.yml)',\n      documentation:\n        'Generates API documentation as a collection of files conforming' +\n        ' to the universal reference YAML format, which is used by the docs.microsoft.com' +\n        ' pipeline.'\n    });\n\n    this._officeParameter = this.defineFlagParameter({\n      parameterLongName: '--office',\n      description: `Enables some additional features specific to Office Add-ins`\n    });\n    this._newDocfxNamespacesParameter = this.defineFlagParameter({\n      parameterLongName: '--new-docfx-namespaces',\n      description:\n        `This enables an experimental feature that will be officially released with the next major version` +\n        ` of API Documenter.  It requires DocFX 2.46 or newer.  It enables documentation for namespaces and` +\n        ` adds them to the table of contents.  This will also affect file layout as namespaced items will be nested` +\n        ` under a directory for the namespace instead of just within the package.`\n    });\n    this._yamlFormatParameter = this.defineChoiceParameter<YamlFormat>({\n      parameterLongName: '--yaml-format',\n      alternatives: ['udp', 'sdp'],\n      defaultValue: 'sdp',\n      description:\n        `Specifies the YAML format - udp or sdp. Universal Document Processor (udp) should be used if you generating` +\n        ` YAML files for DocFX 2.x. Schema Driven Processor (sdp) should be used with DocFX 3.x.` +\n        ` NOTE: This parameter is ignored if you use --office.`\n    });\n  }\n\n  protected override async onExecuteAsync(): Promise<void> {\n    const { apiModel, inputFolder, outputFolder } = this.buildApiModel();\n\n    const yamlDocumenter: YamlDocumenter = this._officeParameter.value\n      ? new OfficeYamlDocumenter(apiModel, inputFolder, this._newDocfxNamespacesParameter.value)\n      : new YamlDocumenter(\n          apiModel,\n          this._newDocfxNamespacesParameter.value,\n          this._yamlFormatParameter.value\n        );\n\n    yamlDocumenter.generateFiles(outputFolder);\n  }\n}\n"]}

package/lib-esm/documenters/DocumenterConfig.js

@@ -0,0 +1,43 @@
+// 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 { JsonSchema, JsonFile, NewlineKind } from '@rushstack/node-core-library';
+import apiDocumenterSchema from '../schemas/api-documenter.schema.json';
+/**
+ * Helper for loading the api-documenter.json file format.  Later when the schema is more mature,
+ * this class will be used to represent the validated and normalized configuration, whereas `IConfigFile`
+ * represents the raw JSON file structure.
+ */
+export class DocumenterConfig {
+    constructor(filePath, configFile) {
+        this.configFilePath = filePath;
+        this.configFile = configFile;
+        switch (configFile.newlineKind) {
+            case 'lf':
+                this.newlineKind = NewlineKind.Lf;
+                break;
+            case 'os':
+                this.newlineKind = NewlineKind.OsDefault;
+                break;
+            default:
+                this.newlineKind = NewlineKind.CrLf;
+                break;
+        }
+    }
+    /**
+     * Load and validate an api-documenter.json file.
+     */
+    static loadFile(configFilePath) {
+        const configFile = JsonFile.loadAndValidate(configFilePath, DocumenterConfig.jsonSchema);
+        return new DocumenterConfig(path.resolve(configFilePath), configFile);
+    }
+}
+/**
+ * The JSON Schema for API Documenter config file (api-documenter.schema.json).
+ */
+DocumenterConfig.jsonSchema = JsonSchema.fromLoadedObject(apiDocumenterSchema);
+/**
+ * The config file name "api-documenter.json".
+ */
+DocumenterConfig.FILENAME = 'api-documenter.json';
+//# sourceMappingURL=DocumenterConfig.js.map

package/lib-esm/documenters/DocumenterConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocumenterConfig.js","sourceRoot":"","sources":["../../src/documenters/DocumenterConfig.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAGjF,OAAO,mBAAmB,MAAM,uCAAuC,CAAC;AAExE;;;;GAIG;AACH,MAAM,OAAO,gBAAgB;IAoB3B,YAAoB,QAAgB,EAAE,UAAuB;QAC3D,IAAI,CAAC,cAAc,GAAG,QAAQ,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAE7B,QAAQ,UAAU,CAAC,WAAW,EAAE,CAAC;YAC/B,KAAK,IAAI;gBACP,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC,EAAE,CAAC;gBAClC,MAAM;YACR,KAAK,IAAI;gBACP,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC,SAAS,CAAC;gBACzC,MAAM;YACR;gBACE,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC,IAAI,CAAC;gBACpC,MAAM;QACV,CAAC;IACH,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,QAAQ,CAAC,cAAsB;QAC3C,MAAM,UAAU,GAAgB,QAAQ,CAAC,eAAe,CAAC,cAAc,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAC;QAEtG,OAAO,IAAI,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC,CAAC;IACxE,CAAC;;AAlCD;;GAEG;AACoB,2BAAU,GAAe,UAAU,CAAC,gBAAgB,CAAC,mBAAmB,CAAC,CAAC;AAEjG;;GAEG;AACoB,yBAAQ,GAAW,qBAAqB,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport * as path from 'node:path';\n\nimport { JsonSchema, JsonFile, NewlineKind } from '@rushstack/node-core-library';\n\nimport type { IConfigFile } from './IConfigFile';\nimport apiDocumenterSchema from '../schemas/api-documenter.schema.json';\n\n/**\n * Helper for loading the api-documenter.json file format.  Later when the schema is more mature,\n * this class will be used to represent the validated and normalized configuration, whereas `IConfigFile`\n * represents the raw JSON file structure.\n */\nexport class DocumenterConfig {\n  public readonly configFilePath: string;\n  public readonly configFile: IConfigFile;\n\n  /**\n   * Specifies what type of newlines API Documenter should use when writing output files.  By default, the output files\n   * will be written with Windows-style newlines.\n   */\n  public readonly newlineKind: NewlineKind;\n\n  /**\n   * The JSON Schema for API Documenter config file (api-documenter.schema.json).\n   */\n  public static readonly jsonSchema: JsonSchema = JsonSchema.fromLoadedObject(apiDocumenterSchema);\n\n  /**\n   * The config file name \"api-documenter.json\".\n   */\n  public static readonly FILENAME: string = 'api-documenter.json';\n\n  private constructor(filePath: string, configFile: IConfigFile) {\n    this.configFilePath = filePath;\n    this.configFile = configFile;\n\n    switch (configFile.newlineKind) {\n      case 'lf':\n        this.newlineKind = NewlineKind.Lf;\n        break;\n      case 'os':\n        this.newlineKind = NewlineKind.OsDefault;\n        break;\n      default:\n        this.newlineKind = NewlineKind.CrLf;\n        break;\n    }\n  }\n\n  /**\n   * Load and validate an api-documenter.json file.\n   */\n  public static loadFile(configFilePath: string): DocumenterConfig {\n    const configFile: IConfigFile = JsonFile.loadAndValidate(configFilePath, DocumenterConfig.jsonSchema);\n\n    return new DocumenterConfig(path.resolve(configFilePath), configFile);\n  }\n}\n"]}

package/lib-esm/documenters/ExperimentalYamlDocumenter.js

@@ -0,0 +1,136 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { DocInlineTag } from '@microsoft/tsdoc';
+import { ApiItemKind, ApiDocumentedItem } from '@microsoft/api-extractor-model';
+import { YamlDocumenter } from './YamlDocumenter';
+/**
+ * EXPERIMENTAL - This documenter is a prototype of a new config file driven mode of operation for
+ * API Documenter.  It is not ready for general usage yet.  Its design may change in the future.
+ */
+export class ExperimentalYamlDocumenter extends YamlDocumenter {
+    constructor(apiModel, documenterConfig) {
+        super(apiModel, documenterConfig.configFile.newDocfxNamespaces);
+        this._config = documenterConfig.configFile.tableOfContents;
+        this._tocPointerMap = {};
+        this._generateTocPointersMap(this._config.tocConfig);
+    }
+    /** @override */
+    buildYamlTocFile(apiItems) {
+        this._buildTocItems2(apiItems);
+        return this._config.tocConfig;
+    }
+    _buildTocItems2(apiItems) {
+        const tocItems = [];
+        for (const apiItem of apiItems) {
+            let tocItem;
+            if (apiItem.kind === ApiItemKind.Namespace && !this.newDocfxNamespaces) {
+                tocItem = {
+                    name: this._getTocItemName(apiItem)
+                };
+            }
+            else {
+                if (this._shouldEmbed(apiItem.kind)) {
+                    // Don't generate table of contents items for embedded definitions
+                    continue;
+                }
+                tocItem = {
+                    name: this._getTocItemName(apiItem),
+                    uid: this._getUid(apiItem)
+                };
+                if (apiItem.kind !== ApiItemKind.Package) {
+                    this._filterItem(apiItem, tocItem);
+                }
+            }
+            tocItems.push(tocItem);
+            const children = this._getLogicalChildren(apiItem);
+            const childItems = this._buildTocItems2(children);
+            if (childItems.length > 0) {
+                tocItem.items = childItems;
+            }
+        }
+        return tocItems;
+    }
+    // Parses the tocConfig object to build a pointers map of nodes where we want to sort out the API items
+    _generateTocPointersMap(tocConfig) {
+        const { catchAllCategory } = this._config;
+        if (tocConfig.items) {
+            for (const tocItem of tocConfig.items) {
+                if (tocItem.items && tocItem.items.length > 0 && this._shouldNotIncludeInPointersMap(tocItem)) {
+                    this._generateTocPointersMap(tocItem);
+                }
+                else {
+                    // check for presence of the `catchAllCategory` config option
+                    if (catchAllCategory && tocItem.name === catchAllCategory) {
+                        this._catchAllPointer = tocItem;
+                    }
+                    else {
+                        this._tocPointerMap[tocItem.name] = tocItem;
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Filtering out the api-item by inlineTags or category name presence in the item name.
+     */
+    _filterItem(apiItem, tocItem) {
+        const { categoryInlineTag, categorizeByName } = this._config;
+        const { name: itemName } = tocItem;
+        let filtered = false;
+        // First we attempt to filter by inline tag if provided.
+        if (apiItem instanceof ApiDocumentedItem) {
+            const docInlineTag = categoryInlineTag
+                ? this._findInlineTagByName(categoryInlineTag, apiItem.tsdocComment)
+                : undefined;
+            const tagContent = docInlineTag && docInlineTag.tagContent && docInlineTag.tagContent.trim();
+            if (tagContent && this._tocPointerMap[tagContent]) {
+                // null assertion used because when pointer map was created we checked for presence of empty `items` array
+                this._tocPointerMap[tagContent].items.push(tocItem);
+                filtered = true;
+            }
+        }
+        // If not filtered by inline tag and `categorizeByName` config is enabled attempt to filter it by category name.
+        if (!filtered && categorizeByName) {
+            const pointers = Object.keys(this._tocPointerMap);
+            for (let i = 0, length = pointers.length; i < length; i++) {
+                if (itemName.indexOf(pointers[i]) !== -1) {
+                    // null assertion used because when pointer map was created we checked for presence of empty `items` array
+                    this._tocPointerMap[pointers[i]].items.push(tocItem);
+                    filtered = true;
+                    break;
+                }
+            }
+        }
+        // If item still not filtered and a `catchAllCategory` config provided push it to it.
+        if (!filtered && this._catchAllPointer && this._catchAllPointer.items) {
+            this._catchAllPointer.items.push(tocItem);
+        }
+    }
+    // This is a direct copy of a @docCategory inline tag finder in office-ui-fabric-react,
+    // but is generic enough to be used for any inline tag
+    _findInlineTagByName(tagName, docComment) {
+        const tagNameToCheck = `@${tagName}`;
+        if (docComment instanceof DocInlineTag) {
+            if (docComment.tagName === tagNameToCheck) {
+                return docComment;
+            }
+        }
+        if (docComment) {
+            for (const childNode of docComment.getChildNodes()) {
+                const result = this._findInlineTagByName(tagName, childNode);
+                if (result !== undefined) {
+                    return result;
+                }
+            }
+        }
+        return undefined;
+    }
+    _shouldNotIncludeInPointersMap(item) {
+        const { nonEmptyCategoryNodeNames } = this._config;
+        if (nonEmptyCategoryNodeNames && nonEmptyCategoryNodeNames.length) {
+            return nonEmptyCategoryNodeNames.indexOf(item.name) === -1;
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=ExperimentalYamlDocumenter.js.map

package/lib-esm/documenters/ExperimentalYamlDocumenter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExperimentalYamlDocumenter.js","sourceRoot":"","sources":["../../src/documenters/ExperimentalYamlDocumenter.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport { type DocComment, DocInlineTag } from '@microsoft/tsdoc';\nimport { type ApiModel, type ApiItem, ApiItemKind, ApiDocumentedItem } from '@microsoft/api-extractor-model';\n\nimport type { IConfigTableOfContents } from './IConfigFile';\nimport type { IYamlTocItem, IYamlTocFile } from '../yaml/IYamlTocFile';\nimport { YamlDocumenter } from './YamlDocumenter';\nimport type { DocumenterConfig } from './DocumenterConfig';\n\n/**\n * EXPERIMENTAL - This documenter is a prototype of a new config file driven mode of operation for\n * API Documenter.  It is not ready for general usage yet.  Its design may change in the future.\n */\nexport class ExperimentalYamlDocumenter extends YamlDocumenter {\n  private _config: IConfigTableOfContents;\n  private _tocPointerMap: { [key: string]: IYamlTocItem };\n  private _catchAllPointer: IYamlTocItem | undefined;\n\n  public constructor(apiModel: ApiModel, documenterConfig: DocumenterConfig) {\n    super(apiModel, documenterConfig.configFile.newDocfxNamespaces);\n    this._config = documenterConfig.configFile.tableOfContents!;\n\n    this._tocPointerMap = {};\n\n    this._generateTocPointersMap(this._config.tocConfig);\n  }\n\n  /** @override */\n  protected buildYamlTocFile(apiItems: ReadonlyArray<ApiItem>): IYamlTocFile {\n    this._buildTocItems2(apiItems);\n    return this._config.tocConfig;\n  }\n\n  private _buildTocItems2(apiItems: ReadonlyArray<ApiItem>): IYamlTocItem[] {\n    const tocItems: IYamlTocItem[] = [];\n    for (const apiItem of apiItems) {\n      let tocItem: IYamlTocItem;\n      if (apiItem.kind === ApiItemKind.Namespace && !this.newDocfxNamespaces) {\n        tocItem = {\n          name: this._getTocItemName(apiItem)\n        };\n      } else {\n        if (this._shouldEmbed(apiItem.kind)) {\n          // Don't generate table of contents items for embedded definitions\n          continue;\n        }\n\n        tocItem = {\n          name: this._getTocItemName(apiItem),\n          uid: this._getUid(apiItem)\n        };\n\n        if (apiItem.kind !== ApiItemKind.Package) {\n          this._filterItem(apiItem, tocItem);\n        }\n      }\n\n      tocItems.push(tocItem);\n\n      const children: ApiItem[] = this._getLogicalChildren(apiItem);\n      const childItems: IYamlTocItem[] = this._buildTocItems2(children);\n      if (childItems.length > 0) {\n        tocItem.items = childItems;\n      }\n    }\n    return tocItems;\n  }\n\n  // Parses the tocConfig object to build a pointers map of nodes where we want to sort out the API items\n  private _generateTocPointersMap(tocConfig: IYamlTocFile | IYamlTocItem): void {\n    const { catchAllCategory } = this._config;\n\n    if (tocConfig.items) {\n      for (const tocItem of tocConfig.items) {\n        if (tocItem.items && tocItem.items.length > 0 && this._shouldNotIncludeInPointersMap(tocItem)) {\n          this._generateTocPointersMap(tocItem);\n        } else {\n          // check for presence of the `catchAllCategory` config option\n          if (catchAllCategory && tocItem.name === catchAllCategory) {\n            this._catchAllPointer = tocItem;\n          } else {\n            this._tocPointerMap[tocItem.name] = tocItem;\n          }\n        }\n      }\n    }\n  }\n\n  /**\n   * Filtering out the api-item by inlineTags or category name presence in the item name.\n   */\n  private _filterItem(apiItem: ApiItem, tocItem: IYamlTocItem): void {\n    const { categoryInlineTag, categorizeByName } = this._config;\n    const { name: itemName } = tocItem;\n    let filtered: boolean = false;\n\n    // First we attempt to filter by inline tag if provided.\n    if (apiItem instanceof ApiDocumentedItem) {\n      const docInlineTag: DocInlineTag | undefined = categoryInlineTag\n        ? this._findInlineTagByName(categoryInlineTag, apiItem.tsdocComment)\n        : undefined;\n\n      const tagContent: string | undefined =\n        docInlineTag && docInlineTag.tagContent && docInlineTag.tagContent.trim();\n\n      if (tagContent && this._tocPointerMap[tagContent]) {\n        // null assertion used because when pointer map was created we checked for presence of empty `items` array\n        this._tocPointerMap[tagContent].items!.push(tocItem);\n        filtered = true;\n      }\n    }\n\n    // If not filtered by inline tag and `categorizeByName` config is enabled attempt to filter it by category name.\n    if (!filtered && categorizeByName) {\n      const pointers: string[] = Object.keys(this._tocPointerMap);\n      for (let i: number = 0, length: number = pointers.length; i < length; i++) {\n        if (itemName.indexOf(pointers[i]) !== -1) {\n          // null assertion used because when pointer map was created we checked for presence of empty `items` array\n          this._tocPointerMap[pointers[i]].items!.push(tocItem);\n          filtered = true;\n          break;\n        }\n      }\n    }\n\n    // If item still not filtered and a `catchAllCategory` config provided push it to it.\n    if (!filtered && this._catchAllPointer && this._catchAllPointer.items) {\n      this._catchAllPointer.items.push(tocItem);\n    }\n  }\n\n  // This is a direct copy of a @docCategory inline tag finder in office-ui-fabric-react,\n  // but is generic enough to be used for any inline tag\n  private _findInlineTagByName(\n    tagName: string,\n    docComment: DocComment | undefined\n  ): DocInlineTag | undefined {\n    const tagNameToCheck: string = `@${tagName}`;\n\n    if (docComment instanceof DocInlineTag) {\n      if (docComment.tagName === tagNameToCheck) {\n        return docComment;\n      }\n    }\n    if (docComment) {\n      for (const childNode of docComment.getChildNodes()) {\n        const result: DocInlineTag | undefined = this._findInlineTagByName(tagName, childNode as DocComment);\n        if (result !== undefined) {\n          return result;\n        }\n      }\n    }\n    return undefined;\n  }\n\n  private _shouldNotIncludeInPointersMap(item: IYamlTocItem): boolean {\n    const { nonEmptyCategoryNodeNames } = this._config;\n    if (nonEmptyCategoryNodeNames && nonEmptyCategoryNodeNames.length) {\n      return nonEmptyCategoryNodeNames.indexOf(item.name) === -1;\n    }\n    return true;\n  }\n}\n"]}

package/lib-esm/documenters/IConfigFile.js

@@ -0,0 +1,4 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+export {};
+//# sourceMappingURL=IConfigFile.js.map

package/lib-esm/documenters/IConfigFile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IConfigFile.js","sourceRoot":"","sources":["../../src/documenters/IConfigFile.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport type { IYamlTocFile } from '../yaml/IYamlTocFile';\n\n/**\n * Typescript interface describing the config schema for toc.yml file format.\n */\nexport interface IConfigTableOfContents {\n  /**\n   * Represents the tree structure describing the toc.file format.\n   * Nodes that have an empty `items` array property or their name will be included in the\n   * {@link IConfigTableOfContents.nonEmptyCategoryNodeNames} will be filled with API items\n   * that are matched with the filters provided. Everything else will be placed under\n   * {@link IConfigTableOfContents.catchAllCategory} if provided, which is highly recommended.\n   */\n  tocConfig: IYamlTocFile;\n\n  /**\n   * Optional category name that is recommended to be included along with\n   * one of the configs: {@link IConfigTableOfContents.categorizeByName} or\n   * {@link IConfigTableOfContents.categoryInlineTag}.\n   * Any items that are not matched according to the mentioned configuration options will be placed under this\n   * catchAll category. If none provided the items will not be included in the final toc.yml file.\n   */\n  catchAllCategory?: string;\n\n  /**\n   * Toggle either categorization of the API items should be made based on category name presence\n   * in the API item's name. Useful when there are API items without an inline tag to categorize them,\n   * but still need to place the items under categories. Note: this type of categorization might place some items\n   * under wrong categories if the names are similar but belong to different categories.\n   * In case that {@link IConfigTableOfContents.categoryInlineTag} is provided it will try categorize by\n   * using it and only if it didn't, it will attempt to categorize by name.\n   */\n  categorizeByName?: boolean;\n\n  /**\n   * Inline tag that will be used to categorize the API items. Will take precedence over the\n   * {@link IConfigTableOfContents.categorizeByName} flag in trying to place the API item according to the\n   * custom inline tag present in documentation of the source code.\n   */\n  categoryInlineTag?: string;\n\n  /**\n   * Array of node names that might have already items injected at the time of creating the\n   * {@link IConfigTableOfContents.tocConfig} tree structure but are still needed to be included as category\n   * nodes where API items will be pushed during the categorization algorithm.\n   */\n  nonEmptyCategoryNodeNames?: string[];\n}\n\n/**\n * Describes plugin packages to be loaded, and which features to enable.\n */\nexport interface IConfigPlugin {\n  /**\n   * Specifies the name of an API Documenter plugin package to be loaded.  By convention, the NPM package name\n   * should have the prefix `doc-plugin-`.  Its main entry point should export an object named\n   * `apiDocumenterPluginManifest` which implements the {@link IApiDocumenterPluginManifest} interface.\n   */\n  packageName: string;\n\n  /**\n   * A list of features to be enabled.  The features are defined in {@link IApiDocumenterPluginManifest.features}.\n   * The `enabledFeatureNames` strings are matched with {@link IFeatureDefinition.featureName}.\n   */\n  enabledFeatureNames: string[];\n}\n\n/**\n * This interface represents the api-documenter.json file format.\n */\nexport interface IConfigFile {\n  /**\n   * Specifies the output target.\n   */\n  outputTarget: 'docfx' | 'markdown';\n\n  /**\n   * Specifies what type of newlines API Documenter should use when writing output files.\n   *\n   * @remarks\n   * By default, the output files will be written with Windows-style newlines.\n   * To use POSIX-style newlines, specify \"lf\" instead.\n   * To use the OS's default newline kind, specify \"os\".\n   */\n  newlineKind?: 'crlf' | 'lf' | 'os';\n\n  /**\n   * This enables an experimental feature that will be officially released with the next major version\n   * of API Documenter.  It requires DocFX 2.46 or newer.  It enables documentation for namespaces and\n   * adds them to the table of contents.  This will also affect file layout as namespaced items will be nested\n   * under a directory for the namespace instead of just within the package.\n   *\n   * This setting currently only affects the 'docfx' output target.  It is equivalent to the `--new-docfx-namespaces`\n   * command-line parameter.\n   */\n  newDocfxNamespaces?: boolean;\n\n  /** {@inheritDoc IConfigPlugin} */\n  plugins?: IConfigPlugin[];\n\n  /** {@inheritDoc IConfigTableOfContents} */\n  tableOfContents?: IConfigTableOfContents;\n\n  /**\n   * Specifies whether inherited members should also be shown on an API item's page.\n   */\n  showInheritedMembers?: boolean;\n}\n"]}