From 6ba3249cab485f09ab6e16d4eb63076d40a564a0 Mon Sep 17 00:00:00 2001
From: Alice <alice.writes.wrongs@gmail.com>
Date: Thu, 27 Jul 2023 09:44:15 -0500
Subject: [PATCH] fix(docs-json): use dts-bundle-generator to bundle types for
 docs-json (#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.
---
 scripts/bundles/internal.ts     |  13 +-
 scripts/utils/bundle-dts.ts     |  30 +-
 src/compiler/docs/json/index.ts |   9 +-
 test/docs-json/docs.d.ts        | 562 ++++++++++++++++++--------------
 4 files changed, 362 insertions(+), 252 deletions(-)

diff --git a/scripts/bundles/internal.ts b/scripts/bundles/internal.ts
index 561754ee01b..fbf7decc4a5 100644
--- a/scripts/bundles/internal.ts
+++ b/scripts/bundles/internal.ts
@@ -1,7 +1,7 @@
 import fs from 'fs-extra';
 import { join } from 'path';
 
-import { cleanDts } from '../utils/bundle-dts';
+import { bundleDts, cleanDts } from '../utils/bundle-dts';
 import type { BuildOptions } from '../utils/options';
 import { writePkgJson } from '../utils/write-pkg-json';
 import { internalAppData } from './internal-app-data';
@@ -70,7 +70,16 @@ async function copyStencilInternalDts(opts: BuildOptions, outputInternalDir: str
   // @stencil/core/internal/stencil-public-docs.d.ts
   const docsDtsSrcPath = join(declarationsInputDir, 'stencil-public-docs.d.ts');
   const docsDtsDestPath = join(outputInternalDir, 'stencil-public-docs.d.ts');
-  const docsDts = cleanDts(await fs.readFile(docsDtsSrcPath, 'utf8'));
+  // We bundle with `dts-bundle-generator` here to ensure that when the `docs-json`
+  // OT writes a `docs.d.ts` file based on this file it is fully portable.
+  const docsDts = await bundleDts(opts, docsDtsSrcPath, {
+    // we want to suppress the `dts-bundle-generator` banner here because we do
+    // our own later on
+    noBanner: true,
+    // we also don't want the types which are inlined into our bundled file to
+    // be re-exported, which will change the 'surface' of the module
+    exportReferencedTypes: false,
+  });
   await fs.writeFile(docsDtsDestPath, docsDts);
 
   // @stencil/core/internal/stencil-public-runtime.d.ts
diff --git a/scripts/utils/bundle-dts.ts b/scripts/utils/bundle-dts.ts
index 9e7f5236126..9bd7af5b6c8 100644
--- a/scripts/utils/bundle-dts.ts
+++ b/scripts/utils/bundle-dts.ts
@@ -1,9 +1,21 @@
-import { generateDtsBundle } from 'dts-bundle-generator/dist/bundle-generator.js';
+import { EntryPointConfig, generateDtsBundle, OutputOptions } from 'dts-bundle-generator/dist/bundle-generator.js';
 import fs from 'fs-extra';
 
 import { BuildOptions } from './options';
 
-export async function bundleDts(opts: BuildOptions, inputFile: string) {
+/**
+ * A thin wrapper for `dts-bundle-generator` which uses our build options to
+ * set a few things up
+ *
+ * **Note**: this file caches its output to disk, and will return any
+ * previously cached file if not in a prod environment!
+ *
+ * @param opts an object holding information about the current build of Stencil
+ * @param inputFile the path to the file which should be bundled
+ * @param outputOptions options for bundling the file
+ * @returns a string containing the bundled typedef
+ */
+export async function bundleDts(opts: BuildOptions, inputFile: string, outputOptions?: OutputOptions): Promise<string> {
   const cachedDtsOutput = inputFile + '-bundled.d.ts';
 
   if (!opts.isProd) {
@@ -12,15 +24,15 @@ export async function bundleDts(opts: BuildOptions, inputFile: string) {
     } catch (e) {}
   }
 
-  const entries = [
-    {
-      filePath: inputFile,
-    },
-  ];
+  const config: EntryPointConfig = {
+    filePath: inputFile,
+  };
 
-  let outputCode = generateDtsBundle(entries).join('\n');
+  if (outputOptions) {
+    config.output = outputOptions;
+  }
 
-  outputCode = cleanDts(outputCode);
+  const outputCode = cleanDts(generateDtsBundle([config]).join('\n'));
 
   await fs.writeFile(cachedDtsOutput, outputCode);
 
diff --git a/src/compiler/docs/json/index.ts b/src/compiler/docs/json/index.ts
index 5e34261b664..e8005c34f96 100644
--- a/src/compiler/docs/json/index.ts
+++ b/src/compiler/docs/json/index.ts
@@ -14,7 +14,14 @@ export const generateJsonDocs = async (
     return;
   }
   const docsDtsPath = join(config.sys.getCompilerExecutingPath(), '..', '..', 'internal', 'stencil-public-docs.d.ts');
-  const docsDts = await compilerCtx.fs.readFile(docsDtsPath);
+  let docsDts = await compilerCtx.fs.readFile(docsDtsPath);
+  // this file was written by dts-bundle-generator, which uses tabs for
+  // indentation. Instead, let's replace those with spaces!
+  docsDts = docsDts
+    .split('\n')
+    .map((line) => line.replace(/\t/g, '    '))
+    .join('\n');
+
   const typesContent = `
 /**
  * This is an autogenerated file created by the Stencil compiler.
diff --git a/test/docs-json/docs.d.ts b/test/docs-json/docs.d.ts
index 42a02815a42..3f36802faee 100644
--- a/test/docs-json/docs.d.ts
+++ b/test/docs-json/docs.d.ts
@@ -3,7 +3,87 @@
  * This is an autogenerated file created by the Stencil compiler.
  * DO NOT MODIFY IT MANUALLY
  */
-import { ComponentCompilerEventComplexType, ComponentCompilerMethodComplexType, ComponentCompilerPropertyComplexType, ComponentCompilerReferencedType } from './stencil-private';
+interface ComponentCompilerPropertyComplexType {
+  /**
+   * The string of the original type annotation in the Stencil source code
+   */
+  original: string;
+  /**
+   * A 'resolved' type, where e.g. imported types have been resolved and inlined
+   *
+   * For instance, an annotation like `(foo: Foo) => string;` will be
+   * converted to `(foo: { foo: string }) => string;`.
+   */
+  resolved: string;
+  /**
+   * A record of the types which were referenced in the assorted type
+   * annotation in the original source file.
+   */
+  references: ComponentCompilerTypeReferences;
+}
+type ComponentCompilerTypeReferences = Record<string, ComponentCompilerTypeReference>;
+interface ComponentCompilerTypeReference {
+  /**
+   * A type may be defined:
+   * - locally (in the same file as the component that uses it)
+   * - globally
+   * - by importing it into a file (and is defined elsewhere)
+   */
+  location: "local" | "global" | "import";
+  /**
+   * The path to the type reference, if applicable (global types should not need a path associated with them)
+   */
+  path?: string;
+  /**
+   * An ID for this type which is unique within a Stencil project.
+   */
+  id: string;
+}
+interface ComponentCompilerReferencedType {
+  /**
+   * The path to the module where the type is declared.
+   */
+  path: string;
+  /**
+   * The string of the original type annotation in the Stencil source code
+   */
+  declaration: string;
+  /**
+   * An extracted docstring
+   */
+  docstring: string;
+}
+interface ComponentCompilerEventComplexType {
+  original: string;
+  resolved: string;
+  references: ComponentCompilerTypeReferences;
+}
+interface ComponentCompilerMethodComplexType {
+  signature: string;
+  parameters: CompilerJsDoc[];
+  references: ComponentCompilerTypeReferences;
+  return: string;
+}
+interface CompilerJsDoc {
+  /**
+   * The text associated with the JSDoc
+   */
+  text: string;
+  /**
+   * Tags included in the JSDoc
+   */
+  tags: CompilerJsDocTagInfo[];
+}
+interface CompilerJsDocTagInfo {
+  /**
+   * The name of the tag - e.g. `@deprecated`
+   */
+  name: string;
+  /**
+   * Additional text that is associated with the tag - e.g. `@deprecated use v2 of this API`
+   */
+  text?: string;
+}
 /**
  * The Type Library holds information about the types which are used in a
  * Stencil project. During compilation, Stencil gathers information about the
@@ -20,158 +100,158 @@ export type JsonDocsTypeLibrary = Record<string, ComponentCompilerReferencedType
  * A container for JSDoc metadata for a project
  */
 export interface JsonDocs {
+  /**
+   * The metadata for the JSDocs for each component in a Stencil project
+   */
+  components: JsonDocsComponent[];
+  /**
+   * The timestamp at which the metadata was generated, in the format YYYY-MM-DDThh:mm:ss
+   */
+  timestamp: string;
+  compiler: {
+    /**
+     * The name of the compiler that generated the metadata
+     */
+    name: string;
     /**
-     * The metadata for the JSDocs for each component in a Stencil project
+     * The version of the Stencil compiler that generated the metadata
      */
-    components: JsonDocsComponent[];
+    version: string;
     /**
-     * The timestamp at which the metadata was generated, in the format YYYY-MM-DDThh:mm:ss
+     * The version of TypeScript that was used to generate the metadata
      */
-    timestamp: string;
-    compiler: {
-        /**
-         * The name of the compiler that generated the metadata
-         */
-        name: string;
-        /**
-         * The version of the Stencil compiler that generated the metadata
-         */
-        version: string;
-        /**
-         * The version of TypeScript that was used to generate the metadata
-         */
-        typescriptVersion: string;
-    };
-    typeLibrary: JsonDocsTypeLibrary;
+    typescriptVersion: string;
+  };
+  typeLibrary: JsonDocsTypeLibrary;
 }
 /**
  * Container for JSDoc metadata for a single Stencil component
  */
 export interface JsonDocsComponent {
-    /**
-     * The directory containing the Stencil component, minus the file name.
-     *
-     * @example /workspaces/stencil-project/src/components/my-component
-     */
-    dirPath?: string;
-    /**
-     * The name of the file containing the Stencil component, with no path
-     *
-     * @example my-component.tsx
-     */
-    fileName?: string;
-    /**
-     * The full path of the file containing the Stencil component
-     *
-     * @example /workspaces/stencil-project/src/components/my-component/my-component.tsx
-     */
-    filePath?: string;
-    /**
-     * The path to the component's `readme.md` file, including the filename
-     *
-     * @example /workspaces/stencil-project/src/components/my-component/readme.md
-     */
-    readmePath?: string;
-    /**
-     * The path to the component's `usage` directory
-     *
-     * @example /workspaces/stencil-project/src/components/my-component/usage/
-     */
-    usagesDir?: string;
-    /**
-     * The encapsulation strategy for a component
-     */
-    encapsulation: 'shadow' | 'scoped' | 'none';
-    /**
-     * The tag name for the component, for use in HTML
-     */
-    tag: string;
-    /**
-     * The contents of a component's `readme.md` that are user generated.
-     *
-     * Auto-generated contents are not stored in this reference.
-     */
-    readme: string;
-    /**
-     * The description of a Stencil component, found in the JSDoc that sits above the component's declaration
-     */
-    docs: string;
-    /**
-     * JSDoc tags found in the JSDoc comment written atop a component's declaration
-     */
-    docsTags: JsonDocsTag[];
-    /**
-     * The text from the class-level JSDoc for a Stencil component, if present.
-     */
-    overview?: string;
-    /**
-     * A mapping of usage example file names to their contents for the component.
-     */
-    usage: JsonDocsUsage;
-    /**
-     * Array of metadata for a component's `@Prop`s
-     */
-    props: JsonDocsProp[];
-    /**
-     * Array of metadata for a component's `@Method`s
-     */
-    methods: JsonDocsMethod[];
-    /**
-     * Array of metadata for a component's `@Event`s
-     */
-    events: JsonDocsEvent[];
-    /**
-     * Array of metadata for a component's `@Listen` handlers
-     */
-    listeners: JsonDocsListener[];
-    /**
-     * Array of metadata for a component's CSS styling information
-     */
-    styles: JsonDocsStyle[];
-    /**
-     * Array of component Slot information, generated from `@slot` tags
-     */
-    slots: JsonDocsSlot[];
-    /**
-     * Array of component Parts information, generate from `@part` tags
-     */
-    parts: JsonDocsPart[];
-    /**
-     * Array of metadata describing where the current component is used
-     */
-    dependents: string[];
-    /**
-     * Array of metadata listing the components which are used in current component
-     */
-    dependencies: string[];
-    /**
-     * Describes a tree of components coupling
-     */
-    dependencyGraph: JsonDocsDependencyGraph;
-    /**
-     * A deprecation reason/description found following a `@deprecated` tag
-     */
-    deprecation?: string;
+  /**
+   * The directory containing the Stencil component, minus the file name.
+   *
+   * @example /workspaces/stencil-project/src/components/my-component
+   */
+  dirPath?: string;
+  /**
+   * The name of the file containing the Stencil component, with no path
+   *
+   * @example my-component.tsx
+   */
+  fileName?: string;
+  /**
+   * The full path of the file containing the Stencil component
+   *
+   * @example /workspaces/stencil-project/src/components/my-component/my-component.tsx
+   */
+  filePath?: string;
+  /**
+   * The path to the component's `readme.md` file, including the filename
+   *
+   * @example /workspaces/stencil-project/src/components/my-component/readme.md
+   */
+  readmePath?: string;
+  /**
+   * The path to the component's `usage` directory
+   *
+   * @example /workspaces/stencil-project/src/components/my-component/usage/
+   */
+  usagesDir?: string;
+  /**
+   * The encapsulation strategy for a component
+   */
+  encapsulation: "shadow" | "scoped" | "none";
+  /**
+   * The tag name for the component, for use in HTML
+   */
+  tag: string;
+  /**
+   * The contents of a component's `readme.md` that are user generated.
+   *
+   * Auto-generated contents are not stored in this reference.
+   */
+  readme: string;
+  /**
+   * The description of a Stencil component, found in the JSDoc that sits above the component's declaration
+   */
+  docs: string;
+  /**
+   * JSDoc tags found in the JSDoc comment written atop a component's declaration
+   */
+  docsTags: JsonDocsTag[];
+  /**
+   * The text from the class-level JSDoc for a Stencil component, if present.
+   */
+  overview?: string;
+  /**
+   * A mapping of usage example file names to their contents for the component.
+   */
+  usage: JsonDocsUsage;
+  /**
+   * Array of metadata for a component's `@Prop`s
+   */
+  props: JsonDocsProp[];
+  /**
+   * Array of metadata for a component's `@Method`s
+   */
+  methods: JsonDocsMethod[];
+  /**
+   * Array of metadata for a component's `@Event`s
+   */
+  events: JsonDocsEvent[];
+  /**
+   * Array of metadata for a component's `@Listen` handlers
+   */
+  listeners: JsonDocsListener[];
+  /**
+   * Array of metadata for a component's CSS styling information
+   */
+  styles: JsonDocsStyle[];
+  /**
+   * Array of component Slot information, generated from `@slot` tags
+   */
+  slots: JsonDocsSlot[];
+  /**
+   * Array of component Parts information, generate from `@part` tags
+   */
+  parts: JsonDocsPart[];
+  /**
+   * Array of metadata describing where the current component is used
+   */
+  dependents: string[];
+  /**
+   * Array of metadata listing the components which are used in current component
+   */
+  dependencies: string[];
+  /**
+   * Describes a tree of components coupling
+   */
+  dependencyGraph: JsonDocsDependencyGraph;
+  /**
+   * A deprecation reason/description found following a `@deprecated` tag
+   */
+  deprecation?: string;
 }
 export interface JsonDocsDependencyGraph {
-    [tagName: string]: string[];
+  [tagName: string]: string[];
 }
 /**
  * A descriptor for a single JSDoc tag found in a block comment
  */
 export interface JsonDocsTag {
-    /**
-     * The tag name (immediately following the '@')
-     */
-    name: string;
-    /**
-     * The description that immediately follows the tag name
-     */
-    text?: string;
+  /**
+   * The tag name (immediately following the '@')
+   */
+  name: string;
+  /**
+   * The description that immediately follows the tag name
+   */
+  text?: string;
 }
 export interface JsonDocsValue {
-    value?: string;
-    type: string;
+  value?: string;
+  type: string;
 }
 /**
  * A mapping of file names to their contents.
@@ -194,109 +274,109 @@ export interface JsonDocsValue {
  * ```
  */
 export interface JsonDocsUsage {
-    [key: string]: string;
+  [key: string]: string;
 }
 /**
  * An intermediate representation of a `@Prop` decorated member's JSDoc
  */
 export interface JsonDocsProp {
-    /**
-     * the name of the prop
-     */
-    name: string;
-    complexType?: ComponentCompilerPropertyComplexType;
-    /**
-     * the type of the prop, in terms of the TypeScript type system (as opposed to JavaScript's or HTML's)
-     */
-    type: string;
-    /**
-     * `true` if the prop was configured as "mutable" where it was declared, `false` otherwise
-     */
-    mutable: boolean;
-    /**
-     * The name of the attribute that is exposed to configure a compiled web component
-     */
-    attr?: string;
-    /**
-     * `true` if the prop was configured to "reflect" back to HTML where it (the prop) was declared, `false` otherwise
-     */
-    reflectToAttr: boolean;
-    /**
-     * the JSDoc description text associated with the prop
-     */
-    docs: string;
-    /**
-     * JSDoc tags associated with the prop
-     */
-    docsTags: JsonDocsTag[];
-    /**
-     * The default value of the prop
-     */
-    default?: string;
-    /**
-     * Deprecation text associated with the prop. This is the text that immediately follows a `@deprecated` tag
-     */
-    deprecation?: string;
-    values: JsonDocsValue[];
-    /**
-     * `true` if a component is declared with a '?', `false` otherwise
-     *
-     * @example
-     * ```tsx
-     * @Prop() componentProps?: any;
-     * ```
-     */
-    optional: boolean;
-    /**
-     * `true` if a component is declared with a '!', `false` otherwise
-     *
-     * @example
-     * ```tsx
-     * @Prop() componentProps!: any;
-     * ```
-     */
-    required: boolean;
+  /**
+   * the name of the prop
+   */
+  name: string;
+  complexType?: ComponentCompilerPropertyComplexType;
+  /**
+   * the type of the prop, in terms of the TypeScript type system (as opposed to JavaScript's or HTML's)
+   */
+  type: string;
+  /**
+   * `true` if the prop was configured as "mutable" where it was declared, `false` otherwise
+   */
+  mutable: boolean;
+  /**
+   * The name of the attribute that is exposed to configure a compiled web component
+   */
+  attr?: string;
+  /**
+   * `true` if the prop was configured to "reflect" back to HTML where it (the prop) was declared, `false` otherwise
+   */
+  reflectToAttr: boolean;
+  /**
+   * the JSDoc description text associated with the prop
+   */
+  docs: string;
+  /**
+   * JSDoc tags associated with the prop
+   */
+  docsTags: JsonDocsTag[];
+  /**
+   * The default value of the prop
+   */
+  default?: string;
+  /**
+   * Deprecation text associated with the prop. This is the text that immediately follows a `@deprecated` tag
+   */
+  deprecation?: string;
+  values: JsonDocsValue[];
+  /**
+   * `true` if a component is declared with a '?', `false` otherwise
+   *
+   * @example
+   * ```tsx
+   * @Prop() componentProps?: any;
+   * ```
+   */
+  optional: boolean;
+  /**
+   * `true` if a component is declared with a '!', `false` otherwise
+   *
+   * @example
+   * ```tsx
+   * @Prop() componentProps!: any;
+   * ```
+   */
+  required: boolean;
 }
 export interface JsonDocsMethod {
-    name: string;
-    docs: string;
-    docsTags: JsonDocsTag[];
-    deprecation?: string;
-    signature: string;
-    returns: JsonDocsMethodReturn;
-    parameters: JsonDocMethodParameter[];
-    complexType: ComponentCompilerMethodComplexType;
+  name: string;
+  docs: string;
+  docsTags: JsonDocsTag[];
+  deprecation?: string;
+  signature: string;
+  returns: JsonDocsMethodReturn;
+  parameters: JsonDocMethodParameter[];
+  complexType: ComponentCompilerMethodComplexType;
 }
 export interface JsonDocsMethodReturn {
-    type: string;
-    docs: string;
+  type: string;
+  docs: string;
 }
 export interface JsonDocMethodParameter {
-    name: string;
-    type: string;
-    docs: string;
+  name: string;
+  type: string;
+  docs: string;
 }
 export interface JsonDocsEvent {
-    event: string;
-    bubbles: boolean;
-    cancelable: boolean;
-    composed: boolean;
-    complexType: ComponentCompilerEventComplexType;
-    docs: string;
-    docsTags: JsonDocsTag[];
-    deprecation?: string;
-    detail: string;
+  event: string;
+  bubbles: boolean;
+  cancelable: boolean;
+  composed: boolean;
+  complexType: ComponentCompilerEventComplexType;
+  docs: string;
+  docsTags: JsonDocsTag[];
+  deprecation?: string;
+  detail: string;
 }
 export interface JsonDocsStyle {
-    name: string;
-    docs: string;
-    annotation: string;
+  name: string;
+  docs: string;
+  annotation: string;
 }
 export interface JsonDocsListener {
-    event: string;
-    target?: string;
-    capture: boolean;
-    passive: boolean;
+  event: string;
+  target?: string;
+  capture: boolean;
+  passive: boolean;
 }
 /**
  * A descriptor for a slot
@@ -304,14 +384,14 @@ export interface JsonDocsListener {
  * Objects of this type are translated from the JSDoc tag, `@slot`
  */
 export interface JsonDocsSlot {
-    /**
-     * The name of the slot. Defaults to an empty string for an unnamed slot.
-     */
-    name: string;
-    /**
-     * A textual description of the slot.
-     */
-    docs: string;
+  /**
+   * The name of the slot. Defaults to an empty string for an unnamed slot.
+   */
+  name: string;
+  /**
+   * A textual description of the slot.
+   */
+  docs: string;
 }
 /**
  * A descriptor of a CSS Shadow Part
@@ -320,20 +400,22 @@ export interface JsonDocsSlot {
  * attribute on a component in TSX
  */
 export interface JsonDocsPart {
-    /**
-     * The name of the Shadow part
-     */
-    name: string;
-    /**
-     * A textual description of the Shadow part.
-     */
-    docs: string;
+  /**
+   * The name of the Shadow part
+   */
+  name: string;
+  /**
+   * A textual description of the Shadow part.
+   */
+  docs: string;
 }
 export interface StyleDoc {
-    name: string;
-    docs: string;
-    annotation: 'prop';
+  name: string;
+  docs: string;
+  annotation: "prop";
 }
 
+export {};
+
 declare const _default: JsonDocs;
 export default _default;