code review

Author: avivkeller

src/generators/jsx/utils/ast.mjs

@@ -67,8 +67,5 @@ function createAttributeNode(name, value) {
   }
 
   // For primitives, use simple string conversion
-  return createTree('mdxJsxAttribute', {
-    name,
-    value: String(value),
-  });
+  return createTree('mdxJsxAttribute', { name, value: String(value) });
 }

src/generators/jsx/utils/buildBarProps.mjs

@@ -27,7 +27,7 @@ export const buildSideBarDocPages = (groupedModules, headNodes) =>
  * @param {ApiDocMetadataEntry} head - Main API metadata entry
  * @param {Array<ApiDocMetadataEntry>} entries - All API metadata entries
  */
-export function buildMetaBarProps(head, entries) {
+export const buildMetaBarProps = (head, entries) => {
   // Extract text content for reading time calculation
   let textContent = '';
   entries.forEach(entry => {
@@ -36,16 +36,18 @@ export function buildMetaBarProps(head, entries) {
     });
   });
 
+  const headings = entries
+    .filter(entry => entry.heading?.data?.name)
+    .map(entry => ({
+      depth: entry.heading.depth,
+      value: entry.heading.data.name,
+    }));
+
   return {
-    headings: entries
-      .filter(entry => entry.heading?.data?.name)
-      .map(entry => ({
-        depth: entry.heading.depth,
-        value: entry.heading.data.name,
-      })),
+    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`,
   };
-}
+};

src/generators/jsx/utils/buildContent.mjs

@@ -23,33 +23,34 @@ import { buildMetaBarProps } from './buildBarProps.mjs';
  * @param {import('unist').Parent} parent - The parent node containing the stability node
  * @returns {[typeof SKIP]} Visitor instruction to skip the node
  */
-function transformStabilityNode(node, index, parent) {
-  const { data } = node;
+const transformStabilityNode = ({ data }, index, parent) => {
   parent.children[index] = createJSXElement('AlertBox', {
     children: data.description,
     level: STABILITY_LEVELS[data.index],
     title: data.index,
   });
+
   return [SKIP];
-}
+};
 
 /**
  * Creates a history of changes for an API element
  *
  * @param {ApiDocMetadataEntry} entry - The metadata entry containing change information
  * @returns {import('unist').Node|null} JSX element representing change history or null if no changes
  */
-function createChangeElement(entry) {
+const createChangeElement = entry => {
   // Collect changes from version fields (added, deprecated, etc.)
   const changeEntries = Object.entries(CHANGE_TYPES)
+    // Do we have this field?
     .filter(([field]) => entry[field])
-    .map(([field, label]) => {
-      const versions = enforceArray(entry[field]);
-      return {
-        versions,
-        label: `${label}: ${versions.join(', ')}`,
-      };
-    });
+    // Get the versions as an array
+    .map(([field, label]) => [enforceArray(entry[field]), label])
+    // Create the change entry
+    .map(([versions, label]) => ({
+      versions,
+      label: `${label}: ${versions.join(', ')}`,
+    }));
 
   // Add explicit changes if they exist
   if (entry.changes?.length) {
@@ -61,22 +62,26 @@ function createChangeElement(entry) {
     changeEntries.push(...explicitChanges);
   }
 
-  if (!changeEntries.length) return null;
+  if (!changeEntries.length) {
+    return null;
+  }
 
   // Sort by version, newest first and create the JSX element
   return createJSXElement('ChangeHistory', {
     changes: sortChanges(changeEntries, 'versions'),
   });
-}
+};
 
 /**
  * Creates a source link element if a source link is available
  *
  * @param {string|undefined} sourceLink - The source link path
  * @returns {import('hastscript').Element|null} The source link element or null if no source link
  */
-function createSourceLink(sourceLink) {
-  if (!sourceLink) return null;
+const createSourceLink = sourceLink => {
+  if (!sourceLink) {
+    return null;
+  }
 
   return createElement('span', [
     'Source Code: ',
@@ -86,7 +91,7 @@ function createSourceLink(sourceLink) {
       sourceLink
     ),
   ]);
-}
+};
 
 /**
  * Enhances a heading node with metadata, source links, and styling
@@ -97,7 +102,7 @@ function createSourceLink(sourceLink) {
  * @param {import('unist').Parent} parent - The parent node containing the heading
  * @returns {[typeof SKIP]} Visitor instruction to skip the node
  */
-function transformHeadingNode(entry, node, index, parent) {
+const transformHeadingNode = (entry, node, index, parent) => {
   const { data, children } = node;
   const headerChildren = [
     createElement(`h${data.depth + 1}`, [
@@ -127,15 +132,15 @@ function transformHeadingNode(entry, node, index, parent) {
   }
 
   return [SKIP];
-}
+};
 
 /**
  * Processes an API documentation entry by applying transformations to its content
  *
  * @param {ApiDocMetadataEntry} entry - The API metadata entry to process
  * @returns {import('unist').Node} The processed content
  */
-function processEntry(entry) {
+const processEntry = entry => {
   // Create a copy to avoid modifying the original
   const content = structuredClone(entry.content);
 
@@ -146,7 +151,7 @@ function processEntry(entry) {
   );
 
   return content;
-}
+};
 
 /**
  * Creates the overall content structure with processed entries
@@ -156,7 +161,7 @@ function processEntry(entry) {
  * @param {Object} metaBarProps - Props for the meta bar component
  * @returns {import('unist').Node} The root node of the content tree
  */
-function createContentStructure(entries, sideBarProps, metaBarProps) {
+const createContentStructure = (entries, sideBarProps, metaBarProps) => {
   return createTree('root', [
     createJSXElement('NavBar'),
     createJSXElement('Article', {
@@ -170,7 +175,7 @@ function createContentStructure(entries, sideBarProps, metaBarProps) {
       ],
     }),
   ]);
-}
+};
 
 /**
  * Transforms API metadata entries into processed MDX content
@@ -181,12 +186,7 @@ function createContentStructure(entries, sideBarProps, metaBarProps) {
  * @param {import('unified').Processor} remark - Remark processor instance for markdown processing
  * @returns {string} The stringified MDX content
  */
-export default function buildContent(
-  metadataEntries,
-  head,
-  sideBarProps,
-  remark
-) {
+const buildContent = (metadataEntries, head, sideBarProps, remark) => {
   const metaBarProps = buildMetaBarProps(head, metadataEntries);
 
   const root = createContentStructure(
@@ -196,4 +196,6 @@ export default function buildContent(
   );
 
   return remark.runSync(root);
-}
+};
+
+export default buildContent;

src/generators/jsx/utils/transformer.mjs

@@ -8,14 +8,17 @@ import { TAG_TRANSFORMS } from '../constants.mjs';
  * @returns {Object} The transformed tree (modified in place)
  */
 export default () => tree => {
-  visit(tree, 'raw', node => {
-    node.type = 'text';
-  });
-
-  visit(tree, 'element', node => {
-    const replacement = TAG_TRANSFORMS[node.tagName];
-    if (replacement) {
-      node.tagName = replacement;
+  visit(tree, ['raw', 'element'], node => {
+    // TODO(@avivkeller): Our parsers shouldn't return raw nodes
+    // When they mistake "<Type>" for an HTML node, rather than
+    // the string type that it is.
+    if (node.type === 'raw') {
+      node.type = 'text';
+    } else {
+      const replacement = TAG_TRANSFORMS[node.tagName];
+      if (replacement) {
+        node.tagName = replacement;
+      }
     }
   });
 };