fix(legacy-json): more identical output (#526)

* fix(legacy-json): more identical output

* fixup!

* no __promote

* dont clone stability, use ref

* tests

Author: avivkeller

src/generators/jsx-ast/constants.mjs

@@ -150,3 +150,5 @@ export const TYPES_WITH_METHOD_SIGNATURES = [
   'method',
   'classMethod',
 ];
+
+export const TRIMMABLE_PADDING_REGEX = /^[\s:]+/;

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

@@ -1,6 +1,7 @@
 import { h as createElement } from 'hastscript';
 
 import createQueries from '../../../utils/queries/index.mjs';
+import { TRIMMABLE_PADDING_REGEX } from '../constants.mjs';
 
 /**
  * Determines if a node looks like part of a type annotation.
@@ -124,7 +125,10 @@ 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(
+        TRIMMABLE_PADDING_REGEX,
+        ''
+      );
     }
 
     properties.push({
@@ -133,7 +137,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

@@ -93,7 +93,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,
                       },
                     ],
                   },

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,18 @@ 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 stabilityIdx = content.children.indexOf(stability.children[0]);
+
+      if (stabilityIdx) {
+        nodes.splice(stabilityIdx - 1, 1);
+      }
     }
   };
 
@@ -153,7 +158,7 @@ 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.type] || 'properties';
 
     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,9 @@ 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]);
       }
       break;
 
@@ -119,9 +124,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/metadata.mjs

@@ -47,11 +47,8 @@ const createMetadata = slugger => {
      *
      * @param {StabilityIndexParent} stability The stability index node to be added
      */
-    addStability: stability => {
-      // We clone the stability to ensure that we don't accidentally override it
-      // with later mutations below on the `.create` method
-      internalMetadata.stability.children.push({ ...stability });
-    },
+    addStability: stability =>
+      internalMetadata.stability.children.push(stability),
     /**
      * Set the Metadata (from YAML if exists) properties to the current Metadata entry
      * it also allows for extra data (such as Stability Index) and miscellaneous data to be set

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(