esupgrade 2025.20.0 → 2025.21.0

package/.github/agents/superjoe.agent.md

@@ -5,12 +5,12 @@ name: SuperJoe
 description: CodingJoe's digital clone following his coding guidelines and best practices.
 ---
 
-
 # SuperJoe
 
 ## Planning
 
 You MUST ALWAYS follow the `naming-things` guidelines. Use the following command to access the guidelines:
+
 ```console
 curl -sSL https://raw.githubusercontent.com/codingjoe/naming-things/refs/heads/main/README.md | head -n 500
 ```
@@ -44,7 +44,6 @@ Avoid functions or other code inside functions.
 Avoid if-statements in favor of switch/match-statements or polymorphism.
 Do not assign names to objects which are returned in the next line.
 
-
 ## Python
 
 Follow PEP 8 guidelines for code style.

package/.github/workflows/ci.yml

@@ -28,7 +28,7 @@ jobs:
           node-version-file: package.json
       - run: npm ci
       - run: node --test --experimental-test-coverage --test-reporter=spec --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=lcov.info
-      - uses: codecov/codecov-action@v6
+      - uses: codecov/codecov-action@v7
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           flags: javascript

package/.pre-commit-config.yaml

@@ -18,10 +18,10 @@ repos:
     hooks:
       - id: mdformat
         additional_dependencies:
+          - mdformat-front-matters
           - mdformat-footnote
           - mdformat-gfm
           - mdformat-gfm-alerts
-        exclude: '.github/agents/'
   - repo: https://github.com/google/yamlfmt
     rev: v0.21.0
     hooks:
@@ -32,7 +32,7 @@ repos:
       - id: write-good
         args: [--no-passive]
   - repo: https://github.com/pre-commit/mirrors-eslint
-    rev: v10.4.0
+    rev: v10.4.1
     hooks:
       - id: eslint
         args: ["--fix"]

package/README.md

@@ -10,10 +10,14 @@
 
 Keeping your JavaScript and TypeScript code up to date with full browser compatibility.
 
+## Sponsors
+
+[![Sponsors](https://django.the-box.sh/sponsors/codingjoe/esupgrade.svg)](https://github.com/sponsors/codingjoe)
+
 ## Usage
 
 esupgrade is safe and meant to be used automatically on your codebase.
-We recommend integrating it into your development workflow using [pre-commit].
+We recommend integrating it into your development workflow using [pre-commit] or [husky].
 
 To try it out on a repository without writing changes, run:
 
@@ -40,6 +44,15 @@ repos:
 pre-commit run esupgrade --all-files
 ```
 
+### Husky
+
+Assuming Husky is already initialized and `.husky/pre-commit` already contains `set -e`, append:
+
+```bash
+echo "git diff --cached --name-only --diff-filter=ACMR -z -- '*.js' '*.jsx' '*.ts' '*.tsx' '*.mjs' '*.cjs' | xargs -0 sh -c 'test \"\$#\" -eq 0 && exit 0; npx esupgrade -- \"\$@\"' sh" >> .husky/pre-commit
+echo "git diff --cached --name-only --diff-filter=ACMR -z -- '*.js' '*.jsx' '*.ts' '*.tsx' '*.mjs' '*.cjs' | xargs -0 sh -c 'test \"\$#\" -eq 0 && exit 0; git add -- \"\$@\"' sh" >> .husky/pre-commit
+```
+
 ### CLI
 
 ```bash
@@ -220,12 +233,21 @@ Supports:
 ```diff
 -const budget = 1000000;
 -const maxUsers = 1000000n;
+-const permission = 0o1234567;
+-const mask = 0xabcdef;
+-const flags = 0b1010000111000011;
+-const ratio = 100000.25;
+-const large = 1e100000;
 +const budget = 1_000_000;
 +const maxUsers = 1_000_000n;
++const permission = 0o1_234_567;
++const mask = 0xab_cd_ef;
++const flags = 0b10100001_11000011;
++const ratio = 100_000.25;
++const large = 1e100_000;
 ```
 
-esupgrade transforms decimal integer and bigint literals with at least five digits.
-Fractional, exponential, hexadecimal, octal, binary, and already formatted literals are left unchanged.
+Decimal and octal numerals are grouped by triplets; hex and binary by byte.
 
 #### `Array.slice(0)` → [Array spread [...]][mdn-spread]
 
@@ -380,6 +402,7 @@ Transforms constructor functions (both function declarations and variable declar
 
 - Function name starts with an uppercase letter
 - At least one prototype method is defined
+- Prototype methods are matched only to constructors declared in the current or an ancestor lexical scope (never sibling or child scopes)
 - Prototype methods using `this` in arrow functions are skipped
 - Prototype object literals with getters, setters, or computed properties are skipped
 
@@ -734,6 +757,7 @@ Furthermore, esupgrade supports JavaScript, TypeScript, and more, while lebab is
 [baseline]: https://web.dev/baseline/
 [calver]: https://calver.org/
 [django-upgrade]: https://github.com/adamchainz/django-upgrade
+[husky]: https://typicode.github.io/husky/
 [mdn-arrow-functions]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions
 [mdn-async-await]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function
 [mdn-at]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/at

package/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: esupgrade
+description: Auto-update JavaScript and TypeScript syntax to new ECMAScript features based on browser support.
+---
+
+Use the CLI with `npx` on files or directories:
+
+```console
+npx esupgrade [--baseline <newly-available|widely-available>] [--check] [--write] <files-or-directories>
+```
+
+- Use `--check` to preview changes and fail when updates are needed.
+- Use `--write` to apply updates in place.
+- Use `--baseline` to choose `newly-available` or `widely-available` (default).

package/package.json

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

package/src/widelyAvailable/constructorToClass.js

@@ -1,33 +1,67 @@
 import { default as j } from "jscodeshift"
 import { NodeTest } from "../types.js"
 
-/**
- * Transform old-school constructor functions with prototype methods to ES6 class
- * syntax.
- *
- * @param {import("jscodeshift").Collection} root - The root AST collection
- * @returns {boolean} True if code was modified
- * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes
- */
-export function constructorToClass(root) {
-  function findConstructors(root) {
-    const constructors = new Map()
-
-    root.find(j.FunctionDeclaration).forEach((path) => {
-      if (
-        !new NodeTest(path.node.id).isConstructorName() ||
-        !new NodeTest(path.node.body).hasSimpleConstructorBody()
-      ) {
-        return
-      }
+function getDeclarationScope(path) {
+  return j.FunctionDeclaration.check(path.node)
+    ? (path.scope.parent ?? path.scope)
+    : path.scope
+}
 
-      constructors.set(path.node.id.name, {
-        declaration: path,
-        prototypeMethods: [],
-      })
-    })
+function addConstructor(constructorsByScope, constructorName, declarationPath) {
+  const scopeNode = getDeclarationScope(declarationPath).path.node
+  const constructorsInScope = constructorsByScope.get(scopeNode) ?? new Map()
+
+  if (constructorsInScope.has(constructorName)) {
+    constructorsInScope.set(constructorName, null)
+    constructorsByScope.set(scopeNode, constructorsInScope)
+    return
+  }
+
+  const constructorInfo = {
+    constructorName,
+    declaration: declarationPath,
+    prototypeMethods: [],
+  }
+
+  constructorsInScope.set(constructorName, constructorInfo)
+  constructorsByScope.set(scopeNode, constructorsInScope)
+}
+
+function getConstructor(constructorsByScope, path, constructorName) {
+  let activeScope = path.scope
 
-    root.find(j.VariableDeclaration).forEach((path) => {
+  while (activeScope) {
+    const constructorsInScope = constructorsByScope.get(activeScope.path.node)
+    const hasConstructorInScope = constructorsInScope?.has(constructorName)
+
+    if (hasConstructorInScope) {
+      return constructorsInScope.get(constructorName)
+    }
+
+    activeScope = activeScope.parent
+  }
+
+  return null
+}
+
+function findConstructors(root) {
+  const constructorsByScope = new Map()
+
+  root.find(j.FunctionDeclaration).forEach((path) => {
+    if (
+      !new NodeTest(path.node.id).isConstructorName() ||
+      !new NodeTest(path.node.body).hasSimpleConstructorBody()
+    ) {
+      return
+    }
+
+    addConstructor(constructorsByScope, path.node.id.name, path)
+  })
+
+  root
+    .find(j.VariableDeclaration)
+    .filter((path) => path.node.declarations.length === 1)
+    .forEach((path) => {
       path.node.declarations.forEach((declarator) => {
         if (
           !new NodeTest(declarator.id).isConstructorName() ||
@@ -37,153 +71,166 @@ export function constructorToClass(root) {
           return
         }
 
-        constructors.set(declarator.id.name, {
-          declaration: path,
-          prototypeMethods: [],
-        })
+        addConstructor(constructorsByScope, declarator.id.name, path)
       })
     })
 
-    return constructors
-  }
+  return constructorsByScope
+}
 
-  /**
-   * Find and associate prototype methods with constructors.
-   *
-   * @param {import("jscodeshift").Collection} root - The root AST collection.
-   * @param {Map<
-   *   string,
-   *   { declaration: import("ast-types").NodePath; prototypeMethods: any[] }
-   * >} constructors
-   *   - Map of constructors.
-   */
-  function findPrototypeMethods(root, constructors) {
-    // Pattern 1: ConstructorName.prototype.methodName = ...
-    root
-      .find(j.ExpressionStatement)
-      .filter(({ node }) => {
-        if (!j.AssignmentExpression.check(node.expression)) {
-          return false
-        }
+/**
+ * Find and associate prototype methods with constructors.
+ *
+ * @param {import("jscodeshift").Collection} root - The root AST collection.
+ * @param {Map<
+ *   object,
+ *   Map<
+ *     string,
+ *     {
+ *       constructorName: string
+ *       declaration: import("ast-types").NodePath
+ *       prototypeMethods: any[]
+ *     }
+ *   >
+ * >} constructorsByScope
+ *   - Map of constructors grouped by lexical scope.
+ */
+function findPrototypeMethods(root, constructorsByScope) {
+  // Pattern 1: ConstructorName.prototype.methodName = ...
+  root.find(j.ExpressionStatement).forEach((path) => {
+    const { node } = path
+
+    if (!j.AssignmentExpression.check(node.expression)) {
+      return
+    }
+
+    const assignment = node.expression
+    const left = assignment.left
+
+    if (
+      !j.MemberExpression.check(left) ||
+      !j.MemberExpression.check(left.object) ||
+      !j.Identifier.check(left.object.object) ||
+      !j.Identifier.check(left.object.property) ||
+      left.object.property.name !== "prototype" ||
+      !j.Identifier.check(left.property)
+    ) {
+      return
+    }
+
+    const constructorName = left.object.object.name
+    const constructorInfo = getConstructor(constructorsByScope, path, constructorName)
+
+    if (!constructorInfo) {
+      return
+    }
+
+    const methodName = left.property.name
+    const methodValue = assignment.right
+
+    if (!new NodeTest(methodValue).canBeClassMethod()) {
+      return
+    }
+
+    constructorInfo.prototypeMethods.push({
+      path,
+      methodName,
+      methodValue,
+    })
+  })
 
-        const assignment = node.expression
-        const left = assignment.left
+  // Pattern 2: ConstructorName.prototype = { methodName: function() {...}, ... }
+  root.find(j.ExpressionStatement).forEach((path) => {
+    const { node } = path
 
-        if (
-          !j.MemberExpression.check(left) ||
-          !j.MemberExpression.check(left.object) ||
-          !j.Identifier.check(left.object.object) ||
-          !j.Identifier.check(left.object.property) ||
-          left.object.property.name !== "prototype" ||
-          !j.Identifier.check(left.property)
-        ) {
-          return false
-        }
+    if (!j.AssignmentExpression.check(node.expression)) {
+      return
+    }
 
-        const constructorName = left.object.object.name
-        return constructors.has(constructorName)
-      })
-      .forEach((path) => {
-        const assignment = path.node.expression
-        const left = assignment.left
-        const constructorName = left.object.object.name
-        const methodName = left.property.name
-        const methodValue = assignment.right
-
-        if (!new NodeTest(methodValue).canBeClassMethod()) {
-          return
-        }
+    const assignment = node.expression
+    const left = assignment.left
 
-        constructors.get(constructorName).prototypeMethods.push({
-          path,
-          methodName,
-          methodValue,
-        })
-      })
+    if (
+      !j.MemberExpression.check(left) ||
+      !j.Identifier.check(left.object) ||
+      !j.Identifier.check(left.property) ||
+      left.property.name !== "prototype"
+    ) {
+      return
+    }
 
-    // Pattern 2: ConstructorName.prototype = { methodName: function() {...}, ... }
-    root
-      .find(j.ExpressionStatement)
-      .filter(({ node }) => {
-        if (!j.AssignmentExpression.check(node.expression)) {
-          return false
-        }
+    const constructorName = left.object.name
+    const constructorInfo = getConstructor(constructorsByScope, path, constructorName)
 
-        const assignment = node.expression
-        const left = assignment.left
+    if (!constructorInfo) {
+      return
+    }
 
-        if (
-          !j.MemberExpression.check(left) ||
-          !j.Identifier.check(left.object) ||
-          !j.Identifier.check(left.property) ||
-          left.property.name !== "prototype"
-        ) {
-          return false
-        }
+    const methodValue = assignment.right
 
-        const constructorName = left.object.name
-        return constructors.has(constructorName)
-      })
-      .forEach((path) => {
-        const assignment = path.node.expression
-        const left = assignment.left
-        const constructorName = left.object.name
-        const methodValue = assignment.right
+    if (!j.ObjectExpression.check(methodValue)) {
+      return
+    }
 
-        if (!j.ObjectExpression.check(methodValue)) {
-          return
-        }
+    methodValue.properties.forEach((prop) => {
+      if (!j.Property.check(prop) && !j.ObjectProperty.check(prop)) {
+        return
+      }
+
+      if (prop.computed) {
+        return
+      }
+
+      let methodName
+      if (j.Identifier.check(prop.key)) {
+        methodName = prop.key.name
+      } else {
+        return
+      }
+
+      if (!new NodeTest(prop.value).canBeClassMethod()) {
+        return
+      }
 
-        methodValue.properties.forEach((prop) => {
-          if (!j.Property.check(prop) && !j.ObjectProperty.check(prop)) {
-            return
-          }
-
-          if (prop.computed) {
-            return
-          }
-
-          let methodName
-          if (j.Identifier.check(prop.key)) {
-            methodName = prop.key.name
-          } else {
-            return
-          }
-
-          if (!new NodeTest(prop.value).canBeClassMethod()) {
-            return
-          }
-
-          constructors.get(constructorName).prototypeMethods.push({
-            path,
-            methodName,
-            methodValue: prop.value,
-            isObjectLiteral: true,
-          })
-        })
+      constructorInfo.prototypeMethods.push({
+        path,
+        methodName,
+        methodValue: prop.value,
+        isObjectLiteral: true,
       })
-  }
+    })
+  })
+}
+
+/**
+ * Transform constructors and their prototype methods to class syntax.
+ *
+ * @param {import("jscodeshift").Collection} root - The root AST collection.
+ * @param {Map<
+ *   object,
+ *   Map<
+ *     string,
+ *     {
+ *       constructorName: string
+ *       declaration: import("ast-types").NodePath
+ *       prototypeMethods: any[]
+ *     }
+ *   >
+ * >} constructorsByScope
+ *   - Map of constructors grouped by lexical scope.
+ *
+ * @returns {boolean} True if code was modified.
+ */
+function transformConstructorsToClasses(root, constructorsByScope) {
+  let modified = false
 
-  /**
-   * Transform constructors and their prototype methods to class syntax.
-   *
-   * @param {import("jscodeshift").Collection} root - The root AST collection.
-   * @param {Map<
-   *   string,
-   *   { declaration: import("ast-types").NodePath; prototypeMethods: any[] }
-   * >} constructors
-   *   - Map of constructors.
-   *
-   * @returns {boolean} True if code was modified.
-   */
-  function transformConstructorsToClasses(root, constructors) {
-    let modified = false
-
-    constructors.forEach((info, constructorName) => {
-      if (info.prototypeMethods.length === 0) {
+  constructorsByScope.forEach((constructors) => {
+    constructors.forEach((info) => {
+      if (!info || info.prototypeMethods.length === 0) {
         return
       }
 
+      const constructorName = info.constructorName
       const declarationPath = info.declaration
       const declarationNode = declarationPath.node
 
@@ -197,20 +244,29 @@ export function constructorToClass(root) {
         constructorNode = declarator.init
       }
 
-      const classBody = [
-        j.methodDefinition(
-          "constructor",
-          j.identifier("constructor"),
-          j.functionExpression(
-            null,
-            constructorNode.params,
-            constructorNode.body,
-            constructorNode.generator,
-            constructorNode.async,
-          ),
-          false,
-        ),
-      ]
+      const hasNodeOrBodyComments =
+        (constructorNode.comments && constructorNode.comments.length > 0) ||
+        (constructorNode.body.comments && constructorNode.body.comments.length > 0)
+
+      const classBody =
+        constructorNode.params.length > 0 ||
+        constructorNode.body.body.length > 0 ||
+        hasNodeOrBodyComments
+          ? [
+              j.methodDefinition(
+                "constructor",
+                j.identifier("constructor"),
+                j.functionExpression(
+                  null,
+                  constructorNode.params,
+                  constructorNode.body,
+                  constructorNode.generator,
+                  constructorNode.async,
+                ),
+                false,
+              ),
+            ]
+          : []
 
       info.prototypeMethods.forEach(({ methodName, methodValue }) => {
         const functionExpr = j.functionExpression(
@@ -254,12 +310,22 @@ export function constructorToClass(root) {
 
       modified = true
     })
+  })
 
-    return modified
-  }
+  return modified
+}
 
-  const constructors = findConstructors(root)
-  findPrototypeMethods(root, constructors)
-  return transformConstructorsToClasses(root, constructors)
+/**
+ * Transform old-school constructor functions with prototype methods to ES6 class
+ * syntax.
+ *
+ * @param {import("jscodeshift").Collection} root - The root AST collection
+ * @returns {boolean} True if code was modified
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes
+ */
+export function constructorToClass(root) {
+  const constructorsByScope = findConstructors(root)
+  findPrototypeMethods(root, constructorsByScope)
+  return transformConstructorsToClasses(root, constructorsByScope)
 }
 constructorToClass.baselineDate = new Date(Date.UTC(2016, 2, 8))