Socket
Socket
Sign inDemoInstall

@microsoft/api-extractor

Package Overview
Dependencies
Maintainers
2
Versions
487
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@microsoft/api-extractor - npm Package Compare versions

Comparing version 4.3.4 to 4.3.5

lib/generators/PackageTypingsGenerator.d.ts

22

CHANGELOG.json

@@ -5,2 +5,24 @@ {

{
"version": "4.3.5",
"tag": "@microsoft/api-extractor_v4.3.5",
"date": "Fri, 22 Dec 2017 17:04:46 GMT",
"comments": {
"patch": [
{
"author": "pgonzal <pgonzal@users.noreply.github.com>",
"commit": "e27707503756cbfb2e9332833b987009c32b8198",
"comment": "Fixed an issue where warnings would cause the api-extractor tool to return a nonzero exit code for a \"--local\" build; warnings should not fail the build in this scenario"
}
],
"dependency": [
{
"comment": "Updating dependency \"@microsoft/node-core-library\" from `0.3.21` to `0.3.22`"
},
{
"comment": "Updating dependency \"@microsoft/ts-command-line\" from `2.2.9` to `2.2.10`"
}
]
}
},
{
"version": "4.3.4",

@@ -7,0 +29,0 @@ "tag": "@microsoft/api-extractor_v4.3.4",

9

CHANGELOG.md
# Change Log - @microsoft/api-extractor
This log was last generated on Tue, 12 Dec 2017 03:33:26 GMT and should not be manually modified.
This log was last generated on Fri, 22 Dec 2017 17:04:46 GMT and should not be manually modified.
## 4.3.5
Fri, 22 Dec 2017 17:04:46 GMT
### Patches
- Fixed an issue where warnings would cause the api-extractor tool to return a nonzero exit code for a "--local" build; warnings should not fail the build in this scenario
## 4.3.4

@@ -6,0 +13,0 @@ Tue, 12 Dec 2017 03:33:26 GMT

12

lib/ast/AstItem.d.ts

@@ -271,14 +271,2 @@ import * as ts from 'typescript';

/**
* This traverses any type aliases to find the original place where an item was defined.
* For example, suppose a class is defined as "export default class MyClass { }"
* but exported from the package's index.ts like this:
*
* export { default as _MyClass } from './MyClass';
*
* In this example, calling followAliases() on the _MyClass symbol will return the
* original definition of MyClass, traversing any intermediary places where the
* symbol was imported and re-exported.
*/
protected followAliases(symbol: ts.Symbol): ts.Symbol;
/**
* Reports an error through the ApiErrorHandler interface that was registered with the Extractor,

@@ -285,0 +273,0 @@ * adding the filename and line number information for the declaration of this AstItem.

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

/**
* This traverses any type aliases to find the original place where an item was defined.
* For example, suppose a class is defined as "export default class MyClass { }"
* but exported from the package's index.ts like this:
*
* export { default as _MyClass } from './MyClass';
*
* In this example, calling followAliases() on the _MyClass symbol will return the
* original definition of MyClass, traversing any intermediary places where the
* symbol was imported and re-exported.
*/
followAliases(symbol) {
let current = symbol;
while (true) {
if (!(current.flags & ts.SymbolFlags.Alias)) {
break;
}
const currentAlias = this.typeChecker.getAliasedSymbol(current);
if (!currentAlias || currentAlias === current) {
break;
}
current = currentAlias;
}
return current;
}
/**
* Reports an error through the ApiErrorHandler interface that was registered with the Extractor,

@@ -407,3 +382,3 @@ * adding the filename and line number information for the declaration of this AstItem.

// Follow the aliases all the way to the ending SourceFile
const currentSymbol = this.followAliases(symbol);
const currentSymbol = TypeScriptHelpers_1.default.followAliases(symbol, this.typeChecker);
if (!currentSymbol.declarations || !currentSymbol.declarations.length) {

@@ -410,0 +385,0 @@ // This is a degenerate case that happens sometimes

@@ -8,2 +8,3 @@ "use strict";

const AstItemContainer_1 = require("./AstItemContainer");
const TypeScriptHelpers_1 = require("../TypeScriptHelpers");
const AstStructuredType_1 = require("./AstStructuredType");

@@ -17,3 +18,3 @@ const AstEnum_1 = require("./AstEnum");

processModuleExport(exportSymbol) {
const followedSymbol = this.followAliases(exportSymbol);
const followedSymbol = TypeScriptHelpers_1.default.followAliases(exportSymbol, this.typeChecker);
if (!followedSymbol.declarations) {

@@ -20,0 +21,0 @@ // This is an API Extractor bug, but it could happen e.g. if we upgrade to a new

@@ -10,2 +10,3 @@ "use strict";

const AstModule_1 = require("./AstModule");
const TypeScriptHelpers_1 = require("../TypeScriptHelpers");
const allowedTypes = ['string', 'number', 'boolean'];

@@ -44,3 +45,3 @@ /**

for (const exportSymbol of exportSymbols) {
const followedSymbol = this.followAliases(exportSymbol);
const followedSymbol = TypeScriptHelpers_1.default.followAliases(exportSymbol, this.typeChecker);
if (!followedSymbol.declarations) {

@@ -47,0 +48,0 @@ // This is an API Extractor bug, but it could happen e.g. if we upgrade to a new

@@ -21,12 +21,10 @@ "use strict";

this.name = context.packageName;
const exportSymbols = this.typeChecker.getExportsOfModule(this.declarationSymbol);
if (exportSymbols) {
for (const exportSymbol of exportSymbols) {
this.processModuleExport(exportSymbol);
const followedSymbol = this.followAliases(exportSymbol);
this._exportedNormalizedSymbols.push({
exportedName: exportSymbol.name,
followedSymbol: followedSymbol
});
}
const exportSymbols = this.typeChecker.getExportsOfModule(this.declarationSymbol) || [];
for (const exportSymbol of exportSymbols) {
this.processModuleExport(exportSymbol);
const followedSymbol = TypeScriptHelpers_1.default.followAliases(exportSymbol, this.typeChecker);
this._exportedNormalizedSymbols.push({
exportedName: exportSymbol.name,
followedSymbol: followedSymbol
});
}

@@ -70,3 +68,3 @@ }

tryGetExportedSymbolName(symbol) {
const followedSymbol = this.followAliases(symbol);
const followedSymbol = TypeScriptHelpers_1.default.followAliases(symbol, this.typeChecker);
for (const exportedSymbol of this._exportedNormalizedSymbols) {

@@ -73,0 +71,0 @@ if (exportedSymbol.followedSymbol === followedSymbol) {

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

}
for (const memberDeclaration of this._classLikeDeclaration.members) {
for (const memberDeclaration of this._classLikeDeclaration.members || []) {
const memberSymbol = TypeScriptHelpers_1.default.tryGetSymbolForDeclaration(memberDeclaration);

@@ -38,0 +38,0 @@ if (memberSymbol) {

@@ -6,21 +6,51 @@ "use strict";

// NOTE: THIS SOURCE FILE IS FOR DEBUGGING PURPOSES ONLY.
// IT IS INVOKED BY THE "Run.cmd" AND "Debug.cmd" BATCH FILES.
// IT IS INVOKED BY THE 'Run.cmd' AND 'Debug.cmd' BATCH FILES.
const Extractor_1 = require("./extractor/Extractor");
const path = require("path");
const extractor = new Extractor_1.Extractor({
compiler: {
configType: 'tsconfig',
rootFolder: '.'
overrideTsconfig: {
'compilerOptions': {
'target': 'es6',
'forceConsistentCasingInFileNames': true,
'module': 'commonjs',
'declaration': true,
'sourceMap': true,
'experimentalDecorators': true,
'types': [
'node'
],
'lib': [
'es5',
'scripthost',
'es2015.collection',
'es2015.promise',
'es2015.iterable',
'dom'
],
'strictNullChecks': true
},
'include': ['lib/**/*.d.ts']
},
rootFolder: '../../libraries/node-core-library'
},
project: {
entryPointSourceFile: 'src/index.ts',
externalJsonFileFolders: ['./testInputs/external-api-json']
entryPointSourceFile: 'lib/index.d.ts',
externalJsonFileFolders: []
},
apiReviewFile: {
enabled: false,
apiReviewFolder: path.join(__dirname, 'debug')
},
apiJsonFile: {
enabled: true,
apiReviewFolder: __dirname
outputFolder: path.join(__dirname, 'debug')
},
apiJsonFile: {
enabled: true
packageTypings: {
enabled: true,
outputFolder: path.join(__dirname, 'debug')
}
});
console.log('CONFIG:' + JSON.stringify(extractor.actualConfig, undefined, ' '));
if (!extractor.processProject()) {

@@ -27,0 +57,0 @@ console.log('processProject() failed the build');

@@ -23,3 +23,11 @@ {

"outputFolder": "./dist"
},
"packageTypings": {
"enabled": false,
"outputFolder": "./dist",
"dtsFilePathForInternal": "index-internal.d.ts",
"dtsFilePathForPreview": "index-preview.d.ts",
"dtsFilePathForPublic": "index-public.d.ts"
}
}

