@mehshekari/eslint-plugin-gsap-motion 3.1.1 → 3.2.0

package/README.md

@@ -75,6 +75,7 @@ so a finding waived that way still fails `gsap-motion audit`.
 | `orphan-tween` | error | A tween created outside `useGSAP`, `gsap.context` or `contextSafe` in React — never reverted, and doubled by StrictMode |
 | `unmanaged-instance` | error | `matchMedia`, `Observer`, `Draggable`, `ScrollSmoother` or `SplitText` created outside a context and never torn down |
 | `tween-per-event` | error | A new tween allocated on every pointer, scroll or wheel event |
+| `unreverted-context` | warn | A `gsap.context` created on mount — `onMounted`, `onMount`, `useEffect`, `astro:page-load` — that nothing reverts |
 | `state-per-event` | error | React state set in a high-frequency handler — a re-render per frame |
 | `shared-plugin-id` | error | A hardcoded `#id` in MotionPath or MorphSVG config, which two instances of a component will share |
 | `unregistered-plugin` | error | A plugin imported and never registered, whose properties are silently ignored |

package/lib/ast.mjs

@@ -21,10 +21,16 @@ const OPTIONS = {
  * `.ts` is read without JSX, because there `<T>(x) => x` is a generic and
  * `<Type>value` a cast; every other extension is read with it. A `.js` file
  * with JSX is common enough, and JSX never changes how plain JavaScript parses.
+ *
+ * A single-file component's `<script>` is read without JSX too: it is
+ * TypeScript as often as not, and the template where the angle brackets live is
+ * blanked out before it reaches here.
  */
 const TYPESCRIPT = Parser.extend(tsPlugin());
 const TYPESCRIPT_JSX = Parser.extend(tsPlugin({ jsx: true }));
 
+const WITHOUT_JSX = /\.(?:[mc]?ts|vue|svelte|astro)$/;
+
 /**
  * Parses `source` as the grammar its `path` implies.
  *
@@ -34,7 +40,7 @@ const TYPESCRIPT_JSX = Parser.extend(tsPlugin({ jsx: true }));
  */
 export function parse(source, path) {
   const comments = [];
-  const parser = /\.[mc]?ts$/.test(path) ? TYPESCRIPT : TYPESCRIPT_JSX;
+  const parser = WITHOUT_JSX.test(path) ? TYPESCRIPT : TYPESCRIPT_JSX;
   const ast = parser.parse(source, { ...OPTIONS, onComment: comments });
   return { ast, comments };
 }

package/lib/rules.mjs

@@ -51,6 +51,8 @@ const HINT = {
     "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.",
   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.",
   danglingListener:
     "A listener that survives unmount keeps the component's closure — and its DOM nodes — alive. Name the handler and remove it in the cleanup, or pass `{ signal }` from an AbortController and abort it there.",
   tweenPerEvent:
@@ -212,7 +214,7 @@ 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 } = {}) {
+function handlersFor(ast, events, { followNames = true, perFrame = false } = {}) {
   const handler = (expression) => {
     const node = unwrap(expression);
     if (node?.type === "CallExpression") return node;
@@ -242,6 +244,17 @@ function handlersFor(ast, events, { followNames = true } = {}) {
     if (node) handlers.push({ name: `on${prop[1]}`, node });
   }
 
+  /**
+   * R3F's `useFrame(callback)` is a per-frame scope of its own: what is inside
+   * runs on every rendered frame, whatever the pointer is doing.
+   */
+  if (perFrame) {
+    for (const call of findAll(ast, (node) => calleeName(node) === "useFrame")) {
+      const node = handler(call.arguments[0]);
+      if (node) handlers.push({ name: "useFrame", node });
+    }
+  }
+
   return handlers;
 }
 
@@ -493,6 +506,47 @@ export function pluginRegistrations(file) {
   return names;
 }
 
+/**
+ * The mount hooks each adapter uses. A context created in one of them lives as
+ * long as the component does, so something has to revert it when the component
+ * goes.
+ */
+const MOUNT_HOOKS = new Set([
+  "onMounted",
+  "onMount",
+  "onActivated",
+  "useEffect",
+  "useLayoutEffect",
+  "$effect",
+]);
+
+/**
+ * Which mount hook `node` was created in, or null. Astro has no hook: its
+ * equivalent is a listener for `astro:page-load`, which fires on the first load
+ * and after every view transition.
+ */
+function mountHook(ast, node) {
+  /** Nearest first, so a function's own parent is the entry after it. */
+  const ancestors = ancestorsOf(ast, node);
+
+  for (let i = 0; i < ancestors.length; i += 1) {
+    if (!isFunction(ancestors[i])) continue;
+    const parent = ancestors[i + 1];
+    if (parent?.type !== "CallExpression") continue;
+
+    const name = calleeName(parent);
+    if (MOUNT_HOOKS.has(name)) return `\`${name}\``;
+    if (
+      name?.endsWith("addEventListener") &&
+      staticString(parent.arguments[0]) === "astro:page-load"
+    ) {
+      return "the `astro:page-load` handler";
+    }
+  }
+
+  return null;
+}
+
 export const RULES = [
   // --- Lifecycle ------------------------------------------------------------
   {
@@ -575,6 +629,40 @@ export const RULES = [
         }));
     },
   },
