@mehshekari/gsap-motion 3.0.0 → 3.1.0

package/skill/scripts/lib/rules.mjs

@@ -11,11 +11,92 @@
  * `{ index, message, hint }`. `level` is "error" (a bug), "warn" (a likely
  * bug or a real cost) or "info" (worth a look, higher false-positive rate).
  *
+ * Rules read `file.ast`, the syntax tree `ast.mjs` builds. A file that does not
+ * parse never reaches a rule: the runner reports it as `not-parsed`.
+ *
  * Every rule has fixtures in `scripts/test/rules.test.mjs`: a case it must fire
  * on and a case it must stay quiet on. A wrong finding in either direction is
  * fixed by adding the case there first and watching it fail.
  */
-import { blockAfter, parenSpan, within } from "./source.mjs";
+import {
+  ancestorsOf,
+  calleeName,
+  chainStart,
+  contains,
+  dottedName,
+  findAll,
+  gsapContexts,
+  isFunction,
+  isGsapCall,
+  keptUnder,
+  keyName,
+  methodName,
+  moduleSource,
+  numberValue,
+  ownVars,
+  parentOf,
+  propertyOf,
+  resolveFunction,
+  scopeOf,
+  staticString,
+  timelineLinks,
+  tweenMethod,
+  unwrap,
+  varsObjects,
+} from "./ast.mjs";
+
+/** What each rule says, in one place. */
+const HINT = {
+  orphanTween:
+    "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.",
+  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:
+    "One tween allocated per event, each fighting the last. Create a `gsap.quickTo()` once and call it from the handler — or, for work that only matters once resizing stops, debounce it.",
+  statePerEvent:
+    "A re-render per frame so one element can move a few pixels. State owns what exists; GSAP owns how it moves — use a ref and quickTo.",
+  triggerPerItem:
+    "Each carries its own start/end maths on every scroll frame. If the items belong to one visual moment, use one trigger with a stagger. Per-item is right only when they genuinely reveal independently — pinned card stacks, for instance.",
+  easedLoop:
+    'The tween decelerates into its own restart, so the loop seam becomes visible. Use `ease: "none"`, or `yoyo: true` if it should breathe.',
+  easedScrub:
+    "The scrollbar is the playhead, so an ease fights the visitor's own scrolling and reads as lag. Use `ease: \"none\"` on the children and let `scrub: 1` do the smoothing.",
+  neverCompletesOwn:
+    "An endless repeat never completes. Use `onRepeat` for something that should happen every cycle, or give it a finite `repeat`.",
+  neverCompletesChild:
+    'The child gives the timeline an effectively infinite duration, and a tween added after it does not end it. Hand over at a position instead — `.call(fn, [], "label+=0.5")` fires when the playhead passes — or run the loop as its own tween outside the timeline.',
+  lateTransformOrigin:
+    "On an SVG element GSAP holds the element in place when its origin changes, and that correction outlives the tween: it ends offset, silently — a circle grown from 0 about its centre lands a whole radius off. Put `transformOrigin` or `svgOrigin` in the from-vars, or set it before the tween. HTML elements are unaffected.",
+  sharedPluginId:
+    "useGSAP scopes the selectors it resolves itself, but MotionPath and MorphSVG resolve their own config against the whole document. Mount this component twice and both instances drive the first one's geometry, silently. Namespace it with useId().",
+  unregisteredPlugin:
+    "An unregistered plugin's properties are ignored without an error — the animation simply does nothing.",
+  missingReducedMotion:
+    "Reduced motion is a design, not an off switch: decide what the motion was saying and say it without the travel. Note that the reduced branch must set the END state — a `from` that never runs leaves its target invisible.",
+  devToolImport:
+    "A static import ships regardless of any `if` around the call. Load it with a dynamic `import()` behind a NODE_ENV check, or bake its output in and delete it.",
+  markers: 'Gate it: `markers: process.env.NODE_ENV === "development"`.',
+  barrelImport:
+    "Import each from its own subpath — `gsap/ScrollTrigger` — so the bundler can drop the ones this route does not use.",
+};
+
+/** Messages that do not vary with what was found. */
+const MESSAGE = {
+  easedLoop: "An infinite repeat with an ease other than `none`.",
+  easedScrub: "Easing inside a scrubbed ScrollTrigger timeline.",
+  neverCompletesChild:
+    "An endlessly repeating child in a timeline with an `onComplete`, which therefore never fires.",
+  lateTransformOrigin:
+    "The transform origin is only in this `fromTo`'s to-vars, while its from-vars scale, rotate or skew.",
+};
+
+/** Whether a string, template chunk or JSX text spells `text`. Comments are not nodes. */
+const spells = (node, text) =>
+  (node.type === "Literal" && typeof node.raw === "string" && node.raw.includes(text)) ||
+  (node.type === "TemplateElement" && node.value.raw.includes(text)) ||
+  (node.type === "JSXText" && node.value.includes(text));
 
 /** Properties whose animation forces the browser to re-run layout. */
 const LAYOUT_PROPERTIES = [
@@ -62,157 +143,354 @@ const TRANSFORM_FOR = {
 const PERCENT_CAVEAT =
   "Careful with percentages: `top: 50%` is half the containing block, `yPercent: 50` is half the element itself. Either wrap it in a full-height box and translate that — the percentages then agree — or measure the container once and translate in pixels.";
 
-/** Events that fire many times a second. Global: every occurrence is scanned. */
-const HOT_EVENTS =
-  /(pointermove|mousemove|touchmove|onMouseMove|onPointerMove|"scroll"|'scroll'|wheel)/g;
-
-/** Every `gsap.to/from/fromTo/set(` call site, as offsets. */
-const tweenCalls = (code) => [
-  ...code.matchAll(/\bgsap\.(to|from|fromTo|set|timeline)\s*\(/g),
-];
+/**
+ * The hint for an animated layout property: the transform that replaces it,
+ * and the percentage trap when the value is a percentage.
+ */
+function layoutHint(property, percent) {
+  const swap = TRANSFORM_FOR[property];
+  return swap
+    ? `Use \`${swap}\` instead — a compositor-only property.` +
+        (percent ? ` ${PERCENT_CAVEAT}` : "")
+    : "Prefer transform and opacity; they never touch layout.";
+}
 
-const find = (code, pattern) => [...code.matchAll(pattern)];
+/** Whether a transform's from-value, as written, leaves the element untransformed. */
+function identityTransform(property, value) {
+  const v = value.trim().replace(/^["'`]|["'`]$/g, "");
+  return property.startsWith("scale")
+    ? /^1(?:\.0+)?$/.test(v)
+    : /^-?0(?:\.0+)?(?:deg|rad)?$/.test(v);
+}
 
 /** An import from `gsap/*` that is a plugin needing `registerPlugin`. */
 const PLUGIN_NAME =
   /(?:Plugin|Trigger|Text|Flip|Observer|Draggable|Ease|Smoother|Bounce|Wiggle)$/;
 
 /**
- * Whether the instance constructed at `index` is kept under a name and
- * reverted or killed through that name.
- *
- * This used to ask whether `.revert(` or `.kill(` appeared anywhere in the
- * file, so one unrelated `tl.kill()` exempted every instance beside it.
+ * Events that fire many times a second, by the name a listener is given — not
+ * a substring anywhere in the file, which could not include `resize` without
+ * reporting every `ResizeObserver`.
  */
-function tornDown(code, index) {
-  const kept = code
-    .slice(Math.max(0, index - 200), index)
-    .match(/([\w$][\w$.]*)\s*=\s*$/);
-  if (!kept) return false;
-  const name = kept[1].replace(/[.$]/g, "\\$&");
-  return new RegExp(
-    `(?<![\\w$.])${name}\\s*\\??\\.\\s*(?:revert|kill)\\s*\\(`,
-  ).test(code);
-}
+const HOT_EVENTS = new Set([
+  "pointermove",
+  "pointerrawupdate",
+  "mousemove",
+  "touchmove",
+  "scroll",
+  "wheel",
+  "resize",
+]);
 
 /**
- * Every call to `method` (`addEventListener` / `removeEventListener`), with
- * the event name and handler read out of its arguments.
- *
- * Pairing by event and handler rather than counting calls: two adds and two
- * removes used to pass even when both removes were for the same event, and an
- * inline arrow — which no remove can ever reach — passed whenever any remove
- * existed. A dynamic event name cannot be judged statically, so it is skipped.
+ * A resize handler that sets state is how a component learns its width: a
+ * render per resize, but a render deciding what exists rather than a frame of
+ * motion. `state-per-event` leaves it out; a tween per resize is still a tween
+ * per event.
  */
-function listenerCalls(code, method) {
-  return find(code, new RegExp(`\\b${method}\\s*\\(`, "g")).map((m) => {
-    const open = m.index + m[0].length - 1;
-    const span = parenSpan(code, open);
-    const args = span ? code.slice(open + 1, span[1]) : "";
-    const event = args.match(/^\s*(["'`])([\w:-]+)\1\s*,\s*/);
-    if (!event) return { index: m.index, event: null };
-
-    const rest = args.slice(event[0].length);
-    const inline = /^(?:async\b|function\b|\(|[\w$]+\s*=>)/.test(rest);
-    return {
-      index: m.index,
-      event: event[2],
-      inline,
-      handler: inline ? null : (rest.match(/^[\w$.]+/)?.[0] ?? null),
-      /** Removed by an AbortController, or by the browser after one call. */
-      selfCleaning: /\bsignal\b|\bonce\s*:\s*true/.test(rest),
-    };
-  });
+const STATE_HOT_EVENTS = new Set(
+  [...HOT_EVENTS].filter((event) => event !== "resize"),
+);
+
+/** `addEventListener` or `removeEventListener` when `node` calls one, on any receiver. */
+function listenerMethod(node) {
+  if (node.type !== "CallExpression") return null;
+  const callee = unwrap(node.callee);
+  const name =
+    callee?.type === "Identifier"
+      ? callee.name
+      : callee?.type === "MemberExpression" && !callee.computed
+        ? callee.property.name
+        : null;
+  return name === "addEventListener" || name === "removeEventListener" ? name : null;
 }
 
 /**
- * The argument spans of the `.to(` / `.from(` / `.fromTo(` calls — or of
- * whichever `methods` are asked for — chained on from `cursor`, following the
- * chain through labels and other calls.
+ * Every handler for one of `events`, as `{ name, node }`: the second argument
+ * of an `addEventListener` whose first names that event, or the expression of a
+ * JSX prop for it. A wrapping call — `debounce(fn, 150)` — is kept whole. With
+ * `followNames`, a handler passed by name is followed to its declaration when
+ * the file declares exactly one function of that name.
  */
-function chainedTweens(code, cursor, methods = ["to", "from", "fromTo"]) {
-  const spans = [];
-  for (;;) {
-    const next = code.slice(cursor).match(/^\s*\.\s*([\w$]+)\s*\(/);
-    if (!next) return spans;
-    const open = cursor + next[0].length - 1;
-    const span = parenSpan(code, open);
-    if (!span) return spans;
-    if (methods.includes(next[1])) spans.push([open, span[1]]);
-    cursor = span[1] + 1;
+function handlersFor(ast, events, { followNames = true } = {}) {
+  const handler = (expression) => {
+    const node = unwrap(expression);
+    if (node?.type === "CallExpression") return node;
+    if (!followNames && !isFunction(node)) return null;
+    return resolveFunction(ast, node);
+  };
+  const handlers = [];
+
+  for (const call of findAll(ast, (node) => listenerMethod(node) === "addEventListener")) {
+    const event = staticString(call.arguments[0]);
+    if (event === null || !events.has(event) || !call.arguments[1]) continue;
+    const node = handler(call.arguments[1]);
+    if (node) handlers.push({ name: event, node });
   }
+
+  const props = findAll(
+    ast,
+    (node) => node.type === "JSXAttribute" && node.name.type === "JSXIdentifier",
+  );
+  for (const attribute of props) {
+    const prop = attribute.name.name.match(
+      /^on(PointerMove|MouseMove|TouchMove|Scroll|Wheel)(?:Capture)?$/,
+    );
+    if (!prop || !events.has(prop[1].toLowerCase())) continue;
+    if (attribute.value?.type !== "JSXExpressionContainer") continue;
+    const node = handler(attribute.value.expression);
+    if (node) handlers.push({ name: `on${prop[1]}`, node });
+  }
+
+  return handlers;
 }
 
 /**
- * What is added to the timeline created by the `gsap.timeline(` match `call`,
- * whose arguments close at `close`: the argument spans of its children, and
- * whether an `onComplete` is attached through `eventCallback`.
+ * Whether `node` runs once the events stop rather than once per event: the
+ * handler is a `debounce(…)` call, or `node` sits inside a `setTimeout` that
+ * the same handler also clears.
+ */
+function debounced(handler, node) {
+  const timer = (name) => (n) => {
+    const called = calleeName(n);
+    return called === name || called === `window.${name}`;
+  };
+  const wrapper = handler.node.type === "CallExpression" ? calleeName(handler.node) : null;
+  if (wrapper === "debounce" || wrapper?.endsWith(".debounce")) return true;
+  if (!findAll(handler.node, timer("clearTimeout")).length) return false;
+  return findAll(handler.node, timer("setTimeout")).some(
+    (call) => call !== node && contains(call, node),
+  );
+}
+
+/** The calls that add a child to a timeline. */
+const CHILDREN = new Set(["to", "from", "fromTo", "add"]);
+
+const TEARDOWN = new Set(["kill", "revert"]);
+const FINISH = new Set(["progress", "totalProgress"]);
+
+/**
+ * Whether the value built at `node` is torn down by hand somewhere in the file:
+ * kept under a name that is `.kill()`ed or `.revert()`ed, or finished with
+ * `.progress(1)`, which completes it so GSAP lets it go.
  *
- * Both are read from the chain on the call itself and from every chain on the
- * variable it was kept in — including one that starts with a label, which is
- * how a sequence usually opens. Those uses are read only up to the next
- * declaration of the same name, so two functions that each keep a `tl` do not
- * lend each other their children.
+ * Followed through one helper. When a function returns the value — alone, or as
+ * an element of an array — every call to that function must keep the result, or
+ * that element, under a name that is torn down. Found on the corpus: a component
+ * that builds its timeline and trigger in `getProjectsSt()` and kills what the
+ * effect destructures from it.
  */
-function timelineCalls(code, call, close) {
-  const CHILDREN = ["to", "from", "fromTo", "add"];
-  const children = chainedTweens(code, close + 1, CHILDREN);
-  const callbacks = chainedTweens(code, close + 1, ["eventCallback"]);
-
-  const kept = code
-    .slice(Math.max(0, call.index - 80), call.index)
-    .match(/([\w$]+)\s*=\s*$/);
-  if (kept) {
-    const name = kept[1].replace(/\$/g, "\\$");
-    const redeclared = code
-      .slice(close)
-      .search(new RegExp(`\\b(?:const|let|var)\\s+${name}\\b`));
-    const end = redeclared === -1 ? code.length : close + redeclared;
-    const uses = new RegExp(`(?<![\\w$.])${name}(?=\\s*\\.\\s*[\\w$]+\\s*\\()`, "g");
-
-    for (const use of code.slice(close, end).matchAll(uses)) {
-      const cursor = close + use.index + use[0].length;
-      children.push(...chainedTweens(code, cursor, CHILDREN));
-      callbacks.push(...chainedTweens(code, cursor, ["eventCallback"]));
+function tornDown(ast, node) {
+  const endsUnder = (name) =>
+    Boolean(name) &&
+    findAll(ast, (n) => {
+      const method = methodName(n);
+      if (!method) return false;
+      const ends =
+        TEARDOWN.has(method) || (FINISH.has(method) && numberValue(n.arguments[0]) === 1);
+      return ends && dottedName(unwrap(n.callee).object) === name;
+    }).length > 0;
+
+  const kept = keptUnder(ast, node);
+  if (endsUnder(kept?.name)) return true;
+
+  const fn = scopeOf(ast, node);
+  if (!isFunction(fn)) return false;
+
+  const holds = (expression) => {
+    const value = unwrap(expression);
+    if (!value) return false;
+    if (value === node) return true;
+    if (value.type === "CallExpression" && chainStart(value) === node) return true;
+    return value.type === "Identifier" && kept?.name === value.name;
+  };
+
+  const returned = findAll(
+    fn,
+    (n) => n.type === "ReturnStatement" && n.argument && scopeOf(ast, n) === fn,
+  ).map((n) => n.argument);
+  if (fn.type === "ArrowFunctionExpression" && fn.expression) returned.push(fn.body);
+
+  let slot = null;
+  for (const expression of returned) {
+    const value = unwrap(expression);
+    if (holds(value)) {
+      slot = "whole";
+      break;
+    }
+    if (value?.type === "ArrayExpression") {
+      const index = value.elements.findIndex((element) => element && holds(element));
+      if (index !== -1) {
+        slot = index;
+        break;
+      }
     }
   }
+  if (slot === null) return false;
+
+  const holder = parentOf(ast, fn);
+  const name =
+    fn.type === "FunctionDeclaration"
+      ? fn.id?.name
+      : holder?.type === "VariableDeclarator" &&
+          holder.init === fn &&
+          holder.id.type === "Identifier"
+        ? holder.id.name
+        : null;
+  if (!name) return false;
 
-  const completes = callbacks.some(([open, end]) =>
-    /^\(\s*["'`]onComplete["'`]/.test(code.slice(open, end)),
+  const calls = findAll(
+    ast,
+    (n) =>
+      n.type === "CallExpression" &&
+      unwrap(n.callee)?.type === "Identifier" &&
+      unwrap(n.callee).name === name,
+  );
+  return (
+    calls.length > 0 &&
+    calls.every((call) => {
+      const parent = parentOf(ast, call);
+      const target =
+        parent?.type === "VariableDeclarator" && parent.init === call
+          ? parent.id
+          : parent?.type === "AssignmentExpression" && parent.right === call
+            ? parent.left
+            : null;
+      if (!target) return false;
+      if (slot === "whole") return endsUnder(dottedName(target));
+      const element = target.type === "ArrayPattern" ? target.elements[slot] : null;
+      return element?.type === "Identifier" && endsUnder(element.name);
+    })
   );
-  return { children, completes };
 }
 
 /**
- * The top-level arguments of the call whose parentheses span `[open, close]`,
- * as `[start, end]` pairs. A comma inside brackets, braces or a string does not
- * separate arguments.
+ * Whether `node`, inside a high-frequency handler, runs less often than once
+ * per event: inside a completion callback — `onComplete`, `onStart`,
+ * `onReverseComplete`, `onInterrupt` — of something the handler started, or
+ * behind an in-flight flag the handler raises first,
+ * `if (!busy.current) { busy.current = true; … }`.
  */
-function callArgs(code, open, close) {
-  const args = [];
-  let depth = 0;
-  let quote = "";
-  let start = open + 1;
-
-  for (let i = open + 1; i < close; i += 1) {
-    const c = code[i];
-
-    if (quote) {
-      if (c === "\\") i += 1;
-      else if (c === quote) quote = "";
-      continue;
+function notPerEvent(ast, handler, node) {
+  for (const ancestor of ancestorsOf(ast, node)) {
+    if (ancestor === handler.node) return false;
+    if (
+      ancestor.type === "Property" &&
+      /^on(?:Complete|Start|ReverseComplete|Interrupt)$/.test(keyName(ancestor) ?? "") &&
+      isFunction(unwrap(ancestor.value))
+    ) {
+      return true;
     }
-    if (c === '"' || c === "'" || c === "`") quote = c;
-    else if ("([{".includes(c)) depth += 1;
-    else if (")]}".includes(c)) depth -= 1;
-    else if (c === "," && depth === 0) {
-      args.push([start, i]);
-      start = i + 1;
+    if (ancestor.type === "IfStatement" && contains(ancestor.consequent, node)) {
+      const test = unwrap(ancestor.test);
+      const flag =
+        test?.type === "UnaryExpression" && test.operator === "!"
+          ? dottedName(test.argument)
+          : null;
+      const raised =
+        flag !== null &&
+        findAll(ancestor.consequent, (n) => {
+          if (n.type !== "AssignmentExpression" || dottedName(n.left) !== flag) return false;
+          const value = unwrap(n.right);
+          return value?.type === "Literal" && value.value === true;
+        }).length > 0;
+      if (raised) return true;
     }
   }
+  return false;
+}
+
+/** Listener targets that outlive every component: the window, the document and its root elements. */
+const GLOBAL_TARGETS = new Set([
+  "window",
+  "document",
+  "document.body",
+  "document.documentElement",
+  "globalThis",
+  "self",
+  "visualViewport",
+  "window.visualViewport",
+]);
 
-  if (code.slice(start, close).trim()) args.push([start, close]);
-  return args;
+/**
+ * Whether `target` is an element or object the file builds itself — every
+ * value it is given comes from `new …` or `createElement` — and so takes its
+ * listeners with it when it goes.
+ */
+function createdHere(ast, target) {
+  const builds = (value) => {
+    const v = unwrap(value);
+    return (
+      v?.type === "NewExpression" ||
+      ["createElement", "createElementNS", "cloneNode"].includes(methodName(v))
+    );
+  };
+  if (builds(target)) return true;
+  if (target.type !== "Identifier") return false;
+
+  const assignments = findAll(
+    ast,
+    (n) =>
+      (n.type === "VariableDeclarator" &&
+        n.id.type === "Identifier" &&
+        n.id.name === target.name &&
+        n.init) ||
+      (n.type === "AssignmentExpression" && dottedName(n.left) === target.name),
+  );
+  return (
+    assignments.length > 0 &&
+    assignments.every((n) => builds(n.type === "VariableDeclarator" ? n.init : n.right))
+  );
+}
+
+/** A value that is the same on every call: a literal, a plain template, `undefined`. */
+const isConstant = (node) => {
+  const value = unwrap(node);
+  return (
+    value?.type === "Literal" ||
+    staticString(value) !== null ||
+    (value?.type === "Identifier" && value.name === "undefined")
+  );
+};
+
+/**
+ * The plugins a file registers, by the names they are imported under from
+ * `gsap/*`, so `ScrollTrigger as ST` registered as `ST` is `ScrollTrigger`.
+ * Registration is global, so the runner unions these across every audited file
+ * before any rule runs.
+ */
+export function pluginRegistrations(file) {
+  const names = new Set();
+  if (!file.ast) return names;
+
+  const imported = new Map();
+  for (const declaration of file.ast.body) {
+    if (declaration.type !== "ImportDeclaration") continue;
+    const from = declaration.source.value;
+    if (typeof from !== "string" || !/^gsap\/[\w/-]+$/.test(from)) continue;
+    for (const specifier of declaration.specifiers) {
+      const name =
+        specifier.type === "ImportSpecifier"
+          ? (specifier.imported.name ?? specifier.imported.value)
+          : specifier.type === "ImportDefaultSpecifier"
+            ? from.split("/").pop()
+            : null;
+      if (name) imported.set(specifier.local.name, name);
+    }
+  }
+
+  const registrations = findAll(file.ast, (node) => {
+    const name = calleeName(node);
+    return name === "registerPlugin" || name?.endsWith(".registerPlugin");
+  });
+  for (const call of registrations) {
+    for (const argument of call.arguments) {
+      for (const id of findAll(argument, (n) => n.type === "Identifier")) {
+        names.add(imported.get(id.name) ?? id.name);
+      }
+    }
+  }
+  return names;
 }
 
 export const RULES = [
@@ -220,29 +498,25 @@ export const RULES = [
   {
     id: "orphan-tween",
     level: "error",
+    /**
+     * 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
+     * gives them, and a helper counts as inside when every use of it is a call
+     * from inside one. A value torn down by hand — see `tornDown` — is not
+     * reported: "nothing reverts it" would be false.
+     */
     test(file) {
       if (!file.isReact || !file.usesGsap) return [];
+      const inside = gsapContexts(file.ast);
 
-      return tweenCalls(file.code)
-        .filter((m) => m[1] !== "set" && !within(file.contexts, m.index))
-        .filter((m) => {
-          /**
-           * Only tweens inside some function — module-scope constants are not
-           * the target here.
-           *
-           * This used to read `\b(useEffect|useLayoutEffect|function|=>)\s*[({]`.
-           * `\b` needs a word character beside it and `=>` has none, so the
-           * arrow alternative could never match: every tween in an arrow-function
-           * handler, which is most of React, was silently exempt. `function`
-           * only matched the anonymous `function (`, never `function Name(`.
-           */
-          const before = file.code.slice(0, m.index);
-          return /(?:\bfunction\b[^(]*\(|=>)/.test(before.slice(-400));
-        })
-        .map((m) => ({
-          index: m.index,
-          message: `\`gsap.${m[1]}\` is created outside any useGSAP/gsap.context scope.`,
-          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. This check does not follow calls: a helper that tweens reads as outside even when only the body calls it — keep the measuring in the helper and the tween in the body.",
+      return findAll(file.ast, (node) => isGsapCall(node))
+        .filter((call) => !inside(call))
+        .filter((call) => ancestorsOf(file.ast, call).some(isFunction))
+        .filter((call) => !tornDown(file.ast, call))
+        .map((call) => ({
+          index: call.start,
+          message: `\`gsap.${methodName(call)}\` is created outside any useGSAP/gsap.context scope.`,
+          hint: HINT.orphanTween,
         }));
     },
   },
@@ -263,41 +537,97 @@ export const RULES = [
   {
     id: "unmanaged-instance",
     level: "error",
+    /**
+     * 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()`
+     * called on it somewhere in the file, optional chaining included.
+     */
     test(file) {
-      const constructors =
-        /\b(?:gsap\.(matchMedia)|(Observer|Draggable|ScrollSmoother)\.create|new (SplitText))\s*\(/g;
-
-      return find(file.code, constructors)
-        .filter((m) => !within(file.contexts, m.index))
-        .filter((m) => !tornDown(file.code, m.index))
-        .map((m) => ({
-          index: m.index,
-          message: `\`${m[1] ?? m[2] ?? m[3]}\` is created outside any useGSAP/gsap.context scope and never torn down.`,
-          hint: "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.",
+      const inside = gsapContexts(file.ast);
+      const CREATORS = new Set(["Observer", "Draggable", "ScrollSmoother", "ScrollTrigger"]);
+
+      const label = (node) => {
+        if (node.type === "NewExpression") {
+          const callee = unwrap(node.callee);
+          return callee?.type === "Identifier" && callee.name === "SplitText"
+            ? "SplitText"
+            : null;
+        }
+        if (node.type !== "CallExpression") return null;
+        const name = calleeName(node);
+        if (name === "gsap.matchMedia") return "matchMedia";
+        const [owner, method, extra] = name?.split(".") ?? [];
+        return method === "create" && extra === undefined && CREATORS.has(owner)
+          ? owner
+          : null;
+      };
+      return findAll(file.ast, (node) => label(node) !== null)
+        .filter((node) => !inside(node))
+        .filter((node) => !tornDown(file.ast, node))
+        .map((node) => ({
+          index: node.start,
+          message: `\`${label(node)}\` is created outside any useGSAP/gsap.context scope and never torn down.`,
+          hint: HINT.unmanagedInstance,
         }));
     },
   },
   {
     id: "dangling-listener",
     level: "warn",
+    /**
+     * 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
+     * plain name — an inline function, or `fn.bind(this)`, which makes a new
+     * function each call — can never be matched by a remove. `signal` and
+     * `once: true` are read from the options object. A dynamic event name
+     * cannot be judged statically, so it is skipped.
+     *
+     * Only a target that can outlive the code is reported. An element or object
+     * the file creates takes its listeners with it. Outside React, where nothing
+     * says when code stops running, only the window and the document can: a
+     * listener on a page's own button lasts exactly as long as the button.
+     */
     test(file) {
+      const listeners = (method) =>
+        findAll(file.ast, (node) => listenerMethod(node) === method).flatMap((call) => {
+          const event = staticString(call.arguments[0]);
+          const handler = unwrap(call.arguments[1]);
+          if (event === null || !/^[\w:-]+$/.test(event) || !handler) return [];
+          const options = unwrap(call.arguments[2]);
+          const once = unwrap(propertyOf(options, "once")?.value);
+          const callee = unwrap(call.callee);
+          const target = callee.type === "MemberExpression" ? unwrap(callee.object) : null;
+          return [
+            {
+              global: target === null || GLOBAL_TARGETS.has(dottedName(target)),
+              created: target !== null && createdHere(file.ast, target),
+              index: callee.type === "MemberExpression" ? callee.property.start : callee.start,
+              event,
+              handler: dottedName(handler),
+              inline: isFunction(handler) || dottedName(handler) === null,
+              selfCleaning:
+                Boolean(propertyOf(options, "signal")) ||
+                (once?.type === "Literal" && once.value === true),
+            },
+          ];
+        });
+
       const removed = new Set(
-        listenerCalls(file.code, "removeEventListener")
+        listeners("removeEventListener")
           .filter((call) => call.handler)
           .map((call) => `${call.event}|${call.handler}`),
       );
 
-      return listenerCalls(file.code, "addEventListener")
-        .filter((call) => call.event && !call.selfCleaning)
-        .filter(
-          (call) => call.inline || !removed.has(`${call.event}|${call.handler}`),
-        )
+      return listeners("addEventListener")
+        .filter((call) => !call.selfCleaning && !call.created)
+        .filter((call) => file.isReact || call.global)
+        .filter((call) => call.inline || !removed.has(`${call.event}|${call.handler}`))
         .map((call) => ({
           index: call.index,
           message: call.inline
             ? `An inline \`${call.event}\` listener, which no removeEventListener can reach.`
             : `\`${call.event}\` listener \`${call.handler}\` is added and never removed.`,
-          hint: "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.",
+          hint: HINT.danglingListener,
         }));
     },
   },
@@ -306,114 +636,151 @@ export const RULES = [
   {
     id: "tween-per-event",
     level: "error",
+    /**
+     * 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
+     * an in-flight flag run less than once per event, and are not reported.
+     */
     test(file) {
-      const findings = [];
-
-      for (const handler of find(file.code, HOT_EVENTS)) {
-        const span = blockAfter(file.code, handler.index);
-        if (!span) continue;
-
-        for (const call of tweenCalls(file.code)) {
-          if (call[1] === "set" || !within([span], call.index)) continue;
-          findings.push({
-            index: call.index,
-            message: `\`gsap.${call[1]}\` inside a high-frequency handler (${handler[1]}).`,
-            hint: "One tween allocated per event, each fighting the last. Create a `gsap.quickTo()` once and call it from the handler.",
-          });
-        }
-      }
+      const calls = findAll(file.ast, (node) => isGsapCall(node));
 
-      return findings;
+      return handlersFor(file.ast, HOT_EVENTS).flatMap((handler) =>
+        calls
+          .filter((call) => contains(handler.node, call))
+          .filter((call) => !debounced(handler, call))
+          .filter((call) => !notPerEvent(file.ast, handler, call))
+          .map((call) => ({
+            index: call.start,
+            message: `\`gsap.${methodName(call)}\` inside a high-frequency handler (${handler.name}).`,
+            hint: HINT.tweenPerEvent,
+          })),
+      );
     },
   },
   {
     id: "state-per-event",
     level: "error",
+    /**
+     * 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 —
+     * inside an inline high-frequency handler other than resize.
+     *
+     * A handler passed by name is not followed here, unlike tween-per-event. A
+     * named scroll handler is usually a scroll-spy setting a discrete value — a
+     * section id, a boolean — and React skips the render when that value has not
+     * changed, so "a render per frame" would be false and, at error level, would
+     * fail correct code. Telling a continuous value from a discrete one is a
+     * precision question for the corpus, not something to guess.
+     *
+     * A setter called with a constant — `null`, a boolean, a literal — is not
+     * reported either: once the state holds that value React skips the render,
+     * so it costs one render, not one per frame. The corpus found
+     * `onScroll={() => setHoveredCard(null)}`.
+     */
     test(file) {
       if (!file.isReact) return [];
-      const findings = [];
-
-      for (const handler of find(file.code, HOT_EVENTS)) {
-        const span = blockAfter(file.code, handler.index);
-        if (!span) continue;
-
-        for (const setter of find(file.code, /\bset[A-Z]\w*\s*\(/g)) {
-          if (!within([span], setter.index)) continue;
-          findings.push({
-            index: setter.index,
-            message: `React state setter inside a ${handler[1]} handler.`,
-            hint: "A re-render per frame so one element can move a few pixels. State owns what exists; GSAP owns how it moves — use a ref and quickTo.",
-          });
-        }
-      }
+      const setters = findAll(file.ast, (node) => {
+        if (node.type !== "CallExpression") return false;
+        const callee = unwrap(node.callee);
+        return (
+          callee?.type === "Identifier" &&
+          /^set(?!Timeout$|Interval$)[A-Z]\w*$/.test(callee.name) &&
+          !(node.arguments.length <= 1 && node.arguments.every(isConstant))
+        );
+      });
 
-      return findings;
+      return handlersFor(file.ast, STATE_HOT_EVENTS, { followNames: false }).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.`,
+              hint: HINT.statePerEvent,
+            })),
+      );
     },
   },
   {
     id: "layout-property",
     level: "warn",
+    /**
+     * 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
+     * key per call: a `fromTo` that names `height` in both vars animates one
+     * property, and says so once, where it first appears. `gsap.set` animates
+     * nothing, and is skipped: measuring with `set(el, { height: "auto" })` is
+     * not a frame of layout.
+     */
     test(file) {
-      const pattern = new RegExp(
-        `\\b(${LAYOUT_PROPERTIES.join("|")})\\s*:\\s*(?!["'\\s]*$)`,
-        "g",
-      );
+      const LAYOUT = new Set(LAYOUT_PROPERTIES);
+      const animates = (node) => {
+        const method = tweenMethod(node);
+        return method !== null && method !== "set";
+      };
 
-      return tweenCalls(file.code).flatMap((call) => {
-        const span = blockAfter(file.code, call.index);
-        if (!span) return [];
-        const body = file.code.slice(span[0], span[1]);
-
-        return [...body.matchAll(pattern)]
-          .filter((m) => !/^\s*(?:\/\/|\*)/.test(m[0]))
-          .map((m) => {
-            const swap = TRANSFORM_FOR[m[1]];
-            /**
-             * Whether the flagged value is a percentage of something.
-             *
-             * Braces are allowed through rather than treated as a terminator:
-             * the value is very often a template literal, and `` `${n}%` ``
-             * carries a closing brace immediately before the `%` that was
-             * meant to be found. The comma and the newline are what actually
-             * end a value here.
-             */
-            const percent = new RegExp(`\\b${m[1]}\\s*:[^,\\n]{0,80}%`).test(
-              body,
-            );
-
-            return {
-              index: span[0] + m.index,
-              message: `Animating \`${m[1]}\` forces layout on every frame.`,
-              hint: swap
-                ? `Use \`${swap}\` instead — a compositor-only property.` +
-                  (percent ? ` ${PERCENT_CAVEAT}` : "")
-                : "Prefer transform and opacity; they never touch layout.",
-            };
-          });
-      });
+      return findAll(file.ast, animates).flatMap(
+        (call) => {
+          const seen = new Set();
+          return varsObjects(call, tweenMethod(call))
+            .flatMap((vars) => vars.properties)
+            .filter((property) => {
+              const key = keyName(property);
+              if (!LAYOUT.has(key) || staticString(property.value) === "") return false;
+              if (seen.has(key)) return false;
+              seen.add(key);
+              return true;
+            })
+            .map((property) => ({
+              index: property.start,
+              message: `Animating \`${keyName(property)}\` forces layout on every frame.`,
+              hint: layoutHint(
+                keyName(property),
+                findAll(property.value, (node) => spells(node, "%")).length > 0,
+              ),
+            }));
+        },
+      );
     },
   },
   {
     id: "trigger-per-item",
     level: "warn",
+    /**
+     * 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
+     * file, at the first.
+     */
     test(file) {
-      return find(file.code, /\.(forEach|map)\s*\(/g)
-        .flatMap((loop) => {
-          const span = blockAfter(file.code, loop.index);
-          if (!span) return [];
-          const body = file.code.slice(span[0], span[1]);
-          const hit = body.indexOf("scrollTrigger");
-          return hit === -1
-            ? []
-            : [
-                {
-                  index: span[0] + hit,
-                  message: "A ScrollTrigger created per item in a loop.",
-                  hint: "Each carries its own start/end maths on every scroll frame. If the items belong to one visual moment, use one trigger with a stagger. Per-item is right only when they genuinely reveal independently — pinned card stacks, for instance.",
-                },
-              ];
-        })
-        .slice(0, 1);
+      const callbacks = findAll(file.ast, (node) => {
+        if (node.type !== "CallExpression") return false;
+        const callee = unwrap(node.callee);
+        return (
+          callee?.type === "MemberExpression" &&
+          !callee.computed &&
+          (callee.property.name === "forEach" || callee.property.name === "map")
+        );
+      })
+        .map((call) => unwrap(call.arguments[0]))
+        .filter(isFunction);
+      const loops = findAll(file.ast, (node) =>
+        ["ForStatement", "ForOfStatement", "ForInStatement"].includes(node.type),
+      ).map((loop) => loop.body);
+
+      const [first] = [...callbacks, ...loops]
+        .flatMap((body) => findAll(body, (node) => keyName(node) === "scrollTrigger"))
+        .sort((a, b) => a.start - b.start);
+
+      return first
+        ? [
+            {
+              index: first.start,
+              message: "A ScrollTrigger created per item in a loop.",
+              hint: HINT.triggerPerItem,
+            },
+          ]
+        : [];
     },
   },
 
@@ -421,87 +788,71 @@ export const RULES = [
   {
     id: "eased-loop",
     level: "warn",
+    /**
+     * 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
+     * own `repeat` is not the tween's. `yoyo` reverses rather than restarting,
+     * so there is no seam to hide.
+     */
     test(file) {
-      return tweenCalls(file.code).flatMap((call) => {
-        const span = blockAfter(file.code, call.index);
-        if (!span) return [];
-        const body = file.code.slice(span[0], span[1]);
-
-        if (!/repeat\s*:\s*-1/.test(body)) return [];
-        /** yoyo reverses rather than restarting, so there is no seam to hide. */
-        if (/yoyo\s*:\s*true/.test(body)) return [];
-        if (/ease\s*:\s*["']none["']/.test(body)) return [];
-        if (!/ease\s*:/.test(body)) return [];
-
-        return [
-          {
-            index: span[0] + body.indexOf("ease"),
-            message: "An infinite repeat with an ease other than `none`.",
-            hint: "The tween decelerates into its own restart, so the loop seam becomes visible. Use `ease: \"none\"`, or `yoyo: true` if it should breathe.",
-          },
-        ];
-      });
+      return findAll(file.ast, (node) => tweenMethod(node) !== null).flatMap(
+        (call) => {
+          const vars = ownVars(call, tweenMethod(call));
+          if (!vars) return [];
+          const repeat = propertyOf(vars, "repeat");
+          if (!repeat || numberValue(repeat.value) !== -1) return [];
+          const yoyo = unwrap(propertyOf(vars, "yoyo")?.value);
+          if (yoyo?.type === "Literal" && yoyo.value === true) return [];
+          const ease = propertyOf(vars, "ease");
+          if (!ease || staticString(ease.value) === "none") return [];
+          return [
+            { index: ease.start, message: MESSAGE.easedLoop, hint: HINT.easedLoop },
+          ];
+        },
+      );
     },
   },
   {
     id: "eased-scrub",
     level: "warn",
+    /**
+     * A GSAP call scrubbed anywhere in its arguments — `scrub: false` aside —
+     * with a string ease other than `"none"` in those arguments or, for a
+     * timeline, in a child `timelineLinks` finds: the chain, and the name it is
+     * kept under within its scope, `this.tl` included. One finding per file.
+     */
     test(file) {
-      if (!/scrub\s*:/.test(file.code)) return [];
-
-      const eased = (text) => text.search(/\bease\s*:\s*["'`](?!none["'`])/);
-      const findings = [];
-      const report = (index) =>
-        findings.push({
-          index,
-          message: "Easing inside a scrubbed ScrollTrigger timeline.",
-          hint: "The scrollbar is the playhead, so an ease fights the visitor's own scrolling and reads as lag. Use `ease: \"none\"` on the children and let `scrub: 1` do the smoothing.",
-        });
-
-      /**
-       * Whitespace is allowed around the dot because a formatter breaks a
-       * three-call chain as `gsap\n  .timeline(…)\n  .to(…)`. The eased child of
-       * a scrubbed timeline is the common case, and it used to be missed: only
-       * the timeline's own vars were read, and they rarely carry the ease.
-       */
-      for (const call of find(
-        file.code,
-        /\bgsap\s*\.\s*(to|from|fromTo|timeline)\s*\(/g,
-      )) {
-        const open = call.index + call[0].length - 1;
-        const span = parenSpan(file.code, open);
-        if (!span) continue;
-        const args = file.code.slice(open, span[1]);
-        if (!/scrub\s*:/.test(args)) continue;
-
-        const own = eased(args);
-        if (own !== -1) report(open + own);
-        if (call[1] !== "timeline") continue;
-
-        const children = chainedTweens(file.code, span[1] + 1);
-        const kept = file.code
-          .slice(Math.max(0, call.index - 80), call.index)
-          .match(/([\w$]+)\s*=\s*$/);
-        if (kept) {
-          const name = kept[1].replace(/\$/g, "\\$");
-          const uses = new RegExp(
-            `(?<![\\w$.])${name}(?=\\s*\\.\\s*(?:to|from|fromTo)\\s*\\()`,
-            "g",
-          );
-          for (const use of find(file.code, uses)) {
-            children.push(
-              ...chainedTweens(file.code, use.index + use[0].length),
-            );
-          }
-        }
+      const scrubbed = (node) =>
+        findAll(node, (n) => {
+          if (keyName(n) !== "scrub") return false;
+          const value = unwrap(n.value);
+          return !(value?.type === "Literal" && value.value === false);
+        }).length > 0;
+      const eased = (nodes) =>
+        nodes.flatMap((node) =>
+          findAll(node, (n) => {
+            if (keyName(n) !== "ease") return false;
+            const value = staticString(n.value);
+            return value !== null && value !== "none";
+          }),
+        )[0];
 
-        for (const [start, end] of children) {
-          const at = eased(file.code.slice(start, end));
-          if (at !== -1) report(start + at);
+      for (const call of findAll(file.ast, (node) => isGsapCall(node))) {
+        if (!call.arguments.some(scrubbed)) continue;
+        const own = eased(call.arguments);
+        const child =
+          methodName(call) === "timeline"
+            ? timelineLinks(file.ast, call)
+                .filter((link) => CHILDREN.has(methodName(link)))
+                .map((link) => eased(link.arguments))
+                .find(Boolean)
+            : undefined;
+        const at = own ?? child;
+        if (at) {
+          return [{ index: at.start, message: MESSAGE.easedScrub, hint: HINT.easedScrub }];
         }
       }
-
-      return findings.slice(0, 1);
+      return [];
     },
   },
   /**
@@ -519,48 +870,55 @@ export const RULES = [
   {
     id: "never-completes",
     level: "error",
+    /**
+     * `onComplete` and `repeat: -1` anywhere in a GSAP call's arguments; for a
+     * timeline, its children and any `eventCallback("onComplete", …)` from
+     * `timelineLinks` — the chain, and the name it is kept under within its
+     * scope, `this.tl` included.
+     */
     test(file) {
-      /** `-1` exactly: the boundary after it rejects `-10`. */
-      const endless = /\brepeat\s*:\s*-1\b/;
+      const endless = (nodes) =>
+        nodes.flatMap((node) =>
+          findAll(node, (n) => keyName(n) === "repeat" && numberValue(n.value) === -1),
+        )[0];
       const findings = [];
 
-      for (const call of find(
-        file.code,
-        /\bgsap\s*\.\s*(to|from|fromTo|timeline)\s*\(/g,
-      )) {
-        const open = call.index + call[0].length - 1;
-        const span = parenSpan(file.code, open);
-        if (!span) continue;
-        const args = file.code.slice(open, span[1]);
-        const waits = /\bonComplete\b/.test(args);
-
-        const own = args.search(endless);
-        if (waits && own !== -1) {
+      for (const call of findAll(file.ast, (node) => isGsapCall(node))) {
+        const method = methodName(call);
+        const waits = call.arguments.some(
+          (argument) => findAll(argument, (n) => keyName(n) === "onComplete").length > 0,
+        );
+        const own = endless(call.arguments);
+        if (waits && own) {
           findings.push({
-            index: open + own,
-            message: `\`gsap.${call[1]}\` repeats forever, so its \`onComplete\` can never run.`,
-            hint: "An endless repeat never completes. Use `onRepeat` for something that should happen every cycle, or give it a finite `repeat`.",
+            index: own.start,
+            message: `\`gsap.${method}\` repeats forever, so its \`onComplete\` can never run.`,
+            hint: HINT.neverCompletesOwn,
           });
           continue;
         }
-        if (call[1] !== "timeline") continue;
+        if (method !== "timeline") continue;
 
-        const { children, completes } = timelineCalls(file.code, call, span[1]);
+        const links = timelineLinks(file.ast, call);
+        const completes = links.some(
+          (link) =>
+            methodName(link) === "eventCallback" &&
+            staticString(link.arguments[0]) === "onComplete",
+        );
         if (!waits && !completes) continue;
 
-        for (const [start, end] of children) {
-          const at = file.code.slice(start, end).search(endless);
-          if (at === -1) continue;
+        const child = links
+          .filter((link) => CHILDREN.has(methodName(link)))
+          .map((link) => endless(link.arguments))
+          .find(Boolean);
+        if (child) {
           findings.push({
-            index: start + at,
-            message:
-              "An endlessly repeating child in a timeline with an `onComplete`, which therefore never fires.",
-            hint: 'The child gives the timeline an effectively infinite duration, and a tween added after it does not end it. Hand over at a position instead — `.call(fn, [], "label+=0.5")` fires when the playhead passes — or run the loop as its own tween outside the timeline.',
+            index: child.start,
+            message: MESSAGE.neverCompletesChild,
+            hint: HINT.neverCompletesChild,
           });
-          break;
         }
       }
-
       return findings;
     },
   },
@@ -581,124 +939,159 @@ export const RULES = [
   {
     id: "late-transform-origin",
     level: "warn",
+    /**
+     * Any `.fromTo(target, fromVars, toVars)` whose two vars are object
+     * literals. Keys are read at the top level of each, and a transform's
+     * from-value as it is written: `rotation: "90deg"` and `scale: 0` move the
+     * element, `scale: 1` and `rotation: 0` do not.
+     */
     test(file) {
-      const ORIGIN = /\b(?:transformOrigin|svgOrigin)\s*:/;
-      const TRANSFORM = /\b(scale[XY]?|rotation|rotate|skew[XY])\s*:\s*([^,}\n]+)/g;
-      /** Whether a from-value leaves the element untransformed. */
-      const identity = (prop, value) => {
-        const v = value.trim().replace(/^["'`]|["'`]$/g, "");
-        return prop.startsWith("scale")
-          ? /^1(?:\.0+)?$/.test(v)
-          : /^-?0(?:\.0+)?(?:deg|rad)?$/.test(v);
-      };
+      const ORIGIN = new Set(["transformOrigin", "svgOrigin"]);
+      const TRANSFORM = /^(?:scale[XY]?|rotation|rotate|skew[XY])$/;
+
+      const calls = findAll(file.ast, (node) => methodName(node) === "fromTo");
 
-      return find(file.code, /\.\s*fromTo\s*\(/g).flatMap((call) => {
-        const open = call.index + call[0].length - 1;
-        const span = parenSpan(file.code, open);
-        if (!span) return [];
-        const [, from, to] = callArgs(file.code, open, span[1]);
-        if (!from || !to) return [];
-
-        const fromVars = file.code.slice(from[0], from[1]);
-        const toVars = file.code.slice(to[0], to[1]);
-        const origin = toVars.search(ORIGIN);
-        if (origin === -1 || ORIGIN.test(fromVars)) return [];
-        if (/\bsmoothOrigin\s*:\s*false\b/.test(toVars)) return [];
-        if (
-          [...fromVars.matchAll(TRANSFORM)].every(([, prop, value]) =>
-            identity(prop, value),
-          )
-        ) {
+      return calls.flatMap((call) => {
+        const from = unwrap(call.arguments[1]);
+        const to = unwrap(call.arguments[2]);
+        if (from?.type !== "ObjectExpression" || to?.type !== "ObjectExpression") {
           return [];
         }
+        const origin = to.properties.find((property) => ORIGIN.has(keyName(property)));
+        if (!origin) return [];
+        if (from.properties.some((property) => ORIGIN.has(keyName(property)))) return [];
+        const smooth = unwrap(propertyOf(to, "smoothOrigin")?.value);
+        if (smooth?.type === "Literal" && smooth.value === false) return [];
 
-        return [
-          {
-            index: to[0] + origin,
-            message:
-              "The transform origin is only in this `fromTo`'s to-vars, while its from-vars scale, rotate or skew.",
-            hint: "On an SVG element GSAP holds the element in place when its origin changes, and that correction outlives the tween: it ends offset, silently — a circle grown from 0 about its centre lands a whole radius off. Put `transformOrigin` or `svgOrigin` in the from-vars, or set it before the tween. HTML elements are unaffected.",
-          },
-        ];
+        const moves = from.properties.some(
+          (property) =>
+            TRANSFORM.test(keyName(property) ?? "") &&
+            !identityTransform(
+              keyName(property),
+              file.raw.slice(property.value.start, property.value.end),
+            ),
+        );
+        return moves
+          ? [
+              {
+                index: origin.start,
+                message: MESSAGE.lateTransformOrigin,
+                hint: HINT.lateTransformOrigin,
+              },
+            ]
+          : [];
       });
     },
   },
   {
     id: "shared-plugin-id",
     level: "error",
+    /**
+     * Any property naming a target geometry whose value is a fixed `#id`: a
+     * string or a template literal with nothing interpolated, including the
+     * shorthands `motionPath: "#id"` and `morphSVG: "#id"`.
+     */
     test(file) {
       if (!file.isReact) return [];
+      const KEYS = new Set(["path", "shape", "align", "motionPath", "morphSVG"]);
 
-      return find(
-        file.code,
-        /\b(?:path|shape|align)\s*:\s*["'](#[A-Za-z][\w-]*)["']/g,
-      ).map((m) => ({
-        index: m.index,
-        message: `Hardcoded id \`${m[1]}\` in plugin config.`,
-        hint: "useGSAP scopes the selectors it resolves itself, but MotionPath and MorphSVG resolve their own config against the whole document. Mount this component twice and both instances drive the first one's geometry, silently. Namespace it with useId().",
-      }));
+      return findAll(file.ast, (node) => KEYS.has(keyName(node))).flatMap(
+        (property) => {
+          const id = staticString(property.value)?.match(/^#[A-Za-z][\w-]*$/)?.[0];
+          return id
+            ? [
+                {
+                  index: property.start,
+                  message: `Hardcoded id \`${id}\` in plugin config.`,
+                  hint: HINT.sharedPluginId,
+                },
+              ]
+            : [];
+        },
+      );
     },
   },
   {
     id: "unregistered-plugin",
     level: "error",
+    /**
+     * Registered means named anywhere inside the arguments of a
+     * `registerPlugin` call — not mentioned anywhere after one, and under its
+     * local name, so an alias registered by its alias counts. Imports are read
+     * as declarations: a default import takes its plugin's name from the path,
+     * and a type-only import, of the whole statement or of one specifier, ships
+     * nothing and is skipped.
+     */
     test(file) {
-      /**
-       * The identifiers actually passed to `registerPlugin`, across every
-       * call. This used to be "does the name appear anywhere after the first
-       * registerPlugin", so a `ScrollTrigger.refresh()` below a registration
-       * that never mentioned it counted as registering it — and an alias
-       * (`ScrollTrigger as ST`) registered by its alias counted as missing.
-       */
-      const registered = new Set(
-        find(file.code, /\bregisterPlugin\s*\(/g).flatMap((m) => {
-          const open = m.index + m[0].length - 1;
-          const span = parenSpan(file.code, open);
-          return span
-            ? file.code
-                .slice(open + 1, span[1])
-                .split(/[^\w$]+/)
-                .filter(Boolean)
-            : [];
-        }),
-      );
+      const registered = new Set();
+      const registrations = findAll(file.ast, (node) => {
+        const name = calleeName(node);
+        return name === "registerPlugin" || name?.endsWith(".registerPlugin");
+      });
+      for (const call of registrations) {
+        for (const arg of call.arguments) {
+          for (const id of findAll(arg, (node) => node.type === "Identifier")) {
+            registered.add(id.name);
+          }
+        }
+      }
 
-      return find(
-        file.code,
-        /\bimport\s*\{([^}]*)\}\s*from\s*["']gsap\/[\w/-]+["']/g,
-      ).flatMap((m) =>
-        m[1]
-          .split(",")
-          .map((specifier) => specifier.trim())
-          .filter((specifier) => specifier && !/^type\s/.test(specifier))
-          .flatMap((specifier) => {
-            const [imported, local = imported] = specifier.split(/\s+as\s+/);
-            if (!PLUGIN_NAME.test(imported) || registered.has(local)) return [];
-            return [
-              {
-                index: m.index,
-                message: `\`${imported}\` is imported but never passed to \`gsap.registerPlugin\`.`,
-                hint: "An unregistered plugin's properties are ignored without an error — the animation simply does nothing.",
-              },
-            ];
-          }),
-      );
+      const findings = [];
+      for (const declaration of file.ast.body) {
+        if (declaration.type !== "ImportDeclaration") continue;
+        if (declaration.importKind === "type") continue;
+        const from = declaration.source.value;
+        if (typeof from !== "string" || !/^gsap\/[\w/-]+$/.test(from)) continue;
+
+        for (const specifier of declaration.specifiers) {
+          if (specifier.importKind === "type") continue;
+          const imported =
+            specifier.type === "ImportSpecifier"
+              ? (specifier.imported.name ?? specifier.imported.value)
+              : specifier.type === "ImportDefaultSpecifier"
+                ? from.split("/").pop()
+                : null;
+          if (!imported || !PLUGIN_NAME.test(imported)) continue;
+          if (registered.has(specifier.local.name)) continue;
+          if (file.registeredElsewhere?.has(imported)) continue;
+          findings.push({
+            index: declaration.start,
+            message: `\`${imported}\` is imported but never passed to \`gsap.registerPlugin\`.`,
+            hint: HINT.unregisteredPlugin,
+          });
+        }
+      }
+      return findings;
     },
   },
   {
     id: "missing-reduced-motion",
     level: "warn",
+    /**
+     * 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
+     * values is not animating anything.
+     */
     test(file) {
       if (!file.usesGsap) return [];
-      if (/prefers-reduced-motion/.test(file.code)) return [];
-      /** A file that only sets values is not animating anything. */
-      if (!tweenCalls(file.code).some((m) => m[1] !== "set")) return [];
+      if (findAll(file.ast, (node) => spells(node, "prefers-reduced-motion")).length) {
+        return [];
+      }
+      if (!findAll(file.ast, (node) => isGsapCall(node)).length) return [];
+
+      const first = findAll(
+        file.ast,
+        (node) =>
+          node.type === "MemberExpression" &&
+          unwrap(node.object)?.type === "Identifier" &&
+          unwrap(node.object).name === "gsap",
+      ).sort((a, b) => a.start - b.start)[0];
 
       return [
         {
-          index: file.code.search(/\bgsap\./),
+          index: first.start,
           message: "No `prefers-reduced-motion` branch in an animating file.",
-          hint: "Reduced motion is a design, not an off switch: decide what the motion was saying and say it without the travel. Note that the reduced branch must set the END state — a `from` that never runs leaves its target invisible.",
+          hint: HINT.missingReducedMotion,
         },
       ];
     },
@@ -708,25 +1101,45 @@ export const RULES = [
   {
     id: "dev-tool-shipped",
     level: "error",
+    /**
+     * 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
+     * ships no code. `markers: true` is the property itself.
+     */
     test(file) {
+      const TOOLS = /^(?:MotionPathHelper|GSDevTools)$/;
       const findings = [];
 
-      for (const m of find(
-        file.code,
-        /^\s*import\b[^\n]*\b(MotionPathHelper|GSDevTools)\b/gm,
-      )) {
+      for (const declaration of file.ast.body) {
+        if (declaration.type !== "ImportDeclaration") continue;
+        if (declaration.importKind === "type") continue;
+        const values = declaration.specifiers.filter((s) => s.importKind !== "type");
+        if (declaration.specifiers.length && !values.length) continue;
+
+        const tool =
+          values
+            .map((s) => s.imported?.name ?? s.local.name)
+            .find((name) => TOOLS.test(name)) ??
+          String(declaration.source.value).split("/").pop();
+        if (!TOOLS.test(tool)) continue;
+
         findings.push({
-          index: m.index,
-          message: `\`${m[1]}\` is statically imported.`,
-          hint: "A static import ships regardless of any `if` around the call. Load it with a dynamic `import()` behind a NODE_ENV check, or bake its output in and delete it.",
+          index: declaration.start,
+          message: `\`${tool}\` is statically imported.`,
+          hint: HINT.devToolImport,
         });
       }
 
-      for (const m of find(file.code, /markers\s*:\s*true/g)) {
+      const markers = findAll(file.ast, (node) => {
+        if (keyName(node) !== "markers") return false;
+        const value = unwrap(node.value);
+        return value?.type === "Literal" && value.value === true;
+      });
+      for (const property of markers) {
         findings.push({
-          index: m.index,
+          index: property.start,
           message: "`markers: true` is unconditional.",
-          hint: 'Gate it: `markers: process.env.NODE_ENV === "development"`.',
+          hint: HINT.markers,
         });
       }
 
@@ -736,12 +1149,16 @@ export const RULES = [
   {
     id: "barrel-import",
     level: "warn",
+    /** An import or re-export whose module is `gsap/all`. */
     test(file) {
-      return find(file.code, /from\s*["']gsap\/all["']/g).map((m) => ({
-        index: m.index,
-        message: "Importing from `gsap/all` pulls in every plugin.",
-        hint: "Import each from its own subpath — `gsap/ScrollTrigger` — so the bundler can drop the ones this route does not use.",
-      }));
+      return file.ast.body
+        .map(moduleSource)
+        .filter((source) => source?.value === "gsap/all")
+        .map((source) => ({
+          index: source.start,
+          message: "Importing from `gsap/all` pulls in every plugin.",
+          hint: HINT.barrelImport,
+        }));
     },
   },
 ];