@mehshekari/eslint-plugin-gsap-motion 4.5.0 → 4.6.1

package/lib/ast.mjs

@@ -602,10 +602,56 @@ export function gsapContexts(root) {
     functions.set(name, node.type === "FunctionDeclaration" ? node : unwrap(node.init));
   }
 
+  /**
+   * Whether a function nested in a context body runs while the body runs, and
+   * so inside the context. GSAP sets the context only for the duration of the
+   * body (Context.add, gsap-core 3.15): a function the body hands to a listener,
+   * a timer, a promise or a ref runs later, outside it, and nothing it creates
+   * is reverted. A real project built a tween in `pulse.current = () => …`
+   * inside useGSAP and called it from pointermove; the audit read it as inside.
+   *
+   * In place: called right there, an array method's callback, GSAP's own
+   * callbacks (`on…` keys, `.add`, `.call`, which GSAP runs in the context),
+   * the cleanup the body returns, or a named function only ever called.
+   */
+  const ITERATORS = new Set(["forEach", "map", "filter", "flatMap", "reduce", "reduceRight", "some", "every", "find", "findIndex", "sort"]);
+  const runsInPlace = (fn) => {
+    const parent = parentOf(root, fn);
+    if (!parent) return false;
+    if (parent.type === "CallExpression") {
+      if (unwrap(parent.callee) === fn) return true;
+      const name = methodName(parent) ?? bareName(parent);
+      return ITERATORS.has(name) || name === "add" || name === "call" || isHook(parent) || safe.has(name) || calleeName(parent) === "gsap.context";
+    }
+    if (parent.type === "Property") return /^on[A-Z]/.test(keyName(parent) ?? "");
+    if (parent.type === "ReturnStatement" || (parent.type === "ArrowFunctionExpression" && parent.body === fn)) return true;
+    const bound =
+      parent.type === "VariableDeclarator" && parent.id.type === "Identifier" && unwrap(parent.init) === fn
+        ? parent.id.name
+        : fn.type === "FunctionDeclaration"
+          ? fn.id?.name
+          : null;
+    if (!bound) return false;
+    const uses = findAll(root, (n) => n.type === "Identifier" && n.name === bound && isReference(root, n));
+    return uses.every((id) => {
+      const call = parentOf(root, id);
+      return call?.type === "CallExpression" && call.callee === id;
+    });
+  };
+  /** Inside `scope`, with no function between that runs later. */
+  const runsWithin = (scope, node) => {
+    if (!contains(scope, node)) return false;
+    for (const ancestor of ancestorsOf(root, node)) {
+      if (ancestor === scope) return true;
+      if (isFunction(ancestor) && !runsInPlace(ancestor)) return false;
+    }
+    return false;
+  };
+
   const contained = new Set();
   const inside = (node) =>
