Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(docs): enrich type information for docs-json Output Target #4212

Merged
merged 1 commit into from
Jun 23, 2023

Conversation

alicewriteswrongs
Copy link
Contributor

@alicewriteswrongs alicewriteswrongs commented Mar 30, 2023

This PR adds significant functionality to the docs-json output target for documenting the types used in a Stencil project.

In particular, it adds a new property to the json blob emitted by docs-json called typeLibrary which includes extensive information about the types used in the public APIs of all the components included in a Stencil project.

Additionally, it adds an option to the docs-json output target, called supplementalPublicTypes, which accepts a filepath pointing to a file with, well, supplemental public types in it 😄 these are basically types which the developers for a Stencil project would like to include in their documentation but which are not used in a public API (e.g. a @Prop, an @Event, etc). The indicated file should be a typescript file which exports types of interest, along the lines of the interface.d.ts file in Framework. All types and interfaces exported from this file will also be documented in the type library, preparing them for easy inclusion in autogenerated documentation or whatever other downstream use-case.

Testing

To test this I'd suggest trying it out in Framework. Do this:

  1. clone and build this branch
  2. install it in framework
  3. change the configuration of the docs-json output target in Framework to specify src/interface.d.ts for the supplementalPublicTypes property

Then do npm run build and look at the docs-json output in docs/core.json. Make sure that all of the types in src/interface.d.ts are present, that the output makes sense, etc. A tool like jq might be helpful for this.

@github-actions
Copy link
Contributor

github-actions bot commented Mar 30, 2023

--strictNullChecks error report

Typechecking with --strictNullChecks resulted in 1627 errors on this branch.

That's 61 fewer than on main! 🎉🎉🎉

reports and statistics

Our most error-prone files
Path Error Count
src/dev-server/index.ts 37
src/mock-doc/serialize-node.ts 36
src/dev-server/server-process.ts 32
src/compiler/prerender/prerender-main.ts 29
src/compiler/build/build-stats.ts 27
src/compiler/output-targets/dist-lazy/generate-lazy-module.ts 26
src/compiler/style/test/optimize-css.spec.ts 23
src/runtime/vdom/vdom-render.ts 23
src/testing/puppeteer/puppeteer-element.ts 23
src/utils/test/message-utils.spec.ts 21
src/runtime/client-hydrate.ts 19
src/screenshot/connector-base.ts 19
src/compiler/bundle/dev-module.ts 17
src/compiler/config/test/validate-paths.spec.ts 16
src/compiler/sys/fetch/tests/fetch-module.spec.ts 16
src/compiler/sys/stencil-sys.ts 15
src/dev-server/request-handler.ts 15
src/sys/node/node-sys.ts 15
src/compiler/prerender/prerender-optimize.ts 14
src/compiler/style/css-parser/serialize-css.ts 14
Our most common errors
Typescript Error Code Count Error messages
TS2345 491
Error messages Argument of type 'string | undefined' is not assignable to parameter of type 'string'.
Type 'undefined' is not assignable to type 'string'.

Argument of type 'Promise<(() => void) | null>' is not assignable to parameter of type 'Promise<() => void>'.

Argument of type 'null' is not assignable to parameter of type 'BuildResultsComponentGraph'.

Argument of type 'Promise<(() => void) | null>' is not assignable to parameter of type 'Promise<() => void>'.
Type '(() => void) | null' is not assignable to type '() => void'.
Type 'null' is not assignable to type '() => void'.

Argument of type 'ComponentRuntimeHostListener[] | undefined' is not assignable to parameter of type 'ComponentRuntimeHostListener[]'.
Type 'undefined' is not assignable to type 'ComponentRuntimeHostListener[]'.

Argument of type 'Logger | undefined' is not assignable to parameter of type 'Logger'.
Type 'undefined' is not assignable to type 'Logger'.

Argument of type 'string[] | undefined' is not assignable to parameter of type 'string[]'.
Type 'undefined' is not assignable to type 'string[]'.

Argument of type 'string' is not assignable to parameter of type 'never'.

Argument of type 'Diagnostic[] | undefined' is not assignable to parameter of type 'readonly Diagnostic[]'.
Type 'undefined' is not assignable to type 'readonly Diagnostic[]'.

Argument of type 'boolean | undefined' is not assignable to parameter of type 'boolean'.

Argument of type 'BuildConditionals | undefined' is not assignable to parameter of type 'BuildConditionals'.
Type 'undefined' is not assignable to type 'BuildConditionals'.

Argument of type 'CompilerSystem | undefined' is not assignable to parameter of type 'CompilerSystem'.
Type 'undefined' is not assignable to type 'CompilerSystem'.

Argument of type '{ styleText: string; output: string; map: null; diagnostics: never[]; imports: never[]; defaultVarName: string; styleDocs: never[]; }' is not assignable to parameter of type 'never'.

Argument of type 'WorkerMeta | undefined' is not assignable to parameter of type 'WorkerMeta'.
Type 'undefined' is not assignable to type 'WorkerMeta'.

Argument of type 'string | null | undefined' is not assignable to parameter of type 'string'.
Type 'undefined' is not assignable to type 'string'.

Argument of type 'Set<string | null>' is not assignable to parameter of type 'Set'.
Type 'string | null' is not assignable to type 'string'.
Type 'null' is not assignable to type 'string'.

Argument of type 'Set<string | null>' is not assignable to parameter of type 'Set'.

Argument of type '(string[] | undefined)[]' is not assignable to parameter of type 'string[][]'.
Type 'string[] | undefined' is not assignable to type 'string[]'.
Type 'undefined' is not assignable to type 'string[]'.

Argument of type 'ComponentCompilerMeta | undefined' is not assignable to parameter of type 'ComponentCompilerMeta'.
Type 'undefined' is not assignable to type 'ComponentCompilerMeta'.

Argument of type 'true | Object | undefined' is not assignable to parameter of type 'boolean | Object | null'.
Type 'undefined' is not assignable to type 'boolean | Object | null'.

Argument of type 'SourceTarget | undefined' is not assignable to parameter of type 'SourceTarget'.
Type 'undefined' is not assignable to type 'SourceTarget'.

Argument of type 'boolean | undefined' is not assignable to parameter of type 'boolean'.
Type 'undefined' is not assignable to type 'boolean'.

Argument of type '(string | undefined)[]' is not assignable to parameter of type 'string[]'.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Argument of type '(string | undefined)[]' is not assignable to parameter of type 'string[]'.

Argument of type 'RollupSourceMap | undefined' is not assignable to parameter of type 'SourceMap'.
Type 'undefined' is not assignable to type 'SourceMap'.

Argument of type 'EntryModule | undefined' is not assignable to parameter of type 'EntryModule'.
Type 'undefined' is not assignable to type 'EntryModule'.

Argument of type '(Module | undefined)[]' is not assignable to parameter of type 'Module[]'.
Type 'Module | undefined' is not assignable to type 'Module'.
Type 'undefined' is not assignable to type 'Module'.

Argument of type 'Document | null' is not assignable to parameter of type 'Document'.
Type 'null' is not assignable to type 'Document'.

Argument of type 'Document | null' is not assignable to parameter of type 'Node | MockNode'.
Type 'null' is not assignable to type 'Node | MockNode'.

Argument of type 'HydrateAnchorElement' is not assignable to parameter of type '{ [attrName: string]: string; }'.
'string' index signatures are incompatible.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Argument of type 'URL | null' is not assignable to parameter of type 'URL'.
Type 'null' is not assignable to type 'URL'.

Argument of type 'string | null' is not assignable to parameter of type 'string'.
Type 'null' is not assignable to type 'string'.

Argument of type 'number | undefined' is not assignable to parameter of type 'number'.
Type 'undefined' is not assignable to type 'number'.

Argument of type 'SitemapXmpResults | null' is not assignable to parameter of type 'SitemapXmpResults'.
Type 'null' is not assignable to type 'SitemapXmpResults'.

Argument of type 'string | undefined' is not assignable to parameter of type 'string | URL'.

Argument of type 'Map<string, string[]> | undefined' is not assignable to parameter of type 'Map<string, string[]>'.
Type 'undefined' is not assignable to type 'Map<string, string[]>'.

Argument of type 'undefined' is not assignable to parameter of type 'string'.

Argument of type 'ServiceWorkerConfig | undefined' is not assignable to parameter of type 'ServiceWorkerConfig'.
Type 'undefined' is not assignable to type 'ServiceWorkerConfig'.

Argument of type 'string | undefined' is not assignable to parameter of type 'string | URL'.
Type 'undefined' is not assignable to type 'string | URL'.

Argument of type 'CssNode[] | null | undefined' is not assignable to parameter of type 'void | CssNode[]'.

Argument of type 'CssNode[] | null | undefined' is not assignable to parameter of type 'void | CssNode[]'.
Type 'null' is not assignable to type 'void | CssNode[]'.

Argument of type 'null' is not assignable to parameter of type 'string'.

Argument of type 'CompilerSystemCreateDirectoryOptions | undefined' is not assignable to parameter of type 'CompilerSystemCreateDirectoryOptions'.
Type 'undefined' is not assignable to type 'CompilerSystemCreateDirectoryOptions'.

Argument of type 'null' is not assignable to parameter of type 'CompilerFileWatcherEvent'.

Argument of type 'null' is not assignable to parameter of type '{ access: (filePath: string) => Promise; accessSync: (filePath: string) => boolean; cancelDeleteDirectoriesFromDisk: (dirPaths: string[]) => void; cancelDeleteFilesFromDisk: (filePaths: string[]) => void; ... 17 more ...; writeFiles: (files: { ...; } | Map<...>, opts?: FsWriteOptions | undefined) => Promise...'.

Argument of type 'undefined' is not assignable to parameter of type 'TypeChecker'.

Argument of type 'CollectionBundleManifest[] | undefined' is not assignable to parameter of type 'any[]'.
Type 'undefined' is not assignable to type 'any[]'.

Argument of type 'Module | undefined' is not assignable to parameter of type 'Module'.
Type 'undefined' is not assignable to type 'Module'.

Argument of type 'NodeArray | undefined' is not assignable to parameter of type 'NodeArray | HeritageClause[]'.
Type 'undefined' is not assignable to type 'NodeArray | HeritageClause[]'.

