esupgrade 2025.3.3 → 2025.3.4

package/bin/esupgrade.js

@@ -74,7 +74,8 @@ class FileProcessor {
       const result = workerResult.result
 
       if (result.modified) {
-        if (options.check) {
+        // Report changes if check mode or if not writing (dry-run)
+        if (options.check || !options.write) {
           this.#reportChanges(filePath, result.changes)
         }
 
@@ -89,6 +90,7 @@ class FileProcessor {
 
         return { modified: true, changes: result.changes, error: false }
       } else {
+        // Show unmodified files unless in check-only mode
         if (!options.check) {
           console.log(`  ${filePath}`)
         }
@@ -237,6 +239,14 @@ class CLIRunner {
     this.#reportSummary(results, options)
   }
 
+  #formatDetailedSummary(modifiedCount, allChanges, actionVerb) {
+    const transformTypes = new Set(allChanges.map((c) => c.type))
+    const typeCount = transformTypes.size
+    const totalChanges = allChanges.length
+
+    return `${modifiedCount} file${modifiedCount !== 1 ? "s" : ""} ${actionVerb} (${totalChanges} change${totalChanges !== 1 ? "s" : ""}, ${typeCount} type${typeCount !== 1 ? "s" : ""})`
+  }
+
   #reportSummary(results, options) {
     let modifiedCount = 0
     const allChanges = results.flatMap((result) =>
@@ -249,12 +259,12 @@ class CLIRunner {
 
     if (options.check) {
       if (modifiedCount > 0) {
-        const transformTypes = new Set(allChanges.map((c) => c.type))
-        const typeCount = transformTypes.size
-        const totalChanges = allChanges.length
-
         console.log(
-          `${modifiedCount} file${modifiedCount !== 1 ? "s" : ""} need${modifiedCount === 1 ? "s" : ""} upgrading (${totalChanges} change${totalChanges !== 1 ? "s" : ""}, ${typeCount} type${typeCount !== 1 ? "s" : ""})`,
+          this.#formatDetailedSummary(
+            modifiedCount,
+            allChanges,
+            `need${modifiedCount === 1 ? "s" : ""} upgrading`,
+          ),
         )
         if (options.write) {
           console.log("Changes have been written")
@@ -262,12 +272,22 @@ class CLIRunner {
       } else {
         console.log("All files are up to date")
       }
-    } else {
+    } else if (options.write) {
+      // --write without --check
       if (modifiedCount > 0) {
         console.log(`✓ ${modifiedCount} file${modifiedCount !== 1 ? "s" : ""} upgraded`)
       } else {
         console.log("All files are up to date")
       }
+    } else {
+      // Dry-run mode (no --check, no --write)
+      if (modifiedCount > 0) {
+        console.log(
+          this.#formatDetailedSummary(modifiedCount, allChanges, "would be upgraded"),
+        )
+      } else {
+        console.log("All files are up to date")
+      }
     }
 
     // Errors take precedence over --check flag.
@@ -296,14 +316,11 @@ program
       .default("widely-available"),
   )
   .option("--check", "Report which files need upgrading and exit with code 1 if any do")
-  .option(
-    "--write",
-    "Write changes to files (default: true unless only --check is specified)",
-  )
+  .option("--write", "Write changes to files")
   .action(async (files, options) => {
     // Handle check/write options - they are not mutually exclusive
-    // Default: write is true unless ONLY --check is specified (no --write)
-    const shouldWrite = options.write !== undefined ? options.write : !options.check
+    // Default: write is false (read-only mode unless --write is specified)
+    const shouldWrite = options.write || false
     const shouldCheck = options.check || false
 
     const processingOptions = {

package/package.json

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

package/src/widelyAvailable.js

@@ -1,20 +1,267 @@
 /**
- * Transform var to const
+ * Check if a pattern (identifier, destructuring, etc.) contains a specific variable name
+ * @param {import('jscodeshift').JSCodeshift} j - The jscodeshift API
+ * @param {import('jscodeshift').ASTNode | null | undefined} node - The AST node to check
+ * @param {string} varName - The variable name to search for
+ * @returns {boolean} True if the pattern contains the identifier
+ */
+function patternContainsIdentifier(j, node, varName) {
+  if (!node) {
+    return false
+  }
+  if (j.Identifier.check(node)) {
+    return node.name === varName
+  }
+  if (j.ObjectPattern.check(node)) {
+    return node.properties.some(
+      (prop) =>
+        ((j.Property.check(prop) || j.ObjectProperty.check(prop)) &&
+          patternContainsIdentifier(j, prop.value, varName)) ||
+        (j.RestElement.check(prop) &&
+          patternContainsIdentifier(j, prop.argument, varName)),
+    )
+  }
+  if (j.ArrayPattern.check(node)) {
+    return node.elements.some((element) =>
+      patternContainsIdentifier(j, element, varName),
+    )
+  }
+  if (j.AssignmentPattern.check(node)) {
+    return patternContainsIdentifier(j, node.left, varName)
+  }
+  // RestElement is the only remaining valid pattern type
+  return (
+    j.RestElement.check(node) && patternContainsIdentifier(j, node.argument, varName)
+  )
+}
+
+/**
+ * Extract all identifier names from a pattern (handles destructuring)
+ * @param {import('jscodeshift').JSCodeshift} j - The jscodeshift API
+ * @param {import('jscodeshift').ASTNode | null | undefined} pattern - The pattern node to extract identifiers from
+ * @yields {string} Identifier names found in the pattern
+ * @returns {Generator<string, void, unknown>}
+ */
+function* extractIdentifiersFromPattern(j, pattern) {
+  if (!pattern) return
+
+  if (j.Identifier.check(pattern)) {
+    yield pattern.name
+  } else if (j.ObjectPattern.check(pattern)) {
+    for (const prop of pattern.properties) {
+      if (j.Property.check(prop) || j.ObjectProperty.check(prop)) {
+        yield* extractIdentifiersFromPattern(j, prop.value)
+      } else if (j.RestElement.check(prop)) {
+        yield* extractIdentifiersFromPattern(j, prop.argument)
+      }
+    }
+  } else if (j.ArrayPattern.check(pattern)) {
+    for (const element of pattern.elements) {
+      yield* extractIdentifiersFromPattern(j, element)
+    }
+  } else if (j.AssignmentPattern.check(pattern)) {
+    yield* extractIdentifiersFromPattern(j, pattern.left)
+  } else if (j.RestElement.check(pattern)) {
+    yield* extractIdentifiersFromPattern(j, pattern.argument)
+  }
+}
+
+/**
+ * Check if an assignment/update expression is shadowed by a closer variable declaration
+ * @param {import('jscodeshift').JSCodeshift} j - The jscodeshift API
+ * @param {string} varName - The variable name to check
+ * @param {import('jscodeshift').ASTPath} declarationPath - The path to the original declaration
+ * @param {import('jscodeshift').ASTPath} usagePath - The path to the assignment/update expression
+ * @returns {boolean} True if the assignment is shadowed by a closer declaration
+ */
+function isAssignmentShadowed(j, varName, declarationPath, usagePath) {
+  let current = usagePath.parent
+
+  while (current) {
+    if (
+      j.FunctionDeclaration.check(current.node) ||
+      j.FunctionExpression.check(current.node) ||
+      j.ArrowFunctionExpression.check(current.node)
+    ) {
+      // Check function parameters
+      if (current.node.params) {
+        for (const param of current.node.params) {
+          if (patternContainsIdentifier(j, param, varName)) {
+            return true
+          }
+        }
+      }
+
+      // Check for var/let/const declarations in this function
+      const functionBody = current.node.body
+      if (functionBody) {
+        let foundOurDeclaration = false
+        const hasLocalDecl = j(functionBody)
+          .find(j.VariableDeclarator)
+          .some((declPath) => {
+            const declParent = declPath.parent.node
+            if (declParent === declarationPath.node) {
+              foundOurDeclaration = true
+              return false
+            }
+            return patternContainsIdentifier(j, declPath.node.id, varName)
+          })
+
+        // If we found a shadowing declaration (not our own), the assignment is shadowed
+        if (hasLocalDecl) {
+          return true
+        }
+
+        // If we found our declaration in this scope, stop traversing -
+        // the assignment is not shadowed, it belongs to our declaration
+        if (foundOurDeclaration) {
+          return false
+        }
+      }
+    }
+
+    current = current.parent
+  }
+
+  return false
+}
+
+/**
+ * Check if a variable is reassigned after its declaration
+ * @param {import('jscodeshift').JSCodeshift} j - The jscodeshift API
+ * @param {import('jscodeshift').Collection} root - The root AST collection
+ * @param {string} varName - The variable name to check
+ * @param {import('jscodeshift').ASTPath} declarationPath - The path to the variable declaration
+ * @returns {boolean} True if the variable is reassigned
+ */
+function isVariableReassigned(j, root, varName, declarationPath) {
+  let isReassigned = false
+
+  // Check for AssignmentExpression where left side targets the variable
+  root.find(j.AssignmentExpression).forEach((assignPath) => {
+    if (!patternContainsIdentifier(j, assignPath.node.left, varName)) {
+      return
+    }
+
+    if (isAssignmentShadowed(j, varName, declarationPath, assignPath)) {
+      return
+    }
+
+    isReassigned = true
+  })
+
+  if (isReassigned) return true
+
+  // Check for UpdateExpression (++, --)
+  root.find(j.UpdateExpression).forEach((updatePath) => {
+    if (
+      !j.Identifier.check(updatePath.node.argument) ||
+      updatePath.node.argument.name !== varName
+    ) {
+      return
+    }
+
+    if (isAssignmentShadowed(j, varName, declarationPath, updatePath)) {
+      return
+    }
+
+    isReassigned = true
+  })
+
+  return isReassigned
+}
+
+/**
+ * Determine the appropriate kind (const or let) for a declarator
+ * @param {import('jscodeshift').JSCodeshift} j - The jscodeshift API
+ * @param {import('jscodeshift').Collection} root - The root AST collection
+ * @param {import('jscodeshift').VariableDeclarator} declarator - The variable declarator
+ * @param {import('jscodeshift').ASTPath} declarationPath - The path to the variable declaration
+ * @returns {'const' | 'let'} The appropriate variable kind
+ */
+function determineDeclaratorKind(j, root, declarator, declarationPath) {
+  if (j.Identifier.check(declarator.id)) {
+    return isVariableReassigned(j, root, declarator.id.name, declarationPath)
+      ? "let"
+      : "const"
+  }
+
+  // Destructuring pattern - check if any identifier is reassigned
+  for (const varName of extractIdentifiersFromPattern(j, declarator.id)) {
+    if (isVariableReassigned(j, root, varName, declarationPath)) {
+      return "let"
+    }
+  }
+
+  return "const"
+}
+
+/**
+ * Process a single declarator variable declaration
+ * @param {import('jscodeshift').JSCodeshift} j - The jscodeshift API
+ * @param {import('jscodeshift').Collection} root - The root AST collection
+ * @param {import('jscodeshift').ASTPath} path - The path to the variable declaration
+ * @returns {{ modified: boolean, change: { type: string, line: number } | null }}
+ */
+function processSingleDeclarator(j, root, path) {
+  const declarator = path.node.declarations[0]
+  const kind = determineDeclaratorKind(j, root, declarator, path)
+
+  path.node.kind = kind
+
+  const change = path.node.loc
+    ? { type: "varToLetOrConst", line: path.node.loc.start.line }
+    : null
+
+  return { modified: true, change }
+}
+
+/**
+ * Process a multiple declarator variable declaration by splitting into separate declarations
+ * @param {import('jscodeshift').JSCodeshift} j - The jscodeshift API
+ * @param {import('jscodeshift').Collection} root - The root AST collection
+ * @param {import('jscodeshift').ASTPath} path - The path to the variable declaration
+ * @returns {{ modified: boolean, change: { type: string, line: number } | null }}
+ */
+function processMultipleDeclarators(j, root, path) {
+  const declarations = path.node.declarations.map((declarator) => {
+    const kind = determineDeclaratorKind(j, root, declarator, path)
+    return j.variableDeclaration(kind, [declarator])
+  })
+
+  j(path).replaceWith(declarations)
+
+  const change = path.node.loc
+    ? { type: "varToLetOrConst", line: path.node.loc.start.line }
+    : null
+
+  return { modified: true, change }
+}
+
+/**
+ * Transform var to const or let
  * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const
  * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let
+ * @param {import('jscodeshift').JSCodeshift} j - The jscodeshift API
+ * @param {import('jscodeshift').Collection} root - The root AST collection
+ * @returns {{ modified: boolean, changes: Array<{ type: string, line: number }> }}
  */
-export function varToConst(j, root) {
+export function varToLetOrConst(j, root) {
   let modified = false
   const changes = []
 
   root.find(j.VariableDeclaration, { kind: "var" }).forEach((path) => {
-    path.node.kind = "const"
-    modified = true
-    if (path.node.loc) {
-      changes.push({
-        type: "varToConst",
-        line: path.node.loc.start.line,
-      })
+    const isSingleDeclarator = path.node.declarations.length === 1
+
+    const result = isSingleDeclarator
+      ? processSingleDeclarator(j, root, path)
+      : processMultipleDeclarators(j, root, path)
+
+    if (result.modified) {
+      modified = true
+    }
+    if (result.change) {
+      changes.push(result.change)
     }
   })
 

package/tests/cli.test.js

@@ -274,7 +274,11 @@ describe("CLI", () => {
       encoding: "utf8",
     })
 
-    assert.match(result.stdout, /var to const/, "shows var to const changes")
+    assert.match(
+      result.stdout,
+      /var to let or const/,
+      "shows var to let or const changes",
+    )
     assert.equal(result.status, 1, "exits with 1")
   })
 
@@ -357,7 +361,11 @@ describe("CLI", () => {
       encoding: "utf8",
     })
 
-    assert.match(result.stdout, /var to const/, "shows var to const changes")
+    assert.match(
+      result.stdout,
+      /var to let or const/,
+      "shows var to let or const changes",
+    )
     assert.equal(result.status, 1, "exits with 1")
   })
 
@@ -397,6 +405,51 @@ describe("CLI", () => {
     assert.equal(result.status, 1, "exits with 1 on errors without --check")
   })
 
+  test("dry-run mode without flags shows changes but doesn't write", () => {
+    const testFile = path.join(tempDir, "test.js")
+    const originalCode = `var x = 1;`
+    fs.writeFileSync(testFile, originalCode)
+
+    const result = spawnSync(process.execPath, [CLI_PATH, testFile], {
+      encoding: "utf8",
+    })
+
+    assert.equal(
+      fs.readFileSync(testFile, "utf8"),
+      originalCode,
+      "leaves file unchanged",
+    )
+    assert.match(result.stdout, /✗/, "indicates changes would be made")
+    assert.match(
+      result.stdout,
+      /1 file would be upgraded/,
+      "reports 1 file would be upgraded",
+    )
+    assert.equal(result.status, 0, "exits with 0 in dry-run mode")
+  })
+
+  test("dry-run mode exits with 0 when no changes needed", () => {
+    const testFile = path.join(tempDir, "test.js")
+    const originalCode = `const x = 1;`
+    fs.writeFileSync(testFile, originalCode)
+
+    const result = spawnSync(process.execPath, [CLI_PATH, testFile], {
+      encoding: "utf8",
+    })
+
+    assert.equal(
+      fs.readFileSync(testFile, "utf8"),
+      originalCode,
+      "leaves file unchanged",
+    )
+    assert.match(
+      result.stdout,
+      /All files are up to date/,
+      "reports all files up to date",
+    )
+    assert.equal(result.status, 0, "exits with 0")
+  })
+
   test("exit with 1 on errors even with valid files", () => {
     const validFile = path.join(tempDir, "valid.js")
     const invalidFile = path.join(tempDir, "invalid.js")

package/tests/newlyAvailable.test.js

@@ -1,8 +1,8 @@
-import { describe, test } from "node:test"
+import { describe, suite, test } from "node:test"
 import assert from "node:assert/strict"
 import { transform } from "../src/index.js"
 
-describe("newly-available", () => {
+suite("newly-available", () => {
   describe("Promise.try", () => {
     test("transforms resolve call with argument", () => {
       const result = transform(