@colrealpro/react-luau-doctor 0.19.0 → 0.19.1

package/dist/cli.js

@@ -11,7 +11,7 @@ var package_default = {
   publishConfig: {
     access: "public"
   },
-  version: "0.19.0",
+  version: "0.19.1",
   description: "Static analysis for React-Luau hooks, effects, rendering, and performance.",
   license: "MIT",
   type: "module",
@@ -1071,6 +1071,7 @@ function serializeProjectModel(project) {
     bindingCompatibleComponentProps: [...project.bindingCompatibleComponentProps].map(([key, value]) => [key, [...value].sort()]),
     staticIterationTables: [...project.staticIterationTables].map(([key, value]) => [key, [...value].sort()]),
     conditionalHookModes: [...project.conditionalHookModes],
+    reactHookModules: [...project.reactHookModules],
     sourceEffects: [...project.sourceEffects].map(([key, value]) => [key, serializeSourceEffect(value)])
   };
 }
@@ -1083,6 +1084,7 @@ function deserializeProjectModel(project) {
     bindingCompatibleComponentProps: new Map(project.bindingCompatibleComponentProps.map(([key, value]) => [key, new Set(value)])),
     staticIterationTables: new Map(project.staticIterationTables.map(([key, value]) => [key, new Set(value)])),
     conditionalHookModes: new Map(project.conditionalHookModes),
+    reactHookModules: new Map(project.reactHookModules ?? []),
     sourceEffects: new Map(project.sourceEffects.map(([key, value]) => [key, deserializeSourceEffect(value)]))
   };
 }
@@ -1107,7 +1109,8 @@ function projectModelFeatureKey(project) {
     bindingApiAlternatives: serialized.bindingApiAlternatives,
     bindingCompatibleComponentProps: serialized.bindingCompatibleComponentProps,
     staticIterationTables: serialized.staticIterationTables,
-    conditionalHookModes: serialized.conditionalHookModes
+    conditionalHookModes: serialized.conditionalHookModes,
+    reactHookModules: serialized.reactHookModules
   });
 }
 function cachedProjectModel(session) {
@@ -1198,6 +1201,19 @@ function walk(node) {
   }
   return result;
 }
+function parameterBindingNames(parameters) {
+  if (!parameters)
+    return [];
+  const result = [];
+  for (const parameter of parameters.namedChildren) {
+    if (parameter.type !== "parameter")
+      continue;
+    const identifier = parameter.namedChildren.find((child) => child.type === "identifier");
+    if (identifier)
+      result.push(identifier.text);
+  }
+  return [...new Set(result)];
+}
 function rootIdentifier(text) {
   const match = text.trim().match(/^([A-Za-z_][A-Za-z0-9_]*)/);
   return match?.[1] ?? null;
@@ -1326,6 +1342,63 @@ function createRuleContext(file) {
   };
 }
 
