Repository navigation
[api-extractor] Option to extend analysis beyond package boundaries #896
Description
Activity
- changed the title
[-]API-Extractor: Option to extend analysis beyond package boundaries #3 [/-][+][api-extractor] Option to extend analysis beyond package boundaries #3 [/+]on Oct 22, 2018 - changed the title
[-][api-extractor] Option to extend analysis beyond package boundaries #3 [/-][+][api-extractor] Option to extend analysis beyond package boundaries[/+]on Oct 23, 2018 It stands to reason that the analysis of external packages could easily lead to the consideration/inclusion of an impractically large number of declarations, degrading AE performance and exploding the size of API review files. Therefore, the "transcend package boundary" option should be paired with a "cut-off" mechanism that allows the user to specify entities at which the analysis stops.
Andreas Eulitz (@aeulitz) FYI the new analyzer performs only "nominal" analysis for external packages that do not have a
"tsdoc": { "tsdocFlavor": "AEDoc" }tag in their package.json file. This would prevent the "extended analysis". I was thinking about relaxing that, but then I remembered when we had started crawling arbitrary .d.ts files (e.g. typings from DefinitelyTyped), those files would sometimes contain degenerate forms or actual syntax errors (that maybe don't cause compiler messages, because the compiler is more lax about parsing such files, especially if skipLibCheck is enabled). Malformed TypeScript code produces malformed AST trees that are sometimes difficult for API Extractor to handle correctly.So perhaps your feature should be split into two parts:
- Every single touched package name is mentioned in the API report file, but "extended analysis" is disabled by default.
- Extended analysis is "opt-in" by editing api-extractor.json and explicitly listing the package names that you want to include.
This way, a human can be involved to make sure the extra junk that gets included was actually intended (and produces usable output).
As of 6.0.2, it seems that AE does not include declarations from other packages in its API review and rollup files. This makes it harder for a package developer to get a comprehensive picture of the API surface s/he is working on. It would be great if AE would have an option to include declarations from external packages, probably in its API review file.
It stands to reason that the analysis of external packages could easily lead to the consideration/inclusion of an impractically large number of declarations, degrading AE performance and exploding the size of API review files. Therefore, the "transcend package boundary" option should be paired with a "cut-off" mechanism that allows the user to specify entities at which the analysis stops. To not impede standalone analysis of a package, the cut-off mechanism should be accommodated within the consuming package.