@colrealpro/react-luau-doctor 0.20.0 → 0.20.1

package/dist/cli.js

@@ -11,7 +11,7 @@ var package_default = {
   publishConfig: {
     access: "public"
   },
-  version: "0.20.0",
+  version: "0.20.1",
   description: "Static analysis for React-Luau hooks, effects, rendering, and performance.",
   license: "MIT",
   type: "module",
@@ -121,6 +121,12 @@ function sameNode(left, right) {
 // src/ast/local-values.ts
 var valueCache = new WeakMap;
 var apiCache = new WeakMap;
+function isUnboundIdentifier(context, node) {
+  return node.type === "identifier" && visibleValue(context, node) === undefined;
+}
+function localValueBinding(context, node) {
+  return node.type === "identifier" ? visibleValue(context, node) : null;
+}
 function unwrapExpression(node) {
   while (["parenthesized_expression", "cast_expression"].includes(node.type) && node.namedChildren[0]) {
     node = node.namedChildren[0];
@@ -2421,6 +2427,242 @@ var effectNeedsCleanup = {
   }
 };
 
+// src/api-reference.ts
+var functions = new Map;
+function register(namespace, members, reference) {
+  for (const member of members)
+    functions.set(`${namespace}.${member}`, reference);
+}
+for (const type of [
+  "Instance",
+  "Random",
+  "RaycastParams",
+  "OverlapParams",
+  "CatalogSearchParams",
+  "SharedTable"
+]) {
+  register(type, ["new"], {
+    returnType: type,
+    allocation: "new",
+    equality: "reference"
+  });
+}
+register("table", ["clone", "create", "pack"], {
+  returnType: "table",
+  allocation: "new",
+  equality: "reference"
+});
+register("SharedTable", ["clone", "cloneAndFreeze"], {
+  returnType: "SharedTable",
+  allocation: "new",
+  equality: "reference"
+});
+register("string", ["split"], {
+  returnType: "table",
+  allocation: "new",
+  equality: "reference"
+});
+register("buffer", ["create", "fromstring"], {
+  returnType: "buffer",
+  allocation: "new",
+  equality: "reference"
+});
+register("coroutine", ["create"], {
+  returnType: "thread",
+  allocation: "new",
+  equality: "reference"
+});
+register("coroutine", ["wrap"], {
+  returnType: "function",
+  allocation: "new",
+  equality: "reference"
+});
+register("table", ["freeze"], {
+  returnType: "table",
+  allocation: "argument",
+  equality: "reference",
+  argumentIndex: 0
+});
+for (const [type, members] of Object.entries({
+  Color3: ["new", "fromRGB", "fromHSV", "fromHex"],
+  ColorSequence: ["new"],
+  ColorSequenceKeypoint: ["new"],
+  NumberSequence: ["new"],
+  NumberSequenceKeypoint: ["new"],
+  NumberRange: ["new"],
+  UDim: ["new"],
+  UDim2: ["new", "fromScale", "fromOffset"],
+  Vector2: ["new"],
+  Vector3: ["new", "fromNormalId", "fromAxis"],
+  CFrame: [
+    "new",
+    "Angles",
+    "fromEulerAnglesXYZ",
+    "fromEulerAnglesYXZ",
+    "fromOrientation",
+    "fromAxisAngle",
+    "fromMatrix",
+    "lookAt",
+    "lookAlong"
+  ],
+  Rect: ["new"],
+  BrickColor: ["new", "palette"]
+})) {
+  register(type, members, {
+    returnType: type,
+    allocation: "new",
+    equality: "value"
+  });
+}
+var instanceMethods = new Map([
+  ...["GetChildren", "GetDescendants", "GetAttributes", "GetTags"].map((member) => [
+    member,
+    { returnType: "table", allocation: "new", equality: "reference" }
+  ]),
+  [
+    "Clone",
+    { returnType: "Instance", allocation: "new", equality: "reference" }
+  ]
+]);
+function apiFunctionReference(path) {
+  return functions.get(path) ?? null;
+}
+function globalPath(context, expression, seen = new Set) {
+  const node = unwrapExpression(expression);
+  if (seen.has(node.id))
+    return null;
+  seen.add(node.id);
+  if (node.type === "identifier") {
+    if (isUnboundIdentifier(context, node))
+      return node.text;
+    const binding = localValueBinding(context, node);
+    return binding?.returnIndex === 0 ? globalPath(context, binding.value, seen) : null;
+  }
+  if (node.type !== "dot_index_expression")
+    return null;
+  const namespace = node.childForFieldName("table");
+  const member = node.childForFieldName("field");
+  const path = namespace && globalPath(context, namespace, seen);
+  return path && member ? `${path}.${member.text}` : null;
+}
+function isInstanceReceiver(context, expression, seen = new Set) {
+  const node = unwrapExpression(expression);
+  if (seen.has(node.id))
+    return false;
+  seen.add(node.id);
+  if (node.type === "identifier") {
+    if (isUnboundIdentifier(context, node))
+      return ["game", "workspace", "script"].includes(node.text);
+    const binding = localValueBinding(context, node);
+    return binding?.returnIndex === 0 && isInstanceReceiver(context, binding.value, seen);
+  }
+  if (node.type === "dot_index_expression") {
+    const receiver = node.childForFieldName("table");
+    return Boolean(receiver && isInstanceReceiver(context, receiver, seen));
+  }
+  if (node.type !== "function_call")
+    return false;
+  const name = node.childForFieldName("name");
+  if (!name)
+    return false;
+  if (globalPath(context, name) === "Instance.new")
+    return true;
+  if (name.type !== "method_index_expression")
+    return false;
+  const receiver = name.childForFieldName("table");
+  const member = name.childForFieldName("method")?.text;
+  return Boolean(receiver && member && [
+    "GetService",
+    "WaitForChild",
+    "FindFirstChild",
+    "FindFirstAncestor",
+    "Clone"
+  ].includes(member) && isInstanceReceiver(context, receiver, seen));
+}
+function apiReferenceForCall(context, call) {
+  const name = call.childForFieldName("name");
+  if (!name)
+    return null;
+  const path = globalPath(context, name);
+  if (path)
+    return apiFunctionReference(path);
+  if (name.type !== "method_index_expression")
+    return null;
+  const receiver = name.childForFieldName("table");
+  const member = name.childForFieldName("method")?.text;
+  return receiver && member && isInstanceReceiver(context, receiver) ? instanceMethods.get(member) ?? null : null;
+}
+
+// src/ast/value-identity.ts
+function freshValueKind(context, expression, lifetime, seen = new Set, returnIndex = 0, lifetimes = new Set([lifetime])) {
+  if (!expression)
+    return null;
+  const node = unwrapExpression(expression);
+  if (seen.has(node.id) || seen.size >= 64)
+    return null;
+  const visited = new Set(seen).add(node.id);
+  const analyze = (value, owner = lifetime, index = 0) => freshValueKind(context, value, owner, visited, index, new Set(lifetimes).add(owner));
+  if (node.type === "identifier") {
+    const binding = resolveLocalValue(context, node);
+    const owner = binding && context.nearestFunction(binding.value);
+    if (!binding || !owner || !lifetimes.has(owner))
+      return null;
+    return analyze(binding.value, lifetime, binding.returnIndex);
+  }
+  if (returnIndex === 0) {
+    if (node.type === "table_constructor")
+      return "table";
+    if (node.type === "function_definition" || node.type === "function_declaration")
+      return "function";
+    if (node.type === "binary_expression") {
+      const operator = node.children.find((child) => ["and", "or"].includes(child.type))?.type;
+      if (operator === "and")
+        return analyze(node.childForFieldName("right"));
+      if (operator === "or")
+        return analyze(node.childForFieldName("left")) ?? analyze(node.childForFieldName("right"));
+    }
+    if (node.type === "if_expression") {
+      for (const branch of [
+        node,
+        ...node.namedChildren.filter((child) => ["elseif_clause", "else_clause"].includes(child.type))
+      ]) {
+        const kind = analyze(branch.childForFieldName("consequence"));
+        if (kind)
+          return kind;
+      }
+    }
+  }
+  if (node.type !== "function_call")
+    return null;
+  const api = apiReferenceForCall(context, node);
+  if (api && returnIndex === 0) {
+    if (api.allocation === "argument")
+      return analyze(context.callArguments(node)[api.argumentIndex ?? 0] ?? null);
+    if (api.equality !== "reference")
+      return null;
+    return api.returnType === "table" || api.returnType === "function" ? api.returnType : "object";
+  }
+  const name = node.childForFieldName("name");
+  const factory = name && resolveLocalFunction(context, name);
+  if (!factory?.body)
+    return null;
+  for (const statement of context.walk(factory.body)) {
+    if (statement.type !== "return_statement" || context.nearestFunction(statement) !== factory)
+      continue;
+    const values = statement.namedChildren.find((child) => child.type === "expression_list")?.namedChildren ?? [];
+    const value = values[returnIndex] ?? values.at(-1);
+    if (!value)
+      continue;
+    const index = Math.max(0, returnIndex - values.length + 1);
+    if (index > 0 && value.type !== "function_call")
+      continue;
+    const kind = analyze(value, factory, index);
+    if (kind)
+      return kind;
+  }
+  return null;
+}
+
 // src/rules/effect-state-rules.ts
 var HOOKS_WITH_DEPS = new Set([
   "React.useEffect",
@@ -2484,23 +2726,6 @@ function hasExternalSubscription(node, context) {
   }
   return false;
 }
-function directLocalInitializer(owner, name) {
-  if (!owner.body)
-    return null;
-  for (const statement of owner.body.namedChildren) {
-    if (statement.type !== "variable_declaration")
-      continue;
-    const assignment = statement.namedChildren.find((child) => child.type === "assignment_statement");
-    const variableList = assignment?.namedChildren.find((child) => child.type === "variable_list");
-    const expressionList = assignment?.namedChildren.find((child) => child.type === "expression_list");
-    const names = variableList?.namedChildren.filter((child) => child.type === "identifier") ?? [];
-    const expressions = expressionList?.namedChildren ?? [];
-    const index = names.findIndex((child) => child.text === name);
-    if (index >= 0)
-      return expressions[index] ?? expressions[0] ?? null;
-  }
-  return null;
-}
 function setterCalledOutsideCallback(context, owner, callback, setterName) {
   if (!owner.body)
     return false;
@@ -2540,20 +2765,6 @@ function guaranteedRepeatedStateChange(argument, stateName, context) {
   }
   return false;
 }
-function freshDependencyKind(node, owner) {
-  if (node.type === "table_constructor")
-    return "table";
-  if (node.type === "function_definition")
-    return "function";
-  if (node.type === "identifier") {
-    const initializer = directLocalInitializer(owner, node.text);
-    if (initializer?.type === "table_constructor")
-      return "table";
-    if (initializer?.type === "function_definition")
-      return "function";
-  }
-  return null;
-}
 var noDerivedStateEffect = {
   id: "react-luau/no-derived-state-effect",
   category: "Effects",
@@ -2665,7 +2876,7 @@ var noEffectWithFreshDeps = {
   id: "react-luau/no-effect-with-fresh-deps",
   category: "Hooks",
   severity: "error",
-  description: "Dependency tables should not contain tables or functions recreated on every render.",
+  description: "Dependency tables should not contain reference values recreated during render",
   run(context) {
     const diagnostics = [];
     for (const call of context.findCalls()) {
@@ -2677,14 +2888,14 @@ var noEffectWithFreshDeps = {
       if (!owner || !parts)
         continue;
       for (const dependency of dependencyExpressions(parts.deps)) {
-        const kind = freshDependencyKind(dependency, owner);
+        const kind = freshValueKind(context, dependency, owner);
         if (!kind)
           continue;
         const label = dependency.type === "identifier" ? ` ${dependency.text}` : "";
         diagnostics.push({
           node: dependency,
-          message: `${path} 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."
+          message: `${path} depends on${label || " an inline value"} that can be a new ${kind} when the component renders`,
+          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"
         });
       }
     }
@@ -4791,40 +5002,32 @@ function componentRenderCost(context, owner) {
     parts.push(`${discovery} Instance discovery call${discovery === 1 ? "" : "s"}`);
   return parts;
 }
-function memoizedImports(context) {
-  const result = new Map;
-  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)
-      continue;
-    const localName = match[1];
-    const memoKind = resolveModuleReference(normalizeRequireTarget(match[2]), context.project.memoizedModules);
-    if (memoKind)
-      result.set(localName, memoKind);
+function memoizedComponentKind(context, expression) {
+  const binding = resolveLocalValue(context, expression);
+  if (!binding || binding.returnIndex !== 0 || binding.value.type !== "function_call")
+    return null;
+  const call = binding.value;
+  if (reactApiPath(context, call) === "React.memo") {
+    return context.callArguments(call).length > 1 ? "custom" : "shallow";
   }
-  return result;
+  const target = context.callArguments(call)[0];
+  if (context.getCallPath(call) !== "require" || !target)
+    return null;
+  return resolveModuleReference(normalizeRequireTarget(target.text), context.project.memoizedModules) ?? null;
 }
 function fieldLabel(field) {
   return fieldName(field) ?? field.childForFieldName("name")?.text ?? "prop";
 }
-function isInlineFreshValue(node) {
-  return node?.type === "table_constructor" || node?.type === "function_definition";
-}
 var rerenderUnstableMemoProps = {
   id: "react-luau/rerender-unstable-memo-props",
   category: "Performance",
   severity: "warning",
-  description: "Warn when fresh table or function props defeat shallow React.memo comparisons.",
+  description: "Warn when props created during render can defeat shallow React.memo comparisons",
   guidance: {
-    explanation: "A new function or table has a new identity, so a shallow memo comparison cannot skip this child.",
-    help: "Stabilize props that change each render if this child is expensive, move construction into the child, or remove ineffective memoization."
+    explanation: "New tables, functions, and reference objects compare unequal even when their contents match",
+    help: "Stabilize props that change each render if this child is expensive, move construction into the child, or remove ineffective memoization"
   },
   run(context) {
-    const imports = memoizedImports(context);
-    if (imports.size === 0)
-      return [];
     const diagnostics = [];
     for (const call of context.findCalls()) {
       if (context.resolveCallPath(context.getCallPath(call) ?? "") !== "React.createElement")
@@ -4834,12 +5037,13 @@ var rerenderUnstableMemoProps = {
         continue;
       const args = context.callArguments(call);
       const childName = args[0]?.text.trim() ?? "";
-      if (imports.get(childName) !== "shallow")
+      if (!args[0] || memoizedComponentKind(context, args[0]) !== "shallow")
         continue;
-      const props = args[1];
-      if (!props || props.type !== "table_constructor")
+      const propsBinding = args[1] && resolveLocalValue(context, args[1]);
+      const props = propsBinding?.returnIndex === 0 ? propsBinding.value : null;
+      if (!props || props.type !== "table_constructor" || context.nearestFunction(props) !== component)
         continue;
-      const unstableFields = props.namedChildren.filter((node) => node.type === "field").filter((field) => isInlineFreshValue(fieldValue(field)));
+      const unstableFields = props.namedChildren.filter((node) => node.type === "field").filter((field) => freshValueKind(context, fieldValue(field), component));
       if (unstableFields.length === 0)
         continue;
       const unstable = unstableFields.map(fieldLabel);
@@ -4848,13 +5052,13 @@ var rerenderUnstableMemoProps = {
         node: highlights[0],
         highlights,
         severity: "warning",
-        message: `Memoized ${childName} receives fresh ${unstable.join(", ")} prop${unstable.length === 1 ? "" : "s"} on every parent render.`,
-        summary: `${childName} gets ${unstable.length} fresh ${unstable.length === 1 ? "prop" : "props"} each render. Memoization cannot skip it.`,
+        message: `Memoized ${childName} can receive fresh ${unstable.join(", ")} prop${unstable.length === 1 ? "" : "s"} when its parent renders`,
+        summary: `${childName} gets ${unstable.length} ${unstable.length === 1 ? "prop" : "props"} created during render that can prevent memoization from skipping it`,
         editorRanges: highlights.map((node, index) => ({
           node,
-          summary: `${childName} gets a fresh ${unstable[index]} prop each render. Memoization cannot skip it.`
+          summary: `${childName} gets a ${unstable[index]} prop created during render that can prevent memoization from skipping it`
         })),
-        help: "Fresh table or function identity prevents the shallow memo comparison from skipping this child. Stabilize the prop only when the parent rerenders frequently, move construction into the child, or remove ineffective memoization."
+        help: "Fresh reference identity can prevent the shallow memo comparison from skipping this child. Stabilize the prop when the parent rerenders frequently, move construction into the child, or remove ineffective memoization"
       });
     }
     return diagnostics;
@@ -7028,30 +7232,32 @@ function currentConditionalHookMode(context) {
   }
   return null;
 }
-function controlledParameterIndex(controlFlow, fn, summary) {
+function controlledParameterIndex(controlFlow, fn, summary, node) {
   if (controlFlow.type !== "if_statement")
     return null;
-  const header = (controlFlow.text.split(/\bthen\b/s, 1)[0] ?? "").trim();
-  for (const [conditionName, index] of Object.entries(summary.conditionVariables)) {
-    const escaped = conditionName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const patterns = [
-      new RegExp(`^if\\s+${escaped}\\s*$`),
-      new RegExp(`^if\\s+not\\s+${escaped}\\s*$`),
-      new RegExp(`^if\\s+${escaped}\\s*(?:==|~=)\\s*(?:true|false|nil)\\s*$`),
-      new RegExp(`^if\\s+(?:true|false|nil)\\s*(?:==|~=)\\s*${escaped}\\s*$`)
-    ];
-    if (patterns.some((pattern) => pattern.test(header)))
-      return index;
-  }
+  const conditions = guardConditions(controlFlow, node);
+  if (conditions.length === 0)
+    return null;
+  const variables = { ...summary.conditionVariables };
   for (const index of summary.parameterIndexes) {
     const name = fn.parameters[index];
-    if (!name)
-      continue;
-    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    if (new RegExp(`^if\\s+(?:not\\s+)?${escaped}\\s*$`).test(header))
-      return index;
+    if (name)
+      variables[name] ??= index;
   }
-  return null;
+  const indexes = conditions.map((condition) => {
+    for (const [name, index] of Object.entries(variables)) {
+      const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const patterns = [
+        new RegExp(`^(?:not\\s+)?${escaped}\\s*$`),
+        new RegExp(`^${escaped}\\s*(?:==|~=)\\s*(?:true|false|nil)\\s*$`),
+        new RegExp(`^(?:true|false|nil)\\s*(?:==|~=)\\s*${escaped}\\s*$`)
+      ];
+      if (patterns.some((pattern) => pattern.test(condition.text.trim())))
+        return index;
+    }
+    return null;
+  });
+  return indexes.every((index) => index !== null) ? indexes[0] : null;
 }
 function dynamicHookModeFixPreview(hookName, argumentText) {
   return {
@@ -7253,28 +7459,104 @@ function staticModuleTables(context) {
   }
   return candidates;
 }
-function simpleConditionRoot(controlFlow) {
-  if (controlFlow.type !== "if_statement" && controlFlow.type !== "if_expression")
-    return null;
+function containsNode(container, node) {
+  return node.startIndex >= container.startIndex && node.endIndex <= container.endIndex;
+}
+function branchContaining(controlFlow, node) {
+  return controlFlow.namedChildren.find((child) => containsNode(child, node)) ?? null;
+}
+function guardConditions(controlFlow, node) {
   const condition = controlFlow.namedChildren[0];
   if (!condition)
-    return null;
+    return [];
+  if (controlFlow.type !== "if_statement" && controlFlow.type !== "if_expression")
+    return [condition];
+  if (containsNode(condition, node))
+    return [];
+  const conditions = [condition];
+  for (const clause of controlFlow.namedChildren.slice(1)) {
+    if (clause.startIndex > node.startIndex)
+      break;
+    if (clause.type !== "elseif_statement" && clause.type !== "elseif_clause")
+      continue;
+    const clauseCondition = clause.namedChildren[0];
+    if (clauseCondition && !containsNode(clauseCondition, node))
+      conditions.push(clauseCondition);
+  }
+  return conditions;
+}
+function conditionallyContains(controlFlow, node) {
+  if (controlFlow.type === "if_statement" || controlFlow.type === "if_expression")
+    return guardConditions(controlFlow, node).length > 0;
+  if (controlFlow.type === "for_statement")
+    return controlFlow.namedChildren.some((child) => child.type === "block" && containsNode(child, node));
+  if (CONDITIONAL_TYPES.has(controlFlow.type))
+    return true;
+  if (controlFlow.type !== "binary_expression" || !controlFlow.children.some((child) => child.type === "and" || child.type === "or"))
+    return false;
+  const right = controlFlow.childForFieldName("right") ?? controlFlow.namedChildren[1];
+  return Boolean(right && containsNode(right, node));
+}
+function simpleConditionRoot(condition) {
   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)
+var unstableLocalNamesCache = new WeakMap;
+function unstableLocalNames(fn, context) {
+  const cached = unstableLocalNamesCache.get(fn);
+  if (cached)
+    return cached;
+  const declared = new Set;
+  const unstable = new Set;
+  for (const node of context.walk(fn.node)) {
+    if (node.type === "variable_declaration" && context.nearestFunction(node) === fn) {
+      for (const name of declarationNames(node)) {
+        if (declared.has(name))
+          unstable.add(name);
+        declared.add(name);
+      }
+    }
+    if (node.type !== "assignment_statement" || node.parent?.type === "variable_declaration")
+      continue;
+    const variables = node.namedChildren.find((child) => child.type === "variable_list");
+    for (const target of variables?.namedChildren ?? []) {
+      if (target.type === "identifier")
+        unstable.add(target.text);
+    }
+  }
+  unstableLocalNamesCache.set(fn, unstable);
+  return unstable;
+}
+function moduleNameIsUnshadowed(name, node, fn, context) {
+  let owner = fn;
+  while (owner) {
+    if (owner.parameters.includes(name) || isBindingShadowedBetween(node, owner, name))
+      return false;
+    owner = context.nearestFunction(owner.node);
+  }
+  return true;
+}
+function conditionIsProvablyInvariant(controlFlow, fn, context, moduleInvariants, node = controlFlow) {
+  if (!["if_statement", "if_expression", "binary_expression"].includes(controlFlow.type))
     return false;
-  if (["true", "false", "nil", "number", "string"].includes(condition.type))
-    return true;
-  const root = simpleConditionRoot(controlFlow);
-  if (!root)
+  const conditions = guardConditions(controlFlow, node);
+  if (conditions.length === 0)
     return false;
-  if (moduleInvariants.has(root))
-    return true;
-  return Boolean(context.model.stableVariablesByFunction.get(nodeKey(fn.node))?.has(root));
+  return conditions.every((condition) => {
+    if (["true", "false", "nil", "number", "string"].includes(condition.type))
+      return true;
+    const root = simpleConditionRoot(condition);
+    if (!root)
+      return false;
+    if (moduleInvariants.has(root) && moduleNameIsUnshadowed(root, condition, fn, context))
+      return true;
+    if (isNameShadowedBetween(condition, fn, root))
+      return false;
+    if (unstableLocalNames(fn, context).has(root))
+      return false;
+    return Boolean(context.model.stableVariablesByFunction.get(nodeKey(fn.node))?.has(root));
+  });
 }
 function branchHookSequence(branch, fn, context) {
   const hooks = [];
@@ -7289,28 +7571,45 @@ function branchHookSequence(branch, fn, context) {
     const path = context.resolveCallPath(rawPath);
     if (!isHookPath(path))
       continue;
-    const nestedControl = findAncestorBetween(node, branch, (ancestor) => CONDITIONAL_TYPES.has(ancestor.type));
-    if (nestedControl)
+    const nestedControl = node.id === branch.id ? null : findAncestorBetween(node, branch, (ancestor) => conditionallyContains(ancestor, node));
+    if (nestedControl || conditionallyContains(branch, node))
       return null;
     hooks.push(path);
   }
   return hooks;
 }
 function ifBranchesHaveEquivalentBuiltInTopology(controlFlow, fn, context) {
-  if (controlFlow.type !== "if_statement")
+  const isStatement = controlFlow.type === "if_statement";
+  if (!isStatement && controlFlow.type !== "if_expression")
     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)
+  const firstBranch = isStatement ? controlFlow.namedChildren.find((child) => child.type === "block") : controlFlow.namedChildren[1];
+  const elseClause = controlFlow.namedChildren.find((child) => child.type === "else_statement" || child.type === "else_clause");
+  const lastBranch = isStatement ? elseClause?.namedChildren.find((child) => child.type === "block") : elseClause?.namedChildren[0];
+  if (!firstBranch || !lastBranch)
     return false;
-  const thenHooks = branchHookSequence(thenBlock, fn, context);
-  const elseHooks = branchHookSequence(elseBlock, fn, context);
-  if (!thenHooks || !elseHooks || thenHooks.length !== elseHooks.length)
+  const branches = [firstBranch];
+  for (const clause of controlFlow.namedChildren) {
+    if (clause.type !== "elseif_statement" && clause.type !== "elseif_clause")
+      continue;
+    const condition = clause.namedChildren[0];
+    if (!condition)
+      return false;
+    const conditionHooks = branchHookSequence(condition, fn, context);
+    if (!conditionHooks || conditionHooks.length > 0)
+      return false;
+    const branch = isStatement ? clause.namedChildren.find((child) => child.type === "block") : clause.namedChildren[1];
+    if (!branch)
+      return false;
+    branches.push(branch);
+  }
+  branches.push(lastBranch);
+  const sequences = branches.map((branch) => branchHookSequence(branch, fn, context));
+  const first = sequences[0];
+  if (!first)
     return false;
-  if (!thenHooks.every((path, index) => path === elseHooks[index]))
+  if (!sequences.every((sequence) => sequence && sequence.length === first.length && sequence.every((path, index) => path === first[index])))
     return false;
-  return thenHooks.every((path) => path.startsWith("React."));
+  return first.every((path) => path.startsWith("React."));
 }
 function stateModeStability(name, owner, context) {
   const binding = context.model.stateBindings.find((candidate) => candidate.owner === owner && candidate.valueName === name);
@@ -7415,7 +7714,21 @@ function controlledAccessPaths(summary, parameterIndex) {
     paths.add("");
   return [...paths];
 }
-function loopIterationIsProvablyStable(loop, imports, owner, stableShapes, moduleTables) {
+function loopIterationIsProvablyStable(loop, imports, owner, stableShapes, moduleTables, context, moduleInvariants) {
+  for (const node of context.walk(loop)) {
+    if (!["break_statement", "continue_statement", "return_statement"].includes(node.type))
+      continue;
+    if (context.nearestFunction(node) !== owner)
+      continue;
+    if (node.type !== "return_statement") {
+      const targetLoop = findAncestorBetween(node, owner.node, (ancestor) => ["for_statement", "while_statement", "repeat_statement"].includes(ancestor.type));
+      if (targetLoop?.id !== loop.id)
+        continue;
+    }
+    const dynamicGuard = findAncestorBetween(node, loop, (ancestor) => conditionallyContains(ancestor, node) && !conditionIsProvablyInvariant(ancestor, owner, context, moduleInvariants, node));
+    if (dynamicGuard)
+      return false;
+  }
   const numeric = loop.namedChildren.find((child) => child.type === "for_numeric_clause");
   if (numeric) {
     const text = numeric.text;
@@ -7488,23 +7801,46 @@ function reachableReturnsBefore(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.filter((node) => node.endIndex <= call.startIndex);
+  return returns.filter((node) => {
+    if (node.endIndex > call.startIndex)
+      return false;
+    return !findAncestorBetween(node, fn.node, (ancestor) => {
+      if (ancestor.type !== "if_statement")
+        return false;
+      const returnBranch = branchContaining(ancestor, node);
+      const callBranch = branchContaining(ancestor, call);
+      return Boolean(returnBranch && callBranch && returnBranch.id !== callBranch.id);
+    });
+  });
 }
 function returnIsControlledByStableTopologyMode(node, fn, summary, context, moduleInvariants) {
   let current = node.parent;
+  let sawStableGuard = false;
   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;
+    if (["for_statement", "while_statement", "repeat_statement"].includes(current.type))
       return false;
+    if (current.type === "if_statement" || current.type === "if_expression") {
+      if (summary && controlledParameterIndex(current, fn, summary, node) !== null)
+        sawStableGuard = true;
+      else if (conditionIsProvablyInvariant(current, fn, context, moduleInvariants, node))
+        sawStableGuard = true;
+      else
+        return false;
     }
     current = current.parent;
   }
-  return false;
+  return sawStableGuard;
 }
 function conditionalFixPreview(kind, hookName) {
+  if (kind === "short-circuit expression") {
+    return {
+      kind: "pattern",
+      before: `local result = enabled and renderChild(${hookName}())`,
+      after: `local value = ${hookName}()
+local result = enabled and renderChild(value)`,
+      note: "Call the hook before the short-circuit expression, then branch on its result"
+    };
+  }
   if (hookName === "React.useEffect" && kind === "if statement") {
     return {
       kind: "pattern",
@@ -7583,6 +7919,34 @@ end`,
     note: "Call hooks before any reachable early return so every render executes the same hook sequence."
   };
 }
+function callbackFunctions(context) {
+  const callbacks = new Set;
+  const addCallback = (expression) => {
+    const fn = resolveLocalFunction(context, expression);
+    if (fn)
+      callbacks.add(fn.node.id);
+  };
+  for (const call of context.findCalls()) {
+    const path = reactApiPath(context, call);
+    const args = context.callArguments(call);
+    for (const [index, argument] of args.entries()) {
+      if (index === 0 && ["React.memo", "React.forwardRef", "React.createElement"].includes(path ?? ""))
+        continue;
+      if (path?.startsWith("React.use") || path === "React.memo" || unwrapExpression(argument).type === "function_definition")
+        addCallback(argument);
+    }
+    if (path !== "React.createElement" || args[0]?.type !== "string" || args[1]?.type !== "table_constructor")
+      continue;
+    for (const field of args[1].namedChildren) {
+      if (field.type !== "field")
+        continue;
+      const value = field.namedChildren.at(-1);
+      if (value)
+        addCallback(value);
+    }
+  }
+  return callbacks;
+}
 var rulesOfHooks = {
   id: "react-luau/rules-of-hooks",
   category: "Hooks",
@@ -7603,6 +7967,7 @@ var rulesOfHooks = {
     const modeImports = conditionalHookModeImports(context);
     const ignoredHookImports = nonReactHookImports(context);
     const currentModeSummary = currentConditionalHookMode(context);
+    const callbacks = callbackFunctions(context);
     const reachableReturns = new Map;
     for (const call of context.findCalls()) {
       const rawPath = context.getCallPath(call);
@@ -7614,11 +7979,11 @@ var rulesOfHooks = {
       if (!isHookPath(path))
         continue;
       const fn = context.nearestFunction(call);
-      if (!fn || !fn.isComponent && !fn.isHook) {
+      if (!fn || !fn.isComponent && !fn.isHook || callbacks.has(fn.node.id)) {
         diagnostics.push({
           node: callNameNode(call),
-          message: `Hook ${path} is called outside a React component or custom hook.`,
-          help: "Move the hook into a component or a custom hook whose name starts with use.",
+          message: `Hook ${path} is called outside a React component or custom hook`,
+          help: "Move the hook into a component or a custom hook whose name starts with use",
           fixPreview: {
             kind: "pattern",
             before: `local value = ${path}()
@@ -7630,7 +7995,7 @@ end`,
 	local value = ${path}()
 	return value
 end`,
-            note: "Hooks need a React-owned component or custom-hook call stack."
+            note: "Hooks need a React-owned component or custom-hook call stack"
           }
         });
         continue;
@@ -7661,24 +8026,28 @@ end`,
           });
         }
       }
-      const controlFlow = findAncestorBetween(call, fn.node, (node) => CONDITIONAL_TYPES.has(node.type));
+      const controlFlow = findAncestorBetween(call, fn.node, (node) => {
+        if (!conditionallyContains(node, call))
+          return false;
+        if (currentModeSummary && controlledParameterIndex(node, fn, currentModeSummary, call) !== null)
+          return false;
+        if (conditionIsProvablyInvariant(node, fn, context, moduleInvariants, call))
+          return false;
+        if (ifBranchesHaveEquivalentBuiltInTopology(node, fn, context))
+          return false;
+        if (node.type === "for_statement" && loopIterationIsProvablyStable(node, staticImports, fn, stableShapes, moduleTables, context, moduleInvariants))
+          return false;
+        return true;
+      });
       if (controlFlow) {
-        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, moduleTables))
-          continue;
-        const kind = controlFlow.type.replaceAll("_", " ");
+        const kind = controlFlow.type === "binary_expression" ? "short-circuit expression" : controlFlow.type.replaceAll("_", " ");
         const loopLike = controlFlow.type === "for_statement" || controlFlow.type === "while_statement" || controlFlow.type === "repeat_statement";
         diagnostics.push({
           node: callNameNode(call),
-          message: loopLike ? `Hook ${path} is called inside ${kind} whose size or iteration order may change between renders. If that happens, React will see a different hook sequence.` : `Hook ${path} is called inside ${kind}, so the hook may be skipped on some renders.`,
-          summary: loopLike ? `${path} may run a different number of times between renders.` : `${path} may be skipped on some renders.`,
-          explanation: loopLike ? `This ${kind} may change how many times ${path} is called.` : `This ${kind} can skip ${path} on some renders.`,
-          help: loopLike ? "Keep hook count independent of runtime collection size or loop iterations. A common fix is to render a child component per item and call the hook inside that child." : "Call the hook unconditionally at the top level, then branch on the returned value.",
+          message: loopLike ? `Hook ${path} is called inside ${kind} whose size or iteration order may change between renders. If that happens, React will see a different hook sequence` : `Hook ${path} is called inside ${kind}, so the hook may be skipped on some renders`,
+          summary: loopLike ? `${path} may run a different number of times between renders` : `${path} may be skipped on some renders`,
+          explanation: loopLike ? `This ${kind} may change how many times ${path} is called` : `This ${kind} can skip ${path} on some renders`,
+          help: loopLike ? "Keep hook count independent of runtime collection size or loop iterations. A common fix is to render a child component per item and call the hook inside that child" : "Call the hook unconditionally at the top level, then branch on the returned value",
           fixPreview: conditionalFixPreview(kind, path)
         });
         continue;
@@ -8051,7 +8420,7 @@ var unstableContextValue = {
   id: "react-luau/unstable-context-value",
   category: "Performance",
   severity: "warning",
-  description: "Avoid recreating context value tables on every provider render when identity matters.",
+  description: "Avoid recreating context reference values during render when identity matters",
   run(context) {
     const diagnostics = [];
     for (const call of context.findCalls()) {
@@ -8066,13 +8435,13 @@ var unstableContextValue = {
       const props = args[1];
       if (!/\.Provider$/.test(element) || !props || props.type !== "table_constructor")
         continue;
-      const valueField = props.namedChildren.find((field) => field.type === "field" && fieldName(field) === "value" && fieldValue(field)?.type === "table_constructor");
+      const valueField = props.namedChildren.find((field) => field.type === "field" && fieldName(field) === "value" && freshValueKind(context, fieldValue(field), component));
       if (!valueField)
         continue;
       diagnostics.push({
         node: fieldNameNode(valueField),
-        message: "Context Provider receives a new inline value table on every render.",
-        help: "Memoize the provider value from its real dependencies when consumer updates depend on object identity."
+        message: "Context Provider can receive a new reference value when the component renders",
+        help: "Memoize the provider value from its real dependencies when consumer updates depend on object identity"
       });
     }
     return diagnostics;
@@ -15554,5 +15923,5 @@ ${renderUpdateNotice(update.current, update.latest, colorized)}
 }
 main();
 
-//# debugId=9D947B614FF21B3A64756E2164756E21
+//# debugId=3EFE794093E582F464756E2164756E21
 //# sourceMappingURL=cli.js.map