Socket
Socket
Sign inDemoInstall

@microsoft/api-extractor

Package Overview
Dependencies
Maintainers
2
Versions
487
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@microsoft/api-extractor - npm Package Compare versions

Comparing version 7.41.1 to 7.42.0

11

dist/rollup.d.ts

@@ -909,4 +909,13 @@ /**

* @remarks
* Also supports glob patterns.
* Note: glob patterns will **only** be resolved against dependencies listed in the project's package.json file.
*
* For example, suppose that Webpack is used to generate a distributed bundle for the project `library1`,
* * This is both a safety and a performance precaution.
*
* Exact package names will be applied against any dependency encountered while walking the type graph, regardless of
* dependencies listed in the package.json.
*
* @example
*
* Suppose that Webpack is used to generate a distributed bundle for the project `library1`,
* and another NPM package `library2` is embedded in this bundle. Some types from `library2` may become part

@@ -913,0 +922,0 @@ * of the exported API for `library1`, but by default API Extractor would generate a .d.ts rollup that explicitly

7

lib/api/ExtractorConfig.js

@@ -451,7 +451,4 @@ "use strict";

const bundledPackages = configObject.bundledPackages || [];
for (const bundledPackage of bundledPackages) {
if (!node_core_library_1.PackageName.isValidName(bundledPackage)) {
throw new Error(`The "bundledPackages" list contains an invalid package name: "${bundledPackage}"`);
}
}
// Note: we cannot fully validate package name patterns, as the strings may contain wildcards.
// We won't know if the entries are valid until we can compare them against the package.json "dependencies" contents.
const tsconfigFilePath = ExtractorConfig._resolvePathWithTokens('tsconfigFilePath', configObject.compiler.tsconfigFilePath, tokenContext);

@@ -458,0 +455,0 @@ if (configObject.compiler.overrideTsconfig === undefined) {

11

lib/api/IConfigFile.d.ts

@@ -348,4 +348,13 @@ import type { EnumMemberOrder } from '@microsoft/api-extractor-model';

* @remarks
* Also supports glob patterns.
* Note: glob patterns will **only** be resolved against dependencies listed in the project's package.json file.
*
* For example, suppose that Webpack is used to generate a distributed bundle for the project `library1`,
* * This is both a safety and a performance precaution.
*
* Exact package names will be applied against any dependency encountered while walking the type graph, regardless of
* dependencies listed in the package.json.
*
* @example
*
* Suppose that Webpack is used to generate a distributed bundle for the project `library1`,
* and another NPM package `library2` is embedded in this bundle. Some types from `library2` may become part

@@ -352,0 +361,0 @@ * of the exported API for `library1`, but by default API Extractor would generate a .d.ts rollup that explicitly

13

lib/collector/ApiItemMetadata.d.ts

@@ -64,2 +64,15 @@ import type * as tsdoc from '@microsoft/tsdoc';

tsdocComment: tsdoc.DocComment | undefined;
/**
* Tracks whether or not the associated API item is known to be missing sufficient documentation.
*
* @remarks
*
* An "undocumented" item is one whose TSDoc comment which either does not contain a summary comment block, or
* has an `@inheritDoc` tag that resolves to another "undocumented" API member.
*
* If there is any ambiguity (e.g. if an `@inheritDoc` comment points to an external API member, whose documentation,
* we can't parse), "undocumented" will be `false`.
*
* @remarks Assigned by {@link DocCommentEnhancer}.
*/
undocumented: boolean;

@@ -66,0 +79,0 @@ docCommentEnhancerVisitorState: VisitorState;

14

lib/collector/ApiItemMetadata.js

@@ -33,3 +33,15 @@ "use strict";

