htm-transform 0.1.3 → 0.1.5

package/index.js

@@ -1,6 +1,6 @@
 import * as acorn from "acorn";
 import { generate } from "astring";
-import { simple } from "acorn-walk";
+import { attachComments, makeTraveler } from "astravel";
 
 /**
  * @typedef {Object} ElementNode
@@ -11,23 +11,23 @@ import { simple } from "acorn-walk";
  */
 
 /**
- * @typedef {Object} TextNode
+ * @typedef {object} TextNode
  * @property {'text'} type
  * @property {string} value
  */
 
 /**
- * @typedef {Object} ExpressionNode
+ * @typedef {object} ExpressionNode
  * @property {'expression'} type
  * @property {string} value
  * @property {import('acorn').Node} [expr]
  */
 
 /**
- * @typedef {Object} Token
+ * @typedef {object} Token
  * @property {'openTag' | 'closeTag' | 'text' | 'expression'} type
  * @property {string} [tag]
- * @property {Object<string, string | boolean>} [props]
+ * @property {Record<string, string | boolean>} [props]
  * @property {boolean} [selfClosing]
  * @property {string} [value]
  */
@@ -35,10 +35,10 @@ import { simple } from "acorn-walk";
 /**
  * Transforms htm tagged templates into h function calls
  * @param {string} code - JavaScript code containing htm tagged templates
- * @param {Object} options - Transform options
- * @param {string} options.pragma - The h function name (default: 'h')
- * @param {string} options.tag - The tag name to look for (default: 'html')
- * @param {Object} options.import - Import configuration
+ * @param {object} [options] - Transform options
+ * @param {string} [options.pragma] - The h function name (default: 'h')
+ * @param {string} [options.tag] - The tag name to look for (default: 'html')
+ * @param {object} [options.import] - Import configuration
  * @param {string} options.import.from - Module to import from (e.g., 'preact', 'react')
  * @param {string} options.import.name - Export name to import (e.g., 'h', 'createElement')
  * @returns {string} - Transformed code
@@ -46,75 +46,125 @@ import { simple } from "acorn-walk";
 export default function transform(code, options = {}) {
   const { pragma = "h", tag: tagName = "html", import: importConfig } = options;
 
-  const ast = acorn.parse(code, {
-    ecmaVersion: "latest",
-    sourceType: "module",
-  });
+  /** @type {Array<import('acorn').Comment>} */
+  const comments = [];
+
+  const ast = /** @type {import('acorn').Program} */ (
+    acorn.parse(code, {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      locations: true,
+      onComment: comments,
+    })
+  );
 
   let hasTransformation = false;
 
