octane 0.2.11 → 0.2.13

package/dist/compiler/hook-deps.js

@@ -3,6 +3,9 @@
 // surgical plain-TS hook pass, keeping custom hooks and components aligned.
 
 import { builders as b } from '@tsrx/core';
+import { hasInlineMemoDirectEval } from './inline-hook-memo.js';
+
+export const STRONG_AUTOMATIC_MEMO_UNSUPPORTED = 'OCTANE_STRONG_AUTOMATIC_MEMO_UNSUPPORTED';
 
 const DEPENDENCY_HOOKS = new Map([
 	['useEffect', { callback: 0, deps: 1 }],
@@ -174,7 +177,13 @@ function collectHoistedVars(node, functionScope, root = true, bindingsOnly = fal
 		for (const child of node) collectHoistedVars(child, functionScope, false, bindingsOnly);
 		return;
 	}
-	if (!root && isFunction(node)) return;
+	if (!root && (isFunction(node) || node.type === 'JSXCodeBlock')) return;
+	if (
+		['JSXIfExpression', 'JSXForExpression', 'JSXSwitchExpression', 'JSXTryExpression'].includes(
+			node.type,
+		)
+	)
+		return;
 	if (
 		bindingsOnly &&
 		(isFunction(node) ||
@@ -216,6 +225,15 @@ function unwrapValue(node) {
 	return node;
 }
 
+function isUnshadowedUndefined(node, scope) {
+	const value = unwrapValue(node);
+	return (
+		value?.type === 'Identifier' &&
+		value.name === 'undefined' &&
+		resolveBinding(scope, value.name) === null
+	);
+}
+
 function canonicalHookName(call, scope, onlyImported) {
 	const callee = unwrapValue(call?.callee);
 	if (!callee) return null;
@@ -305,6 +323,7 @@ function buildScopes(ast, onlyImported, hookRuntimeModules, bindingsOnly = false
 	const moduleScope = createScope(null, 'module');
 	const nodeScopes = new WeakMap();
 	const functionScopes = new WeakMap();
+	const functionBodies = new WeakSet();
 	const declarators = [];
 	const candidates = [];
 	const calls = [];
@@ -358,6 +377,7 @@ function buildScopes(ast, onlyImported, hookRuntimeModules, bindingsOnly = false
 		}
 
 		if (isFunction(node)) {
+			if (node.body) functionBodies.add(node.body);
 			const fnScope = createScope(scope, 'function');
 			const record = bindingsOnly
 				? null
@@ -455,10 +475,16 @@ function buildScopes(ast, onlyImported, hookRuntimeModules, bindingsOnly = false
 		) {
 			const blockScope = createScope(
 				scope,
-				bindingsOnly && node.type === 'StaticBlock' ? 'function' : 'block',
+				(bindingsOnly && node.type === 'StaticBlock') ||
+					(node.type === 'JSXCodeBlock' && !functionBodies.has(node))
+					? 'function'
+					: 'block',
 			);
-			if (bindingsOnly && node.type === 'StaticBlock') {
-				collectHoistedVars(node, blockScope, true, true);
+			if (
+				(bindingsOnly && node.type === 'StaticBlock') ||
+				(node.type === 'JSXCodeBlock' && !functionBodies.has(node))
+			) {
+				collectHoistedVars(node, blockScope, true, bindingsOnly);
 			}
 			predeclareDirect(node.body, blockScope, hookRuntimeModules, bindingsOnly);
 			for (const statement of node.body || []) walk(statement, blockScope);
@@ -638,7 +664,11 @@ function buildScopes(ast, onlyImported, hookRuntimeModules, bindingsOnly = false
 				config,
 				trustedConfig,
 			});
-			if (trustedConfig && node.arguments.length === trustedConfig.deps) {
+			if (
+				trustedConfig &&
+				(node.arguments.length === trustedConfig.deps ||
+					node._octaneStrongOmittedDependency === true)
+			) {
 				candidates.push({ call: node, scope, name: trustedName, config: trustedConfig });
 			}
 		}
@@ -1482,8 +1512,27 @@ function cloneDependency(node) {
 /** @param {any} ast @param {{ onlyImported?: boolean, hookRuntimeModules?: readonly string[], filename?: string, inferDependencies?: boolean }} options */
 function analyzeInternal(ast, options) {
 	const onlyImported = options.onlyImported === true;
-	const hookRuntimeModules = new Set(['octane', ...(options.hookRuntimeModules || [])]);
-	const analysis = buildScopes(ast, onlyImported, hookRuntimeModules);
+	const shared = options.strongHookAnalysis ? analyzeStrongHookBindings(ast, options) : null;
+	let analysis =
+		shared?.analysis ??
+		buildScopes(ast, onlyImported, new Set(['octane', ...(options.hookRuntimeModules || [])]));
+	if (shared) {
+		const callAnnotations = new Map(analysis.callAnnotations);
+		const candidates = [];
+		for (const { call, scope } of analysis.calls) {
+			const name = shared.callNames.get(call);
+			const config = DEPENDENCY_HOOKS.get(name);
+			if (!config) continue;
+			const annotation = { ...callAnnotations.get(call), _octaneImportedHook: name };
+			delete annotation._octaneCustomHookCall;
+			callAnnotations.set(call, annotation);
+			const omitted = call.arguments[config.deps] === undefined;
+			const replaceDependency = isUnshadowedUndefined(call.arguments[config.deps], scope);
+			if (omitted || replaceDependency)
+				candidates.push({ call, scope, name, config, replaceDependency });
+		}
+		analysis = { ...analysis, callAnnotations, candidates };
+	}
 	const inferred = new Map();
 	// A hand-slotted module owns its authored dependency ABI. The production
 	// memo-only pass still needs lexical import provenance, but must not infer
@@ -1514,6 +1563,9 @@ function analyzeInternal(ast, options) {
 		inferred.set(candidate.call, {
 			name: candidate.name,
 			depsIndex: candidate.config.deps,
+			...(candidate.call._octaneStrongOmittedDependency === true || candidate.replaceDependency
+				? { replaceDependency: true }
+				: {}),
 			dependencies,
 		});
 	}
@@ -1549,6 +1601,245 @@ export function analyzeHookDependencies(ast, options = {}) {
 	return analyzeInternal(ast, options).inferred;
 }
 
+/**
+ * Infer callback captures for compiler-owned lifetimes without manufacturing a
+ * hook call. Results retain the hook collector's receiver-aware method records;
+ * null means the expression is not an analyzable callback, never an empty list.
+ * The supplied callbacks must belong to this AST so lexical bindings are shared.
+ */
+export function analyzeCallbackDependencies(ast, callbacks, options = {}) {
+	const analysis = buildScopes(
+		ast,
+		options.onlyImported === true,
+		new Set(['octane', ...(options.hookRuntimeModules || [])]),
+	);
+	markDependencyInvariantBindings(analysis);
+	const inferred = new Map();
+	for (const original of callbacks) {
+		const callback = unwrapValue(original);
+		inferred.set(
+			original,
+			isFunction(callback)
+				? collectDependencies(callback, analysis.functionScopes.get(callback) || null, analysis)
+				: collectCallbackReference(callback, analysis),
+		);
+	}
+	return inferred;
+}
+
+// Strong dependency policy deliberately shares inference's lexical graph and
+// dependency collector. Comparing source strings, or independently collecting
+// free names here, would disagree on stable hooks and Effect Event exclusions.
+function strongHookNameResolver(analysis, onlyImported) {
+	const aliases = new Map();
+	function propertyName(property, computed) {
+		const key = unwrapValue(property);
+		return computed ? (key?.type === 'Literal' ? key.value : null) : key?.name;
+	}
+	for (const { decl, bindings, kind } of analysis.declarators) {
+		if (kind !== 'const' || !decl.init) continue;
+		const byPattern = new Map(bindings.map(({ pattern, binding }) => [pattern, binding]));
+		function collect(pattern, path) {
+			if (pattern?.type === 'Identifier') {
+				const binding = byPattern.get(pattern);
+				if (binding && !binding.reassigned) aliases.set(binding, { node: decl.init, path });
+			} else if (pattern?.type === 'AssignmentPattern') {
+				// Named namespace exports are defined, so their defaults cannot run.
+				collect(pattern.left, path);
+			} else if (pattern?.type === 'ObjectPattern') {
+				for (const property of pattern.properties) {
+					if (property.type === 'RestElement') continue;
+					const name = propertyName(property.key, property.computed);
+					if (typeof name === 'string') collect(property.value, [...path, name]);
+				}
+			}
+		}
+		collect(decl.id, []);
+	}
+	function resolve(node, scope, seen = new Set()) {
+		const value = unwrapValue(node);
+		if (value?.type === 'ChainExpression') return resolve(value.expression, scope, seen);
+		if (value?.type === 'Identifier') {
+			const binding = resolveBinding(scope, value.name);
+			if (binding === null) return onlyImported ? null : value.name;
+			if (binding.reassigned) return null;
+			if (binding.hookRuntimeImport) return binding.hookRuntimeImport;
+			if (binding.hookRuntimeNamespace) return '*';
+			if (!aliases.has(binding) || seen.has(binding)) return null;
+			seen.add(binding);
+			const alias = aliases.get(binding);
+			let name = resolve(alias.node, analysis.nodeScopes.get(alias.node) ?? binding.scope, seen);
+			for (const property of alias.path) name = name === '*' ? property : null;
+			return name;
+		}
+		if (value?.type === 'MemberExpression') {
+			const name = propertyName(value.property, value.computed);
+			return typeof name === 'string' && resolve(value.object, scope, seen) === '*' ? name : null;
+		}
+		return null;
+	}
+	// Optional calls still target defined, immutable Octane exports. Optional
+	// syntax must not bypass Strong authoring policy for those proven imports.
+	return (call, scope) => resolve(call.callee, scope);
+}
+
+/** Shared authored hook identity and lexical proof for Strong analyses. */
+export function analyzeStrongHookBindings(ast, options = {}) {
+	const onlyImported = options.onlyImported === true;
+	const hookRuntimeModules = new Set([
+		'octane',
+		'octane/server',
+		...(options.nativeReads ? ['octane/signals/client', 'octane/signals/server'] : []),
+		...(options.hookRuntimeModules ?? []),
+	]);
+	const shared = options.strongHookAnalysis;
+	if (
+		shared?.ast === ast &&
+		shared.onlyImported === onlyImported &&
+		shared.hookRuntimeModules.size === hookRuntimeModules.size &&
+		[...hookRuntimeModules].every((request) => shared.hookRuntimeModules.has(request))
+	)
+		return shared;
+	const analysis = buildScopes(ast, onlyImported, hookRuntimeModules);
+	const nameFor = strongHookNameResolver(analysis, onlyImported);
+	const callNames = new Map();
+	for (const { call, scope } of analysis.calls) {
+		const name = nameFor(call, scope);
+		if (name !== null) callNames.set(call, name);
+	}
+	return { ast, analysis, callNames, onlyImported, hookRuntimeModules };
+}
+
+function dependencyExpressionKey(expression, analysis) {
+	const node = unwrapValue(expression);
+	if (node?.type === 'Identifier') {
+		const scope = analysis.nodeScopes.get(node);
+		const binding = scope ? resolveBinding(scope, node.name) : null;
+		return binding === null ? `global:${node.name}` : `binding:${binding.id}`;
+	}
+	if (node?.type === 'ChainExpression') return dependencyExpressionKey(node.expression, analysis);
+	if (node?.type === 'MemberExpression') {
+		const object = dependencyExpressionKey(node.object, analysis);
+		const property = node.computed ? unwrapValue(node.property) : null;
+		const name = node.computed
+			? property?.type === 'Literal' && ['string', 'number'].includes(typeof property.value)
+				? String(property.value)
+				: null
+			: node.property?.name;
+		return object === null || name == null
+			? null
+			: `${object}${node.optional ? '?' : ''}[${JSON.stringify(name)}]`;
+	}
+	return null;
+}
+
+// Inference omits imported and module-invariant roots (including stable hook
+// results) because they cannot change between renders. An authored entry for
+// one adds nothing observable to a callback that ignores its arguments.
+function dependencyInvariantRoot(expression, analysis) {
+	const node = unwrapValue(expression);
+	if (node?.type !== 'Identifier') return false;
+	const scope = analysis.nodeScopes.get(node);
+	const binding = scope ? resolveBinding(scope, node.name) : null;
+	return binding !== null && (binding.imported === true || binding.dependencyInvariant === true);
+}
+
+function equivalentStrongDependencies(authored, callback, inferred, analysis) {
+	if (authored?.type !== 'ArrayExpression' || inferred === null) return false;
+	const expected = [];
+	for (const dependency of inferred) {
+		// Inference selects either an own method or its receiver at runtime.
+		// A handwritten member cannot prove equality with that conditional value.
+		if (dependency.method) return false;
+		const key = dependencyExpressionKey(dependency.node, analysis);
+		if (key === null) return false;
+		expected.push(key);
+	}
+	const actual = [];
+	const reactive = [];
+	for (const dependency of authored.elements) {
+		const key = dependencyExpressionKey(dependency, analysis);
+		if (key === null) return false;
+		actual.push(key);
+		if (!dependencyInvariantRoot(dependency, analysis)) reactive.push(key);
+	}
+	// Dependency values are also callback arguments in Octane. For callbacks
+	// that observe those arguments (including opaque references), position and
+	// duplicate entries are observable and cannot be reduced to a set.
+	if (callback?.type !== 'ArrowFunctionExpression' || callback.params.length > 0) {
+		return (
+			actual.length === expected.length && actual.every((key, index) => key === expected[index])
+		);
+	}
+	const actualSet = new Set(reactive);
+	return actualSet.size === new Set(expected).size && expected.every((key) => actualSet.has(key));
+}
+
+/**
+ * Read-only policy records for authored built-in hooks in an enabled Strong
+ * module. The caller owns module opt-in, diagnostic locations, and severity.
+ * Compatibility compilation never invokes this additional lexical analysis.
+ * @param {any} ast
+ * @param {{ onlyImported?: boolean, hookRuntimeModules?: readonly string[], nativeReads?: boolean }} [options]
+ */
+export function analyzeStrongHookPolicies(ast, options = {}) {
+	const { analysis, callNames } = analyzeStrongHookBindings(ast, options);
+	const diagnostics = [];
+	let markedInvariants = false;
+	for (const { call, scope } of analysis.calls) {
+		const name = callNames.get(call);
+		const config = DEPENDENCY_HOOKS.get(name);
+		if (config === undefined) continue;
+		if (name === 'useMemo' || name === 'useCallback') {
+			diagnostics.push({
+				code: 'OCTANE_STRONG_MANUAL_MEMO',
+				node: call,
+				severity: 'error',
+				message: `Strong mode owns calculation and callback caching. Replace ${name} with a const declaration and let the compiler track its inputs.`,
+			});
+			continue;
+		}
+		const argument = call.arguments[config.deps];
+		if (argument === undefined || isUnshadowedUndefined(argument, scope)) continue;
+		const authored = unwrapValue(argument);
+		if (
+			(authored?.type === 'Literal' && authored.value === null) ||
+			authored?.type === 'NullLiteral'
+		) {
+			diagnostics.push({
+				code: 'OCTANE_STRONG_UNTRACKED_EFFECT',
+				node: argument,
+				severity: 'error',
+				message:
+					'Strong mode does not allow null dependency lists. Omit the dependency argument so the compiler tracks the callback’s reactive inputs.',
+			});
+			continue;
+		}
+		let equivalent = false;
+		if (authored?.type === 'ArrayExpression') {
+			if (!markedInvariants) {
+				markDependencyInvariantBindings(analysis);
+				markedInvariants = true;
+			}
+			const callback = unwrapValue(call.arguments[config.callback]);
+			const inferred = isFunction(callback)
+				? collectDependencies(callback, analysis.functionScopes.get(callback) ?? null, analysis)
+				: collectCallbackReference(callback, analysis);
+			equivalent = equivalentStrongDependencies(authored, callback, inferred, analysis);
+		}
+		diagnostics.push({
+			code: 'OCTANE_STRONG_EXPLICIT_DEPENDENCIES',
+			node: argument,
+			severity: equivalent ? 'hint' : 'error',
+			message: equivalent
+				? 'This dependency array is redundant: the compiler infers the same inputs. Omit the dependency argument.'
+				: 'Strong mode owns dependency inference. Omit this dependency argument; its values are not proven equivalent to the callback’s inferred inputs.',
+		});
+	}
+
+	return diagnostics;
+}
+
 /**
  * Copy-on-write rebuild carrying hook metadata: every call the scope walk
  * annotated is replaced by a shallow copy stamped with its `_octane*` props
@@ -1588,14 +1879,14 @@ function rebuildWithHookMetadata(ast, analysis, inferred, insertDeps, nativeRead
 			if (out === null) out = { ...node };
 			if (props !== undefined) Object.assign(out, props);
 			if (result !== undefined) {
-				// Only an authored omission grants this capability. Explicit arrays,
-				// null, and dependency arguments forwarded by wrappers stay ordinary.
+				// Only an omission (including Strong’s proven undefined placeholder) grants
+				// this capability. Arrays, null, and forwarded dependencies stay ordinary.
 				if (nativeReads && result.name === 'useMemo') out._octaneNativeInferredMemo = true;
 				if (insertDeps) {
 					const args = out.arguments.slice();
 					// The synthesized array maps to the hook call it belongs to; each
 					// dependency clone keeps its authored position.
-					args.splice(result.depsIndex, 0, {
+					args.splice(result.depsIndex, result.replaceDependency ? 1 : 0, {
 						...b.array(
 							result.dependencies.map((/** @type {any} */ dependency) =>
 								dependency.method ? methodDepNode(dependency) : cloneDependency(dependency.node),
@@ -1651,3 +1942,461 @@ export function applyHookDependencies(ast, options = {}) {
 	}
 	return rebuildWithHookMetadata(ast, analysis, inferred, true, options.nativeReads === true).ast;
 }
+
+/**
+ * Candidates for Strong's declaration-level caching. Hook inference owns the
+ * lexical and capture proof so generated caches use the same dependency ABI as
+ * authored hooks. Mutable local objects and late-bound captures retain normal
+ * JavaScript evaluation; caching them would change their lifetime or read TDZs.
+ */
+export function analyzeStrongMemoCandidates(ast, options = {}) {
+	const shared = analyzeStrongHookBindings(ast, options);
+	const analysis = shared.analysis;
+	const callNames = shared.callNames;
+	markDependencyInvariantBindings(analysis);
+	const hookName = (call) => callNames.get(call) ?? null;
+	const hookCalls = new Map();
+	const omittedDependencies = new Set();
+	for (const { call, scope, trustedConfig } of analysis.calls) {
+		const name = callNames.get(call);
+		const config = DEPENDENCY_HOOKS.get(name);
+		if (!config) continue;
+		if (!trustedConfig || call.optional) hookCalls.set(call, name);
+		if (isUnshadowedUndefined(call.arguments[config.deps], scope)) omittedDependencies.add(call);
+	}
+	const owners = new Map(analysis.functions.map((record) => [record.scope, record]));
+	const functions = new Map(
+		analysis.functions.filter((record) => record.binding).map((record) => [record.binding, record]),
+	);
+	const declarations = new Map();
+	const aliases = new Map();
+	function connectAlias(binding, target) {
+		if (!binding || !target || binding === target) return;
+		if (!aliases.has(binding)) aliases.set(binding, new Set());
+		if (!aliases.has(target)) aliases.set(target, new Set());
+		aliases.get(binding).add(target);
+		aliases.get(target).add(binding);
+	}
+	function sharedBindings(node, targets) {
+		const value = unwrapValue(node);
+		if (!value) return;
+		if (['Identifier', 'MemberExpression', 'ChainExpression'].includes(value.type)) {
+			const target = rootBinding(value);
+			if (target) targets.add(target);
+		} else if (value.type === 'ObjectExpression')
+			for (const prop of value.properties) sharedBindings(prop.argument ?? prop.value, targets);
+		else if (value.type === 'ArrayExpression')
+			for (const item of value.elements) sharedBindings(item?.argument ?? item, targets);
+		else if (value.type === 'ConditionalExpression') {
+			sharedBindings(value.consequent, targets);
+			sharedBindings(value.alternate, targets);
+		} else if (value.type === 'LogicalExpression') {
+			sharedBindings(value.left, targets);
+			sharedBindings(value.right, targets);
+		} else if (['CallExpression', 'NewExpression'].includes(value.type))
+			for (const arg of value.arguments) sharedBindings(arg.argument ?? arg, targets);
+	}
+
+	for (const record of analysis.declarators) {
+		for (const { binding } of record.bindings) declarations.set(binding, record.decl);
+		const initial = unwrapValue(record.decl.init);
+		if (record.kind === 'const') {
+			const targets = new Set();
+			sharedBindings(initial, targets);
+			for (const { binding } of record.bindings)
+				for (const target of targets) connectAlias(binding, target);
+		}
+	}
+	const names = new Set();
+	const referenced = new Set();
+	const reads = new Map();
+	const parents = new WeakMap();
+	const bindingNodes = new WeakSet();
+	function markBindingNodes(pattern) {
+		if (!pattern) return;
+		if (pattern.type === 'Identifier') bindingNodes.add(pattern);
+		else if (pattern.type === 'ObjectPattern')
+			for (const prop of pattern.properties) markBindingNodes(prop.argument ?? prop.value);
+		else if (pattern.type === 'ArrayPattern')
+			for (const item of pattern.elements) markBindingNodes(item);
+		else if (pattern.type === 'AssignmentPattern') markBindingNodes(pattern.left);
+		else if (pattern.type === 'RestElement') markBindingNodes(pattern.argument);
+	}
+	for (const { decl } of analysis.declarators) markBindingNodes(decl.id);
+	for (const { node } of analysis.functions) {
+		if (node.id) bindingNodes.add(node.id);
+		for (const param of node.params) markBindingNodes(param);
+	}
+
+	const mutated = new Set();
+	const inLoop = new WeakSet();
+	const mutationMethods = new Set([
+		'copyWithin',
+		'fill',
+		'pop',
+		'push',
+		'reverse',
+		'shift',
+		'sort',
+		'splice',
+		'unshift',
+		'set',
+		'delete',
+		'clear',
+		'add',
+	]);
+	function rootBinding(node) {
+		let value = unwrapValue(node);
+		while (value?.type === 'MemberExpression' || value?.type === 'ChainExpression')
+			value = unwrapValue(value.object ?? value.expression);
+		return value?.type === 'Identifier'
+			? resolveBinding(analysis.nodeScopes.get(value) ?? null, value.name)
+			: null;
+	}
+	function markMutation(target) {
+		const value = unwrapValue(target);
+		if (!value) return;
+		if (value.type === 'ArrayPattern') for (const item of value.elements) markMutation(item);
+		else if (value.type === 'ObjectPattern')
+			for (const prop of value.properties) markMutation(prop.argument ?? prop.value);
+		else if (value.type === 'AssignmentPattern') markMutation(value.left);
+		else if (value.type === 'RestElement') markMutation(value.argument);
+		else {
+			const binding = rootBinding(value);
+			if (binding) mutated.add(binding);
+		}
+	}
+	function scan(node, loop = false, parent = null, parentKey = null) {
+		if (!node || typeof node !== 'object') return;
+		if (Array.isArray(node)) {
+			for (const child of node) scan(child, loop, parent, parentKey);
+			return;
+		}
+		if (parent) parents.set(node, parent);
+		if (node.type === 'Identifier') {
+			names.add(node.name);
+			const structural =
+				bindingNodes.has(node) ||
+				parent?.type?.startsWith('Import') ||
+				(parent?.type === 'MemberExpression' && parentKey === 'property' && !parent.computed) ||
+				(['Property', 'MethodDefinition', 'PropertyDefinition'].includes(parent?.type) &&
+					parentKey === 'key' &&
+					!parent.computed) ||
+				(parent?.type === 'LabeledStatement' && parentKey === 'label') ||
+				['BreakStatement', 'ContinueStatement', 'MetaProperty'].includes(parent?.type);
+			if (!structural) {
+				const binding = resolveBinding(analysis.nodeScopes.get(node) ?? null, node.name);
+				if (binding) {
+					referenced.add(binding);
+					if (!reads.has(binding)) reads.set(binding, []);
+					reads.get(binding).push(node);
+				}
+			}
+		}
+
+		// A template `@for` body runs once per row, and this analysis does not
+		// model the row bindings, so its declarations keep plain evaluation.
+		if (
+			[
+				'ForStatement',
+				'ForInStatement',
+				'ForOfStatement',
+				'WhileStatement',
+				'DoWhileStatement',
+				'JSXForExpression',
+			].includes(node.type)
+		)
+			loop = true;
+		if (loop && node.type === 'VariableDeclarator') inLoop.add(node);
+		if (node.type === 'ClassDeclaration' && node.id) {
+			// A class binding stays in its temporal dead zone until the declaration
+			// runs, so a cache input naming a later class would read it eagerly.
+			const binding = resolveBinding(
+				analysis.nodeScopes.get(node.id) ?? analysis.nodeScopes.get(node) ?? null,
+				node.id.name,
+			);
+			if (binding) declarations.set(binding, node);
+		}
+		if (
+			node.type === 'AssignmentExpression' ||
+			node.type === 'UpdateExpression' ||
+			(node.type === 'UnaryExpression' && node.operator === 'delete')
+		) {
+			markMutation(node.left ?? node.argument);
+		}
+		if (
+			['ForInStatement', 'ForOfStatement'].includes(node.type) &&
+			node.left?.type !== 'VariableDeclaration'
+		)
+			markMutation(node.left);
+		if (node.type === 'CallExpression') {
+			const member = unwrapValue(node.callee);
+			const property = unwrapValue(member?.property);
+			const receiver = unwrapValue(member?.object);
+			const method = member?.computed
+				? property?.type === 'Literal'
+					? property.value
+					: null
+				: property?.name;
+			// Preserve the conservative treatment of same-named local objects:
+			// a shadowed Object/Reflect implementation can also mutate its target.
+			if (
+				receiver?.type === 'Identifier' &&
+				((receiver.name === 'Object' &&
+					['assign', 'defineProperty', 'defineProperties', 'setPrototypeOf'].includes(method)) ||
+					(receiver.name === 'Reflect' &&
+						['set', 'deleteProperty', 'defineProperty', 'setPrototypeOf'].includes(method)))
+			)
+				markMutation(node.arguments[0]);
+			if (member?.type === 'MemberExpression' && mutationMethods.has(method)) {
+				const binding = rootBinding(member.object);
+				if (binding) mutated.add(binding);
+			}
+		}
+		for (const key in node)
+			if (!AST_META_KEYS.has(key) && key !== 'typeAnnotation' && key !== 'returnType')
+				scan(node[key], loop, node, key);
+	}
+	scan(ast);
+	const mutationQueue = [...mutated];
+	for (let index = 0; index < mutationQueue.length; index++) {
+		for (const related of aliases.get(mutationQueue[index]) ?? []) {
+			if (!mutated.has(related)) {
+				mutated.add(related);
+				mutationQueue.push(related);
+			}
+		}
+	}
+	const hookSummaries = new Map();
+	// Nested functions count: a callback argument may run its hook synchronously
+	// (`compute(() => useContext(Ctx))`), and caching that declaration would run
+	// the hook only on cache misses.
+	function executesHook(node, active = new Set(), root = true) {
+		if (!node || typeof node !== 'object') return false;
+		if (Array.isArray(node)) return node.some((child) => executesHook(child, active, false));
+		if (node.type === 'CallExpression') {
+			const name = hookName(node, analysis.nodeScopes.get(node));
+			if (/^use(?:[A-Z]|$)/.test(name ?? '')) return true;
+			const callee = unwrapValue(node.callee);
+
+			const binding = directCallBinding(node, analysis.nodeScopes.get(node));
+			if (binding?.customHookImport) return true;
+			const record = functions.get(binding);
+			if (record && active.has(record)) return true;
+			if (record) {
+				if (!hookSummaries.has(record)) {
+					active.add(record);
+					hookSummaries.set(record, executesHook(record.node.body, active));
+					active.delete(record);
+				}
+				if (hookSummaries.get(record)) return true;
+			}
+			if (isFunction(callee) && executesHook(callee.body, active)) return true;
+		}
+		for (const key in node)
+			if (!AST_META_KEYS.has(key) && executesHook(node[key], active, false)) return true;
+		return false;
+	}
+	function prohibited(node, root = true) {
+		if (!node || typeof node !== 'object') return false;
+		if (Array.isArray(node)) return node.some((child) => prohibited(child, false));
+		if (!root && isFunction(node)) return false;
+		if (
+			[
+				'AwaitExpression',
+				'YieldExpression',
+				'AssignmentExpression',
+				'UpdateExpression',
+				'ThisExpression',
+				'Super',
+				'ImportExpression',
+				'CallExpression',
+				'NewExpression',
+				'TaggedTemplateExpression',
+				'SpreadElement',
+			].includes(node.type) ||
+			node.type?.startsWith('JSX')
+		)
+			return true;
+		if (node.type === 'Identifier' && node.name === 'arguments') return true;
+		for (const key in node)
+			if (!AST_META_KEYS.has(key) && prohibited(node[key], false)) return true;
+		return false;
+	}
+	function capturesLexicalReceiver(node, root = true) {
+		if (!node || typeof node !== 'object') return false;
+		if (Array.isArray(node)) return node.some((child) => capturesLexicalReceiver(child, false));
+		if (!root && ['FunctionExpression', 'FunctionDeclaration'].includes(node.type)) return false;
+		if (['ThisExpression', 'Super', 'MetaProperty'].includes(node.type)) return true;
+		for (const key in node)
+			if (!AST_META_KEYS.has(key) && capturesLexicalReceiver(node[key], false)) return true;
+		return false;
+	}
+	function createsIdentity(node) {
+		const value = unwrapValue(node);
+		if (!value) return false;
+		if (
+			[
+				'ObjectExpression',
+				'ArrayExpression',
+				'FunctionExpression',
+				'ArrowFunctionExpression',
+				'CallExpression',
+				'NewExpression',
+				'TaggedTemplateExpression',
+			].includes(value.type)
+		)
+			return true;
+		if (value.type === 'ChainExpression') return createsIdentity(value.expression);
+		if (value.type === 'ConditionalExpression')
+			return createsIdentity(value.consequent) || createsIdentity(value.alternate);
+		if (value.type === 'LogicalExpression')
+			return createsIdentity(value.left) || createsIdentity(value.right);
+		return false;
+	}
+	// A cache inherits an existing authored hook's render scope. Merely
+	// producing JSX (or being named useX) never creates that ownership proof.
+	function effectOwnerForRead(read) {
+		let child = read;
+		for (let node = parents.get(child); node; child = node, node = parents.get(node)) {
+			if (node.type !== 'CallExpression') continue;
+			const name = callNames.get(node);
+			const config = DEPENDENCY_HOOKS.get(name);
+			if (!config || ['useMemo', 'useCallback'].includes(name)) continue;
+			if (node.arguments[config.callback] !== child && node.arguments[config.deps] !== child)
+				continue;
+			return owners.get(nearestFunctionScope(analysis.nodeScopes.get(node)));
+		}
+		return null;
+	}
+	const reflectiveOwners = new Map();
+	function reflectiveOwner(record) {
+		if (!reflectiveOwners.has(record))
+			reflectiveOwners.set(record, hasInlineMemoDirectEval(record.node));
+		return reflectiveOwners.get(record);
+	}
+	// A local custom hook can forward an input into an authored effect without
+	// exposing that value during setup. Full compilation already supplies a
+	// call-site boundary to direct useX calls. Plain modules deliberately do
+	// not slot local custom calls, so only their own builtin effects qualify.
+	const effectParameters = new Map();
+	if (!shared.onlyImported)
+		for (const record of analysis.functions) {
+			if (
+				!record.binding ||
+				record.binding.reassigned ||
+				!record.stableDefinition ||
+				record.node.async ||
+				record.node.generator ||
+				reflectiveOwner(record) ||
+				nearestFunctionScope(record.scope.parent)?.kind !== 'module'
+			)
+				continue;
+			const indices = new Set();
+			for (let index = 0; index < record.parameters.length; index++) {
+				const binding = record.parameters[index];
+				const uses = reads.get(binding) ?? [];
+				if (
+					binding &&
+					!binding.reassigned &&
+					!mutated.has(binding) &&
+					uses.length &&
+					uses.every((read) => effectOwnerForRead(read) === record)
+				)
+					indices.add(index);
+			}
+			if (indices.size) effectParameters.set(record.binding, indices);
+		}
+	function inputOwnerForRead(read) {
+		const effectOwner = effectOwnerForRead(read);
+		if (effectOwner) return effectOwner;
+		let child = read;
+		for (let node = parents.get(child); node; child = node, node = parents.get(node)) {
+			if (node.type !== 'CallExpression') continue;
+			if (
+				node.optional ||
+				node.callee?.type !== 'Identifier' ||
+				!/^use[A-Z]/.test(node.callee.name)
+			)
+				return null;
+			const indices = effectParameters.get(directCallBinding(node, analysis.nodeScopes.get(node)));
+			if (!indices || !indices.has(node.arguments.indexOf(child)) || unwrapValue(child) !== read)
+				return null;
+			return owners.get(nearestFunctionScope(analysis.nodeScopes.get(node)));
+		}
+		return null;
+	}
+	function ownsReads(record, bindings) {
+		if (record.node.async || record.node.generator || reflectiveOwner(record)) return false;
+		// Nested callbacks and local JSX factories are value invocations. A
+		// module function with its own authored slotted effect is already a hook
+		// owner independently of how its name or returned values are spelled.
+		if (nearestFunctionScope(record.scope.parent)?.kind !== 'module') return false;
+		return bindings.every(({ binding }) =>
+			(reads.get(binding) ?? []).every((read) => inputOwnerForRead(read) === record),
+		);
+	}
+	const candidateDependencies = new Map();
+	const candidates = new Map();
+	for (const { decl, kind, bindings } of analysis.declarators) {
+		const initial = unwrapValue(decl.init);
+		if (
+			!bindings.some(({ binding }) => referenced.has(binding)) ||
+			kind !== 'const' ||
+			!createsIdentity(initial) ||
+			inLoop.has(decl) ||
+			bindings.some(({ binding }) => binding.reassigned || mutated.has(binding))
+		)
+			continue;
+		if (['Identifier', 'Literal', 'MemberExpression', 'ChainExpression'].includes(initial.type)) {
+			if (
+				initial.type !== 'ChainExpression' ||
+				!['CallExpression', 'NewExpression'].includes(initial.expression?.type)
+			)
+				continue;
+		}
+		const owner = owners.get(nearestFunctionScope(analysis.nodeScopes.get(decl)));
+		if (!owner || !ownsReads(owner, bindings) || hasInlineMemoDirectEval(initial)) continue;
+		const callback = isFunction(initial);
+		if (
+			(!callback && prohibited(initial)) ||
+			executesHook(initial) ||
+			(initial.type === 'ArrowFunctionExpression' && capturesLexicalReceiver(initial))
+		)
+			continue;
+		const dependencies = collectDependencies(
+			initial,
+			callback ? (analysis.functionScopes.get(initial) ?? null) : null,
+			analysis,
+		);
+		if (
+			dependencies.some(({ binding }) => {
+				const enclosingFunction = owners.get(nearestFunctionScope(binding.scope));
+				if (
+					!callback &&
+					enclosingFunction &&
+					enclosingFunction.node.start >= initial.start &&
+					enclosingFunction.node.end <= initial.end
+				)
+					return false;
+				const declaration = declarations.get(binding);
+				if (
+					!callback &&
+					declaration &&
+					declaration.start >= initial.start &&
+					declaration.end <= initial.end
+				)
+					return false;
+				return (
+					binding.reassigned ||
+					mutated.has(binding) ||
+					(declaration && declaration.start >= decl.start)
+				);
+			})
+		)
+			continue;
+		candidates.set(decl, callback ? 'useCallback' : 'useMemo');
+		candidateDependencies.set(decl, dependencies);
+	}
+	return { candidates, names, hookCalls, omittedDependencies, candidateDependencies };
+}