constructor(options) {
// Assigned by DocCommentEnhancer
/**
* Tracks whether or not the associated API item is known to be missing sufficient documentation.
*
* @remarks
*
* An "undocumented" item is one whose TSDoc comment which either does not contain a summary comment block, or
* has an `@inheritDoc` tag that resolves to another "undocumented" API member.
*
* If there is any ambiguity (e.g. if an `@inheritDoc` comment points to an external API member, whose documentation,
* we can't parse), "undocumented" will be `false`.
*
* @remarks Assigned by {@link DocCommentEnhancer}.
*/
this.undocumented = true;

@@ -36,0 +48,0 @@ this.docCommentEnhancerVisitorState = VisitorState_1.VisitorState.Unvisited;

13

lib/collector/Collector.d.ts

@@ -67,2 +67,15 @@ import * as ts from 'typescript';

/**
* Resolve provided `bundledPackages` names and glob patterns to a list of explicit package names.
*
* @remarks
* Explicit package names will be included in the output unconditionally. However, wildcard patterns will
* only be matched against the various dependencies listed in the provided package.json (if there was one).
* Patterns will be matched against `dependencies`, `devDependencies`, `optionalDependencies`, and `peerDependencies`.
*
* @param bundledPackages - The list of package names and/or glob patterns to resolve.
* @param packageJson - The package.json of the package being processed (if there is one).
* @returns The set of resolved package names to be bundled during analysis.
*/
private static _resolveBundledPackagePatterns;
/**a
* Returns a list of names (e.g. "example-library") that should appear in a reference like this:

@@ -69,0 +82,0 @@ *

51

lib/collector/Collector.js

@@ -27,2 +27,5 @@ "use strict";

};
var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });

@@ -34,2 +37,3 @@ exports.Collector = void 0;

const api_extractor_model_1 = require("@microsoft/api-extractor-model");
const minimatch_1 = __importDefault(require("minimatch"));
const ExtractorMessageId_1 = require("../api/ExtractorMessageId");

@@ -87,3 +91,4 @@ const CollectorEntity_1 = require("./CollectorEntity");

this._tsdocParser = new tsdoc.TSDocParser(this.extractorConfig.tsdocConfiguration);
this.bundledPackageNames = new Set(this.extractorConfig.bundledPackages);
// Resolve package name patterns and store concrete set of bundled package dependency names
this.bundledPackageNames = Collector._resolveBundledPackagePatterns(this.extractorConfig.bundledPackages, this.extractorConfig.packageJson);
this.astSymbolTable = new AstSymbolTable_1.AstSymbolTable(this.program, this.typeChecker, this.packageJsonLookup, this.bundledPackageNames, this.messageRouter);

@@ -94,2 +99,46 @@ this.astReferenceResolver = new AstReferenceResolver_1.AstReferenceResolver(this);

/**
* Resolve provided `bundledPackages` names and glob patterns to a list of explicit package names.
*
* @remarks
* Explicit package names will be included in the output unconditionally. However, wildcard patterns will
* only be matched against the various dependencies listed in the provided package.json (if there was one).
* Patterns will be matched against `dependencies`, `devDependencies`, `optionalDependencies`, and `peerDependencies`.
*
* @param bundledPackages - The list of package names and/or glob patterns to resolve.
* @param packageJson - The package.json of the package being processed (if there is one).
* @returns The set of resolved package names to be bundled during analysis.
*/
static _resolveBundledPackagePatterns(bundledPackages, packageJson) {
var _a, _b, _c, _d;
if (bundledPackages.length === 0) {
// If no `bundledPackages` were specified, then there is nothing to resolve.
// Return an empty set.
return new Set();
}
// Accumulate all declared dependencies.
// Any wildcard patterns in `bundledPackages` will be resolved against these.
const dependencyNames = new Set();
Object.keys((_a = packageJson === null || packageJson === void 0 ? void 0 : packageJson.dependencies) !== null && _a !== void 0 ? _a : {}).forEach((dep) => dependencyNames.add(dep));
Object.keys((_b = packageJson === null || packageJson === void 0 ? void 0 : packageJson.devDependencies) !== null && _b !== void 0 ? _b : {}).forEach((dep) => dependencyNames.add(dep));
Object.keys((_c = packageJson === null || packageJson === void 0 ? void 0 : packageJson.peerDependencies) !== null && _c !== void 0 ? _c : {}).forEach((dep) => dependencyNames.add(dep));
Object.keys((_d = packageJson === null || packageJson === void 0 ? void 0 : packageJson.optionalDependencies) !== null && _d !== void 0 ? _d : {}).forEach((dep) => dependencyNames.add(dep));
// The set of resolved package names to be populated and returned
const resolvedPackageNames = new Set();
for (const packageNameOrPattern of bundledPackages) {
// If the string is an exact package name, use it regardless of package.json contents
if (node_core_library_1.PackageName.isValidName(packageNameOrPattern)) {
resolvedPackageNames.add(packageNameOrPattern);
}
else {
// If the entry isn't an exact package name, assume glob pattern and search for matches
for (const dependencyName of dependencyNames) {
if ((0, minimatch_1.default)(dependencyName, packageNameOrPattern)) {
resolvedPackageNames.add(dependencyName);
}
}
}
}
return resolvedPackageNames;
}
/**a
* Returns a list of names (e.g. "example-library") that should appear in a reference like this:

@@ -96,0 +145,0 @@ *

4

lib/enhancers/DocCommentEnhancer.d.ts

@@ -19,3 +19,7 @@ import type { Collector } from '../collector/Collector';

private _copyInheritedDocs;
/**
* Determines whether or not the provided declaration reference points to an item in the working package.
*/
private _refersToDeclarationInWorkingPackage;
}
//# sourceMappingURL=DocCommentEnhancer.d.ts.map