Argument of type 'Block | undefined' is not assignable to parameter of type 'Block'.
Type 'undefined' is not assignable to type 'Block'.

Argument of type 'Expression | undefined' is not assignable to parameter of type 'Node'.
Type 'undefined' is not assignable to type 'Node'.

Argument of type 'Symbol | undefined' is not assignable to parameter of type 'Symbol'.
Type 'undefined' is not assignable to type 'Symbol'.

Argument of type 'TypeNode | undefined' is not assignable to parameter of type 'Node'.
Type 'undefined' is not assignable to type 'Node'.

Argument of type '(PropertyAssignment | null)[]' is not assignable to parameter of type 'readonly ObjectLiteralElementLike[]'.
Type 'PropertyAssignment | null' is not assignable to type 'ObjectLiteralElementLike'.
Type 'null' is not assignable to type 'ObjectLiteralElementLike'.

Argument of type 'Signature | undefined' is not assignable to parameter of type 'Signature'.
Type 'undefined' is not assignable to type 'Signature'.

Argument of type 'Identifier | undefined' is not assignable to parameter of type 'Node'.
Type 'undefined' is not assignable to type 'Node'.

Argument of type 'ScriptTarget | undefined' is not assignable to parameter of type 'ScriptTarget | CreateSourceFileOptions'.

Argument of type 'Config | null | undefined' is not assignable to parameter of type 'Config'.
Type 'undefined' is not assignable to type 'Config'.

Argument of type 'null' is not assignable to parameter of type 'CollectionCompilerMeta'.

Argument of type 'PropertyName | undefined' is not assignable to parameter of type 'PropertyName'.
Type 'undefined' is not assignable to type 'PropertyName'.

Argument of type 'NamedImportBindings | undefined' is not assignable to parameter of type 'Node'.
Type 'undefined' is not assignable to type 'Node'.

Argument of type 'SourceFile | undefined' is not assignable to parameter of type 'SourceFile'.
Type 'undefined' is not assignable to type 'SourceFile'.

Argument of type 'TypeDeclLike | undefined' is not assignable to parameter of type 'Node'.
Type 'undefined' is not assignable to type 'Node'.

Argument of type 'NamedExportBindings | undefined' is not assignable to parameter of type 'Node'.
Type 'undefined' is not assignable to type 'Node'.

Argument of type 'Declaration | undefined' is not assignable to parameter of type 'Node'.
Type 'undefined' is not assignable to type 'Node'.

Argument of type 'Identifier | undefined' is not assignable to parameter of type 'string | BindingName'.
Type 'undefined' is not assignable to type 'string | BindingName'.

Argument of type 'ScriptTarget | undefined' is not assignable to parameter of type 'ScriptTarget | CreateSourceFileOptions'.
Type 'undefined' is not assignable to type 'ScriptTarget | CreateSourceFileOptions'.

Argument of type 'Diagnostic' is not assignable to parameter of type 'DiagnosticWithLocation'.
Types of property 'file' are incompatible.
Type 'SourceFile | undefined' is not assignable to type 'SourceFile'.
Type 'undefined' is not assignable to type 'SourceFile'.

Argument of type '(...pathSegments: string[]) => string | undefined' is not assignable to parameter of type '(...args: string[]) => string'.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Argument of type 'CompilerWatcher | undefined' is not assignable to parameter of type 'CompilerWatcher'.
Type 'undefined' is not assignable to type 'CompilerWatcher'.

Argument of type 'DevServer | null' is not assignable to parameter of type 'DevServer'.
Type 'null' is not assignable to type 'DevServer'.

Argument of type '{ editor: string | undefined; }' is not assignable to parameter of type 'OpenInEditorOptions'.
Types of property 'editor' are incompatible.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Argument of type 'string | undefined' is not assignable to parameter of type 'PathLike'.

Argument of type 'DevServerConfig | undefined' is not assignable to parameter of type 'DevServerConfig'.
Type 'undefined' is not assignable to type 'DevServerConfig'.

Argument of type 'CompilerBuildResults | undefined' is not assignable to parameter of type 'CompilerBuildResults'.
Type 'undefined' is not assignable to type 'CompilerBuildResults'.

Argument of type 'Window | undefined' is not assignable to parameter of type 'Window'.
Type 'undefined' is not assignable to type 'Window'.

Argument of type 'SerializeDocumentOptions | undefined' is not assignable to parameter of type 'HydrateDocumentOptions'.
Type 'undefined' is not assignable to type 'HydrateDocumentOptions'.

Argument of type 'HydrateDocumentOptions | undefined' is not assignable to parameter of type 'HydrateDocumentOptions'.
Type 'undefined' is not assignable to type 'HydrateDocumentOptions'.

Argument of type 'MockNode | null' is not assignable to parameter of type 'MockNode'.
Type 'null' is not assignable to type 'MockNode'.

Argument of type 'string | undefined' is not assignable to parameter of type 'string | null'.
Type 'undefined' is not assignable to type 'string | null'.

Argument of type 'string | undefined' is not assignable to parameter of type 'string | null'.

Argument of type 'ShadowRoot | null' is not assignable to parameter of type 'Node'.
Type 'null' is not assignable to type 'Node'.

Argument of type 'MockElement' is not assignable to parameter of type 'MockHTMLElement'.
Types of property 'namespaceURI' are incompatible.
Type 'string | null' is not assignable to type 'string'.
Type 'null' is not assignable to type 'string'.

Argument of type 'null' is not assignable to parameter of type 'string | Node'.

Argument of type 'null' is not assignable to parameter of type 'string | boolean | undefined'.

Argument of type '(Window & typeof globalThis) | null' is not assignable to parameter of type 'Window'.
Type 'null' is not assignable to type 'Window'.

Argument of type 'string | null | undefined' is not assignable to parameter of type 'string | undefined'.

Argument of type 'HostRef | undefined' is not assignable to parameter of type 'HostRef'.
Type 'undefined' is not assignable to type 'HostRef'.

Argument of type 'this' is not assignable to parameter of type 'HostElement'.
Type 'HostElement' is not assignable to type 'import("/home/runner/work/stencil/stencil/src/declarations/stencil-private").HostElement'.
The types returned by 'componentOnReady()' are incompatible between these types.
Type 'Promise | undefined' is not assignable to type 'Promise'.
Type 'undefined' is not assignable to type 'Promise'.

Argument of type 'this' is not assignable to parameter of type 'HostElement'.

Argument of type 'string | null' is not assignable to parameter of type 'string | undefined'.

Argument of type 'PropertyDescriptor | undefined' is not assignable to parameter of type 'PropertyDescriptor & ThisType'.
Type 'undefined' is not assignable to type 'PropertyDescriptor & ThisType'.
Type 'undefined' is not assignable to type 'PropertyDescriptor'.

Argument of type 'VNode[] | undefined' is not assignable to parameter of type 'VNode[]'.
Type 'undefined' is not assignable to type 'VNode[]'.

Argument of type 'null | undefined' is not assignable to parameter of type 'ChildType'.
Type 'undefined' is not assignable to type 'ChildType'.

Argument of type 'VNode | null' is not assignable to parameter of type 'ChildType'.
Type 'null' is not assignable to type 'ChildType'.

Argument of type 'VNode | undefined' is not assignable to parameter of type 'ChildType'.
Type 'undefined' is not assignable to type 'ChildType'.

Argument of type 'VNode | null | undefined' is not assignable to parameter of type 'ChildType'.
Type 'undefined' is not assignable to type 'ChildType'.

Argument of type 'null | undefined' is not assignable to parameter of type 'ChildType'.

Argument of type 'RenderNode | undefined' is not assignable to parameter of type 'Node | null'.
Type 'undefined' is not assignable to type 'Node | null'.

Argument of type 'VNode | undefined' is not assignable to parameter of type 'VNode'.
Type 'undefined' is not assignable to type 'VNode'.

Argument of type 'null' is not assignable to parameter of type 'VNode'.

Argument of type 'null' is not assignable to parameter of type 'RenderNode'.

Argument of type 'ScreenshotDiff | undefined' is not assignable to parameter of type 'ScreenshotDiff'.
Type 'undefined' is not assignable to type 'ScreenshotDiff'.

Argument of type 'string | undefined' is not assignable to parameter of type 'PathLike'.
Type 'undefined' is not assignable to type 'PathLike'.

Argument of type 'string | undefined' is not assignable to parameter of type 'string | SemVer'.
Type 'undefined' is not assignable to type 'string | SemVer'.

Argument of type 'string | undefined' is not assignable to parameter of type 'string | SemVer'.

Argument of type 'null' is not assignable to parameter of type 'number | undefined'.

Argument of type 'null' is not assignable to parameter of type 'number | PromiseLike'.

Argument of type 'CompilerWorkerTask | undefined' is not assignable to parameter of type 'CompilerWorkerTask'.
Type 'undefined' is not assignable to type 'CompilerWorkerTask'.

Argument of type 'undefined' is not assignable to parameter of type 'ErrorHandler'.

Argument of type 'string | undefined' is not assignable to parameter of type 'MockRequestInfo'.
Type 'undefined' is not assignable to type 'MockRequestInfo'.

Argument of type 'string | undefined' is not assignable to parameter of type 'MockRequestInfo'.

Argument of type 'MockResponse | undefined' is not assignable to parameter of type 'MockResponse'.
Type 'undefined' is not assignable to type 'MockResponse'.

Argument of type 'RuntimeRef | undefined' is not assignable to parameter of type 'RuntimeRef'.
Type 'undefined' is not assignable to type 'RuntimeRef'.

Argument of type 'this' is not assignable to parameter of type 'E2EElementInternal'.
Type 'E2EElement' is not assignable to type 'E2EElementInternal'.
Types of property 'find' are incompatible.
Type '(selector: string) => Promise<E2EElement | null>' is not assignable to type '(selector: FindSelector) => Promise'.

Argument of type '(elm: Element, pseudoElt: string) => any' is not assignable to parameter of type 'string | EvaluateFunc<[ElementHandle, string | null | undefined]>'.
Type '(elm: Element, pseudoElt: string) => any' is not assignable to type 'EvaluateFunc<[ElementHandle, string | null | undefined]>'.
Types of parameters 'pseudoElt' and 'params_1' are incompatible.
Type 'string | null | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Argument of type 'this' is not assignable to parameter of type 'E2EElementInternal'.