-    scopes.some((argument) => contains(argument, node)) ||
-    [...contained].some((fn) => contains(fn, node));
+    scopes.some((argument) => runsWithin(argument, node)) ||
+    [...contained].some((fn) => runsWithin(fn, node));
   const identifiers = findAll(root, (node) => node.type === "Identifier");
 
   for (let changed = true; changed; ) {

package/lib/rules.mjs

@@ -54,7 +54,7 @@ const HINT = {
   stackedFrom:
     "A `from` or `fromTo` applies its start state the moment it is built. Built more than once against the same element, the last one wins, and holds that element at its start state until the playhead reaches it — invisible, if the start state hides it. Pass `immediateRender: false`, and set the element's first state yourself with `gsap.set`.",
   orphanTween:
-    "Nothing reverts it on unmount, and React StrictMode runs it twice in development. Move it into the useGSAP body, or wrap the handler in contextSafe. A helper counts as inside only when every use of it is a call from inside a context. Note that contextSafe keeps every tween it creates until the context reverts: a handler that runs often should replay a timeline built once, or call a quickTo.",
+    "Nothing reverts it on unmount, and React StrictMode may run it twice in development. Move it into the useGSAP body, or wrap the handler in contextSafe. A helper counts as inside only when every use of it is a call from inside a context. Note that contextSafe keeps every tween it creates until the context reverts: a handler that runs often should replay a timeline built once, or call a quickTo.",
   unmanagedInstance:
     "Inside a context these register themselves and are reverted with it. Out here nothing is watching: move it into the useGSAP body, or keep the instance and revert/kill it from the cleanup.",
   unrevertedContext:
@@ -250,7 +250,32 @@ function listenerMethod(node) {
  * `followNames`, a handler passed by name is followed to its declaration when
  * the file declares exactly one function of that name.
  */
-function handlersFor(ast, events, { followNames = true, perFrame = false } = {}) {
+function handlersFor(ast, events, options = {}) {
+  const direct = directHandlers(ast, events, options);
+  /**
+   * One hop through a ref: a handler that calls `pulse.current()`, where the
+   * file assigns `pulse.current = () => { … }`. A real project kept a tween on
+   * a ref and called it from a pointermove listener, and the rule read the
+   * listener as clean.
+   */
+  const viaRef = direct.flatMap((h) =>
+    findAll(h.node, (n) => n.type === "CallExpression" && unwrap(n.callee)?.type === "MemberExpression")
+      .map((call) => dottedName(unwrap(call.callee)))
+      .filter((name) => name?.endsWith(".current"))
+      .flatMap((name) =>
+        findAll(
+          ast,
+          (n) =>
+            n.type === "AssignmentExpression" &&
+            dottedName(unwrap(n.left)) === name &&
+            isFunction(unwrap(n.right)),
+        ).map((n) => ({ name: h.name, node: unwrap(n.right) })),
+      ),
+  );
+  return [...direct, ...viaRef];
+}
+
+function directHandlers(ast, events, { followNames = true, perFrame = false } = {}) {
   const handler = (expression) => {
     const node = unwrap(expression);
     if (node?.type === "CallExpression") return node;
@@ -397,6 +422,28 @@ const readsRef = (node) =>
       n.property.name === "current",
   ).length > 0;
 
+/**
+ * Whether a file holds a reduced-motion branch: the query written in code, or
+ * asked by name — `useReducedMotion()`, `prefersReducedMotion()`,
+ * `isReduced()`, `matchMedia(REDUCED_MOTION_QUERY)` — since it is often written
+ * once, in a shared module. "Reduced", not "reduce": an array's `.reduce()` is
+ * not one. A comment that mentions it is not a branch.
+ */
+function hasReducedBranch(file) {
+  if (findAll(file.ast, (node) => spells(node, "prefers-reduced-motion")).length) return true;
+  return (
+    findAll(file.ast, (node) => {
+      if (node.type !== "CallExpression") return false;
+      const name = calleeName(node)?.split(".").at(-1) ?? "";
+      if (/reduced/i.test(name)) return true;
+      return (
+        name === "matchMedia" &&
+        node.arguments.some((arg) => arg.type === "Identifier" && /reduced/i.test(arg.name))
+      );
+    }).length > 0
+  );
+}
+
 /** The calls that add a child to a timeline. */
 const CHILDREN = new Set(["to", "from", "fromTo", "add"]);
 
@@ -1841,25 +1888,20 @@ export const RULES = [
      */
     test(file) {
       if (!file.usesGsap) return [];
-      if (findAll(file.ast, (node) => spells(node, "prefers-reduced-motion")).length) {
-        return [];
-      }
+      if (hasReducedBranch(file)) return [];
       /**
-       * The query is often written once, in a shared module, and asked by name:
-       * `useReducedMotion()`, `prefersReducedMotion()`, `isReduced()`, or
-       * `matchMedia(REDUCED_MOTION_QUERY)`. That is a branch too. "Reduced",
-       * not "reduce", so an array's `.reduce()` is not one.
+       * Every caller decides instead: each file that imports this one holds a
+       * branch. Three projects reported a helper flagged while its only caller
+       * returned early under reduced motion. Only the full audit knows the
+       * importers; the editor and the write hook see one file, and report it.
        */
-      const asksByName = findAll(file.ast, (node) => {
-        if (node.type !== "CallExpression") return false;
-        const name = calleeName(node)?.split(".").at(-1) ?? "";
-        if (/reduced/i.test(name)) return true;
-        return (
-          name === "matchMedia" &&
-          node.arguments.some((arg) => arg.type === "Identifier" && /reduced/i.test(arg.name))
-        );
-      });
-      if (asksByName.length) return [];
+      if (
+        file.importers?.length &&
+        !file.importersUnknown &&
+        file.importers.every((importer) => !importer.parseError && hasReducedBranch(importer))
+      ) {
+        return [];
+      }
 
       const [first] = findAll(file.ast, (node) => {
         const method = tweenMethod(node);

package/lib/source.mjs

@@ -249,7 +249,14 @@ export function fromText(raw, path, display = path) {
      */
     usesGsap:
       /\bfrom ["']gsap(?:\/|["'])/.test(code) ||
-      /\bimport\s+(?!type\b)(?:gsap\b|\{[^}]*\bgsap\b[^}]*\})[^;]*?\bfrom\s*["']/.test(code),
+      /\bimport\s+(?!type\b)(?:gsap\b|\{[^}]*\bgsap\b[^}]*\})[^;]*?\bfrom\s*["']/.test(code) ||
+      /**
+       * Loaded on demand: `loadGsap().then(({ gsap }) => …)` or
+       * `const { gsap } = await import(…)`. A real project's brand loader did
+       * this, and was the one file in eleven the lifecycle rules skipped.
+       */
+      /\(\s*\{[^}]*\bgsap\b[^}]*\}\s*\)\s*=>/.test(code) ||
+      /\{[^}]*\bgsap\b[^}]*\}\s*=\s*await\s+import\s*\(/.test(code),
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehshekari/eslint-plugin-gsap-motion",
-  "version": "4.5.0",
+  "version": "4.6.1",
   "description": "The gsap-motion audit as ESLint rules: GSAP tweens that outlive their component, per-event allocations and missing reduced-motion branches, reported in your editor.",
   "keywords": [
     "eslint",