@@ -116,2 +116,31 @@ {

"additionalProperties": false
},
"packageTypings": {
"description": "Configures how the package typings (*.d.ts) will be generated.",
"type": "object",
"properties": {
"enabled": {
"description": "Whether to generate package typings. The default is false.",
"type": "boolean"
},
"outputFolder": {
"description": "Specifies where the *.d.ts files should be written. The default value is \"./dist\"",
"type": "string"
},
"dtsFilePathForInternal": {
"description": "Specifies the output filename for an internal release. The default value is \"index-internal.d.ts\". If the path is not an absolute path, it will be resolved relative to the outputFolder. This file will contain all definitions that are reachable from the entry point.",
"type": "string"
},
"dtsFilePathForPreview": {
"description": "Specifies the output filename for a preview release. The default value is \"index-preview.d.ts\". If the path is not an absolute path, it will be resolved relative to the outputFolder. This file will contain all definitions that are reachable from the entry point, except definitions marked as @alpha or @internal",
"type": "string"
},
"dtsFilePathForPublic": {
"description": "Specifies the output filename for a public release. The default value is \"index-public.d.ts\". If the path is not an absolute path, it will be resolved relative to the outputFolder. This file will contain all definitions that are reachable from the entry point, except definitions marked as @beta, @alpha, or @internal.",
"type": "string"
}
},
"required": [ "enabled" ],
"additionalProperties": false
}