Argument of type '{ viewport: EmulateViewport | undefined; userAgent: string | undefined; }' is not assignable to parameter of type 'Device'.
Types of property 'userAgent' are incompatible.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Argument of type 'null' is not assignable to parameter of type 'SourceMap | undefined'.
TS2322 477
Error messages Type 'string | null | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Type 'boolean | null | undefined' is not assignable to type 'boolean | undefined'.
Type 'null' is not assignable to type 'boolean | undefined'.

Type 'undefined' is not assignable to type 'string'.

Type 'undefined' is not assignable to type 'ComponentConstructor | Promise'.

Type '({ type: "chunk"; fileName: string; map: SourceMap | undefined; code: string; moduleFormat: ModuleFormat | undefined; entryKey: string; imports: string[]; isEntry: boolean; ... 4 more ...; content?: undefined; } | { ...; })[]' is not assignable to type 'RollupResult[]'.
Type '{ type: "chunk"; fileName: string; map: SourceMap | undefined; code: string; moduleFormat: ModuleFormat | undefined; entryKey: string; imports: string[]; isEntry: boolean; ... 4 more ...; content?: undefined; } | { ...; }' is not assignable to type 'RollupResult'.
Type '{ type: "chunk"; fileName: string; map: SourceMap | undefined; code: string; moduleFormat: ModuleFormat | undefined; entryKey: string; imports: string[]; isEntry: boolean; ... 4 more ...; content?: undefined; }' is not assignable to type 'RollupResult'.
Type '{ type: "chunk"; fileName: string; map: SourceMap | undefined; code: string; moduleFormat: ModuleFormat | undefined; entryKey: string; imports: string[]; isEntry: boolean; ... 4 more ...; content?: undefined; }' is not assignable to type 'RollupChunkResult'.
Types of property 'moduleFormat' are incompatible.
Type 'ModuleFormat | undefined' is not assignable to type 'ModuleFormat'.
Type 'undefined' is not assignable to type 'ModuleFormat'.

Type 'null' is not assignable to type 'CompilerBuildResults'.

Type 'null' is not assignable to type 'string'.

Type 'undefined' is not assignable to type 'Document'.

Type 'null' is not assignable to type 'Promise'.

Type 'null' is not assignable to type 'LoggerTimeSpan'.

Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Type 'boolean | undefined' is not assignable to type 'boolean'.

Type 'number | undefined' is not assignable to type 'number'.
Type 'undefined' is not assignable to type 'number'.

Type 'boolean | "prod" | undefined' is not assignable to type 'boolean | "prod"'.
Type 'undefined' is not assignable to type 'boolean | "prod"'.

Type 'BuildResultsComponentGraph | undefined' is not assignable to type 'BuildResultsComponentGraph'.
Type 'undefined' is not assignable to type 'BuildResultsComponentGraph'.

Type 'RollupResults | undefined' is not assignable to type 'RollupResults'.
Type 'undefined' is not assignable to type 'RollupResults'.

Type '{ name: string | undefined; source: string; tags: any[]; }[]' is not assignable to type '{ name: string; source: string; tags: string[]; }[]'.
Type '{ name: string | undefined; source: string; tags: any[]; }' is not assignable to type '{ name: string; source: string; tags: string[]; }'.
Types of property 'name' are incompatible.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Type 'null' is not assignable to type 'CompilerWorkerContext'.

Type 'null' is not assignable to type 'WatchOfConfigFile'.

Type 'null' is not assignable to type 'Promise<(void | void[])[]>'.

Type 'Promise<(void | void[] | null)[]>' is not assignable to type 'Promise<(void | void[])[]>'.
Type '(void | void[] | null)[]' is not assignable to type '(void | void[])[]'.
Type 'void | void[] | null' is not assignable to type 'void | void[]'.
Type 'null' is not assignable to type 'void | void[]'.

Type 'null' is not assignable to type '{ program: WatchOfConfigFile; rebuild: () => void; }'.

Type '(this: PluginContext, importee: string, importer: string) => Promise' is not assignable to type 'ResolveIdHook'.
Types of parameters 'importer' and 'importer' are incompatible.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Type '(this: PluginContext, importee: string, importer: string) => Promise' is not assignable to type 'ResolveIdHook'.
Types of parameters 'importer' and 'importer' are incompatible.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Type 'string | null' is not assignable to type 'string'.
Type 'null' is not assignable to type 'string'.

Type 'null' is not assignable to type 'string | undefined'.

Type '{ code: string; exports: string[]; workerMsgId: string; dependencies: string[]; } | null' is not assignable to type 'WorkerMeta | undefined'.
Type 'null' is not assignable to type 'WorkerMeta | undefined'.

Type 'WorkerMeta | undefined' is not assignable to type 'WorkerMeta'.
Type 'undefined' is not assignable to type 'WorkerMeta'.

Type 'CompilerSystem | undefined' is not assignable to type 'CompilerSystem'.
Type 'undefined' is not assignable to type 'CompilerSystem'.

Type 'Logger | undefined' is not assignable to type 'Logger'.
Type 'undefined' is not assignable to type 'Logger'.

Type 'import("/home/runner/work/stencil/stencil/src/compiler/cache").Cache' is not assignable to type 'import("/home/runner/work/stencil/stencil/src/declarations/stencil-private").Cache'.
The types returned by 'get(...)' are incompatible between these types.
Type 'Promise<string | null>' is not assignable to type 'Promise'.

Type 'null' is not assignable to type 'ValidatedConfig'.
Type 'null' is not assignable to type 'Config'.

Type 'null' is not assignable to type 'string[]'.

Type '{ dir: string; buildDir: string; collectionDir: string | null; typesDir: string; esmLoaderPath: string; copy: d.CopyTask[]; polyfills: boolean | undefined; empty: boolean; transformAliasedImportPathsInCollection: boolean; isPrimaryPackageOutputTarget: boolean; type: "dist"; }' is not assignable to type 'Required'.
Types of property 'polyfills' are incompatible.
Type 'boolean | undefined' is not assignable to type 'boolean'.

Type 'null' is not assignable to type 'number | undefined'.

Type 'null' is not assignable to type 'HistoryApiFallback | undefined'.

Type 'null' is not assignable to type 'CopyTask[] | undefined'.

Type '{ dirPath: string; filePath: string; fileName: string; readmePath: string; usagesDir: string; tag: string; readme: string | undefined; overview: string; usage: JsonDocsUsage; ... 13 more ...; listeners: JsonDocsListener[]; }[]' is not assignable to type 'JsonDocsComponent[]'.
Type '{ dirPath: string; filePath: string; fileName: string; readmePath: string; usagesDir: string; tag: string; readme: string | undefined; overview: string; usage: d.JsonDocsUsage; docs: string; ... 12 more ...; listeners: d.JsonDocsListener[]; }' is not assignable to type 'JsonDocsComponent'.
Types of property 'readme' are incompatible.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Type 'string[] | undefined' is not assignable to type 'string[]'.
Type 'undefined' is not assignable to type 'string[]'.

Type '(ComponentCompilerMeta | undefined)[]' is not assignable to type 'ComponentCompilerMeta[]'.
Type 'ComponentCompilerMeta | undefined' is not assignable to type 'ComponentCompilerMeta'.
Type 'undefined' is not assignable to type 'ComponentCompilerMeta'.

Type '(ComponentCompilerMeta | undefined)[][]' is not assignable to type 'readonly ComponentCompilerMeta[][]'.
Type '(ComponentCompilerMeta | undefined)[]' is not assignable to type 'ComponentCompilerMeta[]'.

Type 'null' is not assignable to type 'boolean | SourceMapOptions | undefined'.

Type 'null' is not assignable to type 'SourceMap | undefined'.

Type '{ name: string | undefined; tags: string[]; }[]' is not assignable to type 'CollectionDependencyData[]'.
Type '{ name: string | undefined; tags: string[]; }' is not assignable to type 'CollectionDependencyData'.
Types of property 'name' are incompatible.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Type 'string | undefined' is not assignable to type 'string | number'.
Type 'undefined' is not assignable to type 'string | number'.

Type 'SourceMap | undefined' is not assignable to type 'SourceMap'.
Type 'undefined' is not assignable to type 'SourceMap'.

Type 'string | null' is not assignable to type 'string | undefined'.

Type 'null' is not assignable to type 'Function'.

Type 'null' is not assignable to type 'Map<string, string[]>'.

Type 'null' is not assignable to type 'PrerenderConfig'.

Type 'null' is not assignable to type 'Set'.

Type 'null' is not assignable to type 'HydrateAnchorElement[]'.

Type 'null' is not assignable to type '(prerenderRequest: PrerenderUrlRequest) => Promise'.

Type 'CssNode | null' is not assignable to type 'void | CssNode'.
Type 'null' is not assignable to type 'void | CssNode'.

Type 'CssNode | null' is not assignable to type 'CssNode'.
Type 'null' is not assignable to type 'CssNode'.

Type 'CssNode | null' is not assignable to type 'void | CssNode'.

Type 'RegExpExecArray | null' is not assignable to type 'RegExpExecArray'.
Type 'null' is not assignable to type 'RegExpExecArray'.

Type 'null' is not assignable to type '() => string'.

Type 'null' is not assignable to type 'number'.

Type 'null' is not assignable to type 'boolean'.

Type 'null' is not assignable to type 'boolean | undefined'.

Type 'FsItem | undefined' is not assignable to type 'FsItem'.
Type 'undefined' is not assignable to type 'FsItem'.

Type 'null' is not assignable to type 'CompilerFileWatcherCallback[]'.

Type '(key: string) => string | undefined' is not assignable to type '(key: string) => string'.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Type '(p: string) => Promise<string | undefined>' is not assignable to type '{ (p: string): Promise; (p: string, encoding: "utf8"): Promise; (p: string, encoding: "binary"): Promise; }'.
Type 'Promise<string | undefined>' is not assignable to type 'Promise'.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Type '(p: string) => string | undefined' is not assignable to type '(p: string, encoding?: string | undefined) => string'.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Type '((maxConcurrentWorkers: number) => WorkerMainController) | null' is not assignable to type '((maxConcurrentWorkers: number) => WorkerMainController) | undefined'.
Type 'null' is not assignable to type '((maxConcurrentWorkers: number) => WorkerMainController) | undefined'.

