@microsoft/api-extractor 7.44.1 → 7.45.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -40,6 +40,10 @@ export declare class PackageMetadataManager {
|
|
|
40
40
|
private readonly _messageRouter;
|
|
41
41
|
private readonly _packageMetadataByPackageJsonPath;
|
|
42
42
|
constructor(packageJsonLookup: PackageJsonLookup, messageRouter: MessageRouter);
|
|
43
|
+
/**
|
|
44
|
+
* This feature is still being standardized: https://github.com/microsoft/tsdoc/issues/7
|
|
45
|
+
* In the future we will use the @microsoft/tsdoc library to read this file.
|
|
46
|
+
*/
|
|
43
47
|
private static _resolveTsdocMetadataPathFromPackageJson;
|
|
44
48
|
/**
|
|
45
49
|
* @param tsdocMetadataPath - An explicit path that can be configured in api-extractor.json.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"PackageMetadataManager.d.ts","sourceRoot":"","sources":["../../src/analyzer/PackageMetadataManager.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"PackageMetadataManager.d.ts","sourceRoot":"","sources":["../../src/analyzer/PackageMetadataManager.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,KAAK,iBAAiB,EAGtB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EAGtB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAGhE;;;GAGG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACH,SAAgB,eAAe,EAAE,MAAM,CAAC;IACxC;;;OAGG;IACH,SAAgB,WAAW,EAAE,gBAAgB,CAAC;IAC9C;;;OAGG;IACH,SAAgB,cAAc,EAAE,OAAO,CAAC;gBAErB,eAAe,EAAE,MAAM,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,OAAO;CAKnG;AAkID;;;;;;;;;;;;GAYG;AACH,qBAAa,sBAAsB;IACjC,OAAc,qBAAqB,EAAE,MAAM,CAA2B;IAEtE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAoB;IACvD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,iCAAiC,CAG9C;gBAEe,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa;IAKrF;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,wCAAwC;IAuBvD;;;;OAIG;WACW,wBAAwB,CACpC,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,gBAAgB,EAC7B,iBAAiB,CAAC,EAAE,MAAM,GACzB,MAAM;IAQT;;OAEG;WACW,sBAAsB,CAAC,iBAAiB,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,IAAI;IAsB/F;;;;OAIG;IACI,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAqCnF;;OAEG;IACI,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;CAO5D"}
|
|
@@ -1,32 +1,13 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
|
|
3
3
|
// See LICENSE in the project root for license information.
|
|
4
|
-
var
|
|
5
|
-
|
|
6
|
-
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
7
|
-
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
8
|
-
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
9
|
-
}
|
|
10
|
-
Object.defineProperty(o, k2, desc);
|
|
11
|
-
}) : (function(o, m, k, k2) {
|
|
12
|
-
if (k2 === undefined) k2 = k;
|
|
13
|
-
o[k2] = m[k];
|
|
14
|
-
}));
|
|
15
|
-
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
16
|
-
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
17
|
-
}) : function(o, v) {
|
|
18
|
-
o["default"] = v;
|
|
19
|
-
});
|
|
20
|
-
var __importStar = (this && this.__importStar) || function (mod) {
|
|
21
|
-
if (mod && mod.__esModule) return mod;
|
|
22
|
-
var result = {};
|
|
23
|
-
if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
|
|
24
|
-
__setModuleDefault(result, mod);
|
|
25
|
-
return result;
|
|
4
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
5
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
26
6
|
};
|
|
27
7
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
28
8
|
exports.PackageMetadataManager = exports.PackageMetadata = void 0;
|
|
29
|
-
const
|
|
9
|
+
const path_1 = __importDefault(require("path"));
|
|
10
|
+
const semver_1 = __importDefault(require("semver"));
|
|
30
11
|
const node_core_library_1 = require("@rushstack/node-core-library");
|
|
31
12
|
const Extractor_1 = require("../api/Extractor");
|
|
32
13
|
const ConsoleMessageId_1 = require("../api/ConsoleMessageId");
|
|
@@ -42,6 +23,117 @@ class PackageMetadata {
|
|
|
42
23
|
}
|
|
43
24
|
}
|
|
44
25
|
exports.PackageMetadata = PackageMetadata;
|
|
26
|
+
const TSDOC_METADATA_FILENAME = 'tsdoc-metadata.json';
|
|
27
|
+
/**
|
|
28
|
+
* 1. If package.json a `"tsdocMetadata": "./path1/path2/tsdoc-metadata.json"` field
|
|
29
|
+
* then that takes precedence. This convention will be rarely needed, since the other rules below generally
|
|
30
|
+
* produce a good result.
|
|
31
|
+
*/
|
|
32
|
+
function _tryResolveTsdocMetadataFromTsdocMetadataField({ tsdocMetadata }) {
|
|
33
|
+
return tsdocMetadata;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* 2. If package.json contains a `"exports": { ".": { "types": "./path1/path2/index.d.ts" } }` field,
|
|
37
|
+
* then we look for the file under "./path1/path2/tsdoc-metadata.json"
|
|
38
|
+
*
|
|
39
|
+
* This always looks for a "." and then a "*" entry in the exports field, and then evaluates for
|
|
40
|
+
* a "types" field in that entry.
|
|
41
|
+
*/
|
|
42
|
+
function _tryResolveTsdocMetadataFromExportsField({ exports }) {
|
|
43
|
+
var _a;
|
|
44
|
+
switch (typeof exports) {
|
|
45
|
+
case 'string': {
|
|
46
|
+
return `${path_1.default.dirname(exports)}/${TSDOC_METADATA_FILENAME}`;
|
|
47
|
+
}
|
|
48
|
+
case 'object': {
|
|
49
|
+
if (Array.isArray(exports)) {
|
|
50
|
+
const [firstExport] = exports;
|
|
51
|
+
// Take the first entry in the array
|
|
52
|
+
if (firstExport) {
|
|
53
|
+
return `${path_1.default.dirname(exports[0])}/${TSDOC_METADATA_FILENAME}`;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
else {
|
|
57
|
+
const rootExport = (_a = exports['.']) !== null && _a !== void 0 ? _a : exports['*'];
|
|
58
|
+
switch (typeof rootExport) {
|
|
59
|
+
case 'string': {
|
|
60
|
+
return `${path_1.default.dirname(rootExport)}/${TSDOC_METADATA_FILENAME}`;
|
|
61
|
+
}
|
|
62
|
+
case 'object': {
|
|
63
|
+
let typesExport = rootExport === null || rootExport === void 0 ? void 0 : rootExport.types;
|
|
64
|
+
while (typesExport) {
|
|
65
|
+
switch (typeof typesExport) {
|
|
66
|
+
case 'string': {
|
|
67
|
+
return `${path_1.default.dirname(typesExport)}/${TSDOC_METADATA_FILENAME}`;
|
|
68
|
+
}
|
|
69
|
+
case 'object': {
|
|
70
|
+
typesExport = typesExport === null || typesExport === void 0 ? void 0 : typesExport.types;
|
|
71
|
+
break;
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
break;
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* 3. If package.json contains a `typesVersions` field, look for the version
|
|
84
|
+
* matching the highest minimum version that either includes a "." or "*" entry.
|
|
85
|
+
*/
|
|
86
|
+
function _tryResolveTsdocMetadataFromTypesVersionsField({ typesVersions }) {
|
|
87
|
+
var _a;
|
|
88
|
+
if (typesVersions) {
|
|
89
|
+
let highestMinimumMatchingSemver;
|
|
90
|
+
let latestMatchingPath;
|
|
91
|
+
for (const [version, paths] of Object.entries(typesVersions)) {
|
|
92
|
+
let range;
|
|
93
|
+
try {
|
|
94
|
+
range = new semver_1.default.Range(version);
|
|
95
|
+
}
|
|
96
|
+
catch (_b) {
|
|
97
|
+
continue;
|
|
98
|
+
}
|
|
99
|
+
const minimumMatchingSemver = semver_1.default.minVersion(range);
|
|
100
|
+
if (minimumMatchingSemver &&
|
|
101
|
+
(!highestMinimumMatchingSemver || semver_1.default.gt(minimumMatchingSemver, highestMinimumMatchingSemver))) {
|
|
102
|
+
const pathEntry = (_a = paths['.']) !== null && _a !== void 0 ? _a : paths['*'];
|
|
103
|
+
const firstPath = pathEntry === null || pathEntry === void 0 ? void 0 : pathEntry[0];
|
|
104
|
+
if (firstPath) {
|
|
105
|
+
highestMinimumMatchingSemver = minimumMatchingSemver;
|
|
106
|
+
latestMatchingPath = firstPath;
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
if (latestMatchingPath) {
|
|
111
|
+
return `${path_1.default.dirname(latestMatchingPath)}/${TSDOC_METADATA_FILENAME}`;
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* 4. If package.json contains a `"types": "./path1/path2/index.d.ts"` or a `"typings": "./path1/path2/index.d.ts"`
|
|
117
|
+
* field, then we look for the file under "./path1/path2/tsdoc-metadata.json".
|
|
118
|
+
*
|
|
119
|
+
* @remarks
|
|
120
|
+
* `types` takes precedence over `typings`.
|
|
121
|
+
*/
|
|
122
|
+
function _tryResolveTsdocMetadataFromTypesOrTypingsFields({ typings, types }) {
|
|
123
|
+
const typesField = types !== null && types !== void 0 ? types : typings;
|
|
124
|
+
if (typesField) {
|
|
125
|
+
return `${path_1.default.dirname(typesField)}/${TSDOC_METADATA_FILENAME}`;
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* 5. If package.json contains a `"main": "./path1/path2/index.js"` field, then we look for the file under
|
|
130
|
+
* "./path1/path2/tsdoc-metadata.json".
|
|
131
|
+
*/
|
|
132
|
+
function _tryResolveTsdocMetadataFromMainField({ main }) {
|
|
133
|
+
if (main) {
|
|
134
|
+
return `${path_1.default.dirname(main)}/${TSDOC_METADATA_FILENAME}`;
|
|
135
|
+
}
|
|
136
|
+
}
|
|
45
137
|
/**
|
|
46
138
|
* This class maintains a cache of analyzed information obtained from package.json
|
|
47
139
|
* files. It is built on top of the PackageJsonLookup class.
|
|
@@ -61,34 +153,20 @@ class PackageMetadataManager {
|
|
|
61
153
|
this._packageJsonLookup = packageJsonLookup;
|
|
62
154
|
this._messageRouter = messageRouter;
|
|
63
155
|
}
|
|
64
|
-
|
|
65
|
-
|
|
156
|
+
/**
|
|
157
|
+
* This feature is still being standardized: https://github.com/microsoft/tsdoc/issues/7
|
|
158
|
+
* In the future we will use the @microsoft/tsdoc library to read this file.
|
|
159
|
+
*/
|
|
66
160
|
static _resolveTsdocMetadataPathFromPackageJson(packageFolder, packageJson) {
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
// then that takes precedence. This convention will be rarely needed, since the other rules below generally
|
|
72
|
-
// produce a good result.
|
|
73
|
-
tsdocMetadataRelativePath = packageJson.tsdocMetadata;
|
|
74
|
-
}
|
|
75
|
-
else if (packageJson.typings) {
|
|
76
|
-
// 2. If package.json contains a field such as "typings": "./path1/path2/index.d.ts", then we look
|
|
77
|
-
// for the file under "./path1/path2/tsdoc-metadata.json"
|
|
78
|
-
tsdocMetadataRelativePath = path.join(path.dirname(packageJson.typings), tsdocMetadataFilename);
|
|
79
|
-
}
|
|
80
|
-
else if (packageJson.main) {
|
|
81
|
-
// 3. If package.json contains a field such as "main": "./path1/path2/index.js", then we look for
|
|
82
|
-
// the file under "./path1/path2/tsdoc-metadata.json"
|
|
83
|
-
tsdocMetadataRelativePath = path.join(path.dirname(packageJson.main), tsdocMetadataFilename);
|
|
84
|
-
}
|
|
85
|
-
else {
|
|
86
|
-
// 4. If none of the above rules apply, then by default we look for the file under "./tsdoc-metadata.json"
|
|
87
|
-
// since the default entry point is "./index.js"
|
|
88
|
-
tsdocMetadataRelativePath = tsdocMetadataFilename;
|
|
89
|
-
}
|
|
161
|
+
var _a, _b, _c, _d, _e;
|
|
162
|
+
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 :
|
|
163
|
+
// As a final fallback, place the file in the root of the package.
|
|
164
|
+
TSDOC_METADATA_FILENAME;
|
|
90
165
|
// Always resolve relative to the package folder.
|
|
91
|
-
const tsdocMetadataPath =
|
|
166
|
+
const tsdocMetadataPath = path_1.default.resolve(packageFolder,
|
|
167
|
+
// This non-null assertion is safe because the last entry in TSDOC_METADATA_RESOLUTION_FUNCTIONS
|
|
168
|
+
// returns a non-undefined value.
|
|
169
|
+
tsdocMetadataRelativePath);
|
|
92
170
|
return tsdocMetadataPath;
|
|
93
171
|
}
|
|
94
172
|
/**
|
|
@@ -98,7 +176,7 @@ class PackageMetadataManager {
|
|
|
98
176
|
*/
|
|
99
177
|
static resolveTsdocMetadataPath(packageFolder, packageJson, tsdocMetadataPath) {
|
|
100
178
|
if (tsdocMetadataPath) {
|
|
101
|
-
return
|
|
179
|
+
return path_1.default.resolve(packageFolder, tsdocMetadataPath);
|
|
102
180
|
}
|
|
103
181
|
return PackageMetadataManager._resolveTsdocMetadataPathFromPackageJson(packageFolder, packageJson);
|
|
104
182
|
}
|
|
@@ -136,7 +214,7 @@ class PackageMetadataManager {
|
|
|
136
214
|
let packageMetadata = this._packageMetadataByPackageJsonPath.get(packageJsonFilePath);
|
|
137
215
|
if (!packageMetadata) {
|
|
138
216
|
const packageJson = this._packageJsonLookup.loadNodePackageJson(packageJsonFilePath);
|
|
139
|
-
const packageJsonFolder =
|
|
217
|
+
const packageJsonFolder = path_1.default.dirname(packageJsonFilePath);
|
|
140
218
|
let aedocSupported = false;
|
|
141
219
|
const tsdocMetadataPath = PackageMetadataManager._resolveTsdocMetadataPathFromPackageJson(packageJsonFolder, packageJson);
|
|
142
220
|
if (node_core_library_1.FileSystem.exists(tsdocMetadataPath)) {
|
|
@@ -161,5 +239,5 @@ class PackageMetadataManager {
|
|
|
161
239
|
}
|
|
162
240
|
}
|
|
163
241
|
exports.PackageMetadataManager = PackageMetadataManager;
|
|
164
|
-
PackageMetadataManager.tsdocMetadataFilename =
|
|
242
|
+
PackageMetadataManager.tsdocMetadataFilename = TSDOC_METADATA_FILENAME;
|
|
165
243
|
//# sourceMappingURL=PackageMetadataManager.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"PackageMetadataManager.js","sourceRoot":"","sources":["../../src/analyzer/PackageMetadataManager.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 'path';\n\nimport {\n type PackageJsonLookup,\n FileSystem,\n JsonFile,\n type NewlineKind,\n type INodePackageJson,\n type JsonObject\n} from '@rushstack/node-core-library';\nimport { Extractor } from '../api/Extractor';\nimport type { MessageRouter } from '../collector/MessageRouter';\nimport { ConsoleMessageId } from '../api/ConsoleMessageId';\n\n/**\n * Represents analyzed information for a package.json file.\n * This object is constructed and returned by PackageMetadataManager.\n */\nexport class PackageMetadata {\n /**\n * The absolute path to the package.json file being analyzed.\n */\n public readonly packageJsonPath: string;\n /**\n * The parsed contents of package.json. Note that PackageJsonLookup\n * only includes essential fields.\n */\n public readonly packageJson: INodePackageJson;\n /**\n * If true, then the package's documentation comments can be assumed\n * to contain API Extractor compatible TSDoc tags.\n */\n public readonly aedocSupported: boolean;\n\n public constructor(packageJsonPath: string, packageJson: INodePackageJson, aedocSupported: boolean) {\n this.packageJsonPath = packageJsonPath;\n this.packageJson = packageJson;\n this.aedocSupported = aedocSupported;\n }\n}\n\n/**\n * This class maintains a cache of analyzed information obtained from package.json\n * files. It is built on top of the PackageJsonLookup class.\n *\n * @remarks\n *\n * IMPORTANT: Don't use PackageMetadataManager to analyze source files from the current project:\n * 1. Files such as tsdoc-metadata.json may not have been built yet, and thus may contain incorrect information.\n * 2. The current project is not guaranteed to have a package.json file at all. For example, API Extractor can\n * be invoked on a bare .d.ts file.\n *\n * Use ts.program.isSourceFileFromExternalLibrary() to test source files before passing the to PackageMetadataManager.\n */\nexport class PackageMetadataManager {\n public static tsdocMetadataFilename: string = 'tsdoc-metadata.json';\n\n private readonly _packageJsonLookup: PackageJsonLookup;\n private readonly _messageRouter: MessageRouter;\n private readonly _packageMetadataByPackageJsonPath: Map<string, PackageMetadata> = new Map<\n string,\n PackageMetadata\n >();\n\n public constructor(packageJsonLookup: PackageJsonLookup, messageRouter: MessageRouter) {\n this._packageJsonLookup = packageJsonLookup;\n this._messageRouter = messageRouter;\n }\n\n // This feature is still being standardized: https://github.com/microsoft/tsdoc/issues/7\n // In the future we will use the @microsoft/tsdoc library to read this file.\n private static _resolveTsdocMetadataPathFromPackageJson(\n packageFolder: string,\n packageJson: INodePackageJson\n ): string {\n const tsdocMetadataFilename: string = PackageMetadataManager.tsdocMetadataFilename;\n\n let tsdocMetadataRelativePath: string;\n\n if (packageJson.tsdocMetadata) {\n // 1. If package.json contains a field such as \"tsdocMetadata\": \"./path1/path2/tsdoc-metadata.json\",\n // then that takes precedence. This convention will be rarely needed, since the other rules below generally\n // produce a good result.\n tsdocMetadataRelativePath = packageJson.tsdocMetadata;\n } else if (packageJson.typings) {\n // 2. If package.json contains a field such as \"typings\": \"./path1/path2/index.d.ts\", then we look\n // for the file under \"./path1/path2/tsdoc-metadata.json\"\n tsdocMetadataRelativePath = path.join(path.dirname(packageJson.typings), tsdocMetadataFilename);\n } else if (packageJson.main) {\n // 3. If package.json contains a field such as \"main\": \"./path1/path2/index.js\", then we look for\n // the file under \"./path1/path2/tsdoc-metadata.json\"\n tsdocMetadataRelativePath = path.join(path.dirname(packageJson.main), tsdocMetadataFilename);\n } else {\n // 4. If none of the above rules apply, then by default we look for the file under \"./tsdoc-metadata.json\"\n // since the default entry point is \"./index.js\"\n tsdocMetadataRelativePath = tsdocMetadataFilename;\n }\n\n // Always resolve relative to the package folder.\n const tsdocMetadataPath: string = path.resolve(packageFolder, tsdocMetadataRelativePath);\n return tsdocMetadataPath;\n }\n\n /**\n * @param tsdocMetadataPath - An explicit path that can be configured in api-extractor.json.\n * If this parameter is not an empty string, it overrides the normal path calculation.\n * @returns the absolute path to the TSDoc metadata file\n */\n public static resolveTsdocMetadataPath(\n packageFolder: string,\n packageJson: INodePackageJson,\n tsdocMetadataPath?: string\n ): string {\n if (tsdocMetadataPath) {\n return path.resolve(packageFolder, tsdocMetadataPath);\n }\n return PackageMetadataManager._resolveTsdocMetadataPathFromPackageJson(packageFolder, packageJson);\n }\n\n /**\n * Writes the TSDoc metadata file to the specified output file.\n */\n public static writeTsdocMetadataFile(tsdocMetadataPath: string, newlineKind: NewlineKind): void {\n const fileObject: JsonObject = {\n tsdocVersion: '0.12',\n toolPackages: [\n {\n packageName: '@microsoft/api-extractor',\n packageVersion: Extractor.version\n }\n ]\n };\n\n const fileContent: string =\n '// This file is read by tools that parse documentation comments conforming to the TSDoc standard.\\n' +\n '// It should be published with your NPM package. It should not be tracked by Git.\\n' +\n JsonFile.stringify(fileObject);\n\n FileSystem.writeFile(tsdocMetadataPath, fileContent, {\n convertLineEndings: newlineKind,\n ensureFolderExists: true\n });\n }\n\n /**\n * Finds the package.json in a parent folder of the specified source file, and\n * returns a PackageMetadata object. If no package.json was found, then undefined\n * is returned. The results are cached.\n */\n public tryFetchPackageMetadata(sourceFilePath: string): PackageMetadata | undefined {\n const packageJsonFilePath: string | undefined =\n this._packageJsonLookup.tryGetPackageJsonFilePathFor(sourceFilePath);\n if (!packageJsonFilePath) {\n return undefined;\n }\n let packageMetadata: PackageMetadata | undefined =\n this._packageMetadataByPackageJsonPath.get(packageJsonFilePath);\n\n if (!packageMetadata) {\n const packageJson: INodePackageJson = this._packageJsonLookup.loadNodePackageJson(packageJsonFilePath);\n\n const packageJsonFolder: string = path.dirname(packageJsonFilePath);\n\n let aedocSupported: boolean = false;\n\n const tsdocMetadataPath: string = PackageMetadataManager._resolveTsdocMetadataPathFromPackageJson(\n packageJsonFolder,\n packageJson\n );\n\n if (FileSystem.exists(tsdocMetadataPath)) {\n this._messageRouter.logVerbose(\n ConsoleMessageId.FoundTSDocMetadata,\n 'Found metadata in ' + tsdocMetadataPath\n );\n // If the file exists at all, assume it was written by API Extractor\n aedocSupported = true;\n }\n\n packageMetadata = new PackageMetadata(packageJsonFilePath, packageJson, aedocSupported);\n this._packageMetadataByPackageJsonPath.set(packageJsonFilePath, packageMetadata);\n }\n\n return packageMetadata;\n }\n\n /**\n * Returns true if the source file is part of a package whose .d.ts files support AEDoc annotations.\n */\n public isAedocSupportedFor(sourceFilePath: string): boolean {\n const packageMetadata: PackageMetadata | undefined = this.tryFetchPackageMetadata(sourceFilePath);\n if (!packageMetadata) {\n return false;\n }\n return packageMetadata.aedocSupported;\n }\n}\n"]}
|
|
1
|
+
{"version":3,"file":"PackageMetadataManager.js","sourceRoot":"","sources":["../../src/analyzer/PackageMetadataManager.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 path from 'path';\nimport semver from 'semver';\n\nimport {\n type PackageJsonLookup,\n FileSystem,\n JsonFile,\n type NewlineKind,\n type INodePackageJson,\n type JsonObject,\n type IPackageJsonExports\n} from '@rushstack/node-core-library';\nimport { Extractor } from '../api/Extractor';\nimport type { MessageRouter } from '../collector/MessageRouter';\nimport { ConsoleMessageId } from '../api/ConsoleMessageId';\n\n/**\n * Represents analyzed information for a package.json file.\n * This object is constructed and returned by PackageMetadataManager.\n */\nexport class PackageMetadata {\n /**\n * The absolute path to the package.json file being analyzed.\n */\n public readonly packageJsonPath: string;\n /**\n * The parsed contents of package.json. Note that PackageJsonLookup\n * only includes essential fields.\n */\n public readonly packageJson: INodePackageJson;\n /**\n * If true, then the package's documentation comments can be assumed\n * to contain API Extractor compatible TSDoc tags.\n */\n public readonly aedocSupported: boolean;\n\n public constructor(packageJsonPath: string, packageJson: INodePackageJson, aedocSupported: boolean) {\n this.packageJsonPath = packageJsonPath;\n this.packageJson = packageJson;\n this.aedocSupported = aedocSupported;\n }\n}\n\nconst TSDOC_METADATA_FILENAME: 'tsdoc-metadata.json' = 'tsdoc-metadata.json';\n\n/**\n * 1. If package.json a `\"tsdocMetadata\": \"./path1/path2/tsdoc-metadata.json\"` field\n * then that takes precedence. This convention will be rarely needed, since the other rules below generally\n * produce a good result.\n */\nfunction _tryResolveTsdocMetadataFromTsdocMetadataField({\n tsdocMetadata\n}: INodePackageJson): string | undefined {\n return tsdocMetadata;\n}\n\n/**\n * 2. If package.json contains a `\"exports\": { \".\": { \"types\": \"./path1/path2/index.d.ts\" } }` field,\n * then we look for the file under \"./path1/path2/tsdoc-metadata.json\"\n *\n * This always looks for a \".\" and then a \"*\" entry in the exports field, and then evaluates for\n * a \"types\" field in that entry.\n */\n\nfunction _tryResolveTsdocMetadataFromExportsField({ exports }: INodePackageJson): string | undefined {\n switch (typeof exports) {\n case 'string': {\n return `${path.dirname(exports)}/${TSDOC_METADATA_FILENAME}`;\n }\n\n case 'object': {\n if (Array.isArray(exports)) {\n const [firstExport] = exports;\n // Take the first entry in the array\n if (firstExport) {\n return `${path.dirname(exports[0])}/${TSDOC_METADATA_FILENAME}`;\n }\n } else {\n const rootExport: IPackageJsonExports | string | null | undefined = exports['.'] ?? exports['*'];\n switch (typeof rootExport) {\n case 'string': {\n return `${path.dirname(rootExport)}/${TSDOC_METADATA_FILENAME}`;\n }\n\n case 'object': {\n let typesExport: IPackageJsonExports | string | undefined = rootExport?.types;\n while (typesExport) {\n switch (typeof typesExport) {\n case 'string': {\n return `${path.dirname(typesExport)}/${TSDOC_METADATA_FILENAME}`;\n }\n\n case 'object': {\n typesExport = typesExport?.types;\n break;\n }\n }\n }\n }\n }\n }\n break;\n }\n }\n}\n\n/**\n * 3. If package.json contains a `typesVersions` field, look for the version\n * matching the highest minimum version that either includes a \".\" or \"*\" entry.\n */\nfunction _tryResolveTsdocMetadataFromTypesVersionsField({\n typesVersions\n}: INodePackageJson): string | undefined {\n if (typesVersions) {\n let highestMinimumMatchingSemver: semver.SemVer | undefined;\n let latestMatchingPath: string | undefined;\n for (const [version, paths] of Object.entries(typesVersions)) {\n let range: semver.Range;\n try {\n range = new semver.Range(version);\n } catch {\n continue;\n }\n\n const minimumMatchingSemver: semver.SemVer | null = semver.minVersion(range);\n if (\n minimumMatchingSemver &&\n (!highestMinimumMatchingSemver || semver.gt(minimumMatchingSemver, highestMinimumMatchingSemver))\n ) {\n const pathEntry: string[] | undefined = paths['.'] ?? paths['*'];\n const firstPath: string | undefined = pathEntry?.[0];\n if (firstPath) {\n highestMinimumMatchingSemver = minimumMatchingSemver;\n latestMatchingPath = firstPath;\n }\n }\n }\n\n if (latestMatchingPath) {\n return `${path.dirname(latestMatchingPath)}/${TSDOC_METADATA_FILENAME}`;\n }\n }\n}\n\n/**\n * 4. If package.json contains a `\"types\": \"./path1/path2/index.d.ts\"` or a `\"typings\": \"./path1/path2/index.d.ts\"`\n * field, then we look for the file under \"./path1/path2/tsdoc-metadata.json\".\n *\n * @remarks\n * `types` takes precedence over `typings`.\n */\nfunction _tryResolveTsdocMetadataFromTypesOrTypingsFields({\n typings,\n types\n}: INodePackageJson): string | undefined {\n const typesField: string | undefined = types ?? typings;\n if (typesField) {\n return `${path.dirname(typesField)}/${TSDOC_METADATA_FILENAME}`;\n }\n}\n\n/**\n * 5. If package.json contains a `\"main\": \"./path1/path2/index.js\"` field, then we look for the file under\n * \"./path1/path2/tsdoc-metadata.json\".\n */\nfunction _tryResolveTsdocMetadataFromMainField({ main }: INodePackageJson): string | undefined {\n if (main) {\n return `${path.dirname(main)}/${TSDOC_METADATA_FILENAME}`;\n }\n}\n\n/**\n * This class maintains a cache of analyzed information obtained from package.json\n * files. It is built on top of the PackageJsonLookup class.\n *\n * @remarks\n *\n * IMPORTANT: Don't use PackageMetadataManager to analyze source files from the current project:\n * 1. Files such as tsdoc-metadata.json may not have been built yet, and thus may contain incorrect information.\n * 2. The current project is not guaranteed to have a package.json file at all. For example, API Extractor can\n * be invoked on a bare .d.ts file.\n *\n * Use ts.program.isSourceFileFromExternalLibrary() to test source files before passing the to PackageMetadataManager.\n */\nexport class PackageMetadataManager {\n public static tsdocMetadataFilename: string = TSDOC_METADATA_FILENAME;\n\n private readonly _packageJsonLookup: PackageJsonLookup;\n private readonly _messageRouter: MessageRouter;\n private readonly _packageMetadataByPackageJsonPath: Map<string, PackageMetadata> = new Map<\n string,\n PackageMetadata\n >();\n\n public constructor(packageJsonLookup: PackageJsonLookup, messageRouter: MessageRouter) {\n this._packageJsonLookup = packageJsonLookup;\n this._messageRouter = messageRouter;\n }\n\n /**\n * This feature is still being standardized: https://github.com/microsoft/tsdoc/issues/7\n * In the future we will use the @microsoft/tsdoc library to read this file.\n */\n private static _resolveTsdocMetadataPathFromPackageJson(\n packageFolder: string,\n packageJson: INodePackageJson\n ): string {\n const tsdocMetadataRelativePath: string =\n _tryResolveTsdocMetadataFromTsdocMetadataField(packageJson) ??\n _tryResolveTsdocMetadataFromExportsField(packageJson) ??\n _tryResolveTsdocMetadataFromTypesVersionsField(packageJson) ??\n _tryResolveTsdocMetadataFromTypesOrTypingsFields(packageJson) ??\n _tryResolveTsdocMetadataFromMainField(packageJson) ??\n // As a final fallback, place the file in the root of the package.\n TSDOC_METADATA_FILENAME;\n\n // Always resolve relative to the package folder.\n const tsdocMetadataPath: string = path.resolve(\n packageFolder,\n // This non-null assertion is safe because the last entry in TSDOC_METADATA_RESOLUTION_FUNCTIONS\n // returns a non-undefined value.\n tsdocMetadataRelativePath!\n );\n return tsdocMetadataPath;\n }\n\n /**\n * @param tsdocMetadataPath - An explicit path that can be configured in api-extractor.json.\n * If this parameter is not an empty string, it overrides the normal path calculation.\n * @returns the absolute path to the TSDoc metadata file\n */\n public static resolveTsdocMetadataPath(\n packageFolder: string,\n packageJson: INodePackageJson,\n tsdocMetadataPath?: string\n ): string {\n if (tsdocMetadataPath) {\n return path.resolve(packageFolder, tsdocMetadataPath);\n }\n\n return PackageMetadataManager._resolveTsdocMetadataPathFromPackageJson(packageFolder, packageJson);\n }\n\n /**\n * Writes the TSDoc metadata file to the specified output file.\n */\n public static writeTsdocMetadataFile(tsdocMetadataPath: string, newlineKind: NewlineKind): void {\n const fileObject: JsonObject = {\n tsdocVersion: '0.12',\n toolPackages: [\n {\n packageName: '@microsoft/api-extractor',\n packageVersion: Extractor.version\n }\n ]\n };\n\n const fileContent: string =\n '// This file is read by tools that parse documentation comments conforming to the TSDoc standard.\\n' +\n '// It should be published with your NPM package. It should not be tracked by Git.\\n' +\n JsonFile.stringify(fileObject);\n\n FileSystem.writeFile(tsdocMetadataPath, fileContent, {\n convertLineEndings: newlineKind,\n ensureFolderExists: true\n });\n }\n\n /**\n * Finds the package.json in a parent folder of the specified source file, and\n * returns a PackageMetadata object. If no package.json was found, then undefined\n * is returned. The results are cached.\n */\n public tryFetchPackageMetadata(sourceFilePath: string): PackageMetadata | undefined {\n const packageJsonFilePath: string | undefined =\n this._packageJsonLookup.tryGetPackageJsonFilePathFor(sourceFilePath);\n if (!packageJsonFilePath) {\n return undefined;\n }\n let packageMetadata: PackageMetadata | undefined =\n this._packageMetadataByPackageJsonPath.get(packageJsonFilePath);\n\n if (!packageMetadata) {\n const packageJson: INodePackageJson = this._packageJsonLookup.loadNodePackageJson(packageJsonFilePath);\n\n const packageJsonFolder: string = path.dirname(packageJsonFilePath);\n\n let aedocSupported: boolean = false;\n\n const tsdocMetadataPath: string = PackageMetadataManager._resolveTsdocMetadataPathFromPackageJson(\n packageJsonFolder,\n packageJson\n );\n\n if (FileSystem.exists(tsdocMetadataPath)) {\n this._messageRouter.logVerbose(\n ConsoleMessageId.FoundTSDocMetadata,\n 'Found metadata in ' + tsdocMetadataPath\n );\n // If the file exists at all, assume it was written by API Extractor\n aedocSupported = true;\n }\n\n packageMetadata = new PackageMetadata(packageJsonFilePath, packageJson, aedocSupported);\n this._packageMetadataByPackageJsonPath.set(packageJsonFilePath, packageMetadata);\n }\n\n return packageMetadata;\n }\n\n /**\n * Returns true if the source file is part of a package whose .d.ts files support AEDoc annotations.\n */\n public isAedocSupportedFor(sourceFilePath: string): boolean {\n const packageMetadata: PackageMetadata | undefined = this.tryFetchPackageMetadata(sourceFilePath);\n if (!packageMetadata) {\n return false;\n }\n return packageMetadata.aedocSupported;\n }\n}\n"]}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@microsoft/api-extractor",
|
|
3
|
-
"version": "7.
|
|
3
|
+
"version": "7.45.1",
|
|
4
4
|
"description": "Analyze the exported API for a TypeScript library and generate reviews, documentation, and .d.ts rollups",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"typescript",
|
|
@@ -40,11 +40,11 @@
|
|
|
40
40
|
"semver": "~7.5.4",
|
|
41
41
|
"source-map": "~0.6.1",
|
|
42
42
|
"typescript": "5.4.2",
|
|
43
|
-
"@microsoft/api-extractor-model": "7.28.
|
|
43
|
+
"@microsoft/api-extractor-model": "7.28.21",
|
|
44
|
+
"@rushstack/node-core-library": "5.3.0",
|
|
44
45
|
"@rushstack/rig-package": "0.5.2",
|
|
45
|
-
"@rushstack/
|
|
46
|
-
"@rushstack/
|
|
47
|
-
"@rushstack/ts-command-line": "4.21.2"
|
|
46
|
+
"@rushstack/ts-command-line": "4.21.4",
|
|
47
|
+
"@rushstack/terminal": "0.12.2"
|
|
48
48
|
},
|
|
49
49
|
"devDependencies": {
|
|
50
50
|
"@rushstack/heft-node-rig": "2.6.7",
|