Skip to content

Commit 12b02d6

Browse files
hiranya911hiranya911
authored
chore: Configuring an API Extractor report for the repo (#1081)
* chore: Configuring an API Extractor report for the repo * fix: Setting declarationMap via gulpfile so that tests are not affected
1 parent 19a7abf commit 12b02d6

9 files changed

+1641
-2
lines changed

‎.github/workflows/ci.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,4 @@ jobs:
2323
npm run build
2424
npm run build:tests
2525
npm test
26+
npm run api-extractor

‎.github/workflows/release.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,9 @@ jobs:
5858
- name: Run unit tests
5959
run: npm test
6060

61+
- name: Verify public API
62+
run: npm run api-extractor
63+
6164
- name: Run integration tests
6265
run: ./.github/scripts/run_integration_tests.sh
6366
env:

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ npm-debug.log
55

66
lib/
77
.tmp/
8+
temp/
89
typings/
910
coverage/
1011
node_modules/

‎api-extractor.json

Lines changed: 368 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,368 @@
1+
/**
2+
* Config file for API Extractor. For more info, please visit: https://api-extractor.com
3+
*/
4+
{
5+
"$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 firebase-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.
51+
"mainEntryPointFilePath": "<projectFolder>/lib/firebase-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+
*/
66+
"bundledPackages": [],
67+
68+
/**
69+
* Determines how the TypeScript compiler engine will be invoked by API Extractor.
70+
*/
71+
"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+
},
107+
108+
/**
109+
* Configures how the API report file (*.api.md) will be generated.
110+
*/
111+
"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/"
157+
},
158+
159+
/**
160+
* Configures how the doc model file (*.api.json) will be generated.
161+
*/
162+
"docModel": {
163+
/**
164+
* (REQUIRED) Whether to generate a doc model file.
165+
*/
166+
"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"
178+
},
179+
180+
/**
181+
* Configures how the .d.ts rollup file will be generated.
182+
*/
183+
"dtsRollup": {
184+
/**
185+
* (REQUIRED) Whether to generate the .d.ts rollup file.
186+
*/
187+
"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
237+
},
238+
239+
/**
240+
* Configures how the tsdoc-metadata.json file will be generated.
241+
*/
242+
"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"
263+
},
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+
*/
279+
"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+
*/
288+
"compilerMessageReporting": {
289+
/**
290+
* Configures the default routing for messages that don't match an explicit rule in this table.
291+
*/
292+
"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+
*/
305+
"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
315+
}
316+
317+
// "TS2551": {
318+
// "logLevel": "warning",
319+
// "addToApiReportFile": true
320+
// },
321+
//
322+
// . . .
323+
},
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+
*/
332+
"extractorMessageReporting": {
333+
"default": {
334+
"logLevel": "warning"
335+
// "addToApiReportFile": false
336+
},
337+
338+
"ae-missing-release-tag": {
339+
"logLevel": "none"
340+
},
341+
342+
"ae-unresolved-link": {
343+
"logLevel": "none"
344+
}
345+
},
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+
*/
354+
"tsdocMessageReporting": {
355+
"default": {
356+
"logLevel": "none"
357+
// "addToApiReportFile": false
358+
}
359+
360+
// "tsdoc-link-tag-unescaped-text": {
361+
// "logLevel": "warning",
362+
// "addToApiReportFile": true
363+
// },
364+
//
365+
// . . .
366+
}
367+
}
368+
}

0 commit comments

Comments
 (0)