feat(jsx): add jsx generator

package.json

@@ -15,7 +15,8 @@
     "test:watch": "node --test --watch",
     "prepare": "husky",
     "run": "node bin/cli.mjs",
-    "watch": "node --watch bin/cli.mjs"
+    "watch": "node --watch bin/cli.mjs",
+    "postinstall": "git-deps install"
   },
   "main": "./src/index.mjs",
   "bin": {
@@ -28,6 +29,7 @@
     "eslint": "^9.23.0",
     "eslint-config-prettier": "^10.1.1",
     "eslint-plugin-jsdoc": "^50.6.9",
+    "git-deps": "^1.0.0",
     "globals": "^16.0.0",
     "husky": "^9.1.7",
     "lint-staged": "^15.5.0",
@@ -41,12 +43,16 @@
     "acorn": "^8.14.1",
     "commander": "^13.1.0",
     "dedent": "^1.5.3",
+    "estree-util-value-to-estree": "^3.4.0",
     "estree-util-visit": "^2.0.0",
     "github-slugger": "^2.0.0",
     "glob": "^11.0.1",
     "hast-util-to-string": "^3.0.1",
     "hastscript": "^9.0.1",
     "html-minifier-terser": "^7.2.0",
+    "reading-time": "^1.5.0",
+    "recma-jsx": "^1.0.0",
+    "rehype-recma": "^1.0.0",
     "rehype-stringify": "^10.0.1",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
@@ -63,5 +69,8 @@
     "unist-util-visit": "^5.0.0",
     "vfile": "^6.0.3",
     "yaml": "^2.7.1"
+  },
+  "gitDependencies": {
+    "@node-core/rehype-shiki": "https://github.com/nodejs/nodejs.org#path:/packages/rehype-shiki"
   }
 }

src/constants.mjs

@@ -9,3 +9,14 @@ export const DOC_NODE_CHANGELOG_URL =
 
 // The base URL for the Node.js website
 export const BASE_URL = 'https://nodejs.org/';
+
+// This is the Node.js Base URL for viewing a file within GitHub UI
+export const DOC_NODE_BLOB_BASE_URL =
+  'https://github.com/nodejs/node/blob/HEAD/';
+
+// This is the Node.js API docs base URL for editing a file on GitHub UI
+export const DOC_API_BLOB_EDIT_BASE_URL =
+  'https://github.com/nodejs/node/edit/main/doc/api/';
+
+// Base URL for a specific Node.js version within the Node.js API docs
+export const DOC_API_BASE_URL_VERSION = 'https://nodejs.org/docs/latest-v';

src/generators/index.mjs

@@ -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/jsx/constants.mjs

@@ -0,0 +1,32 @@
+// Maps Node.js API stability indices (0-3) to UI component stability levels.
+export const STABILITY_LEVELS = [
+  'danger', // (0) Deprecated
+  'warning', // (1) Experimental
+  'success', // (2) Stable
+  'info', // (3) Legacy
+];
+
+// Maps HTML tags to corresponding component names in @node-core/ui-components.
+export const TAG_TRANSFORMS = {
+  pre: 'CodeBox',
+  blockquote: 'Blockquote',
+};
+
+// Maps API heading types to their CircularIcon props.
+export const ICON_SYMBOL_MAP = {
+  event: { symbol: 'E', color: 'red' },
+  method: { symbol: 'M', color: 'red' },
+  property: { symbol: 'P', color: 'red' },
+  class: { symbol: 'C', color: 'red' },
+  module: { symbol: 'M', color: 'red' },
+  classMethod: { symbol: 'S', color: 'red' },
+  ctor: { symbol: 'C', color: 'red' },
+};
+
+// Maps API lifecycle change type identifiers to their human-readable labels.
+export const CHANGE_TYPES = {
+  added_in: 'Added in',
+  deprecated_in: 'Deprecated in',
+  removed_in: 'Removed in',
+  introduced_in: 'Introduced in',
+};

src/generators/jsx/index.mjs

@@ -0,0 +1,68 @@
+import {
+  getCompatibleVersions,
+  groupNodesByModule,
+} from '../../utils/generators.mjs';
+import buildContent from './utils/buildContent.mjs';
+import { getRemarkRecma } from '../../utils/remark.mjs';
+import { buildSideBarDocPages } from './utils/buildBarProps.mjs';
+
+/**
+ * This generator generates a 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
+   * @param {Partial<GeneratorOptions>} options
+   * @returns {Promise<string[]>} Array of generated content
+   */
+  async generate(entries, { releases, version }) {
+    const remarkRecma = getRemarkRecma();
+    const groupedModules = groupNodesByModule(entries);
+
+    // Get sorted primary heading nodes
+    const headNodes = entries
+      .filter(node => node.heading.depth === 1)
+      .sort((a, b) => a.heading.data.name.localeCompare(b.heading.data.name));
+
+    // Generate table of contents
+    const docPages = buildSideBarDocPages(groupedModules, headNodes);
+
+    // Process each head node and build content
+    const results = await Promise.all(
+      headNodes.map(entry => {
+        const versions = getCompatibleVersions(
+          entry.introduced_in,
+          releases,
+          true
+        );
+
+        const sideBarProps = {
+          versions: versions.map(({ version }) => `v${version.version}`),
+          currentVersion: `v${version.version}`,
+          currentPage: `${entry.api}.html`,
+          docPages,
+        };
+
+        return buildContent(
+          groupedModules.get(entry.api),
+          entry,
+          sideBarProps,
+          remarkRecma
+        );
+      })
+    );
+
+    return results;
+  },
+};

src/generators/jsx/utils/ast.mjs

@@ -0,0 +1,71 @@
+'use strict';
+
+import { u as createTree } from 'unist-builder';
+import { valueToEstree } from 'estree-util-value-to-estree';
+
+/**
+ * Creates an MDX JSX element with support for complex attribute values.
+ *
+ * @param {string} name - The name of the JSX element
+ * @param {{
+ * inline?: boolean,
+ * children?: string | import('unist').Node[],
+ * [key: string]: any
+ * }} [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 } = {}
+) => {
+  // Process children: convert string to text node or use array as is
+  const processedChildren =
+    typeof children === 'string'
+      ? [createTree('text', { value: children })]
+      : (children ?? []);
+
+  // Create attribute nodes, handling complex objects and primitive values differently
+  const attrs = Object.entries(attributes).map(([key, value]) =>
+    createAttributeNode(key, value)
+  );
+
+  // Create and return the appropriate JSX element type
+  return createTree(inline ? 'mdxJsxTextElement' : 'mdxJsxFlowElement', {
+    name,
+    attributes: attrs,
+    children: processedChildren,
+  });
+};
+
+/**
+ * Creates an MDX JSX attribute node from the input.
+ *
+ * @param {string} name - The attribute name
+ * @param {any} value - The attribute value (can be any valid JS value)
+ * @returns {import('unist').Node} The MDX JSX attribute node
+ */
+function createAttributeNode(name, value) {
+  // For objects and arrays, create expression nodes to preserve structure
+  if (value !== null && typeof value === 'object') {
+    return createTree('mdxJsxAttribute', {
+      name,
+      value: createTree('mdxJsxAttributeValueExpression', {
+        data: {
+          estree: {
+            type: 'Program',
+            body: [
+              {
+                type: 'ExpressionStatement',
+                expression: valueToEstree(value),
+              },
+            ],
+            sourceType: 'module',
+          },
+        },
+      }),
+    });
+  }
+
+  // For primitives, use simple string conversion
+  return createTree('mdxJsxAttribute', { name, value: String(value) });
+}

src/generators/jsx/utils/buildBarProps.mjs

@@ -0,0 +1,53 @@
+import readingTime from 'reading-time';
+import { DOC_API_BLOB_EDIT_BASE_URL } from '../../../constants.mjs';
+import { visit } from 'unist-util-visit';
+
+/**
+ * Builds sidebar navigation for API documentation pages
+ *
+ * @param {Map<string, Array<ApiDocMetadataEntry>>} groupedModules - Modules grouped by API
+ * @param {Array<ApiDocMetadataEntry>} headNodes - Main entry nodes for each API
+ */
+export const buildSideBarDocPages = (groupedModules, headNodes) =>
+  headNodes.map(node => {
+    const moduleEntries = groupedModules.get(node.api);
+
+    return {
+      title: node.heading.data.name,
+      doc: `${node.api}.html`,
+      headings: moduleEntries
+        .filter(entry => entry.heading?.data?.name && entry.heading.depth === 2)
+        .map(entry => [entry.heading.data.name, `#${entry.heading.data.slug}`]),
+    };
+  });
+
+/**
+ * Builds metadata for the sidebar and meta bar
+ *
+ * @param {ApiDocMetadataEntry} head - Main API metadata entry
+ * @param {Array<ApiDocMetadataEntry>} entries - All API metadata entries
+ */
+export const buildMetaBarProps = (head, entries) => {
+  // Extract text content for reading time calculation
+  let textContent = '';
+  entries.forEach(entry => {
+    visit(entry.content, ['text', 'code'], node => {
+      textContent += node.value || '';
+    });
+  });
+
+  const headings = entries
+    .filter(entry => entry.heading?.data?.name)
+    .map(entry => ({
+      depth: entry.heading.depth,
+      value: entry.heading.data.name,
+    }));
+
+  return {
+    headings,
+    addedIn: head.introduced_in || head.added_in || '',
+    readingTime: readingTime(textContent).text,
+    viewAs: [['JSON', `${head.api}.json`]],
+    editThisPage: `${DOC_API_BLOB_EDIT_BASE_URL}${head.api}.md`,
+  };
+};