@mehshekari/gsap-motion 3.1.0 → 3.2.0

package/skill/scripts/audit-gsap.mjs

@@ -20,6 +20,10 @@
  * `not-parsed`, never passed as clean. A wrong finding is a bug in this script;
  * report it rather than working around it.
  *
+ * What happens to each file — the rules, waivers, `not-parsed` — is in
+ * lib/audit.mjs, which the ESLint plugin runs too. This file finds the files,
+ * collects what they register between them, and prints.
+ *
  * Usage — paths resolve from the current directory, so run it from the project
  * root, wherever the skill itself is installed:
  *   node <skill-dir>/scripts/audit-gsap.mjs [path...]     # default: src
@@ -31,8 +35,9 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 
+import { check, mentionsGsap, notParsed } from "./lib/audit.mjs";
 import { pluginRegistrations, RULES } from "./lib/rules.mjs";
-import { collect, lineAt, load } from "./lib/source.mjs";
+import { collect, load } from "./lib/source.mjs";
 
 /**
  * The project being audited is wherever this is run from, not wherever the
@@ -57,62 +62,29 @@ for (const path of paths) {
   }
 }
 
-// --- Escape hatch ------------------------------------------------------------
-
-/**
- * The same shape many repos already use for their own lint waivers, on
- * purpose: one way to say "yes, and here is why", not two.
- *
- * A hatch is the rule's own id plus `-ok`, on the flagged line or in the eight
- * above it, and it waives that rule and nothing else — silencing a shared id
- * cannot also silence a layout property on the same line. The lookback is eight
- * because a reason usually stands above a whole declaration rather than beside
- * one line of it.
- *
- * Every hatch must carry its reason. A bare token with no sentence after it is
- * a rule someone turned off rather than answered, and once this gates a build
- * that distinction has to stay visible in review.
- */
-const LOOKBACK = 8;
-
-function waived(source, line, ruleId) {
-  const lines = source.split("\n");
-  const from = Math.max(0, line - 1 - LOOKBACK);
-  return lines.slice(from, line).join("\n").includes(`${ruleId}-ok`);
-}
-
 // --- Run ---------------------------------------------------------------------
 
 const findings = [];
 const sources = [];
 
