Skip to content

Commit 32edcac

Browse files
authored
chore: Generating separate API reports for module entry points (#1144)
* chore: Generating separate API reports for module entry points * fix: Using api-extractor library to generate reports
1 parent ed36bb1 commit 32edcac

9 files changed

+991
-850
lines changed

api-extractor.json

Lines changed: 4 additions & 326 deletions
Original file line numberDiff line numberDiff line change
@@ -1,338 +1,32 @@
1-
/**
2-
* Config file for API Extractor. For more info, please visit: https://api-extractor.com
3-
*/
41
{
52
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
6-
7-
/**
8-
* Optionally specifies another JSON config file that this file extends from. This provides a way for
9-
* standard settings to be shared across multiple projects.
10-
*
11-
* If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
12-
* the "extends" field. Otherwise, the first path segment is interpreted as an NPM package name, and will be
13-
* resolved using NodeJS require().
14-
*
15-
* SUPPORTED TOKENS: none
16-
* DEFAULT VALUE: ""
17-
*/
18-
// "extends": "./shared/api-extractor-base.json"
19-
// "extends": "my-package/include/api-extractor-base.json"
20-
21-
/**
22-
* Determines the "<projectFolder>" token that can be used with other config file settings. The project folder
23-
* typically contains the tsconfig.json and package.json config files, but the path is user-defined.
24-
*
25-
* The path is resolved relative to the folder of the config file that contains the setting.
26-
*
27-
* The default value for "projectFolder" is the token "<lookup>", which means the folder is determined by traversing
28-
* parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder
29-
* that contains a tsconfig.json file. If a tsconfig.json file cannot be found in this way, then an error
30-
* will be reported.
31-
*
32-
* SUPPORTED TOKENS: <lookup>
33-
* DEFAULT VALUE: "<lookup>"
34-
*/
35-
// "projectFolder": "..",
36-
37-
/**
38-
* (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis. API Extractor
39-
* analyzes the symbols exported by this module.
40-
*
41-
* The file extension must be ".d.ts" and not ".ts".
42-
*
43-
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
44-
* prepend a folder token such as "<projectFolder>".
45-
*
46-
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
47-
*/
48-
// We point to the default-namespace.d.ts file since index.d.ts uses namespace imports that are
49-
// not supported by API Extractor. See https://github.com/microsoft/rushstack/issues/1029 and
50-
// https://github.com/microsoft/rushstack/issues/2338.
513
"mainEntryPointFilePath": "<projectFolder>/lib/default-namespace.d.ts",
52-
53-
/**
54-
* A list of NPM package names whose exports should be treated as part of this package.
55-
*
56-
* For example, suppose that Webpack is used to generate a distributed bundle for the project "library1",
57-
* and another NPM package "library2" is embedded in this bundle. Some types from library2 may become part
58-
* of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly
59-
* imports library2. To avoid this, we can specify:
60-
*
61-
* "bundledPackages": [ "library2" ],
62-
*
63-
* This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
64-
* local files for library1.
65-
*/
664
"bundledPackages": [],
67-
68-
/**
69-
* Determines how the TypeScript compiler engine will be invoked by API Extractor.
70-
*/
715
"compiler": {
72-
/**
73-
* Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.
74-
*
75-
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
76-
* prepend a folder token such as "<projectFolder>".
77-
*
78-
* Note: This setting will be ignored if "overrideTsconfig" is used.
79-
*
80-
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
81-
* DEFAULT VALUE: "<projectFolder>/tsconfig.json"
82-
*/
83-
// "tsconfigFilePath": "<projectFolder>/tsconfig.json",
84-
/**
85-
* Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.
86-
* The object must conform to the TypeScript tsconfig schema:
87-
*
88-
* http://json.schemastore.org/tsconfig
89-
*
90-
* If omitted, then the tsconfig.json file will be read from the "projectFolder".
91-
*
92-
* DEFAULT VALUE: no overrideTsconfig section
93-
*/
94-
// "overrideTsconfig": {
95-
// . . .
96-
// }
97-
/**
98-
* This option causes the compiler to be invoked with the --skipLibCheck option. This option is not recommended
99-
* and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when
100-
* dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses
101-
* for its analysis. Where possible, the underlying issue should be fixed rather than relying on skipLibCheck.
102-
*
103-
* DEFAULT VALUE: false
104-
*/
105-
// "skipLibCheck": true,
106-
},
1076

108-
/**
109-
* Configures how the API report file (*.api.md) will be generated.
110-
*/
7+
},
1118
"apiReport": {
112-
/**
113-
* (REQUIRED) Whether to generate an API report.
114-
*/
115-
"enabled": true
116-
117-
/**
118-
* The filename for the API report files. It will be combined with "reportFolder" or "reportTempFolder" to produce
119-
* a full file path.
120-
*
121-
* The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/".
122-
*
123-
* SUPPORTED TOKENS: <packageName>, <unscopedPackageName>
124-
* DEFAULT VALUE: "<unscopedPackageName>.api.md"
125-
*/
126-
// "reportFileName": "<unscopedPackageName>.api.md",
127-
128-
/**
129-
* Specifies the folder where the API report file is written. The file name portion is determined by
130-
* the "reportFileName" setting.
131-
*
132-
* The API report file is normally tracked by Git. Changes to it can be used to trigger a branch policy,
133-
* e.g. for an API review.
134-
*
135-
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
136-
* prepend a folder token such as "<projectFolder>".
137-
*
138-
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
139-
* DEFAULT VALUE: "<projectFolder>/etc/"
140-
*/
141-
// "reportFolder": "<projectFolder>/etc/",
142-
143-
/**
144-
* Specifies the folder where the temporary report file is written. The file name portion is determined by
145-
* the "reportFileName" setting.
146-
*
147-
* After the temporary file is written to disk, it is compared with the file in the "reportFolder".
148-
* If they are different, a production build will fail.
149-
*
150-
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
151-
* prepend a folder token such as "<projectFolder>".
152-
*
153-
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
154-
* DEFAULT VALUE: "<projectFolder>/temp/"
155-
*/
156-
// "reportTempFolder": "<projectFolder>/temp/"
9+
"enabled": true,
10+
"reportFileName": ""
15711
},
158-
159-
/**
160-
* Configures how the doc model file (*.api.json) will be generated.
161-
*/
16212
"docModel": {
163-
/**
164-
* (REQUIRED) Whether to generate a doc model file.
165-
*/
16613
"enabled": true
167-
168-
/**
169-
* The output path for the doc model file. The file extension should be ".api.json".
170-
*
171-
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
172-
* prepend a folder token such as "<projectFolder>".
173-
*
174-
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
175-
* DEFAULT VALUE: "<projectFolder>/temp/<unscopedPackageName>.api.json"
176-
*/
177-
// "apiJsonFilePath": "<projectFolder>/temp/<unscopedPackageName>.api.json"
17814
},
179-
180-
/**
181-
* Configures how the .d.ts rollup file will be generated.
182-
*/
18315
"dtsRollup": {
184-
/**
185-
* (REQUIRED) Whether to generate the .d.ts rollup file.
186-
*/
18716
"enabled": false
188-
189-
/**
190-
* Specifies the output path for a .d.ts rollup file to be generated without any trimming.
191-
* This file will include all declarations that are exported by the main entry point.
192-
*
193-
* If the path is an empty string, then this file will not be written.
194-
*
195-
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
196-
* prepend a folder token such as "<projectFolder>".
197-
*
198-
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
199-
* DEFAULT VALUE: "<projectFolder>/dist/<unscopedPackageName>.d.ts"
200-
*/
201-
// "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
202-
203-
/**
204-
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
205-
* This file will include only declarations that are marked as "@public" or "@beta".
206-
*
207-
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
208-
* prepend a folder token such as "<projectFolder>".
209-
*
210-
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
211-
* DEFAULT VALUE: ""
212-
*/
213-
// "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
214-
215-
/**
216-
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.
217-
* This file will include only declarations that are marked as "@public".
218-
*
219-
* If the path is an empty string, then this file will not be written.
220-
*
221-
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
222-
* prepend a folder token such as "<projectFolder>".
223-
*
224-
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
225-
* DEFAULT VALUE: ""
226-
*/
227-
// "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts",
228-
229-
/**
230-
* When a declaration is trimmed, by default it will be replaced by a code comment such as
231-
* "Excluded from this release type: exampleMember". Set "omitTrimmingComments" to true to remove the
232-
* declaration completely.
233-
*
234-
* DEFAULT VALUE: false
235-
*/
236-
// "omitTrimmingComments": true
23717
},
238-
239-
/**
240-
* Configures how the tsdoc-metadata.json file will be generated.
241-
*/
24218
"tsdocMetadata": {
243-
/**
244-
* Whether to generate the tsdoc-metadata.json file.
245-
*
246-
* DEFAULT VALUE: true
247-
*/
248-
// "enabled": true,
249-
/**
250-
* Specifies where the TSDoc metadata file should be written.
251-
*
252-
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
253-
* prepend a folder token such as "<projectFolder>".
254-
*
255-
* The default value is "<lookup>", which causes the path to be automatically inferred from the "tsdocMetadata",
256-
* "typings" or "main" fields of the project's package.json. If none of these fields are set, the lookup
257-
* falls back to "tsdoc-metadata.json" in the package folder.
258-
*
259-
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
260-
* DEFAULT VALUE: "<lookup>"
261-
*/
262-
// "tsdocMetadataFilePath": "<projectFolder>/dist/tsdoc-metadata.json"
19+
"enabled": false
26320
},
264-
265-
/**
266-
* Specifies what type of newlines API Extractor should use when writing output files. By default, the output files
267-
* will be written with Windows-style newlines. To use POSIX-style newlines, specify "lf" instead.
268-
* To use the OS's default newline kind, specify "os".
269-
*
270-
* DEFAULT VALUE: "crlf"
271-
*/
272-
// "newlineKind": "crlf",
273-
274-
/**
275-
* Configures how API Extractor reports error and warning messages produced during analysis.
276-
*
277-
* There are three sources of messages: compiler messages, API Extractor messages, and TSDoc messages.
278-
*/
27921
"messages": {
280-
/**
281-
* Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing
282-
* the input .d.ts files.
283-
*
284-
* TypeScript message identifiers start with "TS" followed by an integer. For example: "TS2551"
285-
*
286-
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
287-
*/
28822
"compilerMessageReporting": {
289-
/**
290-
* Configures the default routing for messages that don't match an explicit rule in this table.
291-
*/
29223
"default": {
293-
/**
294-
* Specifies whether the message should be written to the the tool's output log. Note that
295-
* the "addToApiReportFile" property may supersede this option.
296-
*
297-
* Possible values: "error", "warning", "none"
298-
*
299-
* Errors cause the build to fail and return a nonzero exit code. Warnings cause a production build fail
300-
* and return a nonzero exit code. For a non-production build (e.g. when "api-extractor run" includes
301-
* the "--local" option), the warning is displayed but the build will not fail.
302-
*
303-
* DEFAULT VALUE: "warning"
304-
*/
30524
"logLevel": "warning"
306-
307-
/**
308-
* When addToApiReportFile is true: If API Extractor is configured to write an API report file (.api.md),
309-
* then the message will be written inside that file; otherwise, the message is instead logged according to
310-
* the "logLevel" option.
311-
*
312-
* DEFAULT VALUE: false
313-
*/
314-
// "addToApiReportFile": false
31525
}
316-
317-
// "TS2551": {
318-
// "logLevel": "warning",
319-
// "addToApiReportFile": true
320-
// },
321-
//
322-
// . . .
32326
},
324-
325-
/**
326-
* Configures handling of messages reported by API Extractor during its analysis.
327-
*
328-
* API Extractor message identifiers start with "ae-". For example: "ae-extra-release-tag"
329-
*
330-
* DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings
331-
*/
33227
"extractorMessageReporting": {
33328
"default": {
33429
"logLevel": "warning"
335-
// "addToApiReportFile": false
33630
},
33731

33832
"ae-missing-release-tag": {
@@ -343,26 +37,10 @@
34337
"logLevel": "none"
34438
}
34539
},
346-
347-
/**
348-
* Configures handling of messages reported by the TSDoc parser when analyzing code comments.
349-
*
350-
* TSDoc message identifiers start with "tsdoc-". For example: "tsdoc-link-tag-unescaped-text"
351-
*
352-
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
353-
*/
35440
"tsdocMessageReporting": {
35541
"default": {
35642
"logLevel": "none"
357-
// "addToApiReportFile": false
35843
}
359-
360-
// "tsdoc-link-tag-unescaped-text": {
361-
// "logLevel": "warning",
362-
// "addToApiReportFile": true
363-
// },
364-
//
365-
// . . .
36644
}
36745
}
36846
}

0 commit comments

Comments
 (0)