esupgrade 2025.3.3 → 2025.4.0

package/.github/copilot-instructions.md

@@ -0,0 +1,18 @@
+When writing code, you MUST ALWAYS follow the [naming-things](https://raw.githubusercontent.com/codingjoe/naming-things/refs/heads/main/README.md) guidelines.
+
+All code must be fully tested with a 100% coverage. Unreachable code must be removed.
+
+All transformers must be documented in the README.md.
+
+Use class syntax for all object-oriented code.
+Use named functions instead of anonymous functions whenever possible.
+Use `#` for private methods.
+
+Avoid overly complex functions. Break them into smaller functions if necessary.
+
+Write docstrings with jsdoc type annotations for all functions, classes, and methods.
+Docstrings should be written in present tense imperative mood.
+Docstrings must describe the external behavior of the function, class, or method.
+Docstrings should avoid redundant phrases like "This function" or "This method".
+Class docstrings must not repeat the class name or start with a verb since they don't do anything themselves.
+Avoid code comments unless they describe behavior of 3rd party code or complex algorithms.

package/README.md

@@ -212,6 +212,47 @@ Supports:
 > [!NOTE]
 > Functions using `this`, `arguments`, or `super` are not converted to preserve semantics.
 
+#### Constructor functions → [Classes][mdn-classes]
+
+```diff
+-function Person(name, age) {
+-  this.name = name;
+-  this.age = age;
+-}
+-
+-Person.prototype.greet = function() {
+-  return 'Hello, I am ' + this.name;
+-};
+-
+-Person.prototype.getAge = function() {
+-  return this.age;
+-};
++class Person {
++  constructor(name, age) {
++    this.name = name;
++    this.age = age;
++  }
++
++  greet() {
++    return 'Hello, I am ' + this.name;
++  }
++
++  getAge() {
++    return this.age;
++  }
++}
+```
+
+> [!NOTE]
+> Transforms constructor functions (both function declarations and variable declarations) that meet these criteria:
+>
+> - Function name starts with an uppercase letter
+> - Constructor bodies are limited to simple statements (variable declarations and expression statements)
+> - No control flow statements (`if`, `for`, `while`, `return`, `throw`, etc.) in constructor body
+> - At least one prototype method is defined
+> - Prototype methods must be function expressions (not arrow functions)
+> - Prototype object literals with getters, setters, or computed properties are skipped
+
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://web-platform-dx.github.io/web-features/assets/img/baseline-newly-word-dark.svg">
   <source media="(prefers-color-scheme: light)" srcset="https://web-platform-dx.github.io/web-features/assets/img/baseline-newly-word.svg">
@@ -258,6 +299,7 @@ Furthermore, esupgrade supports JavaScript, TypeScript, and more, while lebab is
 [calver]: https://calver.org/
 [django-upgrade]: https://github.com/adamchainz/django-upgrade
 [mdn-arrow-functions]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions
+[mdn-classes]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes
 [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-in]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...in

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.4.0",
   "description": "Auto-upgrade your JavaScript syntax",
   "type": "module",
   "main": "src/index.js",