code review (2)

Author: avivkeller

src/generators/legacy-json-all/index.mjs

@@ -53,7 +53,9 @@ export default {
       });
     });
 
-    await writeFile(join(output, 'all.json'), JSON.stringify(generatedValue));
+    if (output) {
+      await writeFile(join(output, 'all.json'), JSON.stringify(generatedValue));
+    }
 
     return generatedValue;
   },

src/generators/legacy-json/index.mjs

@@ -55,10 +55,12 @@ export default {
         const section = processModuleNodes(node);
 
         // Write it to the output file
-        await writeFile(
-          join(output, `${node.api}.json`),
-          JSON.stringify(section)
-        );
+        if (output) {
+          await writeFile(
+            join(output, `${node.api}.json`),
+            JSON.stringify(section)
+          );
+        }
       })
     );
 

src/generators/legacy-json/utils/buildSection.mjs

@@ -71,26 +71,24 @@ function createSection(entry, head) {
   };
 }
 
+/**
+ *
+ * @param {String} string
+ * @returns {String}
+ */
+function transformTypeReferences(string) {
+  // console.log(string)
+  return string.replaceAll(/`<([^>]+)>`/g, '{$1}').replaceAll('} | {', '|');
+}
+
 /**
  * Parses a list item to extract properties.
  * @param {import('mdast').ListItem} child - The list item node.
- * @param {import('../types.d.ts').HierarchizedEntry} entry - The entry containing raw content.
  * @returns {import('../types.d.ts').List} The parsed list.
  */
