Refactor internals to clarify some code

Closes GH-2253.

Author: wooorm

package-lock.json

@@ -7,6 +7,10 @@
  * @typedef {import('estree-jsx').Expression} Expression
  * @typedef {import('estree-jsx').FunctionDeclaration} FunctionDeclaration
  * @typedef {import('estree-jsx').ImportDeclaration} ImportDeclaration
+ * @typedef {import('estree-jsx').ImportDefaultSpecifier} ImportDefaultSpecifier
+ * @typedef {import('estree-jsx').ImportExpression} ImportExpression
+ * @typedef {import('estree-jsx').ImportSpecifier} ImportSpecifier
+ * @typedef {import('estree-jsx').Literal} Literal
  * @typedef {import('estree-jsx').JSXElement} JSXElement
  * @typedef {import('estree-jsx').ModuleDeclaration} ModuleDeclaration
  * @typedef {import('estree-jsx').Node} Node
@@ -186,25 +190,38 @@ export function recmaDocument(options) {
             layout = specifier
 
             // Make it just an import: `import MDXLayout from '…'`.
-            handleEsm(
-              create(specifier, {
-                type: 'ImportDeclaration',
-                specifiers: [
-                  // Default as default / something else as default.
-                  specifier.local.name === 'default'
-                    ? {
-                        type: 'ImportDefaultSpecifier',
-                        local: {type: 'Identifier', name: 'MDXLayout'}
-                      }
-                    : create(specifier.local, {
-                        type: 'ImportSpecifier',
-                        imported: specifier.local,
-                        local: {type: 'Identifier', name: 'MDXLayout'}
-                      })
-                ],
-                source: create(source, {type: 'Literal', value: source.value})
+            /** @type {Array<ImportDefaultSpecifier | ImportSpecifier>} */
+            const specifiers = []
+
+            // Default as default / something else as default.
+            if (specifier.local.name === 'default') {
+              specifiers.push({
+                type: 'ImportDefaultSpecifier',
+                local: {type: 'Identifier', name: 'MDXLayout'}
               })
-            )
+            } else {
+              /** @type {ImportSpecifier} */
+              const importSpecifier = {
+                type: 'ImportSpecifier',
+                imported: specifier.local,
+                local: {type: 'Identifier', name: 'MDXLayout'}
+              }
+              create(specifier.local, importSpecifier)
+              specifiers.push(importSpecifier)
+            }
+
+            /** @type {Literal} */
+            const from = {type: 'Literal', value: source.value}
+            create(source, from)
+
+            /** @type {ImportDeclaration} */
+            const declaration = {
+              type: 'ImportDeclaration',
+              specifiers,
+              source: from
+            }
+            create(specifier, declaration)
+            handleEsm(declaration)
 
             return false
           }
@@ -376,7 +393,10 @@ export function recmaDocument(options) {
           // with import maps (<https://github.com/WICG/import-maps>).
         }
 
-        node.source = create(node.source, {type: 'Literal', value})
+        /** @type {Literal} */
+        const literal = {type: 'Literal', value}
+        create(node.source, literal)
+        node.source = literal
       }
 
       /** @type {ModuleDeclaration | Statement | undefined} */
@@ -416,13 +436,10 @@ export function recmaDocument(options) {
           // export * from 'a'
           // //=> const _exportAll0 = await import('a')
           // ```
-          init = {
-            type: 'AwaitExpression',
-            argument: create(node, {
-              type: 'ImportExpression',
-              source: node.source
-            })
-          }
+          /** @type {ImportExpression} */
+          const argument = {type: 'ImportExpression', source: node.source}
+          create(node, argument)
+          init = {type: 'AwaitExpression', argument}
 
           if (
             (node.type === 'ImportDeclaration' ||

packages/mdx/lib/plugin/recma-document.js

@@ -3,25 +3,25 @@
  */
 
 /**
- * @template {Node} N
- * @param {Node} template
- * @param {N} node
- * @returns {N}
+ * @param {Node} from
+ *   Node to take from.
+ * @param {Node} to
+ *   Node to add to.
+ * @returns {void}
+ *   Nothing.
  */
-export function create(template, node) {
-  /** @type {Array<keyof template>} */
+export function create(from, to) {
+  /** @type {Array<keyof Node>} */
   // @ts-expect-error: `start`, `end`, `comments` are custom Acorn fields.
   const fields = ['start', 'end', 'loc', 'range', 'comments']
   let index = -1
 
   while (++index < fields.length) {
     const field = fields[index]
 
-    if (field in template) {
+    if (field in from) {
       // @ts-expect-error: assume they’re settable.
-      node[field] = template[field]
+      to[field] = from[field]
     }
   }
-
-  return node
 }

packages/mdx/lib/util/estree-util-create.js

@@ -1,10 +1,11 @@
 /**
+ * @typedef {import('estree-jsx').AssignmentProperty} AssignmentProperty
  * @typedef {import('estree-jsx').ExportSpecifier} ExportSpecifier
  * @typedef {import('estree-jsx').Expression} Expression
  * @typedef {import('estree-jsx').Identifier} Identifier
- * @typedef {import('estree-jsx').ImportSpecifier} ImportSpecifier
  * @typedef {import('estree-jsx').ImportDefaultSpecifier} ImportDefaultSpecifier
  * @typedef {import('estree-jsx').ImportNamespaceSpecifier} ImportNamespaceSpecifier
+ * @typedef {import('estree-jsx').ImportSpecifier} ImportSpecifier
  * @typedef {import('estree-jsx').VariableDeclarator} VariableDeclarator
  */
 
@@ -36,13 +37,14 @@ export function specifiersToDeclarations(specifiers, init) {
   }
 
   if (importNamespaceSpecifier) {
-    declarations.push(
-      create(importNamespaceSpecifier, {
-        type: 'VariableDeclarator',
-        id: importNamespaceSpecifier.local,
-        init
-      })
-    )
+    /** @type {VariableDeclarator} */
+    const declarator = {
+      type: 'VariableDeclarator',
+      id: importNamespaceSpecifier.local,
+      init
+    }
+    create(importNamespaceSpecifier, declarator)
+    declarations.push(declarator)
   }
 
   declarations.push({
@@ -65,15 +67,18 @@ export function specifiersToDeclarations(specifiers, init) {
           key = specifier.local
         }
 
-        return create(specifier, {
+        /** @type {AssignmentProperty} */
+        const property = {
           type: 'Property',
           kind: 'init',
           shorthand: key.name === value.name,
           method: false,
           computed: false,
           key,
           value
-        })
+        }
+        create(specifier, property)
+        return property
       })
     },
     init: importNamespaceSpecifier