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

package/README.md

@@ -90,11 +90,14 @@ so a finding waived that way still fails `gsap-motion audit`.
 | `missing-reduced-motion` | warn | An animating file with no `prefers-reduced-motion` branch |
 | `barrel-import` | warn | Importing from `gsap/all`, which pulls in every plugin |
 | `tween-per-frame` | warn | A tween created every frame — in `onUpdate`, the ticker, an Observer callback, `useFrame` or a `requestAnimationFrame` loop |
+| `allocation-per-frame` | warn | A Three.js vector, colour, matrix or quaternion built every frame — in `useFrame`, the ticker, `onUpdate` or a `requestAnimationFrame` loop |
+| `layout-read-per-frame` | info | A layout read — `getBoundingClientRect`, `offsetWidth`, `getComputedStyle` — in a callback that runs every frame |
 | `paint-property` | warn | Animating `filter`, `backdropFilter` or `boxShadow`, which repaints the element every frame |
 | `ungated-hover` | warn | A hover animation with no `(hover: hover)` gate, which a tap starts and nothing ends |
 | `delay-chain` | warn | Three or more tweens in one scope sequenced by `delay`, which is a timeline nobody can retime |
 | `unowned-loop` | info | An infinite repeat that nothing pauses, which keeps the ticker busy off screen |
 | `matchmedia-never-runs` | warn | A matchMedia callback that branches on reduced motion, when every condition needs it |
+| `context-safe-misuse` | warn | A callback made context-safe with the context itself, which runs it at once instead |
 | `stacked-from` | warn | A timeline's `from` or `fromTo` built more than once against the same target |
 | `not-parsed` | warn | A file that uses GSAP and that the audit's parser could not read, so no other rule checked it |
 

package/lib/ast.mjs

@@ -214,26 +214,75 @@ export function tweenMethod(node) {
   return allowed.has(method) ? method : null;
 }
 
-const argumentObject = (call, index) => {
-  const node = unwrap(call.arguments[index]);
-  return node?.type === "ObjectExpression" ? node : null;
-};
+/**
+ * The object literal bound to `name` by a `const`, when the file binds that
+ * name exactly once. Two bindings of one name, in different functions, would
+ * need scope to tell apart; a wrong guess is a false finding, so neither is
+ * read.
+ */
+function constObject(root, name) {
+  const bound = findAll(
+    root,
+    (node) => node.type === "VariableDeclarator" && node.id.type === "Identifier" && node.id.name === name,
+  );
+  if (bound.length !== 1 || !bound[0].init) return null;
+  const declaration = parentOf(root, bound[0]);
+  if (declaration?.kind !== "const") return null;
+  const init = unwrap(bound[0].init);
+  return init.type === "ObjectExpression" ? init : null;
+}
+
+/** `node`'s properties, re-anchored at `site`: a finding lands where the tween uses them. */
+const anchoredAt = (properties, site) =>
+  properties.map((property) => ({ ...property, start: site.start, end: site.end }));
+
+/**
+ * The object a vars argument stands for: a literal, or a `const` bound to one,
+ * with any spread of such a `const` unfolded in place. Vars written once and
+ * shared between a `fromTo`'s ends are how a real film's credits hid two of
+ * seven filter tweens from the audit.
+ */
+function resolveObject(root, node, seen = new Set()) {
+  let target = unwrap(node);
+  let site = null;
+  if (target?.type === "Identifier" && root) {
+    site = target;
+    target = constObject(root, target.name);
+  }
+  if (target?.type !== "ObjectExpression" || seen.has(target)) return null;
+  seen.add(target);
+
+  let unfolded = false;
+  const properties = target.properties.flatMap((property) => {
+    if (property.type !== "SpreadElement") return [property];
+    const spread = resolveObject(root, property.argument, seen);
+    if (!spread) return [property];
+    unfolded = true;
+    return anchoredAt(spread.properties, property);
+  });
+  /** A literal with nothing to unfold is returned as it is, not as a copy. */
+  if (site) return { ...target, start: site.start, end: site.end, properties: anchoredAt(properties, site) };
+  return unfolded ? { ...target, properties } : target;
+}
+
+const argumentObject = (call, index, root) => resolveObject(root, call.arguments[index]);
 
 /**
  * The vars object that holds a tween's own settings — `repeat`, `ease`,
  * `yoyo`: the second argument, a `fromTo`'s third, a timeline's first. `null`
- * when it is not an object literal.
+ * when it is neither an object literal nor a `const` bound to one. Pass the
+ * file's `root` to follow a `const`; without it, only literals are read.
  */
