@microsoft/api-extractor - npm Package Compare versions

Comparing version 7.44.1 to 7.45.0

lib/analyzer/PackageMetadataManager.d.ts

@@ -43,2 +43,6 @@ import { type PackageJsonLookup, type NewlineKind, type INodePackageJson } from '@rushstack/node-core-library';
     constructor(packageJsonLookup: PackageJsonLookup, 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.
+     */
     private static _resolveTsdocMetadataPathFromPackageJson;
@@ -45,0 +49,0 @@ /**

lib/analyzer/PackageMetadataManager.js

 "use strict";
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PackageMetadataManager = exports.PackageMetadata = void 0;
-const path = __importStar(require("path"));
+const path_1 = __importDefault(require("path"));
+const semver_1 = __importDefault(require("semver"));
 const node_core_library_1 = require("@rushstack/node-core-library");
@@ -45,3 +26,114 @@ const Extractor_1 = require("../api/Extractor");
 exports.PackageMetadata = PackageMetadata;
+const TSDOC_METADATA_FILENAME = '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 }) {
+    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 }) {
+    var _a;
+    switch (typeof exports) {
+        case 'string': {
+            return `${path_1.default.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_1.default.dirname(exports[0])}/${TSDOC_METADATA_FILENAME}`;
+                }
+            }
+            else {
+                const rootExport = (_a = exports['.']) !== null && _a !== void 0 ? _a : exports['*'];
+                switch (typeof rootExport) {
+                    case 'string': {
+                        return `${path_1.default.dirname(rootExport)}/${TSDOC_METADATA_FILENAME}`;
+                    }
+                    case 'object': {
+                        let typesExport = rootExport === null || rootExport === void 0 ? void 0 : rootExport.types;
+                        while (typesExport) {
+                            switch (typeof typesExport) {
+                                case 'string': {
+                                    return `${path_1.default.dirname(typesExport)}/${TSDOC_METADATA_FILENAME}`;
+                                }
+                                case 'object': {
+                                    typesExport = typesExport === null || typesExport === void 0 ? void 0 : 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 }) {
+    var _a;
+    if (typesVersions) {
+        let highestMinimumMatchingSemver;
+        let latestMatchingPath;
+        for (const [version, paths] of Object.entries(typesVersions)) {
+            let range;
+            try {
+                range = new semver_1.default.Range(version);
+            }
+            catch (_b) {
+                continue;
+            }
+            const minimumMatchingSemver = semver_1.default.minVersion(range);
+            if (minimumMatchingSemver &&
+                (!highestMinimumMatchingSemver || semver_1.default.gt(minimumMatchingSemver, highestMinimumMatchingSemver))) {
+                const pathEntry = (_a = paths['.']) !== null && _a !== void 0 ? _a : paths['*'];
+                const firstPath = pathEntry === null || pathEntry === void 0 ? void 0 : pathEntry[0];
+                if (firstPath) {
+                    highestMinimumMatchingSemver = minimumMatchingSemver;
+                    latestMatchingPath = firstPath;
+                }
+            }
+        }
+        if (latestMatchingPath) {
+            return `${path_1.default.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 }) {
+    const typesField = types !== null && types !== void 0 ? types : typings;
+    if (typesField) {
+        return `${path_1.default.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 }) {
+    if (main) {
+        return `${path_1.default.dirname(main)}/${TSDOC_METADATA_FILENAME}`;
+    }
+}
+/**
  * This class maintains a cache of analyzed information obtained from package.json
@@ -65,30 +157,16 @@ * files.  It is built on top of the PackageJsonLookup class.
     }
-    // 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.
+     */
     static _resolveTsdocMetadataPathFromPackageJson(packageFolder, packageJson) {
-        const tsdocMetadataFilename = PackageMetadataManager.tsdocMetadataFilename;
-        let tsdocMetadataRelativePath;
-        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;
-        }
+        var _a, _b, _c, _d, _e;
+        const tsdocMetadataRelativePath = (_e = (_d = (_c = (_b = (_a = _tryResolveTsdocMetadataFromTsdocMetadataField(packageJson)) !== null && _a !== void 0 ? _a : _tryResolveTsdocMetadataFromExportsField(packageJson)) !== null && _b !== void 0 ? _b : _tryResolveTsdocMetadataFromTypesVersionsField(packageJson)) !== null && _c !== void 0 ? _c : _tryResolveTsdocMetadataFromTypesOrTypingsFields(packageJson)) !== null && _d !== void 0 ? _d : _tryResolveTsdocMetadataFromMainField(packageJson)) !== null && _e !== void 0 ? _e : 
+        // 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 = path.resolve(packageFolder, tsdocMetadataRelativePath);
+        const tsdocMetadataPath = path_1.default.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;
@@ -103,3 +181,3 @@ }
         if (tsdocMetadataPath) {
-            return path.resolve(packageFolder, tsdocMetadataPath);
+            return path_1.default.resolve(packageFolder, tsdocMetadataPath);
         }
@@ -142,3 +220,3 @@ return PackageMetadataManager._resolveTsdocMetadataPathFromPackageJson(packageFolder, packageJson);
             const packageJson = this._packageJsonLookup.loadNodePackageJson(packageJsonFilePath);
-            const packageJsonFolder = path.dirname(packageJsonFilePath);
+            const packageJsonFolder = path_1.default.dirname(packageJsonFilePath);
             let aedocSupported = false;
@@ -168,3 +246,3 @@ const tsdocMetadataPath = PackageMetadataManager._resolveTsdocMetadataPathFromPackageJson(packageJsonFolder, packageJson);
 exports.PackageMetadataManager = PackageMetadataManager;
-PackageMetadataManager.tsdocMetadataFilename = 'tsdoc-metadata.json';
+PackageMetadataManager.tsdocMetadataFilename = TSDOC_METADATA_FILENAME;
 //# sourceMappingURL=PackageMetadataManager.js.map

package.json

 {
   "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",
@@ -43,7 +43,7 @@ "keywords": [
     "typescript": "5.4.2",
-    "@microsoft/api-extractor-model": "7.28.19",
+    "@microsoft/api-extractor-model": "7.28.20",
+    "@rushstack/node-core-library": "5.2.0",
+    "@rushstack/ts-command-line": "4.21.3",
     "@rushstack/rig-package": "0.5.2",
-    "@rushstack/terminal": "0.12.0",
-    "@rushstack/node-core-library": "5.1.0",
-    "@rushstack/ts-command-line": "4.21.2"
+    "@rushstack/terminal": "0.12.1"
   },
@@ -50,0 +50,0 @@ "devDependencies": {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1651406

increased by0.57%

Lines of code

16361

increased by0.51%

Dependency changes

• + Added@microsoft/api-extractor-model@7.28.20(transitive)

• + Added@rushstack/node-core-library@5.2.0(transitive)

• + Added@rushstack/terminal@0.12.1(transitive)

• + Added@rushstack/ts-command-line@4.21.3(transitive)

• - Removed@microsoft/api-extractor-model@7.28.19(transitive)

• - Removed@rushstack/node-core-library@5.1.0(transitive)

• - Removed@rushstack/terminal@0.12.0(transitive)

• - Removed@rushstack/ts-command-line@4.21.2(transitive)

• Updated@microsoft/api-extractor-model@7.28.20

• Updated@rushstack/node-core-library@5.2.0

• Updated@rushstack/terminal@0.12.1

• Updated@rushstack/ts-command-line@4.21.3