esupgrade 2025.15.0 → 2025.16.0

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/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:
@@ -31,7 +32,7 @@ repos:
       - id: write-good
         args: [--no-passive]
   - repo: https://github.com/pre-commit/mirrors-eslint
-    rev: v10.0.0-rc.1
+    rev: v10.3.0
     hooks:
       - id: eslint
         args: ["--fix"]

package/README.md

@@ -224,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
@@ -785,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/package.json

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

package/src/types.js

@@ -494,6 +494,57 @@ export class NodeTest {
     return count
   }
 
+  /**
+   * Determine whether an inline function has side effects.
+   * Extracts parameter names from the function node and checks the body against a
+   * strict whitelist: only literals, parameter identifiers, binary expressions, and
+   * non-computed member access on parameters are side-effect free.
+   *
+   * @returns {boolean} True if the function has side effects
+   */
+  hasSideEffects() {
+    const paramNames = new Set(
+      this.node.params.flatMap((param) =>
+        Array.from(new NodeTest(param).extractIdentifiersFromPattern()),
+      ),
+    )
+    return this.#hasNodeSideEffects(this.node.body, paramNames)
+  }
+
+  /**
+   * Recursively determine if an AST node has side effects given a set of allowed
+   * identifiers. Returns false only for literals, known-parameter identifiers, binary
+   * expressions, non-computed property access on side-effect-free sub-expressions, and
+   * single-return-statement block bodies. Returns true for all other node types.
+   *
+   * @param {import("ast-types").ASTNode} node - The node to inspect
+   * @param {Set<string>} paramNames - Set of allowed identifier names
+   * @returns {boolean} True if the node has side effects
+   */
+  #hasNodeSideEffects(node, paramNames) {
+    if (j.Literal.check(node)) return false
+    if (j.Identifier.check(node)) return !paramNames.has(node.name)
+    if (j.BinaryExpression.check(node)) {
+      return (
+        this.#hasNodeSideEffects(node.left, paramNames) ||
+        this.#hasNodeSideEffects(node.right, paramNames)
+      )
+    }
+    if (j.MemberExpression.check(node)) {
+      if (node.computed) return true
+      return this.#hasNodeSideEffects(node.object, paramNames)
+    }
+    if (j.BlockStatement.check(node)) {
+      if (node.body.length !== 1) return true
+      const [stmt] = node.body
+      return (
+        !j.ReturnStatement.check(stmt) ||
+        this.#hasNodeSideEffects(stmt.argument, paramNames)
+      )
+    }
+    return true
+  }
+
   /**
    * Check if node eventually chains from document.
    *

package/src/widelyAvailable/arrayFilterToFind.js

@@ -0,0 +1,80 @@
+import { default as j } from "jscodeshift"
+import { NodeTest } from "../types.js"
+
+/**
+ * Transform Array.filter()[0] to Array.find().
+ * Converts patterns like arr.filter(predicate)[0] to arr.find(predicate).
+ *
+ * @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/Global_Objects/Array/find
+ */
+export function arrayFilterToFind(root) {
+  let modified = false
+
+  root
+    .find(j.MemberExpression)
+    .filter((path) => {
+      const node = path.node
+
+      // Must be computed access: expr[0]
+      if (!node.computed) {
+        return false
+      }
+
+      // Property must be literal 0
+      if (!j.Literal.check(node.property) || node.property.value !== 0) {
+        return false
+      }
+
+      // Object must be a .filter() call
+      if (!j.CallExpression.check(node.object)) {
+        return false
+      }
+
+      const filterCall = node.object
+
+      if (
+        !j.MemberExpression.check(filterCall.callee) ||
+        filterCall.callee.property.name !== "filter"
+      ) {
+        return false
+      }
+
+      // .filter() must have exactly one argument
+      if (filterCall.arguments.length !== 1) {
+        return false
+      }
+
+      // Predicate must be an inline function whose body is proven side-effect free.
+      // Named function references are skipped because their bodies cannot be inspected.
+      const predicate = filterCall.arguments[0]
+      if (
+        !j.ArrowFunctionExpression.check(predicate) &&
+        !j.FunctionExpression.check(predicate)
+      ) {
+        return false
+      }
+
+      if (new NodeTest(predicate).hasSideEffects()) {
+        return false
+      }
+
+      // Object being filtered must be a known array
+      return new NodeTest(filterCall.callee.object).hasIndexOfAndIncludes()
+    })
+    .forEach((path) => {
+      const filterCall = path.node.object
+
+      j(path).replaceWith(
+        j.callExpression(
+          j.memberExpression(filterCall.callee.object, j.identifier("find"), false),
+          filterCall.arguments,
+        ),
+      )
+
+      modified = true
+    })
+
+  return modified
+}

