esupgrade 2025.1.0 → 2025.2.0

package/AGENTS.md

@@ -0,0 +1,3 @@
+When writing code, you MUST ALWAYS follow the [naming-things](https://raw.githubusercontent.com/codingjoe/naming-things/refs/heads/main/README.md) guidlines.
+
+All code must be fully tested with a 100% coverage. Unreachable code must be removed.

package/README.md

@@ -93,6 +93,21 @@ For more information about Baseline browser support, visit [web.dev/baseline][ba
 +const message = `You have ${count} items`;
 ```
 
+#### Traditional `for` loops → [`for...of` loops][mdn-for-of]
+
+```diff
+-for (let i = 0; i < items.length; i++) {
+-  const item = items[i];
+-  console.log(item);
+-}
++for (const item of items) {
++  console.log(item);
++}
+```
+
+> [!NOTE]
+> Transformations are limited to loops that start at 0, increment by 1, and where the index variable is not used in the loop body.
+
 #### `Array.from().forEach()` → [`for...of` loops][mdn-for-of]
 
 ```diff
@@ -104,6 +119,29 @@ For more information about Baseline browser support, visit [web.dev/baseline][ba
 +}
 ```
 
+#### DOM `forEach()` → [`for...of` loops][mdn-for-of]
+
+```diff
+-document.querySelectorAll('.item').forEach(item => {
+-  item.classList.add('active');
+-});
++for (const item of document.querySelectorAll('.item')) {
++  item.classList.add('active');
++}
+```
+
+Supports:
+
+- `document.querySelectorAll()`
+- `document.getElementsByTagName()`
+- `document.getElementsByClassName()`
+- `document.getElementsByName()`
+- `window.frames`
+
+> [!NOTE]
+> Transformations limited to inline arrow or function expressions with block statement bodies.
+> Callbacks with index parameters or expression bodies are not transformed.
+
 #### `Array.from()` → [Array spread [...]][mdn-spread]
 
 ```diff
@@ -136,6 +174,15 @@ For more information about Baseline browser support, visit [web.dev/baseline][ba
 +const withItem = [...array, item];
 ```
 
+#### `Math.pow()` → [Exponentiation operator \*\*][mdn-exponentiation]
+
+```diff
+-const result = Math.pow(2, 3);
+-const area = Math.PI * Math.pow(radius, 2);
++const result = 2 ** 3;
++const area = Math.PI * radius ** 2;
+```
+
 #### Function expressions → [Arrow functions][mdn-arrow-functions]
 
 ```diff
@@ -174,6 +221,7 @@ For more information about Baseline browser support, visit [web.dev/baseline][ba
 [baseline]: https://web.dev/baseline/
 [mdn-arrow-functions]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions
 [mdn-const]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const
+[mdn-exponentiation]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Exponentiation
 [mdn-for-of]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of
 [mdn-let]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let
 [mdn-promise-try]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/try

package/bin/esupgrade.js

@@ -98,50 +98,52 @@ function processFile(filePath, options) {
 
     if (result.modified) {
       if (options.check) {
-        console.log(`✗ ${filePath}`)
+        // Group changes by type for summary
+        const changesByType = {}
         if (result.changes && result.changes.length > 0) {
-          // Group changes by type
-          const changesByType = {}
-
           for (const change of result.changes) {
             if (!changesByType[change.type]) {
-              changesByType[change.type] = []
+              changesByType[change.type] = 0
             }
-            changesByType[change.type].push(change.line)
+            changesByType[change.type]++
           }
+        }
 
-          for (const [type, lines] of Object.entries(changesByType)) {
-            const uniqueLines = [...new Set(lines)].sort((a, b) => a - b)
+        const transformations = Object.keys(changesByType)
+          .map((type) => {
             const displayName = type
               .replace(/([A-Z])/g, " $1")
               .trim()
               .toLowerCase()
-            console.log(
-              `  - ${displayName} (line${uniqueLines.length > 1 ? "s" : ""}: ${uniqueLines.join(", ")})`,
-            )
-          }
+            return displayName
+          })
+          .join(", ")
+
+        console.log(`✗ ${filePath}`)
+        if (transformations) {
+          console.log(`  ${transformations}`)
         }
       }
 
       if (options.write) {
         fs.writeFileSync(filePath, result.code, "utf8")
         if (!options.check) {
-          console.log(`✓ Upgraded: ${filePath}`)
+          console.log(`✓ ${filePath}`)
         } else {
-          console.log(`  ✓ Changes written to file`)
+          console.log(`  ✓ written`)
         }
       }
 
-      return true
+      return { modified: true, changes: result.changes }
     } else {
       if (!options.check) {
-        console.log(`  No changes: ${filePath}`)
+        console.log(`  ${filePath}`)
       }
-      return false
+      return { modified: false, changes: [] }
     }
   } catch (error) {
-    console.error(`Error processing ${filePath}: ${error.message}`)
-    return false
+    console.error(`✗ Error: ${filePath}: ${error.message}`)
+    return { modified: false, changes: [] }
   }
 }
 
@@ -153,27 +155,42 @@ function processFiles(patterns, options) {
     process.exit(0)
   }
 
-  console.log(`Processing ${files.length} file(s) with baseline: ${options.baseline}\n`)
-
   let modifiedCount = 0
+  const allChanges = []
+
   for (const file of files) {
-    if (processFile(file, options)) {
+    const result = processFile(file, options)
+    if (result.modified) {
       modifiedCount++
+      allChanges.push(...result.changes)
     }
   }
 
   // Summary
-  console.log("")
-  if (modifiedCount > 0) {
-    if (options.write && options.check) {
-      console.log(`Summary: ${modifiedCount} file(s) upgraded`)
-    } else if (options.write) {
-      console.log(`Summary: ${modifiedCount} file(s) upgraded`)
+  if (options.check) {
+    console.log("")
+    if (modifiedCount > 0) {
+      // Count unique transformation types
+      const transformTypes = new Set(allChanges.map((c) => c.type))
+      const typeCount = transformTypes.size
+      const totalChanges = allChanges.length
+
+      console.log(
+        `${modifiedCount} file(s) need upgrading (${totalChanges} change${totalChanges !== 1 ? "s" : ""}, ${typeCount} type${typeCount !== 1 ? "s" : ""})`,
+      )
+      if (options.write) {
+        console.log("Changes have been written")
+      }
     } else {
-      console.log(`Summary: ${modifiedCount} file(s) need upgrading`)
+      console.log("All files are up to date")
     }
   } else {
-    console.log("Summary: All files are already modern")
+    console.log("")
+    if (modifiedCount > 0) {
+      console.log(`✓ ${modifiedCount} file(s) upgraded`)
+    } else {
+      console.log("All files are up to date")
+    }
   }
 
   // Exit with code 1 if --check specified and there were changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esupgrade",
-  "version": "2025.1.0",
+  "version": "2025.2.0",
   "description": "Auto-upgrade your JavaScript syntax",
   "type": "module",
   "main": "src/index.js",

package/src/widelyAvailable.js

@@ -335,3 +335,407 @@ export function arrayFromToSpread(j, root) {
 
   return { modified, changes }
 }
+
+/**
+ * Transform Math.pow() to exponentiation operator (**)
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Exponentiation
+ */
+export function mathPowToExponentiation(j, root) {
+  let modified = false
+  const changes = []
+
+  root
+    .find(j.CallExpression, {
+      callee: {
+        type: "MemberExpression",
+        object: { name: "Math" },
+        property: { name: "pow" },
+      },
+    })
+    .filter((path) => {
+      // Must have exactly 2 arguments (base and exponent)
+      return path.node.arguments.length === 2
+    })
+    .forEach((path) => {
+      const node = path.node
+      const [base, exponent] = node.arguments
+
+      // Create exponentiation expression
+      const expExpression = j.binaryExpression("**", base, exponent)
+
+      j(path).replaceWith(expExpression)
+
+      modified = true
+      if (node.loc) {
+        changes.push({
+          type: "mathPowToExponentiation",
+          line: node.loc.start.line,
+        })
+      }
+    })
+
+  return { modified, changes }
+}
+
+/**
+ * Transform traditional for loops to for...of where safe
+ * Converts: for (let i = 0; i < arr.length; i++) { const item = arr[i]; ... }
+ * To: for (const item of arr) { ... }
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of
+ */
+export function forLoopToForOf(j, root) {
+  let modified = false
+  const changes = []
+
+  root
+    .find(j.ForStatement)
+    .filter((path) => {
+      const node = path.node
+
+      // Check init: must be let/const i = 0
+      if (!j.VariableDeclaration.check(node.init)) {
+        return false
+      }
+      if (node.init.declarations.length !== 1) {
+        return false
+      }
+      const initDeclarator = node.init.declarations[0]
+      if (!j.Identifier.check(initDeclarator.id)) {
+        return false
+      }
+      const indexVar = initDeclarator.id.name
+      if (!j.Literal.check(initDeclarator.init) || initDeclarator.init.value !== 0) {
+        return false
+      }
+
+      // Check test: must be i < arr.length
+      if (!j.BinaryExpression.check(node.test)) {
+        return false
+      }
+      if (node.test.operator !== "<") {
+        return false
+      }
+      if (!j.Identifier.check(node.test.left) || node.test.left.name !== indexVar) {
+        return false
+      }
+      if (!j.MemberExpression.check(node.test.right)) {
+        return false
+      }
+      if (
+        !j.Identifier.check(node.test.right.property) ||
+        node.test.right.property.name !== "length"
+      ) {
+        return false
+      }
+      if (!j.Identifier.check(node.test.right.object)) {
+        return false
+      }
+      const arrayVar = node.test.right.object.name
+
+      // Check update: must be i++ or ++i
+      if (j.UpdateExpression.check(node.update)) {
+        if (
+          !j.Identifier.check(node.update.argument) ||
+          node.update.argument.name !== indexVar ||
+          node.update.operator !== "++"
+        ) {
+          return false
+        }
+      } else {
+        return false
+      }
+
+      // Check body: must be a block statement
+      if (!j.BlockStatement.check(node.body)) {
+        return false
+      }
+
+      // Look for first statement that assigns arr[i] to a variable
+      if (node.body.body.length === 0) {
+        return false
+      }
+
+      const firstStmt = node.body.body[0]
+      if (!j.VariableDeclaration.check(firstStmt)) {
+        return false
+      }
+      if (firstStmt.declarations.length !== 1) {
+        return false
+      }
+      const varDeclarator = firstStmt.declarations[0]
+      if (!j.Identifier.check(varDeclarator.id)) {
+        return false
+      }
+      if (!j.MemberExpression.check(varDeclarator.init)) {
+        return false
+      }
+      if (
+        !j.Identifier.check(varDeclarator.init.object) ||
+        varDeclarator.init.object.name !== arrayVar
+      ) {
+        return false
+      }
+      if (
+        !j.Identifier.check(varDeclarator.init.property) ||
+        varDeclarator.init.property.name !== indexVar ||
+        varDeclarator.init.computed !== true
+      ) {
+        return false
+      }
+
+      // Check that the index variable is not used elsewhere in the body
+      const bodyWithoutFirst = node.body.body.slice(1)
+      let indexVarUsed = false
+
+      // Recursively check if identifier is used in AST nodes
+      const checkNode = (astNode) => {
+        if (!astNode || typeof astNode !== "object") return
+
+        if (astNode.type === "Identifier" && astNode.name === indexVar) {
+          indexVarUsed = true
+          return
+        }
+
+        // Traverse all properties
+        for (const key in astNode) {
+          if (
+            key === "loc" ||
+            key === "start" ||
+            key === "end" ||
+            key === "tokens" ||
+            key === "comments"
+          )
+            continue
+          const value = astNode[key]
+          if (Array.isArray(value)) {
+            value.forEach(checkNode)
+          } else if (value && typeof value === "object") {
+            checkNode(value)
+          }
+        }
+      }
+
+      bodyWithoutFirst.forEach(checkNode)
+
+      if (indexVarUsed) {
+        return false
+      }
+
+      return true
+    })
+    .forEach((path) => {
+      const node = path.node
+      const arrayVar = node.test.right.object.name
+      const itemVar = node.body.body[0].declarations[0].id.name
+      const itemKind = node.body.body[0].kind
+
+      // Create new body without the first declaration
+      const newBody = j.blockStatement(node.body.body.slice(1))
+
+      // Create for...of loop
+      const forOfLoop = j.forOfStatement(
+        j.variableDeclaration(itemKind, [j.variableDeclarator(j.identifier(itemVar))]),
+        j.identifier(arrayVar),
+        newBody,
+      )
+
+      j(path).replaceWith(forOfLoop)
+
+      modified = true
+      if (node.loc) {
+        changes.push({
+          type: "forLoopToForOf",
+          line: node.loc.start.line,
+        })
+      }
+    })
+
+  return { modified, changes }
+}
+
+/**
+ * Transform iterables' forEach() to for...of loop
+ * Handles DOM APIs like querySelectorAll, getElementsBy*, etc. and other known iterables
+ * Only transforms when forEach callback is declared inline with a function body (block statement)
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of
+ */
+export function iterableForEachToForOf(j, root) {
+  let modified = false
+  const changes = []
+
+  // Define known iterable-returning methods by their object/context
+  const knownIterableMethods = {
+    document: [
+      "querySelectorAll",
+      "getElementsByTagName",
+      "getElementsByClassName",
+      "getElementsByName",
+    ],
+  }
+
+  // Define known iterable properties
+  const knownIterableProperties = {
+    window: ["frames"],
+  }
+
+  root
+    .find(j.CallExpression)
+    .filter((path) => {
+      const node = path.node
+      // Check if this is a forEach call
+      if (
+        !j.MemberExpression.check(node.callee) ||
+        !j.Identifier.check(node.callee.property) ||
+        node.callee.property.name !== "forEach"
+      ) {
+        return false
+      }
+
+      const object = node.callee.object
+
+      // Check if this is a property access pattern like window.frames
+      if (j.MemberExpression.check(object) && !j.CallExpression.check(object)) {
+        const objectName = j.Identifier.check(object.object) ? object.object.name : null
+        const propertyName = j.Identifier.check(object.property)
+          ? object.property.name
+          : null
+
+        if (
+          objectName &&
+          propertyName &&
+          knownIterableProperties[objectName] &&
+          knownIterableProperties[objectName].includes(propertyName)
+        ) {
+          // This is a valid iterable property like window.frames - continue to callback check
+        } else {
+          // Not a known iterable property
+          return false
+        }
+      }
+      // Check for method call patterns like document.querySelectorAll()
+      else if (j.CallExpression.check(object)) {
+        // Check if it's a member expression (e.g., document.querySelectorAll)
+        if (!j.MemberExpression.check(object.callee)) {
+          return false
+        }
+
+        // Get the method name
+        const methodName = j.Identifier.check(object.callee.property)
+          ? object.callee.property.name
+          : null
+
+        if (!methodName) {
+          return false
+        }
+
+        // Verify the object is document only
+        const callerObject = object.callee.object
+        if (j.Identifier.check(callerObject)) {
+          const objectName = callerObject.name
+          // Only allow document
+          if (objectName !== "document") {
+            return false
+          }
+          // Verify method belongs to document
+          if (!knownIterableMethods.document.includes(methodName)) {
+            return false
+          }
+        }
+        // Handle cases like document.getElementById('x').querySelectorAll()
+        // Only allow these from document-originating chains
+        else if (
+          j.MemberExpression.check(callerObject) ||
+          j.CallExpression.check(callerObject)
+        ) {
+          // Check if this eventually chains from document
+          const isFromDocument = (node) => {
+            if (j.Identifier.check(node)) {
+              return node.name === "document"
+            }
+            if (j.MemberExpression.check(node)) {
+              return isFromDocument(node.object)
+            }
+            if (j.CallExpression.check(node)) {
+              if (j.MemberExpression.check(node.callee)) {
+                return isFromDocument(node.callee.object)
+              }
+            }
+            return false
+          }
+
+          if (!isFromDocument(callerObject)) {
+            return false
+          }
+
+          // Verify the method is valid for document
+          if (!knownIterableMethods.document.includes(methodName)) {
+            return false
+          }
+        } else {
+          return false
+        }
+      } else {
+        return false
+      }
+
+      // Check that forEach has a callback argument
+      if (node.arguments.length === 0) {
+        return false
+      }
+
+      const callback = node.arguments[0]
+      // Only transform if callback is an inline function (arrow or function expression)
+      if (
+        !j.ArrowFunctionExpression.check(callback) &&
+        !j.FunctionExpression.check(callback)
+      ) {
+        return false
+      }
+
+      // Only transform if the callback has a block statement body (with braces)
+      // Arrow functions with expression bodies (e.g., item => item.value) should NOT be transformed
+      if (!j.BlockStatement.check(callback.body)) {
+        return false
+      }
+
+      // Only transform if callback uses only the first parameter (element)
+      // Don't transform if it uses index or array parameters
+      const params = callback.params
+      if (params.length !== 1) {
+        return false
+      }
+
+      return true
+    })
+    .forEach((path) => {
+      const node = path.node
+      const iterable = node.callee.object
+      const callback = node.arguments[0]
+
+      const itemParam = callback.params[0]
+      const body = callback.body
+
+      // Create for...of loop
+      const forOfLoop = j.forOfStatement(
+        j.variableDeclaration("const", [j.variableDeclarator(itemParam)]),
+        iterable,
+        body,
+      )
+
+      // Replace the expression statement containing the forEach call
+      const statement = path.parent
+      if (j.ExpressionStatement.check(statement.node)) {
+        j(statement).replaceWith(forOfLoop)
+
+        modified = true
+        if (node.loc) {
+          changes.push({
+            type: "iterableForEachToForOf",
+            line: node.loc.start.line,
+          })
+        }
+      }
+    })
+
+  return { modified, changes }
+}