feat(docs): Add hot regeneration for CLI docs

packages/docusaurus/config/docusaurus/plugins/cli-docs.ts

@@ -1,50 +1,70 @@
 import type {Options as MDXLoaderOptions, MDXPlugin}          from '@docusaurus/mdx-loader';
 import type {LoadContext, Plugin, PluginContentLoadedActions} from '@docusaurus/types';
-import {getCli}                                               from '@yarnpkg/cli';
 import {YarnVersion, miscUtils}                               from '@yarnpkg/core';
+import {compileFile}                                          from '@yarnpkg/monorepo/scripts/setup-ts-cache';
 import type {BaseContext, Definition}                         from 'clipanion';
 import {Cli}                                                  from 'clipanion';
 import glob                                                   from 'fast-glob';
-import {createRequire}                                        from 'node:module';
+import jiti, {type JITIOptions}                               from 'jiti';
 import path                                                   from 'path';
 
 const PLUGIN_NAME = `docusaurus-plugin-yarn-cli-docs`;
 const ROUTE_PREFIX = `/cli`;
-
 function dedent(value: string) {
   return value.trim().split(`\n`).map(line => line.trimStart()).join(`\n`);
 }
 
+const transform: JITIOptions['transform'] = ({source, filename}) => {
+  const {code} = compileFile(source, filename!);
+  return {code};
+};
+const loader = jiti(__filename, {
+  cache: true,
+  requireCache: false,
+  transform,
+});
+
 const binaries = [
   {
     name: `@yarnpkg/cli`,
-    getCli,
+    getCli: async () => {
+      const {getCli} = loader(`@yarnpkg/cli`) as typeof import('@yarnpkg/cli');
+      return getCli();
+    },
+    watch: [`../plugin-*/sources/commands/**/*.{ts,tsx}`],
   },
   {
     name: `@yarnpkg/builder`,
     getCli: async () => {
-      const commands = Object.values(await import(`@yarnpkg/builder`));
+      const commands = Object.values(loader(`@yarnpkg/builder`) as typeof import('@yarnpkg/builder'));
       return Cli.from(commands, {binaryName: `yarn builder`});
     },
+    watch: [`../yarnpkg-builder/sources/commands/**/*.ts`],
   },
   {
     name: `@yarnpkg/pnpify`,
     getCli: async () => {
-      const proxyRequire = createRequire(require.resolve(`@yarnpkg/pnpify/package.json`));
-      const commandPaths = await glob([`./sources/commands/**/*.ts`], {cwd: path.dirname(proxyRequire.resolve(`./package.json`))});
+      const proxyLoader = jiti(require.resolve(`@yarnpkg/pnpify/package.json`), {
+        cache: true,
+        requireCache: false,
+        transform,
+      });
+      const commandPaths = await glob([`./sources/commands/**/*.ts`], {cwd: path.dirname(proxyLoader.resolve(`./package.json`))});
 
-      const commands = commandPaths.map(commandPath => proxyRequire(commandPath).default);
+      const commands = commandPaths.map(commandPath => proxyLoader(commandPath).default);
       return Cli.from(commands, {binaryName: `yarn pnpify`});
     },
+    watch: [`../yarnpkg-pnpify/sources/commands/**/*.ts`],
   },
   {
     name: `@yarnpkg/sdks`,
     getCli: async () => {
-      const {SdkCommand} = await import(`@yarnpkg/sdks`);
+      const {SdkCommand} = loader(`@yarnpkg/sdks`) as typeof import('@yarnpkg/sdks');
       return Cli.from(SdkCommand, {binaryName: `yarn sdks`});
     },
+    watch: [`../yarnpkg-sdks/sources/commands/**/*.ts`],
   },
-] satisfies Array<{ name: string, getCli: () => Promise<Cli<BaseContext>> }>;
+] satisfies Array<{ name: string, getCli: () => Promise<Cli<BaseContext>>, watch?: Array<string> }>;
 
 export type Options = {
   remarkPlugins: Array<MDXPlugin>;
@@ -363,6 +383,10 @@ const plugin = async function(context: LoadContext, options: Options): Promise<P
         },
       };
     },
+
+    getPathsToWatch() {
+      return binaries.flatMap(({watch}) => watch ?? []);
+    },
   };
 };
 

packages/docusaurus/package.json

@@ -101,6 +101,7 @@
     "esast-util-from-js": "^2.0.1",
     "esbuild-loader": "^2.20.0",
     "fast-glob": "^3.2.2",
+    "jiti": "^1.21.0",
     "mdast-util-mdx-jsx": "^3.0.0",
     "typedoc": "^0.25.7",
     "typescript": "5.4.1-rc",

scripts/setup-ts-cache.d.ts

@@ -0,0 +1,6 @@
+import type {TransformResult} from 'esbuild-wasm';
+
+declare function compileFile(sourceCode: string, filename: string): Pick<TransformResult, 'code' | 'map'>;
+declare const version: string;
+
+export {compileFile, version};

yarn.lock

@@ -5355,6 +5355,7 @@ __metadata:
     fast-glob: "npm:^3.2.2"
     git-url-parse: "npm:^13.1.0"
     github-markdown-css: "npm:^5.1.0"
+    jiti: "npm:^1.21.0"
     js-untar: "npm:^2.0.0"
     lodash: "npm:^4.17.15"
     markdown-it: "npm:^13.0.1"
@@ -12943,7 +12944,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"jiti@npm:^1.20.0":
+"jiti@npm:^1.20.0, jiti@npm:^1.21.0":
   version: 1.21.0
   resolution: "jiti@npm:1.21.0"
   bin: