Circumvent broken module resolution in v3 api-data d.ts file (#1119)

Author: AndrewJakubowicz

packages/lit-dev-api/api-data/lit-3/pages.json

@@ -6,7 +6,7 @@
       "v1": "api/lit-element/LitElement/"
     },
     "repo": "lit/lit",
-    "commit": "d04a3e30eb3ae3520fb0ac163fb5ddbbf6030620",
+    "commit": "12109c25997ef03180d7eefe05c64e0fb20dd2b0",
     "items": [
       {
         "name": "LitElement",
@@ -3116,7 +3116,7 @@
       "v1": "api/lit-element/UpdatingElement/"
     },
     "repo": "lit/lit",
-    "commit": "d04a3e30eb3ae3520fb0ac163fb5ddbbf6030620",
+    "commit": "12109c25997ef03180d7eefe05c64e0fb20dd2b0",
     "items": [
       {
         "name": "ReactiveElement",
@@ -6265,7 +6265,7 @@
       "v1": "api/lit-html/templates/"
     },
     "repo": "lit/lit",
-    "commit": "d04a3e30eb3ae3520fb0ac163fb5ddbbf6030620",
+    "commit": "12109c25997ef03180d7eefe05c64e0fb20dd2b0",
     "items": [
       {
         "name": "html",
@@ -6851,7 +6851,7 @@
       "v1": "api/lit-element/styles/"
     },
     "repo": "lit/lit",
-    "commit": "d04a3e30eb3ae3520fb0ac163fb5ddbbf6030620",
+    "commit": "12109c25997ef03180d7eefe05c64e0fb20dd2b0",
     "items": [
       {
         "name": "adoptStyles",
@@ -7463,7 +7463,7 @@
       "v1": "api/lit-element/decorators/"
     },
     "repo": "lit/lit",
-    "commit": "d04a3e30eb3ae3520fb0ac163fb5ddbbf6030620",
+    "commit": "12109c25997ef03180d7eefe05c64e0fb20dd2b0",
     "items": [
       {
         "name": "customElement",
@@ -8768,7 +8768,7 @@
       "v1": "api/lit-html/directives/"
     },
     "repo": "lit/lit",
-    "commit": "d04a3e30eb3ae3520fb0ac163fb5ddbbf6030620",
+    "commit": "12109c25997ef03180d7eefe05c64e0fb20dd2b0",
     "items": [
       {
         "name": "asyncAppend",
@@ -17744,7 +17744,7 @@
       "v1": "api/lit-html/custom-directives/"
     },
     "repo": "lit/lit",
-    "commit": "d04a3e30eb3ae3520fb0ac163fb5ddbbf6030620",
+    "commit": "12109c25997ef03180d7eefe05c64e0fb20dd2b0",
     "items": [
       {
         "name": "AsyncDirective",
@@ -22711,7 +22711,7 @@
       "v1": "api/lit-html/templates/"
     },
     "repo": "lit/lit",
-    "commit": "d04a3e30eb3ae3520fb0ac163fb5ddbbf6030620",
+    "commit": "12109c25997ef03180d7eefe05c64e0fb20dd2b0",
     "items": [
       {
         "name": "html",
@@ -23396,7 +23396,7 @@
       "v1": "api/lit-element/LitElement/"
     },
     "repo": "lit/lit",
-    "commit": "d04a3e30eb3ae3520fb0ac163fb5ddbbf6030620",
+    "commit": "12109c25997ef03180d7eefe05c64e0fb20dd2b0",
     "items": [
       {
         "name": "ReactiveController",
@@ -23851,7 +23851,7 @@
       "v1": "api/lit-element/LitElement/"
     },
     "repo": "lit/lit",
-    "commit": "d04a3e30eb3ae3520fb0ac163fb5ddbbf6030620",
+    "commit": "12109c25997ef03180d7eefe05c64e0fb20dd2b0",
     "items": [
       {
         "name": "defaultConverter",

packages/lit-dev-tools-cjs/src/api-docs/configs/lit-3.ts

@@ -42,6 +42,28 @@ export const lit3Config: ApiDocsConfig = {
     pathlib.join(srcDir, 'static-html.ts'),
   ],
 
+  extraSetupCommands: [
+    {
+      cmd: 'npm',
+      args: ['run', 'build:ts'],
+    },
+    // Apply file patch to fix typedoc errors during docs generation. Because
+    // `npm run build:ts` is run prior to this, the patch file can always be
+    // applied unless a change has occurred in the file being patched.
+    {
+      cmd: 'patch',
+      // directive-helpers contains an import of the private `ChildPart` class
+      // that typedoc cannot resolve. By stripping this import typedoc
+      // successfully generates API docs without changing the generated docs
+      // output.
+      args: [
+        'packages/lit-html/development/directive-helpers.d.ts',
+        '-i',
+        '../../../../../packages/lit-dev-tools-cjs/src/api-docs/lit-3-patches/fix-directive-helpers-declaration.patch',
+      ],
+    },
+  ],
+
   pages: [
     {
       slug: 'LitElement',

packages/lit-dev-tools-cjs/src/api-docs/generate.ts

@@ -11,17 +11,14 @@ import {execFile} from 'child_process';
 import {promisify} from 'util';
 import {ApiDocsTransformer} from './transformer.js';
 import {lit2Config} from './configs/lit-2.js';
-
-// TODO(https://github.com/lit/lit.dev/issues/1112) Fix automatic generation of
-// Lit 3.0 docs.
-// import {lit3Config} from './configs/lit-3.js';
+import {lit3Config} from './configs/lit-3.js';
 
 import type {ApiDocsConfig} from './types.js';
 
 const execFileAsync = promisify(execFile);
 
 // Only generate documentation for most recent Lit versions.
-const configs = [lit2Config /* , lit3Config */];
+const configs = [lit2Config, lit3Config];
 
 /**
  * Check whether the given file path exists.

packages/lit-dev-tools-cjs/src/api-docs/lit-3-patches/fix-directive-helpers-declaration.patch

@@ -0,0 +1,16 @@
+--- packages/lit-html/development/directive-helpers.d.ts	2023-05-15 17:13:11
++++ packages/lit-html/development/directive-helpers_new.d.ts	2023-05-16 13:31:18
+@@ -5,9 +5,9 @@
+  */
+ import { Part, DirectiveParent, TemplateResult } from './lit-html.js';
+ import { DirectiveResult, DirectiveClass, PartInfo } from './directive.js';
+-type Primitive = null | undefined | boolean | number | string | symbol | bigint;
+-declare const ChildPart: typeof import("./lit-html.js").ChildPart;
+-type ChildPart = InstanceType<typeof ChildPart>;
++type Primitive = null | undefined | boolean | number | string | symbol | bigint; 
++type ChildPart = import("./lit-html.js").ChildPart;
++ 
+ /**
+  * Tests if a value is a primitive value.
+  *
+\ No newline at end of file