Add no-modifier-argument-destructuring rule

New rule that disallows destructuring positional or named arguments in
ember-modifier callbacks. Destructuring eagerly consumes tracked data,
which can lead to backtracking re-render assertions. Instead, arguments
should be accessed by index or property inside the callback body.

Co-authored-by: NullVoxPopuli <[email protected]>

Author: Copilot

docs/rules/no-modifier-argument-destructuring.md

@@ -0,0 +1,56 @@
+# no-modifier-argument-destructuring
+
+Disallow destructuring of `modifier` arguments to avoid consuming tracked data too early.
+
+## Rule Details
+
+When using `ember-modifier`, destructuring the positional or named arguments of the modifier callback eagerly consumes tracked data. This can lead to backtracking re-render assertions when the tracked data is not actually needed until later (e.g., inside an event listener).
+
+Instead, access the arguments by index (for positional) or property (for named) inside the callback body where the data is actually needed.
+
+## Examples
+
+Examples of **incorrect** code for this rule:
+
+```js
+import { modifier } from 'ember-modifier';
+
+// Destructuring positional args
+modifier((element, [text]) => {
+  element.addEventListener('hover', () => console.log(text));
+});
+```
+
+```js
+import { modifier } from 'ember-modifier';
+
+// Destructuring named args
+modifier((element, positional, { title }) => {
+  element.addEventListener('hover', () => console.log(title));
+});
+```
+
+Examples of **correct** code for this rule:
+
+```js
+import { modifier } from 'ember-modifier';
+
+// Access positional args by index
+modifier((element, positional) => {
+  element.addEventListener('hover', () => console.log(positional[0]));
+});
+```
+
+```js
+import { modifier } from 'ember-modifier';
+
+// Access named args by property
+modifier((element, positional, named) => {
+  element.addEventListener('hover', () => console.log(named.title));
+});
+```
+
+## References
+
+- [ember-modifier](https://github.com/ember-modifier/ember-modifier)
+- [Ember Autotracking](https://guides.emberjs.com/release/in-depth-topics/autotracking-in-depth/)

lib/rules/no-modifier-argument-destructuring.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const { getImportIdentifier } = require('../utils/import');
+
+const ERROR_MESSAGE =
+  'Do not destructure the positional or named arguments of a modifier. Instead, access them by index or property to avoid eagerly consuming tracked data.';
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'disallow destructuring of modifier arguments to avoid consuming tracked data too early',
+      category: 'Ember Object',
+      recommended: false,
+      url: 'https://github.com/ember-cli/eslint-plugin-ember/tree/master/docs/rules/no-modifier-argument-destructuring.md',
+    },
+    fixable: null,
+    schema: [],
+    messages: {
+      main: ERROR_MESSAGE,
+    },
+  },
+
+  ERROR_MESSAGE,
+
+  create(context) {
+    let modifierImportedName = undefined;
+
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value === 'ember-modifier') {
+          modifierImportedName =
+            getImportIdentifier(node, 'ember-modifier', 'modifier') ??
+            modifierImportedName;
+        }
+      },
+
+      CallExpression(node) {
+        if (!modifierImportedName) {
+          return;
+        }
+
+        if (
+          node.callee.type !== 'Identifier' ||
+          node.callee.name !== modifierImportedName
+        ) {
+          return;
+        }
+
+        const callback = node.arguments[0];
+        if (!callback) {
+          return;
+        }
+
+        // Support arrow functions and function expressions
+        if (
+          callback.type !== 'ArrowFunctionExpression' &&
+          callback.type !== 'FunctionExpression'
+        ) {
+          return;
+        }
+
+        // Check 2nd parameter (positional args) - index 1
+        const positionalParam = callback.params[1];
+        if (positionalParam && positionalParam.type === 'ArrayPattern') {
+          context.report({
+            node: positionalParam,
+            messageId: 'main',
+          });
+        }
+
+        // Check 3rd parameter (named args) - index 2
+        const namedParam = callback.params[2];
+        if (namedParam && namedParam.type === 'ObjectPattern') {
+          context.report({
+            node: namedParam,
+            messageId: 'main',
+          });
+        }
+      },
+    };
+  },
+};

tests/lib/rules/no-modifier-argument-destructuring.js