57

lib/enhancers/DocCommentEnhancer.js

@@ -127,8 +127,39 @@ "use strict";

}
if (metadata.tsdocComment) {
// Require the summary to contain at least 10 non-spacing characters
metadata.undocumented = !tsdoc.PlainTextEmitter.hasAnyTextContent(metadata.tsdocComment.summarySection, 10);
}
else {
metadata.undocumented = true;
// For non-constructor items, we will determine whether or not the item is documented as follows:
// 1. If it contains a summary section with at least 10 characters, then it is considered "documented".
// 2. If it contains an @inheritDoc tag, then it *may* be considered "documented", depending on whether or not
// the tag resolves to a "documented" API member.
// - Note: for external members, we cannot currently determine this, so we will consider the "documented"
// status to be unknown.
if (metadata.tsdocComment) {
if (tsdoc.PlainTextEmitter.hasAnyTextContent(metadata.tsdocComment.summarySection, 10)) {
// If the API item has a summary comment block (with at least 10 characters), mark it as "documented".
metadata.undocumented = false;
}
else if (metadata.tsdocComment.inheritDocTag) {
if (this._refersToDeclarationInWorkingPackage(metadata.tsdocComment.inheritDocTag.declarationReference)) {
// If the API item has an `@inheritDoc` comment that points to an API item in the working package,
// then the documentation contents should have already been copied from the target via `_applyInheritDoc`.
// The continued existence of the tag indicates that the declaration reference was invalid, and not
// documentation contents could be copied.
// An analyzer issue will have already been logged for this.
// We will treat such an API as "undocumented".
metadata.undocumented = true;
}
else {
// If the API item has an `@inheritDoc` comment that points to an external API item, we cannot currently
// determine whether or not the target is "documented", so we cannot say definitively that this is "undocumented".
metadata.undocumented = false;
}
}
else {
// If the API item has neither a summary comment block, nor an `@inheritDoc` comment, mark it as "undocumented".
metadata.undocumented = true;
}
}
else {
// If there is no tsdoc comment at all, mark "undocumented".
metadata.undocumented = true;
}
}

@@ -148,4 +179,3 @@ }

