apps/api-documenter/CHANGELOG.json

@@ -1,6 +1,30 @@
 {
   "name": "@microsoft/api-documenter",
   "entries": [
+    {
+      "version": "7.24.12",
+      "tag": "@microsoft/api-documenter_v7.24.12",
+      "date": "Tue, 28 May 2024 00:09:47 GMT",
+      "comments": {
+        "dependency": [
+          {
+            "comment": "Updating dependency \"@microsoft/api-extractor-model\" to `7.28.20`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/node-core-library\" to `5.2.0`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/terminal\" to `0.12.1`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/ts-command-line\" to `4.21.3`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/heft\" to `0.66.13`"
+          }
+        ]
+      }
+    },
     {
       "version": "7.24.11",
       "tag": "@microsoft/api-documenter_v7.24.11",

apps/api-documenter/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Change Log - @microsoft/api-documenter
 
-This log was last generated on Sat, 25 May 2024 04:54:07 GMT and should not be manually modified.
+This log was last generated on Tue, 28 May 2024 00:09:47 GMT and should not be manually modified.
+
+## 7.24.12
+Tue, 28 May 2024 00:09:47 GMT
+
+_Version update only_
 
 ## 7.24.11
 Sat, 25 May 2024 04:54:07 GMT

apps/api-documenter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/api-documenter",
-  "version": "7.24.11",
+  "version": "7.24.12",
   "description": "Read JSON files from api-extractor, generate documentation pages",
   "repository": {
     "type": "git",

apps/api-extractor/CHANGELOG.json

@@ -1,6 +1,32 @@
 {
   "name": "@microsoft/api-extractor",
   "entries": [
+    {
+      "version": "7.45.0",
+      "tag": "@microsoft/api-extractor_v7.45.0",
+      "date": "Tue, 28 May 2024 00:09:47 GMT",
+      "comments": {
+        "minor": [
+          {
+            "comment": "Improve support for resolving the `tsdoc-metadata.json` to include the folder referenced by a `types` field in an `\"exports\"` field and an `\"typesVersions\"` field in addition to `\"types\"`, `\"typings\"`, and `\"tsdocMetadata\"` fields."
+          }
+        ],
+        "dependency": [
+          {
+            "comment": "Updating dependency \"@microsoft/api-extractor-model\" to `7.28.20`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/node-core-library\" to `5.2.0`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/terminal\" to `0.12.1`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/ts-command-line\" to `4.21.3`"
+          }
+        ]
+      }
+    },
     {
       "version": "7.44.1",
       "tag": "@microsoft/api-extractor_v7.44.1",

apps/api-extractor/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Change Log - @microsoft/api-extractor
 
-This log was last generated on Sat, 25 May 2024 04:54:07 GMT and should not be manually modified.
+This log was last generated on Tue, 28 May 2024 00:09:47 GMT and should not be manually modified.
+
+## 7.45.0
+Tue, 28 May 2024 00:09:47 GMT
+
+### Minor changes
+
+- Improve support for resolving the `tsdoc-metadata.json` to include the folder referenced by a `types` field in an `"exports"` field and an `"typesVersions"` field in addition to `"types"`, `"typings"`, and `"tsdocMetadata"` fields.
 
 ## 7.44.1
 Sat, 25 May 2024 04:54:07 GMT

apps/api-extractor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/api-extractor",
-  "version": "7.44.1",
+  "version": "7.45.0",
   "description": "Analyze the exported API for a TypeScript library and generate reviews, documentation, and .d.ts rollups",
   "keywords": [
     "typescript",

apps/api-extractor/src/analyzer/PackageMetadataManager.ts

@@ -1,15 +1,17 @@
 // 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 'path';
+import path from 'path';
+import semver from 'semver';
 
 import {
   type PackageJsonLookup,
   FileSystem,
   JsonFile,
   type NewlineKind,
   type INodePackageJson,
-  type JsonObject
+  type JsonObject,
+  type IPackageJsonExports
 } from '@rushstack/node-core-library';
 import { Extractor } from '../api/Extractor';
 import type { MessageRouter } from '../collector/MessageRouter';
@@ -42,6 +44,134 @@ export class PackageMetadata {
   }
 }
 
+const TSDOC_METADATA_FILENAME: 'tsdoc-metadata.json' = 'tsdoc-metadata.json';
+
+/**
+ * 1. If package.json a `"tsdocMetadata": "./path1/path2/tsdoc-metadata.json"` field
+ * then that takes precedence. This convention will be rarely needed, since the other rules below generally
+ * produce a good result.
+ */
+function _tryResolveTsdocMetadataFromTsdocMetadataField({
+  tsdocMetadata
+}: INodePackageJson): string | undefined {
+  return tsdocMetadata;
+}
+
+/**
+ * 2. If package.json contains a `"exports": { ".": { "types": "./path1/path2/index.d.ts" } }` field,
+ * then we look for the file under "./path1/path2/tsdoc-metadata.json"
+ *
+ * This always looks for a "." and then a "*" entry in the exports field, and then evaluates for
+ * a "types" field in that entry.
+ */
+
+function _tryResolveTsdocMetadataFromExportsField({ exports }: INodePackageJson): string | undefined {
+  switch (typeof exports) {
+    case 'string': {
+      return `${path.dirname(exports)}/${TSDOC_METADATA_FILENAME}`;
+    }
+
+    case 'object': {
+      if (Array.isArray(exports)) {
+        const [firstExport] = exports;
+        // Take the first entry in the array
+        if (firstExport) {
+          return `${path.dirname(exports[0])}/${TSDOC_METADATA_FILENAME}`;
+        }
+      } else {
+        const rootExport: IPackageJsonExports | string | null | undefined = exports['.'] ?? exports['*'];
+        switch (typeof rootExport) {
+          case 'string': {
+            return `${path.dirname(rootExport)}/${TSDOC_METADATA_FILENAME}`;
+          }
+
+          case 'object': {
+            let typesExport: IPackageJsonExports | string | undefined = rootExport?.types;
+            while (typesExport) {
+              switch (typeof typesExport) {
+                case 'string': {
+                  return `${path.dirname(typesExport)}/${TSDOC_METADATA_FILENAME}`;
+                }
+
+                case 'object': {
+                  typesExport = typesExport?.types;
+                  break;
+                }
+              }
+            }
+          }
+        }
+      }
+      break;
+    }
+  }
+}
+
+/**
+ * 3. If package.json contains a `typesVersions` field, look for the version
+ * matching the highest minimum version that either includes a "." or "*" entry.
+ */
+function _tryResolveTsdocMetadataFromTypesVersionsField({
+  typesVersions
+}: INodePackageJson): string | undefined {
+  if (typesVersions) {
+    let highestMinimumMatchingSemver: semver.SemVer | undefined;
+    let latestMatchingPath: string | undefined;
+    for (const [version, paths] of Object.entries(typesVersions)) {
+      let range: semver.Range;
+      try {
+        range = new semver.Range(version);
+      } catch {
+        continue;
+      }
+
+      const minimumMatchingSemver: semver.SemVer | null = semver.minVersion(range);
+      if (
+        minimumMatchingSemver &&
+        (!highestMinimumMatchingSemver || semver.gt(minimumMatchingSemver, highestMinimumMatchingSemver))
+      ) {
+        const pathEntry: string[] | undefined = paths['.'] ?? paths['*'];
+        const firstPath: string | undefined = pathEntry?.[0];
+        if (firstPath) {
+          highestMinimumMatchingSemver = minimumMatchingSemver;
+          latestMatchingPath = firstPath;
+        }
+      }
+    }
+
+    if (latestMatchingPath) {
+      return `${path.dirname(latestMatchingPath)}/${TSDOC_METADATA_FILENAME}`;
+    }
+  }
+}
+
+/**
+ * 4. If package.json contains a `"types": "./path1/path2/index.d.ts"` or a `"typings": "./path1/path2/index.d.ts"`
+ * field, then we look for the file under "./path1/path2/tsdoc-metadata.json".
+ *
+ * @remarks
+ * `types` takes precedence over `typings`.
+ */
+function _tryResolveTsdocMetadataFromTypesOrTypingsFields({
+  typings,
+  types
+}: INodePackageJson): string | undefined {
+  const typesField: string | undefined = types ?? typings;
+  if (typesField) {
+    return `${path.dirname(typesField)}/${TSDOC_METADATA_FILENAME}`;
+  }
+}
+
+/**
+ * 5. If package.json contains a `"main": "./path1/path2/index.js"` field, then we look for the file under
+ * "./path1/path2/tsdoc-metadata.json".
+ */
+function _tryResolveTsdocMetadataFromMainField({ main }: INodePackageJson): string | undefined {
+  if (main) {
+    return `${path.dirname(main)}/${TSDOC_METADATA_FILENAME}`;
+  }
+}
+
 /**
  * This class maintains a cache of analyzed information obtained from package.json
  * files.  It is built on top of the PackageJsonLookup class.
@@ -56,7 +186,7 @@ export class PackageMetadata {
  * Use ts.program.isSourceFileFromExternalLibrary() to test source files before passing the to PackageMetadataManager.
  */
 export class PackageMetadataManager {
-  public static tsdocMetadataFilename: string = 'tsdoc-metadata.json';
+  public static tsdocMetadataFilename: string = TSDOC_METADATA_FILENAME;
 
   private readonly _packageJsonLookup: PackageJsonLookup;
   private readonly _messageRouter: MessageRouter;
@@ -70,37 +200,30 @@ export class PackageMetadataManager {
     this._messageRouter = messageRouter;
   }
 
-  // This feature is still being standardized: https://github.com/microsoft/tsdoc/issues/7
-  // In the future we will use the @microsoft/tsdoc library to read this file.
+  /**
+   * This feature is still being standardized: https://github.com/microsoft/tsdoc/issues/7
+   * In the future we will use the @microsoft/tsdoc library to read this file.
+   */
   private static _resolveTsdocMetadataPathFromPackageJson(
     packageFolder: string,
     packageJson: INodePackageJson
   ): string {
-    const tsdocMetadataFilename: string = PackageMetadataManager.tsdocMetadataFilename;
-
-    let tsdocMetadataRelativePath: string;
-
-    if (packageJson.tsdocMetadata) {
-      // 1. If package.json contains a field such as "tsdocMetadata": "./path1/path2/tsdoc-metadata.json",
-      // then that takes precedence.  This convention will be rarely needed, since the other rules below generally
-      // produce a good result.
-      tsdocMetadataRelativePath = packageJson.tsdocMetadata;
-    } else if (packageJson.typings) {
-      // 2. If package.json contains a field such as "typings": "./path1/path2/index.d.ts", then we look
-      // for the file under "./path1/path2/tsdoc-metadata.json"
-      tsdocMetadataRelativePath = path.join(path.dirname(packageJson.typings), tsdocMetadataFilename);
-    } else if (packageJson.main) {
-      // 3. If package.json contains a field such as "main": "./path1/path2/index.js", then we look for
-      // the file under "./path1/path2/tsdoc-metadata.json"
-      tsdocMetadataRelativePath = path.join(path.dirname(packageJson.main), tsdocMetadataFilename);
-    } else {
-      // 4. If none of the above rules apply, then by default we look for the file under "./tsdoc-metadata.json"
-      // since the default entry point is "./index.js"
-      tsdocMetadataRelativePath = tsdocMetadataFilename;
-    }
+    const tsdocMetadataRelativePath: string =
+      _tryResolveTsdocMetadataFromTsdocMetadataField(packageJson) ??
+      _tryResolveTsdocMetadataFromExportsField(packageJson) ??
+      _tryResolveTsdocMetadataFromTypesVersionsField(packageJson) ??
+      _tryResolveTsdocMetadataFromTypesOrTypingsFields(packageJson) ??
+      _tryResolveTsdocMetadataFromMainField(packageJson) ??
+      // As a final fallback, place the file in the root of the package.
+      TSDOC_METADATA_FILENAME;
 
     // Always resolve relative to the package folder.
-    const tsdocMetadataPath: string = path.resolve(packageFolder, tsdocMetadataRelativePath);
+    const tsdocMetadataPath: string = path.resolve(
+      packageFolder,
+      // This non-null assertion is safe because the last entry in TSDOC_METADATA_RESOLUTION_FUNCTIONS
+      // returns a non-undefined value.
+      tsdocMetadataRelativePath!
+    );
     return tsdocMetadataPath;
   }
 
@@ -117,6 +240,7 @@ export class PackageMetadataManager {
     if (tsdocMetadataPath) {
       return path.resolve(packageFolder, tsdocMetadataPath);
     }
+
     return PackageMetadataManager._resolveTsdocMetadataPathFromPackageJson(packageFolder, packageJson);
   }