@@ -118,0 +147,0 @@ },

@@ -52,3 +52,3 @@ import * as ts from 'typescript';

private static _defaultLogger;
private readonly _config;
private readonly _actualConfig;
private readonly _program;

@@ -61,2 +61,11 @@ private readonly _localBuild;

/**
* Returns the normalized configuration object after defaults have been applied.
*
* @remarks
* This is a read-only object. The caller should NOT modify any member of this object.
* It is provided for diagnostic purposes. For example, a build script could write
* this object to a JSON file to report the final configuration options used by API Extractor.
*/
readonly actualConfig: IExtractorConfig;
/**
* Invokes the API Extractor engine, using the configuration that was passed to the constructor.

@@ -70,3 +79,9 @@ * @deprecated Use {@link Extractor.processProject} instead.

* config file.
* @returns true if there were no errors or warnings; false if the tool chain should fail the build
* @returns true for a successful build, or false if the tool chain should fail the build
*
* @remarks
*
* This function returns false to indicate that the build failed, i.e. the command-line tool
* would return a nonzero exit code. Normally the build fails if there are any errors or
* warnings; however, if options.localBuild=true then warnings are ignored.
*/

@@ -73,0 +88,0 @@ processProject(options?: IAnalyzeProjectOptions): boolean;

@@ -14,2 +14,3 @@ "use strict";