+  {
+    id: "unreverted-context",
+    level: "warn",
+    description:
+      "A `gsap.context` created on mount — `onMounted`, `onMount`, `useEffect`, `astro:page-load` — that nothing reverts",
+    /**
+     * Every adapter's teardown rule, in one shape: a context built when the
+     * component mounts holds every tween, ScrollTrigger and matchMedia made
+     * inside it, and reverting it is the whole cleanup. Nothing reverts it here.
+     *
+     * Only contexts created in a mount hook are read. A context built in a
+     * function the module exports — the vanilla `mountReveal(root)` shape — hands
+     * its teardown to the caller, and this file cannot see whether the caller
+     * calls it.
+     */
+    test(file) {
+      const contexts = findAll(
+        file.ast,
+        (node) => calleeName(node) === "gsap.context",
+      );
+
+      return contexts.flatMap((call) => {
+        const hook = mountHook(file.ast, call);
+        if (!hook || tornDown(file.ast, call)) return [];
+        return [
+          {
+            index: call.start,
+            message: `The \`gsap.context\` created in ${hook} is never reverted.`,
+            hint: HINT.unrevertedContext,
+          },
+        ];
+      });
+    },
+  },
   {
     id: "dangling-listener",
     level: "warn",
@@ -699,14 +787,20 @@ export const RULES = [
         );
       });
 
-      return handlersFor(file.ast, STATE_HOT_EVENTS, { followNames: false }).flatMap(
+      return handlersFor(file.ast, STATE_HOT_EVENTS, {
+        followNames: false,
+        perFrame: true,
+      }).flatMap(
         (handler) =>
           setters
             .filter((setter) => contains(handler.node, setter))
             .filter((setter) => !debounced(handler, setter))
             .map((setter) => ({
               index: setter.start,
-              message: `React state setter inside a ${handler.name} handler.`,
+              message:
+                handler.name === "useFrame"
+                  ? "React state setter inside a `useFrame` callback, which runs every frame."
+                  : `React state setter inside a ${handler.name} handler.`,
               hint: HINT.statePerEvent,
             })),
       );

package/lib/source.mjs

@@ -12,7 +12,19 @@ import { extname, join, relative } from "node:path";
 
 import { parse } from "./ast.mjs";
 
-const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs"]);
+const SOURCE_EXTENSIONS = new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".vue",
+  ".svelte",
+  ".astro",
+]);
+
+/** A single-file component: only its `<script>` blocks are code. */
+const SINGLE_FILE = /\.(?:vue|svelte|astro)$/;
 const SKIP_DIRECTORIES = new Set([
   "node_modules",
   ".next",
@@ -131,6 +143,41 @@ export function lineAt(source, index) {
   return line;
 }
 
+/**
+ * A single-file component with everything outside its `<script>` blocks blanked
+ * out, keeping every newline and every offset — so what reaches the parser is
+ * JavaScript, and a finding still points at the right line of the `.vue`,
+ * `.svelte` or `.astro` file.
+ *
+ * A `<script>` whose `type` is not JavaScript — JSON-LD, an import map, a
+ * template — is blanked with the markup. Astro's `---` frontmatter runs on the
+ * server and animates nothing, so it is left out too; the client `<script>` is
+ * what this reads.
+ */
+export function scriptsOnly(raw) {
+  const blank = (text) => text.replace(/[^\n]/g, " ");
+  const JAVASCRIPT = /^(?:module|text\/javascript|application\/javascript|ts|tsx)$/i;
+  const open = /<script\b([^>]*)>/gi;
+
+  let out = "";
+  let index = 0;
+
+  for (let tag = open.exec(raw); tag; tag = open.exec(raw)) {
+    const start = tag.index + tag[0].length;
+    const close = raw.indexOf("</script", start);
+    const end = close === -1 ? raw.length : close;
+    const type = tag[1].match(/\btype\s*=\s*["']([^"']*)["']/i)?.[1];
+    const code = !type || JAVASCRIPT.test(type.trim());
+
+    out += blank(raw.slice(index, start));
+    out += code ? raw.slice(start, end) : blank(raw.slice(start, end));
+    index = end;
+    open.lastIndex = end;
+  }
+
+  return out + blank(raw.slice(index));
+}
+
 /**
  * A file plus everything the rules need, from its text.
  *
@@ -139,7 +186,8 @@ export function lineAt(source, index) {
  * points run the rules on the same parse of the same characters.
  */
 export function fromText(raw, path, display = path) {
-  const code = stripComments(raw);
+  const source = SINGLE_FILE.test(path) ? scriptsOnly(raw) : raw;
+  const code = stripComments(source);
 
   /**
    * Parsed on first use, and once. Most files in a project never mention GSAP,
@@ -151,7 +199,7 @@ export function fromText(raw, path, display = path) {
   const tree = () => {
     if (parsed === undefined) {
       try {
-        parsed = { ...parse(raw, path), error: null };
+        parsed = { ...parse(source, path), error: null };
       } catch (error) {
         parsed = {
           ast: null,

package/package.json

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