@mehshekari/eslint-plugin-gsap-motion 3.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mehran.shekari
+
+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.

package/NOTICE.md

@@ -0,0 +1,83 @@
+# Notice
+
+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
+skill writes uses GSAP (`gsap`, its plugins, and `@gsap/react`), which is
+published by GreenSock, now part of Webflow, under the GSAP Standard License:
+<https://gsap.com/standard-license>
+
+In short, at the time of writing: GSAP and every one of its plugins are free to
+use, including in commercial projects. The notable restriction is that GSAP may
+not be used, without Webflow's written consent, in a tool that lets people build
+visual animations without code in competition with Webflow.
+
+That summary is not legal advice. Read the licence itself before relying on it,
+and check it again when you upgrade.
+
+This skill does not bundle or redistribute GSAP. Install it from npm.
+
+"GSAP" and "GreenSock" are trademarks of their respective owners. This project
+is not affiliated with or endorsed by GreenSock or Webflow.

package/README.md

@@ -0,0 +1,101 @@
+# @mehshekari/eslint-plugin-gsap-motion
+
+The [gsap-motion](https://github.com/mehShekari/gsap-motion) audit as ESLint
+rules. It reports the GSAP failures that raise no error — a tween that outlives
+its component, a tween allocated per pointer event, a plugin imported and never
+registered — in your editor and in any lint run.
+
+It runs the audit's own rules on the audit's own parse of each file. So it
+reports exactly what `npx @mehshekari/gsap-motion audit` reports, on the same
+lines, and the audit's
+[measured precision](https://github.com/mehShekari/gsap-motion#measured-precision)
+holds here too.
+
+## Install
+
+```bash
+npm install --save-dev --save-exact @mehshekari/eslint-plugin-gsap-motion
+```
+
+It needs ESLint 9 or 10 with flat config, and Node.js 18.18 or later. Pin the
+exact version: a release can add a rule, or catch a case a rule used to miss,
+and fail a build that passed.
+
+## Configure
+
+```js
+// eslint.config.mjs
+import gsapMotion from "@mehshekari/eslint-plugin-gsap-motion";
+
+export default [
+  // …your own config, with a parser for each kind of file you lint
+  {
+    files: ["**/*.{js,jsx,mjs,ts,tsx}"],
+    ...gsapMotion.configs.recommended,
+  },
+];
+```
+
+`recommended` turns on every rule at the audit's level. It sets no `files` and
+no parser. ESLint must already be able to read the file: `typescript-eslint` for
+TypeScript, and JSX enabled for `.jsx`. The plugin never reads the tree that
+parser builds.
+
+### Plugins registered in another file
+
+`gsap.registerPlugin` is global, and most apps call it once, in an entry file.
+The command line collects registrations across every file it reads. ESLint reads
+one file at a time, so name them:
+
+```js
+{
+  rules: {
+    "gsap-motion/unregistered-plugin": ["error", { registered: ["ScrollTrigger", "SplitText"] }],
+  },
+}
+```
+
+## Waiving a finding
+
+The same waiver as the audit's: the rule's id plus `-ok`, with a reason, on the
+flagged line or in the eight lines above it.
+
+```ts
+/* shared-plugin-id-ok — mounted exactly once, by the root layout. */
+gsap.to("#dot", { motionPath: { path: "#track" } });
+```
+
+An `eslint-disable` comment silences ESLint only. The audit does not read those,
+so a finding waived that way still fails `gsap-motion audit`.
+
+## Rules
+
+| Rule | Level | Catches |
+| --- | --- | --- |
+| `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 |
+| `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 |
+| `never-completes` | error | An `onComplete` that can never run: on a timeline holding a `repeat: -1` child, or on a tween or timeline that repeats forever |
+| `dev-tool-shipped` | error | `GSDevTools` or `MotionPathHelper` imported statically, or unconditional `markers: true` |
+| `dangling-listener` | warn | An event listener that is never removed, including inline handlers that cannot be |
+| `layout-property` | warn | Animating `width`, `height`, `top`, `left`, margins or padding, which forces layout every frame |
+| `trigger-per-item` | warn | A ScrollTrigger created per item in a loop |
+| `eased-loop` | warn | An infinite repeat with an ease, which makes its own seam visible |
+| `eased-scrub` | warn | Easing inside a scrubbed ScrollTrigger, which fights the scrollbar |
+| `late-transform-origin` | warn | A `fromTo` whose origin is only in its to-vars while its from-vars scale, rotate or skew, which leaves an SVG element offset |
+| `missing-reduced-motion` | warn | An animating file with no `prefers-reduced-motion` branch |
+| `barrel-import` | warn | Importing from `gsap/all`, which pulls in every plugin |
+| `not-parsed` | warn | A file that uses GSAP and that the audit's parser could not read, so no other rule checked it |
+
+`not-parsed` is an info finding in the command line; ESLint has no info level.
+
+The plugin checks the files the command line checks: `.js`, `.jsx`, `.mjs`,
+`.ts` and `.tsx`. A file that never mentions GSAP is not parsed at all.
+
+## License
+
+MIT. The bundled parser — acorn, with @sveltejs/acorn-typescript — is MIT too;
+see `NOTICE.md`.

package/index.mjs

@@ -0,0 +1,156 @@
+/**
+ * The gsap-motion audit, as ESLint rules.
+ *
+ * Every rule here is the audit's own rule, run on the audit's own parse of the
+ * file — not on the tree the project's ESLint parser built. So the editor and
+ * `gsap-motion audit` report the same findings on the same lines, the precision
+ * measured for the command line holds here too, and a waiver means the same in
+ * both. The project's parser only has to accept the file; nothing reads its
+ * tree.
+ *
+ * `lib/` is the audit's own `scripts/lib`, copied in by scripts/bundle-audit.mjs
+ * before the package is packed or tested.
+ */
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+
+import { check, mentionsGsap, NOT_PARSED, notParsed } from "./lib/audit.mjs";
+import { RULES } from "./lib/rules.mjs";
+import { fromText, hasSourceExtension } from "./lib/source.mjs";
+
+const pkg = JSON.parse(
+  readFileSync(new URL("./package.json", import.meta.url), "utf8"),
+);
+
+const NAMESPACE = "gsap-motion";
+const DOCS = "https://github.com/mehShekari/gsap-motion#the-audit";
+
+/** ESLint has no info level. The one info finding, `not-parsed`, warns. */
+const severity = (level) => (level === "info" ? "warn" : level);
+
+/**
+ * Parsed once per file, however many of the rules run on it: ESLint hands every
+ * rule the same SourceCode for a file. `null` marks a file the audit does not
+ * read.
+ */
+const sources = new WeakMap();
+
+function sourceFor(context) {
+  const { sourceCode, filename } = context;
+  if (!sources.has(sourceCode)) {
+    /**
+     * The files the command line reads and no others, so the two report the
+     * same findings. A name with no extension — code piped in as `<text>` — is
+     * read as JavaScript with JSX.
+     */
+    const readable = !extname(filename) || hasSourceExtension(filename);
+    const source = readable ? fromText(sourceCode.text, filename) : null;
+    sources.set(sourceCode, source && mentionsGsap(source) ? source : null);
+  }
+  return sources.get(sourceCode);
+}
+
+const MESSAGES = { finding: "{{ message }} {{ hint }}" };
+
+function report(context, finding) {
+  context.report({
+    loc: { line: finding.line, column: finding.column },
+    messageId: "finding",
+    data: { message: finding.message, hint: finding.hint },
+  });
+}
+
+/**
+ * ESLint lints one file at a time, so a plugin registered in another file —
+ * once, in the app's entry — cannot be seen from this one. The command line
+ * collects registrations across the files it audits; here the project names
+ * them.
+ */
+const REGISTERED = [
+  {
+    type: "object",
+    properties: {
+      registered: {
+        type: "array",
+        items: { type: "string" },
+        uniqueItems: true,
+      },
+    },
+    additionalProperties: false,
+  },
+];
+
+function toEslintRule(rule) {
+  return {
+    meta: {
+      type: "problem",
+      docs: { description: rule.description, recommended: true, url: DOCS },
+      messages: MESSAGES,
+      schema: rule.id === "unregistered-plugin" ? REGISTERED : [],
+    },
+    create(context) {
+      const source = sourceFor(context);
+      if (!source || source.parseError) return {};
+      return {
+        Program() {
+          const file = Object.create(source, {
+            registeredElsewhere: {
+              value: new Set(context.options[0]?.registered),
+            },
+          });
+          for (const finding of check(rule, file)) report(context, finding);
+        },
+      };
+    },
+  };
+}
+
+const notParsedRule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "A file that uses GSAP and that the audit's parser could not read, so no other rule checked it",
+      recommended: true,
+      url: DOCS,
+    },
+    messages: MESSAGES,
+    schema: [],
+  },
+  create(context) {
+    const source = sourceFor(context);
+    if (!source?.parseError) return {};
+    return {
+      Program() {
+        const finding = notParsed(source);
+        if (finding) report(context, finding);
+      },
+    };
+  },
+};
+
+const plugin = {
+  meta: { name: pkg.name, version: pkg.version, namespace: NAMESPACE },
+  rules: Object.fromEntries([
+    ...RULES.map((rule) => [rule.id, toEslintRule(rule)]),
+    [NOT_PARSED, notParsedRule],
+  ]),
+  configs: {},
+};
+
+/**
+ * Every rule at the level the command line gives it.
+ *
+ * No `files`: the config applies to whatever the project already lints, and
+ * never widens that to files the project's parser cannot read.
+ */
+plugin.configs.recommended = {
+  name: `${NAMESPACE}/recommended`,
+  plugins: { [NAMESPACE]: plugin },
+  rules: Object.fromEntries([
+    ...RULES.map((rule) => [`${NAMESPACE}/${rule.id}`, severity(rule.level)]),
+    [`${NAMESPACE}/${NOT_PARSED}`, severity("info")],
+  ]),
+};
+
+export default plugin;