+// src/module-resolution.ts
+import path5 from "path";
+function normalizeRelative2(value) {
+  return value.split(path5.sep).join("/");
+}
+function moduleKeys(relativePath) {
+  let normalized = normalizeRelative2(relativePath).replace(/\.(?:lua|luau)$/i, "");
+  if (normalized.endsWith("/init"))
+    normalized = normalized.slice(0, -"/init".length);
+  const segments = normalized.split("/").filter(Boolean);
+  if (segments[0]?.toLowerCase() === "src")
+    segments.shift();
+  const keys = new Set;
+  for (let index = 0;index < segments.length; index += 1) {
+    const suffix = segments.slice(index).join(".").toLowerCase();
+    if (suffix)
+      keys.add(suffix);
+  }
+  return [...keys];
+}
+function normalizeRequireTarget(text) {
+  return (text.match(/[A-Za-z_][A-Za-z0-9_]*/g) ?? []).join(".").toLowerCase();
+}
+function buildUniqueFeatureAliases(modules, featureByModuleId) {
+  const owners = new Map;
+  for (const module of modules) {
+    for (const key of module.keys) {
+      const ids = owners.get(key) ?? new Set;
+      ids.add(module.id);
+      owners.set(key, ids);
+    }
+  }
+  const aliases = new Map;
+  for (const module of modules) {
+    const value = featureByModuleId.get(module.id);
+    if (value === undefined)
+      continue;
+    for (const key of module.keys) {
+      const ids = owners.get(key);
+      if (ids?.size === 1 && ids.has(module.id))
+        aliases.set(key, value);
+    }
+  }
+  return aliases;
+}
+function resolveModuleReference(target, aliases) {
+  let candidate = target;
+  while (true) {
+    if (aliases.has(candidate))
+      return aliases.get(candidate);
+    const separator = candidate.indexOf(".");
+    if (separator < 0)
+      return null;
+    candidate = candidate.slice(separator + 1);
+  }
+}
+
 // src/ast/react-model.ts
 var REACT_HOOKS = new Set([
   "useState",
@@ -1356,18 +1429,7 @@ var INSTANCE_FACTORY_MEMBERS = new Set([
 ]);
 var STABLE_ENGINE_FACTORY_MEMBERS = new Set(["GetMouse", "GetService"]);
 function identifiersFromParameters(node) {
-  if (!node)
-    return [];
-  const result = [];
-  for (const child of walk(node)) {
-    if (child.type !== "identifier")
-      continue;
-    const parentType = child.parent?.type;
-    if (parentType === "parameters" || parentType === "parameter" || parentType === "typed_identifier") {
-      result.push(child.text);
-    }
-  }
-  return [...new Set(result)];
+  return parameterBindingNames(node);
 }
 function getFunctionName(node) {
   if (node.type === "function_declaration") {
@@ -1421,15 +1483,19 @@ function directCalls(node) {
 function hasDirectCreateElementCall(node, aliases, reactNamespaces, reactRobloxNamespaces) {
   return directCalls(node).some((call) => {
     const name = call.childForFieldName("name")?.text ?? "";
-    const path5 = resolvePath(name, aliases, reactNamespaces, reactRobloxNamespaces);
-    return path5 === "React.createElement" || path5 === "ReactRoblox.createPortal";
+    const path6 = resolvePath(name, aliases, reactNamespaces, reactRobloxNamespaces);
+    return path6 === "React.createElement" || path6 === "ReactRoblox.createPortal";
   });
 }
-function hasDirectHookCall(node, aliases, reactNamespaces, reactRobloxNamespaces) {
+function hasDirectHookCall(node, aliases, reactNamespaces, reactRobloxNamespaces, importedHookKinds) {
   return directCalls(node).some((call) => {
     const name = call.childForFieldName("name")?.text ?? "";
-    const path5 = resolvePath(name, aliases, reactNamespaces, reactRobloxNamespaces);
-    const final = path5.split(/[.:]/).at(-1) ?? "";
+    const path6 = resolvePath(name, aliases, reactNamespaces, reactRobloxNamespaces);
+    const normalizedName = normalizeExpressionText(name);
+    const importedKind = importedHookKinds.get(normalizedName);
+    if (importedKind !== undefined)
+      return importedKind;
+    const final = path6.split(/[.:]/).at(-1) ?? "";
     return /^use[A-Z0-9_]/.test(final);
   });
 }
@@ -1515,8 +1581,8 @@ function isSyntacticallyStableInitializer(node) {
     return false;
   return ["nil", "true", "false", "number", "string", "string_content"].includes(node.type) || /^(?:nil|true|false|-?\d+(?:\.\d+)?(?:e[+-]?\d+)?)$/i.test(node.text.trim());
 }
-function finalCallMember(path5) {
-  return path5.split(/[.:]/).at(-1) ?? path5;
+function finalCallMember(path6) {
+  return path6.split(/[.:]/).at(-1) ?? path6;
 }
 function expressionCreatesInstance(node, aliases, reactNamespaces, reactRobloxNamespaces) {
   if (!node)
@@ -1528,8 +1594,8 @@ function expressionCreatesInstance(node, aliases, reactNamespaces, reactRobloxNa
     if (candidate.type !== "function_call")
       continue;
     const rawPath = candidate.childForFieldName("name")?.text ?? "";
-    const path5 = resolvePath(rawPath, aliases, reactNamespaces, reactRobloxNamespaces);
-    if (path5 === "Instance.new" || INSTANCE_FACTORY_MEMBERS.has(finalCallMember(path5)))
+    const path6 = resolvePath(rawPath, aliases, reactNamespaces, reactRobloxNamespaces);
+    if (path6 === "Instance.new" || INSTANCE_FACTORY_MEMBERS.has(finalCallMember(path6)))
       return true;
   }
   return false;
@@ -1541,8 +1607,8 @@ function expressionIsStableEngineObject(node, aliases, reactNamespaces, reactRob
   if (calls.length !== 1)
     return false;
   const rawPath = calls[0].childForFieldName("name")?.text ?? "";
-  const path5 = resolvePath(rawPath, aliases, reactNamespaces, reactRobloxNamespaces);
-  return STABLE_ENGINE_FACTORY_MEMBERS.has(finalCallMember(path5));
+  const path6 = resolvePath(rawPath, aliases, reactNamespaces, reactRobloxNamespaces);
+  return STABLE_ENGINE_FACTORY_MEMBERS.has(finalCallMember(path6));
 }
 function memoReturnsInstance(callback, aliases, reactNamespaces, reactRobloxNamespaces) {
   if (!callback || callback.type !== "function_definition")
@@ -1558,7 +1624,21 @@ function memoReturnsInstance(callback, aliases, reactNamespaces, reactRobloxName
 function isEmptyDependencyTable(node) {
   return Boolean(node?.type === "table_constructor" && node.namedChildren.every((child) => child.type !== "field"));
 }
-function buildReactModel(root) {
+function importedHookKinds(declarations, project) {
+  const result = new Map;
+  if (!project)
+    return result;
+  for (const declaration of declarations) {
+    const match = declaration.text.match(/^\s*local\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*require\s*\((.*?)\)\s*$/s);
+    if (!match || !/^use[A-Z0-9_]/.test(match[1]))
+      continue;
+    const kind = resolveModuleReference(normalizeRequireTarget(match[2]), project.reactHookModules);
+    if (kind !== null)
+      result.set(match[1], kind);
+  }
+  return result;
+}
+function buildReactModel(root, project) {
   const reactNamespaces = new Set;
   const reactRobloxNamespaces = new Set;
   const aliases = new Map;
@@ -1574,6 +1654,7 @@ function buildReactModel(root) {
   const instanceVariablesByFunction = new Map;
   const allNodes = [...walk(root)];
   const declarations = allNodes.filter((node) => node.type === "variable_declaration");
+  const projectHookKinds = importedHookKinds(declarations, project);
   let isReactFile = false;
   for (const declaration of declarations) {
     const text = declaration.text;
@@ -1648,7 +1729,7 @@ function buildReactModel(root) {
     if (!isReactFile || !info.body || info.isHook)
       continue;
     const simplePascalName = Boolean(info.name && /^[A-Z][A-Za-z0-9_]*$/.test(info.name));
-    const hasHooks = hasDirectHookCall(info.body, aliases, reactNamespaces, reactRobloxNamespaces);
+    const hasHooks = hasDirectHookCall(info.body, aliases, reactNamespaces, reactRobloxNamespaces, projectHookKinds);
     const renders = hasDirectCreateElementCall(info.body, aliases, reactNamespaces, reactRobloxNamespaces);
     if (hasHooks || isMemoWrappedFunction(info.node, aliases, reactNamespaces) || simplePascalName && renders) {
       info.isComponent = true;
@@ -1660,8 +1741,8 @@ function buildReactModel(root) {
     if (call.type !== "function_call")
       continue;
     const rawPath = call.childForFieldName("name")?.text ?? "";
-    const path5 = resolvePath(rawPath, aliases, reactNamespaces, reactRobloxNamespaces);
-    if (path5 !== "React.createElement")
+    const path6 = resolvePath(rawPath, aliases, reactNamespaces, reactRobloxNamespaces);
+    if (path6 !== "React.createElement")
       continue;
     const element = call.childForFieldName("arguments")?.namedChildren[0]?.text.trim() ?? "";
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(element))
@@ -1696,13 +1777,13 @@ function buildReactModel(root) {
     if (!call)
       continue;
     const rawPath = call.childForFieldName("name")?.text ?? "";
-    const path5 = resolvePath(rawPath, aliases, reactNamespaces, reactRobloxNamespaces);
+    const path6 = resolvePath(rawPath, aliases, reactNamespaces, reactRobloxNamespaces);
     const args = call.childForFieldName("arguments")?.namedChildren ?? [];
-    if (path5 === "React.joinBindings" && names.length >= 1) {
+    if (path6 === "React.joinBindings" && names.length >= 1) {
       stableVariables.add(names[0]);
       addScopedVariable(stableVariablesByFunction, owner, names[0]);
       addScopedVariable(externalMutableVariablesByFunction, owner, names[0]);
-    } else if (path5 === "React.useState" && names.length >= 2) {
+    } else if (path6 === "React.useState" && names.length >= 2) {
       const [valueName, setterName] = names;
       stateSetters.set(setterName, valueName);
       stateValues.set(valueName, setterName);
@@ -1716,10 +1797,10 @@ function buildReactModel(root) {
         initializer: args[0] ?? null,
         owner
       });
-    } else if (path5 === "React.useReducer" && names.length >= 2) {
+    } else if (path6 === "React.useReducer" && names.length >= 2) {
       stableVariables.add(names[1]);
       addScopedVariable(stableVariablesByFunction, owner, names[1]);
-    } else if (path5 === "React.useBinding" && names.length >= 1) {
+    } else if (path6 === "React.useBinding" && names.length >= 1) {
       stableVariables.add(names[0]);
       addScopedVariable(stableVariablesByFunction, owner, names[0]);
       if (names.length >= 2) {
@@ -1727,7 +1808,7 @@ function buildReactModel(root) {
         bindingSetters.add(names[1]);
         addScopedVariable(stableVariablesByFunction, owner, names[1]);
       }
-    } else if (path5 === "React.useMemo" && names.length >= 1) {
+    } else if (path6 === "React.useMemo" && names.length >= 1) {
       if (isEmptyDependencyTable(args[1])) {
         stableVariables.add(names[0]);
         addScopedVariable(stableVariablesByFunction, owner, names[0]);
@@ -1736,16 +1817,16 @@ function buildReactModel(root) {
         addScopedVariable(externalMutableVariablesByFunction, owner, names[0]);
         addScopedVariable(instanceVariablesByFunction, owner, names[0]);
       }
-    } else if (path5 === "React.useCallback" && names.length >= 1 && isEmptyDependencyTable(args[1])) {
+    } else if (path6 === "React.useCallback" && names.length >= 1 && isEmptyDependencyTable(args[1])) {
       stableVariables.add(names[0]);
       addScopedVariable(stableVariablesByFunction, owner, names[0]);
-    } else if (path5 === "React.useRef" && names.length >= 1) {
+    } else if (path6 === "React.useRef" && names.length >= 1) {
       stableVariables.add(names[0]);
       refVariables.add(names[0]);
       addScopedVariable(stableVariablesByFunction, owner, names[0]);
       addScopedVariable(refVariablesByFunction, owner, names[0]);
     } else {
-      const final = path5.split(/[.:]/).at(-1) ?? "";
+      const final = path6.split(/[.:]/).at(-1) ?? "";
       if (/^use[A-Z0-9_]/.test(final)) {
         for (const name of names.slice(1)) {
           if (!STABLE_CUSTOM_HOOK_RETURN.test(name))
@@ -1769,11 +1850,11 @@ function buildReactModel(root) {
     if (!expression || expression.type !== "function_call")
       continue;
     const rawPath = expression.childForFieldName("name")?.text ?? "";
-    const path5 = resolvePath(rawPath, aliases, reactNamespaces, reactRobloxNamespaces);
-    if (path5 === "React.useState" && names.length >= 2) {
+    const path6 = resolvePath(rawPath, aliases, reactNamespaces, reactRobloxNamespaces);
+    if (path6 === "React.useState" && names.length >= 2) {
       stableVariables.add(names[1]);
       addScopedVariable(stableVariablesByFunction, owner, names[1]);
-    } else if (path5 === "React.useBinding" && names.length >= 1) {
+    } else if (path6 === "React.useBinding" && names.length >= 1) {
       stableVariables.add(names[0]);
       addScopedVariable(stableVariablesByFunction, owner, names[0]);
       addScopedVariable(externalMutableVariablesByFunction, owner, names[0]);
@@ -1888,7 +1969,7 @@ function createInlineSuppressionChecker(source) {
 
 // src/parser.ts
 import fs5 from "fs";
-import path5 from "path";
+import path6 from "path";
 import { Language, Parser } from "web-tree-sitter";
 
 // src/parser-compat.ts
@@ -2027,6 +2108,23 @@ function isCode(mask, start, end = start + 1) {
   }
   return true;
 }
+function matchingCodeDelimiterEnd(source, mask, start, opener, closer) {
+  if (source[start] !== opener || !isCode(mask, start))
+    return null;
+  let depth = 0;
+  for (let cursor = start;cursor < source.length; cursor += 1) {
+    if (!isCode(mask, cursor))
+      continue;
+    if (source[cursor] === opener)
+      depth += 1;
+    else if (source[cursor] === closer) {
+      depth -= 1;
+      if (depth === 0)
+        return cursor + 1;
+    }
+  }
+  return null;
+}
 function maskTypeAliases(source, mask) {
   const { lines: lines2, offsets } = lineData(source);
   const ranges = [];
@@ -2234,6 +2332,89 @@ function genericFunctionParameterRanges(source, mask) {
   }
   return ranges;
 }
+function genericFunctionReturnPrefixRanges(source, mask) {
+  const ranges = [];
+  const functionPattern = /\bfunction\b/g;
+  for (const match of source.matchAll(functionPattern)) {
+    const start = match.index;
+    if (!isCode(mask, start, start + match[0].length))
+      continue;
+    let cursor = start + match[0].length;
+    let genericDepth = 0;
+    while (cursor < source.length) {
+      if (!isCode(mask, cursor)) {
+        cursor += 1;
+        continue;
+      }
+      if (source[cursor] === "<")
+        genericDepth += 1;
+      else if (source[cursor] === ">" && genericDepth > 0)
+        genericDepth -= 1;
+      else if (source[cursor] === "(" && genericDepth === 0)
+        break;
+      cursor += 1;
+    }
+    if (source[cursor] !== "(")
+      continue;
+    const parameterEnd = matchingCodeDelimiterEnd(source, mask, cursor, "(", ")");
+    if (parameterEnd === null)
+      continue;
+    cursor = parameterEnd;
+    while (cursor < source.length && /\s/.test(source[cursor]))
+      cursor += 1;
+    if (source[cursor] !== ":" || !isCode(mask, cursor))
+      continue;
+    cursor += 1;
+    while (cursor < source.length && /\s/.test(source[cursor]))
+      cursor += 1;
+    if (source[cursor] !== "<")
+      continue;
+    const rangeStart = cursor;
+    const genericEnd = matchingCodeDelimiterEnd(source, mask, cursor, "<", ">");
+    if (genericEnd === null)
+      continue;
+    cursor = genericEnd;
+    while (cursor < source.length && /\s/.test(source[cursor]))
+      cursor += 1;
+    const typeParametersEnd = matchingCodeDelimiterEnd(source, mask, cursor, "(", ")");
+    if (typeParametersEnd === null)
+      continue;
+    cursor = typeParametersEnd;
+    while (cursor < source.length && /\s/.test(source[cursor]))
+      cursor += 1;
+    if (source.slice(cursor, cursor + 2) !== "->" || !isCode(mask, cursor, cursor + 2))
+      continue;
+    cursor += 2;
+    while (cursor < source.length && /[ \t]/.test(source[cursor]))
+      cursor += 1;
+    ranges.push({ start: rangeStart, end: cursor });
+  }
+  return ranges;
+}
+function normalizeLocalTypeofAnnotations(source, mask) {
+  const replacements = [];
+  const pattern = /\blocal\s+[A-Za-z_][A-Za-z0-9_]*\s*:\s*typeof\s*\(/g;
+  for (const match of source.matchAll(pattern)) {
+    const matchStart = match.index;
+    if (!isCode(mask, matchStart, matchStart + match[0].length))
+      continue;
+    const typeofStart = matchStart + match[0].lastIndexOf("typeof");
+    const open = source.indexOf("(", typeofStart + 6);
+    if (open < 0)
+      continue;
+    const end = matchingCodeDelimiterEnd(source, mask, open, "(", ")");
+    if (end === null)
+      continue;
+    const original = source.slice(typeofStart, end);
+    const padding = blankPreservingUtf8Bytes(original).slice(3);
+    replacements.push({ start: typeofStart, end, value: `any${padding}` });
+  }
+  let output = source;
+  for (const replacement of replacements.sort((a, b) => b.start - a.start)) {
+    output = `${output.slice(0, replacement.start)}${replacement.value}${output.slice(replacement.end)}`;
+  }
+  return output;
+}
 function normalizeGenericTypePackUses(source, mask) {
   const declarationRanges = genericFunctionParameterRanges(source, mask);
   const replacements = [];
@@ -2294,13 +2475,15 @@ function parserCompatibleSource(source) {
   const keywordCompatible = replaceContextualKeywords(source, mask);
   const literalCompatible = normalizeIntegerLiteralSuffixes(keywordCompatible, mask);
   const packCompatible = normalizeGenericTypePackUses(literalCompatible, mask);
+  const typeofCompatible = normalizeLocalTypeofAnnotations(packCompatible, mask);
   const ranges = [
     ...maskTypeAliases(source, mask),
     ...maskTypeLevelBlocks(source, mask),
     ...attributeRanges(source, mask),
-    ...explicitTypeArgumentRanges(source, mask)
+    ...explicitTypeArgumentRanges(source, mask),
+    ...genericFunctionReturnPrefixRanges(source, mask)
   ];
-  const masked = applyMasks(packCompatible, ranges);
+  const masked = applyMasks(typeofCompatible, ranges);
   return masked.replace(/^(\s*)type(?=\s*(?:\+=|-=|\*=|\/=|%=|\^=|\.\.=|=(?!=)))/gm, "$1_typ");
 }
 
@@ -2308,7 +2491,7 @@ function parserCompatibleSource(source) {
 var parserPromise = null;
 async function createParser() {
   await Parser.init();
-  const grammarPath = path5.resolve(import.meta.dir, "../vendor/tree-sitter-luau.wasm");
+  const grammarPath = path6.resolve(import.meta.dir, "../vendor/tree-sitter-luau.wasm");
   const grammar = new Uint8Array(fs5.readFileSync(grammarPath));
   const language = await Language.load(grammar);
   const parser = new Parser;
@@ -2433,8 +2616,8 @@ var INSTANCE_FACTORY_MEMBERS2 = new Set([
   "GetService",
   "WaitForChild"
 ]);
-function finalCallMember2(path6) {
-  return path6.split(/[.:]/).at(-1) ?? path6;
+function finalCallMember2(path7) {
+  return path7.split(/[.:]/).at(-1) ?? path7;
 }
 function declarationInitializer(node, name) {
   if (node.type !== "variable_declaration")
@@ -2502,8 +2685,8 @@ function expressionHasRobloxOrigin(expression, from, context, seen) {
   seen.add(root);
   return expressionHasRobloxOrigin(visibleInitializer(root, from, context), from, context, seen);
 }
-function hasRobloxReceiver(path6, call, context) {
-  const normalized = path6.replace(/\s+/g, "");
+function hasRobloxReceiver(path7, call, context) {
+  const normalized = path7.replace(/\s+/g, "");
   if (/^(?:game|workspace|script)(?:[.:]|$)/.test(normalized))
     return true;
   const root = normalized.match(/^([A-Za-z_][A-Za-z0-9_]*)/)?.[1];
@@ -2652,8 +2835,8 @@ function sourceHasHighFrequencyRobloxEvent(source) {
   }
   return false;
 }
-function knownYieldReason(path6, call, context) {
-  const normalized = path6.replace(/\s+/g, "");
+function knownYieldReason(path7, call, context) {
+  const normalized = path7.replace(/\s+/g, "");
   if (normalized === "task.wait")
     return "task.wait";
   if (normalized === "coroutine.yield")
@@ -2673,15 +2856,15 @@ function functionYieldPoint(node, context) {
     const owner = context.model.functionByNode.get(node.id);
     if (owner && nearest !== owner)
       continue;
-    const path6 = context.resolveCallPath(context.getCallPath(candidate) ?? "");
-    const reason = knownYieldReason(path6, candidate, context);
+    const path7 = context.resolveCallPath(context.getCallPath(candidate) ?? "");
+    const reason = knownYieldReason(path7, candidate, context);
     if (reason)
       return { call: candidate, reason };
   }
   return null;
 }
-function mutableDependencyBase(path6, externallyMutableRoots) {
-  const normalized = path6.replace(/\s+/g, "");
+function mutableDependencyBase(path7, externallyMutableRoots) {
+  const normalized = path7.replace(/\s+/g, "");
   if (/\.current(?:\.|$)/.test(normalized))
     return "";
   const segments = normalized.split(".");
@@ -2707,8 +2890,8 @@ var CONDITIONAL_TYPES = new Set([
   "while_statement",
   "repeat_statement"
 ]);
-function isHookPath(path6) {
-  const final = path6.split(/[.:]/).at(-1) ?? "";
+function isHookPath(path7) {
+  const final = path7.split(/[.:]/).at(-1) ?? "";
   return /^use[A-Z0-9_]/.test(final);
 }
 function assignmentTargetNode(statement) {
@@ -2784,8 +2967,8 @@ function functionInfoForNode(context, node) {
 function stateBindingsFor(context, owner) {
   return context.model.stateBindings.filter((binding) => binding.owner === owner);
 }
-function isEffectPath(path6) {
-  return path6 === "React.useEffect" || path6 === "React.useLayoutEffect";
+function isEffectPath(path7) {
+  return path7 === "React.useEffect" || path7 === "React.useLayoutEffect";
 }
 function dependencyExpressions(node) {
   if (!node || node.type !== "table_constructor")
@@ -3040,11 +3223,11 @@ function isManagedByCleanupContainer(call, context, callback) {
   let current = call.parent;
   while (current && !sameNode(current, callback.node)) {
     if (current.type === "function_call") {
-      const path6 = context.getCallPath(current) ?? "";
-      if (ALWAYS_MANAGED_METHOD.test(path6))
+      const path7 = context.getCallPath(current) ?? "";
+      if (ALWAYS_MANAGED_METHOD.test(path7))
         return true;
-      if (GENERIC_MANAGER_METHOD.test(path6)) {
-        const receiver = path6.split(":", 1)[0] ?? "";
+      if (GENERIC_MANAGER_METHOD.test(path7)) {
+        const receiver = path7.split(":", 1)[0] ?? "";
         if (MANAGER_ROOT.test(receiver))
           return true;
       }
@@ -3149,10 +3332,10 @@ function isCleanupOnlyTask(callbackNode, context) {
     return false;
   return calls.every((call) => /:(?:Destroy|Disconnect)$/.test(context.getCallPath(call) ?? ""));
 }
-function taskSeverity(path6, call, taskCallback, yieldPoint, context) {
-  if (path6 === "task.defer" && !yieldPoint)
+function taskSeverity(path7, call, taskCallback, yieldPoint, context) {
+  if (path7 === "task.defer" && !yieldPoint)
     return "suggestion";
-  if (path6 === "task.delay" && !yieldPoint) {
+  if (path7 === "task.delay" && !yieldPoint) {
     if (isCleanupOnlyTask(taskCallback, context))
       return "suggestion";
     const delay = numericTaskDelay(call, context);
@@ -3202,10 +3385,10 @@ end`,
     };
   }
   if ([...labels].every((label) => label.includes("task"))) {
-    const path6 = context.resolveCallPath(context.getCallPath(first.call) ?? "task.delay");
-    const taskCall = path6 === "task.defer" ? `task.defer(function()
+    const path7 = context.resolveCallPath(context.getCallPath(first.call) ?? "task.delay");
+    const taskCall = path7 === "task.defer" ? `task.defer(function()
 	doWork()
-end)` : path6 === "task.spawn" ? `task.spawn(function()
+end)` : path7 === "task.spawn" ? `task.spawn(function()
 	doWork()
 end)` : `task.delay(delaySeconds, function()
 	doWork()
@@ -3258,9 +3441,9 @@ end`,
 }
 function classifyResource(call, context, callback) {
   const rawPath = context.getCallPath(call) ?? "";
-  const path6 = context.resolveCallPath(rawPath);
+  const path7 = context.resolveCallPath(rawPath);
   const variable = assignedVariableName(call, callback);
-  const finalMember = path6.split(/[.:]/).at(-1) ?? path6;
+  const finalMember = path7.split(/[.:]/).at(-1) ?? path7;
   if (/:Connect$/.test(rawPath)) {
     const ownerExpression = connectionOwnerExpression(rawPath);
     const ownerIsInstance = isProvenInstanceExpression(ownerExpression, call, context, callback);
@@ -3329,7 +3512,7 @@ function classifyResource(call, context, callback) {
       }
     };
   }
-  if (path6 === "ReactRoblox.createRoot") {
+  if (path7 === "ReactRoblox.createRoot") {
     return {
       call,
       label: "React root",
@@ -3339,17 +3522,17 @@ function classifyResource(call, context, callback) {
       }
     };
   }
-  if (path6 === "task.delay" || path6 === "task.defer" || path6 === "task.spawn") {
+  if (path7 === "task.delay" || path7 === "task.defer" || path7 === "task.spawn") {
     const taskCallback = taskCallbackNode(call, context, callback);
     const yieldPoint = taskCallback ? functionYieldPoint(taskCallback, context) : null;
-    const outlivesEffect = path6 !== "task.spawn" || Boolean(yieldPoint);
+    const outlivesEffect = path7 !== "task.spawn" || Boolean(yieldPoint);
     if (!outlivesEffect)
       return null;
     return {
       call,
-      label: path6 === "task.spawn" ? "yielding spawned task" : path6 === "task.defer" ? "deferred task" : "delayed task",
+      label: path7 === "task.spawn" ? "yielding spawned task" : path7 === "task.defer" ? "deferred task" : "delayed task",
       detail: yieldPoint ? `The task can outlive the effect because it yields at ${yieldPoint.reason}.` : "The task is scheduled to run after the effect callback can finish.",
-      severity: taskSeverity(path6, call, taskCallback, yieldPoint, context),
+      severity: taskSeverity(path7, call, taskCallback, yieldPoint, context),
       variable,
       cleanupMatches(text, name) {
         if (name) {
@@ -3376,8 +3559,8 @@ var effectNeedsCleanup = {
       const rawPath = context.getCallPath(call);
       if (!rawPath)
         continue;
-      const path6 = context.resolveCallPath(rawPath);
-      if (path6 !== "React.useEffect" && path6 !== "React.useLayoutEffect")
+      const path7 = context.resolveCallPath(rawPath);
+      if (path7 !== "React.useEffect" && path7 !== "React.useLayoutEffect")
         continue;
       const callbackNode = firstFunctionArgument(context, call);
       const callback = functionInfoForNode(context, callbackNode);
@@ -3431,10 +3614,22 @@ function ownerForHook(context, call) {
   const owner = context.nearestFunction(call);
   return owner && (owner.isComponent || owner.isHook) ? owner : null;
 }
+function effectCallbackWithoutDeps(context, call) {
+  const path7 = context.resolveCallPath(context.getCallPath(call) ?? "");
+  if (!isEffectPath(path7))
+    return null;
+  const args = context.callArguments(call);
+  const callback = args[0];
+  if (callback?.type !== "function_definition")
+    return null;
+  if (args.length < 2 || args[1]?.type === "nil")
+    return callback;
+  return null;
+}
 function callbackAndDeps(context, call) {
-  const path6 = context.resolveCallPath(context.getCallPath(call) ?? "");
+  const path7 = context.resolveCallPath(context.getCallPath(call) ?? "");
   const args = context.callArguments(call);
-  if (path6 === "React.useImperativeHandle") {
+  if (path7 === "React.useImperativeHandle") {
     const callback2 = args[1];
     const deps2 = args[2];
     if (callback2?.type === "function_definition" && deps2?.type === "table_constructor")
@@ -3464,8 +3659,8 @@ function hasExternalSubscription(node, context) {
   for (const child of context.walk(node)) {
     if (child.type !== "function_call")
       continue;
-    const path6 = context.getCallPath(child) ?? "";
-    if (/:Connect$/.test(path6) || /BindToRenderStep$/.test(path6) || /:BindAction(?:AtPriority)?$/.test(path6))
+    const path7 = context.getCallPath(child) ?? "";
+    if (/:Connect$/.test(path7) || /BindToRenderStep$/.test(path7) || /:BindAction(?:AtPriority)?$/.test(path7))
       return true;
   }
   return false;
@@ -3499,6 +3694,33 @@ function setterCalledOutsideCallback(context, owner, callback, setterName) {
   }
   return false;
 }
+function guaranteedRepeatedStateChange(argument, stateName, context) {
+  if (argument.type === "table_constructor")
+    return true;
+  if (argument.type === "function_definition") {
+    const updater = functionInfoForNode(context, argument);
+    const previousName = updater?.parameters[0];
+    const returnStatement = updater?.body?.namedChildren.find((child) => child.type === "return_statement");
+    const returnValue = returnStatement?.namedChildren[0];
+    if (previousName && returnValue && guaranteedRepeatedStateChange(returnValue, previousName, context))
+      return true;
+    return false;
+  }
+  const text = argument.text.trim();
+  const escaped = stateName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  if (new RegExp(`^not\\s+${escaped}$`).test(text))
+    return true;
+  if (new RegExp(`^${escaped}\\s*[+-]\\s*(?:[1-9]\\d*(?:\\.\\d+)?|0?\\.\\d*[1-9]\\d*)$`).test(text))
+    return true;
+  if (new RegExp(`^(?:[1-9]\\d*(?:\\.\\d+)?|0?\\.\\d*[1-9]\\d*)\\s*\\+\\s*${escaped}$`).test(text))
+    return true;
+  if (argument.type === "function_call") {
+    const path7 = context.resolveCallPath(context.getCallPath(argument) ?? "");
+    if (path7 === "table.clone" || path7 === "table.create" || path7 === "table.pack")
+      return true;
+  }
+  return false;
+}
 function freshDependencyKind(node, owner) {
   if (node.type === "table_constructor")
     return "table";
@@ -3521,8 +3743,8 @@ var noDerivedStateEffect = {
   run(context) {
     const diagnostics = [];
     for (const call of context.findCalls()) {
-      const path6 = context.resolveCallPath(context.getCallPath(call) ?? "");
-      if (!isEffectPath(path6))
+      const path7 = context.resolveCallPath(context.getCallPath(call) ?? "");
+      if (!isEffectPath(path7))
         continue;
       const owner = ownerForHook(context, call);
       const parts = callbackAndDeps(context, call);
@@ -3560,28 +3782,48 @@ var noSelfUpdatingEffect = {
   id: "react-luau/no-self-updating-effect",
   category: "Effects",
   severity: "warning",
-  description: "Effects should not unconditionally update state that is also one of their dependencies.",
+  description: "Effects should not unconditionally update state in a way that schedules themselves again.",
   run(context) {
     const diagnostics = [];
     for (const call of context.findCalls()) {
-      const path6 = context.resolveCallPath(context.getCallPath(call) ?? "");
-      if (!isEffectPath(path6))
+      const path7 = context.resolveCallPath(context.getCallPath(call) ?? "");
+      if (!isEffectPath(path7))
         continue;
       const owner = ownerForHook(context, call);
+      if (!owner)
+        continue;
       const parts = callbackAndDeps(context, call);
-      if (!owner || !parts)
+      if (parts) {
+        const deps = parseDependencyRoots(parts.deps);
+        for (const binding of stateBindingsFor(context, owner)) {
+          if (!deps.has(binding.valueName))
+            continue;
+          for (const setterCall of directTopLevelCalls(context, parts.callback)) {
+            if (context.getCallPath(setterCall) !== binding.setterName)
+              continue;
+            diagnostics.push({
+              node: callNameNode(setterCall),
+              message: `${binding.setterName}() updates ${binding.valueName}, which is also in this effect's dependency table.`,
+              help: "Guard the update so it converges, move it to the originating event, or derive the value during render."
+            });
+          }
+        }
+        continue;
+      }
+      const callback = effectCallbackWithoutDeps(context, call);
+      if (!callback)
         continue;
-      const deps = parseDependencyRoots(parts.deps);
       for (const binding of stateBindingsFor(context, owner)) {
-        if (!deps.has(binding.valueName))
-          continue;
-        for (const setterCall of directTopLevelCalls(context, parts.callback)) {
+        for (const setterCall of directTopLevelCalls(context, callback)) {
           if (context.getCallPath(setterCall) !== binding.setterName)
             continue;
+          const argument = context.callArguments(setterCall)[0];
+          if (!argument || !guaranteedRepeatedStateChange(argument, binding.valueName, context))
+            continue;
           diagnostics.push({
             node: callNameNode(setterCall),
-            message: `${binding.setterName}() updates ${binding.valueName}, which is also in this effect's dependency table.`,
-            help: "Guard the update so it converges, move it to the originating event, or derive the value during render."
+            message: `${binding.setterName}() unconditionally changes ${binding.valueName} in an effect that runs after every render.`,
+            help: "Add a dependency table or convergence guard, move the update to the event that owns it, or derive the value during render."
           });
         }
       }
@@ -3597,8 +3839,8 @@ var noEffectWithFreshDeps = {
   run(context) {
     const diagnostics = [];
     for (const call of context.findCalls()) {
-      const path6 = context.resolveCallPath(context.getCallPath(call) ?? "");
-      if (!HOOKS_WITH_DEPS.has(path6))
+      const path7 = context.resolveCallPath(context.getCallPath(call) ?? "");
+      if (!HOOKS_WITH_DEPS.has(path7))
         continue;
       const owner = ownerForHook(context, call);
       const parts = callbackAndDeps(context, call);
@@ -3611,7 +3853,7 @@ var noEffectWithFreshDeps = {
         const label = dependency.type === "identifier" ? ` ${dependency.text}` : "";
         diagnostics.push({
           node: dependency,
-          message: `${path6} depends on${label || " an inline value"} that is a new ${kind} on every render.`,
+          message: `${path7} depends on${label || " an inline value"} that is a new ${kind} on every render.`,
           help: "Move the value inside the hook callback and depend on its simple inputs, or intentionally stabilize the value with useMemo/useCallback when identity is part of the contract."
         });
       }
@@ -3627,8 +3869,8 @@ var noMutableInDeps = {
   run(context) {
     const diagnostics = [];
     for (const call of context.findCalls()) {
-      const path6 = context.resolveCallPath(context.getCallPath(call) ?? "");
-      if (!HOOKS_WITH_DEPS.has(path6))
+      const path7 = context.resolveCallPath(context.getCallPath(call) ?? "");
+      if (!HOOKS_WITH_DEPS.has(path7))
         continue;
       const owner = ownerForHook(context, call);
       const parts = callbackAndDeps(context, call);
@@ -3721,23 +3963,61 @@ var HOOK_ARGUMENTS = new Map([
   ["React.useImperativeHandle", { callbackIndex: 1, depsIndex: 2 }]
 ]);
 function parameterNames2(functionNode) {
-  const names = new Set;
-  const parameters = functionNode.childForFieldName("parameters");
-  if (!parameters)
-    return names;
-  for (const node of parameters.namedChildren) {
-    for (const candidate of descendants(node)) {
-      if (candidate.type === "identifier")
-        names.add(candidate.text);
-    }
-  }
-  return names;
+  return new Set(parameterBindingNames(functionNode.childForFieldName("parameters")));
 }
 function* descendants(node) {
   yield node;
   for (const child of node.namedChildren)
     yield* descendants(child);
 }
+var TYPE_ONLY_NODES = new Set([
+  "type_definition",
+  "type_annotation",
+  "type_parameters",
+  "generic_type_list",
+  "generic_type",
+  "function_type",
+  "optional_type",
+  "object_type",
+  "union_type",
+  "intersection_type",
+  "tuple_type",
+  "singleton_type",
+  "variadic_type",
+  "variadic_type_pack"
+]);
+function isTypeOnlyChild(parent, child) {
+  if (TYPE_ONLY_NODES.has(child.type))
+    return true;
+  if (TYPE_ONLY_NODES.has(parent.type))
+    return true;
+  if (parent.type === "parameter") {
+    return !sameNode(parent.namedChildren.find((candidate) => candidate.type === "identifier"), child);
+  }
+  if (parent.type === "cast_expression" || parent.type === "type_cast_expression") {
+    return !sameNode(parent.namedChildren[0], child);
+  }
+  if (parent.type === "function_definition" || parent.type === "function_declaration") {
+    const name = parent.childForFieldName("name");
+    const parameters = parent.childForFieldName("parameters");
+    const body = parent.childForFieldName("body");
+    if (sameNode(child, name) || sameNode(child, parameters) || sameNode(child, body))
+      return false;
+    return true;
+  }
+  if (parent.type === "variable_list" && parent.parent?.parent?.type === "variable_declaration") {
+    return true;
+  }
+  return false;
+}
+function* runtimeDescendants(node) {
+  yield node;
+  for (const child of node.namedChildren) {
+    if (isTypeOnlyChild(node, child))
+      continue;
+    yield* runtimeDescendants(child);
+  }
+}
 function directBlockBindingNames(block, beforeIndex) {
   const names = new Set;
   for (const child of block.namedChildren) {
@@ -3813,8 +4093,8 @@ function rootIdentifierNode(node, root) {
   }
   return null;
 }
-function normalizeCapturedPath(path6, stableVariables, externallyMutableRoots) {
-  const normalized = normalizeExpressionText(path6);
+function normalizeCapturedPath(path7, stableVariables, externallyMutableRoots) {
+  const normalized = normalizeExpressionText(path7);
   const root = rootIdentifier(normalized);
   if (!root)
     return normalized;
@@ -3831,7 +4111,7 @@ function normalizeCapturedPath(path6, stableVariables, externallyMutableRoots) {
 }
 function capturedDependencyPaths(callback, available, stableVariables, externallyMutableRoots) {
   const captured = new Set;
-  for (const node of descendants(callback)) {
+  for (const node of runtimeDescendants(callback)) {
     if (node.type === "dot_index_expression" && outermostDotPath(node)) {
       const root = rootIdentifier(node.text);
       if (!root || !available.has(root) || GLOBALS.has(root) || stableVariables.has(root))
@@ -3900,8 +4180,81 @@ function expandLocalFunctionCaptures(captured, owner, available, stableVariables
     addCapture(capture);
   return result;
 }
+function dependencyCoveragePath(node) {
+  if (node.type === "cast_expression" || node.type === "type_cast_expression" || node.type === "parenthesized_expression") {
+    const expression = node.namedChildren[0];
+    if (expression)
+      return dependencyCoveragePath(expression);
+  }
+  if (node.type === "binary_expression") {
+    const left = node.childForFieldName("left") ?? node.namedChildren[0];
+    const right = node.childForFieldName("right") ?? node.namedChildren[1];
+    const isOr = node.children.some((child) => child.type === "or");
+    if (isOr && left && right?.type === "false")
+      return dependencyCoveragePath(left);
+  }
+  return normalizeExpressionText(node.text);
+}
 function dependencyPaths(node) {
-  return new Set(dependencyExpressions(node).map((dependency) => normalizeExpressionText(dependency.text)));
+  return new Set(dependencyExpressions(node).map(dependencyCoveragePath));
+}
+function transparentAliasPath(node) {
+  if (node.type === "cast_expression" || node.type === "type_cast_expression" || node.type === "parenthesized_expression") {
+    const expression = node.namedChildren[0];
+    return expression ? transparentAliasPath(expression) : null;
+  }
+  if (node.type !== "identifier" && node.type !== "dot_index_expression")
+    return null;
+  return normalizeExpressionText(node.text);
+}
+function immutableTransparentAliases(owner, context) {
+  const aliases = new Map;
+  if (!owner.body)
+    return aliases;
+  const mutated = mutatedOwnerLocals(owner, context);
+  for (const statement of owner.body.namedChildren) {
+    if (statement.type !== "variable_declaration")
+      continue;
+    const names = declarationNames2(statement);
+    const expressions = declarationExpressions3(statement);
+    for (let index = 0;index < names.length; index += 1) {
+      const name = names[index];
+      const expression = expressions[index];
+      if (!expression || mutated.has(name))
+        continue;
+      const source = transparentAliasPath(expression);
+      if (!source || source === name)
+        continue;
+      const sourceRoot = rootIdentifier(source);
+      if (!sourceRoot || mutated.has(sourceRoot))
+        continue;
+      aliases.set(name, source);
+    }
+  }
+  return aliases;
+}
+function resolveAliasPath(path7, aliases) {
+  let current = path7;
+  const visiting = new Set;
+  while (true) {
+    const root = rootIdentifier(current);
+    if (!root || visiting.has(root))
+      return current;
+    const source = aliases.get(root);
+    if (!source)
+      return current;
+    visiting.add(root);
+    current = `${source}${current.slice(root.length)}`;
+  }
+}
+function dependencyPathsWithAliases(node, aliases) {
+  const dependencies = dependencyPaths(node);
+  for (const dependency of [...dependencies]) {
+    const resolved = resolveAliasPath(dependency, aliases);
+    if (resolved !== dependency)
+      dependencies.add(resolved);
+  }
+  return dependencies;
 }
 var PURE_DERIVED_CALL = /^(?:math\.(?!random(?:seed)?$)[A-Za-z_][A-Za-z0-9_]*|string\.[A-Za-z_][A-Za-z0-9_]*|table\.(?:find|concat|clone|create|isfrozen)|(?:Color3|Vector2|Vector3|UDim|UDim2|CFrame|BrickColor|Rect|NumberRange|NumberSequence|ColorSequence|TweenInfo|Font|Ray|Region3|PhysicalProperties)\.[A-Za-z_][A-Za-z0-9_]*|[^:]+:(?:ToHSV|Lerp|Dot|Cross|FuzzyEq|Inverse|ToObjectSpace|ToWorldSpace))$/;
 function isPureDerivedExpression(node, context) {
@@ -3913,8 +4266,8 @@ function isPureDerivedExpression(node, context) {
     const rawPath = context.getCallPath(candidate);
     if (!rawPath)
       return false;
-    const path6 = normalizeExpressionText(context.resolveCallPath(rawPath));
-    if (!PURE_DERIVED_CALL.test(path6))
+    const path7 = normalizeExpressionText(context.resolveCallPath(rawPath));
+    if (!PURE_DERIVED_CALL.test(path7))
       return false;
   }
   return true;
@@ -3993,8 +4346,8 @@ function hasDynamicUnpackDependencies(node, context) {
       const rawPath = context.getCallPath(candidate);
       if (!rawPath)
         continue;
-      const path6 = normalizeExpressionText(context.resolveCallPath(rawPath));
-      if (path6 === "unpack" || path6 === "table.unpack")
+      const path7 = normalizeExpressionText(context.resolveCallPath(rawPath));
+      if (path7 === "unpack" || path7 === "table.unpack")
         return true;
     }
   }
@@ -4019,8 +4372,8 @@ function memoizedProducerDependencies(owner, context) {
       const rawPath = context.getCallPath(expression);
       if (!rawPath)
         continue;
-      const path6 = context.resolveCallPath(rawPath);
-      if (path6 !== "React.useMemo" && path6 !== "React.useCallback")
+      const path7 = context.resolveCallPath(rawPath);
+      if (path7 !== "React.useMemo" && path7 !== "React.useCallback")
         continue;
       const args = context.callArguments(expression);
       const deps = args[1];
@@ -4079,9 +4432,9 @@ function directCallsInExpression(node) {
   return calls;
 }
 function isCustomHookCall(call, context) {
-  const path6 = context.resolveCallPath(context.getCallPath(call) ?? "");
-  const final = path6.split(/[.:]/).at(-1) ?? "";
-  return !path6.startsWith("React.") && /^use[A-Z0-9_]/.test(final);
+  const path7 = context.resolveCallPath(context.getCallPath(call) ?? "");
+  const final = path7.split(/[.:]/).at(-1) ?? "";
+  return !path7.startsWith("React.") && /^use[A-Z0-9_]/.test(final);
 }
 var HANDLE_VALUE_NAME = /(?:ref|binding|tween|spring|motion|animation|controller|handle|connection|signal)$/i;
 var HANDLE_HOOK_NAME = /(?:Tween|Spring|Binding|Motion|Animated|Animation|Sound)$/i;
@@ -4091,8 +4444,8 @@ function isCalledAsFunction(owner, name, context) {
   for (const call of context.walk(owner.body)) {
     if (call.type !== "function_call")
       continue;
-    const path6 = normalizeExpressionText(context.getCallPath(call) ?? "");
-    if (path6 === name)
+    const path7 = normalizeExpressionText(context.getCallPath(call) ?? "");
+    if (path7 === name)
       return true;
   }
   return false;
@@ -4122,8 +4475,8 @@ function customHookDependencyHints(owner, context) {
         continue;
       const directHook = calls.find((call) => isCustomHookCall(call, context));
       if (directHook && expression.type === "function_call") {
-        const path6 = context.resolveCallPath(context.getCallPath(directHook) ?? "");
-        const final = path6.split(/[.:]/).at(-1) ?? "";
+        const path7 = context.resolveCallPath(context.getCallPath(directHook) ?? "");
+        const final = path7.split(/[.:]/).at(-1) ?? "";
         const likelyHandle = HANDLE_VALUE_NAME.test(name) || HANDLE_HOOK_NAME.test(final) || isCalledAsFunction(owner, name, context);
         if (likelyHandle) {
           hints.memberHandleRoots.add(name);
@@ -4133,14 +4486,14 @@ function customHookDependencyHints(owner, context) {
       }
       if (expression.type === "table_constructor") {
         const meaningfulCalls = calls.filter((call) => {
-          const path6 = context.resolveCallPath(context.getCallPath(call) ?? "");
-          return !/^(?:Color3|Vector2|Vector3|UDim|UDim2|CFrame|TweenInfo|NumberSequence|ColorSequence)\./.test(path6);
+          const path7 = context.resolveCallPath(context.getCallPath(call) ?? "");
+          return !/^(?:Color3|Vector2|Vector3|UDim|UDim2|CFrame|TweenInfo|NumberSequence|ColorSequence)\./.test(path7);
         });
         const allHandleHooks = meaningfulCalls.length > 0 && meaningfulCalls.every((call) => {
           if (!isCustomHookCall(call, context))
             return false;
-          const path6 = context.resolveCallPath(context.getCallPath(call) ?? "");
-          const final = path6.split(/[.:]/).at(-1) ?? "";
+          const path7 = context.resolveCallPath(context.getCallPath(call) ?? "");
+          const final = path7.split(/[.:]/).at(-1) ?? "";
           return HANDLE_HOOK_NAME.test(final);
         });
         if (allHandleHooks)
@@ -4170,12 +4523,13 @@ var exhaustiveDeps = {
     const derivedDependenciesByOwner = new Map;
     const dependencyHintsByOwner = new Map;
     const memoizedProducersByOwner = new Map;
+    const transparentAliasesByOwner = new Map;
     for (const call of context.findCalls()) {
       const rawPath = context.getCallPath(call);
       if (!rawPath)
         continue;
-      const path6 = context.resolveCallPath(rawPath);
-      const shape = HOOK_ARGUMENTS.get(path6);
+      const path7 = context.resolveCallPath(rawPath);
+      const shape = HOOK_ARGUMENTS.get(path7);
       if (!shape)
         continue;
       const args = context.callArguments(call);
@@ -4191,7 +4545,12 @@ var exhaustiveDeps = {
       const stableVariables = context.model.stableVariablesByFunction.get(ownerKey) ?? new Set;
       const externallyMutableRoots = context.model.externalMutableVariablesByFunction.get(ownerKey) ?? new Set;
       const functionExpandedCaptures = expandLocalFunctionCaptures(capturedDependencyPaths(callback, available, stableVariables, externallyMutableRoots), owner, available, stableVariables, externallyMutableRoots, context);
-      const dependencies = dependencyPaths(deps);
+      let transparentAliases = transparentAliasesByOwner.get(ownerKey);
+      if (!transparentAliases) {
+        transparentAliases = immutableTransparentAliases(owner, context);
+        transparentAliasesByOwner.set(ownerKey, transparentAliases);
+      }
+      const dependencies = dependencyPathsWithAliases(deps, transparentAliases);
       let derivedDependencies = derivedDependenciesByOwner.get(ownerKey);
       if (!derivedDependencies) {
         derivedDependencies = derivedLocalDependencies(owner, available, stableVariables, externallyMutableRoots, context);
@@ -4205,7 +4564,7 @@ var exhaustiveDeps = {
         diagnostics.push({
           node: tableStartNode(deps),
           severity: "suggestion",
-          message: `${path6} uses dynamic unpack(...) dependencies, so exhaustive dependency analysis is partial.`,
+          message: `${path7} uses dynamic unpack(...) dependencies, so exhaustive dependency analysis is partial.`,
           help: "The analyzer cannot prove which values unpack(...) contributes. Review the explicit dependencies and the custom hook contract."
         });
         continue;
@@ -4226,7 +4585,7 @@ var exhaustiveDeps = {
       if (reactiveMissing.length > 0) {
         diagnostics.push({
           node: tableStartNode(deps),
-          message: `${path6} dependency table is missing ${reactiveMissing.join(", ")}.`,
+          message: `${path7} dependency table is missing ${reactiveMissing.join(", ")}.`,
           help: `Add ${reactiveMissing.join(", ")} to the dependency table, or stop capturing ${reactiveMissing.length === 1 ? "that value" : "those values"} in the callback.`
         });
       }
@@ -4234,7 +4593,7 @@ var exhaustiveDeps = {
         diagnostics.push({
           node: tableStartNode(deps),
           severity: "suggestion",
-          message: `${path6} captures memoized value ${transitivelyCoveredMemoized.join(", ")} without listing ${transitivelyCoveredMemoized.length === 1 ? "it directly" : "them directly"}, but ${transitivelyCoveredMemoized.length === 1 ? "its memo dependencies are" : "their memo dependencies are"} already covered.`,
+          message: `${path7} captures memoized value ${transitivelyCoveredMemoized.join(", ")} without listing ${transitivelyCoveredMemoized.length === 1 ? "it directly" : "them directly"}, but ${transitivelyCoveredMemoized.length === 1 ? "its memo dependencies are" : "their memo dependencies are"} already covered.`,
           help: "The producing memo dependencies are already covered. Listing the memoized value directly can make the dependency relationship clearer."
         });
       }
@@ -4242,7 +4601,7 @@ var exhaustiveDeps = {
         diagnostics.push({
           node: tableStartNode(deps),
           severity: "suggestion",
-          message: `${path6} captures custom-hook handle ${uncertainHandles.join(", ")} without listing ${uncertainHandles.length === 1 ? "it as a dependency" : "them as dependencies"}.`,
+          message: `${path7} captures custom-hook handle ${uncertainHandles.join(", ")} without listing ${uncertainHandles.length === 1 ? "it as a dependency" : "them as dependencies"}.`,
           help: "The analyzer cannot prove this custom-hook return is stable. Check the hook contract before changing the dependency table."
         });
       }
@@ -4276,8 +4635,8 @@ function createElementCallsInLoop(context, loop) {
   for (const node of context.walk(loop)) {
     if (node.type !== "function_call")
       continue;
-    const path6 = context.resolveCallPath(context.getCallPath(node) ?? "");
-    if (path6 === "React.createElement")
+    const path7 = context.resolveCallPath(context.getCallPath(node) ?? "");
+    if (path7 === "React.createElement")
       result.push(node);
   }
   return result;
@@ -4333,8 +4692,8 @@ var noCreateContextInRender = {
   run(context) {
     const diagnostics = [];
     for (const call of context.findCalls()) {
-      const path6 = context.resolveCallPath(context.getCallPath(call) ?? "");
-      if (path6 !== "React.createContext")
+      const path7 = context.resolveCallPath(context.getCallPath(call) ?? "");
+      if (path7 !== "React.createContext")
         continue;
       const owner = context.nearestFunction(call);
       if (!owner || !owner.isComponent && !owner.isHook)
@@ -4370,8 +4729,8 @@ function isRenderedBy(context, component, name) {
       continue;
     if (context.nearestFunction(call) !== component)
       continue;
-    const path6 = context.resolveCallPath(context.getCallPath(call) ?? "");
-    if (path6 !== "React.createElement")
+    const path7 = context.resolveCallPath(context.getCallPath(call) ?? "");
+    if (path7 !== "React.createElement")
       continue;
     if (context.callArguments(call)[0]?.text.trim() === name)
       return true;
@@ -4415,63 +4774,6 @@ var noNestedComponentDefinition = {
   }
 };
 
-// src/module-resolution.ts
-import path6 from "path";
-function normalizeRelative2(value) {
-  return value.split(path6.sep).join("/");
-}
-function moduleKeys(relativePath) {
-  let normalized = normalizeRelative2(relativePath).replace(/\.(?:lua|luau)$/i, "");
-  if (normalized.endsWith("/init"))
-    normalized = normalized.slice(0, -"/init".length);
-  const segments = normalized.split("/").filter(Boolean);
-  if (segments[0]?.toLowerCase() === "src")
-    segments.shift();
-  const keys = new Set;
-  for (let index = 0;index < segments.length; index += 1) {
-    const suffix = segments.slice(index).join(".").toLowerCase();
-    if (suffix)
-      keys.add(suffix);
-  }
-  return [...keys];
-}
-function normalizeRequireTarget(text) {
-  return (text.match(/[A-Za-z_][A-Za-z0-9_]*/g) ?? []).join(".").toLowerCase();
-}
-function buildUniqueFeatureAliases(modules, featureByModuleId) {
-  const owners = new Map;
-  for (const module of modules) {
-    for (const key of module.keys) {
-      const ids = owners.get(key) ?? new Set;
-      ids.add(module.id);
-      owners.set(key, ids);
-    }
-  }
-  const aliases = new Map;
-  for (const module of modules) {
-    const value = featureByModuleId.get(module.id);
-    if (value === undefined)
-      continue;
-    for (const key of module.keys) {
-      const ids = owners.get(key);
-      if (ids?.size === 1 && ids.has(module.id))
-        aliases.set(key, value);
-    }
-  }
-  return aliases;
-}
-function resolveModuleReference(target, aliases) {
-  let candidate = target;
-  while (true) {
-    if (aliases.has(candidate))
-      return aliases.get(candidate);
-    const separator = candidate.indexOf(".");
-    if (separator < 0)
-      return null;
-    candidate = candidate.slice(separator + 1);
-  }
-}
-
 // src/rules/parameter-mutations.ts
 var analysisCache = new WeakMap;
 var EMPTY_INDEXES = new Set;
@@ -7194,6 +7496,20 @@ function staticIterationImports(context) {
   }
   return result;
 }
+function nonReactHookImports(context) {
+  const result = new Set;
+  for (const node of context.walk(context.root)) {
+    if (node.type !== "variable_declaration")
+      continue;
+    const match = node.text.match(/^\s*local\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*require\s*\((.*?)\)\s*$/s);
+    if (!match || !/^use[A-Z0-9_]/.test(match[1]))
+      continue;
+    const kind = resolveModuleReference(normalizeRequireTarget(match[2]), context.project.reactHookModules);
+    if (kind === false)
+      result.add(match[1]);
+  }
+  return result;
+}
 function conditionalHookModeImports(context) {
   const result = new Map;
   for (const node of context.walk(context.root)) {
@@ -7241,30 +7557,12 @@ function controlledParameterIndex(controlFlow, fn, summary) {
   }
   return null;
 }
-function isStableModeArgument(node, context) {
-  if (!node)
-    return true;
-  const text = node.text.trim();
-  if (["true", "false", "nil"].includes(text))
-    return true;
-  if ([
-    "number",
-    "string",
-    "string_content",
-    "table_constructor",
-    "function_definition"
-  ].includes(node.type))
-    return true;
-  if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(text) && context.model.stableVariables.has(text))
-    return true;
-  return false;
-}
 function dynamicHookModeFixPreview(hookName, argumentText) {
   return {
     kind: "pattern",
     before: `local value = ${hookName}(${argumentText})`,
-    after: `local value = ${hookName}(true) -- or false; keep this mode fixed for this call site`,
-    note: "A custom hook may choose different internal hooks only when this mode is stable for the lifetime of the component instance."
+    after: `local value = ${hookName}(${argumentText}) -- keep the hook-topology mode stable for this instance`,
+    note: "A custom hook may choose different internal hooks only when the value controlling that choice stays stable for the lifetime of the component instance."
   };
 }
 function unwrapIteratorExpression(text) {
@@ -7284,6 +7582,17 @@ function declarationExpressions4(node) {
 function isEmptyTable(node) {
   return Boolean(node?.type === "table_constructor" && node.namedChildren.every((child) => child.type !== "field"));
 }
+function tableConstructorHasStableArity(node) {
+  if (node.type !== "table_constructor")
+    return false;
+  const fields = node.namedChildren.filter((child) => child.type === "field");
+  if (fields.length === 0)
+    return true;
+  if (fields.some((field) => [...field.namedChildren].some((child) => child.type === "vararg_expression")))
+    return false;
+  const last = fields.at(-1);
+  return !last?.namedChildren.some((child) => child.type === "function_call");
+}
 function stableShapeVariablesByFunction(context) {
   const stable = new Map;
   const functionsByName = new Map;
@@ -7310,7 +7619,7 @@ function stableShapeVariablesByFunction(context) {
       const expression = expressions[index] ?? expressions[0];
       if (!expression)
         continue;
-      if (expression.type === "table_constructor") {
+      if (expression.type === "table_constructor" && tableConstructorHasStableArity(expression)) {
         namesFor(owner).add(names[index]);
         continue;
       }
@@ -7337,7 +7646,7 @@ function stableShapeVariablesByFunction(context) {
     if (!expression)
       return false;
     if (expression.type === "table_constructor")
-      return true;
+      return tableConstructorHasStableArity(expression);
     const text = expression.text.trim();
     if (!owner || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(text))
       return false;
@@ -7390,6 +7699,187 @@ function stableShapeVariablesByFunction(context) {
   }
   return stable;
 }
+function moduleInvariantVariables(context) {
+  const declarations = new Map;
+  const reassigned = new Set;
+  for (const node of context.walk(context.root)) {
+    if (node.type === "variable_declaration" && !context.nearestFunction(node)) {
+      for (const name of declarationNames2(node))
+        declarations.set(name, node);
+      continue;
+    }
+    if (node.type !== "assignment_statement" || node.parent?.type === "variable_declaration")
+      continue;
+    const variableList = node.namedChildren.find((child) => child.type === "variable_list");
+    for (const target of variableList?.namedChildren ?? []) {
+      if (target.type === "identifier")
+        reassigned.add(target.text);
+    }
+  }
+  return new Set([...declarations.keys()].filter((name) => !reassigned.has(name)));
+}
+function simpleConditionRoot(controlFlow) {
+  if (controlFlow.type !== "if_statement" && controlFlow.type !== "if_expression")
+    return null;
+  const condition = controlFlow.namedChildren[0];
+  if (!condition)
+    return null;
+  const text = condition.text.trim();
+  const match = text.match(/^(?:not\s+)?([A-Za-z_][A-Za-z0-9_]*)(?:\s*(?:==|~=)\s*(?:true|false|nil))?$/);
+  return match?.[1] ?? null;
+}
+function conditionIsProvablyInvariant(controlFlow, fn, context, moduleInvariants) {
+  const condition = controlFlow.namedChildren[0];
+  if (!condition)
+    return false;
+  if (["true", "false", "nil", "number", "string"].includes(condition.type))
+    return true;
+  const root = simpleConditionRoot(controlFlow);
+  if (!root)
+    return false;
+  if (moduleInvariants.has(root))
+    return true;
+  return Boolean(context.model.stableVariablesByFunction.get(nodeKey(fn.node))?.has(root));
+}
+function branchHookSequence(branch, fn, context) {
+  const hooks = [];
+  for (const node of context.walk(branch)) {
+    if (node.type !== "function_call")
+      continue;
+    if (context.nearestFunction(node) !== fn)
+      continue;
+    const rawPath = context.getCallPath(node);
+    if (!rawPath)
+      continue;
+    const path7 = context.resolveCallPath(rawPath);
+    if (!isHookPath(path7))
+      continue;
+    const nestedControl = findAncestorBetween(node, branch, (ancestor) => CONDITIONAL_TYPES.has(ancestor.type));
+    if (nestedControl)
+      return null;
+    hooks.push(path7);
+  }
+  return hooks;
+}
+function ifBranchesHaveEquivalentBuiltInTopology(controlFlow, fn, context) {
+  if (controlFlow.type !== "if_statement")
+    return false;
+  const thenBlock = controlFlow.namedChildren.find((child) => child.type === "block");
+  const elseStatement = controlFlow.namedChildren.find((child) => child.type === "else_statement");
+  const elseBlock = elseStatement?.namedChildren.find((child) => child.type === "block");
+  if (!thenBlock || !elseBlock)
+    return false;
+  const thenHooks = branchHookSequence(thenBlock, fn, context);
+  const elseHooks = branchHookSequence(elseBlock, fn, context);
+  if (!thenHooks || !elseHooks || thenHooks.length !== elseHooks.length)
+    return false;
+  if (!thenHooks.every((path7, index) => path7 === elseHooks[index]))
+    return false;
+  return thenHooks.every((path7) => path7.startsWith("React."));
+}
+function stateModeStability(name, owner, context) {
+  const binding = context.model.stateBindings.find((candidate) => candidate.owner === owner && candidate.valueName === name);
+  if (!binding || !owner.body)
+    return null;
+  const initializerText = binding.initializer?.text.trim() ?? "nil";
+  const stableLiteral = /^(?:true|false|nil|-?\d+(?:\.\d+)?|"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')$/;
+  let sawIndirectSetterReference = false;
+  for (const node of context.walk(owner.body)) {
+    if (node.type === "function_call" && context.getCallPath(node) === binding.setterName) {
+      const argument = context.callArguments(node)[0];
+      if (!argument || !stableLiteral.test(initializerText) || argument.text.trim() !== initializerText)
+        return "unstable";
+      continue;
+    }
+    if (node.type !== "identifier" || node.text !== binding.setterName)
+      continue;
+    if (node.startIndex >= binding.declaration.startIndex && node.endIndex <= binding.declaration.endIndex)
+      continue;
+    if (node.parent?.type === "function_call")
+      continue;
+    sawIndirectSetterReference = true;
+  }
+  if (sawIndirectSetterReference)
+    return "unknown";
+  return "stable";
+}
+function localAliasExpression(name, owner, context) {
+  if (!owner.body)
+    return null;
+  let result = null;
+  for (const node of context.walk(owner.body)) {
+    if (node.type !== "variable_declaration" || context.nearestFunction(node) !== owner)
+      continue;
+    const names = declarationNames2(node);
+    const index = names.indexOf(name);
+    if (index < 0)
+      continue;
+    const expressions = declarationExpressions4(node);
+    const expression = expressions[index] ?? expressions[0] ?? null;
+    if (result)
+      return null;
+    result = expression;
+  }
+  return result;
+}
+function modeValueStability(node, owner, context, moduleInvariants, depth = 0) {
+  if (!node)
+    return "stable";
+  if (depth > 4)
+    return "unknown";
+  const text = node.text.trim();
+  if (["true", "false", "nil"].includes(text))
+    return "stable";
+  if (["number", "string", "string_content", "function_definition"].includes(node.type))
+    return "stable";
+  const root = text.match(/^([A-Za-z_][A-Za-z0-9_]*)/)?.[1];
+  if (!root)
+    return "unknown";
+  const stateStability = stateModeStability(root, owner, context);
+  if (stateStability)
+    return stateStability;
+  if (moduleInvariants.has(root))
+    return "stable";
+  if (context.model.stableVariablesByFunction.get(nodeKey(owner.node))?.has(root))
+    return "stable";
+  if (text === root) {
+    const alias = localAliasExpression(root, owner, context);
+    if (alias && alias.text.trim() !== root)
+      return modeValueStability(alias, owner, context, moduleInvariants, depth + 1);
+  }
+  return "unknown";
+}
+function tableFieldValue(table, accessPath) {
+  if (!table || accessPath === "")
+    return table;
+  if (table.type !== "table_constructor")
+    return;
+  let current = table;
+  for (const part of accessPath.split(".")) {
+    if (!current || current.type !== "table_constructor")
+      return;
+    const field = current.namedChildren.find((child) => {
+      if (child.type !== "field")
+        return false;
+      return child.namedChildren[0]?.type === "identifier" && child.namedChildren[0]?.text === part;
+    });
+    if (!field)
+      return;
+    current = field.namedChildren[1];
+  }
+  return current;
+}
+function controlledAccessPaths(summary, parameterIndex) {
+  const paths = new Set;
+  for (const [conditionName, index] of Object.entries(summary.conditionVariables)) {
+    if (index !== parameterIndex)
+      continue;
+    paths.add(summary.conditionAccessPaths?.[conditionName] ?? "");
+  }
+  if (paths.size === 0)
+    paths.add("");
+  return [...paths];
+}
 function loopIterationIsProvablyStable(loop, imports, owner, stableShapes) {
   const numeric = loop.namedChildren.find((child) => child.type === "for_numeric_clause");
   if (numeric) {
@@ -7451,9 +7941,9 @@ function impossibleNilGuardReturn(node, fn, parameterTypes) {
   }
   return false;
 }
-function hasReachableReturnBefore(call, fn, context, cache) {
+function reachableReturnsBefore(call, fn, context, cache) {
   if (!fn.body)
-    return false;
+    return [];
   const key = nodeKey(fn.node);
   let returns = cache.get(key);
   if (!returns) {
@@ -7461,7 +7951,21 @@ function hasReachableReturnBefore(call, fn, context, cache) {
     returns = [...context.walk(fn.body)].filter((node) => node.type === "return_statement" && !isNestedInsideFunction(node, fn.node) && !impossibleNilGuardReturn(node, fn, parameterTypes));
     cache.set(key, returns);
   }
-  return returns.some((node) => node.endIndex <= call.startIndex);
+  return returns.filter((node) => node.endIndex <= call.startIndex);
+}
+function returnIsControlledByStableTopologyMode(node, fn, summary, context, moduleInvariants) {
+  let current = node.parent;
+  while (current && current !== fn.node) {
+    if (current.type === "if_statement" || current.type === "if_expression") {
+      if (summary && controlledParameterIndex(current, fn, summary) !== null)
+        return true;
+      if (conditionIsProvablyInvariant(current, fn, context, moduleInvariants))
+        return true;
+      return false;
+    }
+    current = current.parent;
+  }
+  return false;
 }
 function conditionalFixPreview(kind, hookName) {
   if (kind === "for statement") {
@@ -7533,15 +8037,21 @@ var rulesOfHooks = {
   description: "Hooks must run in the same order on every render of a React component or custom hook.",
   run(context) {
     const diagnostics = [];
+    if (!context.model.isReactFile)
+      return diagnostics;
     const staticImports = staticIterationImports(context);
     const stableShapes = stableShapeVariablesByFunction(context);
+    const moduleInvariants = moduleInvariantVariables(context);
     const modeImports = conditionalHookModeImports(context);
+    const ignoredHookImports = nonReactHookImports(context);
     const currentModeSummary = currentConditionalHookMode(context);
     const reachableReturns = new Map;
     for (const call of context.findCalls()) {
       const rawPath = context.getCallPath(call);
       if (!rawPath)
         continue;
+      if (ignoredHookImports.has(rawPath))
+        continue;
       const path7 = context.resolveCallPath(rawPath);
       if (!isHookPath(path7))
         continue;
@@ -7570,25 +8080,36 @@ end`,
       const importedMode = modeImports.get(rawPath);
       if (importedMode) {
         const args = context.callArguments(call);
-        const dynamicIndexes = importedMode.parameterIndexes.filter((index) => !isStableModeArgument(args[index], context));
-        if (dynamicIndexes.length > 0) {
-          const firstIndex = dynamicIndexes[0];
-          const argument = args[firstIndex];
+        const unstableControls = importedMode.parameterIndexes.flatMap((index) => controlledAccessPaths(importedMode, index).map((accessPath) => {
+          const argument = args[index];
+          const value = tableFieldValue(argument, accessPath);
+          const stability = accessPath !== "" ? argument?.type === "table_constructor" ? value ? modeValueStability(value, fn, context, moduleInvariants) : "stable" : "unknown" : modeValueStability(argument, fn, context, moduleInvariants);
+          return { index, accessPath, argument, value, stability };
+        }).filter((control) => control.stability === "unstable"));
+        if (unstableControls.length > 0) {
+          const first = unstableControls[0];
+          const firstIndex = first.index;
+          const argument = first.argument;
           const parameterOffset = importedMode.parameterIndexes.indexOf(firstIndex);
-          const parameterName = importedMode.parameterNames[parameterOffset] ?? `argument ${firstIndex + 1}`;
-          const argumentText = argument?.text.trim() || "<omitted>";
+          const baseParameterName = importedMode.parameterNames[parameterOffset] ?? `argument ${firstIndex + 1}`;
+          const parameterName = first.accessPath ? `${baseParameterName}.${first.accessPath}` : baseParameterName;
+          const argumentText = first.value?.text.trim() || argument?.text.trim() || "<omitted>";
           diagnostics.push({
-            node: argument ?? callNameNode(call),
-            highlights: dynamicIndexes.map((index) => args[index]).filter((node) => Boolean(node)),
-            message: `Hook ${rawPath} receives render-varying hook mode ${parameterName} from ${argumentText}; if it changes between renders, the custom hook can execute a different hook sequence.`,
-            help: `Pass a stable mode at this call site, or refactor ${rawPath} so it always calls the same hooks regardless of ${parameterName}.`,
+            node: first.value ?? argument ?? callNameNode(call),
+            highlights: unstableControls.map((control) => control.value ?? control.argument).filter((node) => Boolean(node)),
+            message: `Hook ${rawPath} receives hook-topology mode ${parameterName} from ${argumentText}, which is updated between renders and can make the custom hook execute a different hook sequence.`,
+            help: `Keep ${parameterName} stable for this hook instance, or refactor ${rawPath} so it always calls the same hooks regardless of that mode.`,
             fixPreview: dynamicHookModeFixPreview(rawPath, argumentText)
           });
         }
       }
       const controlFlow = findAncestorBetween(call, fn.node, (node) => CONDITIONAL_TYPES.has(node.type));
       if (controlFlow) {
-        if (currentModeSummary && currentModeSummary.knownCallSites > 0 && controlledParameterIndex(controlFlow, fn, currentModeSummary) !== null)
+        if (currentModeSummary && controlledParameterIndex(controlFlow, fn, currentModeSummary) !== null)
+          continue;
+        if (conditionIsProvablyInvariant(controlFlow, fn, context, moduleInvariants))
+          continue;
+        if (ifBranchesHaveEquivalentBuiltInTopology(controlFlow, fn, context))
           continue;
         if (controlFlow.type === "for_statement" && loopIterationIsProvablyStable(controlFlow, staticImports, fn, stableShapes))
           continue;
@@ -7602,7 +8123,8 @@ end`,
         });
         continue;
       }
-      if (hasReachableReturnBefore(call, fn, context, reachableReturns)) {
+      const earlierReturns = reachableReturnsBefore(call, fn, context, reachableReturns);
+      if (earlierReturns.length > 0 && !earlierReturns.every((node) => returnIsControlledByStableTopologyMode(node, fn, currentModeSummary, context, moduleInvariants))) {
         diagnostics.push({
           node: callNameNode(call),
           message: `Hook ${path7} may run after an earlier reachable return, so some renders can execute fewer hooks.`,
@@ -8075,7 +8597,7 @@ function toDiagnostic(file, ruleId, category, severity, input) {
 }
 async function analyzeReactFile(input, tree) {
   const parsedTree = tree ?? await parseLuau(input.source);
-  const model = buildReactModel(parsedTree.rootNode);
+  const model = buildReactModel(parsedTree.rootNode, input.project);
   if (!input.forceScan && !model.isReactFile) {
     return { relativePath: input.relativePath, isReactFile: false, scanned: false, diagnostics: [] };
   }
@@ -8447,37 +8969,81 @@ function parameterName(parameter) {
 function branchContainsHookCall(text) {
   return /\b(?:[A-Za-z_][A-Za-z0-9_]*[.:])?use[A-Z0-9_][A-Za-z0-9_]*\s*\(/.test(text);
 }
+var BUILT_IN_REACT_HOOK_NAMES = new Set([
+  "useState",
+  "useEffect",
+  "useLayoutEffect",
+  "useMemo",
+  "useCallback",
+  "useContext",
+  "useReducer",
+  "useRef",
+  "useImperativeHandle",
+  "useBinding"
+]);
+function simpleBranchHookPaths(text) {
+  if (/\b(?:if|for|while|repeat|function)\b/.test(text))
+    return null;
+  return [...text.matchAll(/\b(React\.(use[A-Z0-9_][A-Za-z0-9_]*))\s*\(/g)].map((match) => match[2]);
+}
+function simpleIfHasEquivalentBuiltInTopology(source, ifStart) {
+  if (ifStart === undefined)
+    return false;
+  const statement = source.slice(ifStart).match(/^if\b[\s\S]*?\bthen\b([\s\S]*?)\belse\b([\s\S]*?)\bend\b/);
+  if (!statement)
+    return false;
+  const left = simpleBranchHookPaths(statement[1] ?? "");
+  const right = simpleBranchHookPaths(statement[2] ?? "");
+  if (!left || !right || left.length === 0 || left.length !== right.length)
+    return false;
+  return left.every((name, index) => name === right[index] && BUILT_IN_REACT_HOOK_NAMES.has(name));
+}
 function conditionAliasesForParameter(source, parameter) {
-  const aliases = new Set([parameter]);
+  const aliases = new Map([[parameter, ""]]);
   const escaped = parameter.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  for (const match of source.matchAll(new RegExp(`\\b${escaped}((?:\\.[A-Za-z_][A-Za-z0-9_]*)+)`, "g"))) {
+    aliases.set(`${parameter}${match[1]}`, match[1].slice(1));
+  }
   const directPatterns = [
-    new RegExp(`^\\s*local\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*=\\s*${escaped}\\s*$`, "gm"),
-    new RegExp(`^\\s*local\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*=\\s*not\\s+${escaped}\\s*$`, "gm"),
-    new RegExp(`^\\s*local\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*=\\s*${escaped}\\s*(?:==|~=)\\s*(?:true|false|nil)\\s*$`, "gm"),
-    new RegExp(`^\\s*local\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*=\\s*(?:true|false|nil)\\s*(?:==|~=)\\s*${escaped}\\s*$`, "gm"),
-    new RegExp(`^\\s*local\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*=\\s*if\\s+${escaped}\\s*(?:==|~=)\\s*nil\\s+then\\s+(?:true|false)\\s+else\\s+${escaped}\\s*$`, "gm"),
-    new RegExp(`^\\s*local\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*=\\s*if\\s+${escaped}\\s+then\\s+(?:true|false)\\s+else\\s+(?:true|false)\\s*$`, "gm")
+    new RegExp(`^\\s*local\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*=\\s*(${escaped}(?:\\.[A-Za-z_][A-Za-z0-9_]*)*)\\s*$`, "gm"),
+    new RegExp(`^\\s*local\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*=\\s*not\\s+(${escaped}(?:\\.[A-Za-z_][A-Za-z0-9_]*)*)\\s*$`, "gm"),
+    new RegExp(`^\\s*local\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*=\\s*(${escaped}(?:\\.[A-Za-z_][A-Za-z0-9_]*)*)\\s*(?:==|~=)\\s*(?:true|false|nil)\\s*$`, "gm"),
+    new RegExp(`^\\s*local\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*=\\s*(?:true|false|nil)\\s*(?:==|~=)\\s*(${escaped}(?:\\.[A-Za-z_][A-Za-z0-9_]*)*)\\s*$`, "gm")
   ];
   for (const pattern of directPatterns) {
-    for (const match of source.matchAll(pattern))
-      aliases.add(match[1]);
+    for (const match of source.matchAll(pattern)) {
+      const sourcePath = match[2];
+      const accessPath = sourcePath === parameter ? "" : sourcePath.slice(parameter.length + 1);
+      aliases.set(match[1], accessPath);
+    }
+  }
+  for (const match of source.matchAll(new RegExp(`^\\s*local\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*=\\s*if\\s+(${escaped}(?:\\.[A-Za-z_][A-Za-z0-9_]*)*)\\s*(?:==|~=)\\s*nil\\s+then\\s+(?:true|false)\\s+else\\s+\\2\\s*$`, "gm"))) {
+    const sourcePath = match[2];
+    aliases.set(match[1], sourcePath === parameter ? "" : sourcePath.slice(parameter.length + 1));
+  }
+  for (const match of source.matchAll(new RegExp(`^\\s*local\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*=\\s*if\\s+(${escaped}(?:\\.[A-Za-z_][A-Za-z0-9_]*)*)\\s+then\\s+(?:true|false)\\s+else\\s+(?:true|false)\\s*$`, "gm"))) {
+    const sourcePath = match[2];
+    aliases.set(match[1], sourcePath === parameter ? "" : sourcePath.slice(parameter.length + 1));
   }
-  return [...aliases];
+  return aliases;
 }
 function findConditionalHookMode(source) {
   const exported = exportedFunctionParameters(source);
   if (!exported)
     return null;
+  if (exported.name && !/^use[A-Z0-9_]/.test(exported.name))
+    return null;
   const parameterNames3 = exported.parameters.map(parameterName);
   const controlledIndexes = [];
   const controlledNames = [];
   const conditionVariables = {};
+  const conditionAccessPaths = {};
   for (const [index, name] of parameterNames3.entries()) {
     if (!name)
       continue;
     const aliases = conditionAliasesForParameter(source, name);
     let controlsHook = false;
-    for (const alias of aliases) {
+    for (const [alias, accessPath] of aliases) {
       const escaped = alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
       const patterns = [
         new RegExp(`\\bif\\s+${escaped}\\s+then([\\s\\S]*?)(?=\\belse\\b|\\bend\\b)`, "g"),
@@ -8489,8 +9055,11 @@ function findConditionalHookMode(source) {
         for (const match of source.matchAll(pattern)) {
           if (!branchContainsHookCall(match[1] ?? ""))
             continue;
+          if (simpleIfHasEquivalentBuiltInTopology(source, match.index))
+            continue;
           controlsHook = true;
           conditionVariables[alias] = index;
+          conditionAccessPaths[alias] = accessPath;
           break;
         }
         if (controlsHook)
@@ -8509,6 +9078,7 @@ function findConditionalHookMode(source) {
     parameterIndexes: controlledIndexes,
     parameterNames: controlledNames,
     conditionVariables,
+    conditionAccessPaths,
     knownCallSites: 0,
     dynamicCallSites: 0
   };
@@ -9159,6 +9729,63 @@ function findBindingCompatibleComponentProps(source) {
   }
   return compatible.size > 0 ? compatible : null;
 }
+function exportedUseFunctionName(source) {
+  const name = exportedFunctionName(source);
+  return name && /^use[A-Z0-9_]/.test(name) ? name : null;
+}
+function directReactHookUsage(source) {
+  const namespaces = new Set(["React"]);
+  const requirePattern = /\blocal\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*require\s*\((.*?)\)/gs;
+  for (const match of source.matchAll(requirePattern)) {
+    const target = normalizeRequireTarget(match[2]);
+    if (target.split(".").includes("react"))
+      namespaces.add(match[1]);
+  }
+  for (const namespace of namespaces) {
+    const escaped = namespace.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (new RegExp(`\\b${escaped}\\.use[A-Z0-9_][A-Za-z0-9_]*\\b`).test(source))
+      return true;
+  }
+  return false;
+}
+function calledRequiredModules(source) {
+  const result = [];
+  const requirePattern = /\blocal\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*require\s*\((.*?)\)/gs;
+  for (const match of source.matchAll(requirePattern)) {
+    const localName = match[1];
+    const escaped = localName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (!new RegExp(`\\b${escaped}\\s*\\(`).test(source.slice(match.index + match[0].length)))
+      continue;
+    result.push({ localName, target: normalizeRequireTarget(match[2]) });
+  }
+  return result;
+}
+function findReactHookModules(records) {
+  const hookRecords = records.filter((record) => exportedUseFunctionName(record.source));
+  const provenReact = new Map;
+  for (const record of hookRecords) {
+    if (directReactHookUsage(record.source))
+      provenReact.set(record.id, true);
+  }
+  let changed = true;
+  while (changed) {
+    changed = false;
+    const aliases = buildUniqueFeatureAliases(records, provenReact);
+    for (const record of hookRecords) {
+      if (provenReact.has(record.id))
+        continue;
+      const callsReactHookModule = calledRequiredModules(record.source).some(({ target }) => resolveModuleReference(target, aliases) === true);
+      if (!callsReactHookModule)
+        continue;
+      provenReact.set(record.id, true);
+      changed = true;
+    }
+  }
+  const result = new Map;
+  for (const record of hookRecords)
+    result.set(record.id, provenReact.has(record.id));
+  return result;
+}
 function findStaticIterationTables(source) {
   const match = /^return\s*\{/m.exec(source);
   if (!match || match.index === undefined)
@@ -9234,11 +9861,13 @@ function buildProjectModel(root, candidates, options = {}) {
         parameterIndexes: [...analysis.conditionalHookMode.parameterIndexes],
         parameterNames: [...analysis.conditionalHookMode.parameterNames],
         conditionVariables: { ...analysis.conditionalHookMode.conditionVariables },
+        conditionAccessPaths: { ...analysis.conditionalHookMode.conditionAccessPaths },
         knownCallSites: 0,
         dynamicCallSites: 0
       });
   }
   const conditionalHookModes = buildUniqueFeatureAliases(records, conditionalHookModesByModule);
+  const reactHookModules = buildUniqueFeatureAliases(records, findReactHookModules(records));
   collectConditionalHookModeCallSites(records, conditionalHookModes);
   let changed = true;
   while (changed) {
@@ -9262,6 +9891,7 @@ function buildProjectModel(root, candidates, options = {}) {
     bindingCompatibleComponentProps: buildUniqueFeatureAliases(records, bindingCompatibleComponentPropsByModule),
     staticIterationTables: buildUniqueFeatureAliases(records, staticIterationTablesByModule),
     conditionalHookModes,
+    reactHookModules,
     sourceEffects: new Map
   };
 }
@@ -13635,5 +14265,5 @@ ${renderUpdateNotice(update.current, update.latest, colorized)}
 }
 main();
 
-//# debugId=569DB065E837196F64756E2164756E21
+//# debugId=C71A438CE8D868EF64756E2164756E21
 //# sourceMappingURL=cli.js.map