1 | /**
|
2 | * API Extractor helps with validation, documentation, and reviewing of the exported API for a TypeScript library.
|
3 | * The `@microsoft/api-extractor` package provides the command-line tool. It also exposes a developer API that you
|
4 | * can use to invoke API Extractor programmatically.
|
5 | *
|
6 | * @packageDocumentation
|
7 | */
|
8 |
|
9 | import { EnumMemberOrder } from '@microsoft/api-extractor-model';
|
10 | import { INodePackageJson } from '@rushstack/node-core-library';
|
11 | import { JsonSchema } from '@rushstack/node-core-library';
|
12 | import { NewlineKind } from '@rushstack/node-core-library';
|
13 | import { PackageJsonLookup } from '@rushstack/node-core-library';
|
14 | import { RigConfig } from '@rushstack/rig-package';
|
15 | import * as tsdoc from '@microsoft/tsdoc';
|
16 | import { TSDocConfigFile } from '@microsoft/tsdoc-config';
|
17 | import { TSDocConfiguration } from '@microsoft/tsdoc';
|
18 |
|
19 | /**
|
20 | * This class represents the TypeScript compiler state. This allows an optimization where multiple invocations
|
21 | * of API Extractor can reuse the same TypeScript compiler analysis.
|
22 | *
|
23 | * @public
|
24 | */
|
25 | export declare class CompilerState {
|
26 | /**
|
27 | * The TypeScript compiler's `Program` object, which represents a complete scope of analysis.
|
28 | */
|
29 | readonly program: unknown;
|
30 | private constructor();
|
31 | /**
|
32 | * Create a compiler state for use with the specified `IExtractorInvokeOptions`.
|
33 | */
|
34 | static create(extractorConfig: ExtractorConfig, options?: ICompilerStateCreateOptions): CompilerState;
|
35 | /**
|
36 | * Given a list of absolute file paths, return a list containing only the declaration
|
37 | * files. Duplicates are also eliminated.
|
38 | *
|
39 | * @remarks
|
40 | * The tsconfig.json settings specify the compiler's input (a set of *.ts source files,
|
41 | * plus some *.d.ts declaration files used for legacy typings). However API Extractor
|
42 | * analyzes the compiler's output (a set of *.d.ts entry point files, plus any legacy
|
43 | * typings). This requires API Extractor to generate a special file list when it invokes
|
44 | * the compiler.
|
45 | *
|
46 | * Duplicates are removed so that entry points can be appended without worrying whether they
|
47 | * may already appear in the tsconfig.json file list.
|
48 | */
|
49 | private static _generateFilePathsForAnalysis;
|
50 | private static _createCompilerHost;
|
51 | }
|
52 |
|
53 | /**
|
54 | * Unique identifiers for console messages reported by API Extractor.
|
55 | *
|
56 | * @remarks
|
57 | *
|
58 | * These strings are possible values for the { ExtractorMessage.messageId} property
|
59 | * when the `ExtractorMessage.category` is { ExtractorMessageCategory.Console}.
|
60 | *
|
61 | *
|
62 | */
|
63 | export declare const enum ConsoleMessageId {
|
64 | /**
|
65 | * "Analysis will use the bundled TypeScript version ___"
|
66 | */
|
67 | Preamble = "console-preamble",
|
68 | /**
|
69 | * "The target project appears to use TypeScript ___ which is newer than the bundled compiler engine;
|
70 | * consider upgrading API Extractor."
|
71 | */
|
72 | CompilerVersionNotice = "console-compiler-version-notice",
|
73 | /**
|
74 | * "Using custom TSDoc config from ___"
|
75 | */
|
76 | UsingCustomTSDocConfig = "console-using-custom-tsdoc-config",
|
77 | /**
|
78 | * "Found metadata in ___"
|
79 | */
|
80 | FoundTSDocMetadata = "console-found-tsdoc-metadata",
|
81 | /**
|
82 | * "Writing: ___"
|
83 | */
|
84 | WritingDocModelFile = "console-writing-doc-model-file",
|
85 | /**
|
86 | * "Writing package typings: ___"
|
87 | */
|
88 | WritingDtsRollup = "console-writing-dts-rollup",
|
89 | /**
|
90 | * "You have changed the public API signature for this project.
|
91 | * Please copy the file ___ to ___, or perform a local build (which does this automatically).
|
92 | * See the Git repo documentation for more info."
|
93 | *
|
94 | * OR
|
95 | *
|
96 | * "The API report file is missing.
|
97 | * Please copy the file ___ to ___, or perform a local build (which does this automatically).
|
98 | * See the Git repo documentation for more info."
|
99 | */
|
100 | ApiReportNotCopied = "console-api-report-not-copied",
|
101 | /**
|
102 | * "You have changed the public API signature for this project. Updating ___"
|
103 | */
|
104 | ApiReportCopied = "console-api-report-copied",
|
105 | /**
|
106 | * "The API report is up to date: ___"
|
107 | */
|
108 | ApiReportUnchanged = "console-api-report-unchanged",
|
109 | /**
|
110 | * "The API report file was missing, so a new file was created. Please add this file to Git: ___"
|
111 | */
|
112 | ApiReportCreated = "console-api-report-created",
|
113 | /**
|
114 | * "Unable to create the API report file. Please make sure the target folder exists: ___"
|
115 | */
|
116 | ApiReportFolderMissing = "console-api-report-folder-missing",
|
117 | /**
|
118 | * Used for the information printed when the "--diagnostics" flag is enabled.
|
119 | */
|
120 | Diagnostics = "console-diagnostics"
|
121 | }
|
122 |
|
123 | /**
|
124 | * The starting point for invoking the API Extractor tool.
|
125 | * @public
|
126 | */
|
127 | export declare class Extractor {
|
128 | /**
|
129 | * Returns the version number of the API Extractor NPM package.
|
130 | */
|
131 | static get version(): string;
|
132 | /**
|
133 | * Returns the package name of the API Extractor NPM package.
|
134 | */
|
135 | static get packageName(): string;
|
136 | private static _getPackageJson;
|
137 | /**
|
138 | * Load the api-extractor.json config file from the specified path, and then invoke API Extractor.
|
139 | */
|
140 | static loadConfigAndInvoke(configFilePath: string, options?: IExtractorInvokeOptions): ExtractorResult;
|
141 | /**
|
142 | * Invoke API Extractor using an already prepared `ExtractorConfig` object.
|
143 | */
|
144 | static invoke(extractorConfig: ExtractorConfig, options?: IExtractorInvokeOptions): ExtractorResult;
|
145 | private static _checkCompilerCompatibility;
|
146 | private static _generateRollupDtsFile;
|
147 | }
|
148 |
|
149 | /**
|
150 | * The `ExtractorConfig` class loads, validates, interprets, and represents the api-extractor.json config file.
|
151 | * @public
|
152 | */
|
153 | export declare class ExtractorConfig {
|
154 | /**
|
155 | * The JSON Schema for API Extractor config file (api-extractor.schema.json).
|
156 | */
|
157 | static readonly jsonSchema: JsonSchema;
|
158 | /**
|
159 | * The config file name "api-extractor.json".
|
160 | */
|
161 | static readonly FILENAME: string;
|
162 | /**
|
163 | * The full path to `extends/tsdoc-base.json` which contains the standard TSDoc configuration
|
164 | * for API Extractor.
|
165 | * @internal
|
166 | */
|
167 | static readonly _tsdocBaseFilePath: string;
|
168 | private static readonly _defaultConfig;
|
169 | private static readonly _declarationFileExtensionRegExp;
|
170 | /** {@inheritDoc IConfigFile.projectFolder} */
|
171 | readonly projectFolder: string;
|
172 | /**
|
173 | * The parsed package.json file for the working package, or undefined if API Extractor was invoked without
|
174 | * a package.json file.
|
175 | */
|
176 | readonly packageJson: INodePackageJson | undefined;
|
177 | /**
|
178 | * The absolute path of the folder containing the package.json file for the working package, or undefined
|
179 | * if API Extractor was invoked without a package.json file.
|
180 | */
|
181 | readonly packageFolder: string | undefined;
|
182 | /** {@inheritDoc IConfigFile.mainEntryPointFilePath} */
|
183 | readonly mainEntryPointFilePath: string;
|
184 | /** {@inheritDoc IConfigFile.bundledPackages} */
|
185 | readonly bundledPackages: string[];
|
186 | /** {@inheritDoc IConfigCompiler.tsconfigFilePath} */
|
187 | readonly tsconfigFilePath: string;
|
188 | /** {@inheritDoc IConfigCompiler.overrideTsconfig} */
|
189 | readonly overrideTsconfig: {} | undefined;
|
190 | /** {@inheritDoc IConfigCompiler.skipLibCheck} */
|
191 | readonly skipLibCheck: boolean;
|
192 | /** {@inheritDoc IConfigApiReport.enabled} */
|
193 | readonly apiReportEnabled: boolean;
|
194 | /** The `reportFolder` path combined with the `reportFileName`. */
|
195 | readonly reportFilePath: string;
|
196 | /** The `reportTempFolder` path combined with the `reportFileName`. */
|
197 | readonly reportTempFilePath: string;
|
198 | /** {@inheritDoc IConfigDocModel.enabled} */
|
199 | readonly docModelEnabled: boolean;
|
200 | /** {@inheritDoc IConfigDocModel.apiJsonFilePath} */
|
201 | readonly apiJsonFilePath: string;
|
202 | /** {@inheritDoc IConfigDtsRollup.enabled} */
|
203 | readonly rollupEnabled: boolean;
|
204 | /** {@inheritDoc IConfigDtsRollup.untrimmedFilePath} */
|
205 | readonly untrimmedFilePath: string;
|
206 | /** {@inheritDoc IConfigDtsRollup.alphaTrimmedFilePath} */
|
207 | readonly alphaTrimmedFilePath: string;
|
208 | /** {@inheritDoc IConfigDtsRollup.betaTrimmedFilePath} */
|
209 | readonly betaTrimmedFilePath: string;
|
210 | /** {@inheritDoc IConfigDtsRollup.publicTrimmedFilePath} */
|
211 | readonly publicTrimmedFilePath: string;
|
212 | /** {@inheritDoc IConfigDtsRollup.omitTrimmingComments} */
|
213 | readonly omitTrimmingComments: boolean;
|
214 | /** {@inheritDoc IConfigTsdocMetadata.enabled} */
|
215 | readonly tsdocMetadataEnabled: boolean;
|
216 | /** {@inheritDoc IConfigTsdocMetadata.tsdocMetadataFilePath} */
|
217 | readonly tsdocMetadataFilePath: string;
|
218 | /**
|
219 | * The tsdoc.json configuration that will be used when parsing doc comments.
|
220 | */
|
221 | readonly tsdocConfigFile: TSDocConfigFile;
|
222 | /**
|
223 | * The `TSDocConfiguration` loaded from {@link ExtractorConfig.tsdocConfigFile}.
|
224 | */
|
225 | readonly tsdocConfiguration: TSDocConfiguration;
|
226 | /**
|
227 | * Specifies what type of newlines API Extractor should use when writing output files. By default, the output files
|
228 | * will be written with Windows-style newlines.
|
229 | */
|
230 | readonly newlineKind: NewlineKind;
|
231 | /** {@inheritDoc IConfigFile.messages} */
|
232 | readonly messages: IExtractorMessagesConfig;
|
233 | /** {@inheritDoc IConfigFile.testMode} */
|
234 | readonly testMode: boolean;
|
235 | /** {@inheritDoc IConfigFile.enumMemberOrder} */
|
236 | readonly enumMemberOrder: EnumMemberOrder;
|
237 | private constructor();
|
238 | /**
|
239 | * Returns a JSON-like string representing the `ExtractorConfig` state, which can be printed to a console
|
240 | * for diagnostic purposes.
|
241 | *
|
242 | * @remarks
|
243 | * This is used by the "--diagnostics" command-line option. The string is not intended to be deserialized;
|
244 | * its format may be changed at any time.
|
245 | */
|
246 | getDiagnosticDump(): string;
|
247 | /**
|
248 | * Returns a simplified file path for use in error messages.
|
249 | * @internal
|
250 | */
|
251 | _getShortFilePath(absolutePath: string): string;
|
252 | /**
|
253 | * Searches for the api-extractor.json config file associated with the specified starting folder,
|
254 | * and loads the file if found. This lookup supports
|
255 | * {//www.npmjs.com/package/@rushstack/rig-package | rig packages}.
https: |
256 | *
|
257 | *
|
258 | * The search will first look for a package.json file in a parent folder of the starting folder;
|
259 | * if found, that will be used as the base folder instead of the starting folder. If the config
|
260 | * file is not found in `<baseFolder>/api-extractor.json` or `<baseFolder>/config/api-extractor.json`,
|
261 | * then `<baseFolder/config/rig.json` will be checked to see whether a
|
262 | * {//www.npmjs.com/package/@rushstack/rig-package | rig package} is referenced; if so then
https: |
263 | * the rig's api-extractor.json file will be used instead. If a config file is found, it will be loaded
|
264 | * and returned with the `IExtractorConfigPrepareOptions` object. Otherwise, `undefined` is returned
|
265 | * to indicate that API Extractor does not appear to be configured for the specified folder.
|
266 | *
|
267 | * `undefined`
An options object that can be passed to { ExtractorConfig.prepare}, or |
268 | * if not api-extractor.json file was found.
|
269 | */
|
270 | static tryLoadForFolder(options: IExtractorConfigLoadForFolderOptions): IExtractorConfigPrepareOptions | undefined;
|
271 | /**
|
272 | * Loads the api-extractor.json config file from the specified file path, and prepares an `ExtractorConfig` object.
|
273 | *
|
274 | * @remarks
|
275 | * Loads the api-extractor.json config file from the specified file path. If the "extends" field is present,
|
276 | * the referenced file(s) will be merged. For any omitted fields, the API Extractor default values are merged.
|
277 | *
|
278 | * The result is prepared using `ExtractorConfig.prepare()`.
|
279 | */
|
280 | static loadFileAndPrepare(configJsonFilePath: string): ExtractorConfig;
|
281 | /**
|
282 | * Performs only the first half of {@link ExtractorConfig.loadFileAndPrepare}, providing an opportunity to
|
283 | * modify the object before it is passed to {@link ExtractorConfig.prepare}.
|
284 | *
|
285 | * @remarks
|
286 | * Loads the api-extractor.json config file from the specified file path. If the "extends" field is present,
|
287 | * the referenced file(s) will be merged. For any omitted fields, the API Extractor default values are merged.
|
288 | */
|
289 | static loadFile(jsonFilePath: string): IConfigFile;
|
290 | private static _resolveConfigFileRelativePaths;
|
291 | private static _resolveConfigFileRelativePath;
|
292 | /**
|
293 | * Prepares an `ExtractorConfig` object using a configuration that is provided as a runtime object,
|
294 | * rather than reading it from disk. This allows configurations to be constructed programmatically,
|
295 | * loaded from an alternate source, and/or customized after loading.
|
296 | */
|
297 | static prepare(options: IExtractorConfigPrepareOptions): ExtractorConfig;
|
298 | private static _resolvePathWithTokens;
|
299 | private static _expandStringWithTokens;
|
300 | /**
|
301 | * Returns true if the specified file path has the ".d.ts" file extension.
|
302 | */
|
303 | static hasDtsFileExtension(filePath: string): boolean;
|
304 | /**
|
305 | * Given a path string that may have originally contained expandable tokens such as `<projectFolder>"`
|
306 | * this reports an error if any token-looking substrings remain after expansion (e.g. `c:\blah\<invalid>\blah`).
|
307 | */
|
308 | private static _rejectAnyTokensInPath;
|
309 | }
|
310 |
|
311 | /**
|
312 | * Used with {@link IConfigMessageReportingRule.logLevel} and {@link IExtractorInvokeOptions.messageCallback}.
|
313 | *
|
314 | * @remarks
|
315 | * This is part of the {@link IConfigFile} structure.
|
316 | *
|
317 | * @public
|
318 | */
|
319 | export declare const enum ExtractorLogLevel {
|
320 | /**
|
321 | * The message will be displayed as an error.
|
322 | *
|
323 | * @remarks
|
324 | * Errors typically cause the build to fail and return a nonzero exit code.
|
325 | */
|
326 | Error = "error",
|
327 | /**
|
328 | * The message will be displayed as an warning.
|
329 | *
|
330 | * @remarks
|
331 | * Warnings typically cause a production build fail and return a nonzero exit code. For a non-production build
|
332 | * (e.g. using the `--local` option with `api-extractor run`), the warning is displayed but the build will not fail.
|
333 | */
|
334 | Warning = "warning",
|
335 | /**
|
336 | * The message will be displayed as an informational message.
|
337 | *
|
338 | * @remarks
|
339 | * Informational messages may contain newlines to ensure nice formatting of the output,
|
340 | * however word-wrapping is the responsibility of the message handler.
|
341 | */
|
342 | Info = "info",
|
343 | /**
|
344 | * The message will be displayed only when "verbose" output is requested, e.g. using the `--verbose`
|
345 | * command line option.
|
346 | */
|
347 | Verbose = "verbose",
|
348 | /**
|
349 | * The message will be discarded entirely.
|
350 | */
|
351 | None = "none"
|
352 | }
|
353 |
|
354 | /**
|
355 | * This object is used to report an error or warning that occurred during API Extractor's analysis.
|
356 | *
|
357 | * @public
|
358 | */
|
359 | export declare class ExtractorMessage {
|
360 | private _handled;
|
361 | private _logLevel;
|
362 | /**
|
363 | * The category of issue.
|
364 | */
|
365 | readonly category: ExtractorMessageCategory;
|
366 | /**
|
367 | * A text string that uniquely identifies the issue type. This identifier can be used to suppress
|
368 | * or configure the reporting of issues, and also to search for help about an issue.
|
369 | */
|
370 | readonly messageId: tsdoc.TSDocMessageId | ExtractorMessageId | ConsoleMessageId | string;
|
371 | /**
|
372 | * The text description of this issue.
|
373 | */
|
374 | readonly text: string;
|
375 | /**
|
376 | * The absolute path to the affected input source file, if there is one.
|
377 | */
|
378 | readonly sourceFilePath: string | undefined;
|
379 | /**
|
380 | * The line number where the issue occurred in the input source file. This is not used if `sourceFilePath`
|
381 | * is undefined. The first line number is 1.
|
382 | */
|
383 | readonly sourceFileLine: number | undefined;
|
384 | /**
|
385 | * The column number where the issue occurred in the input source file. This is not used if `sourceFilePath`
|
386 | * is undefined. The first column number is 1.
|
387 | */
|
388 | readonly sourceFileColumn: number | undefined;
|
389 | /**
|
390 | * Additional contextual information about the message that may be useful when reporting errors.
|
391 | * All properties are optional.
|
392 | */
|
393 | readonly properties: IExtractorMessageProperties;
|
394 | /** @internal */
|
395 | constructor(options: IExtractorMessageOptions);
|
396 | /**
|
397 | * If the {this property to true, it will prevent the message
IExtractorInvokeOptions.messageCallback} sets |
398 | * from being displayed by API Extractor.
|
399 | *
|
400 | *
|
401 | * If the `messageCallback` routes the message to a custom handler (e.g. a toolchain logger), it should
|
402 | * assign `handled = true` to prevent API Extractor from displaying it. Assigning `handled = true` for all messages
|
403 | * would effectively disable all console output from the `Extractor` API.
|
404 | *
|
405 | * If `handled` is set to true, the message will still be included in the count of errors/warnings;
|
406 | * to discard a message entirely, instead assign `logLevel = none`.
|
407 | */
|
408 | get handled(): boolean;
|
409 | set handled(value: boolean);
|
410 | /**
|
411 | * Specifies how the message should be reported.
|
412 | *
|
413 | * @remarks
|
414 | * If the {@link IExtractorInvokeOptions.messageCallback} handles the message (i.e. sets `handled = true`),
|
415 | * it can use the `logLevel` to determine how to display the message.
|
416 | *
|
417 | * Alternatively, if API Extractor is handling the message, the `messageCallback` could assign `logLevel` to change
|
418 | * how it will be processed. However, in general the recommended practice is to configure message routing
|
419 | * using the `messages` section in api-extractor.json.
|
420 | *
|
421 | * To discard a message entirely, assign `logLevel = none`.
|
422 | */
|
423 | get logLevel(): ExtractorLogLevel;
|
424 | set logLevel(value: ExtractorLogLevel);
|
425 | /**
|
426 | * Returns the message formatted with its identifier and file position.
|
427 | * @remarks
|
428 | * Example:
|
429 | * ```
|
430 | * src/folder/File.ts:123:4 - (ae-extra-release-tag) The doc comment should not contain more than one release tag.
|
431 | * ```
|
432 | */
|
433 | formatMessageWithLocation(workingPackageFolderPath: string | undefined): string;
|
434 | formatMessageWithoutLocation(): string;
|
435 | }
|
436 |
|
437 | /**
|
438 | * Specifies a category of messages for use with {@link ExtractorMessage}.
|
439 | * @public
|
440 | */
|
441 | export declare const enum ExtractorMessageCategory {
|
442 | /**
|
443 | * Messages originating from the TypeScript compiler.
|
444 | *
|
445 | * @remarks
|
446 | * These strings begin with the prefix "TS" and have a numeric error code.
|
447 | * Example: `TS2551`
|
448 | */
|
449 | Compiler = "Compiler",
|
450 | /**
|
451 | * Messages related to parsing of TSDoc comments.
|
452 | *
|
453 | * @remarks
|
454 | * These strings begin with the prefix "tsdoc-".
|
455 | * Example: `tsdoc-link-tag-unescaped-text`
|
456 | */
|
457 | TSDoc = "TSDoc",
|
458 | /**
|
459 | * Messages related to API Extractor's analysis.
|
460 | *
|
461 | * @remarks
|
462 | * These strings begin with the prefix "ae-".
|
463 | * Example: `ae-extra-release-tag`
|
464 | */
|
465 | Extractor = "Extractor",
|
466 | /**
|
467 | * Console messages communicate the progress of the overall operation. They may include newlines to ensure
|
468 | * nice formatting. They are output in real time, and cannot be routed to the API Report file.
|
469 | *
|
470 | * @remarks
|
471 | * These strings begin with the prefix "console-".
|
472 | * Example: `console-writing-typings-file`
|
473 | */
|
474 | Console = "console"
|
475 | }
|
476 |
|
477 | /**
|
478 | * Unique identifiers for messages reported by API Extractor during its analysis.
|
479 | *
|
480 | * @remarks
|
481 | *
|
482 | * These strings are possible values for the {@link ExtractorMessage.messageId} property
|
483 | * when the `ExtractorMessage.category` is {@link ExtractorMessageCategory.Extractor}.
|
484 | *
|
485 | * @public
|
486 | */
|
487 | export declare const enum ExtractorMessageId {
|
488 | /**
|
489 | * "The doc comment should not contain more than one release tag."
|
490 | */
|
491 | ExtraReleaseTag = "ae-extra-release-tag",
|
492 | /**
|
493 | * "This symbol has another declaration with a different release tag."
|
494 | */
|
495 | DifferentReleaseTags = "ae-different-release-tags",
|
496 | /**
|
497 | * "The symbol ___ is marked as ___, but its signature references ___ which is marked as ___."
|
498 | */
|
499 | IncompatibleReleaseTags = "ae-incompatible-release-tags",
|
500 | /**
|
501 | * "___ is exported by the package, but it is missing a release tag (`@alpha`, `@beta`, `@public`, or `@internal`)."
|
502 | */
|
503 | MissingReleaseTag = "ae-missing-release-tag",
|
504 | /**
|
505 | * "The `@packageDocumentation` comment must appear at the top of entry point *.d.ts file."
|
506 | */
|
507 | MisplacedPackageTag = "ae-misplaced-package-tag",
|
508 | /**
|
509 | * "The symbol ___ needs to be exported by the entry point ___."
|
510 | */
|
511 | ForgottenExport = "ae-forgotten-export",
|
512 | /**
|
513 | * "The name ___ should be prefixed with an underscore because the declaration is marked as `@internal`."
|
514 | */
|
515 | InternalMissingUnderscore = "ae-internal-missing-underscore",
|
516 | /**
|
517 | * "Mixed release tags are not allowed for ___ because one of its declarations is marked as `@internal`."
|
518 | */
|
519 | InternalMixedReleaseTag = "ae-internal-mixed-release-tag",
|
520 | /**
|
521 | * "The `@preapproved` tag cannot be applied to ___ because it is not a supported declaration type."
|
522 | */
|
523 | PreapprovedUnsupportedType = "ae-preapproved-unsupported-type",
|
524 | /**
|
525 | * "The `@preapproved` tag cannot be applied to ___ without an `@internal` release tag."
|
526 | */
|
527 | PreapprovedBadReleaseTag = "ae-preapproved-bad-release-tag",
|
528 | /**
|
529 | * "The `@inheritDoc` reference could not be resolved."
|
530 | */
|
531 | UnresolvedInheritDocReference = "ae-unresolved-inheritdoc-reference",
|
532 | /**
|
533 | * "The `@inheritDoc` tag needs a TSDoc declaration reference; signature matching is not supported yet."
|
534 | *
|
535 | * @privateRemarks
|
536 | * In the future, we will implement signature matching so that you can write `{@inheritDoc}` and API Extractor
|
537 | * will find a corresponding member from a base class (or implemented interface). Until then, the tag
|
538 | * always needs an explicit declaration reference such as `{@inhertDoc MyBaseClass.sameMethod}`.
|
539 | */
|
540 | UnresolvedInheritDocBase = "ae-unresolved-inheritdoc-base",
|
541 | /**
|
542 | * "The `@inheritDoc` tag for ___ refers to its own declaration."
|
543 | */
|
544 | CyclicInheritDoc = "ae-cyclic-inherit-doc",
|
545 | /**
|
546 | * "The `@link` reference could not be resolved."
|
547 | */
|
548 | UnresolvedLink = "ae-unresolved-link",
|
549 | /**
|
550 | * "The doc comment for the property ___ must appear on the getter, not the setter."
|
551 | */
|
552 | SetterWithDocs = "ae-setter-with-docs",
|
553 | /**
|
554 | * "The property ___ has a setter but no getter."
|
555 | */
|
556 | MissingGetter = "ae-missing-getter",
|
557 | /**
|
558 | * "Incorrect file type; API Extractor expects to analyze compiler outputs with the .d.ts file extension.
|
559 | * Troubleshooting tips: `https://api-extractor.com/link/dts-error`"
|
560 | */
|
561 | WrongInputFileType = "ae-wrong-input-file-type"
|
562 | }
|
563 |
|
564 | /**
|
565 | * This object represents the outcome of an invocation of API Extractor.
|
566 | *
|
567 | * @public
|
568 | */
|
569 | export declare class ExtractorResult {
|
570 | /**
|
571 | * The TypeScript compiler state that was used.
|
572 | */
|
573 | readonly compilerState: CompilerState;
|
574 | /**
|
575 | * The API Extractor configuration that was used.
|
576 | */
|
577 | readonly extractorConfig: ExtractorConfig;
|
578 | /**
|
579 | * Whether the invocation of API Extractor was successful. For example, if `succeeded` is false, then the build task
|
580 | * would normally return a nonzero process exit code, indicating that the operation failed.
|
581 | *
|
582 | * @remarks
|
583 | *
|
584 | * Normally the operation "succeeds" if `errorCount` and `warningCount` are both zero. However if
|
585 | * {@link IExtractorInvokeOptions.localBuild} is `true`, then the operation "succeeds" if `errorCount` is zero
|
586 | * (i.e. warnings are ignored).
|
587 | */
|
588 | readonly succeeded: boolean;
|
589 | /**
|
590 | * Returns true if the API report was found to have changed.
|
591 | */
|
592 | readonly apiReportChanged: boolean;
|
593 | /**
|
594 | * Reports the number of errors encountered during analysis.
|
595 | *
|
596 | * @remarks
|
597 | * This does not count exceptions, where unexpected issues prematurely abort the operation.
|
598 | */
|
599 | readonly errorCount: number;
|
600 | /**
|
601 | * Reports the number of warnings encountered during analysis.
|
602 | *
|
603 | * @remarks
|
604 | * This does not count warnings that are emitted in the API report file.
|
605 | */
|
606 | readonly warningCount: number;
|
607 | /** @internal */
|
608 | constructor(properties: ExtractorResult);
|
609 | }
|
610 |
|
611 | /**
|
612 | * Options for { CompilerState.create}
|
613 | *
|
614 | */
|
615 | export declare interface ICompilerStateCreateOptions {
|
616 | /** {@inheritDoc IExtractorInvokeOptions.typescriptCompilerFolder} */
|
617 | typescriptCompilerFolder?: string;
|
618 | /**
|
619 | * Additional .d.ts files to include in the analysis.
|
620 | */
|
621 | additionalEntryPoints?: string[];
|
622 | }
|
623 |
|
624 | /**
|
625 | * Configures how the API report files (*.api.md) will be generated.
|
626 | *
|
627 | * @remarks
|
628 | * This is part of the {@link IConfigFile} structure.
|
629 | *
|
630 | * @public
|
631 | */
|
632 | export declare interface IConfigApiReport {
|
633 | /**
|
634 | * Whether to generate an API report.
|
635 | */
|
636 | enabled: boolean;
|
637 | /**
|
638 | * The filename for the API report files. It will be combined with `reportFolder` or `reportTempFolder` to produce
|
639 | * a full output filename.
|
640 | *
|
641 | * @remarks
|
642 | * The file extension should be ".api.md", and the string should not contain a path separator such as `\` or `/`.
|
643 | */
|
644 | reportFileName?: string;
|
645 | /**
|
646 | * Specifies the folder where the API report file is written. The file name portion is determined by
|
647 | * the `reportFileName` setting.
|
648 | *
|
649 | * @remarks
|
650 | * The API report file is normally tracked by Git. Changes to it can be used to trigger a branch policy,
|
651 | * e.g. for an API review.
|
652 | *
|
653 | * The path is resolved relative to the folder of the config file that contains the setting; to change this,
|
654 | * prepend a folder token such as `<projectFolder>`.
|
655 | */
|
656 | reportFolder?: string;
|
657 | /**
|
658 | * Specifies the folder where the temporary report file is written. The file name portion is determined by
|
659 | * the `reportFileName` setting.
|
660 | *
|
661 | * @remarks
|
662 | * After the temporary file is written to disk, it is compared with the file in the `reportFolder`.
|
663 | * If they are different, a production build will fail.
|
664 | *
|
665 | * The path is resolved relative to the folder of the config file that contains the setting; to change this,
|
666 | * prepend a folder token such as `<projectFolder>`.
|
667 | */
|
668 | reportTempFolder?: string;
|
669 | }
|
670 |
|
671 | /**
|
672 | * Determines how the TypeScript compiler engine will be invoked by API Extractor.
|
673 | *
|
674 | * @remarks
|
675 | * This is part of the {@link IConfigFile} structure.
|
676 | *
|
677 | * @public
|
678 | */
|
679 | export declare interface IConfigCompiler {
|
680 | /**
|
681 | * Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.
|
682 | *
|
683 | * @remarks
|
684 | * The path is resolved relative to the folder of the config file that contains the setting; to change this,
|
685 | * prepend a folder token such as `<projectFolder>`.
|
686 | *
|
687 | * Note: This setting will be ignored if `overrideTsconfig` is used.
|
688 | */
|
689 | tsconfigFilePath?: string;
|
690 | /**
|
691 | * Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.
|
692 | *
|
693 | * @remarks
|
694 | * The value must conform to the TypeScript tsconfig schema:
|
695 | *
|
696 | * http://json.schemastore.org/tsconfig
|
697 | *
|
698 | * If omitted, then the tsconfig.json file will instead be read from the projectFolder.
|
699 | */
|
700 | overrideTsconfig?: {};
|
701 | /**
|
702 | * This option causes the compiler to be invoked with the `--skipLibCheck` option.
|
703 | *
|
704 | * @remarks
|
705 | * This option is not recommended and may cause API Extractor to produce incomplete or incorrect declarations,
|
706 | * but it may be required when dependencies contain declarations that are incompatible with the TypeScript engine
|
707 | * that API Extractor uses for its analysis. Where possible, the underlying issue should be fixed rather than
|
708 | * relying on skipLibCheck.
|
709 | */
|
710 | skipLibCheck?: boolean;
|
711 | }
|
712 |
|
713 | /**
|
714 | * Configures how the doc model file (*.api.json) will be generated.
|
715 | *
|
716 | * @remarks
|
717 | * This is part of the {@link IConfigFile} structure.
|
718 | *
|
719 | * @public
|
720 | */
|
721 | export declare interface IConfigDocModel {
|
722 | /**
|
723 | * Whether to generate a doc model file.
|
724 | */
|
725 | enabled: boolean;
|
726 | /**
|
727 | * The output path for the doc model file. The file extension should be ".api.json".
|
728 | *
|
729 | * @remarks
|
730 | * The path is resolved relative to the folder of the config file that contains the setting; to change this,
|
731 | * prepend a folder token such as `<projectFolder>`.
|
732 | */
|
733 | apiJsonFilePath?: string;
|
734 | }
|
735 |
|
736 | /**
|
737 | * Configures how the .d.ts rollup file will be generated.
|
738 | *
|
739 | * @remarks
|
740 | * This is part of the {@link IConfigFile} structure.
|
741 | *
|
742 | * @public
|
743 | */
|
744 | export declare interface IConfigDtsRollup {
|
745 | /**
|
746 | * Whether to generate the .d.ts rollup file.
|
747 | */
|
748 | enabled: boolean;
|
749 | /**
|
750 | * Specifies the output path for a .d.ts rollup file to be generated without any trimming.
|
751 | *
|
752 | * @remarks
|
753 | * This file will include all declarations that are exported by the main entry point.
|
754 | *
|
755 | * If the path is an empty string, then this file will not be written.
|
756 | *
|
757 | * The path is resolved relative to the folder of the config file that contains the setting; to change this,
|
758 | * prepend a folder token such as `<projectFolder>`.
|
759 | */
|
760 | untrimmedFilePath?: string;
|
761 | /**
|
762 | * Specifies the output path for a .d.ts rollup file to be generated with trimming for an "alpha" release.
|
763 | *
|
764 | * @remarks
|
765 | * This file will include only declarations that are marked as `@public`, `@beta`, or `@alpha`.
|
766 | *
|
767 | * The path is resolved relative to the folder of the config file that contains the setting; to change this,
|
768 | * prepend a folder token such as `<projectFolder>`.
|
769 | */
|
770 | alphaTrimmedFilePath?: string;
|
771 | /**
|
772 | * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
|
773 | *
|
774 | * @remarks
|
775 | * This file will include only declarations that are marked as `@public` or `@beta`.
|
776 | *
|
777 | * The path is resolved relative to the folder of the config file that contains the setting; to change this,
|
778 | * prepend a folder token such as `<projectFolder>`.
|
779 | */
|
780 | betaTrimmedFilePath?: string;
|
781 | /**
|
782 | * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.
|
783 | *
|
784 | * @remarks
|
785 | * This file will include only declarations that are marked as `@public`.
|
786 | *
|
787 | * If the path is an empty string, then this file will not be written.
|
788 | *
|
789 | * The path is resolved relative to the folder of the config file that contains the setting; to change this,
|
790 | * prepend a folder token such as `<projectFolder>`.
|
791 | */
|
792 | publicTrimmedFilePath?: string;
|
793 | /**
|
794 | * When a declaration is trimmed, by default it will be replaced by a code comment such as
|
795 | * "Excluded from this release type: exampleMember". Set "omitTrimmingComments" to true to remove the
|
796 | * declaration completely.
|
797 | */
|
798 | omitTrimmingComments?: boolean;
|
799 | }
|
800 |
|
801 | /**
|
802 | * Configuration options for the API Extractor tool. These options can be constructed programmatically
|
803 | * or loaded from the api-extractor.json config file using the {@link ExtractorConfig} class.
|
804 | *
|
805 | * @public
|
806 | */
|
807 | export declare interface IConfigFile {
|
808 | /**
|
809 | * Optionally specifies another JSON config file that this file extends from. This provides a way for
|
810 | * standard settings to be shared across multiple projects.
|
811 | *
|
812 | * @remarks
|
813 | * If the path starts with `./` or `../`, the path is resolved relative to the folder of the file that contains
|
814 | * the `extends` field. Otherwise, the first path segment is interpreted as an NPM package name, and will be
|
815 | * resolved using NodeJS `require()`.
|
816 | */
|
817 | extends?: string;
|
818 | /**
|
819 | * Determines the `<projectFolder>` token that can be used with other config file settings. The project folder
|
820 | * typically contains the tsconfig.json and package.json config files, but the path is user-defined.
|
821 | *
|
822 | * @remarks
|
823 | *
|
824 | * The path is resolved relative to the folder of the config file that contains the setting.
|
825 | *
|
826 | * The default value for `projectFolder` is the token `<lookup>`, which means the folder is determined using
|
827 | * the following heuristics:
|
828 | *
|
829 | * If the config/rig.json system is used (as defined by {@link https://www.npmjs.com/package/@rushstack/rig-package
|
830 | * | @rushstack/rig-package}), then the `<lookup>` value will be the package folder that referenced the rig.
|
831 | *
|
832 | * Otherwise, the `<lookup>` value is determined by traversing parent folders, starting from the folder containing
|
833 | * api-extractor.json, and stopping at the first folder that contains a tsconfig.json file. If a tsconfig.json file
|
834 | * cannot be found in this way, then an error will be reported.
|
835 | */
|
836 | projectFolder?: string;
|
837 | /**
|
838 | * Specifies the .d.ts file to be used as the starting point for analysis. API Extractor
|
839 | * analyzes the symbols exported by this module.
|
840 | *
|
841 | * @remarks
|
842 | *
|
843 | * The file extension must be ".d.ts" and not ".ts".
|
844 | * The path is resolved relative to the "projectFolder" location.
|
845 | */
|
846 | mainEntryPointFilePath: string;
|
847 | /**
|
848 | * A list of NPM package names whose exports should be treated as part of this package.
|
849 | *
|
850 | * @remarks
|
851 | *
|
852 | * For example, suppose that Webpack is used to generate a distributed bundle for the project `library1`,
|
853 | * and another NPM package `library2` is embedded in this bundle. Some types from `library2` may become part
|
854 | * of the exported API for `library1`, but by default API Extractor would generate a .d.ts rollup that explicitly
|
855 | * imports `library2`. To avoid this, we can specify:
|
856 | *
|
857 | * ```js
|
858 | * "bundledPackages": [ "library2" ],
|
859 | * ```
|
860 | *
|
861 | * This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
|
862 | * local files for `library1`.
|
863 | */
|
864 | bundledPackages?: string[];
|
865 | /**
|
866 | * {@inheritDoc IConfigCompiler}
|
867 | */
|
868 | compiler?: IConfigCompiler;
|
869 | /**
|
870 | * {@inheritDoc IConfigApiReport}
|
871 | */
|
872 | apiReport?: IConfigApiReport;
|
873 | /**
|
874 | * {@inheritDoc IConfigDocModel}
|
875 | */
|
876 | docModel?: IConfigDocModel;
|
877 | /**
|
878 | * {@inheritDoc IConfigDtsRollup}
|
879 | * @beta
|
880 | */
|
881 | dtsRollup?: IConfigDtsRollup;
|
882 | /**
|
883 | * {@inheritDoc IConfigTsdocMetadata}
|
884 | * @beta
|
885 | */
|
886 | tsdocMetadata?: IConfigTsdocMetadata;
|
887 | /**
|
888 | * Specifies what type of newlines API Extractor should use when writing output files.
|
889 | *
|
890 | * @remarks
|
891 | * By default, the output files will be written with Windows-style newlines.
|
892 | * To use POSIX-style newlines, specify "lf" instead.
|
893 | * To use the OS's default newline kind, specify "os".
|
894 | */
|
895 | newlineKind?: 'crlf' | 'lf' | 'os';
|
896 | /**
|
897 | * {@inheritDoc IExtractorMessagesConfig}
|
898 | */
|
899 | messages?: IExtractorMessagesConfig;
|
900 | /**
|
901 | * Set to true when invoking API Extractor's test harness.
|
902 | * @remarks
|
903 | * When `testMode` is true, the `toolVersion` field in the .api.json file is assigned an empty string
|
904 | * to prevent spurious diffs in output files tracked for tests.
|
905 | */
|
906 | testMode?: boolean;
|
907 | /**
|
908 | * Specifies how API Extractor sorts members of an enum when generating api.json.
|
909 | *
|
910 | * @remarks
|
911 | * By default, the output files will be sorted alphabetically, which is "by-name".
|
912 | * To keep the ordering in the source code, specify "preserve".
|
913 | *
|
914 | * @defaultValue `by-name`
|
915 | */
|
916 | enumMemberOrder?: EnumMemberOrder;
|
917 | }
|
918 |
|
919 | /**
|
920 | * Configures reporting for a given message identifier.
|
921 | *
|
922 | * @remarks
|
923 | * This is part of the {@link IConfigFile} structure.
|
924 | *
|
925 | * @public
|
926 | */
|
927 | export declare interface IConfigMessageReportingRule {
|
928 | /**
|
929 | * Specifies whether the message should be written to the the tool's output log.
|
930 | *
|
931 | * @remarks
|
932 | * Note that the `addToApiReportFile` property may supersede this option.
|
933 | */
|
934 | logLevel: ExtractorLogLevel;
|
935 | /**
|
936 | * When `addToApiReportFile` is true: If API Extractor is configured to write an API report file (.api.md),
|
937 | * then the message will be written inside that file; otherwise, the message is instead logged according to
|
938 | * the `logLevel` option.
|
939 | */
|
940 | addToApiReportFile?: boolean;
|
941 | }
|
942 |
|
943 | /**
|
944 | * Specifies a table of reporting rules for different message identifiers, and also the default rule used for
|
945 | * identifiers that do not appear in the table.
|
946 | *
|
947 | * @remarks
|
948 | * This is part of the {@link IConfigFile} structure.
|
949 | *
|
950 | * @public
|
951 | */
|
952 | export declare interface IConfigMessageReportingTable {
|
953 | /**
|
954 | * The key is a message identifier for the associated type of message, or "default" to specify the default policy.
|
955 | * For example, the key might be `TS2551` (a compiler message), `tsdoc-link-tag-unescaped-text` (a TSDOc message),
|
956 | * or `ae-extra-release-tag` (a message related to the API Extractor analysis).
|
957 | */
|
958 | [messageId: string]: IConfigMessageReportingRule;
|
959 | }
|
960 |
|
961 | /**
|
962 | * Configures how the tsdoc-metadata.json file will be generated.
|
963 | *
|
964 | * @remarks
|
965 | * This is part of the {@link IConfigFile} structure.
|
966 | *
|
967 | * @public
|
968 | */
|
969 | export declare interface IConfigTsdocMetadata {
|
970 | /**
|
971 | * Whether to generate the tsdoc-metadata.json file.
|
972 | */
|
973 | enabled: boolean;
|
974 | /**
|
975 | * Specifies where the TSDoc metadata file should be written.
|
976 | *
|
977 | * @remarks
|
978 | * The path is resolved relative to the folder of the config file that contains the setting; to change this,
|
979 | * prepend a folder token such as `<projectFolder>`.
|
980 | *
|
981 | * The default value is `<lookup>`, which causes the path to be automatically inferred from the `tsdocMetadata`,
|
982 | * `typings` or `main` fields of the project's package.json. If none of these fields are set, the lookup
|
983 | * falls back to `tsdoc-metadata.json` in the package folder.
|
984 | */
|
985 | tsdocMetadataFilePath?: string;
|
986 | }
|
987 |
|
988 | /**
|
989 | * Options for {@link ExtractorConfig.tryLoadForFolder}.
|
990 | *
|
991 | * @public
|
992 | */
|
993 | export declare interface IExtractorConfigLoadForFolderOptions {
|
994 | /**
|
995 | * The folder path to start from when searching for api-extractor.json.
|
996 | */
|
997 | startingFolder: string;
|
998 | /**
|
999 | * An already constructed `PackageJsonLookup` cache object to use. If omitted, a temporary one will
|
1000 | * be constructed.
|
1001 | */
|
1002 | packageJsonLookup?: PackageJsonLookup;
|
1003 | /**
|
1004 | * An already constructed `RigConfig` object. If omitted, then a new `RigConfig` object will be constructed.
|
1005 | */
|
1006 | rigConfig?: RigConfig;
|
1007 | }
|
1008 |
|
1009 | /**
|
1010 | * Options for {@link ExtractorConfig.prepare}.
|
1011 | *
|
1012 | * @public
|
1013 | */
|
1014 | export declare interface IExtractorConfigPrepareOptions {
|
1015 | /**
|
1016 | * A configuration object as returned by {@link ExtractorConfig.loadFile}.
|
1017 | */
|
1018 | configObject: IConfigFile;
|
1019 | /**
|
1020 | * The absolute path of the file that the `configObject` object was loaded from. This is used for error messages
|
1021 | * and when probing for `tsconfig.json`.
|
1022 | *
|
1023 | * @remarks
|
1024 | *
|
1025 | * If `configObjectFullPath` and `projectFolderLookupToken` are both unspecified, then the api-extractor.json
|
1026 | * config file must explicitly specify a `projectFolder` setting rather than relying on the `<lookup>` token.
|
1027 | */
|
1028 | configObjectFullPath: string | undefined;
|
1029 | /**
|
1030 | * The parsed package.json file for the working package, or undefined if API Extractor was invoked without
|
1031 | * a package.json file.
|
1032 | *
|
1033 | * @remarks
|
1034 | *
|
1035 | * If omitted, then the `<unscopedPackageName>` and `<packageName>` tokens will have default values.
|
1036 | */
|
1037 | packageJson?: INodePackageJson | undefined;
|
1038 | /**
|
1039 | * The absolute path of the file that the `packageJson` object was loaded from, or undefined if API Extractor
|
1040 | * was invoked without a package.json file.
|
1041 | *
|
1042 | * @remarks
|
1043 | *
|
1044 | * This is used for error messages and when resolving paths found in package.json.
|
1045 | *
|
1046 | * If `packageJsonFullPath` is specified but `packageJson` is omitted, the file will be loaded automatically.
|
1047 | */
|
1048 | packageJsonFullPath: string | undefined;
|
1049 | /**
|
1050 | * The default value for the `projectFolder` setting is the `<lookup>` token, which uses a heuristic to guess
|
1051 | * an appropriate project folder. Use `projectFolderLookupValue` to manually specify the `<lookup>` token value
|
1052 | * instead.
|
1053 | *
|
1054 | * @remarks
|
1055 | * If the `projectFolder` setting is explicitly specified in api-extractor.json file, it should take precedence
|
1056 | * over a value specified via the API. Thus the `projectFolderLookupToken` option provides a way to override
|
1057 | * the default value for `projectFolder` setting while still honoring a manually specified value.
|
1058 | */
|
1059 | projectFolderLookupToken?: string;
|
1060 | /**
|
1061 | * Allow customization of the tsdoc.json config file. If omitted, this file will be loaded from its default
|
1062 | * location. If the file does not exist, then the standard definitions will be used from
|
1063 | * `@microsoft/api-extractor/extends/tsdoc-base.json`.
|
1064 | */
|
1065 | tsdocConfigFile?: TSDocConfigFile;
|
1066 | /**
|
1067 | * When preparing the configuration object, folder and file paths referenced in the configuration are checked
|
1068 | * for existence, and an error is reported if they are not found. This option can be used to disable this
|
1069 | * check for the main entry point module. This may be useful when preparing a configuration file for an
|
1070 | * un-built project.
|
1071 | */
|
1072 | ignoreMissingEntryPoint?: boolean;
|
1073 | }
|
1074 |
|
1075 | /**
|
1076 | * Runtime options for Extractor.
|
1077 | *
|
1078 | * @public
|
1079 | */
|
1080 | export declare interface IExtractorInvokeOptions {
|
1081 | /**
|
1082 | * An optional TypeScript compiler state. This allows an optimization where multiple invocations of API Extractor
|
1083 | * can reuse the same TypeScript compiler analysis.
|
1084 | */
|
1085 | compilerState?: CompilerState;
|
1086 | /**
|
1087 | * Indicates that API Extractor is running as part of a local build, e.g. on developer's
|
1088 | * machine.
|
1089 | *
|
1090 | * @remarks
|
1091 | * This disables certain validation that would normally be performed for a ship/production build. For example,
|
1092 | * the *.api.md report file is automatically updated in a local build.
|
1093 | *
|
1094 | * The default value is false.
|
1095 | */
|
1096 | localBuild?: boolean;
|
1097 | /**
|
1098 | * If true, API Extractor will include {@link ExtractorLogLevel.Verbose} messages in its output.
|
1099 | */
|
1100 | showVerboseMessages?: boolean;
|
1101 | /**
|
1102 | * If true, API Extractor will print diagnostic information used for troubleshooting problems.
|
1103 | * These messages will be included as {@link ExtractorLogLevel.Verbose} output.
|
1104 | *
|
1105 | * @remarks
|
1106 | * Setting `showDiagnostics=true` forces `showVerboseMessages=true`.
|
1107 | */
|
1108 | showDiagnostics?: boolean;
|
1109 | /**
|
1110 | * Specifies an alternate folder path to be used when loading the TypeScript system typings.
|
1111 | *
|
1112 | * @remarks
|
1113 | * API Extractor uses its own TypeScript compiler engine to analyze your project. If your project
|
1114 | * is built with a significantly different TypeScript version, sometimes API Extractor may report compilation
|
1115 | * errors due to differences in the system typings (e.g. lib.dom.d.ts). You can use the "--typescriptCompilerFolder"
|
1116 | * option to specify the folder path where you installed the TypeScript package, and API Extractor's compiler will
|
1117 | * use those system typings instead.
|
1118 | */
|
1119 | typescriptCompilerFolder?: string;
|
1120 | /**
|
1121 | * An optional callback function that will be called for each `ExtractorMessage` before it is displayed by
|
1122 | * API Extractor. The callback can customize the message, handle it, or discard it.
|
1123 | *
|
1124 | * @remarks
|
1125 | * If a `messageCallback` is not provided, then by default API Extractor will print the messages to
|
1126 | * the STDERR/STDOUT console.
|
1127 | */
|
1128 | messageCallback?: (message: ExtractorMessage) => void;
|
1129 | }
|
1130 |
|
1131 | /**
|
1132 | * Constructor options for `ExtractorMessage`.
|
1133 | */
|
1134 | declare interface IExtractorMessageOptions {
|
1135 | category: ExtractorMessageCategory;
|
1136 | messageId: tsdoc.TSDocMessageId | ExtractorMessageId | ConsoleMessageId | string;
|
1137 | text: string;
|
1138 | sourceFilePath?: string;
|
1139 | sourceFileLine?: number;
|
1140 | sourceFileColumn?: number;
|
1141 | properties?: IExtractorMessageProperties;
|
1142 | logLevel?: ExtractorLogLevel;
|
1143 | }
|
1144 |
|
1145 | /**
|
1146 | * Used by {@link ExtractorMessage.properties}.
|
1147 | *
|
1148 | * @public
|
1149 | */
|
1150 | export declare interface IExtractorMessageProperties {
|
1151 | /**
|
1152 | * A declaration can have multiple names if it is exported more than once.
|
1153 | * If an `ExtractorMessage` applies to a specific export name, this property can indicate that.
|
1154 | *
|
1155 | * @remarks
|
1156 | *
|
1157 | * Used by {@link ExtractorMessageId.InternalMissingUnderscore}.
|
1158 | */
|
1159 | readonly exportName?: string;
|
1160 | }
|
1161 |
|
1162 | /**
|
1163 | * Configures how API Extractor reports error and warning messages produced during analysis.
|
1164 | *
|
1165 | * @remarks
|
1166 | * This is part of the {@link IConfigFile} structure.
|
1167 | *
|
1168 | * @public
|
1169 | */
|
1170 | export declare interface IExtractorMessagesConfig {
|
1171 | /**
|
1172 | * Configures handling of diagnostic messages generating the TypeScript compiler while analyzing the
|
1173 | * input .d.ts files.
|
1174 | */
|
1175 | compilerMessageReporting?: IConfigMessageReportingTable;
|
1176 | /**
|
1177 | * Configures handling of messages reported by API Extractor during its analysis.
|
1178 | */
|
1179 | extractorMessageReporting?: IConfigMessageReportingTable;
|
1180 | /**
|
1181 | * Configures handling of messages reported by the TSDoc parser when analyzing code comments.
|
1182 | */
|
1183 | tsdocMessageReporting?: IConfigMessageReportingTable;
|
1184 | }
|
1185 |
|
1186 | export { }
|