rea-agents 6.4.0 → 6.7.0

package/dist/domain/javascript/javascriptSemanticAsyncEffects.js

@@ -1,11 +1,11 @@
 import * as t from "@babel/types";
-import { semanticBuiltinNamespacePath } from "./javascriptSemanticProvenance.js";
-import { semanticCallableIdForNode } from "./javascriptSemanticProjection.js";
+import { createSemanticCallableIdStack } from "./javascriptSemanticCallableStack.js";
 import { semanticStaticPropertyName } from "./javascriptAstValues.js";
 import { resolveSemanticBindingState, semanticResolutionBlocked, } from "./javascriptSemanticState.js";
+import { semanticBindingAtRead } from "./javascriptSemanticMutationInitializers.js";
 import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
 import { range } from "./javascriptStaticAnalysisHelpers.js";
-import { dataEffectLiteralString, dataEffectMemberCallee, assignedSemanticResultBindings, scalarAssignedResultBinding, semanticProjectedBindingFacts, } from "./javascriptSemanticDataEffectHelpers.js";
+import { builtinDataEffectMethod, dataEffectLiteralString, dataEffectMemberCallee, assignedSemanticResultBindings, scalarAssignedResultBinding, semanticProjectedBindingFacts, } from "./javascriptSemanticDataEffectHelpers.js";
 const EVENT_REGISTER_METHODS = [
     "on",
     "once",
@@ -18,6 +18,12 @@ const EVENT_REMOVE_METHODS = [
     "removeListener",
     "removeAllListeners",
 ];
+/**
+ * Methods whose argument position 1 names a listener. `removeAllListeners`
+ * takes only an optional event name, and `emit` passes its remaining
+ * arguments as data to listeners that already exist.
+ */
+const EVENT_LISTENER_METHODS = [...EVENT_REGISTER_METHODS, "off", "removeListener"];
 const EVENT_METHODS = [
     ...EVENT_REGISTER_METHODS,
     ...EVENT_REMOVE_METHODS,
@@ -38,15 +44,13 @@ export const collectJavaScriptSemanticAsyncEffects = (program, state, callables)
     const events = [];
     const timers = [];
     const callableIds = new Set(callables.map(({ callableId }) => callableId));
-    const callableStack = [];
+    const callableStack = createSemanticCallableIdStack(callableIds);
     const ancestors = [];
     traverseJavaScriptAst(program, {
-        enter: (node) => {
-            const callableId = semanticCallableIdForNode(node);
-            if (callableId !== null && callableIds.has(callableId))
-                callableStack.push(callableId);
+        enter: (node, parent) => {
+            callableStack.enter(node, parent);
             if (t.isCallExpression(node) || t.isOptionalCallExpression(node)) {
-                const ownerCallableId = callableStack.at(-1) ?? null;
+                const ownerCallableId = callableStack.callables.at(-1) ?? null;
                 collectEvent(node, ownerCallableId, state, events);
                 collectTimer({
                     node,
@@ -59,10 +63,8 @@ export const collectJavaScriptSemanticAsyncEffects = (program, state, callables)
             ancestors.push(node);
         },
         exit: (node) => {
-            const callableId = semanticCallableIdForNode(node);
             ancestors.pop();
-            if (callableId !== null && callableStack.at(-1) === callableId)
-                callableStack.pop();
+            callableStack.exit(node);
         },
     });
     return {
@@ -80,7 +82,9 @@ const collectEvent = (node, ownerCallableId, state, output) => {
         return;
     const kind = eventKind(method);
     const eventArgument = node.arguments[0];
-    const listenerArgument = node.arguments[1];
+    const listenerArgument = EVENT_LISTENER_METHODS.includes(method)
+        ? node.arguments[1]
+        : undefined;
     const emitter = emitterIdentity(member.object, state);
     const eventName = dataEffectLiteralString(eventArgument);
     output.push({
@@ -142,6 +146,27 @@ const collectTimer = (input) => {
         ? "schedule"
         : "cancel";
     const projectedResultBindings = assignedSemanticResultBindings(node, ancestors, state);
+    const handle = kind === "cancel" && t.isIdentifier(node.arguments[0])
+        ? resolveSemanticBindingState(state, node.arguments[0], node.arguments[0].name)
+        : undefined;
+    const handleRead = handle === undefined || !t.isIdentifier(node.arguments[0])
+        ? null
+        : (() => {
+            const snapshot = semanticBindingAtRead(handle, node.arguments[0], state.parentsByNode);
+            // A const handle has the same value inside a later closure even
+            // when the source positions belong to different function bodies.
+            const stableClosureCapture = !handle.mutable &&
+                handle.initializers.length === 1 &&
+                handle.referenceInitializers.length === 0;
+            const origins = [
+                ...snapshot.binding.initializers,
+                ...snapshot.binding.referenceInitializers,
+            ];
+            return {
+                origins: origins.map(({ node: origin }) => origin),
+                complete: snapshot.status === "ordered" || stableClosureCapture,
+            };
+        })();
     output.push({
         node,
         method,
@@ -153,29 +178,22 @@ const collectTimer = (input) => {
         projectedResultBindings: kind === "schedule"
             ? semanticProjectedBindingFacts(projectedResultBindings.filter(({ projectionPath }) => projectionPath.length > 0))
             : [],
+        handleRead,
     });
 };
 const resolveTimers = (candidates) => {
-    const schedulesByBinding = new Map();
-    for (const candidate of candidates) {
-        if (candidate.kind !== "schedule")
-            continue;
-        const ids = [
-            ...(candidate.handleBindingId === null
-                ? []
-                : [candidate.handleBindingId]),
-            ...candidate.projectedResultBindings.map(({ bindingId }) => bindingId),
-        ];
-        for (const id of ids) {
-            const existing = schedulesByBinding.get(id) ?? [];
-            existing.push(candidate);
-            schedulesByBinding.set(id, existing);
-        }
-    }
+    const schedules = new Map(candidates
+        .filter(({ kind }) => kind === "schedule")
+        .map((candidate) => [candidate.node, candidate]));
     return candidates.map((candidate) => {
-        const linked = candidate.kind === "cancel" && candidate.handleBindingId !== null
-            ? (schedulesByBinding.get(candidate.handleBindingId) ?? [])
-            : [];
+        // Unordered reads retain possible initializers as candidate edges. Only an
+        // ordered or immutable read can establish one complete cancellation link.
+        const linked = candidate.handleRead?.origins.flatMap((origin) => {
+            const schedule = schedules.get(origin);
+            return schedule === undefined ? [] : [schedule];
+        }) ?? [];
+        const incompleteOrigins = candidate.handleRead !== null &&
+            candidate.handleRead.origins.length !== linked.length;
         return {
             timerId: timerId(candidate),
             kind: candidate.kind,
@@ -191,9 +209,11 @@ const resolveTimers = (candidates) => {
             resolution: candidate.kind === "schedule"
                 ? "complete"
                 : linked.length === 1 &&
+                    candidate.handleRead?.complete &&
+                    !incompleteOrigins &&
                     !linked[0]?.projectedResultBindings.some(({ bindingId }) => bindingId === candidate.handleBindingId)
                     ? "complete"
-                    : linked.length > 1
+                    : linked.length > 0
                         ? "partial"
                         : "unresolved",
         };
@@ -210,30 +230,10 @@ const timerMethod = (callee, state) => {
                 ? null
                 : method;
         }
-        return timerMethodFromBinding(binding);
     }
-    if (!t.isMemberExpression(callee) && !t.isOptionalMemberExpression(callee))
-        return null;
-    const method = admittedTimerMethod(semanticStaticPropertyName(callee.property, callee.computed));
-    return method !== null &&
-        t.isIdentifier(callee.object) &&
-        timerNamespaceBinding(resolveSemanticBindingState(state, callee.object, callee.object.name))
-        ? method
-        : null;
+    return admittedTimerMethod(builtinDataEffectMethod(callee, state, ["timers", "node:timers"]) ?? "");
 };
 const admittedTimerMethod = (value) => [...TIMER_SCHEDULE_METHODS, ...TIMER_CANCEL_METHODS].find((candidate) => candidate === value) ?? null;
-const timerMethodFromBinding = (binding) => {
-    for (const { specifier, importedPath } of binding.directOrigins) {
-        if (!timerModule(specifier))
-            continue;
-        const method = admittedTimerMethod(importedPath.at(-1) ?? "");
-        if (method !== null)
-            return method;
-    }
-    return null;
-};
-const timerNamespaceBinding = (binding) => binding?.directOrigins.some(({ specifier, importedPath }) => timerModule(specifier) && semanticBuiltinNamespacePath(importedPath)) ?? false;
-const timerModule = (specifier) => specifier === "timers" || specifier === "node:timers";
 const bindingId = (node, state) => t.isIdentifier(node)
     ? (resolveSemanticBindingState(state, node, node.name)?.bindingId ?? null)
     : null;

package/dist/domain/javascript/javascriptSemanticCallResolution.js

@@ -1,14 +1,15 @@
 import * as t from "@babel/types";
 import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
 import { semanticCallableIdForNode } from "./javascriptSemanticProjection.js";
-import { unwrapJavaScriptExpression } from "./javascriptAstValues.js";
-import { resolveSemanticBindingState, } from "./javascriptSemanticState.js";
+import { semanticBindingAtRead } from "./javascriptSemanticMutationInitializers.js";
+import { unwrapJavaScriptExpression, runtimeFunctionParameters, } from "./javascriptAstValues.js";
+import { resolveSemanticBindingState, semanticStableInitializer, } from "./javascriptSemanticState.js";
 import { range } from "./javascriptStaticAnalysisHelpers.js";
 /** Resolve local callable candidates without following dynamic properties. */
 export const resolveLocalCallables = (input) => resolveCallables(input.node, {
     state: input.state,
     callableById: input.callableById,
-    seenBindings: input.seenBindings,
+    seenInitializers: input.seenInitializers,
     bindingCache: input.bindingCache,
 });
 const resolveCallables = (node, context) => {
@@ -35,14 +36,35 @@ const resolveCallables = (node, context) => {
     };
 };
 const resolveIdentifier = (node, context) => {
+    const cached = context.bindingCache.get(node);
+    if (cached !== undefined)
+        return cached;
     const binding = resolveSemanticBindingState(context.state, node, node.name);
-    return binding === undefined
-        ? {
+    if (binding === undefined)
+        return {
             callableIds: [],
             complete: false,
             reason: `Unresolved call target ${node.name}.`,
+        };
+    const read = semanticBindingAtRead(binding, node, context.state.parentsByNode);
+    const candidates = resolveBindingCallables(read.binding, context);
+    // Knowing every local candidate does not prove that any write replaced the
+    // incoming value, or that a write in another activation precedes this read.
+    const covered = read.hasDefiniteInitializer ||
+        semanticStableInitializer(binding, context.state) !== undefined;
+    const resolution = candidates.complete && !covered
+        ? {
+            ...candidates,
+            complete: false,
+            reason: `Call target ${binding.name} may retain an incoming value or an unordered assignment.`,
         }
-        : resolveBindingCallables(binding, context);
+        : candidates;
+    // Key by the immutable read, not binding identity: before/after snapshots
+    // differ. Cache cycle-independent partial results too, keeping alias
+    // diamonds linear even when their shared leaf has an unknown incoming value.
+    if (!resolution.cycleDependent)
+        context.bindingCache.set(node, resolution);
+    return resolution;
 };
 const resolveAlternatives = (left, right, context) => {
     const candidates = [left, right].map((candidate) => resolveCallables(candidate, context));
@@ -50,31 +72,36 @@ const resolveAlternatives = (left, right, context) => {
         callableIds: uniqueCallableIds(candidates.flatMap(({ callableIds }) => callableIds)),
         complete: candidates.every(({ complete }) => complete),
         reason: "Conditional or logical call target has multiple candidates.",
+        ...(candidates.some((candidate) => candidate.cycleDependent)
+            ? { cycleDependent: true }
+            : {}),
     };
 };
 const resolveBindingCallables = (binding, context) => {
-    const cached = context.bindingCache.get(binding.bindingId);
-    if (cached !== undefined)
-        return cached;
-    if (context.seenBindings.has(binding.bindingId))
-        return {
-            callableIds: [],
-            complete: false,
-            reason: `Call target alias cycle at ${binding.name}.`,
-        };
     if (binding.initializers.length === 0)
         return missingBindingInitializer(binding);
-    const candidateContext = {
-        ...context,
-        seenBindings: new Set([...context.seenBindings, binding.bindingId]),
-    };
-    const candidates = binding.initializers.map(({ node, projection }) => projection.length === 0
-        ? resolveCallables(node, candidateContext)
-        : {
-            callableIds: [],
-            complete: false,
-            reason: `Projected call target ${binding.name} is unresolved.`,
-        });
+    const candidates = binding.initializers.map((initializer) => {
+        if (context.seenInitializers.has(initializer))
+            return {
+                callableIds: [],
+                complete: false,
+                cycleDependent: true,
+                reason: `Call target initializer cycle at ${binding.name}.`,
+            };
+        return initializer.projection.length === 0
+            ? resolveCallables(initializer.node, {
+                ...context,
+                seenInitializers: new Set([
+                    ...context.seenInitializers,
+                    initializer,
+                ]),
+            })
+            : {
+                callableIds: [],
+                complete: false,
+                reason: `Projected call target ${binding.name} is unresolved.`,
+            };
+    });
     const callableIds = uniqueCallableIds(candidates.flatMap((candidate) => candidate.callableIds));
     const resolution = {
         callableIds,
@@ -82,9 +109,10 @@ const resolveBindingCallables = (binding, context) => {
         reason: callableIds.length === 1 && candidates.every(({ complete }) => complete)
             ? "Unique local callable target."
             : `Call target ${binding.name} has ambiguous or unsupported assignments.`,
+        ...(candidates.some((candidate) => candidate.cycleDependent)
+            ? { cycleDependent: true }
+            : {}),
     };
-    if (resolution.complete)
-        context.bindingCache.set(binding.bindingId, resolution);
     return resolution;
 };
 const missingBindingInitializer = (binding) => ({
@@ -111,12 +139,13 @@ const parameterAcceptsArgument = (callable, location, argumentIndex, state) => {
     const node = state.callableNodesById.get(callable.callableId);
     if (!t.isFunction(node))
         return false;
-    const parameterIndex = node.params.findIndex((parameter) => rangeContains(range(parameter), location));
+    const parameters = runtimeFunctionParameters(node);
+    const parameterIndex = parameters.findIndex((parameter) => rangeContains(range(parameter), location));
     if (parameterIndex === argumentIndex)
         return true;
     return (parameterIndex >= 0 &&
         parameterIndex < argumentIndex &&
-        t.isRestElement(node.params[parameterIndex]));
+        t.isRestElement(parameters[parameterIndex]));
 };
 const rangeContains = (outer, inner) => (outer.start.line < inner.start.line ||
     (outer.start.line === inner.start.line &&

package/dist/domain/javascript/javascriptSemanticCallableStack.js

@@ -0,0 +1,52 @@
+import * as t from "@babel/types";
+import { semanticCallableIdForNode } from "./javascriptSemanticProjection.js";
+/**
+ * Track callables admitted by `admit`, which maps a callable ID to the value
+ * kept on the stack or `undefined` to ignore it. A caller-owned `callables`
+ * array is updated in place, so shared contexts can keep reading it.
+ */
+export const createSemanticCallableStack = (admit, callables = []) => {
+    const frames = [];
+    const suspendedMethods = new Map();
+    callables.length = 0;
+    const push = (frame) => {
+        frames.push(frame);
+        callables.push(frame.callable);
+    };
+    const pop = () => {
+        callables.pop();
+        return frames.pop();
+    };
+    return {
+        callables,
+        enter: (node, parent) => {
+            if (parent !== null &&
+                (t.isObjectMethod(parent) || t.isClassMethod(parent)) &&
+                parent.computed &&
+                parent.key === node &&
+                frames.at(-1)?.callableId === semanticCallableIdForNode(parent)) {
+                const method = pop();
+                if (method !== undefined)
+                    suspendedMethods.set(node, method);
+            }
+            const callableId = semanticCallableIdForNode(node);
+            if (callableId === null)
+                return;
+            const callable = admit(callableId);
+            if (callable !== undefined)
+                push({ callableId, callable });
+        },
+        exit: (node) => {
+            const callableId = semanticCallableIdForNode(node);
+            if (callableId !== null && frames.at(-1)?.callableId === callableId)
+                pop();
+            const method = suspendedMethods.get(node);
+            if (method !== undefined) {
+                suspendedMethods.delete(node);
+                push(method);
+            }
+        },
+    };
+};
+/** Track admitted callable IDs, keeping each ID as its stack value. */
+export const createSemanticCallableIdStack = (admitted, callables = []) => createSemanticCallableStack((callableId) => (admitted.has(callableId) ? callableId : undefined), callables);

package/dist/domain/javascript/javascriptSemanticCalls.js

@@ -1,5 +1,6 @@
 import * as t from "@babel/types";
-import { semanticCallableIdForNode, semanticReferenceRole, } from "./javascriptSemanticProjection.js";
+import { semanticReferenceRole } from "./javascriptSemanticProjection.js";
+import { createSemanticCallableStack } from "./javascriptSemanticCallableStack.js";
 import { semanticStaticPropertyKey } from "./javascriptAstValues.js";
 import { resolveSemanticBindingState, isUnshadowedGlobal, } from "./javascriptSemanticState.js";
 import { parameterBindings, resolveLocalCallables, } from "./javascriptSemanticCallResolution.js";
@@ -21,18 +22,15 @@ export const collectJavaScriptSemanticCalls = (program, state, callables) => {
         state,
         callableById,
         output,
-        bindingResolutionCache: new Map(),
+        bindingResolutionCache: new WeakMap(),
         parameterBindingCache: new Map(),
         ancestors: [],
     };
-    const callableStack = [];
+    const callableStack = createSemanticCallableStack((callableId) => callableById.get(callableId));
     traverseJavaScriptAst(program, {
         enter: (node, parent) => {
-            const callableId = semanticCallableIdForNode(node);
-            const callable = callableId === null ? undefined : callableById.get(callableId);
-            if (callable !== undefined)
-                callableStack.push(callable);
-            const owner = enclosingFunction(callableStack);
+            callableStack.enter(node, parent);
+            const owner = enclosingFunction(callableStack.callables);
             collectCapture(node, parent, owner, context);
             collectDynamicProperty(node, owner, state, output);
             collectDynamicScope(node, owner, state, output);
@@ -44,10 +42,7 @@ export const collectJavaScriptSemanticCalls = (program, state, callables) => {
         },
         exit: (node) => {
             context.ancestors.pop();
-            const callableId = semanticCallableIdForNode(node);
-            if (callableId !== null &&
-                callableStack.at(-1)?.callableId === callableId)
-                callableStack.pop();
+            callableStack.exit(node);
         },
     });
     return {
@@ -65,7 +60,7 @@ const collectCallSite = (node, parent, owner, context) => {
         node: node.callee,
         state,
         callableById,
-        seenBindings: new Set(),
+        seenInitializers: new Set(),
         bindingCache: context.bindingResolutionCache,
     });
     const callSiteId = semanticCallSiteId(node);
@@ -234,8 +229,8 @@ const collectDynamicProperty = (node, owner, state, output) => {
 const collectDynamicScope = (node, owner, state, output) => {
     const reason = t.isWithStatement(node)
         ? "`with` introduces a runtime binding environment; names inside are not statically resolvable."
-        : t.isCallExpression(node) && isUnshadowedGlobal(node.callee, state, "eval")
-            ? "`eval` can declare bindings at runtime; names inside the evaluated source are not statically resolvable."
+        : state.opaqueEffects.sites.has(node)
+            ? "`eval` can change bindings and reachable objects at runtime; its effects are not statically resolvable."
             : null;
     if (reason === null)
         return;