@microsoft/api-extractor 7.40.6 → 7.41.0
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.
- package/dist/rollup.d.ts +4 -4
- package/dist/tsdoc-metadata.json +1 -1
- package/lib/aedoc/PackageDocComment.js +2 -1
- package/lib/aedoc/PackageDocComment.js.map +1 -1
- package/lib/analyzer/PackageMetadataManager.js +2 -1
- package/lib/analyzer/PackageMetadataManager.js.map +1 -1
- package/lib/api/ConsoleMessageId.d.ts +1 -1
- package/lib/api/ConsoleMessageId.d.ts.map +1 -1
- package/lib/api/ConsoleMessageId.js +71 -0
- package/lib/api/ConsoleMessageId.js.map +1 -1
- package/lib/api/Extractor.js +12 -11
- package/lib/api/Extractor.js.map +1 -1
- package/lib/api/ExtractorLogLevel.d.ts +1 -1
- package/lib/api/ExtractorLogLevel.d.ts.map +1 -1
- package/lib/api/ExtractorLogLevel.js +44 -0
- package/lib/api/ExtractorLogLevel.js.map +1 -1
- package/lib/api/ExtractorMessage.d.ts +1 -1
- package/lib/api/ExtractorMessage.d.ts.map +1 -1
- package/lib/api/ExtractorMessage.js +48 -7
- package/lib/api/ExtractorMessage.js.map +1 -1
- package/lib/api/ExtractorMessageId.d.ts +1 -1
- package/lib/api/ExtractorMessageId.d.ts.map +1 -1
- package/lib/api/ExtractorMessageId.js +106 -1
- package/lib/api/ExtractorMessageId.js.map +1 -1
- package/lib/collector/Collector.js +8 -7
- package/lib/collector/Collector.js.map +1 -1
- package/lib/collector/MessageRouter.js +30 -28
- package/lib/collector/MessageRouter.js.map +1 -1
- package/lib/enhancers/DocCommentEnhancer.js +5 -4
- package/lib/enhancers/DocCommentEnhancer.js.map +1 -1
- package/lib/enhancers/ValidationEnhancer.js +6 -5
- package/lib/enhancers/ValidationEnhancer.js.map +1 -1
- package/lib/generators/ApiReportGenerator.js +2 -1
- package/lib/generators/ApiReportGenerator.js.map +1 -1
- package/lib/index.js +15 -1
- package/lib/index.js.map +1 -1
- package/package.json +5 -5
|
@@ -2,8 +2,49 @@
|
|
|
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
4
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
5
|
-
exports.ExtractorMessage = void 0;
|
|
5
|
+
exports.ExtractorMessage = exports.ExtractorMessageCategory = void 0;
|
|
6
|
+
const ExtractorLogLevel_1 = require("./ExtractorLogLevel");
|
|
6
7
|
const SourceFileLocationFormatter_1 = require("../analyzer/SourceFileLocationFormatter");
|
|
8
|
+
/**
|
|
9
|
+
* Specifies a category of messages for use with {@link ExtractorMessage}.
|
|
10
|
+
* @public
|
|
11
|
+
*/
|
|
12
|
+
var ExtractorMessageCategory;
|
|
13
|
+
(function (ExtractorMessageCategory) {
|
|
14
|
+
/**
|
|
15
|
+
* Messages originating from the TypeScript compiler.
|
|
16
|
+
*
|
|
17
|
+
* @remarks
|
|
18
|
+
* These strings begin with the prefix "TS" and have a numeric error code.
|
|
19
|
+
* Example: `TS2551`
|
|
20
|
+
*/
|
|
21
|
+
ExtractorMessageCategory["Compiler"] = "Compiler";
|
|
22
|
+
/**
|
|
23
|
+
* Messages related to parsing of TSDoc comments.
|
|
24
|
+
*
|
|
25
|
+
* @remarks
|
|
26
|
+
* These strings begin with the prefix "tsdoc-".
|
|
27
|
+
* Example: `tsdoc-link-tag-unescaped-text`
|
|
28
|
+
*/
|
|
29
|
+
ExtractorMessageCategory["TSDoc"] = "TSDoc";
|
|
30
|
+
/**
|
|
31
|
+
* Messages related to API Extractor's analysis.
|
|
32
|
+
*
|
|
33
|
+
* @remarks
|
|
34
|
+
* These strings begin with the prefix "ae-".
|
|
35
|
+
* Example: `ae-extra-release-tag`
|
|
36
|
+
*/
|
|
37
|
+
ExtractorMessageCategory["Extractor"] = "Extractor";
|
|
38
|
+
/**
|
|
39
|
+
* Console messages communicate the progress of the overall operation. They may include newlines to ensure
|
|
40
|
+
* nice formatting. They are output in real time, and cannot be routed to the API Report file.
|
|
41
|
+
*
|
|
42
|
+
* @remarks
|
|
43
|
+
* These strings begin with the prefix "console-".
|
|
44
|
+
* Example: `console-writing-typings-file`
|
|
45
|
+
*/
|
|
46
|
+
ExtractorMessageCategory["Console"] = "console";
|
|
47
|
+
})(ExtractorMessageCategory || (exports.ExtractorMessageCategory = ExtractorMessageCategory = {}));
|
|
7
48
|
/**
|
|
8
49
|
* This object is used to report an error or warning that occurred during API Extractor's analysis.
|
|
9
50
|
*
|
|
@@ -20,7 +61,7 @@ class ExtractorMessage {
|
|
|
20
61
|
this.sourceFileColumn = options.sourceFileColumn;
|
|
21
62
|
this.properties = options.properties || {};
|
|
22
63
|
this._handled = false;
|
|
23
|
-
this._logLevel = options.logLevel ||
|
|
64
|
+
this._logLevel = options.logLevel || ExtractorLogLevel_1.ExtractorLogLevel.None;
|
|
24
65
|
}
|
|
25
66
|
/**
|
|
26
67
|
* If the {@link IExtractorInvokeOptions.messageCallback} sets this property to true, it will prevent the message
|
|
@@ -61,11 +102,11 @@ class ExtractorMessage {
|
|
|
61
102
|
}
|
|
62
103
|
set logLevel(value) {
|
|
63
104
|
switch (value) {
|
|
64
|
-
case
|
|
65
|
-
case
|
|
66
|
-
case
|
|
67
|
-
case
|
|
68
|
-
case
|
|
105
|
+
case ExtractorLogLevel_1.ExtractorLogLevel.Error:
|
|
106
|
+
case ExtractorLogLevel_1.ExtractorLogLevel.Info:
|
|
107
|
+
case ExtractorLogLevel_1.ExtractorLogLevel.None:
|
|
108
|
+
case ExtractorLogLevel_1.ExtractorLogLevel.Verbose:
|
|
109
|
+
case ExtractorLogLevel_1.ExtractorLogLevel.Warning:
|
|
69
110
|
break;
|
|
70
111
|
default:
|
|
71
112
|
throw new Error('Invalid log level');
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ExtractorMessage.js","sourceRoot":"","sources":["../../src/api/ExtractorMessage.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;
|
|
1
|
+
{"version":3,"file":"ExtractorMessage.js","sourceRoot":"","sources":["../../src/api/ExtractorMessage.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAI3D,2DAAwD;AAExD,yFAAsF;AAmBtF;;;GAGG;AACH,IAAY,wBAqCX;AArCD,WAAY,wBAAwB;IAClC;;;;;;OAMG;IACH,iDAAqB,CAAA;IAErB;;;;;;OAMG;IACH,2CAAe,CAAA;IAEf;;;;;;OAMG;IACH,mDAAuB,CAAA;IAEvB;;;;;;;OAOG;IACH,+CAAmB,CAAA;AACrB,CAAC,EArCW,wBAAwB,wCAAxB,wBAAwB,QAqCnC;AAgBD;;;;GAIG;AACH,MAAa,gBAAgB;IA2C3B,gBAAgB;IAChB,YAAmB,OAAiC;QAClD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAC7C,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAC7C,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;QACjD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;QAE3C,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACtB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,QAAQ,IAAI,qCAAiB,CAAC,IAAI,CAAC;IAC9D,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAW,OAAO;QAChB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,IAAW,OAAO,CAAC,KAAc;QAC/B,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,KAAK,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACb,yFAAyF,CAC1F,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;IACxB,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,IAAW,QAAQ;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,IAAW,QAAQ,CAAC,KAAwB;QAC1C,QAAQ,KAAK,EAAE,CAAC;YACd,KAAK,qCAAiB,CAAC,KAAK,CAAC;YAC7B,KAAK,qCAAiB,CAAC,IAAI,CAAC;YAC5B,KAAK,qCAAiB,CAAC,IAAI,CAAC;YAC5B,KAAK,qCAAiB,CAAC,OAAO,CAAC;YAC/B,KAAK,qCAAiB,CAAC,OAAO;gBAC5B,MAAM;YACR;gBACE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACzC,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;IACzB,CAAC;IAED;;;;;;;OAOG;IACI,yBAAyB,CAAC,wBAA4C;QAC3E,IAAI,MAAM,GAAW,EAAE,CAAC;QAExB,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,MAAM,IAAI,yDAA2B,CAAC,UAAU,CAAC,IAAI,CAAC,cAAc,EAAE;gBACpE,cAAc,EAAE,IAAI,CAAC,cAAc;gBACnC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;gBACvC,wBAAwB;aACzB,CAAC,CAAC;YAEH,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtB,MAAM,IAAI,KAAK,CAAC;YAClB,CAAC;QACH,CAAC;QAED,MAAM,IAAI,IAAI,CAAC,4BAA4B,EAAE,CAAC;QAE9C,OAAO,MAAM,CAAC;IAChB,CAAC;IAEM,4BAA4B;QACjC,OAAO,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5C,CAAC;CACF;AAhJD,4CAgJC","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 type * as tsdoc from '@microsoft/tsdoc';\nimport type { ExtractorMessageId } from './ExtractorMessageId';\nimport { ExtractorLogLevel } from './ExtractorLogLevel';\nimport type { ConsoleMessageId } from './ConsoleMessageId';\nimport { SourceFileLocationFormatter } from '../analyzer/SourceFileLocationFormatter';\n\n/**\n * Used by {@link ExtractorMessage.properties}.\n *\n * @public\n */\nexport interface IExtractorMessageProperties {\n /**\n * A declaration can have multiple names if it is exported more than once.\n * If an `ExtractorMessage` applies to a specific export name, this property can indicate that.\n *\n * @remarks\n *\n * Used by {@link ExtractorMessageId.InternalMissingUnderscore}.\n */\n readonly exportName?: string;\n}\n\n/**\n * Specifies a category of messages for use with {@link ExtractorMessage}.\n * @public\n */\nexport enum ExtractorMessageCategory {\n /**\n * Messages originating from the TypeScript compiler.\n *\n * @remarks\n * These strings begin with the prefix \"TS\" and have a numeric error code.\n * Example: `TS2551`\n */\n Compiler = 'Compiler',\n\n /**\n * Messages related to parsing of TSDoc comments.\n *\n * @remarks\n * These strings begin with the prefix \"tsdoc-\".\n * Example: `tsdoc-link-tag-unescaped-text`\n */\n TSDoc = 'TSDoc',\n\n /**\n * Messages related to API Extractor's analysis.\n *\n * @remarks\n * These strings begin with the prefix \"ae-\".\n * Example: `ae-extra-release-tag`\n */\n Extractor = 'Extractor',\n\n /**\n * Console messages communicate the progress of the overall operation. They may include newlines to ensure\n * nice formatting. They are output in real time, and cannot be routed to the API Report file.\n *\n * @remarks\n * These strings begin with the prefix \"console-\".\n * Example: `console-writing-typings-file`\n */\n Console = 'console'\n}\n\n/**\n * Constructor options for `ExtractorMessage`.\n */\nexport interface IExtractorMessageOptions {\n category: ExtractorMessageCategory;\n messageId: tsdoc.TSDocMessageId | ExtractorMessageId | ConsoleMessageId | string;\n text: string;\n sourceFilePath?: string;\n sourceFileLine?: number;\n sourceFileColumn?: number;\n properties?: IExtractorMessageProperties;\n logLevel?: ExtractorLogLevel;\n}\n\n/**\n * This object is used to report an error or warning that occurred during API Extractor's analysis.\n *\n * @public\n */\nexport class ExtractorMessage {\n private _handled: boolean;\n private _logLevel: ExtractorLogLevel;\n\n /**\n * The category of issue.\n */\n public readonly category: ExtractorMessageCategory;\n\n /**\n * A text string that uniquely identifies the issue type. This identifier can be used to suppress\n * or configure the reporting of issues, and also to search for help about an issue.\n */\n public readonly messageId: tsdoc.TSDocMessageId | ExtractorMessageId | ConsoleMessageId | string;\n\n /**\n * The text description of this issue.\n */\n public readonly text: string;\n\n /**\n * The absolute path to the affected input source file, if there is one.\n */\n public readonly sourceFilePath: string | undefined;\n\n /**\n * The line number where the issue occurred in the input source file. This is not used if `sourceFilePath`\n * is undefined. The first line number is 1.\n */\n public readonly sourceFileLine: number | undefined;\n\n /**\n * The column number where the issue occurred in the input source file. This is not used if `sourceFilePath`\n * is undefined. The first column number is 1.\n */\n public readonly sourceFileColumn: number | undefined;\n\n /**\n * Additional contextual information about the message that may be useful when reporting errors.\n * All properties are optional.\n */\n public readonly properties: IExtractorMessageProperties;\n\n /** @internal */\n public constructor(options: IExtractorMessageOptions) {\n this.category = options.category;\n this.messageId = options.messageId;\n this.text = options.text;\n this.sourceFilePath = options.sourceFilePath;\n this.sourceFileLine = options.sourceFileLine;\n this.sourceFileColumn = options.sourceFileColumn;\n this.properties = options.properties || {};\n\n this._handled = false;\n this._logLevel = options.logLevel || ExtractorLogLevel.None;\n }\n\n /**\n * If the {@link IExtractorInvokeOptions.messageCallback} sets this property to true, it will prevent the message\n * from being displayed by API Extractor.\n *\n * @remarks\n * If the `messageCallback` routes the message to a custom handler (e.g. a toolchain logger), it should\n * assign `handled = true` to prevent API Extractor from displaying it. Assigning `handled = true` for all messages\n * would effectively disable all console output from the `Extractor` API.\n *\n * If `handled` is set to true, the message will still be included in the count of errors/warnings;\n * to discard a message entirely, instead assign `logLevel = none`.\n */\n public get handled(): boolean {\n return this._handled;\n }\n\n public set handled(value: boolean) {\n if (this._handled && !value) {\n throw new Error(\n 'One a message has been marked as handled, the \"handled\" property cannot be set to false'\n );\n }\n this._handled = value;\n }\n\n /**\n * Specifies how the message should be reported.\n *\n * @remarks\n * If the {@link IExtractorInvokeOptions.messageCallback} handles the message (i.e. sets `handled = true`),\n * it can use the `logLevel` to determine how to display the message.\n *\n * Alternatively, if API Extractor is handling the message, the `messageCallback` could assign `logLevel` to change\n * how it will be processed. However, in general the recommended practice is to configure message routing\n * using the `messages` section in api-extractor.json.\n *\n * To discard a message entirely, assign `logLevel = none`.\n */\n public get logLevel(): ExtractorLogLevel {\n return this._logLevel;\n }\n\n public set logLevel(value: ExtractorLogLevel) {\n switch (value) {\n case ExtractorLogLevel.Error:\n case ExtractorLogLevel.Info:\n case ExtractorLogLevel.None:\n case ExtractorLogLevel.Verbose:\n case ExtractorLogLevel.Warning:\n break;\n default:\n throw new Error('Invalid log level');\n }\n this._logLevel = value;\n }\n\n /**\n * Returns the message formatted with its identifier and file position.\n * @remarks\n * Example:\n * ```\n * src/folder/File.ts:123:4 - (ae-extra-release-tag) The doc comment should not contain more than one release tag.\n * ```\n */\n public formatMessageWithLocation(workingPackageFolderPath: string | undefined): string {\n let result: string = '';\n\n if (this.sourceFilePath) {\n result += SourceFileLocationFormatter.formatPath(this.sourceFilePath, {\n sourceFileLine: this.sourceFileLine,\n sourceFileColumn: this.sourceFileColumn,\n workingPackageFolderPath\n });\n\n if (result.length > 0) {\n result += ' - ';\n }\n }\n\n result += this.formatMessageWithoutLocation();\n\n return result;\n }\n\n public formatMessageWithoutLocation(): string {\n return `(${this.messageId}) ${this.text}`;\n }\n}\n"]}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ExtractorMessageId.d.ts","sourceRoot":"","sources":["../../src/api/ExtractorMessageId.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,
|
|
1
|
+
{"version":3,"file":"ExtractorMessageId.d.ts","sourceRoot":"","sources":["../../src/api/ExtractorMessageId.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,oBAAY,kBAAkB;IAC5B;;OAEG;IACH,eAAe,yBAAyB;IAExC;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,oBAAoB;IAEhC;;OAEG;IACH,oBAAoB,8BAA8B;IAElD;;OAEG;IACH,uBAAuB,iCAAiC;IAExD;;OAEG;IACH,iBAAiB,2BAA2B;IAE5C;;OAEG;IACH,mBAAmB,6BAA6B;IAEhD;;OAEG;IACH,eAAe,wBAAwB;IAEvC;;OAEG;IACH,yBAAyB,mCAAmC;IAE5D;;OAEG;IACH,uBAAuB,kCAAkC;IAEzD;;OAEG;IACH,0BAA0B,oCAAoC;IAE9D;;OAEG;IACH,wBAAwB,mCAAmC;IAE3D;;OAEG;IACH,6BAA6B,uCAAuC;IAEpE;;;;;;;OAOG;IACH,wBAAwB,kCAAkC;IAE1D;;OAEG;IACH,gBAAgB,0BAA0B;IAE1C;;OAEG;IACH,cAAc,uBAAuB;IAErC;;OAEG;IACH,cAAc,wBAAwB;IAEtC;;OAEG;IACH,aAAa,sBAAsB;IAEnC;;;OAGG;IACH,kBAAkB,6BAA6B;CAChD;AAED,eAAO,MAAM,sBAAsB,EAAE,GAAG,CAAC,MAAM,CAmB7C,CAAC"}
|
|
@@ -2,7 +2,112 @@
|
|
|
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
4
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
5
|
-
exports.allExtractorMessageIds = void 0;
|
|
5
|
+
exports.allExtractorMessageIds = exports.ExtractorMessageId = void 0;
|
|
6
|
+
/**
|
|
7
|
+
* Unique identifiers for messages reported by API Extractor during its analysis.
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
*
|
|
11
|
+
* These strings are possible values for the {@link ExtractorMessage.messageId} property
|
|
12
|
+
* when the `ExtractorMessage.category` is {@link ExtractorMessageCategory.Extractor}.
|
|
13
|
+
*
|
|
14
|
+
* @public
|
|
15
|
+
*/
|
|
16
|
+
var ExtractorMessageId;
|
|
17
|
+
(function (ExtractorMessageId) {
|
|
18
|
+
/**
|
|
19
|
+
* "The doc comment should not contain more than one release tag."
|
|
20
|
+
*/
|
|
21
|
+
ExtractorMessageId["ExtraReleaseTag"] = "ae-extra-release-tag";
|
|
22
|
+
/**
|
|
23
|
+
* "Missing documentation for ___."
|
|
24
|
+
* @remarks
|
|
25
|
+
* The `ae-undocumented` message is only generated if the API report feature is enabled.
|
|
26
|
+
*
|
|
27
|
+
* Because the API report file already annotates undocumented items with `// (undocumented)`,
|
|
28
|
+
* the `ae-undocumented` message is not logged by default. To see it, add a setting such as:
|
|
29
|
+
* ```json
|
|
30
|
+
* "messages": {
|
|
31
|
+
* "extractorMessageReporting": {
|
|
32
|
+
* "ae-undocumented": {
|
|
33
|
+
* "logLevel": "warning"
|
|
34
|
+
* }
|
|
35
|
+
* }
|
|
36
|
+
* }
|
|
37
|
+
* ```
|
|
38
|
+
*/
|
|
39
|
+
ExtractorMessageId["Undocumented"] = "ae-undocumented";
|
|
40
|
+
/**
|
|
41
|
+
* "This symbol has another declaration with a different release tag."
|
|
42
|
+
*/
|
|
43
|
+
ExtractorMessageId["DifferentReleaseTags"] = "ae-different-release-tags";
|
|
44
|
+
/**
|
|
45
|
+
* "The symbol ___ is marked as ___, but its signature references ___ which is marked as ___."
|
|
46
|
+
*/
|
|
47
|
+
ExtractorMessageId["IncompatibleReleaseTags"] = "ae-incompatible-release-tags";
|
|
48
|
+
/**
|
|
49
|
+
* "___ is part of the package's API, but it is missing a release tag (`@alpha`, `@beta`, `@public`, or `@internal`)."
|
|
50
|
+
*/
|
|
51
|
+
ExtractorMessageId["MissingReleaseTag"] = "ae-missing-release-tag";
|
|
52
|
+
/**
|
|
53
|
+
* "The `@packageDocumentation` comment must appear at the top of entry point *.d.ts file."
|
|
54
|
+
*/
|
|
55
|
+
ExtractorMessageId["MisplacedPackageTag"] = "ae-misplaced-package-tag";
|
|
56
|
+
/**
|
|
57
|
+
* "The symbol ___ needs to be exported by the entry point ___."
|
|
58
|
+
*/
|
|
59
|
+
ExtractorMessageId["ForgottenExport"] = "ae-forgotten-export";
|
|
60
|
+
/**
|
|
61
|
+
* "The name ___ should be prefixed with an underscore because the declaration is marked as `@internal`."
|
|
62
|
+
*/
|
|
63
|
+
ExtractorMessageId["InternalMissingUnderscore"] = "ae-internal-missing-underscore";
|
|
64
|
+
/**
|
|
65
|
+
* "Mixed release tags are not allowed for ___ because one of its declarations is marked as `@internal`."
|
|
66
|
+
*/
|
|
67
|
+
ExtractorMessageId["InternalMixedReleaseTag"] = "ae-internal-mixed-release-tag";
|
|
68
|
+
/**
|
|
69
|
+
* "The `@preapproved` tag cannot be applied to ___ because it is not a supported declaration type."
|
|
70
|
+
*/
|
|
71
|
+
ExtractorMessageId["PreapprovedUnsupportedType"] = "ae-preapproved-unsupported-type";
|
|
72
|
+
/**
|
|
73
|
+
* "The `@preapproved` tag cannot be applied to ___ without an `@internal` release tag."
|
|
74
|
+
*/
|
|
75
|
+
ExtractorMessageId["PreapprovedBadReleaseTag"] = "ae-preapproved-bad-release-tag";
|
|
76
|
+
/**
|
|
77
|
+
* "The `@inheritDoc` reference could not be resolved."
|
|
78
|
+
*/
|
|
79
|
+
ExtractorMessageId["UnresolvedInheritDocReference"] = "ae-unresolved-inheritdoc-reference";
|
|
80
|
+
/**
|
|
81
|
+
* "The `@inheritDoc` tag needs a TSDoc declaration reference; signature matching is not supported yet."
|
|
82
|
+
*
|
|
83
|
+
* @privateRemarks
|
|
84
|
+
* In the future, we will implement signature matching so that you can write `{@inheritDoc}` and API Extractor
|
|
85
|
+
* will find a corresponding member from a base class (or implemented interface). Until then, the tag
|
|
86
|
+
* always needs an explicit declaration reference such as `{@inhertDoc MyBaseClass.sameMethod}`.
|
|
87
|
+
*/
|
|
88
|
+
ExtractorMessageId["UnresolvedInheritDocBase"] = "ae-unresolved-inheritdoc-base";
|
|
89
|
+
/**
|
|
90
|
+
* "The `@inheritDoc` tag for ___ refers to its own declaration."
|
|
91
|
+
*/
|
|
92
|
+
ExtractorMessageId["CyclicInheritDoc"] = "ae-cyclic-inherit-doc";
|
|
93
|
+
/**
|
|
94
|
+
* "The `@link` reference could not be resolved."
|
|
95
|
+
*/
|
|
96
|
+
ExtractorMessageId["UnresolvedLink"] = "ae-unresolved-link";
|
|
97
|
+
/**
|
|
98
|
+
* "The doc comment for the property ___ must appear on the getter, not the setter."
|
|
99
|
+
*/
|
|
100
|
+
ExtractorMessageId["SetterWithDocs"] = "ae-setter-with-docs";
|
|
101
|
+
/**
|
|
102
|
+
* "The property ___ has a setter but no getter."
|
|
103
|
+
*/
|
|
104
|
+
ExtractorMessageId["MissingGetter"] = "ae-missing-getter";
|
|
105
|
+
/**
|
|
106
|
+
* "Incorrect file type; API Extractor expects to analyze compiler outputs with the .d.ts file extension.
|
|
107
|
+
* Troubleshooting tips: `https://api-extractor.com/link/dts-error`"
|
|
108
|
+
*/
|
|
109
|
+
ExtractorMessageId["WrongInputFileType"] = "ae-wrong-input-file-type";
|
|
110
|
+
})(ExtractorMessageId || (exports.ExtractorMessageId = ExtractorMessageId = {}));
|
|
6
111
|
exports.allExtractorMessageIds = new Set([
|
|
7
112
|
'ae-extra-release-tag',
|
|
8
113
|
'ae-undocumented',
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ExtractorMessageId.js","sourceRoot":"","sources":["../../src/api/ExtractorMessageId.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;
|
|
1
|
+
{"version":3,"file":"ExtractorMessageId.js","sourceRoot":"","sources":["../../src/api/ExtractorMessageId.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAE3D;;;;;;;;;GASG;AACH,IAAY,kBA8GX;AA9GD,WAAY,kBAAkB;IAC5B;;OAEG;IACH,8DAAwC,CAAA;IAExC;;;;;;;;;;;;;;;;OAgBG;IACH,sDAAgC,CAAA;IAEhC;;OAEG;IACH,wEAAkD,CAAA;IAElD;;OAEG;IACH,8EAAwD,CAAA;IAExD;;OAEG;IACH,kEAA4C,CAAA;IAE5C;;OAEG;IACH,sEAAgD,CAAA;IAEhD;;OAEG;IACH,6DAAuC,CAAA;IAEvC;;OAEG;IACH,kFAA4D,CAAA;IAE5D;;OAEG;IACH,+EAAyD,CAAA;IAEzD;;OAEG;IACH,oFAA8D,CAAA;IAE9D;;OAEG;IACH,iFAA2D,CAAA;IAE3D;;OAEG;IACH,0FAAoE,CAAA;IAEpE;;;;;;;OAOG;IACH,gFAA0D,CAAA;IAE1D;;OAEG;IACH,gEAA0C,CAAA;IAE1C;;OAEG;IACH,2DAAqC,CAAA;IAErC;;OAEG;IACH,4DAAsC,CAAA;IAEtC;;OAEG;IACH,yDAAmC,CAAA;IAEnC;;;OAGG;IACH,qEAA+C,CAAA;AACjD,CAAC,EA9GW,kBAAkB,kCAAlB,kBAAkB,QA8G7B;AAEY,QAAA,sBAAsB,GAAgB,IAAI,GAAG,CAAS;IACjE,sBAAsB;IACtB,iBAAiB;IACjB,2BAA2B;IAC3B,8BAA8B;IAC9B,wBAAwB;IACxB,0BAA0B;IAC1B,qBAAqB;IACrB,gCAAgC;IAChC,+BAA+B;IAC/B,iCAAiC;IACjC,gCAAgC;IAChC,oCAAoC;IACpC,+BAA+B;IAC/B,uBAAuB;IACvB,oBAAoB;IACpB,qBAAqB;IACrB,mBAAmB;IACnB,0BAA0B;CAC3B,CAAC,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\n/**\n * Unique identifiers for messages reported by API Extractor during its analysis.\n *\n * @remarks\n *\n * These strings are possible values for the {@link ExtractorMessage.messageId} property\n * when the `ExtractorMessage.category` is {@link ExtractorMessageCategory.Extractor}.\n *\n * @public\n */\nexport enum ExtractorMessageId {\n /**\n * \"The doc comment should not contain more than one release tag.\"\n */\n ExtraReleaseTag = 'ae-extra-release-tag',\n\n /**\n * \"Missing documentation for ___.\"\n * @remarks\n * The `ae-undocumented` message is only generated if the API report feature is enabled.\n *\n * Because the API report file already annotates undocumented items with `// (undocumented)`,\n * the `ae-undocumented` message is not logged by default. To see it, add a setting such as:\n * ```json\n * \"messages\": {\n * \"extractorMessageReporting\": {\n * \"ae-undocumented\": {\n * \"logLevel\": \"warning\"\n * }\n * }\n * }\n * ```\n */\n Undocumented = 'ae-undocumented',\n\n /**\n * \"This symbol has another declaration with a different release tag.\"\n */\n DifferentReleaseTags = 'ae-different-release-tags',\n\n /**\n * \"The symbol ___ is marked as ___, but its signature references ___ which is marked as ___.\"\n */\n IncompatibleReleaseTags = 'ae-incompatible-release-tags',\n\n /**\n * \"___ is part of the package's API, but it is missing a release tag (`@alpha`, `@beta`, `@public`, or `@internal`).\"\n */\n MissingReleaseTag = 'ae-missing-release-tag',\n\n /**\n * \"The `@packageDocumentation` comment must appear at the top of entry point *.d.ts file.\"\n */\n MisplacedPackageTag = 'ae-misplaced-package-tag',\n\n /**\n * \"The symbol ___ needs to be exported by the entry point ___.\"\n */\n ForgottenExport = 'ae-forgotten-export',\n\n /**\n * \"The name ___ should be prefixed with an underscore because the declaration is marked as `@internal`.\"\n */\n InternalMissingUnderscore = 'ae-internal-missing-underscore',\n\n /**\n * \"Mixed release tags are not allowed for ___ because one of its declarations is marked as `@internal`.\"\n */\n InternalMixedReleaseTag = 'ae-internal-mixed-release-tag',\n\n /**\n * \"The `@preapproved` tag cannot be applied to ___ because it is not a supported declaration type.\"\n */\n PreapprovedUnsupportedType = 'ae-preapproved-unsupported-type',\n\n /**\n * \"The `@preapproved` tag cannot be applied to ___ without an `@internal` release tag.\"\n */\n PreapprovedBadReleaseTag = 'ae-preapproved-bad-release-tag',\n\n /**\n * \"The `@inheritDoc` reference could not be resolved.\"\n */\n UnresolvedInheritDocReference = 'ae-unresolved-inheritdoc-reference',\n\n /**\n * \"The `@inheritDoc` tag needs a TSDoc declaration reference; signature matching is not supported yet.\"\n *\n * @privateRemarks\n * In the future, we will implement signature matching so that you can write `{@inheritDoc}` and API Extractor\n * will find a corresponding member from a base class (or implemented interface). Until then, the tag\n * always needs an explicit declaration reference such as `{@inhertDoc MyBaseClass.sameMethod}`.\n */\n UnresolvedInheritDocBase = 'ae-unresolved-inheritdoc-base',\n\n /**\n * \"The `@inheritDoc` tag for ___ refers to its own declaration.\"\n */\n CyclicInheritDoc = 'ae-cyclic-inherit-doc',\n\n /**\n * \"The `@link` reference could not be resolved.\"\n */\n UnresolvedLink = 'ae-unresolved-link',\n\n /**\n * \"The doc comment for the property ___ must appear on the getter, not the setter.\"\n */\n SetterWithDocs = 'ae-setter-with-docs',\n\n /**\n * \"The property ___ has a setter but no getter.\"\n */\n MissingGetter = 'ae-missing-getter',\n\n /**\n * \"Incorrect file type; API Extractor expects to analyze compiler outputs with the .d.ts file extension.\n * Troubleshooting tips: `https://api-extractor.com/link/dts-error`\"\n */\n WrongInputFileType = 'ae-wrong-input-file-type'\n}\n\nexport const allExtractorMessageIds: Set<string> = new Set<string>([\n 'ae-extra-release-tag',\n 'ae-undocumented',\n 'ae-different-release-tags',\n 'ae-incompatible-release-tags',\n 'ae-missing-release-tag',\n 'ae-misplaced-package-tag',\n 'ae-forgotten-export',\n 'ae-internal-missing-underscore',\n 'ae-internal-mixed-release-tag',\n 'ae-preapproved-unsupported-type',\n 'ae-preapproved-bad-release-tag',\n 'ae-unresolved-inheritdoc-reference',\n 'ae-unresolved-inheritdoc-base',\n 'ae-cyclic-inherit-doc',\n 'ae-unresolved-link',\n 'ae-setter-with-docs',\n 'ae-missing-getter',\n 'ae-wrong-input-file-type'\n]);\n"]}
|
|
@@ -30,6 +30,7 @@ const ts = __importStar(require("typescript"));
|
|
|
30
30
|
const tsdoc = __importStar(require("@microsoft/tsdoc"));
|
|
31
31
|
const node_core_library_1 = require("@rushstack/node-core-library");
|
|
32
32
|
const api_extractor_model_1 = require("@microsoft/api-extractor-model");
|
|
33
|
+
const ExtractorMessageId_1 = require("../api/ExtractorMessageId");
|
|
33
34
|
const CollectorEntity_1 = require("./CollectorEntity");
|
|
34
35
|
const AstSymbolTable_1 = require("../analyzer/AstSymbolTable");
|
|
35
36
|
const AstSymbol_1 = require("../analyzer/AstSymbol");
|
|
@@ -147,7 +148,7 @@ class Collector {
|
|
|
147
148
|
// Typically there will be many such files -- to avoid too much noise, only report the first one.
|
|
148
149
|
const badSourceFile = sourceFiles.find(({ fileName }) => !ExtractorConfig_1.ExtractorConfig.hasDtsFileExtension(fileName));
|
|
149
150
|
if (badSourceFile) {
|
|
150
|
-
this.messageRouter.addAnalyzerIssueForPosition(
|
|
151
|
+
this.messageRouter.addAnalyzerIssueForPosition(ExtractorMessageId_1.ExtractorMessageId.WrongInputFileType, 'Incorrect file type; API Extractor expects to analyze compiler outputs with the .d.ts file extension. ' +
|
|
151
152
|
'Troubleshooting tips: https://api-extractor.com/link/dts-error', badSourceFile, 0);
|
|
152
153
|
}
|
|
153
154
|
// Build the entry point
|
|
@@ -496,7 +497,7 @@ class Collector {
|
|
|
496
497
|
}
|
|
497
498
|
}
|
|
498
499
|
if (!foundGetter) {
|
|
499
|
-
this.messageRouter.addAnalyzerIssue(
|
|
500
|
+
this.messageRouter.addAnalyzerIssue(ExtractorMessageId_1.ExtractorMessageId.MissingGetter, `The property "${astDeclaration.astSymbol.localName}" has a setter but no getter.`, astDeclaration);
|
|
500
501
|
}
|
|
501
502
|
}
|
|
502
503
|
}
|
|
@@ -530,7 +531,7 @@ class Collector {
|
|
|
530
531
|
if (declarationMetadata.isAncillary) {
|
|
531
532
|
if (astDeclaration.declaration.kind === ts.SyntaxKind.SetAccessor) {
|
|
532
533
|
if (declarationMetadata.tsdocParserContext) {
|
|
533
|
-
this.messageRouter.addAnalyzerIssue(
|
|
534
|
+
this.messageRouter.addAnalyzerIssue(ExtractorMessageId_1.ExtractorMessageId.SetterWithDocs, `The doc comment for the property "${astDeclaration.astSymbol.localName}"` +
|
|
534
535
|
` must appear on the getter, not the setter.`, astDeclaration);
|
|
535
536
|
}
|
|
536
537
|
}
|
|
@@ -583,7 +584,7 @@ class Collector {
|
|
|
583
584
|
if (extraReleaseTags) {
|
|
584
585
|
if (!astDeclaration.astSymbol.isExternal) {
|
|
585
586
|
// for now, don't report errors for external code
|
|
586
|
-
this.messageRouter.addAnalyzerIssue(
|
|
587
|
+
this.messageRouter.addAnalyzerIssue(ExtractorMessageId_1.ExtractorMessageId.ExtraReleaseTag, 'The doc comment should not contain more than one release tag', astDeclaration);
|
|
587
588
|
}
|
|
588
589
|
}
|
|
589
590
|
options.declaredReleaseTag = declaredReleaseTag;
|
|
@@ -603,12 +604,12 @@ class Collector {
|
|
|
603
604
|
options.isPreapproved = true;
|
|
604
605
|
}
|
|
605
606
|
else {
|
|
606
|
-
this.messageRouter.addAnalyzerIssue(
|
|
607
|
+
this.messageRouter.addAnalyzerIssue(ExtractorMessageId_1.ExtractorMessageId.PreapprovedBadReleaseTag, `The @preapproved tag cannot be applied to "${astDeclaration.astSymbol.localName}"` +
|
|
607
608
|
` without an @internal release tag`, astDeclaration);
|
|
608
609
|
}
|
|
609
610
|
break;
|
|
610
611
|
default:
|
|
611
|
-
this.messageRouter.addAnalyzerIssue(
|
|
612
|
+
this.messageRouter.addAnalyzerIssue(ExtractorMessageId_1.ExtractorMessageId.PreapprovedUnsupportedType, `The @preapproved tag cannot be applied to "${astDeclaration.astSymbol.localName}"` +
|
|
612
613
|
` because it is not a supported declaration type`, astDeclaration);
|
|
613
614
|
break;
|
|
614
615
|
}
|
|
@@ -641,7 +642,7 @@ class Collector {
|
|
|
641
642
|
// We also don't report errors for the default export of an entry point, since its doc comment
|
|
642
643
|
// isn't easy to obtain from the .d.ts file
|
|
643
644
|
if (astSymbol.rootAstSymbol.localName !== '_default') {
|
|
644
|
-
this.messageRouter.addAnalyzerIssue(
|
|
645
|
+
this.messageRouter.addAnalyzerIssue(ExtractorMessageId_1.ExtractorMessageId.MissingReleaseTag, `"${entity.astEntity.localName}" is part of the package's API, but it is missing ` +
|
|
645
646
|
`a release tag (@alpha, @beta, @public, or @internal)`, astSymbol);
|
|
646
647
|
}
|
|
647
648
|
}
|