@mehshekari/gsap-motion 3.1.0 → 3.1.1

package/README.md

@@ -28,7 +28,7 @@ The audit needs no install. Pin the version, so a new rule cannot fail your
 build without warning:
 
 ```json
-"lint": "eslint && npx @mehshekari/gsap-motion@3.1.0 audit src --quiet"
+"lint": "eslint && npx @mehshekari/gsap-motion@3.1.1 audit src --quiet"
 ```
 
 Or install it with `npm install --save-dev --save-exact @mehshekari/gsap-motion`.
@@ -38,6 +38,9 @@ The command it adds is `gsap-motion`:
 "lint": "eslint && gsap-motion audit src --quiet"
 ```
 
+The same rules also run inside ESLint, so findings appear in your editor:
+[`@mehshekari/eslint-plugin-gsap-motion`](https://www.npmjs.com/package/@mehshekari/eslint-plugin-gsap-motion).
+
 ## Claude Code plugin
 
 The same skill is also a Claude Code plugin:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehshekari/gsap-motion",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Install the gsap-creative-animation Agent Skill, and audit GSAP animation for leaks, jank and accessibility failures — with npx.",
   "keywords": [
     "gsap",

package/skill/SKILL.md

@@ -4,7 +4,7 @@ description: Senior motion engineer for GSAP. Turns a visual or interaction idea
 license: MIT. See LICENSE; GSAP itself is licensed separately, see NOTICE.md
 compatibility: Any Agent Skills client; written for Claude Code. GSAP 3.13+, where every plugin is free. React guidance targets @gsap/react 2.x, React 18/19 and the Next.js App Router. The audit scripts need Node.js 18+ and nothing else.
 metadata:
-  version: "3.1.0"
+  version: "3.1.1"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---

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/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

@@ -498,6 +498,8 @@ export const RULES = [
   {
     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 +539,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()`
@@ -574,6 +578,8 @@ export const RULES = [
   {
     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 +642,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 +668,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 —
@@ -705,6 +715,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 +759,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 +802,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 +831,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 +888,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 +959,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 +1008,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 +1038,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 +1093,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 +1129,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 +1179,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

@@ -131,9 +131,14 @@ 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");
+/**
+ * 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 code = stripComments(raw);
 
   /**
@@ -151,7 +156,11 @@ export function load(path, root) {
         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 +178,7 @@ export function load(path, root) {
       return tree().error;
     },
     path,
-    display: relative(root, path).replace(/\\/g, "/"),
+    display,
     raw,
     code,
     /**
@@ -187,3 +196,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));
+}