Type 'null' is not assignable to type 'ResolvedModuleWithFailedLookupLocations'.

Type 'null' is not assignable to type 'Worker'.

Type 'CollectionCompilerMeta | undefined' is not assignable to type 'CollectionCompilerMeta'.
Type 'undefined' is not assignable to type 'CollectionCompilerMeta'.

Type 'DeclarationName | undefined' is not assignable to type 'DeclarationName'.
Type 'undefined' is not assignable to type 'DeclarationName'.

Type 'boolean | null' is not assignable to type 'boolean'.
Type 'null' is not assignable to type 'boolean'.

Type 'undefined' is not assignable to type 'ComponentCompilerVirtualProperty'.

Type '{ name: string; method: string; bubbles: boolean; cancelable: boolean; composed: boolean; docs: CompilerJsDoc; complexType: ComponentCompilerEventComplexType; internal: boolean | undefined; }[]' is not assignable to type 'ComponentCompilerEvent[]'.
Type '{ name: string; method: string; bubbles: boolean; cancelable: boolean; composed: boolean; docs: d.CompilerJsDoc; complexType: d.ComponentCompilerEventComplexType; internal: boolean | undefined; }' is not assignable to type 'ComponentCompilerEvent'.
Types of property 'internal' are incompatible.
Type 'boolean | undefined' is not assignable to type 'boolean'.

Type '{ name: string; docs: CompilerJsDoc; complexType: ComponentCompilerMethodComplexType; internal: boolean | undefined; }[]' is not assignable to type 'ComponentCompilerMethod[]'.
Type '{ name: string; docs: d.CompilerJsDoc; complexType: d.ComponentCompilerMethodComplexType; internal: boolean | undefined; }' is not assignable to type 'ComponentCompilerMethod'.
Types of property 'internal' are incompatible.
Type 'boolean | undefined' is not assignable to type 'boolean'.

Type '{ name: string; type: ComponentCompilerPropertyType; attribute: string | undefined; reflect: boolean; mutable: boolean; required: boolean; optional: boolean; defaultValue: string | undefined; complexType: ComponentCompilerPropertyComplexType; docs: CompilerJsDoc; internal: boolean | undefined; }[]' is not assignable to type 'ComponentCompilerProperty[]'.
Type '{ name: string; type: d.ComponentCompilerPropertyType; attribute: string | undefined; reflect: boolean; mutable: boolean; required: boolean; optional: boolean; defaultValue: string | undefined; complexType: d.ComponentCompilerPropertyComplexType; docs: d.CompilerJsDoc; internal: boolean | undefined; }' is not assignable to type 'ComponentCompilerProperty'.
Types of property 'internal' are incompatible.
Type 'boolean | undefined' is not assignable to type 'boolean'.

Type 'null' is not assignable to type 'ImportData'.

Type 'undefined' is not assignable to type '"queryparams" | null'.

Type 'null' is not assignable to type 'WeakSet'.

Type 'Node | readonly Node[] | undefined' is not assignable to type 'VisitResult'.
Type 'undefined' is not assignable to type 'VisitResult'.

Type 'null' is not assignable to type 'Module'.

Type 'Module | undefined' is not assignable to type 'Module'.
Type 'undefined' is not assignable to type 'Module'.

Type 'undefined' is not assignable to type 'CompilerJsDoc'.

Type '{ [x: string]: d.TypesMemberNameData[] | undefined; }' is not assignable to type 'TypesImportData'.
'string' index signatures are incompatible.
Type 'TypesMemberNameData[] | undefined' is not assignable to type 'TypesMemberNameData[]'.
Type 'undefined' is not assignable to type 'TypesMemberNameData[]'.

Type '((data: { file: string; line: number; column: number; }) => void) | null' is not assignable to type 'OpenInEditorCallback | undefined'.
Type 'null' is not assignable to type 'OpenInEditorCallback | undefined'.

Type 'null' is not assignable to type 'WebSocket'.

Type 'null' is not assignable to type 'BuildOnEventRemove'.

Type 'null' is not assignable to type '() => void'.

Type 'null' is not assignable to type '(msg: DevServerMessage) => void'.

Type 'DevServerConfig | undefined' is not assignable to type 'DevServerConfig'.
Type 'undefined' is not assignable to type 'DevServerConfig'.

Type 'null' is not assignable to type '{ open(openId: string): Promise; }'.

Type 'null' is not assignable to type 'Promise<DevServerEditor[]>'.

Type 'null' is not assignable to type '(req: IncomingMessage, res: ServerResponse, next: () => void) => void'.

Type 'null' is not assignable to type 'URL'.

Type 'null' is not assignable to type 'URLSearchParams'.

Type 'PageReloadStrategy | undefined' is not assignable to type 'PageReloadStrategy'.
Type 'undefined' is not assignable to type 'PageReloadStrategy'.

Type 'null' is not assignable to type 'Server<typeof IncomingMessage, typeof ServerResponse>'.

Type 'null' is not assignable to type 'DevWebSocket'.

Type 'null' is not assignable to type 'DevServerContext'.

Type 'DevWebSocket | null' is not assignable to type 'DevWebSocket'.
Type 'null' is not assignable to type 'DevWebSocket'.

Type 'string | undefined' is not assignable to type 'string | null'.

Type 'null' is not assignable to type 'ChildProcess'.

Type 'null' is not assignable to type 'HydrateApp'.

Type '() => undefined' is not assignable to type '{ (cb?: (() => void) | undefined): TestServerResponse; (chunk: any, cb?: (() => void) | undefined): TestServerResponse; (chunk: any, encoding: BufferEncoding, cb?: (() => void) | undefined): TestServerResponse; }'.
Type 'undefined' is not assignable to type 'TestServerResponse'.

Type 'HTMLElement | null' is not assignable to type 'HTMLElement'.
Type 'null' is not assignable to type 'HTMLElement'.

Type 'null' is not assignable to type 'ComponentConstructor'.

Type '(this: HostElement) => Promise | undefined' is not assignable to type '() => Promise'.
Type 'Promise | undefined' is not assignable to type 'Promise'.
Type 'undefined' is not assignable to type 'Promise'.

Type 'null' is not assignable to type 'Window & typeof globalThis'.
Type 'null' is not assignable to type 'Window'.

Type 'null' is not assignable to type 'Window & typeof globalThis'.

Type 'null' is not assignable to type 'MockCSSStyleSheet'.

Type 'null' is not assignable to type 'string | boolean'.

Type 'null' is not assignable to type 'Location'.

Type 'null' is not assignable to type 'MockElement'.

Type 'null' is not assignable to type 'SVGSVGElement'.

Type 'null' is not assignable to type 'SVGElement'.

Type 'null' is not assignable to type 'EventTarget'.

Type 'null' is not assignable to type 'MockEventListener[]'.

Type 'null' is not assignable to type 'MockDocument'.

Type '{ name: string; value: string; namespace: string | null; prefix: null; }[]' is not assignable to type 'Attribute[]'.
Type '{ name: string; value: string; namespace: string | null; prefix: null; }' is not assignable to type 'Attribute'.
Types of property 'namespace' are incompatible.
Type 'string | null' is not assignable to type 'string | undefined'.
Type 'null' is not assignable to type 'string | undefined'.

Type '(element: MockElement) => string | null' is not assignable to type '(element: unknown) => string'.
Type 'string | null' is not assignable to type 'string'.
Type 'null' is not assignable to type 'string'.

Type 'ParentNode | null' is not assignable to type 'Node'.
Type 'null' is not assignable to type 'Node'.

Type 'null' is not assignable to type 'Document'.

Type 'string | null | undefined' is not assignable to type 'string | undefined'.

Type 'never[] | null' is not assignable to type 'RenderNode[]'.
Type 'null' is not assignable to type 'RenderNode[]'.

Type 'null' is not assignable to type 'VNode[]'.

Type 'null' is not assignable to type 'string | number | undefined'.

Type 'null' is not assignable to type 'string | number | Function'.

Type 'RenderNode | null' is not assignable to type 'RenderNode'.
Type 'null' is not assignable to type 'RenderNode'.

Type 'HTMLElement | null' is not assignable to type 'EventTarget'.
Type 'null' is not assignable to type 'EventTarget'.

Type 'string | null | undefined' is not assignable to type 'string | undefined'.
Type 'null' is not assignable to type 'string | undefined'.

Type 'Promise | undefined' is not assignable to type 'Promise'.
Type 'undefined' is not assignable to type 'Promise'.

Type 'VNode[] | undefined' is not assignable to type 'VNode[]'.
Type 'undefined' is not assignable to type 'VNode[]'.

Type '(props: {}, children: VNode[], utils: FunctionalUtilities) => null' is not assignable to type 'FunctionalComponent<{}>'.
Type 'null' is not assignable to type 'VNode | VNode[]'.

Type '() => null' is not assignable to type 'FunctionalComponent<{}>'.
Type 'null' is not assignable to type 'VNode | VNode[]'.

Type 'null' is not assignable to type 'VNode'.

Type 'undefined' is not assignable to type 'VNode'.

Type 'RenderNode | undefined' is not assignable to type 'RenderNode'.
Type 'undefined' is not assignable to type 'RenderNode'.

Type 'RelocateNodeData | undefined' is not assignable to type 'RelocateNodeData'.
Type 'undefined' is not assignable to type 'RelocateNodeData'.

Type 'ChildNode | null' is not assignable to type 'Node'.
Type 'null' is not assignable to type 'Node'.

Type 'null' is not assignable to type 'ScreenshotCache'.

Type 'null' is not assignable to type 'Buffer'.

Type 'null' is not assignable to type 'Screenshot'.

Type '(() => void) | undefined' is not assignable to type '() => any'.
Type 'undefined' is not assignable to type '() => any'.

Type '() => null' is not assignable to type '(opts: { rootDir: string; moduleId: string; path: string; }) => string'.
Type 'null' is not assignable to type 'string'.

Type '() => null' is not assignable to type '(opts: { moduleId: string; path?: string | undefined; version?: string | undefined; }) => string'.
Type 'null' is not assignable to type 'string'.

Type '() => string | undefined' is not assignable to type '() => string'.
Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Type 'number | null' is not assignable to type 'number'.
Type 'null' is not assignable to type 'number'.

Type 'any[] | undefined' is not assignable to type 'any[]'.
Type 'undefined' is not assignable to type 'any[]'.

Type 'boolean | null | undefined' is not assignable to type 'boolean | undefined'.

Type 'undefined' is not assignable to type 'MockNode'.

Type 'null' is not assignable to type 'MockNode[]'.

Type 'null' is not assignable to type 'ConfigBundle[] | undefined'.

Type 'null' is not assignable to type 'OutputTarget[] | undefined'.

Type 'null' is not assignable to type 'TestingConfig | undefined'.

Type 'null' is not assignable to type 'Cache'.

Type 'null' is not assignable to type '{ access: (filePath: string) => Promise; accessSync: (filePath: string) => boolean; cancelDeleteDirectoriesFromDisk: (dirPaths: string[]) => void; cancelDeleteFilesFromDisk: (filePaths: string[]) => void; ... 17 more ...; writeFiles: (files: { ...; } | Map<...>, opts?: FsWriteOptions | undefined) => Promise...'.

Type 'Function | undefined' is not assignable to type 'Function'.
Type 'undefined' is not assignable to type 'Function'.

Type 'RafCallback | undefined' is not assignable to type 'Function'.
Type 'undefined' is not assignable to type 'Function'.

Type 'QueuedLoadModule | undefined' is not assignable to type 'QueuedLoadModule'.
Type 'undefined' is not assignable to type 'QueuedLoadModule'.

Type 'null' is not assignable to type 'ElementHandle'.

Type 'null' is not assignable to type 'E2EPageInternal'.

Type 'ElementHandle | null' is not assignable to type 'ElementHandle'.
Type 'null' is not assignable to type 'ElementHandle'.

Type 'ElementHandle | null' is not assignable to type 'ElementHandle'.
Type 'null' is not assignable to type 'ElementHandle'.

Type 'ElementHandle | null' is not assignable to type 'ElementHandle | null'.
Type 'ElementHandle' is not assignable to type 'ElementHandle'.
Type 'Node' is missing the following properties from type 'Element': attributes, classList, className, clientHeight, and 113 more.

Type 'null' is not assignable to type 'Promise<JSHandle>'.

Type 'null' is not assignable to type 'CompilerWatcher'.

Type 'null' is not assignable to type 'Promise'.

Type 'Browser | null' is not assignable to type 'Browser'.
Type 'null' is not assignable to type 'Browser'.

Type 'null' is not assignable to type 'ValidatedConfig'.

Type 'null' is not assignable to type 'DevServer'.

Type 'null' is not assignable to type 'Browser'.

Type 'null' is not assignable to type 'SourceMap'.

Type 'null' is not assignable to type 'PackageJsonData'.
TS18048 382
Error messages 'sys.details' is possibly 'undefined'.

'details' is possibly 'undefined'.

'config.sys.getDevServerExecutingPath' is possibly 'undefined'.

'config.sys.dynamicImport' is possibly 'undefined'.

'config.sys.lazyRequire' is possibly 'undefined'.

'sys.parseYarnLockFile' is possibly 'undefined'.

'sys.fetch' is possibly 'undefined'.

'moduleFile' is possibly 'undefined'.

'config.extras' is possibly 'undefined'.

'config.sys' is possibly 'undefined'.

'config.logger' is possibly 'undefined'.

'hmr' is possibly 'undefined'.

'config.outputTargets' is possibly 'undefined'.

'c.moduleFiles' is possibly 'undefined'.

'a.name' is possibly 'undefined'.

'b.name' is possibly 'undefined'.

'orgNodeResolveId' is possibly 'undefined'.

'config.rollupPlugins' is possibly 'undefined'.

'config.rollupConfig.inputOptions' is possibly 'undefined'.

'compilerCtx.worker' is possibly 'undefined'.

'lastModified' is possibly 'undefined'.

'config.devServer.historyApiFallback' is possibly 'undefined'.

'inputConfig.flags' is possibly 'undefined'.

'userConfig.flags' is possibly 'undefined'.

'outputTarget.serviceWorker' is possibly 'undefined'.

'cmp' is possibly 'undefined'.

'deps' is possibly 'undefined'.

'cmp.directDependents' is possibly 'undefined'.

'cmp.dependents' is possibly 'undefined'.

'config.bundles' is possibly 'undefined'.

'c.dependencies' is possibly 'undefined'.

'c.directDependencies' is possibly 'undefined'.

'outputTargets' is possibly 'undefined'.

'opts' is possibly 'undefined'.

'errorLine.text' is possibly 'undefined'.

'errorLine.errorLength' is possibly 'undefined'.

'opts.format' is possibly 'undefined'.

'config.sys.generateContentHash' is possibly 'undefined'.

'config.sys.copy' is possibly 'undefined'.

'entryModule' is possibly 'undefined'.

'a.directDependents' is possibly 'undefined'.

'b.directDependents' is possibly 'undefined'.

'a.directDependencies' is possibly 'undefined'.

'b.directDependencies' is possibly 'undefined'.

'a.dependents' is possibly 'undefined'.

'b.dependents' is possibly 'undefined'.

'a.dependencies' is possibly 'undefined'.

'b.dependencies' is possibly 'undefined'.

'bundleOptions.loader' is possibly 'undefined'.

'config.maxConcurrentWorkers' is possibly 'undefined'.

'config.logger.createLineUpdater' is possibly 'undefined'.

'hydrateOpts.staticComponents' is possibly 'undefined'.

'sys.generateFileHash' is possibly 'undefined'.

'manager.config.logger' is possibly 'undefined'.

'manager.config.sys' is possibly 'undefined'.

'serviceWorker' is possibly 'undefined'.

'node.comment' is possibly 'undefined'.

'node.selectors' is possibly 'undefined'.

'node.values' is possibly 'undefined'.

'moduleId' is possibly 'undefined'.

'sys' is possibly 'undefined'.

'tsResults.diagnostics' is possibly 'undefined'.

'r.resolvedModule' is possibly 'undefined'.

'compilerSystem.watchDirectory' is possibly 'undefined'.

'compilerSystem.watchFile' is possibly 'undefined'.

'collectionManifest.bundles' is possibly 'undefined'.

'cstrMethod.body' is possibly 'undefined'.

'cmp.dependencies' is possibly 'undefined'.

'foundDep' is possibly 'undefined'.

'connectedCallback.body' is possibly 'undefined'.

'cmpNode.name' is possibly 'undefined'.

'symbol.declarations' is possibly 'undefined'.

'signature' is possibly 'undefined'.

'collection.moduleFiles' is possibly 'undefined'.

'tsSourceFiles' is possibly 'undefined'.

'importHomeModule' is possibly 'undefined'.

'results.data' is possibly 'undefined'.

'results.imports' is possibly 'undefined'.

'transformers.before' is possibly 'undefined'.

'transformers.afterDeclarations' is possibly 'undefined'.

'transformers.after' is possibly 'undefined'.

'msg.requestLog' is possibly 'undefined'.

'msg.error' is possibly 'undefined'.

'msg.buildResults' is possibly 'undefined'.

'a.priority' is possibly 'undefined'.

'b.priority' is possibly 'undefined'.

'devServerConfig.historyApiFallback' is possibly 'undefined'.

'devServerConfig.basePath' is possibly 'undefined'.

'req.pathname' is possibly 'undefined'.

'req.stats' is possibly 'undefined'.

'devServerConfig' is possibly 'undefined'.

'res.$content' is possibly 'undefined'.

'opts.maxHydrateCount' is possibly 'undefined'.

'ref' is possibly 'undefined'.

'opts.excludeComponents' is possibly 'undefined'.

'hostRef' is possibly 'undefined'.

'hostRef.$instanceValues$' is possibly 'undefined'.

'ref.$onInstancePromise$' is possibly 'undefined'.

'ref.$lazyInstance$' is possibly 'undefined'.

'opts.indentSpaces' is possibly 'undefined'.

'opts.approximateLineWidth' is possibly 'undefined'.

'plt.$orgLocNodes$' is possibly 'undefined'.

'hostRef.$lazyInstance$' is possibly 'undefined'.

'cmpMeta.$attrsToReflect$' is possibly 'undefined'.

'cmpMeta.$members$' is possibly 'undefined'.

'nodeRef' is possibly 'undefined'.

'screenshot.diff' is possibly 'undefined'.

'screenshotCache.items' is possibly 'undefined'.

'emulateConfig.viewport' is possibly 'undefined'.

'emulateConfig.viewport.deviceScaleFactor' is possibly 'undefined'.

'res.statusCode' is possibly 'undefined'.

'tsSysWatchDirectory' is possibly 'undefined'.

'tsSysWatchFile' is possibly 'undefined'.

'sys.events' is possibly 'undefined'.

't.retries' is possibly 'undefined'.

'testing.emulate' is possibly 'undefined'.

'parsedConfig.collectCoverageFrom' is possibly 'undefined'.

'compare.deviceScaleFactor' is possibly 'undefined'.

'config' is possibly 'undefined'.

'screenshotEmulate.viewport' is possibly 'undefined'.

'd.absFilePath' is possibly 'undefined'.

'd.code' is possibly 'undefined'.
TS18047 97
Error messages 'configFileData' is possibly 'null'.

'canonicalLinkElm.parentNode' is possibly 'null'.

'link.parentNode' is possibly 'null'.

'href' is possibly 'null'.

'stencilScriptElm.parentNode' is possibly 'null'.

'attr' is possibly 'null'.

't.cmp' is possibly 'null'.

't.event' is possibly 'null'.

'progressBar.parentNode' is possibly 'null'.

'serverProcess.stdout' is possibly 'null'.

'serverProcess.stderr' is possibly 'null'.

'node.nodeName' is possibly 'null'.

'element.nodeName' is possibly 'null'.

'nodeValue' is possibly 'null'.

'cloned' is possibly 'null'.

'clonedDiv' is possibly 'null'.

'clonedTemplate' is possibly 'null'.

'clonedTemplate.content.firstChild' is possibly 'null'.

'clonedTemplate.content.firstChild.textContent' is possibly 'null'.