-function parseListItem(child, entry) {
+function parseListItem(child) {
   const current = {};
 
-  /**
-   * Extracts raw content from a node based on its position.
-   * @param {import('mdast').BlockContent} node
-   * @returns {string}
-   */
-  const getRawContent = node =>
-    entry.rawContent.slice(
-      node.position.start.offset,
-      node.position.end.offset
-    );
-
   /**
    * Extracts a pattern from text and assigns it to the current object.
    * @param {string} text
@@ -108,12 +106,14 @@ function parseListItem(child, entry) {
   };
 
   // Combine and clean text from child nodes, excluding nested lists
-  current.textRaw = child.children
-    .filter(node => node.type !== 'list')
-    .map(getRawContent)
-    .join('')
-    .replace(/\s+/g, ' ')
-    .replace(/<!--.*?-->/gs, '');
+  current.textRaw = transformTypeReferences(
+    transformNodesToString(
+      child.children.filter(node => node.type !== 'list'),
+      true
+    )
+      .replace(/\s+/g, ' ')
+      .replace(/<!--.*?-->/gs, '')
+  );
 
   let text = current.textRaw;
 
@@ -136,9 +136,7 @@ function parseListItem(child, entry) {
   const optionsNode = child.children.find(child => child.type === 'list');
 
   if (optionsNode) {
-    current.options = optionsNode.children.map(child =>
-      parseListItem(child, entry)
-    );
+    current.options = optionsNode.children.map(parseListItem);
   }
 
   return current;
@@ -148,38 +146,26 @@ function parseListItem(child, entry) {
  * Parses stability metadata and adds it to the section.
  * @param {import('../types.d.ts').Section} section - The section to add stability to.
  * @param {Array} nodes - The AST nodes.
+ * @param {import('../types.d.ts').HierarchizedEntry} entry - The entry to handle.
  */
-function parseStability(section, nodes) {
-  nodes.forEach((node, i) => {
-    if (
-      node.type === 'blockquote' &&
-      node.children.length === 1 &&
-      node.children[0].type === 'paragraph' &&
-      nodes.slice(0, i).every(n => n.type === 'list')
-    ) {
-      const text = transformNodesToString(node.children[0].children);
-      const stabilityMatch = /^Stability: ([0-5])(?:\s*-\s*)?(.*)$/s.exec(text);
-      if (stabilityMatch) {
-        section.stability = Number(stabilityMatch[1]);
-        section.stabilityText = stabilityMatch[2].replace(/\n/g, ' ').trim();
-        nodes.splice(i, 1); // Remove the matched stability node to prevent further processing
-      }
-    }
-  });
+function parseStability(section, nodes, entry) {
+  const json = entry.stability.toJSON()[0];
+  if (json) {
+    section.stability = json.index;
+    section.stabilityText = json.description;
+    nodes.splice(0, 1);
+  }
 }
 
 /**
  * Parses a list and updates the section accordingly.
  * @param {import('../types.d.ts').Section} section - The section to update.
  * @param {Array} nodes - The AST nodes.
- * @param {import('../types.d.ts').HierarchizedEntry} entry - The associated entry.
  */
-function parseList(section, nodes, entry) {
+function parseList(section, nodes) {
   const list = nodes[0]?.type === 'list' ? nodes.shift() : null;
 
-  const values = list
-    ? list.children.map(child => parseListItem(child, entry))
-    : [];
+  const values = list ? list.children.map(parseListItem) : [];
 
   switch (section.type) {
     case 'ctor':
@@ -296,8 +282,8 @@ function handleEntry(entry, parentSection) {
   const [headingNode, ...nodes] = structuredClone(entry.content.children);
   const section = createSection(entry, headingNode);
 
-  parseStability(section, nodes);
-  parseList(section, nodes, entry);
+  parseStability(section, nodes, entry);
+  parseList(section, nodes);
   addDescription(section, nodes);
   handleChildren(entry, section);
   addAdditionalMetadata(section, parentSection, headingNode);

src/metadata.mjs

@@ -155,7 +155,6 @@ const createMetadata = slugger => {
         content: section,
         tags,
         introduced_in,
-        rawContent: apiDoc.toString(),
       };
     },
   };

src/queries.mjs

@@ -1,7 +1,7 @@
 'use strict';
 
 import { u as createTree } from 'unist-builder';
-import { SKIP, visit } from 'unist-util-visit';
+import { SKIP } from 'unist-util-visit';
 
 import { DOC_API_STABILITY_SECTION_REF_URL } from './constants.mjs';
 
@@ -76,23 +76,26 @@ const createQueries = () => {
    * @param {import('mdast').Parent} parent The parent node
    */
   const updateTypeReference = (node, parent) => {
-    const replacedTypes = node.value.replace(
-      createQueries.QUERIES.normalizeTypes,
-      transformTypeToReferenceLink
-    );
-
-    // This changes the type into a link by splitting it up
-    // into several nodes, and adding those nodes to the
-    // parent.
+    const replacedTypes = node.value
+      .replace(
+        createQueries.QUERIES.normalizeTypes,
+        transformTypeToReferenceLink
+      )
+      // Remark doesn't handle leading / trailing spaces, so replace them with
+      // HTML entities.
+      .replace(/^\s/, ' ')
+      .replace(/\s$/, ' ');
+
+    // This changes the type into a link by splitting it up into several nodes,
+    // and adding those nodes to the parent.
     const {
       children: [newNode],
     } = remark.parse(replacedTypes);
+
+    // Find the index of the original node in the parent
     const index = parent.children.indexOf(node);
-    const originalPosition = node.position;
-    visit(newNode, node => {
-      (node.position.start += originalPosition.start),
-        (node.position.end += originalPosition.end);
-    });
+
+    // Replace the original node with the new node(s)
     parent.children.splice(index, 1, ...newNode.children);
 
     return [SKIP];

src/test/metadata.test.mjs

@@ -73,7 +73,6 @@ describe('createMetadata', () => {
       heading,
       n_api_version: undefined,
       introduced_in: undefined,
-      rawContent: '',
       removed_in: undefined,
       slug: 'test-heading',
       source_link: 'test.com',

src/types.d.ts

@@ -98,8 +98,6 @@ declare global {
     // Extra YAML section entries that are stringd and serve
     // to provide additional metadata about the API doc entry
     tags: Array<string>;
-    // The raw file content
-    rawContent: string;
   }
 
   export interface ApiDocReleaseEntry {