package/src/widelyAvailable.js

@@ -1,6 +1,7 @@
 export { anonymousFunctionToArrow } from "./widelyAvailable/anonymousFunctionToArrow.js"
 export { argumentsToRestParameters } from "./widelyAvailable/argumentsToRestParameters.js"
 export { arrayConcatToSpread } from "./widelyAvailable/arrayConcatToSpread.js"
+export { arrayFilterToFind } from "./widelyAvailable/arrayFilterToFind.js"
 export { arrayFromForEachToForOf } from "./widelyAvailable/arrayFromForEachToForOf.js"
 export { arrayFromToSpread } from "./widelyAvailable/arrayFromToSpread.js"
 export { arraySliceToSpread } from "./widelyAvailable/arraySliceToSpread.js"

package/tests/widelyAvailable/array-filter-to-find.test.js

@@ -0,0 +1,173 @@
+import assert from "node:assert/strict"
+import { describe, suite, test } from "node:test"
+import { transform } from "../../src/index.js"
+
+suite("widely-available", () => {
+  describe("arrayFilterToFind", () => {
+    test("array literal with named function - should not transform", () => {
+      const result = transform(`const first = [1, 2, 3].filter(isPositive)[0];`)
+
+      assert(!result.modified, "skip filter()[0] with named function predicate")
+    })
+
+    test("array literal with side effect exception - should not transform", () => {
+      const result = transform(`const first = [1, 2, 3].filter(x => {
+        throw new Error("Side effect");
+      })[0];`)
+
+      assert(!result.modified, "skip filter()[0] with named function predicate")
+    })
+
+    test("array literal with side effect out of scope variable - should not transform", () => {
+      const result = transform(`const someList = []
+      const first = [1, 2, 3].filter(x => {
+        someList.push(x);
+      })[0];`)
+
+      assert(!result.modified, "skip filter()[0] with named function predicate")
+    })
+
+    test("predicate accessing outer scope - should not transform", () => {
+      const result = transform(`const first = [1, 2, 3].filter(x => x > threshold)[0];`)
+
+      assert(!result.modified, "skip filter()[0] when predicate accesses outer scope")
+    })
+
+    test("predicate calling a function - should not transform", () => {
+      const result = transform(`const first = [1, 2, 3].filter(x => sideEffect(x))[0];`)
+
+      assert(!result.modified, "skip filter()[0] when predicate calls a function")
+    })
+
+    test("predicate using computed member access - should not transform", () => {
+      const result = transform(`const first = [1, 2, 3].filter(x => x[0] > 0)[0];`)
+
+      assert(
+        !result.modified,
+        "skip filter()[0] when predicate uses computed member access",
+      )
+    })
+
+    test("predicate with multi-statement body - should not transform", () => {
+      const result = transform(
+        `const first = [1, 2, 3].filter(n => { const doubled = n * 2; return n > doubled; })[0];`,
+      )
+
+      assert(
+        !result.modified,
+        "skip filter()[0] when predicate body has multiple statements",
+      )
+    })
+
+    test("predicate with member access on parameter", () => {
+      const result = transform(
+        `const first = ['ab', 'abc'].filter(x => x.length > 1)[0];`,
+      )
+
+      assert(
+        result.modified,
+        "transform filter()[0] when predicate uses non-computed member access on parameter",
+      )
+      assert.match(result.code, /\.find\(x => x\.length > 1\)/)
+      assert.doesNotMatch(result.code, /filter/)
+    })
+
+    test("array literal with arrow function", () => {
+      const result = transform(`const first = [1, 2, 3].filter(x => x > 0)[0];`)
+
+      assert(result.modified, "transform filter()[0] with arrow function")
+      assert.match(result.code, /\[1, 2, 3\]\.find\(x => x > 0\)/)
+      assert.doesNotMatch(result.code, /filter/)
+    })
+
+    test("array literal with function expression", () => {
+      const result = transform(
+        `const first = [1, 2, 3].filter(function(n) { return n > 1; })[0];`,
+      )
+
+      assert(result.modified, "transform filter()[0] with function expression")
+      assert.match(result.code, /\[1, 2, 3\]\.find\(/)
+      assert.doesNotMatch(result.code, /filter/)
+    })
+
+    test("new Array() with arrow function", () => {
+      const result = transform(
+        `const first = new Array(1, 2, 3).filter(n => n > 1)[0];`,
+      )
+
+      assert(result.modified, "transform filter()[0] on new Array()")
+      assert.match(result.code, /new Array\(1, 2, 3\)\.find\(n => n > 1\)/)
+      assert.doesNotMatch(result.code, /filter/)
+    })
+
+    test("chained array method", () => {
+      const result = transform(
+        `const first = [1, 2, 3].map(n => n * 2).filter(n => n > 2)[0];`,
+      )
+
+      assert(result.modified, "transform filter()[0] on chained array method")
+      assert.match(result.code, /\.find\(n => n > 2\)/)
+      assert.doesNotMatch(result.code, /filter/)
+    })
+
+    test("nested filter chain", () => {
+      const result = transform(
+        `const first = [1, 2, 3].filter(n => n > 0).filter(n => n < 3)[0];`,
+      )
+
+      assert(result.modified, "transform filter()[0] on nested filter chain")
+      assert.match(result.code, /\.find\(n => n < 3\)/)
+    })
+
+    test("unknown receiver with arrow predicate - should not transform", () => {
+      const result = transform(`const first = arr.filter(n => n > 0)[0];`)
+
+      assert(
+        !result.modified,
+        "skip filter()[0] on unknown receiver even with inline predicate",
+      )
+    })
+
+    test("non-filter method with [0] - should not transform", () => {
+      const result = transform(`const first = [1, 2, 3].sort(fn)[0];`)
+
+      assert(!result.modified, "skip [0] access on non-filter method call")
+    })
+
+    test("function call result with [0] - should not transform", () => {
+      const result = transform(`const first = getItems()[0];`)
+
+      assert(!result.modified, "skip [0] access on plain function call result")
+    })
+
+    test("unknown identifier - should not transform", () => {
+      const result = transform(`const first = arr.filter(fn)[0];`)
+
+      assert(!result.modified, "skip filter()[0] on unknown identifier")
+    })
+
+    test("non-zero index - should not transform", () => {
+      const result = transform(`const second = [1, 2, 3].filter(fn)[1];`)
+
+      assert(!result.modified, "skip filter()[1] - not index 0")
+    })
+
+    test("variable index - should not transform", () => {
+      const result = transform(`const item = [1, 2, 3].filter(fn)[n];`)
+
+      assert(!result.modified, "skip filter()[n] - computed variable index")
+    })
+
+    test("no arguments to filter - should not transform", () => {
+      const result = transform(`const first = [1, 2, 3].filter()[0];`)
+
+      assert(!result.modified, "skip filter()[0] with no filter arguments")
+    })
+
+    test("two arguments to filter - should not transform", () => {
+      const result = transform(`const first = [1, 2, 3].filter(fn, thisArg)[0];`)
+
+      assert(!result.modified, "skip filter()[0] with two filter arguments")
+    })
+  })
+})