fix: Changes for docs-gen v6 ESM compatibility

Author: nicolethoen

packages/documentation-framework/scripts/cli/build.js

@@ -76,7 +76,7 @@ async function execFile(file, args) {
 }
 
 async function build(cmd, options) {
-  generate(options);
+  await generate(options);
   const toBuild = cmd === 'all'
     ? ['server', 'client']
     : cmd;

packages/documentation-framework/scripts/cli/cli.js

@@ -9,9 +9,9 @@ program
 program
   .command('generate')
   .description('generates source files')
-  .action(options => {
+  .action(async options => {
     const { generate } = require('./generate');
-    generate(options);
+    await generate(options);
   });
 
 program

packages/documentation-framework/scripts/cli/generate.js

@@ -1,15 +1,16 @@
 const path = require('path');
-const { sourceMD, sourceProps, sourceFunctionDocs, writeIndex } = require('../md/parseMD');
+const { sourceMD, sourceProps, sourceFunctionDocs, writeIndex, waitForProps } = require('../md/parseMD');
 
 function getSource(options) {
   return require(path.join(process.cwd(), options.parent.source));
 }
 
-function generate(options) {
+async function generate(options) {
   const start = new Date();
   console.log('write source files to patternfly-docs/generated');
   const sourceMDWithOptions = (glob, source, ignore) => sourceMD(glob, source, ignore, options._name);
   getSource(options)(sourceMDWithOptions, sourceProps, sourceFunctionDocs);
+  await waitForProps();
   const exitCode = writeIndex();
   if (exitCode !== 0) {
     process.exit(exitCode);

packages/documentation-framework/scripts/cli/start.js

@@ -19,7 +19,7 @@ function startDevServer(webpackConfig) {
 }
 
 async function start(options) {
-  generate(options, true);
+  await generate(options, true);
   const webpackClientConfig = await clientConfig(null, { mode: 'development', ...getConfig(options) });
   console.log('start rspack-dev-server');
   watchMD();

packages/documentation-framework/scripts/md/parseMD.js

@@ -19,6 +19,7 @@ const outputBase = path.join(process.cwd(), `patternfly-docs/generated`);
 const tsDocs = {};
 let functionDocs = {};
 const routes = {};
+const pendingProps = [];
 const globs = {
   props: [],
   md: [],
@@ -267,8 +268,8 @@ function toReactComponent(mdFilePath, source, buildMode) {
   };
 }
 
-function sourcePropsFile(file) {
-  tsDocgen(file)
+async function sourcePropsFile(file) {
+  (await tsDocgen(file))
     .filter(({ hide }) => !hide)
     .forEach(({ name, description, props }) => {
       tsDocs[getTsDocName(name, getTsDocNameVariant(file))] = { name, description, props };
@@ -345,7 +346,11 @@ function getTsDocNameVariant(source) {
 module.exports = {
   sourceProps(glob, ignore) {
     globs.props.push({ glob, ignore });
-    globSync(glob, { ignore }).forEach(sourcePropsFile);
+    const promise = Promise.all(globSync(glob, { ignore }).map(sourcePropsFile));
+    pendingProps.push(promise);
+  },
+  async waitForProps() {
+    await Promise.all(pendingProps);
   },
   sourceMD(glob, source, ignore, buildMode) {
     globs.md.push({ glob, source, ignore });

packages/documentation-framework/scripts/tsDocgen.js

@@ -1,7 +1,15 @@
 const fs = require("fs");
-const reactDocgen = require("react-docgen");
 const ts = require("typescript");
 
+// react-docgen v6+ is ESM-only; lazy-load it asynchronously on first use
+let reactDocgenReady = null;
+function loadReactDocgen() {
+  if (!reactDocgenReady) {
+    reactDocgenReady = import("react-docgen");
+  }
+  return reactDocgenReady;
+}
+
 const annotations = [
   {
     regex: /@deprecated/,
@@ -41,7 +49,8 @@ function addAnnotations(prop) {
   return prop;
 }
 
-function getComponentMetadata(filename, sourceText) {
+async function getComponentMetadata(filename, sourceText) {
+  const reactDocgen = await loadReactDocgen();
   let parsedComponents = null;
   try {
     parsedComponents = reactDocgen.parse(sourceText, {
@@ -159,9 +168,9 @@ function normalizeProp([
   return res;
 }
 
-function tsDocgen(file) {
+async function tsDocgen(file) {
   const sourceText = fs.readFileSync(file, "utf8");
-  const componentMeta = getComponentMetadata(file, sourceText); // Array of components with props
+  const componentMeta = await getComponentMetadata(file, sourceText); // Array of components with props
   const interfaceMeta = getInterfaceMetadata(file, sourceText); // Array of interfaces with props
   const typeAliasMeta = getTypeAliasMetadata(file, sourceText); // Array of type aliases with props
   const propsMetaMap = [...interfaceMeta, ...typeAliasMeta].reduce(function (