const ApiFileGenerator_1 = require("../generators/ApiFileGenerator");
const PackageTypingsGenerator_1 = require("../generators/PackageTypingsGenerator");
const MonitoredLogger_1 = require("./MonitoredLogger");

@@ -30,4 +31,3 @@ /**

this._monitoredLogger = new MonitoredLogger_1.MonitoredLogger(mergedLogger);
this._config = Extractor._applyConfigDefaults(config);
this._monitoredLogger.logVerbose('API Extractor Config: ' + JSON.stringify(this._config));
this._actualConfig = Extractor._applyConfigDefaults(config);
if (!options) {

@@ -37,5 +37,5 @@ options = {};

this._localBuild = options.localBuild || false;
switch (this._config.compiler.configType) {
switch (this._actualConfig.compiler.configType) {
case 'tsconfig':
const rootFolder = this._config.compiler.rootFolder;
const rootFolder = this._actualConfig.compiler.rootFolder;
if (!fsx.existsSync(rootFolder)) {

@@ -45,3 +45,3 @@ throw new Error('The root folder does not exist: ' + rootFolder);

this._absoluteRootFolder = path.normalize(path.resolve(rootFolder));
let tsconfig = this._config.compiler.overrideTsconfig;
let tsconfig = this._actualConfig.compiler.overrideTsconfig;
if (!tsconfig) {

@@ -82,2 +82,13 @@ // If it wasn't overridden, then load it from disk

/**
* Returns the normalized configuration object after defaults have been applied.
*
* @remarks
* This is a read-only object. The caller should NOT modify any member of this object.
* It is provided for diagnostic purposes. For example, a build script could write
* this object to a JSON file to report the final configuration options used by API Extractor.
*/
get actualConfig() {
return this._actualConfig;
}
/**
* Invokes the API Extractor engine, using the configuration that was passed to the constructor.

@@ -93,3 +104,9 @@ * @deprecated Use {@link Extractor.processProject} instead.

* config file.
* @returns true if there were no errors or warnings; false if the tool chain should fail the build
* @returns true for a successful build, or false if the tool chain should fail the build
*
* @remarks
*
* This function returns false to indicate that the build failed, i.e. the command-line tool
* would return a nonzero exit code. Normally the build fails if there are any errors or
* warnings; however, if options.localBuild=true then warnings are ignored.
*/

@@ -102,6 +119,7 @@ processProject(options) {

const projectConfig = options.projectConfig ?
options.projectConfig : this._config.project;
options.projectConfig : this._actualConfig.project;
// This helps strict-null-checks to understand that _applyConfigDefaults() eliminated
// any undefined members
if (!(this._config.policies && this._config.apiJsonFile && this._config.apiReviewFile)) {
if (!(this._actualConfig.policies && this._actualConfig.apiJsonFile && this._actualConfig.apiReviewFile
&& this._actualConfig.packageTypings)) {
throw new Error('The configuration object wasn\'t normalized properly');

@@ -113,3 +131,3 @@ }

logger: this._monitoredLogger,
policies: this._config.policies
policies: this._actualConfig.policies
});

@@ -120,17 +138,17 @@ for (const externalJsonFileFolder of projectConfig.externalJsonFileFolders || []) {

const packageBaseName = path.basename(context.packageName);
const apiJsonFileConfig = this._config.apiJsonFile;
const apiJsonFileConfig = this._actualConfig.apiJsonFile;
if (apiJsonFileConfig.enabled) {
const outputFolder = path.resolve(this._absoluteRootFolder, apiJsonFileConfig.outputFolder);
fsx.mkdirsSync(outputFolder);
const jsonGenerator = new ApiJsonGenerator_1.default();
const apiJsonFilename = path.join(outputFolder, packageBaseName + '.api.json');
this._monitoredLogger.logVerbose('Writing: ' + apiJsonFilename);
fsx.mkdirsSync(path.dirname(apiJsonFilename));
jsonGenerator.writeJsonFile(apiJsonFilename, context);
}
if (this._config.apiReviewFile.enabled) {
if (this._actualConfig.apiReviewFile.enabled) {
const generator = new ApiFileGenerator_1.default();
const apiReviewFilename = packageBaseName + '.api.ts';
const actualApiReviewPath = path.resolve(this._absoluteRootFolder, this._config.apiReviewFile.tempFolder, apiReviewFilename);
const actualApiReviewPath = path.resolve(this._absoluteRootFolder, this._actualConfig.apiReviewFile.tempFolder, apiReviewFilename);
const actualApiReviewShortPath = this._getShortFilePath(actualApiReviewPath);
const expectedApiReviewPath = path.resolve(this._absoluteRootFolder, this._config.apiReviewFile.apiReviewFolder, apiReviewFilename);
const expectedApiReviewPath = path.resolve(this._absoluteRootFolder, this._actualConfig.apiReviewFile.apiReviewFolder, apiReviewFilename);
const expectedApiReviewShortPath = this._getShortFilePath(expectedApiReviewPath);

@@ -172,4 +190,17 @@ const actualApiReviewContent = generator.generateApiFileContent(context);

}
// If there were any errors or warnings, then fail the build
return (this._monitoredLogger.errorCount + this._monitoredLogger.warningCount) === 0;
if (this._actualConfig.packageTypings.enabled) {
const packageTypingsGenerator = new PackageTypingsGenerator_1.default(context);
const dtsFilename = path.resolve(this._absoluteRootFolder, this._actualConfig.packageTypings.outputFolder, this._actualConfig.packageTypings.dtsFilePathForInternal);
this._monitoredLogger.logVerbose(`Writing package typings: ${dtsFilename}`);
fsx.mkdirsSync(path.dirname(dtsFilename));
packageTypingsGenerator.writeTypingsFile(dtsFilename);
}
if (this._localBuild) {
// For a local build, fail if there were errors (but ignore warnings)
return this._monitoredLogger.errorCount === 0;
}
else {
// For a production build, fail if there were any errors or warnings
return (this._monitoredLogger.errorCount + this._monitoredLogger.warningCount) === 0;
}
}

@@ -176,0 +207,0 @@ _getShortFilePath(absolutePath) {

@@ -131,2 +131,52 @@ /**

/**
* Configures how the package typings (*.d.ts) will be generated.
* @remarks
* API Extractor can generate a single unified *.d.ts file that contains all
* the exported typings for the package entry point. It can also remove
* \@alpha \@beta \@internal definitions depending on the release type.
*
* @beta
*/
export interface IExtractorPackageTypingsConfig {
/**
* Whether to generate package typings. The default is false.
*/
enabled: boolean;
/**
* Specifies where the *.d.ts files should be written.
*
* The default value is "./dist"
*/
outputFolder?: string;
/**
* Specifies the *.d.ts file path used for an internal release.
* The default value is "index-internal.d.ts".
*
* @remarks
* If the path is not an absolute path, it will be resolved relative to the outputFolder.
* This output file will contain all definitions that are reachable from the entry point.
*/
dtsFilePathForInternal?: string;
/**
* Specifies the output filename for a preview release.
* The default value is "index-preview.d.ts".
*
* @remarks
* If the path is not an absolute path, it will be resolved relative to the outputFolder.
* This output file will contain all definitions that are reachable from the entry point,
* except definitions marked as \@alpha or \@internal.
*/
dtsFilePathForPreview?: string;
/**
* Specifies the output filename for a public release.
* The default value is "index-public.d.ts".
*
* @remarks
* If the path is not an absolute path, it will be resolved relative to the outputFolder.
* This output file will contain all definitions that are reachable from the entry point,
* except definitions marked as \@beta, \@alpha, or \@internal.
*/
dtsFilePathForPublic?: string;
}
/**
* Configuration options for the API Extractor tool. These options can be loaded

@@ -160,2 +210,7 @@ * from a JSON config file.

apiJsonFile?: IExtractorApiJsonFileConfig;
/**
* {@inheritdoc IExtractorPackageTypingsConfig}
* @beta
*/
packageTypings?: IExtractorPackageTypingsConfig;
}
export { default as ExternalApiHelper } from './ExternalApiHelper';
export { Extractor, IAnalyzeProjectOptions, IExtractorOptions } from './extractor/Extractor';
export { IExtractorTsconfigCompilerConfig, IExtractorRuntimeCompilerConfig, IExtractorProjectConfig, IExtractorPoliciesConfig, IExtractorApiReviewFileConfig, IExtractorApiJsonFileConfig, IExtractorConfig } from './extractor/IExtractorConfig';
export { IExtractorTsconfigCompilerConfig, IExtractorRuntimeCompilerConfig, IExtractorProjectConfig, IExtractorPoliciesConfig, IExtractorApiReviewFileConfig, IExtractorApiJsonFileConfig, IExtractorPackageTypingsConfig, IExtractorConfig } from './extractor/IExtractorConfig';
export { ILogger } from './extractor/ILogger';

@@ -5,0 +5,0 @@ export * from './api/ApiItem';

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

/**
* This traverses any type aliases to find the original place where an item was defined.
* For example, suppose a class is defined as "export default class MyClass { }"
* but exported from the package's index.ts like this:
*
* export { default as _MyClass } from './MyClass';
*
* In this example, calling followAliases() on the _MyClass symbol will return the
* original definition of MyClass, traversing any intermediary places where the
* symbol was imported and re-exported.
*/
static followAliases(symbol: ts.Symbol, typeChecker: ts.TypeChecker): ts.Symbol;
static getImmediateAliasedSymbol(symbol: ts.Symbol, typeChecker: ts.TypeChecker): ts.Symbol;
/**
* Returns the Symbol for the provided Declaration. This is a workaround for a missing

@@ -22,0 +35,0 @@ * feature of the TypeScript Compiler API. It is the only apparent way to reach

@@ -5,5 +5,35 @@ "use strict";

Object.defineProperty(exports, "__esModule", { value: true });
/* tslint:disable:no-bitwise */
const ts = require("typescript");
const PrettyPrinter_1 = require("./PrettyPrinter");
class TypeScriptHelpers {
/**
* This traverses any type aliases to find the original place where an item was defined.
* For example, suppose a class is defined as "export default class MyClass { }"
* but exported from the package's index.ts like this:
*
* export { default as _MyClass } from './MyClass';
*
* In this example, calling followAliases() on the _MyClass symbol will return the
* original definition of MyClass, traversing any intermediary places where the
* symbol was imported and re-exported.
*/
static followAliases(symbol, typeChecker) {
let current = symbol;
while (true) {
if (!(current.flags & ts.SymbolFlags.Alias)) {
break;
}
const currentAlias = typeChecker.getAliasedSymbol(current);
if (!currentAlias || currentAlias === current) {
break;
}
current = currentAlias;
}
return current;
}
static getImmediateAliasedSymbol(symbol, typeChecker) {
return typeChecker.getImmediateAliasedSymbol(symbol); // tslint:disable-line:no-any
}
/**
* Returns the Symbol for the provided Declaration. This is a workaround for a missing

@@ -10,0 +40,0 @@ * feature of the TypeScript Compiler API. It is the only apparent way to reach

{
"name": "@microsoft/api-extractor",
"version": "4.3.4",
"version": "4.3.5",
"description": "Validate, document, and review the exported API for a TypeScript library",

@@ -31,4 +31,4 @@ "keywords": [

"dependencies": {
"@microsoft/node-core-library": "0.3.21",
"@microsoft/ts-command-line": "2.2.9",
"@microsoft/node-core-library": "0.3.22",
"@microsoft/ts-command-line": "2.2.10",
"@types/fs-extra": "0.0.37",

@@ -35,0 +35,0 @@ "@types/node": "6.0.88",

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

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

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc