@mehshekari/eslint-plugin-gsap-motion 4.4.2 → 4.6.0

package/README.md

@@ -81,6 +81,7 @@ so a finding waived that way still fails `gsap-motion audit`.
 | `unregistered-plugin` | error | A plugin imported and never registered, whose properties are silently ignored |
 | `never-completes` | error | An `onComplete` that can never run: on a timeline holding a `repeat: -1` child, or on a tween or timeline that repeats forever |
 | `dev-tool-shipped` | error | `GSDevTools` or `MotionPathHelper` imported statically, or unconditional `markers: true` |
+| `ref-read-in-cleanup` | warn | `killTweensOf` given a ref's `.current` in a `useEffect` cleanup, where React has already cleared it at unmount |
 | `dangling-listener` | warn | An event listener that is never removed, including inline handlers that cannot be |
 | `layout-property` | warn | Animating `width`, `height`, `top`, `left`, margins or padding, which forces layout every frame |
 | `trigger-per-item` | warn | A ScrollTrigger created per item in a loop |

package/lib/ast.mjs

@@ -307,7 +307,7 @@ export const contains = (outer, inner) =>
  * returns `null`: an ambiguous handler is left unread rather than guessed at.
  */
 export function resolveFunction(root, node) {
-  const target = unwrap(node);
+  const target = wrappedFunction(unwrap(node));
   if (isFunction(target)) return target;
   if (target?.type !== "Identifier") return null;
 
@@ -318,13 +318,34 @@ export function resolveFunction(root, node) {
       (n.type === "VariableDeclarator" &&
         n.id.type === "Identifier" &&
         n.id.name === target.name &&
-        isFunction(unwrap(n.init))),
+        isFunction(wrappedFunction(unwrap(n.init)))),
   );
   if (declarations.length !== 1) return null;
   const [declaration] = declarations;
   return declaration.type === "FunctionDeclaration"
     ? declaration
-    : unwrap(declaration.init);
+    : wrappedFunction(unwrap(declaration.init));
+}
+
+/**
+ * The function inside a call that hands it back to run later, unchanged in
+ * what it does: `contextSafe(fn)`, `ctx.add(null, fn)` and `useCallback(fn, deps)`.
+ * The handler the skill recommends is wrapped in contextSafe, and following
+ * names stopped at the wrapper, so a tween per pointer event went unreported.
+ * Anything else is returned as it was.
+ */
+function wrappedFunction(node) {
+  if (node?.type !== "CallExpression") return node;
+  const name = calleeName(node)?.split(".").at(-1);
+  if (name === "contextSafe" || name === "useCallback") return unwrap(node.arguments[0]);
+  if (
+    name === "add" &&
+    unwrap(node.arguments[0])?.type === "Literal" &&
+    unwrap(node.arguments[0]).value === null
+  ) {
+    return unwrap(node.arguments[1]);
+  }
+  return node;
 }
 
 const PARENTS = new WeakMap();
@@ -581,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,13 +54,15 @@ 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.",
+    "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:
     "Keep it under a name and revert it when the component goes: `onUnmounted` in Vue, the function returned from `onMount` or `$effect` in Svelte, the `useEffect` cleanup in React, `astro:before-swap` in Astro. Everything created inside the context goes with it.",
   tweenPerFrame:
     "A tween per frame allocates an object per frame, and each one fights the last. Create a `gsap.quickTo()` or `quickSetter()` once outside the callback and call it inside — or, for scroll, scrub a timeline instead of writing values by hand.",
+  refReadInCleanup:
+    "So nothing is killed, and the tweens outlive the component. Capture the element in the effect body — `const el = ref.current` — and kill through that in the cleanup, or build the tweens in a useGSAP or gsap.context body, whose revert needs no ref.",
   allocationPerFrame:
     "Every frame's object is garbage by the next, and the collector reclaims it in a pause that lands as a dropped frame. Build it once, outside the callback — at module scope, or in a ref or useMemo — and reuse it with `.set()` or `.copy()`.",
   layoutReadPerFrame:
