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

package/README.md

@@ -90,6 +90,8 @@ 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 |

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

@@ -61,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:
@@ -104,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`.",
@@ -173,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, "");
@@ -589,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",
@@ -1009,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);
@@ -1087,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 [];
@@ -1401,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",
@@ -1415,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);
@@ -1462,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 [];
@@ -1518,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;

package/package.json

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