'clonedWin' is possibly 'null'.

'titleElm' is possibly 'null'.

'dstWin' is possibly 'null'.

'orgLocationNode.parentNode' is possibly 'null'.

'node.nodeValue' is possibly 'null'.

'node.parentNode' is possibly 'null'.

'appendAfter.parentNode' is possibly 'null'.

'hostElm.firstElementChild' is possibly 'null'.

'hostElm.lastElementChild' is possibly 'null'.

'nodeRef.nodeValue' is possibly 'null'.

'nodeRef.parentNode' is possibly 'null'.

'parentNode' is possibly 'null'.

'defaultHolder.parentNode' is possibly 'null'.

'nodeToRelocate.parentNode' is possibly 'null'.

'elm.textContent' is possibly 'null'.

'rsp' is possibly 'null'.

'head' is possibly 'null'.
TS2722 39
Error messages Cannot invoke an object which is possibly 'undefined'.
TS2532 38
Error messages Object is possibly 'undefined'.
TS2531 25
Error messages Object is possibly 'null'.
TS2454 16
Error messages Variable 'pkgJsonData' is used before being assigned.

Variable 'minifyOpts' is used before being assigned.

Variable 'workerCtrl' is used before being assigned.

Variable 'timespan' is used before being assigned.

Variable 'compilerExe' is used before being assigned.

Variable 'declarationOutputText' is used before being assigned.

Variable 'outputText' is used before being assigned.

Variable 'win' is used before being assigned.

Variable 'hostId' is used before being assigned.

Variable 'textContent' is used before being assigned.

Variable 'resolve' is used before being assigned.

Variable 'opts' is used before being assigned.
TS2352 13
Error messages Conversion of type 'null' to type 'CompilerSystem' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first.

Conversion of type 'null' to type 'string' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first.

Conversion of type '{ cmps: never[]; }' to type 'Module' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first.
Type '{ cmps: never[]; }' is missing the following properties from type 'Module': coreRuntimeApis, outputTargetCoreRuntimeApis, collectionName, dtsFilePath, and 28 more.

Conversion of type 'null' to type 'ScreenshotCache' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first.
TS2769 10
Error messages No overload matches this call.
Overload 1 of 2, '(type: keyof DocumentEventMap, listener: (this: Document, ev: PointerEvent | MouseEvent | UIEvent | Event | ErrorEvent | ... 13 more ... | WheelEvent) => any, options?: boolean | ... 1 more ... | undefined): void', gave the following error.
Argument of type '"e"' is not assignable to parameter of type 'keyof DocumentEventMap'.
Overload 2 of 2, '(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions | undefined): void', gave the following error.
Argument of type 'null' is not assignable to parameter of type 'EventListenerOrEventListenerObject'.

No overload matches this call.
Overload 1 of 2, '(o: {}): string[]', gave the following error.
Argument of type 'BuildResultsComponentGraph | undefined' is not assignable to parameter of type '{}'.
Type 'undefined' is not assignable to type '{}'.
Overload 2 of 2, '(o: object): string[]', gave the following error.
Argument of type 'BuildResultsComponentGraph | undefined' is not assignable to parameter of type 'object'.
Type 'undefined' is not assignable to type 'object'.

No overload matches this call.
Overload 1 of 4, '(object: {}, method: never): SpyInstance<never, never>', gave the following error.
Argument of type 'CompilerWorkerContext | undefined' is not assignable to parameter of type '{}'.
Type 'undefined' is not assignable to type '{}'.
Overload 2 of 4, '(object: {}, method: never): SpyInstance<never, never>', gave the following error.
Argument of type 'CompilerWorkerContext | undefined' is not assignable to parameter of type '{}'.
Type 'undefined' is not assignable to type '{}'.

No overload matches this call.
The last overload gave the following error.
Argument of type 'string | null' is not assignable to parameter of type '(substring: string, ...args: any[]) => string'.
Type 'null' is not assignable to type '(substring: string, ...args: any[]) => string'.

No overload matches this call.
Overload 1 of 2, '(configFileName: string, optionsToExtend: CompilerOptions | undefined, system: System, createProgram?: CreateProgram | undefined, reportDiagnostic?: DiagnosticReporter | undefined, reportWatchStatus?: WatchStatusReporter | undefined, watchOptionsToExtend?: WatchOptions | undefined, extraFileExtensions?: readonly FileExtensionInfo[] | undefined): WatchCompilerHostOfConfigFile<...>', gave the following error.
Argument of type 'string | undefined' is not assignable to parameter of type 'string'.
Type 'undefined' is not assignable to type 'string'.
Overload 2 of 2, '(rootFiles: string[], options: CompilerOptions, system: System, createProgram?: CreateProgram | undefined, reportDiagnostic?: DiagnosticReporter | undefined, reportWatchStatus?: WatchStatusReporter | undefined, projectReferences?: readonly ProjectReference[] | undefined, watchOptions?: WatchOptions | undefined): WatchCompilerHostOfFilesAndCompilerOptions<...>', gave the following error.
Argument of type 'string | undefined' is not assignable to parameter of type 'string[]'.
Type 'undefined' is not assignable to type 'string[]'.

No overload matches this call.
Overload 1 of 2, '(timeoutId: string | number | Timeout | undefined): void', gave the following error.
Argument of type 'Timeout | null' is not assignable to parameter of type 'string | number | Timeout | undefined'.
Type 'null' is not assignable to type 'string | number | Timeout | undefined'.
Overload 2 of 2, '(id: number | undefined): void', gave the following error.
Argument of type 'Timeout | null' is not assignable to parameter of type 'number | undefined'.
Type 'null' is not assignable to type 'number | undefined'.

No overload matches this call.
Overload 1 of 2, '(timeoutId: string | number | Timeout | undefined): void', gave the following error.
Argument of type 'Timeout | null' is not assignable to parameter of type 'string | number | Timeout | undefined'.
Overload 2 of 2, '(id: number | undefined): void', gave the following error.
Argument of type 'Timeout | null' is not assignable to parameter of type 'number | undefined'.

No overload matches this call.
Overload 1 of 3, '(p: string, encoding: "utf8"): Promise', gave the following error.
Argument of type 'string | undefined' is not assignable to parameter of type 'string'.
Type 'undefined' is not assignable to type 'string'.
Overload 2 of 3, '(p: string, encoding: "binary"): Promise', gave the following error.
Argument of type 'string | undefined' is not assignable to parameter of type 'string'.
Type 'undefined' is not assignable to type 'string'.
TS2790 10
Error messages The operand of a 'delete' operator must be optional.
TS2538 8
Error messages Type 'undefined' cannot be used as an index type.

Type 'null' cannot be used as an index type.
TS2344 5
Error messages Type 'T' does not satisfy the constraint 'Answers'.
TS2416 5
Error messages Property 'get' in type 'Cache' is not assignable to the same property in base type 'Cache'.
Type '(key: string) => Promise<string | null>' is not assignable to type '(key: string) => Promise'.
Type 'Promise<string | null>' is not assignable to type 'Promise'.
Type 'string | null' is not assignable to type 'string'.
Type 'null' is not assignable to type 'string'.

Property 'getMemoryStats' in type 'Cache' is not assignable to the same property in base type 'Cache'.
Type '() => string | null' is not assignable to type '() => string'.
Type 'string | null' is not assignable to type 'string'.
Type 'null' is not assignable to type 'string'.

Property 'find' in type 'E2EElement' is not assignable to the same property in base type 'E2EElementInternal'.
Type '(selector: string) => Promise<E2EElement | null>' is not assignable to type '(selector: FindSelector) => Promise'.
Type 'Promise<E2EElement | null>' is not assignable to type 'Promise'.
Type 'E2EElement | null' is not assignable to type 'E2EElement'.
Type 'null' is not assignable to type 'E2EElement'.

Property 'findAll' in type 'E2EElement' is not assignable to the same property in base type 'E2EElementInternal'.
Type '(selector: string) => Promise<E2EElement[]>' is not assignable to type '(selector: FindSelector) => Promise<E2EElement[]>'.
Type 'Promise<import("/home/runner/wo

@alicewriteswrongs alicewriteswrongs force-pushed the ap/docs-json branch 3 times, most recently from ce538dd to 054b330 Compare March 30, 2023 20:49
Copy link
Contributor Author

@alicewriteswrongs alicewriteswrongs left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just noting a few things

@@ -477,10 +501,12 @@ const getTypeReferenceLocation = (typeName: string, tsNode: ts.Node): d.Componen
}) as ts.ImportDeclaration;

