esupgrade 2025.14.3 → 2025.16.0

package/.gitattributes

@@ -0,0 +1,2 @@
+package-lock.json linguist-generated
+src/jQuery/HTMLInputElement.json linguist-generated

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

@@ -0,0 +1,66 @@
+---
+# For format details, see: https://gh.io/customagents/config
+
+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 | cat
+```
+
+You MUST ALWAYS read the `CONTRIBUTING.md` file before planning or writing any code.
+You MUST ALWAYS search the documentation and amend or update it as necessary.
+You MUST ALWAYS check for pre-commit hooks and run them before committing code.
+You MUST ALWAYS ensure that all new code is fully tested with 100% coverage. Unreachable code branches MUST be removed.
+
+## Writing Code
+
+Less code is more! Use the latest language features and libraries to achieve more with less code.
+
+Do not add new dependencies, but if you do, they must be widely adopted and well-maintained in the open-source community.
+
+You are a strong FOSS advocate with a preference for permissive licenses like BSD or MIT.
+
+Use generators instead of adding items to lists or arrays.
+
+Use class syntax for all object-oriented code.
+Use named functions instead of anonymous functions whenever possible.
+Avoid overly complex functions. Break them into smaller functions if necessary.
+Docstrings should be written in present tense imperative mood.
+They must start with a capital letter and end with a period.
+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.
+Avoid loops in favor of recursive functions or generator functions.
+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.
+EAFP (Easier to Ask Forgiveness than Permission) is preferred over LBYL (Look Before You Leap).
+Use type hints for all public functions, classes, and methods.
+Use dataclasses for simple data structures.
+Use context managers for resource management.
+Use list/set/dict comprehensions instead of loops for creating collections.
+Use generators for large data sets to save memory.
+Use the walrus operator (`:=`) for inline assignments when it improves readability.
+
+### JavaScript
+
+Use `#` for private methods.
+Write docstrings with jsdoc type annotations for all functions, classes, and methods.
+
+### TypeScript
+
+Use `#` for private methods.

package/.github/copilot-instructions.md