@@ -96,7 +98,7 @@ const HINT = {
   unregisteredPlugin:
     "An unregistered plugin's properties are ignored without an error — the animation simply does nothing.",
   missingReducedMotion:
-    "Reduced motion is a design, not an off switch: decide what the motion was saying and say it without the travel. Note that the reduced branch must set the END state — a `from` that never runs leaves its target invisible.",
+    "Reduced motion is a design, not an off switch: decide what the motion was saying and say it without the travel. Note that the reduced branch must set the END state — a `from` that never runs leaves its target invisible. If the branch lives in the module that calls this one, waive it here and name that caller.",
   devToolImport:
     "A static import ships regardless of any `if` around the call. Load it with a dynamic `import()` behind a NODE_ENV check, or bake its output in and delete it.",
   markers: 'Gate it: `markers: process.env.NODE_ENV === "development"`.',
@@ -248,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;
@@ -310,6 +337,113 @@ function debounced(handler, node) {
   );
 }
 
+/**
+ * Whether a tween's target is a local the enclosing effect captured, and that
+ * effect's code kills that local's tweens: `const el = ref.current` in the body,
+ * `gsap.killTweensOf(el)` in the cleanup. Found on the corpus, where it was
+ * reported as an orphan.
+ *
+ * Only a captured local counts. `killTweensOf(ref.current)` in a passive
+ * cleanup kills nothing at unmount — React has already cleared the ref — and
+ * that is `ref-read-in-cleanup`'s to say.
+ */
+function killedThroughCapture(ast, node) {
+  if (!isGsapCall(node)) return false;
+  const target = unwrap(node.arguments[0]);
+  if (target?.type !== "Identifier") return false;
+
+  const effect = ancestorsOf(ast, node).find((fn) => {
+    if (!isFunction(fn)) return false;
+    const call = parentOf(ast, fn);
+    return (
+      call?.type === "CallExpression" &&
+      call.arguments[0] === fn &&
+      EFFECTS.has(calleeName(call)?.split(".").at(-1))
+    );
+  });
+  if (!effect) return false;
+
+  const captured = findAll(
+    effect,
+    (n) => n.type === "VariableDeclarator" && n.id.type === "Identifier" && n.id.name === target.name,
+  ).length > 0;
+  if (!captured) return false;
+
+  /**
+   * In the cleanup — the function the effect returns — and nowhere else. A
+   * kill at the top of the body stops the previous run's tweens before
+   * starting new ones; it does nothing at unmount. Nine true corpus findings
+   * did exactly that, and the first version of this check let them go.
+   */
+  const cleanups = cleanupsOf(ast, effect);
+
+  const names = (arg) => {
+    const value = unwrap(arg);
+    if (value?.type === "Identifier") return [value.name];
+    if (value?.type === "ArrayExpression") return value.elements.flatMap((e) => (e ? names(e) : []));
+    return [];
+  };
+  return cleanups.some(
+    (cleanup) =>
+      findAll(
+        cleanup,
+        (n) =>
+          n.type === "CallExpression" &&
+          calleeName(n)?.endsWith("killTweensOf") &&
+          n.arguments.some((arg) => names(arg).includes(target.name)),
+      ).length > 0,
+  );
+}
+
+const EFFECTS = new Set(["useEffect", "useLayoutEffect"]);
+
+/** The functions an effect callback returns: its cleanups. */
+function cleanupsOf(ast, effect) {
+  const cleanups = findAll(
+    effect,
+    (n) => n.type === "ReturnStatement" && n.argument && scopeOf(ast, n) === effect,
+  )
+    .map((n) => unwrap(n.argument))
+    .filter(isFunction);
+  if (effect.type === "ArrowFunctionExpression" && effect.expression && isFunction(unwrap(effect.body))) {
+    cleanups.push(unwrap(effect.body));
+  }
+  return cleanups;
+}
+
+/** Whether `node` reads a ref: a `.current` anywhere inside it. */
+const readsRef = (node) =>
+  findAll(
+    node,
+    (n) =>
+      n.type === "MemberExpression" &&
+      !n.computed &&
+      n.property.type === "Identifier" &&
+      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"]);
 
@@ -341,6 +475,22 @@ function tornDown(ast, node) {
   const kept = keptUnder(ast, node);
   if (endsUnder(kept?.name)) return true;
 
+  /**
+   * A second name for it: `active = timeline`, then `active?.kill()` in the
+   * cleanup. Found on the corpus, in a preview whose timeline was built in a
+   * helper and handed to a variable the effect owns.
+   */
+  if (kept?.name) {
+    const aliases = findAll(ast, (n) => {
+      const from = n.type === "AssignmentExpression" ? n.right : n.type === "VariableDeclarator" ? n.init : null;
+      const to = n.type === "AssignmentExpression" ? n.left : n.type === "VariableDeclarator" ? n.id : null;
+      return unwrap(from)?.type === "Identifier" && unwrap(from).name === kept.name && to?.type === "Identifier";
+    }).map((n) => (n.type === "AssignmentExpression" ? n.left.name : n.id.name));
+    if (aliases.some(endsUnder)) return true;
+  }
+
+  if (killedThroughCapture(ast, node)) return true;
+
   const fn = scopeOf(ast, node);
   if (!isFunction(fn)) return false;
 
@@ -886,6 +1036,62 @@ export const RULES = [
       });
     },
   },
