feat(generator): add jsx generator

Author: avivkeller

.gitignore

@@ -4,3 +4,4 @@ npm-debug.log
 
 # Default Output Directory
 out
+dist

.prettierignore

@@ -1,3 +1,5 @@
 # Tests files
 src/generators/api-links/test/fixtures/
 *.snapshot
+
+dist

declarations.d.ts

@@ -0,0 +1,4 @@
+declare module "*.module.css" {
+  const classes: { [key: string]: string };
+  export default classes;
+}

eslint.config.mjs

@@ -4,6 +4,7 @@ import jsdoc from 'eslint-plugin-jsdoc';
 import globals from 'globals';
 
 export default [
+  { ignores: ['dist', 'out'] },
   // @see https://eslint.org/docs/latest/use/configure/configuration-files#specifying-files-and-ignores
   {
     files: ['src/**/*.mjs', 'bin/**/*.mjs'],

package-lock.json

@@ -47,6 +47,10 @@
     "hast-util-to-string": "^3.0.1",
     "hastscript": "^9.0.1",
     "html-minifier-terser": "^7.2.0",
+    "recma-build-jsx": "^1.0.0",
+    "recma-jsx": "^1.0.0",
+    "recma-stringify": "^1.0.0",
+    "rehype-recma": "^1.0.0",
     "rehype-stringify": "^10.0.1",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",

package.json

@@ -11,6 +11,7 @@ import apiLinks from './api-links/index.mjs';
 import oramaDb from './orama-db/index.mjs';
 import astJs from './ast-js/index.mjs';
 import llmsTxt from './llms-txt/index.mjs';
+import jsx from './jsx/index.mjs';
 
 export const publicGenerators = {
   'json-simple': jsonSimple,
@@ -23,6 +24,7 @@ export const publicGenerators = {
   'api-links': apiLinks,
   'orama-db': oramaDb,
   'llms-txt': llmsTxt,
+  jsx,
 };
 
 export const allGenerators = {

src/generators/index.mjs

@@ -0,0 +1,6 @@
+export const STABILITY_LEVELS = [
+  'danger', // Deprecated
+  'warning', // Experimental
+  'success', // Stable
+  'info', // Legacy
+];

src/generators/jsx/constants.mjs

@@ -0,0 +1,36 @@
+import { groupNodesByModule } from '../../utils/generators.mjs';
+import buildContent from './utils/buildContent.mjs';
+import { getRemarkRecma } from '../../utils/remark.mjs';
+
+/**
+ * This generator generates an JSX AST from an input MDAST
+ *
+ * @typedef {Array<ApiDocMetadataEntry>} Input
+ *
+ * @type {GeneratorMetadata<Input, string>}
+ */
+export default {
+  name: 'jsx',
+  version: '1.0.0',
+  description: 'Generates JSX from the input AST',
+  dependsOn: 'ast',
+
+  /**
+   * Generates a JSX AST
+   *
+   * @param {Input} entries
+   * @returns {Promise<string[]>} Array of generated content
+   */
+  async generate(entries) {
+    const remarkRecma = getRemarkRecma();
+
+    const results = await Promise.all(
+      Array.from(groupNodesByModule(entries).values()).map(entry =>
+        buildContent(entry, remarkRecma)
+      )
+    );
+
+    console.log(results);
+    return results;
+  },
+};

src/generators/jsx/index.mjs

@@ -0,0 +1,34 @@
+'use strict';
+
+import { u as createTree } from 'unist-builder';
+
+/**
+ * Creates an MDX JSX element.
+ *
+ * @param {string} name - The name of the JSX element
+ * @param {{
+ * inline?: boolean,
+ * children?: string | import('unist').Node[],
+ * [key: string]: string
+ * }} [options={}] - Options including type, children, and JSX attributes
+ * @returns {import('unist').Node} The created MDX JSX element node
+ */
+export const createJSXElement = (
+  name,
+  { inline = true, children = [], ...attributes } = {}
+) => {
+  const processedChildren =
+    typeof children === 'string'
+      ? [createTree('text', { value: children })]
+      : (children ?? []);
+
+  const attrs = Object.entries(attributes).map(([key, value]) =>
+    createTree('mdxJsxAttribute', { name: key, value: String(value) })
+  );
+
+  return createTree(inline ? 'mdxJsxTextElement' : 'mdxJsxFlowElement', {
+    name,
+    attributes: attrs,
+    children: processedChildren,
+  });
+};

src/generators/jsx/utils/ast.mjs

@@ -0,0 +1,73 @@
+'use strict';
+
+// External dependencies
+import { u as createTree } from 'unist-builder';
+import { SKIP, visit } from 'unist-util-visit';
+
+// Internal dependencies
+import createQueries from '../../../utils/queries/index.mjs';
+import { createJSXElement } from './ast.mjs';
+import { STABILITY_LEVELS } from '../constants.mjs';
+
+/**
+ * Transforms a stability node into an AlertBox JSX element
+ *
+ * @param {Object} node - The stability node to transform
+ * @param {number} index - The index of the node in its parent's children array
+ * @param {Object} parent - The parent node containing the stability node
+ * @returns {Array} - Returns [SKIP] to indicate this node should be skipped in further traversal
+ */
+function transformStabilityNode(node, index, parent) {
+  parent.children.splice(
+    index,
+    1,
+    createTree('paragraph', {
+      children: [
+        createJSXElement('AlertBox', {
+          children: node.data.description,
+          level: STABILITY_LEVELS[node.data.index],
+          title: node.data.index,
+        }),
+      ],
+    })
+  );
+  return [SKIP];
+}
+
+/**
+ * Processes content by transforming stability nodes
+ *
+ * @param {Object} content - The content object to process
+ * @returns {Object} - The processed content with stability nodes transformed
+ */
+function processContent(content) {
+  const contentCopy = { ...content };
+  visit(
+    contentCopy,
+    createQueries.UNIST.isStabilityNode,
+    transformStabilityNode
+  );
+  return contentCopy;
+}
+
+/**
+ * Transforms API metadata entries into processed MDX content
+ *
+ * @param {Array} metadataEntries - API documentation metadata entries
+ * @param {import('unified').Processor} remark - Remark processor instance for markdown processing
+ * @returns {React.ReactElement} - Evaluated React element from processed MDX, ready for rendering
+ */
+export default function transformMetadataToMdx(metadataEntries, remark) {
+  // Create and process the root node with all entries
+  const rootNode = createTree(
+    'root',
+    metadataEntries.map(entry => processContent(entry.content))
+  );
+
+  // Process with remark and convert to string
+  const processedNodes = remark.runSync(rootNode);
+  const mdxString = remark.stringify(processedNodes);
+
+  // Evaluate MDX and return React element
+  return mdxString;
+}

src/generators/jsx/utils/buildContent.mjs

@@ -209,7 +209,7 @@ export default (headNodes, metadataEntries, remark) => {
     // Parses the metadata pieces of each node and the content
     metadataEntries.map(entry => {
       // Deep clones the content nodes to avoid affecting upstream nodes
-      const content = JSON.parse(JSON.stringify(entry.content));
+      const content = structuredClone(entry.content);
 
       // Parses the Heading nodes into Heading elements
       visit(content, createQueries.UNIST.isHeading, buildHeading);

src/generators/legacy-html/utils/buildContent.mjs

@@ -44,12 +44,9 @@ export default class WorkerPool {
         this.changeActiveThreadCount(1);
 
         // Create and start the worker thread
-        const worker = new Worker(
-          new URL(import.meta.resolve('./worker.mjs')),
-          {
-            workerData: { name, dependencyOutput, extra },
-          }
-        );
+        const worker = new Worker(new URL('./worker.mjs', import.meta.url), {
+          workerData: { name, dependencyOutput, extra },
+        });
 
         // Handle worker thread messages (result or error)
         worker.on('message', result => {

src/threading/index.mjs

@@ -7,8 +7,13 @@ import remarkParse from 'remark-parse';
 import remarkRehype from 'remark-rehype';
 import remarkStringify from 'remark-stringify';
 
+import rehypeRecma from 'rehype-recma';
 import rehypeStringify from 'rehype-stringify';
 
+import recmaJsx from 'recma-jsx';
+import recmaBuildJsx from 'recma-build-jsx';
+import recmaStringify from 'recma-stringify';
+
 import syntaxHighlighter from './highlighter.mjs';
 
 /**
@@ -37,3 +42,32 @@ export const getRemarkRehype = () =>
     // We allow dangerous HTML to be passed through, since we have HTML within our Markdown
     // and we trust the sources of the Markdown files
     .use(rehypeStringify, { allowDangerousHtml: true });
+
+/**
+ * Retrieves an instance of Remark configured to output JSX code.
+ * including parsing Code Boxes with syntax highlighting
+ */
+export const getRemarkRecma = () =>
+  unified()
+    .use(remarkParse)
+    // TODO(@avivkeller): @node-core/mdx Remark plugins
+    // We make Rehype ignore existing HTML nodes, and JSX
+    // as these are nodes we manually created during the generation process
+    // We also allow dangerous HTML to be passed through, since we have HTML within our Markdown
+    // and we trust the sources of the Markdown files
+    .use(remarkRehype, {
+      allowDangerousHtml: true,
+      passThrough: [
+        'element',
+        'mdxFlowExpression',
+        'mdxJsxFlowElement',
+        'mdxJsxTextElement',
+        'mdxTextExpression',
+        'mdxjsEsm',
+      ],
+    })
+    // TODO(@avivkeller): @node-core/mdx Rehype plugins
+    .use(rehypeRecma)
+    .use(recmaJsx)
+    .use(recmaBuildJsx)
+    .use(recmaStringify);