@@ -1,9 +1,15 @@
 When writing code, you MUST ALWAYS follow the [naming guidelines](https://raw.githubusercontent.com/codingjoe/naming-things/refs/heads/main/README.md).
 
+Usage:
+
+```console
+curl -sL https://raw.githubusercontent.com/codingjoe/naming-things/refs/heads/main/README.md
+```
+
 All code must be fully tested with a 100% coverage. Unreachable code must be removed.
 Follow the [CONTRIBUTING.md](./CONTRIBUTING.md) guidelines for testing and linting.
 The test suite will fail if the line coverage is below 100%.
-The test coverage will be written to stdout or the `lcov.info` file in the project root.
+The test coverage will be written to stdout when running the tests via `npm test | grep -v '100.00'`.
 
 All transformers must be documented in the README.md.
 
@@ -20,3 +26,7 @@ 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.
+Avoid loops in favor of recursive functions or generator functions.
+Avoid functions or other code inside functions.
+Avoid if-statements in favor of switch-statements or polymorphism.
+Do not assign names to objects which are returned in the next line.

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@v5
+      - uses: codecov/codecov-action@v6
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           flags: javascript

package/.pre-commit-config.yaml

@@ -21,6 +21,7 @@ repos:
           - mdformat-footnote
           - mdformat-gfm
           - mdformat-gfm-alerts
+        exclude: '.github/agents/'
   - repo: https://github.com/google/yamlfmt
     rev: v0.21.0
     hooks:
@@ -30,6 +31,16 @@ repos:
     hooks:
       - id: write-good
         args: [--no-passive]
+  - repo: https://github.com/pre-commit/mirrors-eslint
+    rev: v10.3.0
+    hooks:
+      - id: eslint
+        args: ["--fix"]
+        require_serial: true
+        additional_dependencies:
+          - "@eslint/js@9.39.2"
+          - "eslint@9.39.2"
+          - "globals@17.0.0"
   - repo: local
     hooks:
       - id: esupgrade

package/AGENTS.md

@@ -0,0 +1,33 @@
+# esupgrade
+
+The package includes transformers for upgrading JavaScript syntax.
+
+## Categories
+
+- [Widely Available](./src/widelyAvailable/): Transformers for features available in all major browsers for at least 30 months.
+- [Newly Available](./src/newlyAvailable/): Transformers for features available in all major browsers for 0-30 months.
+
+For a full list of transformations, see [README.md](./README.md).
+
+## Package Structure
+
+- [bin/](./bin/): Command-line interface script.
+- [src/](./src/): Source code and transformers.
+- [tests/](./tests/): Test suite.
+
+For contributing guidelines, see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Instructions
+
+Use EOF syntax to run node scripts directly from the command line. For example:
+
+```bash
+node --input-type=module <<'EOF'
+import { transform } from './src/index.js';
+
+const sample = "const v = $(input).val();";
+const res = transform(sample);
+console.log('modified:', res.modified);
+console.log('code:\n' + res.code);
+EOF
+```

package/CONTRIBUTING.md

@@ -20,3 +20,7 @@ Or instead run the linters once with:
 ```console
 uvx pre-commit run --all-files
 ```
+
+## Naming conversions
+
+When writing code, please follow the [naming guidelines](https://raw.githubusercontent.com/codingjoe/naming-things/refs/heads/main/README.md).

package/README.md

@@ -15,6 +15,12 @@ Keeping your JavaScript and TypeScript code up to date with full browser compati
 esupgrade is safe and meant to be used automatically on your codebase.
 We recommend integrating it into your development workflow using [pre-commit].
 
+To try it out on a repository without writing changes, run:
+
+```bash
+npx esupgrade $(git ls-files | grep -E -i -w '.*\.(t|j)sx?')
+```
+
 ### pre-commit
 
 ```bash
@@ -218,6 +224,17 @@ Supports:
 +const clone = [...Array.from(items)];
 ```
 
+#### `Array.filter()[0]` → [`Array.find()`][mdn-find]
+
+```diff
+-const first = [1, 2, 3].filter(n => n > 1)[0];
++const first = [1, 2, 3].find(n => n > 1);
+```
+
+Transforms `filter(predicate)[0]` to the more explicit and performant `find(predicate)`, which stops at the first match instead of filtering the entire array.
+
+Transformations are limited to when the receiver can be verified as an array (array literals, `new Array()`, or known array method chains) and `filter()` is called with exactly one argument.
+
 #### `Math.pow()` → [Exponentiation operator \*\*][mdn-exponentiation]
 
 ```diff
@@ -565,6 +582,189 @@ These transformations are mainly to harden code for future releases and should b
 +});
 ```
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://jquery.com/wp-content/themes/jquery/images/logo-jquery@2x.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://upload.wikimedia.org/wikipedia/commons/f/fd/JQuery-Logo.svg">
+  <img alt="jQuery logo" src="https://upload.wikimedia.org/wikipedia/commons/f/fd/JQuery-Logo.svg" height="32" align="right">
+</picture>
+
+## jQuery
+
+esupgrade can transform common [jQuery] patterns to modern, standards-based DOM APIs via the `--jQuery` argument.
+For further reading, we recommend: [You Might Not Need jQuery](https://youmightnotneedjquery.com/).
+
+```bash
+npx esupgrade --jQuery <files>
+```
+
+> [!WARNING]
+> jQuery transformers are experimental and may produce unsafe code in complex scenarios.
+> Review all changes before applying them to your codebase.
+
+### Selection
+
+#### `$(selector)` → `document.querySelectorAll()` / `document.getElementById()`
+
+```diff
+-$('.foo')
+- $('#bar')
++document.querySelectorAll('.foo')
++document.getElementById('bar')
+```
+
+Skipped when jQuery chaining is present (e.g. `$('.x').css(...).addClass(...)`).
+
+### Class and Attributes
+
+#### Class helpers
+
+```diff
+-$(el).addClass('a b');
+-$(el).removeClass('a');
+-$(el).toggleClass('x');
+-$(el).hasClass('x');
++el.classList.add('a', 'b');
++el.classList.remove('a');
++el.classList.toggle('x');
++el.classList.contains('x');
+```
+
+#### Attribute helpers
+
+```diff
+-$(el).attr('data');
+-$(el).attr('data', v);
+-$(el).removeAttr('disabled');
++el.getAttribute('data');
++el.setAttribute('data', v);
++el.removeAttribute('disabled');
+```
+
+### Content and Value
+
+#### Text and HTML accessors
+
+```diff
+-const text = $(el).text();
+-$(el).text('new text');
+-const html = $(el).html();
+-$(el).html('<b>bold</b>');
++const text = el.textContent;
++el.textContent = 'new text';
++const html = el.innerHTML;
++el.innerHTML = '<b>bold</b>';
+```
+
+#### Value accessors
+
+```diff
+-const val = $(el).val();
+-$(el).val('new value');
++const val = el.value;
++el.value = 'new value';
+```
+
+### DOM Manipulation
+
+#### Insertion and Removal
+
+```diff
+-$(parent).append(child);
+-$(parent).prepend(child);
+-$(el).before(node);
+-$(el).after(node);
+-$(el).remove();
+-$(el).empty();
++parent.append(child);
++parent.prepend(child);
++el.before(node);
++el.after(node);
++el.remove();
++el.replaceChildren();
+```
+
+### Events
+
+#### Event Listeners
+
+```diff
+-$(el).on('click', handler);
+-$(el).off('click', handler);
+-$(el).click(handler);
++el.addEventListener('click', handler);
++el.removeEventListener('click', handler);
++el.addEventListener('click', handler);
+```
+
+#### Dispatching and Ready
+
+```diff
+-$(el).trigger('custom');
+-$(document).ready(fn);
++el.dispatchEvent(new CustomEvent('custom'));
++document.addEventListener('DOMContentLoaded', fn);
+```
+
+### Traversal
+
+#### Traversal helpers
+
+```diff
+-$(el).find('.sel');
+-$(el).parent();
+-$(el).closest('.sel');
+-$(el).next();
+-$(el).prev();
+-$(el).children();
+-$(el).siblings();
++el.querySelectorAll('.sel');
++el.parentElement;
++el.closest('.sel');
++el.nextElementSibling;
++el.previousElementSibling;
++Array.from(el.children);
++Array.from(el.parentElement.children).filter(c => c !== el);
+```
+
+### Style and Sizing
+
+#### CSS and Display
+
+```diff
+-$(el).css('color');
+-$(el).css('color', 'red');
+-$(el).show();
+-$(el).hide();
++getComputedStyle(el).color;
++el.style.color = 'red';
++el.style.display = '';
++el.style.display = 'none';
+```
+
+#### Dimensions
+
+```diff
+-$(el).width();
+-$(el).height();
++el.clientWidth;
++el.clientHeight;
+```
+
+### Static Utilities
+
+#### Collection and String utilities
+
+```diff
+-$.each(array, fn);
+-$.map(array, fn);
+-$.inArray(val, array) !== -1;
+-$.trim(str);
++array.forEach(fn);
++array.map(fn);
++array.includes(val);
++str.trim();
+```
+
 ## Versioning
 
 esupgrade uses the [calver] `YYYY.MINOR.PATCH` versioning scheme.
@@ -587,6 +787,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
+[jquery]: https://jquery.com/
 [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-classes]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes
@@ -595,6 +796,7 @@ Furthermore, esupgrade supports JavaScript, TypeScript, and more, while lebab is
 [mdn-default-parameters]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters
 [mdn-endswith]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith
 [mdn-exponentiation]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Exponentiation
+[mdn-find]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find
 [mdn-for-of]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of
 [mdn-functions]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions
 [mdn-globalthis]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis

package/bin/esupgrade.js

@@ -30,11 +30,12 @@ class WorkerRunner {
    * Run a worker thread to process a file.
    * @param {string} filePath - Path to the file to process.
    * @param {string} baseline - Baseline level for transformations.
+   * @param {boolean} jQuery - Whether to include jQuery transformers.
    * @returns {Promise<Object>} Worker message result.
    */
-  async run(filePath, baseline) {
+  async run(filePath, baseline, jQuery) {
     const worker = new Worker(this.workerPath, {
-      workerData: { filePath, baseline },
+      workerData: { filePath, baseline, jQuery },
     })
 
     const [message] = await once(worker, "message")
@@ -57,6 +58,7 @@ class FileProcessor {
    * @param {string} options.baseline - Baseline level for transformations.
    * @param {boolean} options.check - Whether to only check for changes.
    * @param {boolean} options.write - Whether to write changes to file.
+   * @param {boolean} options.jQuery - Whether to include jQuery transformers.
    * @returns {Promise<{modified: boolean, error: boolean}>} Result of processing.
    */
   async processFile(filePath, options) {
@@ -73,7 +75,11 @@ class FileProcessor {
     }
 
     try {
-      const workerResult = await this.workerRunner.run(filePath, options.baseline)
+      const workerResult = await this.workerRunner.run(
+        filePath,
+        options.baseline,
+        options.jQuery,
+      )
 
       if (!workerResult.success) {
         console.error(`\x1b[31m✗\x1b[0m Error: ${filePath}: ${workerResult.error}`)
@@ -193,6 +199,7 @@ class CLIRunner {
   async run(patterns, options) {
     console.time("Processing")
     // Hand CLI-provided names directly to the worker pool; file validation occurs in processFile.
+    // Pass jQuery to worker pool
     const results = await this.workerPool.processFiles(patterns, options)
     console.timeEnd("Processing")
 
@@ -259,21 +266,15 @@ program
       .choices(["widely-available", "newly-available"])
       .default("widely-available"),
   )
-  .option("--check", "Report which files need upgrading and exit with code 1 if any do")
-  .option("--write", "Write changes to files")
+  .option(
+    "--check",
+    "Report which files need upgrading and exit with code 1 if any do",
+    false,
+  )
+  .option("--write", "Write changes to files", false)
+  .option("--jquery, --jQuery", "Enable jQuery specific transformers", false)
   .action(async (files, options) => {
-    // Handle check/write options - they are not mutually exclusive
-    // Default: write is false (read-only mode unless --write is specified)
-    const shouldWrite = options.write || false
-    const shouldCheck = options.check || false
-
-    const processingOptions = {
-      baseline: options.baseline,
-      write: shouldWrite,
-      check: shouldCheck,
-    }
-
-    await cliRunner.run(files, processingOptions)
+    await cliRunner.run(files, options)
   })
 
 program.parse()

package/eslint.config.cjs

@@ -0,0 +1,12 @@
+const js = require("@eslint/js")
+const globals = require("globals")
+const defineConfig = require("eslint/config").defineConfig
+
+module.exports = defineConfig([
+    {
+        files: ["**/*.{js,mjs,cjs}"],
+        plugins: { js },
+        extends: ["js/recommended"],
+        languageOptions: { globals: globals.node },
+    },
+])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esupgrade",
-  "version": "2025.14.3",
+  "version": "2025.16.0",
   "description": "Auto-upgrade your JavaScript syntax",
   "type": "module",
   "main": "src/index.js",
@@ -8,7 +8,7 @@
     "esupgrade": "./bin/esupgrade.js"
   },
   "scripts": {
-    "test": "node --test --experimental-test-coverage --test-coverage-lines=100 --test-reporter=spec --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=lcov.info --test-coverage-exclude=tests/**/* tests/*.test.js tests/**/*.test.js"
+    "test": "node --test --experimental-test-coverage --test-reporter=spec --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=lcov.info --test-coverage-exclude=tests/**/* tests/*.test.js tests/**/*.test.js"
   },
   "keywords": [
     "javascript",
@@ -36,6 +36,5 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/codingjoe/esupgrade.git"
-  },
-  "devDependencies": {}
+  }
 }

package/src/index.js

@@ -1,6 +1,13 @@
 import jscodeshift from "jscodeshift"
 import * as newlyAvailable from "./newlyAvailable.js"
 import * as widelyAvailable from "./widelyAvailable.js"
+import * as jQueryTransformers from "./jQuery.js"
+
+/**
+ * Transformer function type.
+ *
+ * @typedef {function(import('jscodeshift').Collection): boolean} Transformer
+ */
 
 /**
  * Result of a transformation.
@@ -10,32 +17,52 @@ import * as widelyAvailable from "./widelyAvailable.js"
  * @property {boolean} modified - Whether the code was modified
  */
 
+/**
+ * Apply transformers to code recursively until no changes occur.
+ *
+ * @param {string} code - The source code to transform.
+ * @param {import('jscodeshift').JSCodeshift} j - jscodeshift instance.
+ * @param {Transformer[]} transformers - Transformer functions.
+ * @param {boolean} globalModified - Whether any modifications have occurred.
+ * @returns {TransformResult} Object with transformed code and modification status.
+ */
+function applyTransformersRecursively(code, j, transformers, globalModified = false) {
+  const root = j(code)
+  let passModified = false
+
+  for (const transformer of transformers) {
+    passModified = transformer(root) || passModified
+  }
+
+  if (passModified) {
+    return applyTransformersRecursively(root.toSource(), j, transformers, passModified)
+  }
+
+  return {
+    code,
+    modified: globalModified,
+  }
+}
+
 /**
  * Transform JavaScript code using the specified transformers.
  *
  * @param {string} code - The source code to transform.
  * @param {string} baseline - Baseline level ('widely-available' or 'newly-available').
+ * @param {boolean} jQuery - Whether to include jQuery transformers.
  * @returns {TransformResult} Object with transformed code and modification status.
  */
-export function transform(code, baseline = "widely-available") {
+export function transform(code, baseline = "widely-available", jQuery) {
   const j = jscodeshift.withParser("tsx")
-  const root = j(code)
-
-  let modified = false
 
-  const transformers =
+  let transformers =
     baseline === "newly-available"
       ? { ...widelyAvailable, ...newlyAvailable }
       : widelyAvailable
 
-  for (const transformer of Object.values(transformers)) {
-    if (transformer(root)) {
-      modified = true
-    }
+  if (jQuery) {
+    transformers = { ...transformers, ...jQueryTransformers }
   }
 
-  return {
-    code: root.toSource(),
-    modified,
-  }
+  return applyTransformersRecursively(code, j, Object.values(transformers))
 }