any-doctor 0.0.1

package/doctors/async-doctor.mjs

@@ -0,0 +1,295 @@
+export const meta = {
+  id: "async-doctor",
+  description: "Async and concurrency discipline: fetch hygiene, promise handling, timer cleanup.",
+  severity: "warning",
+  category: "async",
+  blindSpots: [
+    "Fetch: cannot determine whether an options variable, spread, or helper supplies a signal at runtime; aliased or member-expression fetch functions are not recognized.",
+    "Promises: consumption inside template strings or dynamic property access, reassignable bindings (let) with conditional awaits, and results passed to a helper that awaits internally are not tracked.",
+    "Timers: only directly named useEffect/setTimeout/clearTimeout are recognized; handles must be a simple local identifier cleared in the same effect.",
+  ],
+  checks: [
+    {
+      id: "fetch-calls-without-abortsignal",
+      description: "Fetch call does not provide an AbortSignal.",
+      severity: "warning",
+      impact: "Requests cannot be cancelled: navigating away, unmounting, or superseding leaves fetches running to completion.",
+      why: "A fetch without a signal has no path to cancellation, so component-driven requests outlive the components that issued them.",
+      fix: "Pass an AbortController's signal via the request options and abort it on cleanup or supersede.",
+    },
+    {
+      id: "unawaited-async-map",
+      description: ".map(async ...) result is never awaited — the promises are dropped.",
+      severity: "warning",
+      impact: "The async work starts but nothing waits for it: errors vanish silently and the results are lost mid-flight.",
+      why: "Array.map returns a new array of promises. Without Promise.all or an await on the result, the async callbacks run fire-and-forget.",
+      fix: "Wrap the mapped array in Promise.all and await it — or drop the async if the work should actually be sequential.",
+    },
+    {
+      id: "uncleared-settimeout-in-effect",
+      description: "setTimeout inside useEffect is not cleared with clearTimeout.",
+      severity: "warning",
+      impact: "The callback fires after the component is gone: state updates on unmounted components, work the user cancelled, and hard-to-trace bugs.",
+      why: "Every timer started inside an effect must be cleared in that effect's cleanup; an uncleared setTimeout outlives the render that created it.",
+      fix: "Assign the timer and return a cleanup that calls clearTimeout with the same identifier.",
+    },
+  ],
+};
+
+export async function doctor(ctx) {
+  await checkFetch(ctx);
+  await checkUnawaitedMap(ctx);
+  await checkSetTimeout(ctx);
+}
+
+// --- fetch-calls-without-abortsignal ------------------------------------
+
+async function checkFetch(ctx) {
+  const calls = await ctx.search.pattern("fetch($$$ARGS)");
+  for (const call of calls) {
+    if (!hasInlineSignal(call.text)) {
+      ctx.report.finding({ ...call, rule: "fetch-calls-without-abortsignal" });
+    }
+  }
+}
+
+function hasInlineSignal(call) {
+  const open = call.indexOf("(");
+  if (open < 0) return false;
+
+  const argumentsText = call.slice(open + 1, -1);
+  const argumentsList = splitTopLevel(argumentsText);
+  const options = argumentsList[1]?.trim();
+  if (!options?.startsWith("{")) return false;
+
+  const close = matchingBrace(options);
+  if (close < 0) return false;
+
+  return splitTopLevel(options.slice(1, close)).some((property) =>
+    /^(?:signal|["']signal["'])\s*(?::|$)/.test(property.trim()),
+  );
+}
+
+function splitTopLevel(text) {
+  const parts = [];
+  let start = 0;
+  let depth = 0;
+  let quote = null;
+
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (quote) {
+      if (character === "\\") index += 1;
+      else if (character === quote) quote = null;
+    } else if (character === "'" || character === '"' || character === "`") {
+      quote = character;
+    } else if (character === "(" || character === "[" || character === "{") {
+      depth += 1;
+    } else if (character === ")" || character === "]" || character === "}") {
+      depth -= 1;
+    } else if (character === "," && depth === 0) {
+      parts.push(text.slice(start, index));
+      start = index + 1;
+    }
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
+
+function matchingBrace(text) {
+  let depth = 0;
+  let quote = null;
+
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (quote) {
+      if (character === "\\") index += 1;
+      else if (character === quote) quote = null;
+    } else if (character === "'" || character === '"' || character === "`") {
+      quote = character;
+    } else if (character === "{") {
+      depth += 1;
+    } else if (character === "}" && --depth === 0) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+// --- unawaited-async-map -------------------------------------------------
+
+async function checkUnawaitedMap(ctx) {
+  const CONSUMERS = /(Promise\s*\.\s*(all|allSettled|race|any)\s*\((?:[^()]|\([^()]*\))*\bNAME\b|await\s+(?:[\w.$]+\s*=\s*)?\s*\bNAME\b)/;
+
+  for (const file of ctx.files.list([".ts", ".tsx", ".js", ".jsx", ".mjs"])) {
+    const src = ctx.files.read(file);
+    const lines = src.split("\n");
+
+    for (let i = 0; i < lines.length; i++) {
+      const decl = lines[i].match(/\bconst\s+([A-Za-z_$][\w$]*)\s*=\s*[\w.$\]]+\s*\.\s*map\(\s*async\b/);
+      if (!decl) continue;
+      const name = decl[1];
+
+      const rest = lines.slice(i + 1).join("\n");
+      const consumer = new RegExp(CONSUMERS.source.replace(/NAME/g, escapeRe(name)));
+      if (consumer.test(rest)) continue;
+
+      ctx.report.finding({
+        rule: "unawaited-async-map",
+        file: file,
+        line: i + 1,
+        column: decl.index + 1,
+      });
+    }
+  }
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// --- uncleared-settimeout-in-effect ---------------------------
+
+async function checkSetTimeout(ctx) {
+  const files = await ctx.files.list();
+
+  for (const file of files) {
+    const source = await ctx.files.read(file);
+    const masked = maskNonCode(source);
+    const effects = [];
+    const useEffect = /\buseEffect\b/g;
+    let match;
+
+    while ((match = useEffect.exec(masked))) {
+      const open = nextNonSpace(masked, match.index + match[0].length);
+      if (masked[open] !== "(") continue;
+      const close = matchingDelimiter(masked, open, "(", ")");
+      if (close === -1) continue;
+      const body = effectBody(masked, open + 1, firstArgumentEnd(masked, open, close));
+      if (body) effects.push(body);
+    }
+
+    for (const effect of effects) {
+      const cleared = new Set();
+      const clearTimeout = /\bclearTimeout\s*\(\s*([A-Za-z_$][\w$]*)\s*\)/g;
+      const body = masked.slice(effect.start, effect.end);
+      while ((match = clearTimeout.exec(body))) cleared.add(match[1]);
+
+      const timeout = /\bsetTimeout\s*\(/g;
+      while ((match = timeout.exec(body))) {
+        const index = effect.start + match.index;
+        const insideNestedEffect = effects.some(
+          (other) => other !== effect && other.start < index && index < other.end,
+        );
+        if (insideNestedEffect) continue;
+
+        const before = masked.slice(effect.start, index);
+        const assignment = /(?:(?:\bconst|\blet|\bvar)\s+)?([A-Za-z_$][\w$]*)\s*=\s*$/.exec(before);
+        if (!assignment || !cleared.has(assignment[1])) {
+          ctx.report.finding({ rule: "uncleared-settimeout-in-effect", file, line: lineAt(source, index) });
+        }
+      }
+    }
+  }
+}
+
+function maskNonCode(source) {
+  const chars = source.split("");
+  let index = 0;
+
+  while (index < source.length) {
+    const char = source[index];
+    const next = source[index + 1];
+
+    if (char === "/" && next === "/") {
+      const end = source.indexOf("\n", index + 2);
+      const stop = end === -1 ? source.length : end;
+      for (let cursor = index; cursor < stop; cursor += 1) chars[cursor] = " ";
+      index = stop;
+    } else if (char === "/" && next === "*") {
+      const end = source.indexOf("*/", index + 2);
+      const stop = end === -1 ? source.length : end + 2;
+      for (let cursor = index; cursor < stop; cursor += 1) {
+        if (chars[cursor] !== "\n") chars[cursor] = " ";
+      }
+      index = stop;
+    } else if (char === "'" || char === '"' || char === "`") {
+      const quote = char;
+      let cursor = index + 1;
+      while (cursor < source.length) {
+        if (source[cursor] === "\\") {
+          cursor += 2;
+        } else if (source[cursor] === quote) {
+          cursor += 1;
+          break;
+        } else {
+          cursor += 1;
+        }
+      }
+      for (let position = index; position < cursor; position += 1) {
+        if (chars[position] !== "\n") chars[position] = " ";
+      }
+      index = cursor;
+    } else {
+      index += 1;
+    }
+  }
+
+  return chars.join("");
+}
+
+function nextNonSpace(source, index) {
+  while (index < source.length && /\s/.test(source[index])) index += 1;
+  return index;
+}
+
+function matchingDelimiter(source, open, opening, closing) {
+  let depth = 0;
+  for (let index = open; index < source.length; index += 1) {
+    if (source[index] === opening) depth += 1;
+    if (source[index] === closing) {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return -1;
+}
+
+function firstArgumentEnd(source, open, close) {
+  let parens = 0;
+  let brackets = 0;
+  let braces = 0;
+  for (let index = open + 1; index < close; index += 1) {
+    const char = source[index];
+    if (char === "(") parens += 1;
+    if (char === ")") parens -= 1;
+    if (char === "[") brackets += 1;
+    if (char === "]") brackets -= 1;
+    if (char === "{") braces += 1;
+    if (char === "}") braces -= 1;
+    if (char === "," && parens === 0 && brackets === 0 && braces === 0) return index;
+  }
+  return close;
+}
+
+function effectBody(masked, start, end) {
+  const argument = masked.slice(start, end);
+  const arrow = argument.indexOf("=>");
+  const functionMatch = /\bfunction\b/.exec(argument);
+  const callbackStart = arrow === -1 ? functionMatch?.index : arrow + 2;
+  if (callbackStart === undefined || callbackStart === -1) return null;
+
+  const brace = masked.indexOf("{", start + callbackStart);
+  if (brace === -1 || brace >= end) return null;
+  const bodyEnd = matchingDelimiter(masked, brace, "{", "}");
+  if (bodyEnd === -1 || bodyEnd > end) return null;
+  return { start: brace + 1, end: bodyEnd };
+}
+
+function lineAt(source, index) {
+  let line = 1;
+  for (let cursor = 0; cursor < index; cursor += 1) {
+    if (source[cursor] === "\n") line += 1;
+  }
+  return line;
+}

package/doctors/convex-doctor.fixtures.mjs

@@ -0,0 +1,177 @@
+export const fixtures = [
+  // --- filter-table-scan ---
+  {
+    name: "flags .filter() with no .withIndex()",
+    seed: {
+      "convex/messages.ts": [
+        "export const listByRoom = query({ args: { room: v.string() }, handler: async (ctx, { room }) => {",
+        "  return await ctx.db.query(\"messages\").filter(q => q.eq(q.field(\"room\"), room)).collect();",
+        "}});",
+      ].join("\n"),
+    },
+    expected: [{ file: "convex/messages.ts", line: 2 }],
+  },
+  {
+    name: "accepts .withIndex() with a range expression",
+    seed: {
+      "convex/messages.ts": [
+        "export const listByRoom = query({ args: { room: v.string() }, handler: async (ctx, { room }) => {",
+        "  return await ctx.db.query(\"messages\").withIndex(\"by_room\", q => q.eq(\"room\", room)).collect();",
+        "}});",
+      ].join("\n"),
+    },
+    expected: [],
+  },
+  {
+    name: "accepts .filter() chained AFTER .withIndex() (filter narrows the indexed read)",
+    seed: {
+      "convex/messages.ts": [
+        "export const recent = query({ args: { room: v.string() }, handler: async (ctx, { room }) => {",
+        "  return await ctx.db.query(\"messages\")",
+        "    .withIndex(\"by_room\", q => q.eq(\"room\", room))",
+        "    .filter(q => q.eq(q.field(\"pinned\"), true))",
+        "    .take(20);",
+        "}});",
+      ].join("\n"),
+    },
+    expected: [],
+  },
+
+  // --- index-without-range ---
+  {
+    name: "flags .withIndex() with no range expression",
+    seed: {
+      "convex/messages.ts": [
+        "export const all = query({ handler: async (ctx) => {",
+        "  return await ctx.db.query(\"messages\").withIndex(\"by_room\").collect();",
+        "}});",
+      ].join("\n"),
+    },
+    expected: [{ file: "convex/messages.ts", line: 2 }],
+  },
+  {
+    name: "flags .withIndex(name, q => ...) whose callback never calls q.eq",
+    seed: {
+      "convex/messages.ts": [
+        "export const all = query({ handler: async (ctx) => {",
+        "  return await ctx.db.query(\"messages\").withIndex(\"by_room\", q => q).collect();",
+        "}});",
+      ].join("\n"),
+    },
+    expected: [{ file: "convex/messages.ts", line: 2 }],
+  },
+  {
+    name: "accepts .withIndex() with q.gt range",
+    seed: {
+      "convex/messages.ts": [
+        "export const since = query({ handler: async (ctx) => {",
+        "  return await ctx.db.query(\"messages\").withIndex(\"by_time\", q => q.gt(\"time\", 100)).collect();",
+        "}});",
+      ].join("\n"),
+    },
+    expected: [],
+  },
+
+  // --- unbounded-subscription ---
+  {
+    name: "flags useQuery on a whole-table query",
+    seed: {
+      "src/App.tsx": [
+        "import { useQuery } from \"convex/react\";",
+        "import { api } from \"../convex/_generated/api\";",
+        "export function Messages() {",
+        "  const messages = useQuery(api.messages.list);",
+        "  return <ul>{messages?.map(m => <li key={m._id}>{m.body}</li>)}</ul>;",
+        "}",
+      ].join("\n"),
+    },
+    expected: [{ file: "src/App.tsx", line: 4 }],
+  },
+  {
+    name: "accepts usePaginatedQuery",
+    seed: {
+      "src/App.tsx": [
+        "import { usePaginatedQuery } from \"convex/react\";",
+        "import { api } from \"../convex/_generated/api\";",
+        "export function Messages() {",
+        "  const { results, loadMore } = usePaginatedQuery(api.messages.list, {}, { initialNumItems: 25 });",
+        "  return <ul>{results.map(m => <li key={m._id}>{m.body}</li>)}</ul>;",
+        "}",
+      ].join("\n"),
+    },
+    expected: [],
+  },
+
+  // --- nondeterministic-clock-in-transaction ---
+  {
+    name: "flags Date.now() inside a mutation handler",
+    seed: {
+      "convex/timers.ts": [
+        "export const touch = mutation({ handler: async (ctx) => {",
+        "  const now = Date.now();",
+        "  await ctx.db.patch(id, { updatedAt: now });",
+        "}});",
+      ].join("\n"),
+    },
+    expected: [{ file: "convex/timers.ts", line: 2 }],
+  },
+  {
+    name: "flags Math.random() inside a query handler",
+    seed: {
+      "convex/roll.ts": [
+        "export const sample = query({ handler: async (ctx) => {",
+        "  const pick = Math.random();",
+        "  return pick;",
+        "}});",
+      ].join("\n"),
+    },
+    expected: [{ file: "convex/roll.ts", line: 2 }],
+  },
+  {
+    name: "flags elapsed-time math comparing two Date.now() calls in one transaction",
+    seed: {
+      "convex/sessions.ts": [
+        "export const expire = mutation({ handler: async (ctx, s) => {",
+        "  const elapsed = Date.now() - s.startedAt;",
+        "  if (elapsed > 5000) await ctx.db.delete(s._id);",
+        "}});",
+      ].join("\n"),
+    },
+    expected: [{ file: "convex/sessions.ts", line: 2 }],
+  },
+  {
+    name: "accepts Date.now() in a plain (non-Convex) function",
+    seed: {
+      "src/lib/time.ts": [
+        "export function nowMs() {",
+        "  return Date.now();",
+        "}",
+      ].join("\n"),
+    },
+    expected: [],
+  },
+  {
+    name: "accepts Date.now() passed in as a mutation argument",
+    seed: {
+      "convex/timers.ts": [
+        "export const touch = mutation({ args: { now: v.number() }, handler: async (ctx, { now }) => {",
+        "  await ctx.db.patch(id, { updatedAt: now });",
+        "}});",
+      ].join("\n"),
+    },
+    expected: [],
+  },
+  {
+    name: "ignores clock lookalikes inside comments and strings",
+    seed: {
+      "convex/timers.ts": [
+        "export const touch = mutation({ handler: async (ctx) => {",
+        "  // const now = Date.now();",
+        "  const note = 'call Date.now() from the client';",
+        "  await ctx.db.patch(id, { note });",
+        "}});",
+      ].join("\n"),
+    },
+    expected: [],
+  },
+];

package/doctors/convex-doctor.mjs

@@ -0,0 +1,223 @@
+export const meta = {
+  id: "convex-doctor",
+  description: "Convex discipline: indexed reads, bounded subscriptions, deterministic transactions.",
+  severity: "warning",
+  category: "convex",
+  blindSpots: [
+    "Queries: the schema is never cross-referenced - a .filter() on a table the doctor cannot see indexed is still flagged only at the query site; withIndex is trusted to name a real index.",
+    "Subscriptions: useQuery is flagged at the call site without resolving the referenced function, so a paginated cursor returned from a helper is not recognized.",
+    "Clock: only direct Date.now()/Math.random() calls inside query/mutation/action bodies are detected; calls hidden behind wrappers or imported aliases are not.",
+    "Chains split across multiple statements (const q = ctx.db.query(t); q.filter(...)) are not tracked - only single-statement chains.",
+  ],
+  checks: [
+    {
+      id: "filter-table-scan",
+      description: ".filter() query without .withIndex() reads every document in the table.",
+      severity: "warning",
+      impact: "Convex bills and measures performance by documents read: a .filter() chain scans the whole table on every call, so a query that is fast at demo scale degrades linearly with data and can hit function limits in production.",
+      why: ".filter() runs after documents are read - it cannot reduce reads. Only an index range (.withIndex with q.eq/q.gt/...) restricts how many documents the query touches.",
+      fix: "Define an index covering the filtered fields in schema.ts and use .withIndex(\"by_field\", q => q.eq(\"field\", value)) instead of .filter().",
+    },
+    {
+      id: "index-without-range",
+      description: ".withIndex() with no range expression still scans the whole table through the index.",
+      severity: "warning",
+      impact: "The index is selected but never narrowed: every document is read via the index in full order, which costs the same as a table scan while looking optimized.",
+      why: "withIndex(\"by_x\") with no second argument (or a callback that never calls q.eq/q.gt/q.lt/q.range) leaves the read range unbounded - the docs call this out as a scan in disguise.",
+      fix: "Pass a range expression: .withIndex(\"by_x\", q => q.eq(\"x\", value)).",
+    },
+    {
+      id: "unbounded-subscription",
+      description: "useQuery subscribes to a whole table with no pagination.",
+      severity: "warning",
+      impact: "Every document re-syncs to the client on any change to the table; as the table grows, the subscription's payload and re-render cost grow without bound.",
+      why: "useQuery keeps the result live. Without .paginate() on the query side or usePaginatedQuery on the client side, the subscription reads and ships the entire table.",
+      fix: "Use .paginate(opts) in the query and usePaginatedQuery on the client; or bound the result with .withIndex(...).order(\"desc\").take(n) when the table is provably small.",
+    },
+    {
+      id: "nondeterministic-clock-in-transaction",
+      description: "Date.now() or Math.random() called inside a Convex transaction function.",
+      severity: "warning",
+      impact: "The value is snapshotted per transaction: elapsed-time math inside one mutation always sees zero, and repeated calls return the same value - timeouts, jitter, and expiry logic silently misbehave.",
+      why: "Convex executes query/mutation bodies deterministically within a transaction: Date.now() is pinned to the transaction's start and Math.random() is seeded from it. Both are safe to store but wrong for measuring or branching.",
+      fix: "Pass timestamps/randomness in as arguments from the client or an action (where they are genuinely live), or rely on _creationTime for ordering.",
+    },
+  ],
+};
+
+export async function doctor(ctx) {
+  const files = await ctx.files.list([".ts", ".tsx", ".js", ".jsx", ".mjs"]);
+  for (const file of files) {
+    const source = await ctx.files.read(file);
+    const masked = maskNonCode(source);
+    const lines = masked.split("\n");
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (!line.includes(".filter(") && !line.includes(".withIndex(")) continue;
+      const chain = statementAt(lines, i);
+      if (!chain.includes("ctx.db.query(") && !chain.includes("db.query(")) continue;
+
+      const hasWithIndex = chain.includes(".withIndex(");
+      const hasFilter = chain.includes(".filter(");
+      if (hasFilter && !hasWithIndex) {
+        ctx.report.finding({ rule: "filter-table-scan", file, line: i + 1 });
+      } else if (hasWithIndex && !hasRangeExpression(chain)) {
+        ctx.report.finding({ rule: "index-without-range", file, line: i + 1 });
+      }
+    }
+
+    checkSubscriptions(ctx, file, masked);
+    checkClock(ctx, file, masked);
+  }
+}
+
+// --- query chain checks ----------------------------------------------------
+
+// Gather the full statement containing line i (chains wrap across lines).
+function statementAt(lines, i) {
+  let start = i;
+  while (start > 0 && !statementEnds(lines[start - 1])) start--;
+  let end = i;
+  while (end < lines.length - 1 && !statementEnds(lines[end])) end++;
+  return lines.slice(start, end + 1).join("\n");
+}
+
+function statementEnds(line) {
+  const bare = line.trim();
+  if (bare.startsWith("//") || bare.startsWith("*") || bare.startsWith("/*")) return true;
+  if (/\b(?:return|await|const|let|var|export|throw)\b.*[;)]\s*$/.test(bare) && !/[.(,+]$/.test(bare)) return true;
+  return /;\s*(\/\/.*)?$/.test(bare);
+}
+
+// withIndex("by_x") or withIndex("by_x", q => q.eq(...)) - the range is the
+// second argument; detect it by finding an eq/gt/gtQuiet/lt/ltQuiet/range
+// call within the withIndex argument span.
+function hasRangeExpression(chain) {
+  const idx = chain.indexOf(".withIndex(");
+  if (idx === -1) return false;
+  const open = chain.indexOf("(", idx);
+  const close = matchingParen(chain, open);
+  if (close === -1) return false;
+  const args = chain.slice(open + 1, close);
+  // No second argument at all: withIndex("by_x") or withIndex("by_x")
+  if (args.trim().length > 0 && !args.includes(",")) return false;
+  return /\bq\s*\.\s*(eq|neq|gt|gtQuiet|lt|ltQuiet|range)\s*\(/.test(args);
+}
+
+function matchingParen(text, open) {
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    if (text[i] === "(") depth++;
+    if (text[i] === ")") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+// --- subscription check ----------------------------------------------------
+
+function checkSubscriptions(ctx, file, masked) {
+  const lines = masked.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    if (!/useQuery\s*\(/.test(lines[i])) continue;
+    // A paginated sibling anywhere in the statement opts out.
+    const chain = statementAt(lines, i);
+    if (chain.includes("usePaginatedQuery")) continue;
+    ctx.report.finding({
+      rule: "unbounded-subscription",
+      file,
+      line: i + 1,
+    });
+  }
+}
+
+// --- clock/random check ----------------------------------------------------
+
+// Track function boundaries: an export wired through query()/mutation()/
+// action()/internalQuery()/internalMutation()/internalAction() starts a
+// transaction body; direct Date.now()/Math.random() inside it is flagged.
+const CONVEX_FNS = /\b(?:query|mutation|action|internalQuery|internalMutation|internalAction)\s*\(\s*(?:\([^)]*\)\s*=>|function\b|\{)/;
+
+function checkClock(ctx, file, masked) {
+  const lines = masked.split("\n");
+  let insideConvexFn = false;
+  let braceDepth = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!insideConvexFn && CONVEX_FNS.test(line)) {
+      insideConvexFn = true;
+      braceDepth = countChars(line, "{") - countChars(line, "}");
+      continue;
+    }
+    if (!insideConvexFn) continue;
+
+    braceDepth += countChars(line, "{") - countChars(line, "}");
+    if (/\b(?:Date\s*\.\s*now|Math\s*\.\s*random)\s*\(/.test(line)) {
+      ctx.report.finding({
+        rule: "nondeterministic-clock-in-transaction",
+        file,
+        line: i + 1,
+      });
+    }
+    if (braceDepth <= 0) {
+      insideConvexFn = false;
+    }
+  }
+}
+
+function countChars(line, ch) {
+  let n = 0;
+  for (const c of line) if (c === ch) n++;
+  return n;
+}
+
+// --- shared masking (comments and strings blanked, code shape kept) --------
+
+function maskNonCode(source) {
+  const chars = source.split("");
+  let index = 0;
+
+  while (index < source.length) {
+    const char = source[index];
+    const next = source[index + 1];
+
+    if (char === "/" && next === "/") {
+      const end = source.indexOf("\n", index + 2);
+      const stop = end === -1 ? source.length : end;
+      for (let cursor = index; cursor < stop; cursor += 1) chars[cursor] = " ";
+      index = stop;
+    } else if (char === "/" && next === "*") {
+      const end = source.indexOf("*/", index + 2);
+      const stop = end === -1 ? source.length : end + 2;
+      for (let cursor = index; cursor < stop; cursor += 1) {
+        if (chars[cursor] !== "\n") chars[cursor] = " ";
+      }
+      index = stop;
+    } else if (char === "'" || char === '"' || char === "`") {
+      const quote = char;
+      let cursor = index + 1;
+      while (cursor < source.length) {
+        if (source[cursor] === "\\") {
+          cursor += 2;
+        } else if (source[cursor] === quote) {
+          cursor += 1;
+          break;
+        } else {
+          cursor += 1;
+        }
+      }
+      for (let position = index; position < cursor; position += 1) {
+        if (chars[position] !== "\n") chars[position] = " ";
+      }
+      index = cursor;
+    } else {
+      index += 1;
+    }
+  }
+
+  return chars.join("");
+}