-  simple(ast, {
-    TaggedTemplateExpression(node) {
+  const traveler = makeTraveler({
+    TaggedTemplateExpression(node, state) {
       if (node.tag.type === "Identifier" && node.tag.name === tagName) {
         hasTransformation = true;
         const transformed = transformTaggedTemplate(node, pragma);
 
         // Replace the node with the transformed version
-        for (const key in node) {
-          delete node[key];
+        const mutableNode = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (node));
+        for (const key in mutableNode) {
+          delete mutableNode[key];
         }
         Object.assign(node, transformed);
+        // Continue traversing into the transformed node to handle nested templates
+        this.go(node, state);
+        return;
       }
+      // Continue traversal for non-matching nodes
+      this.super.TaggedTemplateExpression.call(this, node, state);
     },
   });
 
+  traveler.go(ast);
+
   // Add import statement if specified and transformation occurred
   if (hasTransformation && importConfig?.from && importConfig?.name) {
     addImportDeclaration(ast, importConfig.from, importConfig.name);
   }
 
-  return generate(ast);
+  // Attach comments to AST nodes
+  if (comments.length > 0) {
+    attachComments(ast, comments);
+  }
+
+  return generate(ast, { comments: true });
 }
 
 /**
  * Adds an import declaration at the top of the AST
- * @param {import('acorn').Node} ast - The AST to modify
+ * @param {import('acorn').Program} ast - The AST to modify
  * @param {string} moduleName - The module to import from
  * @param {string} exportName - The export name to import
  * @returns {void}
  */
 function addImportDeclaration(ast, moduleName, exportName) {
   const hasImport = ast.body.some(
-    (node) =>
-      node.type === "ImportDeclaration" &&
-      node.source.value === moduleName &&
-      node.specifiers.some(
-        (spec) => spec.type === "ImportSpecifier" && spec.imported.name === exportName,
-      ),
+    /**
+     * @param {import('acorn').Statement | import('acorn').ModuleDeclaration} node
+     * @returns {boolean}
+     */
+    (node) => {
+      if (node.type !== "ImportDeclaration") return false;
+      const importNode = /** @type {import('acorn').ImportDeclaration} */ (node);
+      return (
+        importNode.source.value === moduleName &&
+        importNode.specifiers.some(
+          /**
+           * @param {import('acorn').ImportSpecifier | import('acorn').ImportDefaultSpecifier | import('acorn').ImportNamespaceSpecifier} spec
+           * @returns {boolean}
+           */
+          (spec) => {
+            if (spec.type !== "ImportSpecifier") return false;
+            const importSpec = /** @type {import('acorn').ImportSpecifier} */ (spec);
+            return (
+              importSpec.imported.type === "Identifier" && importSpec.imported.name === exportName
+            );
+          },
+        )
+      );
+    },
   );
 
   if (hasImport) return;
 
   // Create import declaration: import { exportName } from 'moduleName';
+  /** @type {import('acorn').ImportDeclaration} */
   const importDeclaration = {
     type: "ImportDeclaration",
+    start: 0,
+    end: 0,
     specifiers: [
       {
         type: "ImportSpecifier",
+        start: 0,
+        end: 0,
         imported: {
           type: "Identifier",
+          start: 0,
+          end: 0,
           name: exportName,
         },
         local: {
           type: "Identifier",
+          start: 0,
+          end: 0,
           name: exportName,
         },
       },
     ],
     source: {
       type: "Literal",
+      start: 0,
+      end: 0,
       value: moduleName,
     },
+    attributes: [],
   };
 
   // Add to the beginning of the body
@@ -123,9 +173,9 @@ function addImportDeclaration(ast, moduleName, exportName) {
 
 /**
  * Transforms a single tagged template expression
- * @param {import('acorn').Node} node - The tagged template expression node
+ * @param {import('acorn').TaggedTemplateExpression} node - The tagged template expression node
  * @param {string} pragma - The pragma function name
- * @returns {import('acorn').Node} The transformed AST node
+ * @returns {import('acorn').Literal | import('acorn').CallExpression | import('acorn').ArrayExpression | import('acorn').Expression} The transformed AST node
  */
 function transformTaggedTemplate(node, pragma) {
   const quasi = node.quasi;
@@ -149,15 +199,21 @@ function transformTaggedTemplate(node, pragma) {
 
   // Convert to h() calls
   if (elements.length === 0) {
-    return { type: "Literal", value: null };
+    /** @type {import('acorn').Literal} */
+    const literal = { type: "Literal", start: 0, end: 0, value: null };
+    return literal;
   } else if (elements.length === 1) {
     return elementsToAST(elements[0], pragma);
   } else {
     // Multiple root elements - return array
-    return {
+    /** @type {import('acorn').ArrayExpression} */
+    const arrayExpr = {
       type: "ArrayExpression",
+      start: 0,
+      end: 0,
       elements: elements.map((el) => elementsToAST(el, pragma)),
     };
+    return arrayExpr;
   }
 }
 
@@ -185,15 +241,16 @@ function parseTemplate(template, placeholders) {
 
       if (token.type === "openTag") {
         i++;
+        /** @type {ElementNode} */
         const element = {
           type: "element",
-          tag: token.tag,
-          props: token.props,
+          tag: token.tag || "",
+          props: token.props || {},
           children: [],
         };
 
         if (!token.selfClosing) {
-          element.children = parse(token.tag);
+          element.children = parse(token.tag || "");
         }
 
         children.push(element);
@@ -204,13 +261,17 @@ function parseTemplate(template, placeholders) {
         }
         i++;
       } else if (token.type === "text") {
-        const text = token.value.trim();
+        const text = (token.value || "").trim();
         if (text) {
-          children.push({ type: "text", value: text });
+          /** @type {TextNode} */
+          const textNode = { type: "text", value: text };
+          children.push(textNode);
         }
         i++;
       } else if (token.type === "expression") {
-        children.push({ type: "expression", value: token.value });
+        /** @type {ExpressionNode} */
+        const exprNode = { type: "expression", value: token.value || "" };
+        children.push(exprNode);
         i++;
       } else {
         i++;
@@ -232,6 +293,7 @@ function parseTemplate(template, placeholders) {
  * @returns {Array<Token>} Array of tokens
  */
 function tokenize(template) {
+  /** @type {Token[]} */
   const tokens = [];
   let i = 0;
 
@@ -244,21 +306,27 @@ function tokenize(template) {
         const [full, isClosing, tagName, attrsStr, selfClosing] = tagMatch;
 
         if (isClosing) {
-          tokens.push({ type: "closeTag", tag: tagName });
+          /** @type {Token} */
+          const closeToken = { type: "closeTag", tag: tagName };
+          tokens.push(closeToken);
         } else {
           const props = parseAttributes(attrsStr);
-          tokens.push({
+          /** @type {Token} */
+          const openToken = {
             type: "openTag",
             tag: tagName,
             props,
             selfClosing: selfClosing === "/",
-          });
+          };
+          tokens.push(openToken);
         }
 
         i += full.length;
       } else {
         // Not a valid tag, treat as text
-        tokens.push({ type: "text", value: "<" });
+        /** @type {Token} */
+        const textToken = { type: "text", value: "<" };
+        tokens.push(textToken);
         i++;
       }
     } else {
@@ -272,9 +340,13 @@ function tokenize(template) {
       // Check if this is an expression placeholder
       const exprMatch = text.match(/^(__EXPR_\d+__)/);
       if (exprMatch && text === exprMatch[0]) {
-        tokens.push({ type: "expression", value: exprMatch[0] });
+        /** @type {Token} */
+        const exprToken = { type: "expression", value: exprMatch[0] };
+        tokens.push(exprToken);
       } else if (text.trim()) {
-        tokens.push({ type: "text", value: text });
+        /** @type {Token} */
+        const textToken = { type: "text", value: text };
+        tokens.push(textToken);
       }
     }
   }
@@ -288,6 +360,7 @@ function tokenize(template) {
  * @returns {Object<string, string | boolean>} Parsed attributes object
  */
 function parseAttributes(attrsStr) {
+  /** @type {Record<string, string | boolean>} */
   const props = {};
   const attrRegex = /([a-zA-Z0-9_:-]+)(?:=(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
   let match;
@@ -319,45 +392,69 @@ function resolvePlaceholders(nodes, placeholders) {
     if (node.type === "element") {
       // Resolve tag name if it's a placeholder (component)
       if (typeof node.tag === "string" && node.tag.startsWith("__EXPR_")) {
-        node.tag = { type: "expression", expr: placeholderMap.get(node.tag) };
+        const expr = placeholderMap.get(node.tag);
+        if (expr) {
+          node.tag = { type: "expression", expr };
+        }
       }
 
       // Resolve props, preserving order
+      /** @type {Record<string, string | boolean | {type: 'expression', expr: import('acorn').Node}>} */
       const newProps = {};
       for (const [key, value] of Object.entries(node.props)) {
         if (key.startsWith("__EXPR_")) {
           // Handle spread props (key is the placeholder)
-          newProps["...spread"] = { type: "expression", expr: placeholderMap.get(key) };
+          const expr = placeholderMap.get(key);
+          if (expr) {
+            newProps["...spread"] = { type: "expression", expr };
+          }
         } else if (typeof value === "string" && placeholderMap.has(value)) {
           // Single placeholder value
-          newProps[key] = { type: "expression", expr: placeholderMap.get(value) };
+          const expr = placeholderMap.get(value);
+          if (expr) {
+            newProps[key] = { type: "expression", expr };
+          }
         } else if (typeof value === "string" && value.includes("__EXPR_")) {
           // Template string with placeholders - create TemplateLiteral
           const parts = value.split(/(__EXPR_\d+__)/);
+          /** @type {Array<import('acorn').TemplateElement>} */
           const quasis = [];
+          /** @type {Array<import('acorn').Expression>} */
           const expressions = [];
 
           for (let i = 0; i < parts.length; i++) {
             if (i % 2 === 0) {
               // Static string part
-              quasis.push({
+              /** @type {import('acorn').TemplateElement} */
+              const templateElement = {
                 type: "TemplateElement",
+                start: 0,
+                end: 0,
                 value: { raw: parts[i], cooked: parts[i] },
                 tail: i === parts.length - 1,
-              });
+              };
+              quasis.push(templateElement);
             } else {
               // Expression placeholder
-              expressions.push(placeholderMap.get(parts[i]));
+              const expr = placeholderMap.get(parts[i]);
+              if (expr) {
+                expressions.push(/** @type {import('acorn').Expression} */ (expr));
+              }
             }
           }
 
+          /** @type {import('acorn').TemplateLiteral} */
+          const templateLiteral = {
+            type: "TemplateLiteral",
+            start: 0,
+            end: 0,
+            quasis,
+            expressions,
+          };
+
           newProps[key] = {
             type: "expression",
-            expr: {
-              type: "TemplateLiteral",
-              quasis,
-              expressions,
-            },
+            expr: templateLiteral,
           };
         } else {
           newProps[key] = value;
@@ -366,7 +463,9 @@ function resolvePlaceholders(nodes, placeholders) {
       node.props = newProps;
 
       // Resolve children
-      node.children = node.children.map(resolve);
+      node.children = /** @type {Array<ElementNode | TextNode | ExpressionNode>} */ (
+        node.children.map(resolve).flat()
+      );
     } else if (node.type === "expression") {
       const expr = placeholderMap.get(node.value);
       if (expr) {
@@ -376,21 +475,30 @@ function resolvePlaceholders(nodes, placeholders) {
       // Check if text contains placeholders
       const parts = node.value.split(/(__EXPR_\d+__)/);
       if (parts.length > 1) {
-        return parts
+        /** @type {Array<ElementNode | TextNode | ExpressionNode>} */
+        const result = parts
           .filter((p) => p)
           .map((p) => {
             if (p.startsWith("__EXPR_")) {
-              return { type: "expression", expr: placeholderMap.get(p) };
+              const expr = placeholderMap.get(p);
+              if (expr) {
+                /** @type {ExpressionNode} */
+                const exprNode = { type: "expression", value: p, expr };
+                return exprNode;
+              }
             }
-            return { type: "text", value: p };
+            /** @type {TextNode} */
+            const textNode = { type: "text", value: p };
+            return textNode;
           });
+        return result;
       }
     }
 
     return node;
   }
 
-  return nodes.map(resolve).flat();
+  return /** @type {Array<ElementNode | TextNode | ExpressionNode>} */ (nodes.map(resolve).flat());
 }
 
 /**
@@ -407,26 +515,36 @@ function needsQuoting(key) {
  * Converts element nodes to AST nodes representing h() calls
  * @param {ElementNode | TextNode | ExpressionNode} node - The node to convert
  * @param {string} pragma - The pragma function name
- * @returns {import('acorn').Node} The AST node
+ * @returns {import('acorn').Literal | import('acorn').CallExpression | import('acorn').Expression} The AST node
  */
 function elementsToAST(node, pragma) {
   if (node.type === "text") {
-    return { type: "Literal", value: node.value };
+    /** @type {import('acorn').Literal} */
+    const literal = { type: "Literal", start: 0, end: 0, value: node.value };
+    return literal;
   }
 
   if (node.type === "expression") {
-    return node.expr;
+    return /** @type {import('acorn').Expression} */ (node.expr);
   }
 
   if (node.type === "element") {
     // Build h(tag, props, ...children)
+    /** @type {Array<import('acorn').Expression | import('acorn').SpreadElement>} */
     const args = [];
 
     // Tag argument
-    if (node.tag.type === "expression") {
-      args.push(node.tag.expr);
+    if (typeof node.tag === "object" && node.tag.type === "expression") {
+      args.push(/** @type {import('acorn').Expression} */ (node.tag.expr));
     } else {
-      args.push({ type: "Literal", value: node.tag });
+      /** @type {import('acorn').Literal} */
+      const tagLiteral = {
+        type: "Literal",
+        start: 0,
+        end: 0,
+        value: /** @type {string} */ (node.tag),
+      };
+      args.push(tagLiteral);
     }
 
     // Props argument
@@ -434,54 +552,122 @@ function elementsToAST(node, pragma) {
     if (propsEntries.length > 0) {
       const spreadProp = node.props["...spread"];
 
-      if (spreadProp && propsEntries.length === 1) {
+      if (
+        spreadProp &&
+        typeof spreadProp === "object" &&
+        spreadProp.type === "expression" &&
+        propsEntries.length === 1
+      ) {
         // Just spread props
-        args.push(spreadProp.expr);
-      } else if (spreadProp) {
+        args.push(/** @type {import('acorn').Expression} */ (spreadProp.expr));
+      } else if (spreadProp && typeof spreadProp === "object" && spreadProp.type === "expression") {
         // Merge spread with other props, preserving order
+        /** @type {Array<import('acorn').Property | import('acorn').SpreadElement>} */
         const properties = propsEntries.map(([key, value]) => {
-          if (key === "...spread") {
-            return {
+          if (key === "...spread" && typeof value === "object" && value.type === "expression") {
+            /** @type {import('acorn').SpreadElement} */
+            const spread = {
               type: "SpreadElement",
-              argument: value.expr,
+              start: 0,
+              end: 0,
+              argument: /** @type {import('acorn').Expression} */ (value.expr),
             };
+            return spread;
           }
-          return {
+          /** @type {import('acorn').Property} */
+          const prop = {
             type: "Property",
+            start: 0,
+            end: 0,
             key: needsQuoting(key)
-              ? { type: "Literal", value: key }
-              : { type: "Identifier", name: key },
-            value: value.type === "expression" ? value.expr : { type: "Literal", value },
+              ? /** @type {import('acorn').Literal} */ ({
+                  type: "Literal",
+                  start: 0,
+                  end: 0,
+                  value: key,
+                })
+              : /** @type {import('acorn').Identifier} */ ({
+                  type: "Identifier",
+                  start: 0,
+                  end: 0,
+                  name: key,
+                }),
+            value:
+              typeof value === "object" && value.type === "expression"
+                ? /** @type {import('acorn').Expression} */ (value.expr)
+                : /** @type {import('acorn').Literal} */ ({
+                    type: "Literal",
+                    start: 0,
+                    end: 0,
+                    value: /** @type {string | boolean} */ (value),
+                  }),
             kind: "init",
             method: false,
             shorthand: false,
             computed: false,
           };
+          return prop;
         });
 
-        args.push({
+        /** @type {import('acorn').ObjectExpression} */
+        const objExpr = {
           type: "ObjectExpression",
+          start: 0,
+          end: 0,
           properties,
-        });
+        };
+        args.push(objExpr);
       } else {
         // Normal props
-        args.push({
-          type: "ObjectExpression",
-          properties: propsEntries.map(([key, value]) => ({
+        /** @type {Array<import('acorn').Property | import('acorn').SpreadElement>} */
+        const properties = propsEntries.map(([key, value]) => {
+          /** @type {import('acorn').Property} */
+          const prop = {
             type: "Property",
+            start: 0,
+            end: 0,
             key: needsQuoting(key)
-              ? { type: "Literal", value: key }
-              : { type: "Identifier", name: key },
-            value: value.type === "expression" ? value.expr : { type: "Literal", value },
+              ? /** @type {import('acorn').Literal} */ ({
+                  type: "Literal",
+                  start: 0,
+                  end: 0,
+                  value: key,
+                })
+              : /** @type {import('acorn').Identifier} */ ({
+                  type: "Identifier",
+                  start: 0,
+                  end: 0,
+                  name: key,
+                }),
+            value:
+              typeof value === "object" && value.type === "expression"
+                ? /** @type {import('acorn').Expression} */ (value.expr)
+                : /** @type {import('acorn').Literal} */ ({
+                    type: "Literal",
+                    start: 0,
+                    end: 0,
+                    value: /** @type {string | boolean} */ (value),
+                  }),
             kind: "init",
             method: false,
             shorthand: false,
             computed: false,
-          })),
+          };
+          return prop;
         });
+        /** @type {import('acorn').ObjectExpression} */
+        const objExpr = {
+          type: "ObjectExpression",
+          start: 0,
+          end: 0,
+          properties,
+        };
+        args.push(objExpr);
       }
     } else {
-      args.push({ type: "Literal", value: null });
+      /** @type {import('acorn').Literal} */
+      const nullLiteral = { type: "Literal", start: 0, end: 0, value: null };
+      args.push(nullLiteral);
     }
 
     // Children arguments
@@ -489,12 +675,24 @@ function elementsToAST(node, pragma) {
       args.push(elementsToAST(child, pragma));
     }
 
-    return {
+    /** @type {import('acorn').CallExpression} */
+    const callExpr = {
       type: "CallExpression",
-      callee: { type: "Identifier", name: pragma },
+      start: 0,
+      end: 0,
+      callee: /** @type {import('acorn').Identifier} */ ({
+        type: "Identifier",
+        start: 0,
+        end: 0,
+        name: pragma,
+      }),
       arguments: args,
+      optional: false,
     };
+    return callExpr;
   }
 
-  return { type: "Literal", value: null };
+  /** @type {import('acorn').Literal} */
+  const nullLiteral = { type: "Literal", start: 0, end: 0, value: null };
+  return nullLiteral;
 }