@mehshekari/gsap-motion 3.0.0 → 3.1.1

package/skill/scripts/lib/source.mjs

@@ -1,15 +1,17 @@
 /**
- * Source reading for the GSAP audit.
+ * Source reading for the GSAP audit: finding the files, and reading each one
+ * once into what the rules need.
  *
- * Every helper here exists because naive matching produces false findings, and
- * a checker that cries wolf is one people switch off. Comments are stripped
- * before any rule runs — well-commented animation code explains itself at length, and
- * a docblock saying "do not use `gsap.to` in a pointermove handler" would
- * otherwise be reported as doing exactly that.
+ * Rules read the syntax tree. A few facts about the whole file — is it React,
+ * does it use GSAP — are still read from its text with the comments blanked
+ * out, because well-commented animation code explains itself at length, and a
+ * docblock that mentions `@gsap/react` is not an import of it.
  */
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { extname, join, relative } from "node:path";
 
+import { parse } from "./ast.mjs";
+
 const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs"]);
 const SKIP_DIRECTORIES = new Set([
   "node_modules",
@@ -40,6 +42,22 @@ export function collect(root) {
   return files.sort();
 }
 
+/**
+ * Whether the character at `i` opens a string literal.
+ *
+ * An apostrophe between two word characters never does: that is JSX text —
+ * `<p>Don't</p>` — and in code it would be a syntax error. Read as an opening
+ * quote, it inverted every string and comment after it, so a comment survived
+ * stripping and a call's span ran past its own closing parenthesis. A backtick
+ * after a word character is left alone: that is a tagged template.
+ */
+export function opensString(source, i) {
+  const c = source[i];
+  if (c !== '"' && c !== "'" && c !== "`") return false;
+  const word = (ch) => ch !== undefined && /\w/.test(ch);
+  return !(c === "'" && word(source[i - 1]) && word(source[i + 1]));
+}
+
 /**
  * Replaces comment bodies with spaces, keeping every newline and every offset.
  *
@@ -68,7 +86,7 @@ export function stripComments(source) {
         out[i] = " ";
         out[i + 1] = " ";
         i += 1;
-      } else if (c === '"' || c === "'" || c === "`") {
+      } else if (opensString(source, i)) {
         mode = "string";
         quote = c;
       }
@@ -114,110 +132,53 @@ export function lineAt(source, index) {
 }
 
 /**
- * The `{ … }` block that opens at or after `from`, as a `[start, end]` pair.
+ * A file plus everything the rules need, from its text.
  *
- * Used to ask "is this call inside that handler?" without a parser. Quotes are
- * tracked so a brace inside a string cannot close the block early; comments are
- * already gone by the time this runs.
+ * The command line reads the text from disk, through `load`. The ESLint plugin
+ * passes the text ESLint already holds, with the file's path, so both entry
+ * points run the rules on the same parse of the same characters.
  */
-export function blockAfter(source, from) {
-  const start = source.indexOf("{", from);
-  if (start === -1) return null;
-
-  let depth = 0;
-  let quote = "";
-
-  for (let i = start; i < source.length; i += 1) {
-    const c = source[i];
-
-    if (quote) {
-      if (c === "\\") i += 1;
-      else if (c === quote) quote = "";
-      continue;
-    }
-    if (c === '"' || c === "'" || c === "`") {
-      quote = c;
-      continue;
-    }
-    if (c === "{") depth += 1;
-    else if (c === "}") {
-      depth -= 1;
-      if (depth === 0) return [start, i];
-    }
-  }
-
-  return null;
-}
-
-/** Whether `index` falls inside any of the given `[start, end]` spans. */
-export const within = (spans, index) =>
-  spans.some(([start, end]) => index > start && index < end);
-
-/**
- * The `( … )` of a call, as a `[start, end]` pair, given the index of its
- * opening paren. Quotes are tracked the same way `blockAfter` tracks them.
- */
-export function parenSpan(source, open) {
-  let depth = 0;
-  let quote = "";
-
-  for (let i = open; i < source.length; i += 1) {
-    const c = source[i];
+export function fromText(raw, path, display = path) {
+  const code = stripComments(raw);
 
-    if (quote) {
-      if (c === "\\") i += 1;
-      else if (c === quote) quote = "";
-      continue;
-    }
-    if (c === '"' || c === "'" || c === "`") {
-      quote = c;
-      continue;
-    }
-    if (c === "(") depth += 1;
-    else if (c === ")") {
-      depth -= 1;
-      if (depth === 0) return [open, i];
+  /**
+   * Parsed on first use, and once. Most files in a project never mention GSAP,
+   * and the run skips those before any rule asks for a tree. A file that does
+   * not parse keeps `ast: null` and says why in `parseError`, so it can be
+   * reported as not checked rather than passed as clean.
+   */
+  let parsed;
+  const tree = () => {
+    if (parsed === undefined) {
+      try {
+        parsed = { ...parse(raw, path), error: null };
+      } catch (error) {
+        parsed = {
+          ast: null,
+          comments: [],
+          error: {
+            message: error.message,
+            line: error.loc?.line ?? 1,
+            column: error.loc?.column ?? 0,
+          },
+        };
+      }
     }
-  }
-
-  return null;
-}
-
-/**
- * Spans of every `useGSAP(…)`, `gsap.context(…)` and `contextSafe(…)` call.
- *
- * Anything created outside these is outside the context that reverts it, which
- * is the single most common way an animation outlives its component.
- *
- * The span is the call's parentheses, not the first `{` after its name. The
- * first brace failed silently twice over: a bodiless `useGSAP()` — the usual
- * way to get `contextSafe` — claimed whatever block came next in the file, so an
- * orphaned tween in the handler below it read as owned; and an expression-bodied
- * `contextSafe(() => gsap.to(el, { … }))` measured as the tween's own vars
- * object, which the call itself sits in front of.
- *
- * `contextSafe` counts because it is a context: a wrapped function's tweens are
- * added to the one `useGSAP` created.
- */
-export function contextSpans(code) {
-  const spans = [];
-  for (const match of code.matchAll(
-    /\b(?:useGSAP|gsap\.context|contextSafe)\s*\(/g,
-  )) {
-    const span = parenSpan(code, match.index + match[0].length - 1);
-    if (span) spans.push(span);
-  }
-  return spans;
-}
-
-/** A file plus everything the rules need, read once. */
-export function load(path, root) {
-  const raw = readFileSync(path, "utf8");
-  const code = stripComments(raw);
+    return parsed;
+  };
 
   return {
+    get ast() {
+      return tree().ast;
+    },
+    get comments() {
+      return tree().comments;
+    },
+    get parseError() {
+      return tree().error;
+    },
     path,
-    display: relative(root, path).replace(/\\/g, "/"),
+    display,
     raw,
     code,
     /**
@@ -233,6 +194,19 @@ export function load(path, root) {
       /\bfrom ["']@gsap\/react["']/.test(code),
     isClient: /^\s*["']use client["']/m.test(code),
     usesGsap: /\bfrom ["']gsap(?:\/|["'])/.test(code),
-    contexts: contextSpans(code),
   };
 }
+
+/** A file on disk, read once, shown by its path from `root`. */
+export function load(path, root) {
+  return fromText(
+    readFileSync(path, "utf8"),
+    path,
+    relative(root, path).replace(/\\/g, "/"),
+  );
+}
+
+/** Whether `collect` reads files with this path's extension. */
+export function hasSourceExtension(path) {
+  return SOURCE_EXTENSIONS.has(extname(path));
+}