@mehshekari/gsap-motion 3.0.0 → 3.1.1

package/NOTICE.md

@@ -3,6 +3,65 @@
 This skill — its instructions, references, presets, examples, templates and
 scripts — is released under the MIT License. See [LICENSE](LICENSE).
 
+## Third-party code in the audit
+
+`scripts/lib/vendor/parser.mjs` bundles two MIT-licensed packages, so the audit
+can read JavaScript and TypeScript without installing anything. It is generated
+from the versions its first lines name.
+
+### acorn
+
+```text
+MIT License
+
+Copyright (C) 2012-2022 by various contributors (see AUTHORS)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+### @sveltejs/acorn-typescript
+
+```text
+MIT License
+
+Copyright (c) 2022 Tyreal Hu
+Copyright (c) 2025 The Svelte Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## GSAP is licensed separately
 
 **GSAP is not part of this skill, and it is not MIT-licensed.** The code this

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.0.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.0.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/NOTICE.md

@@ -3,6 +3,65 @@
 This skill — its instructions, references, presets, examples, templates and
 scripts — is released under the MIT License. See [LICENSE](LICENSE).
 
+## Third-party code in the audit
+
+`scripts/lib/vendor/parser.mjs` bundles two MIT-licensed packages, so the audit
+can read JavaScript and TypeScript without installing anything. It is generated
+from the versions its first lines name.
+
+### acorn
+
+```text
+MIT License
+
+Copyright (C) 2012-2022 by various contributors (see AUTHORS)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+### @sveltejs/acorn-typescript
+
+```text
+MIT License
+
+Copyright (c) 2022 Tyreal Hu
+Copyright (c) 2025 The Svelte Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## GSAP is licensed separately
 
 **GSAP is not part of this skill, and it is not MIT-licensed.** The code this

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.0.0"
+  version: "3.1.1"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---

package/skill/scripts/audit-gsap.mjs

@@ -13,10 +13,16 @@
  * Rhythm, easing choice and whether an animation earns its place are not
  * checkable and are not attempted — reference/motion-design.md owns those.
  *
- * This is static analysis without a parser, so it is deliberately conservative
- * and will still be wrong sometimes. `info` findings have the loosest match.
- * A wrong finding is a bug in this script; report it rather than working
- * around it.
+ * It reads each file's syntax tree — with a vendored parser, so nothing is
+ * installed — and follows what can be followed inside one file: aliases, a
+ * helper called only from a context, a timeline kept under a name. It does not
+ * follow calls into other files. A file it cannot parse is reported as
+ * `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:
@@ -29,8 +35,9 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 
-import { RULES } from "./lib/rules.mjs";
-import { collect, lineAt, load } from "./lib/source.mjs";
+import { check, mentionsGsap, notParsed } from "./lib/audit.mjs";
+import { pluginRegistrations, RULES } from "./lib/rules.mjs";
+import { collect, load } from "./lib/source.mjs";
 
 /**
  * The project being audited is wherever this is run from, not wherever the
@@ -55,58 +62,50 @@ 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;
+
+    if (source.parseError) {
+      const finding = notParsed(source);
+      if (finding) findings.push(reported(source, finding));
+      continue;
+    }
+
+    sources.push(source);
+  }
+}
+
+/**
+ * Plugin registration is global: `gsap.registerPlugin(ScrollTrigger)` in one
+ * module registers it for every other. What the audited files register between
+ * them is collected before any rule runs, so a section that imports a plugin
+ * the app's entry registers is not reported as unregistered.
+ */
+const registered = new Set(sources.flatMap((source) => [...pluginRegistrations(source)]));
+
+for (const source of sources) {
+  source.registeredElsewhere = registered;
 
-    /**
-     * 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;
-
-    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 rule of RULES) {
+    for (const finding of check(rule, source)) {
+      findings.push(reported(source, finding));
     }
   }
 }