fix(legacy-json): more identical output

Author: avivkeller

src/generators/jsx-ast/utils/buildContent.mjs

@@ -229,7 +229,7 @@ export const processEntry = (entry, remark) => {
   // Transform typed lists into property tables
   visit(
     content,
-    createQueries.UNIST.isTypedList,
+    createQueries.UNIST.isStronglyTypedList,
     (node, idx, parent) => (parent.children[idx] = createPropertyTable(node))
   );
 

src/generators/jsx-ast/utils/buildPropertyTable.mjs

@@ -124,7 +124,7 @@ export const parseListIntoProperties = node => {
 
     // Clean up leading whitespace in remaining description
     if (children[0]?.type === 'text') {
-      children[0].value = children[0].value.trimStart();
+      children[0].value = children[0].value.replace(/^[\s:]+/, '');
     }
 
     properties.push({
@@ -133,7 +133,7 @@ export const parseListIntoProperties = node => {
       // The remaining children are the description
       desc: children,
       // Is there a list within this list?
-      sublist: sublists.find(createQueries.UNIST.isTypedList),
+      sublist: sublists.find(createQueries.UNIST.isLooselyTypedList),
     });
   }
 

src/generators/jsx-ast/utils/buildSignature.mjs

@@ -89,7 +89,7 @@ export const getFullName = ({ name, text }, fallback = name) => {
  */
 export default ({ children }, { data }, idx) => {
   // Try to locate the parameter list immediately following the heading
-  const listIdx = children.findIndex(createQueries.UNIST.isTypedList);
+  const listIdx = children.findIndex(createQueries.UNIST.isStronglyTypedList);
 
   // Parse parameters from the list, if found
   const params =

src/generators/legacy-json/constants.mjs

@@ -12,7 +12,7 @@ export const DEFAULT_EXPRESSION = /\s*\*\*Default:\*\*\s*([^]+)$/i;
 
 // Grabs the parameters from a method's signature
 //  ex/ 'new buffer.Blob([sources[, options]])'.match(PARAM_EXPRESSION) === ['([sources[, options]])', '[sources[, options]]']
-export const PARAM_EXPRESSION = /\((.+)\);?$/;
+export const PARAM_EXPRESSION = /\(([^)]+)\);?$/;
 
 // The plurals associated with each section type.
 export const SECTION_TYPE_PLURALS = {

src/generators/legacy-json/utils/__tests__/parseList.test.mjs

@@ -8,6 +8,16 @@ import {
   parseList,
 } from '../parseList.mjs';
 
+const validTypedList = [
+  { type: 'inlineCode', value: 'option' }, // inline code
+  { type: 'text', value: ' ' }, // space
+  {
+    type: 'link',
+    children: [{ type: 'text', value: '<boolean>' }], // link with < value
+  },
+  { type: 'text', value: ' option description' },
+];
+
 describe('transformTypeReferences', () => {
   it('replaces template syntax with curly braces', () => {
     const result = transformTypeReferences('`<string>`');
@@ -90,7 +100,7 @@ describe('parseList', () => {
             children: [
               {
                 type: 'paragraph',
-                children: [{ type: 'text', value: '{string} description' }],
+                children: validTypedList,
               },
             ],
           },
@@ -134,9 +144,7 @@ describe('parseList', () => {
             children: [
               {
                 type: 'paragraph',
-                children: [
-                  { type: 'text', value: 'param1 {string} first parameter' },
-                ],
+                children: validTypedList,
               },
               // This is a nested typed list
               {
@@ -146,15 +154,7 @@ describe('parseList', () => {
                     children: [
                       {
                         type: 'paragraph',
-                        children: [
-                          { type: 'inlineCode', value: 'option' }, // inline code
-                          { type: 'text', value: ' ' }, // space
-                          {
-                            type: 'link',
-                            children: [{ type: 'text', value: '<boolean>' }], // link with < value
-                          },
-                          { type: 'text', value: ' option description' },
-                        ],
+                        children: validTypedList,
                       },
                     ],
                   },
@@ -167,6 +167,9 @@ describe('parseList', () => {
     ];
 
     parseList(section, nodes);
+
+    console.log(section);
+
     assert.equal(section.params[0].options.length, 1);
   });
 });

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

@@ -53,7 +53,7 @@ export const createSectionBuilder = () => {
 
     meta.changes = changes;
 
-    if (n_api_version?.length) {
+    if (typeof n_api_version === 'number' || n_api_version?.length) {
       meta.napiVersion = enforceArray(n_api_version);
     }
 
@@ -102,13 +102,17 @@ export const createSectionBuilder = () => {
    * @param {Array} nodes - The remaining AST nodes.
    * @param {import('../types.d.ts').HierarchizedEntry} entry - The entry providing stability information.
    */
-  const parseStability = (section, nodes, { stability }) => {
-    const stabilityInfo = stability.children.map(node => node.data)?.[0];
+  const parseStability = (section, nodes, { stability, content }) => {
+    const stabilityNode = stability.children[0];
 
-    if (stabilityInfo) {
-      section.stability = Number(stabilityInfo.index);
-      section.stabilityText = stabilityInfo.description;
-      nodes.shift(); // Remove stability node from processing
+    if (stabilityNode) {
+      section.stability = Number(stabilityNode.data.index);
+      section.stabilityText = stabilityNode.data.description;
+
+      const nodeToRemove = content.children.findIndex(
+        ({ data }) => data === stabilityNode.data
+      );
+      nodes.splice(nodeToRemove - 1, 1);
     }
   };
 
@@ -153,7 +157,10 @@ export const createSectionBuilder = () => {
    * @param {import('../types.d.ts').Section} parent - The parent section.
    */
   const addToParent = (section, parent) => {
-    const key = SECTION_TYPE_PLURALS[section.type] || 'miscs';
+    const key =
+      SECTION_TYPE_PLURALS[section.__promote ?? section.type] || 'miscs';
+
+    delete section.__promote;
 
     parent[key] ??= [];
     parent[key].push(section);

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

@@ -47,7 +47,7 @@ export const extractPattern = (text, pattern, key, current) => {
 export function parseListItem(child) {
   const current = {};
 
-  const subList = child.children.find(createQueries.UNIST.isTypedList);
+  const subList = child.children.find(createQueries.UNIST.isLooselyTypedList);
 
   // Extract and clean raw text from the node, excluding nested lists
   current.textRaw = transformTypeReferences(
@@ -89,10 +89,13 @@ export function parseListItem(child) {
  * @param {import('@types/mdast').RootContent[]} nodes
  */
 export function parseList(section, nodes) {
-  const list = nodes[0]?.type === 'list' ? nodes.shift() : null;
+  const listIdx = nodes.findIndex(createQueries.UNIST.isStronglyTypedList);
+  const list = nodes[listIdx];
 
   const values = list ? list.children.map(parseListItem) : [];
 
+  let removeList = true;
+
   // Update the section based on its type and parsed values
   switch (section.type) {
     case 'ctor':
@@ -109,7 +112,12 @@ export function parseList(section, nodes) {
     case 'property':
       // For properties, update type and other details if values exist
       if (values.length) {
-        leftHandAssign(section, values[0]);
+        delete values[0].name;
+
+        Object.assign(section, values[0]);
+
+        // TODO(@avivkeller): There is probably a better way to do this.
+        section.__promote = 'property';
       }
       break;
 
@@ -119,9 +127,10 @@ export function parseList(section, nodes) {
       break;
 
     default:
-      // If no specific handling, re-add the list for further processing
-      if (list) {
-        nodes.unshift(list);
-      }
+      removeList = false;
+  }
+
+  if (removeList && list) {
+    nodes.splice(listIdx, 1);
   }
 }

src/utils/parser/constants.mjs

@@ -37,17 +37,20 @@ const FUNCTION_CALL = '\\([^)]*\\)';
 // Matches "bar":
 // Group 1: foo[bar]
 // Group 2: foo.bar
-const PROPERTY = `${CAMEL_CASE}(?:(\\[${CAMEL_CASE}\\])|\\.(\\w+))`;
+const PROPERTY = `${CAMEL_CASE}(?:(\\[[^\\]]+\\])|\\.(\\w+))`;
 
 // An array of objects defining the different types of API doc headings we want to
 // capture and their respective regex to match against the heading text.
 // The regex are case-insensitive.
 export const DOC_API_HEADING_TYPES = [
   {
     type: 'method',
-    regex: new RegExp(`^\`${PROPERTY}${FUNCTION_CALL}\`$`, 'i'),
+    regex: new RegExp(
+      `^\`(?:${PROPERTY}|(${CAMEL_CASE}))${FUNCTION_CALL}\`$`,
+      'i'
+    ),
   },
-  { type: 'event', regex: /^Event: +`'?([^']+)'`$/i },
+  { type: 'event', regex: /^Event: +`'?([^`]*?)'?`$/i },
   {
     type: 'class',
     regex: new RegExp(

src/utils/queries/__tests__/index.test.mjs

@@ -108,17 +108,23 @@ describe('createQueries', () => {
   });
 
   describe('UNIST', () => {
-    describe('isTypedList', () => {
+    describe('isStronglyTypedList', () => {
       it('returns false for non-list nodes', () => {
         strictEqual(
-          createQueries.UNIST.isTypedList({ type: 'paragraph', children: [] }),
+          createQueries.UNIST.isStronglyTypedList({
+            type: 'paragraph',
+            children: [],
+          }),
           false
         );
       });
 
       it('returns false for empty lists', () => {
         strictEqual(
-          createQueries.UNIST.isTypedList({ type: 'list', children: [] }),
+          createQueries.UNIST.isStronglyTypedList({
+            type: 'list',
+            children: [],
+          }),
           false
         );
       });
@@ -211,7 +217,7 @@ describe('createQueries', () => {
 
       cases.forEach(({ name, node, expected }) => {
         it(`returns ${expected} for ${name}`, () => {
-          strictEqual(createQueries.UNIST.isTypedList(node), expected);
+          strictEqual(createQueries.UNIST.isStronglyTypedList(node), expected);
         });
       });
     });

src/utils/queries/constants.mjs

@@ -4,4 +4,4 @@
 export const DOC_API_STABILITY_SECTION_REF_URL =
   'documentation.html#stability-index';
 
-export const VALID_JAVASCRIPT_PROPERTY = /^[.a-z0-9$_]+$/i;
+export const VALID_JAVASCRIPT_PROPERTY = /^[.a-z0-9$_'-]+$/i;