if (importTypeDeclaration) {
const id = addToLibrary(type, typeName, checker);
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this function getTypeReferenceLocation ends up being called when were finding the referenced types for events, methods, and props, so it's a natural place to ensure that any type which is referenced gets added to the type library

const localImportPath = (<ts.StringLiteral>importTypeDeclaration.moduleSpecifier).text;
return {
location: 'import',
path: localImportPath,
id,
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We return the referenced type's id here so that it will be possible later on to cross-reference from a type reference to the canonical reference for that type in the docs-json output

* record of all the types referenced by components which are 'seen' during a
* Stencil build
*/
const TYPE_LIBRARY: d.JsonDocsTypeLibrary = {};
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this object stores information about any referenced type which we encounter during the compilation process - in particular, in transform-utils there are calls make to the addToLibrary function when we locate the types referenced in the annotations for various Stencil component features (events, props, etc).

I decided to make this a module-level variable because I think in any case we'll want this to be something that we populate during a build as a build-global value and this is fairly easy pattern that gives us that. This symbol isn't exported though, instead you can get a reference to it with the getLibrary function - the idea there is that if at some later point we change the implementation it could still remain hidden behind that abstraction.

* @param checker a {@link ts.TypeChecker} instance
* @returns the unique ID for the type in question
*/
export function addToLibrary(type: ts.Type, typeName: string, checker: ts.TypeChecker): string {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this function attempts to avoid doing work if we don't need to, so, for instance, it checks if something is from an external library and, if so, it bails before doing any of the work to get the type declaration or the docstring.

it also checks if we've already stored information about the type, and if so it will likewise skip doing any work.

/**
* TODO: Document
*/
export type JsonDocsTypeLibrary = Record<string, ComponentCompilerReferencedType>;
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Open to other names for the type here, I sort of went with what I thought was the most obvious candidate

Copy link
Contributor Author

@alicewriteswrongs alicewriteswrongs left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

one note

Comment on lines 67 to 85
const program = ts.createProgram([filePath], {});
const checker = program.getTypeChecker();
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we need to stand these up here because we want this function to be callable at any point in the whole build process, not just when we're executing the initial TS compilation.

This is needed because at the point in the build where we're dealing with the docs-json output target and need to decide whether we have to call this function or not we don't have a ts.Program and ts.TypeChecker hanging around

@alicewriteswrongs alicewriteswrongs force-pushed the ap/docs-json branch 8 times, most recently from ad0e4f9 to b4f8aa0 Compare April 14, 2023 14:03
Copy link
Contributor Author

@alicewriteswrongs alicewriteswrongs left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just noting a few more things

"bundlers": "cd ./bundler && npm run start",
"build.browser-compile": "cd ./browser-compile && npm run build",
"build.end-to-end": "cd ./end-to-end && npm ci && npm run build",
"build.hello-world": "cd ./hello-world && npm run build",
"build.hello-vdom": "cd ./hello-vdom && npm run build",
"build.ionic": "cd ./ionic-app && npm ci && npm run build",
"build.todo": "cd ./todo-app && npm ci && npm run build"
"build.todo": "cd ./todo-app && npm ci && npm run build",
"build.docs-json": "cd ./docs-json && npm ci && npm run build"
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added this here so that the docs-json project will be built during CI. This will test whether there was any change in the built output (specifically test/docs-json/docs.json) reflecting a regression in how Stencil pulls information into that file.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this or build in this package.json ever get called by CI? I didn't think we ever called build for this package.json in CI

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

isn't it run by the analysis workflow?

run: npm run test.analysis

the test.analysis will run build-and-analyze in test/ which calls all these build steps

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, my bad. Sorry about the confusion!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I modeled this on the other files in test/*

@alicewriteswrongs alicewriteswrongs force-pushed the ap/docs-json branch 2 times, most recently from 434bbb6 to 367d759 Compare April 19, 2023 18:31
@alicewriteswrongs alicewriteswrongs force-pushed the ap/docs-json branch 3 times, most recently from 69a28e0 to dcec8ce Compare May 15, 2023 14:44
@alicewriteswrongs alicewriteswrongs force-pushed the ap/docs-json branch 3 times, most recently from affe1a7 to 7072ad7 Compare June 6, 2023 19:35
@alicewriteswrongs alicewriteswrongs marked this pull request as ready for review June 6, 2023 20:08
@alicewriteswrongs alicewriteswrongs requested a review from a team as a code owner June 6, 2023 20:08
@alicewriteswrongs alicewriteswrongs force-pushed the ap/docs-json branch 2 times, most recently from dba42eb to db9a58e Compare June 7, 2023 15:45
@alicewriteswrongs
Copy link
Contributor Author

@rwaskiewicz ok I think all of your comments should now be addressed!

Copy link
Contributor

@rwaskiewicz rwaskiewicz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mostly questions on my end, looking pretty good!

const sourceFile = program.getSourceFile(filePath);

if (!sourceFile) {
config.logger.warn(`Could not gather type information from "${filePath}"!`);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think there are a few ways we could improve the UX of this error message. If someone were to run into this error message today, they'd see something like:
Screenshot 2023-06-22 at 10 07 25 AM

I think it might be helpful to:

  1. Contextualize where this error occurred (e.g. "we couldn't gather type information from supplementalPublicTypes in docs-json")*
  1. Give the user some suggestions as to how we might be able to fix it

What do you think about something like:

Suggested change
config.logger.warn(`Could not gather type information from "${filePath}"!`);
config.logger.warn(`docs-json: unable to gather type information from "${filePath}". Please double check this path exists relative to your project root.`);

* ATM, I'm making a big(?) assumption this transformer will only run for docs-json, maybe that's not a safe assumption to make though 🤔

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah the addFileToLibrary function will only be called if there is a docs-json OT set on the config, so we don't need to worry about this error message being hit otherwise.

I'll expand the error message - what I have there now is something of a placeholder that I neglected to expand / improve

src/compiler/docs/generate-doc-data.ts Show resolved Hide resolved
@@ -221,7 +221,7 @@ export const createInMemoryFs = (sys: d.CompilerSystem) => {
const emptyDirs = async (dirs: string[]): Promise<void> => {
dirs = dirs
.filter(isString)
.map(normalizePath)
.map((s) => normalizePath(s))
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Double checking, is this change needed? Doesn't what we have before do the same thing?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

EDIT: NVM - I found the change later in the review to normalizePath, and GH didn't delete it (or that's my story at least 😏 )

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah I wish this could stay as a unary function here, but I think the issue here is that .map will pass more than one argument and the type of the second argument won't match the second argument of normalizePath anymore, so arrow function it is

src/compiler/transformers/type-library.ts Outdated Show resolved Hide resolved
"bundlers": "cd ./bundler && npm run start",
"build.browser-compile": "cd ./browser-compile && npm run build",
"build.end-to-end": "cd ./end-to-end && npm ci && npm run build",
"build.hello-world": "cd ./hello-world && npm run build",
"build.hello-vdom": "cd ./hello-vdom && npm run build",
"build.ionic": "cd ./ionic-app && npm ci && npm run build",
"build.todo": "cd ./todo-app && npm ci && npm run build"
"build.todo": "cd ./todo-app && npm ci && npm run build",
"build.docs-json": "cd ./docs-json && npm ci && npm run build"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, my bad. Sorry about the confusion!

src/compiler/transformers/type-library.ts Outdated Show resolved Hide resolved
Comment on lines +513 to +514
const namedImportBindings = importTypeDeclaration?.importClause?.namedBindings;
if (importTypeDeclaration && ts.isNamedImports(namedImportBindings)) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For my own edification, why do we need to expand this conditional?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's just a typing hack, basically the namedBindings prop could have a few different types so the ts.isNamedImports is to narrow it so that .elements will be typed correctly

@alicewriteswrongs
Copy link
Contributor Author

@rwaskiewicz ok comments addressed!

@rwaskiewicz
Copy link
Contributor

@alicewriteswrongs I think the unit tests & format are failing - can you PTAL?

This enriches the type information supplied in the `docs-json` output
target in order to make it easier to deliver a rich documentation
experience for a Stencil project.

This involves three significant changes.

Firstly, the information which the `docs-json` OT gathers about the
properties which comprise the API of a Stencil component is expanded to
include more information about the types used in the declaration of the
property. In particular, this means that if you have, say, a `@Method`
on a component whose signature involves several types imported from
other modules the JSON blob for that method will now include more
detailed information about all the types used in that declaration.

This information is stored under the `complexType` key for each field on
a component. This `complexType` object includes a `references` object
which now includes a new, globally-unique ID for each type in a Stencil
project which looks like:

```ts
const typeID = `${pathToTypeHomeModule}::${typeName}`;
```

where `pathToTypeHomeModule` is the path to the type's "home" module,
i.e. where it was originally declared, and `typeName` is the _original_
name it is declared under in that module. This if you had a type like
the following:

```ts src/shared-interfaces.ts
export interface SharedInterface {
  property: "value";
}
```

the `SharedInterface` type would have the following ID:

```ts
"src/shared-interfaces.ts::SharedInterface"
```

This unique identifier allows cross-references to be made between the
_usage sites_ of a type (as documented in the JSON blob for, say, a
`@Method` or `@Prop`) and canonical information about that type.

The second major addition is the creation of a new canonical reference
point for all exported types used within a Stencil project. This
reference is called the _type library_ and it is included in the
`docs-json` output target under the `"typeLibrary"` key. It's an object
which maps the unique type IDs described above to an object containing
information about those types, including their original declaration
rendered as a string, the path to their home module, and documentation,
if present

> Note that global types, types imported from `node_modules`, and
  types marked as private with the `@private` JSDoc tag are not included
  in the type library, even if they are used in the declaration of a
  property decorated with a Stencil decorator.

The combination of globally-unique type IDs and the type library will
allow Stencil component authors to create richer documentation
experiences where the usage sites of a widely imported type can easily
be linked to a canonical reference point for that type.

The third addition is a new configuration option for the `docs-json`
output target called `supplementalPublicTypes`. This option takes a
filepath which points to a file exporting types and interfaces which
should be included in the type library regardless of whether they are
used in the API of any component included in the Stencil project.

The motivation for `supplementalPublicTypes` is to facilitate the
documentation of types and interfaces which are important for a given
project but which may not be included in the type library because
they're not used by a `@Prop()`, `@Event()`, or another Stencil
decorator.
@alicewriteswrongs alicewriteswrongs enabled auto-merge (squash) June 23, 2023 17:57
@alicewriteswrongs alicewriteswrongs merged commit c74e654 into stencil/v4-dev Jun 23, 2023
@alicewriteswrongs alicewriteswrongs deleted the ap/docs-json branch June 23, 2023 18:10
rwaskiewicz pushed a commit that referenced this pull request Jun 26, 2023
This enriches the type information supplied in the `docs-json` output
target in order to make it easier to deliver a rich documentation
experience for a Stencil project.

This involves three significant changes.

Firstly, the information which the `docs-json` OT gathers about the
properties which comprise the API of a Stencil component is expanded to
include more information about the types used in the declaration of the
property. In particular, this means that if you have, say, a `@Method`
on a component whose signature involves several types imported from
other modules the JSON blob for that method will now include more
detailed information about all the types used in that declaration.

This information is stored under the `complexType` key for each field on
a component. This `complexType` object includes a `references` object
which now includes a new, globally-unique ID for each type in a Stencil
project which looks like:

```ts
const typeID = `${pathToTypeHomeModule}::${typeName}`;
```

where `pathToTypeHomeModule` is the path to the type's "home" module,
i.e. where it was originally declared, and `typeName` is the _original_
name it is declared under in that module. This if you had a type like
the following:

```ts src/shared-interfaces.ts
export interface SharedInterface {
  property: "value";
}
```

the `SharedInterface` type would have the following ID:

```ts
"src/shared-interfaces.ts::SharedInterface"
```

This unique identifier allows cross-references to be made between the
_usage sites_ of a type (as documented in the JSON blob for, say, a
`@Method` or `@Prop`) and canonical information about that type.

The second major addition is the creation of a new canonical reference
point for all exported types used within a Stencil project. This
reference is called the _type library_ and it is included in the
`docs-json` output target under the `"typeLibrary"` key. It's an object
which maps the unique type IDs described above to an object containing
information about those types, including their original declaration
rendered as a string, the path to their home module, and documentation,
if present

> Note that global types, types imported from `node_modules`, and
  types marked as private with the `@private` JSDoc tag are not included
  in the type library, even if they are used in the declaration of a
  property decorated with a Stencil decorator.

The combination of globally-unique type IDs and the type library will
allow Stencil component authors to create richer documentation
experiences where the usage sites of a widely imported type can easily
be linked to a canonical reference point for that type.

The third addition is a new configuration option for the `docs-json`
output target called `supplementalPublicTypes`. This option takes a
filepath which points to a file exporting types and interfaces which
should be included in the type library regardless of whether they are
used in the API of any component included in the Stencil project.

The motivation for `supplementalPublicTypes` is to facilitate the
documentation of types and interfaces which are important for a given
project but which may not be included in the type library because
they're not used by a `@Prop()`, `@Event()`, or another Stencil
decorator.
rwaskiewicz pushed a commit that referenced this pull request Jun 26, 2023
This enriches the type information supplied in the `docs-json` output
target in order to make it easier to deliver a rich documentation
experience for a Stencil project.

This involves three significant changes.

Firstly, the information which the `docs-json` OT gathers about the
properties which comprise the API of a Stencil component is expanded to
include more information about the types used in the declaration of the
property. In particular, this means that if you have, say, a `@Method`
on a component whose signature involves several types imported from
other modules the JSON blob for that method will now include more
detailed information about all the types used in that declaration.

This information is stored under the `complexType` key for each field on
a component. This `complexType` object includes a `references` object
which now includes a new, globally-unique ID for each type in a Stencil
project which looks like:

```ts
const typeID = `${pathToTypeHomeModule}::${typeName}`;
```

where `pathToTypeHomeModule` is the path to the type's "home" module,
i.e. where it was originally declared, and `typeName` is the _original_
name it is declared under in that module. This if you had a type like
the following:

```ts src/shared-interfaces.ts
export interface SharedInterface {
  property: "value";
}
```

the `SharedInterface` type would have the following ID:

```ts
"src/shared-interfaces.ts::SharedInterface"
```

This unique identifier allows cross-references to be made between the
_usage sites_ of a type (as documented in the JSON blob for, say, a
`@Method` or `@Prop`) and canonical information about that type.

The second major addition is the creation of a new canonical reference
point for all exported types used within a Stencil project. This
reference is called the _type library_ and it is included in the
`docs-json` output target under the `"typeLibrary"` key. It's an object
which maps the unique type IDs described above to an object containing
information about those types, including their original declaration
rendered as a string, the path to their home module, and documentation,
if present

> Note that global types, types imported from `node_modules`, and
  types marked as private with the `@private` JSDoc tag are not included
  in the type library, even if they are used in the declaration of a
  property decorated with a Stencil decorator.

The combination of globally-unique type IDs and the type library will
allow Stencil component authors to create richer documentation
experiences where the usage sites of a widely imported type can easily
be linked to a canonical reference point for that type.

The third addition is a new configuration option for the `docs-json`
output target called `supplementalPublicTypes`. This option takes a
filepath which points to a file exporting types and interfaces which
should be included in the type library regardless of whether they are
used in the API of any component included in the Stencil project.

The motivation for `supplementalPublicTypes` is to facilitate the
documentation of types and interfaces which are important for a given
project but which may not be included in the type library because
they're not used by a `@Prop()`, `@Event()`, or another Stencil
decorator.
alicewriteswrongs added a commit that referenced this pull request Jul 25, 2023
This fixes an issue that crops up when building documentation using the
`docs-json` output target.

When #4212 was merged it included a change to
`src/declarations/stencil-public-docs.ts` which involved adding imports
from private Stencil type declarations. Previously this file had no
imports and so was "standalone", however, after this change it now
imported some types from `"./private"`.

This created a problem when using the `docs-json` output target because
when building a Stencil project with that output target enabled the
compiled typedef corresponding to `stencil-public-docs.ts` is copied out
of `node_modules` and into the users project. See here:

https://github.com/ionic-team/stencil/blob/43cfc584c8fbcb77122cbf2a813b1a0303085dce/src/compiler/docs/json/index.ts#L16-L18

This commit fixes the issue by using `dts-bundle-generator` to inline
the types imported by `stencil-public-docs.ts` so that the resulting
`.d.ts` file has no external dependencies and is therefore portable.
alicewriteswrongs added a commit that referenced this pull request Jul 25, 2023
This fixes an issue that crops up when building documentation using the
`docs-json` output target.

When #4212 was merged it included a change to
`src/declarations/stencil-public-docs.ts` which involved adding imports
from private Stencil type declarations. Previously this file had no
imports and so was "standalone", however, after this change it now
imported some types from `"./private"`.

This created a problem when using the `docs-json` output target because
when building a Stencil project with that output target enabled the
compiled typedef corresponding to `stencil-public-docs.ts` is copied out
of `node_modules` and into the users project. See here:

https://github.com/ionic-team/stencil/blob/43cfc584c8fbcb77122cbf2a813b1a0303085dce/src/compiler/docs/json/index.ts#L16-L18

This commit fixes the issue by using `dts-bundle-generator` to inline
the types imported by `stencil-public-docs.ts` so that the resulting
`.d.ts` file has no external dependencies and is therefore portable.
alicewriteswrongs added a commit that referenced this pull request Jul 25, 2023
This fixes an issue that crops up when building documentation using the
`docs-json` output target.

When #4212 was merged it included a change to
`src/declarations/stencil-public-docs.ts` which involved adding imports
from private Stencil type declarations. Previously this file had no
imports and so was "standalone", however, after this change it now
imported some types from `"./private"`.

This created a problem when using the `docs-json` output target because
when building a Stencil project with that output target enabled the
compiled typedef corresponding to `stencil-public-docs.ts` is copied out
of `node_modules` and into the users project. See here:

https://github.com/ionic-team/stencil/blob/43cfc584c8fbcb77122cbf2a813b1a0303085dce/src/compiler/docs/json/index.ts#L16-L18

This commit fixes the issue by using `dts-bundle-generator` to inline
the types imported by `stencil-public-docs.ts` so that the resulting
`.d.ts` file has no external dependencies and is therefore portable.
alicewriteswrongs added a commit that referenced this pull request Jul 26, 2023
This fixes an issue that crops up when building documentation using the
`docs-json` output target.

When #4212 was merged it included a change to
`src/declarations/stencil-public-docs.ts` which involved adding imports
from private Stencil type declarations. Previously this file had no
imports and so was "standalone", however, after this change it now
imported some types from `"./private"`.

This created a problem when using the `docs-json` output target because
when building a Stencil project with that output target enabled the
compiled typedef corresponding to `stencil-public-docs.ts` is copied out
of `node_modules` and into the users project. See here:

https://github.com/ionic-team/stencil/blob/43cfc584c8fbcb77122cbf2a813b1a0303085dce/src/compiler/docs/json/index.ts#L16-L18

This commit fixes the issue by using `dts-bundle-generator` to inline
the types imported by `stencil-public-docs.ts` so that the resulting
`.d.ts` file has no external dependencies and is therefore portable.
alicewriteswrongs added a commit that referenced this pull request Jul 26, 2023
This fixes an issue that crops up when building documentation using the
`docs-json` output target.

When #4212 was merged it included a change to
`src/declarations/stencil-public-docs.ts` which involved adding imports
from private Stencil type declarations. Previously this file had no
imports and so was "standalone", however, after this change it now
imported some types from `"./private"`.

This created a problem when using the `docs-json` output target because
when building a Stencil project with that output target enabled the
compiled typedef corresponding to `stencil-public-docs.ts` is copied out
of `node_modules` and into the users project. See here:

https://github.com/ionic-team/stencil/blob/43cfc584c8fbcb77122cbf2a813b1a0303085dce/src/compiler/docs/json/index.ts#L16-L18

This commit fixes the issue by using `dts-bundle-generator` to inline
the types imported by `stencil-public-docs.ts` so that the resulting
`.d.ts` file has no external dependencies and is therefore portable.
alicewriteswrongs added a commit that referenced this pull request Jul 27, 2023
This fixes an issue that crops up when building documentation using the
`docs-json` output target.

When #4212 was merged it included a change to
`src/declarations/stencil-public-docs.ts` which involved adding imports
from private Stencil type declarations. Previously this file had no
imports and so was "standalone", however, after this change it now
imported some types from `"./private"`.

This created a problem when using the `docs-json` output target because
when building a Stencil project with that output target enabled the
compiled typedef corresponding to `stencil-public-docs.ts` is copied out
of `node_modules` and into the users project. See here:

https://github.com/ionic-team/stencil/blob/43cfc584c8fbcb77122cbf2a813b1a0303085dce/src/compiler/docs/json/index.ts#L16-L18

This commit fixes the issue by using `dts-bundle-generator` to inline
the types imported by `stencil-public-docs.ts` so that the resulting
`.d.ts` file has no external dependencies and is therefore portable.
github-merge-queue bot pushed a commit that referenced this pull request Jul 27, 2023
#4619)

This fixes an issue that crops up when building documentation using the
`docs-json` output target.

When #4212 was merged it included a change to
`src/declarations/stencil-public-docs.ts` which involved adding imports
from private Stencil type declarations. Previously this file had no
imports and so was "standalone", however, after this change it now
imported some types from `"./private"`.

This created a problem when using the `docs-json` output target because
when building a Stencil project with that output target enabled the
compiled typedef corresponding to `stencil-public-docs.ts` is copied out
of `node_modules` and into the users project. See here:

https://github.com/ionic-team/stencil/blob/43cfc584c8fbcb77122cbf2a813b1a0303085dce/src/compiler/docs/json/index.ts#L16-L18

This commit fixes the issue by using `dts-bundle-generator` to inline
the types imported by `stencil-public-docs.ts` so that the resulting
`.d.ts` file has no external dependencies and is therefore portable.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants