@mehshekari/gsap-motion 3.0.0 → 3.1.0

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.0 audit src --quiet"
 ```
 
 Or install it with `npm install --save-dev --save-exact @mehshekari/gsap-motion`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehshekari/gsap-motion",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "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.0"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---

package/skill/scripts/audit-gsap.mjs

@@ -13,10 +13,12 @@
  * 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.
  *
  * Usage — paths resolve from the current directory, so run it from the project
  * root, wherever the skill itself is installed:
@@ -29,7 +31,7 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 
-import { RULES } from "./lib/rules.mjs";
+import { pluginRegistrations, RULES } from "./lib/rules.mjs";
 import { collect, lineAt, load } from "./lib/source.mjs";
 
 /**
@@ -82,6 +84,7 @@ function waived(source, line, ruleId) {
 // --- Run ---------------------------------------------------------------------
 
 const findings = [];
+const sources = [];
 
 for (const path of paths) {
   for (const file of collect(path)) {
@@ -93,20 +96,54 @@ for (const path of paths) {
      */
     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;
-
+    /**
+     * 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: rule.id,
-          level: rule.level,
+          rule: "not-parsed",
+          level: "info",
           file: source.display,
           line,
-          message: hit.message,
-          hint: hit.hint,
+          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.",
         });
       }
+      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;
+
+  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,
+      });
     }
   }
 }