eslint-plugin-no-mistakes 0.94.0 → 0.96.0

package/README.md

@@ -57,3 +57,8 @@ See [options and examples](../../docs/eslint-rules/postgres-no-async-sql-builder
 `require-options-on-imported-call` requires a static options object on configured
 imports, globals with no local binding, and terminal methods with a matching receiver shape.
 See [options and examples](../../docs/eslint-rules/require-options-on-imported-call.md).
+
+`restricted-api-usage` is an opt-in import/export-name and call-name policy.
+See [options and examples](../../docs/eslint-rules/restricted-api-usage.md).
+
+Opt-in client contracts: [`no-consecutive-unbatched-reads`](../../docs/eslint-rules/no-consecutive-unbatched-reads.md) configures adjacent awaited read batching; [`require-top-level-registration`](../../docs/eslint-rules/require-top-level-registration.md) configures owner-module lifecycle registration. Both support ESLint/Oxlint and have no product defaults.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-no-mistakes",
-  "version": "0.94.0",
+  "version": "0.96.0",
   "description": "ESLint and Oxlint rules that keep code static enough for no-mistakes analyzers and coding agents",
   "license": "MIT",
   "repository": {

package/src/component-functions.js

@@ -1,5 +1,7 @@
 "use strict";
 
+const { literalString } = require("./helpers");
+
 function nonEmptyStrings(value, fallback) {
   if (!Array.isArray(value)) {
     return fallback;
@@ -23,7 +25,7 @@ function unwrapExpression(node, opts) {
   if (node.type !== "CallExpression" || !isConfiguredWrapper(node.callee, opts)) {
     return node;
   }
-  for (const arg of node.arguments) {
+  for (const arg of wrapperArguments(node)) {
     const unwrapped = unwrapExpression(arg, opts);
     if (isFunctionNode(unwrapped)) {
       return unwrapped;
@@ -32,19 +34,49 @@ function unwrapExpression(node, opts) {
   return node;
 }
 
+function wrapperArguments(node) {
+  const args = node.arguments || [];
+  const name = staticCalleeName(node.callee);
+  if (name !== "call" && name !== "apply") return args;
+  if (args.some((arg) => arg?.type === "SpreadElement")) return [];
+  if (name === "call") return args.slice(1);
+  const list = args[1];
+  if (
+    list?.type !== "ArrayExpression" ||
+    list.elements.some((element) => !element || element.type === "SpreadElement")
+  ) {
+    return [];
+  }
+  return list.elements;
+}
+
 function isConfiguredWrapper(callee, opts) {
   const name = calleeName(callee);
   return Boolean(name && opts.wrappers.has(name));
 }
 
+function staticCalleeName(node) {
+  if (!node || node.type !== "MemberExpression") return null;
+  if (node.computed && node.property?.type === "Identifier") return null;
+  if (!node.computed && typeof node.property?.name === "string") return node.property.name;
+  return literalString(node.property);
+}
+
 function calleeName(node) {
-  if (node.type === "Identifier") {
-    return node.name;
-  }
-  if (node.type === "MemberExpression" && !node.computed) {
-    return node.property.name;
+  let current = node;
+  for (let depth = 0; depth < 4; depth += 1) {
+    while (current?.type === "ChainExpression") current = current.expression;
+    if (current?.type === "MemberExpression") {
+      const name = staticCalleeName(current);
+      if (name === "call" || name === "apply") {
+        current = current.object;
+        continue;
+      }
+      return name;
+    }
+    break;
   }
-  return null;
+  return current?.type === "Identifier" ? current.name : null;
 }
 
 function isFunctionNode(node) {

package/src/exported-component-definitions.js

@@ -0,0 +1,32 @@
+"use strict";
+
+const { functionFromExpression } = require("./component-functions");
+
+function collectTopLevelDefinition(statement, definitions, opts, aliases, exported) {
+  if (statement.type === "FunctionDeclaration" && statement.id) {
+    definitions.set(statement.id.name, { name: statement.id.name, fn: statement });
+    return;
+  }
+  if (statement.type !== "VariableDeclaration") {
+    return;
+  }
+  for (const declaration of statement.declarations) {
+    if (declaration.id.type !== "Identifier") {
+      continue;
+    }
+    const fn = functionFromExpression(declaration.init, opts);
+    if (fn) {
+      definitions.set(declaration.id.name, { name: declaration.id.name, fn });
+      continue;
+    }
+    if (declaration.init?.type === "Identifier" && declaration.parent?.kind === "const") {
+      aliases.push({
+        name: declaration.id.name,
+        target: declaration.init.name,
+        exported,
+      });
+    }
+  }
+}
+
+module.exports = { collectTopLevelDefinition };

package/src/exported-components.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const { functionFromExpression, nonEmptyStrings } = require("./component-functions");
+const { collectTopLevelDefinition } = require("./exported-component-definitions");
 
 const DEFAULT_COMPONENT_NAME_PATTERN = "^[A-Z]";
 const DEFAULT_WRAPPERS = ["memo", "forwardRef", "observer"];
@@ -66,17 +67,34 @@ function collectExportedComponents(program, opts) {
   const namedExports = new Set();
   const defaultExports = new Set();
   const components = [];
+  const aliases = [];
 
   for (const statement of program.body) {
-    collectTopLevelDefinition(statement, definitions, opts);
+    collectTopLevelDefinition(statement, definitions, opts, aliases, false);
     if (statement.type === "ExportNamedDeclaration") {
-      collectNamedExport(statement, definitions, namedExports, defaultExports, components, opts);
+      collectNamedExport(
+        statement,
+        definitions,
+        namedExports,
+        defaultExports,
+        components,
+        opts,
+        aliases,
+      );
     }
     if (statement.type === "ExportDefaultDeclaration") {
       collectDefaultExport(statement, definitions, defaultExports, components, opts);
     }
   }
 
+  for (const alias of aliases) {
+    const target = definitions.get(alias.target);
+    if (!target) continue;
+    const definition = { name: alias.name, fn: target.fn };
+    definitions.set(alias.name, definition);
+    if (alias.exported && opts.exportTypes.has("named")) components.push(definition);
+  }
+
   pushExportedDefinitions(namedExports, definitions, components, opts.exportTypes.has("named"));
   pushExportedDefinitions(defaultExports, definitions, components, opts.exportTypes.has("default"));
   return uniqueComponents(components);
@@ -94,25 +112,6 @@ function pushExportedDefinitions(names, definitions, components, enabled) {
   }
 }
 
-function collectTopLevelDefinition(statement, definitions, opts) {
-  if (statement.type === "FunctionDeclaration" && statement.id) {
-    definitions.set(statement.id.name, { name: statement.id.name, fn: statement });
-    return;
-  }
-  if (statement.type !== "VariableDeclaration") {
-    return;
-  }
-  for (const declaration of statement.declarations) {
-    if (declaration.id.type !== "Identifier") {
-      continue;
-    }
-    const fn = functionFromExpression(declaration.init, opts);
-    if (fn) {
-      definitions.set(declaration.id.name, { name: declaration.id.name, fn });
-    }
-  }
-}
-
 function collectNamedExport(
   statement,
   definitions,
@@ -120,6 +119,7 @@ function collectNamedExport(
   defaultExports,
   components,
   opts,
+  aliases,
 ) {
   if (statement.source) {
     return;
@@ -133,7 +133,7 @@ function collectNamedExport(
     return;
   }
   if (statement.declaration?.type === "VariableDeclaration") {
-    collectTopLevelDefinition(statement.declaration, definitions, opts);
+    collectTopLevelDefinition(statement.declaration, definitions, opts, aliases, true);
     for (const declaration of statement.declaration.declarations) {
       const definition = definitions.get(declaration.id.name);
       if (declaration.id.type === "Identifier" && definition && opts.exportTypes.has("named")) {

package/src/fetch-call.js

@@ -0,0 +1,102 @@
+"use strict";
+
+const { unwrapExpression } = require("./rules/async-ast");
+const { logicalCall, memberPropertyName, propertyName } = require("./rules/module-mock-helpers");
+
+const LOCAL_BINDING_TYPES = new Set([
+  "Variable",
+  "Parameter",
+  "CatchClause",
+  "FunctionName",
+  "ImportBinding",
+  "ClassName",
+]);
+const FETCH_ROOTS = new Set(["globalThis", "window", "self", "global"]);
+
+function isFetchShadowed(scope) {
+  while (scope) {
+    const get = scope.set?.get;
+    const variable = typeof get === "function" ? get.call(scope.set, "fetch") : null;
+    if (variable) return variable.defs.some((def) => LOCAL_BINDING_TYPES.has(def.type));
+    if (!scope.set || typeof get !== "function") {
+      const fallback = scope.variables?.find((item) => item.name === "fetch");
+      if (fallback) return fallback.defs.some((def) => LOCAL_BINDING_TYPES.has(def.type));
+    }
+    scope = scope.upper;
+  }
+  return false;
+}
+
+function unboundRoot(node, context) {
+  if (node?.type !== "Identifier" || !FETCH_ROOTS.has(node.name)) return false;
+  let scope = context.sourceCode.getScope(node);
+  while (scope) {
+    const variable = scope.variables?.find((item) => item.name === node.name);
+    if (variable) return !variable.defs?.some((def) => LOCAL_BINDING_TYPES.has(def.type));
+    scope = scope.upper;
+  }
+  return true;
+}
+
+function bindingVariable(node, context) {
+  if (!context?.sourceCode?.getScope) return null;
+  let scope = context.sourceCode.getScope(node);
+  while (scope) {
+    const variable = scope.variables?.find((item) => item.name === node.name);
+    if (variable) return variable;
+    scope = scope.upper;
+  }
+  return null;
+}
+
+function fetchCallee(node, context, seen) {
+  node = unwrapExpression(node);
+  if (!node) return false;
+  const visiting = seen || new Set();
+  if (node.type === "MemberExpression") {
+    if (memberPropertyName(node) !== "fetch") return false;
+    return unboundRoot(unwrapExpression(node.object), context);
+  }
+  if (node.type === "Identifier") {
+    if (node.name === "fetch" && !isFetchShadowed(context?.sourceCode?.getScope?.(node)))
+      return true;
+    const variable = bindingVariable(node, context);
+    if (!variable || visiting.has(variable) || variable.defs.length !== 1) return false;
+    visiting.add(variable);
+    const def = variable.defs[0];
+    if (def.type !== "Variable" || def.parent?.kind !== "const") return false;
+    if (def.node.id.type === "Identifier") {
+      if (!def.node.init) return false;
+      return fetchCallee(def.node.init, context, visiting);
+    }
+    if (def.node.id.type !== "ObjectPattern") return false;
+    for (const item of def.node.id.properties) {
+      if (item.type === "Property") {
+        const value = item.value.type === "AssignmentPattern" ? item.value.left : item.value;
+        // `const { [name]: schedule }` names an expression, not the fetch property.
+        if (item.computed && item.key?.type === "Identifier") continue;
+        if (
+          value.type === "Identifier" &&
+          value.name === node.name &&
+          propertyName(item.key) === "fetch"
+        ) {
+          return unboundRoot(unwrapExpression(def.node.init), context);
+        }
+      }
+    }
+    return false;
+  }
+  return false;
+}
+
+function fetchInvocation(node, context) {
+  const invoked = logicalCall(node);
+  if (!invoked?.callee || !fetchCallee(invoked.callee, context)) return null;
+  return invoked.arguments;
+}
+
+function isFetchCall(node, context) {
+  return fetchInvocation(node, context) !== null;
+}
+
+module.exports = { fetchInvocation, isFetchCall };

package/src/helpers.js

@@ -1,5 +1,7 @@
 "use strict";
 
+const { fetchInvocation, isFetchCall } = require("./fetch-call");
+
 const DEFAULT_SELECTOR_ATTRIBUTES = ["data-testid", "data-pw"];
 const DEFAULT_NAMING_PATTERN = "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$";
 const INTERACTIVE_ELEMENTS = new Set(["button", "input", "select", "textarea"]);
@@ -134,40 +136,6 @@ function selectorValueNode(attribute) {
   return expression && expression.type !== "JSXEmptyExpression" ? expression : null;
 }
 
-const LOCAL_BINDING_TYPES = new Set([
-  "Variable",
-  "Parameter",
-  "CatchClause",
-  "FunctionName",
-  "ImportBinding",
-  "ClassName",
-]);
-
-function isFetchShadowed(scope) {
-  while (scope) {
-    const get = scope.set?.get;
-    const variable = typeof get === "function" ? get.call(scope.set, "fetch") : null;
-    if (variable) {
-      return variable.defs.some((def) => LOCAL_BINDING_TYPES.has(def.type));
-    }
-    if (!scope.set || typeof get !== "function") {
-      const fallback = scope.variables?.find((item) => item.name === "fetch");
-      if (fallback) {
-        return fallback.defs.some((def) => LOCAL_BINDING_TYPES.has(def.type));
-      }
-    }
-    scope = scope.upper;
-  }
-  return false;
-}
-
-function isFetchCall(node, context) {
-  if (node.callee.type !== "Identifier" || node.callee.name !== "fetch") {
-    return false;
-  }
-  return !isFetchShadowed(context.sourceCode.getScope(node));
-}
-
 function rule(meta, create) {
   return { meta, create };
 }
@@ -179,6 +147,7 @@ module.exports = {
   canonicalAttribute,
   cssSelectorValues,
   INTERACTIVE_ELEMENTS,
+  fetchInvocation,
   isFetchCall,
   isSelectorAttribute,
   isSelectorCall,

package/src/index.js

@@ -1,6 +1,9 @@
 "use strict";
 
 const rules = {
+  "restricted-api-usage": require("./rules/restricted-api-usage"),
+  "no-consecutive-unbatched-reads": require("./rules/no-consecutive-unbatched-reads"),
+  "require-top-level-registration": require("./rules/require-top-level-registration"),
   "forbidden-member-chains": require("./rules/forbidden-member-chains"),
   "gh-api-argument-safety": require("./rules/gh-api-argument-safety"),
   "no-argv-main-guard": require("./rules/no-argv-main-guard"),
@@ -39,8 +42,10 @@ const rules = {
   "playwright-unique": require("./rules/playwright-unique"),
   "postgres-cursor-call-contract": require("./rules/postgres-cursor-call-contract"),
   "postgres-no-async-sql-builder": require("./rules/postgres-no-async-sql-builder"),
+  "postgres-no-correlated-sql-builder": require("./rules/postgres-no-correlated-sql-builder"),
   "postgres-no-executor-adapter": require("./rules/postgres-no-executor-adapter"),
   "postgres-no-manual-transaction": require("./rules/postgres-no-manual-transaction"),
+  "postgres-no-nonliteral-sql-registry-key": require("./rules/postgres-no-nonliteral-sql-registry-key"),
   "postgres-no-unbounded-query-fanout": require("./rules/postgres-no-unbounded-query-fanout"),
   "react-no-nullish-react-node": require("./rules/react-no-nullish-react-node"),
   "react-no-use-promise-resolve": require("./rules/react-no-use-promise-resolve"),

package/src/rule-suppression.js

@@ -6,6 +6,7 @@ function ruleSuppression(context, ruleId, suppressionOptions) {
   const lines = new Set();
   let file = false;
   const source = context.sourceCode;
+  if (!source?.ast?.tokens || !source.getAllComments) return () => false;
   const first = source.ast.tokens[0];
   const requireReason = suppressionOptions?.requireReason === true;
   for (const comment of source.getAllComments()) {

package/src/rules/argv-main-fragments.js

@@ -0,0 +1,25 @@
+"use strict";
+const ARGV = 1;
+// Strings and [prefix, suffix] fragments stay separate from path identities.
+// Keeping the fragment until the comparison lets nested concatenations fold once.
+function identity(value) {
+  if (Array.isArray(value)) return /^file:\/\/\/?$/i.test(value[0]) && value[1] === "" ? ARGV : 0;
+  return typeof value === "number" ? value : 0;
+}
+function concatenate(left, right) {
+  if (left === ARGV) left = ["", ""];
+  if (right === ARGV) right = ["", ""];
+  // Accepted prefixes have at most eight characters; reject before allocating.
+  if (typeof left === "string" && typeof right === "string")
+    return left.length + right.length <= 8 ? left + right : 0;
+  if (typeof left === "string" && Array.isArray(right))
+    return left.length + right[0].length <= 8 ? [left + right[0], right[1]] : 0;
+  if (Array.isArray(left) && typeof right === "string") return right === "" ? left : 0;
+  return 0;
+}
+function fileUrlArgument(target, read) {
+  if (target?.type !== "NewExpression" || target.arguments.length !== 1) return 0;
+  const argument = read(target.arguments[0]);
+  return Array.isArray(argument) && identity(argument) === ARGV ? argument : 0;
+}
+module.exports = { ARGV, identity, concatenate, fileUrlArgument };

package/src/rules/argv-main-values.js

@@ -1,7 +1,8 @@
 "use strict";
 const { unwrapExpression } = require("./async-ast");
 const { resolveVariable, memberPropertyName, isLocalRequire } = require("./async-target-bindings");
-const { literalString } = require("./module-mock-helpers");
+const { literalString, logicalCall } = require("./module-mock-helpers");
+const { ARGV, identity, concatenate, fileUrlArgument } = require("./argv-main-fragments");
 
 function globalName(node, name, context) {
   if (node?.type !== "Identifier" || node.name !== name) return false;
@@ -29,16 +30,18 @@ function nodeProcess(node, context) {
     ["process", "node:process"].includes(literalString(init.arguments[0]))
   );
 }
-const ARGV = 1;
 const MAIN = 2;
 const PROCESS = 3;
 const ARGUMENTS = 4;
 function createClassifier(context, wrappers) {
   const stable = new WeakMap();
   const aliases = new WeakMap();
+  const value = (node, depth) => identity(classify(node, depth));
   function classify(input, depth = 0) {
     const node = unwrapExpression(input);
     if (!node || depth > 32) return 0;
+    const text = literalString(node);
+    if (text !== null) return text;
     if (node.type === "Identifier") {
       const variable = resolveVariable(node, context);
       if (!variable) {
@@ -51,6 +54,25 @@ function createClassifier(context, wrappers) {
       if (nodeProcess(node, context)) return PROCESS;
       if (globalName(node, "__filename", context)) return MAIN;
       const def = variable.defs.length === 1 ? variable.defs[0] : null;
+      if (def?.type === "ImportBinding" && def.node?.type === "ImportSpecifier") {
+        const imported = def.node.imported;
+        const importedName = imported?.type === "Literal" ? String(imported.value) : imported?.name;
+        if (
+          importedName === "argv" &&
+          ["process", "node:process"].includes(def.parent?.source?.value)
+        ) {
+          return ARGUMENTS;
+        }
+      }
+      if (
+        def?.type === "Variable" &&
+        def.parent?.kind === "const" &&
+        def.node?.id?.type === "ObjectPattern"
+      ) {
+        const key = objectPatternKey(def.node.id, node.name);
+        if (key === "argv" && value(def.node.init, depth + 1) === PROCESS) return ARGUMENTS;
+        return 0;
+      }
       if (
         def?.type !== "Variable" ||
         def.parent.kind !== "const" ||
@@ -64,6 +86,29 @@ function createClassifier(context, wrappers) {
       }
       return aliases.get(variable);
     }
+    if (node.type === "BinaryExpression" && node.operator === "+") {
+      return concatenate(classify(node.left, depth + 1), classify(node.right, depth + 1));
+    }
+    if (
+      node.type === "LogicalExpression" &&
+      node.operator === "??" &&
+      classify(node.right, depth + 1) === ""
+    ) {
+      return classify(node.left, depth + 1);
+    }
+    if (node.type === "TemplateLiteral") {
+      // Only prefix substitutions may be constant; a suffix substitution is not an argv guard.
+      const last = node.expressions.length - 1;
+      const argument = classify(node.expressions[last], depth + 1);
+      if (identity(argument) !== ARGV || node.quasis[last + 1].value.cooked !== "") return 0;
+      let prefix = node.quasis[0].value.cooked;
+      for (let i = 0; i < last; i++) {
+        const part = classify(node.expressions[i], depth + 1);
+        if (typeof part !== "string") return 0;
+        prefix = concatenate(prefix, concatenate(part, node.quasis[i + 1].value.cooked));
+      }
+      return concatenate(prefix, argument);
+    }
     if (node.type === "MemberExpression") {
       const name = memberPropertyName(node);
       if (
@@ -73,15 +118,14 @@ function createClassifier(context, wrappers) {
         ["url", "filename"].includes(name)
       )
         return MAIN;
-      const object = classify(node.object, depth + 1);
+      const target = unwrapExpression(node.object);
+      if (name === "href" && globalName(target?.callee, "URL", context)) {
+        const constructed = fileUrlArgument(target, (argument) => classify(argument, depth + 1));
+        if (constructed) return constructed;
+      }
+      const object = value(node.object, depth + 1);
       if (object === PROCESS && name === "argv") return ARGUMENTS;
-      if (
-        object === ARGUMENTS &&
-        node.computed &&
-        node.property.type === "Literal" &&
-        node.property.value === 1
-      )
-        return ARGV;
+      if (object === ARGUMENTS && node.computed && staticIndexOne(node.property)) return ARGV;
       // A URL conversion's href preserves the same module/argv identity.
       if (
         name === "href" &&
@@ -91,24 +135,71 @@ function createClassifier(context, wrappers) {
         return object;
     }
     if (node.type === "CallExpression") {
-      const callee = unwrapExpression(node.callee);
+      const invoked = logicalCall(node);
+      if (!invoked) return 0;
+      const callee = unwrapExpression(invoked.callee);
       if (
         callee?.type === "MemberExpression" &&
         memberPropertyName(callee) === "at" &&
-        classify(callee.object, depth + 1) === ARGUMENTS &&
-        node.arguments.length === 1 &&
-        node.arguments[0].type === "Literal" &&
-        node.arguments[0].value === 1
+        value(callee.object, depth + 1) === ARGUMENTS &&
+        invoked.arguments.length === 1 &&
+        staticIndexOne(invoked.arguments[0])
       )
         return ARGV;
-      if (node.arguments.length !== 1 || node.arguments[0].type === "SpreadElement") return 0;
+      if (
+        !invoked.forwarded &&
+        callee?.type === "MemberExpression" &&
+        memberPropertyName(callee) === "toString" &&
+        invoked.arguments.length === 0
+      ) {
+        const url = unwrapExpression(callee.object);
+        if (globalName(url?.callee, "URL", context)) {
+          const constructed = fileUrlArgument(url, (argument) => classify(argument, depth + 1));
+          if (constructed) return constructed;
+        }
+        const classified = classify(callee.object, depth + 1);
+        return typeof classified === "string" || [ARGV, MAIN].includes(identity(classified))
+          ? classified
+          : 0;
+      }
+      if (
+        !invoked.forwarded &&
+        callee?.type === "MemberExpression" &&
+        memberPropertyName(callee) === "concat" &&
+        invoked.arguments.every((argument) => argument.type !== "SpreadElement")
+      )
+        return invoked.arguments.reduce(
+          (folded, argument) => concatenate(folded, classify(argument, depth + 1)),
+          classify(callee.object, depth + 1),
+        );
+      if (invoked.arguments.length !== 1 || invoked.arguments[0].type === "SpreadElement") return 0;
+      if (globalName(callee, "String", context)) return classify(invoked.arguments[0], depth + 1);
       if (globalName(callee, "Boolean", context) || wrappers.resolveCallTarget(node)) {
-        const value = classify(node.arguments[0], depth + 1);
-        return value === ARGV || value === MAIN ? value : 0;
+        const argument = value(invoked.arguments[0], depth + 1);
+        return argument === ARGV || argument === MAIN ? argument : 0;
       }
     }
     return 0;
   }
-  return (node) => classify(node);
+  return (node) => value(node, 0);
 }
+function staticIndexOne(node) {
+  if (!node) return false;
+  if (node.type === "Literal") return node.value === 1 || node.value === "1";
+  return literalString(node) === "1";
+}
+
+function objectPatternKey(pattern, name) {
+  for (const property of pattern.properties) {
+    if (property.type !== "Property") continue;
+    const value =
+      property.value.type === "AssignmentPattern" ? property.value.left : property.value;
+    if (value.type !== "Identifier" || value.name !== name) continue;
+    if (property.key.type === "Identifier" && !property.computed) return property.key.name;
+    if (property.key.type === "Literal") return String(property.key.value);
+    return literalString(property.key);
+  }
+  return null;
+}
+
 module.exports = { createClassifier, ARGV, MAIN };

package/src/rules/async-ast.js

@@ -6,6 +6,7 @@ const transparentExpressionTypes = new Set([
   "TSAsExpression",
   "TSTypeAssertion",
   "TSSatisfiesExpression",
+  "TSInstantiationExpression",
 ]);
 
 function isFunction(node) {
@@ -24,6 +25,18 @@ function findContainingFunction(node) {
   }
 }
 
+function findContainingRoot(node) {
+  return findContainingFunction(node) ?? findProgram(node);
+}
+
+function findProgram(node) {
+  let current = node;
+  while (current) {
+    if (current.type === "Program") return current;
+    current = current.parent;
+  }
+}
+
 function isTransparentExpression(node) {
   return transparentExpressionTypes.has(node?.type);
 }
@@ -34,6 +47,14 @@ function unwrapExpression(node) {
   return current;
 }
 
+function unwrapSequence(node) {
+  let current = unwrapExpression(node);
+  while (current?.type === "SequenceExpression") {
+    current = unwrapExpression(current.expressions.at(-1));
+  }
+  return current;
+}
+
 function unwrapTransparentParent(node) {
   let current = node;
   while (isTransparentExpression(current.parent)) current = current.parent;
@@ -81,10 +102,12 @@ function isUnconditionalBeforeReturn(node, block) {
 
 module.exports = {
   findContainingFunction,
+  findContainingRoot,
   isFunction,
   isTransparentExpression,
   isUnconditionalBeforeReturn,
   traverse,
   unwrapExpression,
+  unwrapSequence,
   unwrapTransparentParent,
 };