+  {
+    id: "ref-read-in-cleanup",
+    level: "warn",
+    description:
+      "`killTweensOf` given a ref's `.current` in a `useEffect` cleanup, where React has already cleared it at unmount",
+    /**
+     * At unmount React detaches a DOM ref before it runs passive cleanups, so
+     * `ref.current` is null there and the kill finds nothing. A corpus project
+     * did this in three cleanups, and fifteen tweens outlived their component.
+     *
+     * Narrow on purpose. Only `useEffect`: when a layout cleanup runs relative
+     * to ref detachment is not something this rule is sure of. Only
+     * `killTweensOf`, whose argument is the element: a ref that holds a timeline
+     * — `tlRef.current?.kill()` — is not cleared by React, and is correct.
+     */
+    test(file) {
+      if (!file.isReact) return [];
+      const effects = findAll(
+        file.ast,
+        (n) => n.type === "CallExpression" && calleeName(n)?.split(".").at(-1) === "useEffect",
+      )
+        .map((call) => unwrap(call.arguments[0]))
+        .filter(isFunction);
+
+      return effects.flatMap((effect) =>
+        cleanupsOf(file.ast, effect).flatMap((cleanup) => {
+          /** A local the cleanup itself reads from a ref: `const root = rootRef.current`. */
+          const fromRef = new Set(
+            findAll(
+              cleanup,
+              (n) =>
+                n.type === "VariableDeclarator" &&
+                n.id.type === "Identifier" &&
+                n.init &&
+                readsRef(n.init),
+            ).map((n) => n.id.name),
+          );
+          const viaRef = (arg) =>
+            readsRef(arg) ||
+            findAll(arg, (n) => n.type === "Identifier" && fromRef.has(n.name)).length > 0;
+
+          return findAll(
+            cleanup,
+            (n) =>
+              n.type === "CallExpression" &&
+              calleeName(n)?.endsWith("killTweensOf") &&
+              n.arguments.some(viaRef),
+          ).map((call) => ({
+            index: call.start,
+            message: "`killTweensOf` reads a ref in a useEffect cleanup, which React has already cleared at unmount.",
+            hint: HINT.refReadInCleanup,
+          }));
+        }),
+      );
+    },
+  },
   {
     id: "dangling-listener",
     level: "warn",
@@ -1682,7 +1888,14 @@ export const RULES = [
      */
     test(file) {
       if (!file.usesGsap) return [];
-      if (findAll(file.ast, (node) => spells(node, "prefers-reduced-motion")).length) {
+      if (hasReducedBranch(file)) return [];
+      /**
+       * 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.
+       */
+      if (file.importers?.length && file.importers.every((importer) => !importer.parseError && hasReducedBranch(importer))) {
         return [];
       }
 

package/lib/source.mjs

@@ -241,7 +241,15 @@ export function fromText(raw, path, display = path) {
       /\bfrom ["']react["']/.test(code) ||
       /\bfrom ["']@gsap\/react["']/.test(code),
     isClient: /^\s*["']use client["']/m.test(code),
-    usesGsap: /\bfrom ["']gsap(?:\/|["'])/.test(code),
+    /**
+     * GSAP itself, or a binding named `gsap` from anywhere: a project's own
+     * wrapper (`import { gsap } from "@/core/motion/gsap"`) is common, and
+     * reading only the package left orphan-tween and missing-reduced-motion
+     * blind to every file in a real project that used one.
+     */
+    usesGsap:
+      /\bfrom ["']gsap(?:\/|["'])/.test(code) ||
+      /\bimport\s+(?!type\b)(?:gsap\b|\{[^}]*\bgsap\b[^}]*\})[^;]*?\bfrom\s*["']/.test(code),
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehshekari/eslint-plugin-gsap-motion",
-  "version": "4.4.2",
+  "version": "4.6.0",
   "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",