@@ -0,0 +1,154 @@
+const rule = require('../../../lib/rules/no-modifier-argument-destructuring');
+const RuleTester = require('eslint').RuleTester;
+
+const { ERROR_MESSAGE } = rule;
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+  },
+});
+
+ruleTester.run('no-modifier-argument-destructuring', rule, {
+  valid: [
+    // Not importing from ember-modifier
+    `
+      function modifier(fn) { return fn; }
+      modifier((element, [text]) => {});
+    `,
+
+    // No destructuring of positional args
+    `
+      import { modifier } from 'ember-modifier';
+      modifier((element, positional) => {
+        element.addEventListener('hover', () => console.log(positional[0]));
+      });
+    `,
+
+    // No destructuring of named args
+    `
+      import { modifier } from 'ember-modifier';
+      modifier((element, positional, named) => {
+        element.addEventListener('hover', () => console.log(named.text));
+      });
+    `,
+
+    // Only element parameter
+    `
+      import { modifier } from 'ember-modifier';
+      modifier((element) => {
+        element.addEventListener('click', () => {});
+      });
+    `,
+
+    // No arguments at all
+    `
+      import { modifier } from 'ember-modifier';
+      modifier(() => {});
+    `,
+
+    // Using a non-modifier function from ember-modifier
+    `
+      import { something } from 'ember-modifier';
+      something((element, [text]) => {});
+    `,
+
+    // Modifier called with non-function argument
+    `
+      import { modifier } from 'ember-modifier';
+      modifier(myCallback);
+    `,
+
+    // Destructuring element (first param) is fine as it's not tracked
+    `
+      import { modifier } from 'ember-modifier';
+      modifier(({ tagName }) => {});
+    `,
+
+    // Function expression (not arrow) without destructuring
+    `
+      import { modifier } from 'ember-modifier';
+      modifier(function(element, positional) {
+        console.log(positional[0]);
+      });
+    `,
+  ],
+
+  invalid: [
+    // Destructuring positional args (arrow function)
+    {
+      code: `
+        import { modifier } from 'ember-modifier';
+        modifier((element, [text]) => {
+          element.addEventListener('hover', () => console.log(text));
+        });
+      `,
+      output: null,
+      errors: [{ message: ERROR_MESSAGE, type: 'ArrayPattern' }],
+    },
+
+    // Destructuring positional args (function expression)
+    {
+      code: `
+        import { modifier } from 'ember-modifier';
+        modifier(function(element, [text]) {
+          element.addEventListener('hover', () => console.log(text));
+        });
+      `,
+      output: null,
+      errors: [{ message: ERROR_MESSAGE, type: 'ArrayPattern' }],
+    },
+
+    // Destructuring named args
+    {
+      code: `
+        import { modifier } from 'ember-modifier';
+        modifier((element, positional, { text }) => {
+          element.addEventListener('hover', () => console.log(text));
+        });
+      `,
+      output: null,
+      errors: [{ message: ERROR_MESSAGE, type: 'ObjectPattern' }],
+    },
+
+    // Both positional and named args destructured
+    {
+      code: `
+        import { modifier } from 'ember-modifier';
+        modifier((element, [text], { title }) => {
+          element.addEventListener('hover', () => console.log(text, title));
+        });
+      `,
+      output: null,
+      errors: [
+        { message: ERROR_MESSAGE, type: 'ArrayPattern' },
+        { message: ERROR_MESSAGE, type: 'ObjectPattern' },
+      ],
+    },
+
+    // Renamed import
+    {
+      code: `
+        import { modifier as createModifier } from 'ember-modifier';
+        createModifier((element, [text]) => {
+          element.addEventListener('hover', () => console.log(text));
+        });
+      `,
+      output: null,
+      errors: [{ message: ERROR_MESSAGE, type: 'ArrayPattern' }],
+    },
+
+    // Multiple positional args destructured
+    {
+      code: `
+        import { modifier } from 'ember-modifier';
+        modifier((element, [text, count]) => {
+          element.addEventListener('hover', () => console.log(text, count));
+        });
+      `,
+      output: null,
+      errors: [{ message: ERROR_MESSAGE, type: 'ArrayPattern' }],
+    },
+  ],
+});