+/** A finding as the report shows it: under the file's display path, no column. */
+const reported = (source, finding) => ({
+  rule: finding.rule,
+  level: finding.level,
+  file: source.display,
+  line: finding.line,
+  message: finding.message,
+  hint: finding.hint,
+});
+
 for (const path of paths) {
   for (const file of collect(path)) {
     const source = load(file, ROOT);
+    if (!mentionsGsap(source)) continue;
 
-    /**
-     * A file that never mentions GSAP has nothing these rules can say. Checked
-     * once here rather than in every rule.
-     */
-    if (!source.usesGsap && !/\bgsap\./.test(source.code)) continue;
-
-    /**
-     * What was not checked is reported as not checked. A file that uses GSAP
-     * and does not parse gets no rule's verdict — a silent skip would read as
-     * clean.
-     */
     if (source.parseError) {
-      const { line, message } = source.parseError;
-      if (!waived(source.raw, line, "not-parsed")) {
-        findings.push({
-          rule: "not-parsed",
-          level: "info",
-          file: source.display,
-          line,
-          message: `Not checked: the file could not be parsed (${message}).`,
-          hint: "No rule ran on this file. If it is valid JavaScript or TypeScript, the audit's parser is wrong — report it with this line.",
-        });
-      }
+      const finding = notParsed(source);
+      if (finding) findings.push(reported(source, finding));
       continue;
     }
 
@@ -132,18 +104,8 @@ for (const source of sources) {
   source.registeredElsewhere = registered;
 
   for (const rule of RULES) {
-    for (const hit of rule.test(source)) {
-      const line = lineAt(source.raw, hit.index);
-      if (waived(source.raw, line, rule.id)) continue;
-
-      findings.push({
-        rule: rule.id,
-        level: rule.level,
-        file: source.display,
-        line,
-        message: hit.message,
-        hint: hit.hint,
-      });
+    for (const finding of check(rule, source)) {
+      findings.push(reported(source, finding));
     }
   }
 }

package/skill/scripts/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/skill/scripts/lib/audit.mjs

@@ -0,0 +1,91 @@
+/**
+ * One file through the audit, shared by the command line and the ESLint plugin.
+ *
+ * The runner decides which files to read and how to print them; ESLint decides
+ * both for the plugin. What happens to a file in between — whether the rules
+ * look at it at all, what a file that does not parse reports, where a finding
+ * lands and whether a waiver answers it — is decided here, once, so the two
+ * entry points cannot disagree.
+ */
+import { lineAt } from "./source.mjs";
+
+/**
+ * A file that never mentions GSAP has nothing these rules can say. Checked once
+ * per file rather than in every rule, and before anything is parsed.
+ */
+export function mentionsGsap(source) {
+  return source.usesGsap || /\bgsap\./.test(source.code);
+}
+
+// --- Escape hatch ------------------------------------------------------------
+
+/**
+ * The same shape many repos already use for their own lint waivers, on
+ * purpose: one way to say "yes, and here is why", not two.
+ *
+ * A hatch is the rule's own id plus `-ok`, on the flagged line or in the eight
+ * above it, and it waives that rule and nothing else — silencing a shared id
+ * cannot also silence a layout property on the same line. The lookback is eight
+ * because a reason usually stands above a whole declaration rather than beside
+ * one line of it.
+ *
+ * Every hatch must carry its reason. A bare token with no sentence after it is
+ * a rule someone turned off rather than answered, and once this gates a build
+ * that distinction has to stay visible in review.
+ */
+const LOOKBACK = 8;
+
+export function waived(raw, line, ruleId) {
+  const lines = raw.split("\n");
+  const from = Math.max(0, line - 1 - LOOKBACK);
+  return lines.slice(from, line).join("\n").includes(`${ruleId}-ok`);
+}
+
+// --- Findings ----------------------------------------------------------------
+
+/** 0-indexed column of a character offset, as ESLint counts columns. */
+function columnAt(raw, index) {
+  return Math.max(0, index - (raw.lastIndexOf("\n", index - 1) + 1));
+}
+
+export const NOT_PARSED = "not-parsed";
+
+/**
+ * What was not checked is reported as not checked. A file that uses GSAP and
+ * does not parse gets no rule's verdict — a silent skip would read as clean.
+ *
+ * Returns null for a file that parsed, and for one whose waiver answers it.
+ */
+export function notParsed(source) {
+  const error = source.parseError;
+  if (!error || waived(source.raw, error.line, NOT_PARSED)) return null;
+  return {
+    rule: NOT_PARSED,
+    level: "info",
+    line: error.line,
+    column: error.column,
+    message: `Not checked: the file could not be parsed (${error.message}).`,
+    hint: "No rule ran on this file. If it is valid JavaScript or TypeScript, the audit's parser is wrong — report it with this line.",
+  };
+}
+
+/**
+ * What one rule reports on one parsed file: each finding placed on its line and
+ * column, and dropped when a waiver answers it.
+ */
+export function check(rule, source) {
+  const findings = [];
+  for (const hit of rule.test(source)) {
+    const line = lineAt(source.raw, hit.index);
+    if (waived(source.raw, line, rule.id)) continue;
+    findings.push({
+      rule: rule.id,
+      level: rule.level,
+      line,
+      column: columnAt(source.raw, hit.index),
+      message: hit.message,
+      hint: hit.hint,
+    });
+  }
+  return findings;
+}

package/skill/scripts/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,11 +506,54 @@ 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 ------------------------------------------------------------
   {
     id: "orphan-tween",
     level: "error",
+    description:
+      "A tween created outside `useGSAP`, `gsap.context` or `contextSafe` in React — never reverted, and doubled by StrictMode",
     /**
      * A GSAP tween call inside a function but outside every context — module
      * scope is not the target. Contexts are recognised under the names the file
@@ -537,6 +593,8 @@ export const RULES = [
   {
     id: "unmanaged-instance",
     level: "error",
+    description:
+      "`matchMedia`, `Observer`, `Draggable`, `ScrollSmoother` or `SplitText` created outside a context and never torn down",
     /**
      * Torn down as `tornDown` reads it: kept under a name — through any chain
      * called on it, or a helper's return — that has `.revert()` or `.kill()`
@@ -571,9 +629,45 @@ 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",
+    description:
+      "An event listener that is never removed, including inline handlers that cannot be",
     /**
      * Adds and removes are paired by event and by the handler's name as
      * written, across the file — not by counting calls. A handler that is not a
@@ -636,6 +730,8 @@ export const RULES = [
   {
     id: "tween-per-event",
     level: "error",
+    description:
+      "A new tween allocated on every pointer, scroll or wheel event",
     /**
      * A GSAP tween call inside a high-frequency handler, followed by name when
      * it can be. A debounced one, one in a completion callback, and one behind
@@ -660,6 +756,8 @@ export const RULES = [
   {
     id: "state-per-event",
     level: "error",
+    description:
+      "React state set in a high-frequency handler — a re-render per frame",
     /**
      * A bare `setX(…)` call — not a member call such as `el.style.setProperty`,
      * which is exactly what a pointer handler should do, and not a timer —
@@ -689,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,
             })),
       );
@@ -705,6 +809,8 @@ export const RULES = [
   {
     id: "layout-property",
     level: "warn",
+    description:
+      "Animating `width`, `height`, `top`, `left`, margins or padding, which forces layout every frame",
     /**
      * The layout keys of every vars object a tween carries — both of a
      * `fromTo`'s — on any receiver, so a timeline child counts. One finding per
@@ -747,6 +853,8 @@ export const RULES = [
   {
     id: "trigger-per-item",
     level: "warn",
+    description:
+      "A ScrollTrigger created per item in a loop",
     /**
      * A `scrollTrigger` property inside a loop body: the callback of `.forEach`
      * or `.map`, or a `for`, `for…of` or `for…in` statement. One finding per
@@ -788,6 +896,8 @@ export const RULES = [
   {
     id: "eased-loop",
     level: "warn",
+    description:
+      "An infinite repeat with an ease, which makes its own seam visible",
     /**
      * The tween's own vars — a `fromTo`'s to-vars — on any receiver, so a
      * timeline child counts. Keys at the top level only: a `stagger` object's
@@ -815,6 +925,8 @@ export const RULES = [
   {
     id: "eased-scrub",
     level: "warn",
+    description:
+      "Easing inside a scrubbed ScrollTrigger, which fights the scrollbar",
     /**
      * A GSAP call scrubbed anywhere in its arguments — `scrub: false` aside —
      * with a string ease other than `"none"` in those arguments or, for a
@@ -870,6 +982,8 @@ export const RULES = [
   {
     id: "never-completes",
     level: "error",
+    description:
+      "An `onComplete` that can never run: on a timeline holding a `repeat: -1` child, or on a tween or timeline that repeats forever",
     /**
      * `onComplete` and `repeat: -1` anywhere in a GSAP call's arguments; for a
      * timeline, its children and any `eventCallback("onComplete", …)` from
@@ -939,6 +1053,8 @@ export const RULES = [
   {
     id: "late-transform-origin",
     level: "warn",
+    description:
+      "A `fromTo` whose origin is only in its to-vars while its from-vars scale, rotate or skew, which leaves an SVG element offset",
     /**
      * Any `.fromTo(target, fromVars, toVars)` whose two vars are object
      * literals. Keys are read at the top level of each, and a transform's
@@ -986,6 +1102,8 @@ export const RULES = [
   {
     id: "shared-plugin-id",
     level: "error",
+    description:
+      "A hardcoded `#id` in MotionPath or MorphSVG config, which two instances of a component will share",
     /**
      * Any property naming a target geometry whose value is a fixed `#id`: a
      * string or a template literal with nothing interpolated, including the
@@ -1014,6 +1132,8 @@ export const RULES = [
   {
     id: "unregistered-plugin",
     level: "error",
+    description:
+      "A plugin imported and never registered, whose properties are silently ignored",
     /**
      * Registered means named anywhere inside the arguments of a
      * `registerPlugin` call — not mentioned anywhere after one, and under its
@@ -1067,6 +1187,8 @@ export const RULES = [
   {
     id: "missing-reduced-motion",
     level: "warn",
+    description:
+      "An animating file with no `prefers-reduced-motion` branch",
     /**
      * A branch is the query written in code — a string, a template or JSX
      * text. A comment that mentions it is not a branch. A file that only sets
@@ -1101,6 +1223,8 @@ export const RULES = [
   {
     id: "dev-tool-shipped",
     level: "error",
+    description:
+      "`GSDevTools` or `MotionPathHelper` imported statically, or unconditional `markers: true`",
     /**
      * A static import declaration that brings in a dev tool, by a specifier's
      * name or, for a bare or default import, by its path. A type-only import
@@ -1149,6 +1273,8 @@ export const RULES = [
   {
     id: "barrel-import",
     level: "warn",
+    description:
+      "Importing from `gsap/all`, which pulls in every plugin",
     /** An import or re-export whose module is `gsap/all`. */
     test(file) {
       return file.ast.body

package/skill/scripts/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,10 +143,51 @@ export function lineAt(source, index) {
   return line;
 }
 
-/** A file plus everything the rules need, read once. */
-export function load(path, root) {
-  const raw = readFileSync(path, "utf8");
-  const code = stripComments(raw);
+/**
+ * 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.
+ *
+ * The command line reads the text from disk, through `load`. The ESLint plugin
+ * passes the text ESLint already holds, with the file's path, so both entry
+ * points run the rules on the same parse of the same characters.
+ */
+export function fromText(raw, path, display = path) {
+  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,
@@ -146,12 +199,16 @@ export function load(path, root) {
   const tree = () => {
     if (parsed === undefined) {
       try {
-        parsed = { ...parse(raw, path), error: null };
+        parsed = { ...parse(source, path), error: null };
       } catch (error) {
         parsed = {
           ast: null,
           comments: [],
-          error: { message: error.message, line: error.loc?.line ?? 1 },
+          error: {
+            message: error.message,
+            line: error.loc?.line ?? 1,
+            column: error.loc?.column ?? 0,
+          },
         };
       }
     }
@@ -169,7 +226,7 @@ export function load(path, root) {
       return tree().error;
     },
     path,
-    display: relative(root, path).replace(/\\/g, "/"),
+    display,
     raw,
     code,
     /**
@@ -187,3 +244,17 @@ export function load(path, root) {
     usesGsap: /\bfrom ["']gsap(?:\/|["'])/.test(code),
   };
 }
+
+/** A file on disk, read once, shown by its path from `root`. */
+export function load(path, root) {
+  return fromText(
+    readFileSync(path, "utf8"),
+    path,
+    relative(root, path).replace(/\\/g, "/"),
+  );
+}
+
+/** Whether `collect` reads files with this path's extension. */
+export function hasSourceExtension(path) {
+  return SOURCE_EXTENSIONS.has(extname(path));
+}