-export const ownVars = (call, method) =>
-  argumentObject(call, method === "fromTo" ? 2 : method === "timeline" ? 0 : 1);
+export const ownVars = (call, method, root) =>
+  argumentObject(call, method === "fromTo" ? 2 : method === "timeline" ? 0 : 1, root);
 
 /**
  * Every vars object a tween call carries, as object literals: both of a
  * `fromTo`'s, a timeline's own, or the tween's.
  */
-export function varsObjects(call, method) {
+export function varsObjects(call, method, root) {
   const indexes = method === "fromTo" ? [1, 2] : method === "timeline" ? [0] : [1];
-  return indexes.map((index) => argumentObject(call, index)).filter(Boolean);
+  return indexes.map((index) => argumentObject(call, index, root)).filter(Boolean);
 }
 
 const FUNCTIONS = new Set([

package/lib/rules.mjs

@@ -49,6 +49,8 @@ import {
 const HINT = {
   matchMediaNeverRuns:
     "A matchMedia callback runs only while at least one of its named conditions matches, and a visitor with no reduced-motion preference matches none of these — so the branch for them is dead code and nothing animates. Add `motion: \"(prefers-reduced-motion: no-preference)\"` beside it, or use two separate `add` calls.",
+  contextSafeMisuse:
+    "The callback of `gsap.matchMedia().add`, `gsap.context` and `useGSAP` receives `(context, contextSafe)`: take the second argument, as in `mm.add(query, (context, contextSafe) => …)`, and wrap the delayed callback in it. `context.add(fn)` runs `fn` straight away instead.",
   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:
@@ -59,6 +61,10 @@ const HINT = {
     "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.",
+  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:
+    "If anything has changed layout since the last frame, this read makes the browser compute it now, every frame. Measure once and again only on resize — a ScrollTrigger's `onRefresh`, or a ResizeObserver — and read the cached value here.",
   paintProperty:
     "Filters and shadows repaint the layer every frame, and the cost grows with the painted area. Animate `opacity` on a pre-blurred or pre-shadowed copy, or move a transform instead, and measure before defending anything else.",
   unownedLoop:
@@ -102,6 +108,7 @@ const HINT = {
 const MESSAGE = {
   easedLoop: "An infinite repeat with an ease other than `none`.",
   tweenPerFrame: "A tween is created here on every frame.",
+  layoutReadPerFrame: "Layout is read here on every frame.",
   unownedLoop: "An infinite repeat that nothing pauses.",
   ungatedHover: "A hover animation with no `(hover: hover)` gate.",
   delayChain: "Three or more tweens in this scope are sequenced by `delay`.",
@@ -171,10 +178,19 @@ function layoutHint(property, percent) {
   const swap = TRANSFORM_FOR[property];
   return swap
     ? `Use \`${swap}\` instead — a compositor-only property.` +
+        (property === "height" ? ` ${HEIGHT_CAVEAT}` : "") +
         (percent ? ` ${PERCENT_CAVEAT}` : "")
     : "Prefer transform and opacity; they never touch layout.";
 }
 
+/**
+ * A scale squashes what is inside. An accordion's text is the usual case, and
+ * a real project kept its `height` tween for exactly that reason, which the
+ * hint above alone would have argued against.
+ */
+const HEIGHT_CAVEAT =
+  "Unless what is inside must keep its shape — an accordion's text: then transition `grid-template-rows` from `0fr` to `1fr`, or use Flip.";
+
 /** Whether a transform's from-value, as written, leaves the element untransformed. */
 function identityTransform(property, value) {
   const v = value.trim().replace(/^["'`]|["'`]$/g, "");
@@ -587,6 +603,36 @@ const PAINT_PROPERTIES = new Set([
   "boxShadow",
 ]);
 
+/** Three's math types: what a render loop allocates when it should reuse. */
+const THREE_MATH = new Set([
+  "Vector2",
+  "Vector3",
+  "Vector4",
+  "Quaternion",
+  "Euler",
+  "Matrix3",
+  "Matrix4",
+  "Color",
+  "Box3",
+  "Sphere",
+  "Ray",
+  "Plane",
+  "Spherical",
+]);
+
+/** Reads that return layout, and so make the browser compute it if it is stale. */
+const LAYOUT_READ_METHODS = new Set(["getBoundingClientRect", "getClientRects"]);
+const LAYOUT_READ_PROPERTIES = new Set([
+  "offsetWidth",
+  "offsetHeight",
+  "offsetTop",
+  "offsetLeft",
+  "clientWidth",
+  "clientHeight",
+  "scrollWidth",
+  "scrollHeight",
+]);
+
 const HOVER_EVENTS = new Set([
   "pointerenter",
   "pointerover",
@@ -685,6 +731,45 @@ function stopped(ast, name) {
   );
 }
 
+/**
+ * Every `add` call on a `gsap.matchMedia()`: made on it directly, or on a name
+ * the file binds it to, at declaration or later.
+ */
+function matchMediaAdds(file) {
+  const media = new Set(
+    findAll(
+      file.ast,
+      (node) =>
+        (node.type === "VariableDeclarator" &&
+          node.id.type === "Identifier" &&
+          /**
+           * `let tl;` has no initializer, and `calleeName` does not accept
+           * null. Every fixture initialised its declarations, so 133 passing
+           * tests missed this; the first real project threw on it and took
+           * the whole audit down with it.
+           */
+          Boolean(node.init) &&
+          calleeName(unwrap(node.init)) === "gsap.matchMedia") ||
+        (node.type === "AssignmentExpression" &&
+          node.left.type === "Identifier" &&
+          calleeName(unwrap(node.right)) === "gsap.matchMedia"),
+    ).map((node) => (node.type === "VariableDeclarator" ? node.id.name : node.left.name)),
+  );
+
+  const onMatchMedia = (call) => {
+    const callee = unwrap(call.callee);
+    if (callee?.type !== "MemberExpression") return false;
+    const object = unwrap(callee.object);
+    if (object?.type === "Identifier") return media.has(object.name);
+    return calleeName(object) === "gsap.matchMedia";
+  };
+
+  return findAll(file.ast, (node) => methodName(node) === "add" && onMatchMedia(node));
+}
+
+/** Nodes a value passes through unchanged on its way to whatever uses it. */
+const TRANSPARENT = new Set(["ParenthesizedExpression", "ChainExpression", "TSAsExpression", "TSNonNullExpression"]);
+
 export const RULES = [
   // --- Lifecycle ------------------------------------------------------------
   {
@@ -968,7 +1053,7 @@ export const RULES = [
       return findAll(file.ast, animates).flatMap(
         (call) => {
           const seen = new Set();
-          return varsObjects(call, tweenMethod(call))
+          return varsObjects(call, tweenMethod(call), file.ast)
             .flatMap((vars) => vars.properties)
             .filter((property) => {
               const key = keyName(property);
@@ -1046,7 +1131,7 @@ export const RULES = [
     test(file) {
       return findAll(file.ast, (node) => tweenMethod(node) !== null).flatMap(
         (call) => {
-          const vars = ownVars(call, tweenMethod(call));
+          const vars = ownVars(call, tweenMethod(call), file.ast);
           if (!vars) return [];
           const repeat = propertyOf(vars, "repeat");
           if (!repeat || numberValue(repeat.value) !== -1) return [];
@@ -1360,6 +1445,91 @@ export const RULES = [
       return findings;
     },
   },
+  {
+    id: "allocation-per-frame",
+    level: "warn",
+    description:
+      "A Three.js vector, colour, matrix or quaternion built every frame — in `useFrame`, the ticker, `onUpdate` or a `requestAnimationFrame` loop",
+    /**
+     * Only Three's math types, by name. Any `new` in a frame allocates, but a
+     * `Set` or a `Map` there is usually deliberate and rarely hot; these are
+     * the objects a render loop builds by the thousand, once per object per
+     * frame, and each has a `set` or `copy` that makes the allocation pointless.
+     */
+    test(file) {
+      const scopes = perFrameScopes(file.ast);
+      if (scopes.length === 0) return [];
+
+      const built = findAll(file.ast, (node) => {
+        if (node.type !== "NewExpression") return false;
+        const name = dottedName(unwrap(node.callee))?.split(".").at(-1);
+        return THREE_MATH.has(name);
+      });
+
+      const reported = new Set();
+      return built.flatMap((node) => {
+        if (reported.has(node.start) || !scopes.some((scope) => contains(scope, node))) {
+          return [];
+        }
+        reported.add(node.start);
+        const name = dottedName(unwrap(node.callee)).split(".").at(-1);
+        return [
+          {
+            index: node.start,
+            message: `A \`${name}\` is allocated here on every frame.`,
+            hint: HINT.allocationPerFrame,
+          },
+        ];
+      });
+    },
+  },
+  {
+    id: "layout-read-per-frame",
+    level: "info",
+    description:
+      "A layout read — `getBoundingClientRect`, `offsetWidth`, `getComputedStyle` — in a callback that runs every frame",
+    /**
+     * Info, because a read is only expensive when something has invalidated
+     * layout since the last frame, and that depends on what else runs — a
+     * transform does not, a `width` tween does. What is certain is that the
+     * value is re-measured every frame when it usually changes only on resize.
+     */
+    test(file) {
+      const scopes = perFrameScopes(file.ast);
+      if (scopes.length === 0) return [];
+
+      const reads = findAll(file.ast, (node) => {
+        if (node.type === "CallExpression") {
+          const name = calleeName(node);
+          return (
+            name === "getComputedStyle" ||
+            name === "window.getComputedStyle" ||
+            LAYOUT_READ_METHODS.has(methodName(node))
+          );
+        }
+        return (
+          node.type === "MemberExpression" &&
+          !node.computed &&
+          LAYOUT_READ_PROPERTIES.has(node.property.name)
+        );
+      });
+
+      const reported = new Set();
+      return reads.flatMap((node) => {
+        if (reported.has(node.start) || !scopes.some((scope) => contains(scope, node))) {
+          return [];
+        }
+        reported.add(node.start);
+        return [
+          {
+            index: node.start,
+            message: MESSAGE.layoutReadPerFrame,
+            hint: HINT.layoutReadPerFrame,
+          },
+        ];
+      });
+    },
+  },
   {
     id: "paint-property",
     level: "warn",
@@ -1374,7 +1544,7 @@ export const RULES = [
 
       return findAll(file.ast, animates).flatMap((call) => {
         const seen = new Set();
-        return varsObjects(call, tweenMethod(call))
+        return varsObjects(call, tweenMethod(call), file.ast)
           .flatMap((vars) => vars.properties)
           .filter((property) => {
             const key = keyName(property);
@@ -1421,7 +1591,7 @@ export const RULES = [
 
       return findAll(file.ast, (node) => tweenMethod(node) !== null).flatMap((call) => {
         if (inside(call)) return [];
-        const vars = ownVars(call, tweenMethod(call));
+        const vars = ownVars(call, tweenMethod(call), file.ast);
         if (!vars) return [];
         const repeat = propertyOf(vars, "repeat");
         if (!repeat || numberValue(repeat.value) !== -1) return [];
@@ -1477,7 +1647,7 @@ export const RULES = [
 
       for (const call of findAll(file.ast, (node) => tweenMethod(node) !== null)) {
         if (chainStart(call) !== call) continue;
-        const vars = ownVars(call, tweenMethod(call));
+        const vars = ownVars(call, tweenMethod(call), file.ast);
         const delay = vars && propertyOf(vars, "delay");
         if (!delay || !(numberValue(delay.value) > 0)) continue;
         const scope = scopeOf(file.ast, call) ?? file.ast;
@@ -1628,35 +1798,6 @@ export const RULES = [
       const REDUCE = /prefers-reduced-motion\s*:\s*reduce/i;
       const PREFERENCE = /prefers-reduced-motion/i;
 
-      /** Names bound to `gsap.matchMedia()` in this file, at declaration or later. */
-      const media = new Set(
-        findAll(
-          file.ast,
-          (node) =>
-            (node.type === "VariableDeclarator" &&
-              node.id.type === "Identifier" &&
-              /**
-               * `let tl;` has no initializer, and `calleeName` does not accept
-               * null. Every fixture initialised its declarations, so 133 passing
-               * tests missed this; the first real project threw on it and took
-               * the whole audit down with it.
-               */
-              Boolean(node.init) &&
-              calleeName(unwrap(node.init)) === "gsap.matchMedia") ||
-            (node.type === "AssignmentExpression" &&
-              node.left.type === "Identifier" &&
-              calleeName(unwrap(node.right)) === "gsap.matchMedia"),
-        ).map((node) => (node.type === "VariableDeclarator" ? node.id.name : node.left.name)),
-      );
-
-      const onMatchMedia = (call) => {
-        const callee = unwrap(call.callee);
-        if (callee?.type !== "MemberExpression") return false;
-        const object = unwrap(callee.object);
-        if (object?.type === "Identifier") return media.has(object.name);
-        return calleeName(object) === "gsap.matchMedia";
-      };
-
       /** The conditions as written: in the call, or in a `const` the file declares once. */
       const conditionsOf = (argument) => {
         const target = unwrap(argument);
@@ -1714,7 +1855,7 @@ export const RULES = [
         }).length > 0;
       };
 
-      return findAll(file.ast, (node) => methodName(node) === "add" && onMatchMedia(node))
+      return matchMediaAdds(file)
         .filter((call) => {
           if (!everyReduces(conditionsOf(call.arguments[0]))) return false;
           const callback = resolveFunction(file.ast, call.arguments[1]);
@@ -1728,6 +1869,93 @@ export const RULES = [
         }));
     },
   },
+  {
+    id: "context-safe-misuse",
+    level: "warn",
+    description:
+      "A callback made context-safe with the context itself, which runs it at once instead",
+    /**
+     * The callback of `gsap.matchMedia().add`, `gsap.context` or `useGSAP`
+     * receives `(context, contextSafe)`. Two ways of getting that wrong both
+     * ship a blank page:
+     *
+     * - `({ contextSafe }) => …` reads `contextSafe` from the context, which has
+     *   none. It is `undefined`, and the first call throws.
+     * - `context.add(fn)` handed on as a callback. `add` with a function runs it
+     *   at once, passing the context, and returns what it returned, so the
+     *   caller receives no callback and `fn` ran with the wrong argument.
+     *
+     * Found in the 4.3 creative A/B: three of 27 runs, in both arms, crashed on
+     * load this way, every one inside a matchMedia. `add` as a statement runs a
+     * block inside the context and is correct; a named `add("onClick", fn)` and
+     * `add(null, fn)` return a wrapper and are correct too. Only an `add` whose
+     * result is used, given a function, is reported.
+     */
+    test(file) {
+      const callbacks = new Set(
+        [
+          ...matchMediaAdds(file).map((call) => call.arguments[1]),
+          ...findAll(
+            file.ast,
+            (node) =>
+              node.type === "CallExpression" &&
+              ["gsap.context", "useGSAP"].includes(calleeName(node)),
+          ).map((call) => call.arguments[0]),
+        ]
+          .map((argument) => resolveFunction(file.ast, argument))
+          .filter(Boolean),
+      );
+
+      /** Is the call's result handed on, rather than thrown away as a statement? */
+      const used = (call) => {
+        let child = call;
+        let parent = parentOf(file.ast, call);
+        while (parent && TRANSPARENT.has(parent.type)) {
+          child = parent;
+          parent = parentOf(file.ast, parent);
+        }
+        if (!parent || parent.type === "ExpressionStatement" || parent.type === "SequenceExpression") {
+          return false;
+        }
+        return !(parent.type === "CallExpression" && parent.callee === child);
+      };
+
+      const findings = [];
+      for (const fn of callbacks) {
+        const [param] = fn.params;
+        if (param?.type === "ObjectPattern") {
+          const property = param.properties.find((p) => keyName(p) === "contextSafe");
+          if (property) {
+            findings.push({
+              index: property.start,
+              message:
+                "`contextSafe` is read from the callback's first argument, the context, which has none: it is undefined, and the first call throws.",
+              hint: HINT.contextSafeMisuse,
+            });
+          }
+          continue;
+        }
+        if (param?.type !== "Identifier") continue;
+        const adds = findAll(fn.body, (node) => {
+          if (methodName(node) !== "add") return false;
+          const receiver = unwrap(unwrap(node.callee).object);
+          return receiver?.type === "Identifier" && receiver.name === param.name;
+        });
+        for (const call of adds) {
+          const target = unwrap(call.arguments[0]);
+          if (!target || target.type === "Literal" || target.type === "TemplateLiteral") continue;
+          if (!isFunction(target) && target.type !== "Identifier") continue;
+          if (!used(call)) continue;
+          findings.push({
+            index: call.start,
+            message: `\`${param.name}.add(fn)\` runs fn at once and returns its result, so what is handed on here is not a callback.`,
+            hint: HINT.contextSafeMisuse,
+          });
+        }
+      }
+      return findings;
+    },
+  },
   {
     id: "stacked-from",
     level: "warn",

package/package.json

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