// Tracked by: https://github.com/microsoft/rushstack/issues/1195
if (node.codeDestination.packageName === undefined ||
node.codeDestination.packageName === this._collector.workingPackage.name) {
if (this._refersToDeclarationInWorkingPackage(node.codeDestination)) {
const referencedAstDeclaration = this._collector.astReferenceResolver.resolve(node.codeDestination);

@@ -170,6 +200,4 @@ if (referencedAstDeclaration instanceof AstReferenceResolver_1.ResolverFailure) {

}
// Is it referring to the working package?
if (!(inheritDocTag.declarationReference.packageName === undefined ||
inheritDocTag.declarationReference.packageName === this._collector.workingPackage.name)) {
// It's referencing an external package, so skip this inheritDoc tag, since AstReferenceResolver doesn't
if (!this._refersToDeclarationInWorkingPackage(inheritDocTag.declarationReference)) {
// The `@inheritDoc` tag is referencing an external package. Skip it, since AstReferenceResolver doesn't
// support it yet. As a workaround, this tag will get handled later by api-documenter.

@@ -206,4 +234,11 @@ // Tracked by: https://github.com/microsoft/rushstack/issues/1195

}
/**
* Determines whether or not the provided declaration reference points to an item in the working package.
*/
_refersToDeclarationInWorkingPackage(declarationReference) {
return ((declarationReference === null || declarationReference === void 0 ? void 0 : declarationReference.packageName) === undefined ||
declarationReference.packageName === this._collector.workingPackage.name);
}
}
exports.DocCommentEnhancer = DocCommentEnhancer;
//# sourceMappingURL=DocCommentEnhancer.js.map

2

lib/generators/DtsRollupGenerator.js

@@ -108,3 +108,3 @@ "use strict";

// E.g. class Foo (`@public`) extends interface Bar (`@beta`) from some external library.
// API-Extractor cannot trim `import { Bar } from "externa-library"` when generating its public rollup,
// API-Extractor cannot trim `import { Bar } from "external-library"` when generating its public rollup,
// or the export of `Foo` would include a broken reference to `Bar`.

@@ -111,0 +111,0 @@ const astImport = entity.astEntity;

9

lib/schemas/api-extractor-template.json

@@ -56,3 +56,3 @@ /**

* of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly
* imports library2. To avoid this, we can specify:
* imports library2. To avoid this, we might specify:
*

@@ -63,2 +63,9 @@ * "bundledPackages": [ "library2" ],

* local files for library1.
*
* The "bundledPackages" elements may specify glob patterns using minimatch syntax. To ensure deterministic
* output, globs are expanded by matching explicitly declared top-level dependencies only. For example,
* the pattern below will NOT match "@my-company/example" unless it appears in a field such as "dependencies"
* or "devDependencies" of the project's package.json file:
*
* "bundledPackages": [ "@my-company/*" ],
*/

@@ -65,0 +72,0 @@ "bundledPackages": [],

2

lib/schemas/api-extractor.schema.json

@@ -27,3 +27,3 @@ {

"bundledPackages": {
"description": "A list of NPM package names whose exports should be treated as part of this package.",
"description": "A list of NPM package names whose exports should be treated as part of this package. Also supports glob patterns.",
"type": "array",

@@ -30,0 +30,0 @@ "items": {

8

package.json
{
"name": "@microsoft/api-extractor",
"version": "7.41.1",
"version": "7.42.0",
"description": "Analyze the exported API for a TypeScript library and generate reviews, documentation, and .d.ts rollups",

@@ -38,2 +38,3 @@ "keywords": [

"lodash": "~4.17.15",
"minimatch": "~3.0.3",
"resolve": "~1.22.1",

@@ -44,6 +45,6 @@ "semver": "~7.5.4",

"@microsoft/api-extractor-model": "7.28.13",
"@rushstack/node-core-library": "4.0.2",
"@rushstack/rig-package": "0.5.2",
"@rushstack/ts-command-line": "4.18.0",
"@rushstack/terminal": "0.10.0",
"@rushstack/ts-command-line": "4.18.0"
"@rushstack/node-core-library": "4.0.2"
},

@@ -55,2 +56,3 @@ "devDependencies": {

"@types/lodash": "4.14.116",
"@types/minimatch": "3.0.5",
"@types/node": "18.17.15",

@@ -57,0 +59,0 @@ "@types/resolve": "1.20.2",

lib/api/ExtractorConfig.d.ts.map

Sorry, the diff of this file is not supported yet

lib/api/ExtractorConfig.js.map

Sorry, the diff of this file is not supported yet

lib/api/IConfigFile.d.ts.map

Sorry, the diff of this file is not supported yet

lib/api/IConfigFile.js.map

Sorry, the diff of this file is not supported yet

lib/collector/ApiItemMetadata.d.ts.map

Sorry, the diff of this file is not supported yet

lib/collector/ApiItemMetadata.js.map

Sorry, the diff of this file is not supported yet

lib/collector/Collector.d.ts.map

Sorry, the diff of this file is not supported yet

lib/collector/Collector.js.map

Sorry, the diff of this file is not supported yet

lib/enhancers/DocCommentEnhancer.d.ts.map

Sorry, the diff of this file is not supported yet

lib/enhancers/DocCommentEnhancer.js.map

Sorry, the diff of this file is not supported yet

lib/generators/DtsRollupGenerator.js.map

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc