mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 17:28:26 -04:00
e41569b4a6
* chore(NA): remove overrides for rootDir on packages * chore(NA): replace './target_types' with 'target_types' on packages * chore(NA): removes stripInternal false configs * chore(NA): remove unused strip internals |
||
|---|---|---|
| .. | ||
| src | ||
| BUILD.bazel | ||
| index.ts | ||
| jest.config.js | ||
| jest.integration.config.js | ||
| kibana.jsonc | ||
| package.json | ||
| README.mdx | ||
| tsconfig.json | ||
--- id: kibDevDocsOpsTypeSummarizer slug: /kibana-dev-docs/ops/type-summarizer title: "@kbn/type-summarizer" description: A tool to summarize and produce a single .d.ts file from tsc output supporting sourcemaps date: 2022-05-17 tags: ['kibana', 'dev', 'contributor', 'operations', 'type', 'summarizer', 'typescript', 'bundler', 'sourcemap'] --- Consumes the .d.ts files produced by `tsc` for a package and generates a single `.d.ts` file of the public types along with a source map that points back to the original source. ## You mean like API Extractor? Yeah, except with source map support and without all the legacy features and other features we disable to generate our current type summaries. We first attempted to implement this in api-extractor but we hit a wall when dealing with the `Span` class. This class handles all the text output which ends up becoming source code, and I wasn't able to find a way to associate specific spans with source locations without getting 12 headaches. Instead I decided to try implementing this from scratch, reducing our reliance on the api-extractor project and putting us in control of how we generate type summaries. ## Using the Type Summarizer The type-summarizer CLI from `@kbn/type-summarizer-cli` is automatically called by bazel via the `pkg_npm_types()` rule. If you want to run the CLI manually use `node scripts/type_summarizer <relatative path to package>` and the type summary for your package will be written to `data/type_summarizer_output`. ## How does it work? The type summarizer code is fairly well documented. The high level approach is to use two phases: ### 1. Indexing In this phase we traverse the symbol and AST graphs to determine the imports, local declarations, and ambient references needed to recreate the exported symbols of a package (along with all their references). This is done by the `AstIndexer` class and more information about the process is available there. ### 2. Printing After indexing is complete we use the created index to produce the necessary source code for the type summary file. This process is completed by the `printTypeSummary()` function in `src/lib/type_summary`, which uses the `SourceNode` class from the [source-map package](https://github.com/mozilla/source-map) to create the code and source maps of the type symmary file at the same time. The logic of this function is documented and should be relatively easy to follow once the structure of the `AstIndex` type is understood.