rea-agents 6.3.0 → 6.5.0

package/dist/domain/javascript/javascriptSemanticReturnedReferences.js

@@ -0,0 +1,233 @@
+import * as t from "@babel/types";
+import { semanticStaticPropertyKey, unwrapJavaScriptExpression, } from "./javascriptAstValues.js";
+import { resolveLocalCallables, } from "./javascriptSemanticCallResolution.js";
+import { semanticCallableResultExpressions } from "./javascriptSemanticCallableResults.js";
+import { semanticArrayIndex, } from "./javascriptSemanticPropertyPaths.js";
+import { resolveSemanticBindingState, } from "./javascriptSemanticState.js";
+/** Resolve local result references conservatively, without claiming call execution. */
+export const createSemanticReturnedReferences = (state) => {
+    const callableById = new Map(state.callables.map((callable) => [callable.callableId, callable]));
+    const bindingCache = new Map();
+    const results = new WeakMap();
+    const objectTargets = new WeakMap();
+    return (callee) => {
+        const existing = results.get(callee);
+        if (existing !== undefined)
+            return existing;
+        const functions = new Set();
+        const resolution = resolveLocalCallables({
+            node: callee,
+            state,
+            callableById,
+            bindingCache,
+            seenBindings: new Set(),
+        });
+        for (const id of resolution.callableIds) {
+            const node = state.callableNodesById.get(id);
+            if (node !== undefined)
+                functions.add(node);
+        }
+        const pending = [
+            { node: callee, path: [], bindings: new Set() },
+        ];
+        // A shared initializer can be reached through both arms of every alias
+        // diamond. Expand an expression/path again only when its cycle context
+        // permits a binding that an earlier traversal blocked.
+        const expanded = new WeakMap();
+        for (let cursor = 0; cursor < pending.length; cursor++) {
+            const item = pending[cursor];
+            if (item === undefined)
+                break;
+            const node = unwrapJavaScriptExpression(item.node).node;
+            const pathKey = JSON.stringify(item.path);
+            const paths = expanded.get(node) ?? new Map();
+            const contexts = paths.get(pathKey) ?? [];
+            if (contexts.some((context) => [...context].every((binding) => item.bindings.has(binding))))
+                continue;
+            paths.set(pathKey, [
+                ...contexts.filter((context) => ![...item.bindings].every((binding) => context.has(binding))),
+                item.bindings,
+            ]);
+            expanded.set(node, paths);
+            if (t.isIdentifier(node)) {
+                const binding = resolveSemanticBindingState(state, node, node.name);
+                if (binding === undefined || item.bindings.has(binding.bindingId))
+                    continue;
+                const bindings = new Set([...item.bindings, binding.bindingId]);
+                for (const initializer of [
+                    ...binding.initializers,
+                    ...binding.referenceInitializers,
+                ])
+                    pending.push({
+                        node: initializer.node,
+                        path: [...initializer.projection, ...item.path],
+                        bindings,
+                    });
+            }
+            else if (t.isMemberExpression(node) ||
+                t.isOptionalMemberExpression(node)) {
+                const path = [];
+                let receiver = node;
+                while (t.isMemberExpression(receiver) ||
+                    t.isOptionalMemberExpression(receiver)) {
+                    path.push(semanticStaticPropertyKey(receiver.property, receiver.computed));
+                    receiver = unwrapJavaScriptExpression(receiver.object).node;
+                }
+                pending.push({
+                    ...item,
+                    node: receiver,
+                    path: [...path.reverse(), ...item.path],
+                });
+            }
+            else if (t.isConditionalExpression(node) ||
+                t.isLogicalExpression(node)) {
+                pending.push({
+                    ...item,
+                    node: t.isConditionalExpression(node) ? node.consequent : node.left,
+                }, {
+                    ...item,
+                    node: t.isConditionalExpression(node) ? node.alternate : node.right,
+                });
+            }
+            else if (t.isSequenceExpression(node)) {
+                const last = node.expressions.at(-1);
+                if (last !== undefined)
+                    pending.push({ ...item, node: last });
+            }
+            else if (t.isFunction(node) && item.path.length === 0)
+                functions.add(node);
+            else if (t.isObjectExpression(node))
+                selectObjectTargets(node, item, pending, objectTargets);
+            else if (t.isArrayExpression(node)) {
+                const [key, ...path] = item.path;
+                const index = key === undefined || key === null ? null : semanticArrayIndex(key);
+                let uncertainOffset = false;
+                node.elements.forEach((element, offset) => {
+                    if (element === null)
+                        return;
+                    if (t.isSpreadElement(element)) {
+                        uncertainOffset = true;
+                        pending.push({
+                            ...item,
+                            node: element.argument,
+                            path: [null, ...path],
+                        });
+                    }
+                    else if (index === null || uncertainOffset || index === offset)
+                        pending.push({ ...item, node: element, path });
+                });
+            }
+            else if (t.isNewExpression(node))
+                pending.push({ ...item, node: node.callee });
+            else if (t.isClass(node)) {
+                const [key, ...path] = item.path;
+                for (const member of node.body.body) {
+                    if (t.isClassMethod(member)) {
+                        if ((item.path.length === 0 && member.kind === "constructor") ||
+                            (key !== undefined &&
+                                (key === null ||
+                                    semanticStaticPropertyKey(member.key, member.computed) ===
+                                        String(key))))
+                            pending.push({ ...item, node: member, path });
+                    }
+                    else if (t.isClassProperty(member) &&
+                        member.value !== null &&
+                        member.value !== undefined &&
+                        key !== undefined &&
+                        (key === null ||
+                            semanticStaticPropertyKey(member.key, member.computed) ===
+                                String(key)))
+                        pending.push({ ...item, node: member.value, path });
+                }
+                if (node.superClass !== null && node.superClass !== undefined)
+                    pending.push({ ...item, node: node.superClass });
+            }
+        }
+        const output = [...functions].flatMap((node) => {
+            const callables = t.isClass(node)
+                ? node.body.body.filter((member) => t.isClassMethod(member) && member.kind === "constructor")
+                : [node];
+            return callables.flatMap((callable) => semanticCallableResultExpressions(callable).flatMap(({ node, delegated }) => node === null
+                ? []
+                : [{ node, projection: delegated ? [null] : [] }]));
+        });
+        results.set(callee, output);
+        return output;
+    };
+};
+const selectObjectTargets = (node, item, pending, indexes) => {
+    const [key, ...path] = item.path;
+    if (key !== null && key !== undefined) {
+        const index = objectTargetIndex(node, indexes);
+        const property = index.propertyByName.get(String(key));
+        if (property !== undefined) {
+            const unknowns = [];
+            for (let unknown = index.trailingUnknownsByProperty.get(property); unknown !== undefined; unknown = unknown.previous)
+                unknowns.push(unknown);
+            for (const { node: unknown } of unknowns.reverse())
+                pending.push({
+                    ...item,
+                    node: t.isSpreadElement(unknown)
+                        ? unknown.argument
+                        : t.isObjectProperty(unknown)
+                            ? unknown.value
+                            : unknown,
+                    ...(t.isSpreadElement(unknown) ? {} : { path }),
+                });
+            pending.push({
+                ...item,
+                node: t.isObjectProperty(property) ? property.value : property,
+                path,
+            });
+            return;
+        }
+    }
+    let replaced = false;
+    for (const property of [...node.properties].reverse()) {
+        if (replaced)
+            break;
+        if (t.isSpreadElement(property)) {
+            pending.push({ ...item, node: property.argument });
+            continue;
+        }
+        const name = semanticStaticPropertyKey(property.key, property.computed);
+        if (key !== null &&
+            key !== undefined &&
+            name !== null &&
+            name !== String(key))
+            continue;
+        if (t.isObjectProperty(property))
+            pending.push({ ...item, node: property.value, path });
+        else
+            pending.push({ ...item, node: property, path });
+        if (key !== null && key !== undefined && name === String(key))
+            replaced = true;
+    }
+};
+const objectTargetIndex = (node, indexes) => {
+    const existing = indexes.get(node);
+    if (existing !== undefined)
+        return existing;
+    const propertyByName = new Map();
+    const trailingUnknownsByProperty = new Map();
+    let trailingUnknown;
+    for (const property of [...node.properties].reverse()) {
+        if (t.isSpreadElement(property)) {
+            trailingUnknown = { node: property, previous: trailingUnknown };
+            continue;
+        }
+        const name = semanticStaticPropertyKey(property.key, property.computed);
+        if (name === null) {
+            trailingUnknown = { node: property, previous: trailingUnknown };
+            continue;
+        }
+        if (propertyByName.has(name))
+            continue;
+        propertyByName.set(name, property);
+        if (trailingUnknown !== undefined)
+            trailingUnknownsByProperty.set(property, trailingUnknown);
+    }
+    const created = { propertyByName, trailingUnknownsByProperty };
+    indexes.set(node, created);
+    return created;
+};

package/dist/domain/javascript/javascriptSemanticReturns.js

@@ -7,12 +7,12 @@ import { resolveSemanticBindingState, } from "./javascriptSemanticState.js";
 import { evaluateSemanticExpression } from "./javascriptSemanticValues.js";
 import { range } from "./javascriptStaticAnalysisHelpers.js";
 import { semanticReturnCoverage } from "./javascriptSemanticCoverage.js";
-import { childNodes, traverseJavaScriptAst, } from "./javascriptSemanticTraversal.js";
+import { semanticCallableResultExpressions } from "./javascriptSemanticCallableResults.js";
+import { semanticReadInitializers } from "./javascriptSemanticMutationInitializers.js";
 /** Evaluate direct returns while excluding every nested callable. */
-export const collectSemanticReturns = (program, state, parserPartial) => {
-    const nodes = callableNodes(program);
+export const collectSemanticReturns = (state, parserPartial) => {
     return state.callables.map((callable) => {
-        const node = nodes.get(callable.callableId);
+        const node = state.callableNodesById.get(callable.callableId);
         if (node === undefined)
             return {
                 ...callable,
@@ -43,77 +43,74 @@ export const collectSemanticReturns = (program, state, parserPartial) => {
         };
     });
 };
-const semanticReturnSiteId = (callableId, location) => `${callableId}:return:${String(location.start.line)}:${String(location.start.column)}:${String(location.end.line)}:${String(location.end.column)}`;
-/** Link exports to callables only when lexical resolution is unique and exact. */
-export const resolveSemanticModuleCallables = (state, callables) => {
+const semanticReturnSiteId = (callableId, location) => [
+    callableId,
+    "return",
+    String(location.start.line),
+    String(location.start.column),
+    String(location.end.line),
+    String(location.end.column),
+].join(":");
+/** Finalize exported bindings only when lexical resolution is unique and exact. */
+export const resolveSemanticModuleCallables = (state, callables, bindings) => {
     const callableIds = new Set(callables.map(({ callableId }) => callableId));
+    const provenanceByBinding = new Map(bindings.map(({ bindingId, provenance }) => [bindingId, provenance]));
     return state.moduleLinks.map((link) => {
+        if (link.kind === "type-import")
+            return { ...link, callableId: null };
         // Named exports follow their lexical binding, including every assignment.
         // A declaration's ID or a callable's display name cannot prove that link.
-        if (link.localName === null)
+        const captured = state.defaultExportExpressions.get(link);
+        if (link.localName === null && captured === undefined)
             return link.callableId !== null && callableIds.has(link.callableId)
                 ? link
                 : { ...link, callableId: null };
         const binding = state.moduleLinkBindings.get(link);
-        const resolved = binding === undefined
-            ? []
-            : callableIdsForBinding(binding, state, callableIds, new Set());
+        const resolved = captured !== undefined
+            ? callableIdsForNode(captured, state, callableIds, new Set(), true)
+            : binding === undefined
+                ? []
+                : callableIdsForBinding(binding, state, callableIds, new Set());
+        const provenance = binding === undefined || link.specifier !== null
+            ? undefined
+            : provenanceByBinding.get(binding.bindingId);
+        const resolutionMode = provenance?.status === "module"
+            ? provenance.origins[0].resolutionMode
+            : undefined;
         return {
             ...link,
+            ...(resolutionMode !== undefined ? { resolutionMode } : {}),
             callableId: resolved.length === 1 ? (resolved[0] ?? null) : null,
         };
     });
 };
-const callableNodes = (program) => {
-    const output = new Map();
-    traverseJavaScriptAst(program, {
-        enter: (node) => {
-            const id = semanticCallableIdForNode(node);
-            if (id !== null)
-                output.set(id, node);
-        },
-    });
-    return output;
-};
-const directReturnExpressions = (callable) => {
-    if (t.isArrowFunctionExpression(callable) &&
-        !t.isBlockStatement(callable.body))
-        return [{ node: callable.body, location: range(callable.body) }];
-    if (!t.isFunction(callable))
-        return [];
-    const output = [];
-    const visit = (node) => {
-        if (t.isFunction(node) || t.isClass(node))
-            return;
-        if (t.isReturnStatement(node)) {
-            output.push({ node: node.argument ?? null, location: range(node) });
-            return;
-        }
-        for (const child of childNodes(node))
-            visit(child);
-    };
-    for (const child of childNodes(callable.body))
-        visit(child);
-    return output;
-};
-const callableIdsForBinding = (binding, state, admitted, seen) => {
+const directReturnExpressions = (callable) => semanticCallableResultExpressions(callable)
+    .filter(({ kind }) => kind === "return")
+    .map(({ node, site }) => ({ node, location: range(site) }));
+const callableIdsForBinding = (binding, state, admitted, seen, read) => {
     // A single initializer does not prove an assignment executes or replace
     // the unknown incoming value of a parameter/catch binding.
     if (seen.has(binding.bindingId) ||
-        binding.initializers.length !== 1 ||
-        binding.definitions.some(({ kind }) => kind === "assignment" || kind === "parameter" || kind === "catch"))
+        (read === undefined && binding.initializers.length !== 1) ||
+        binding.definitions.some(({ kind }) => (read === undefined && kind === "assignment") ||
+            kind === "parameter" ||
+            kind === "catch"))
         return [];
-    const initializer = binding.initializers[0];
+    const selected = read === undefined
+        ? binding
+        : semanticReadInitializers(binding, read, state.parentsByNode);
+    const initializer = selected.initializers[0];
     if (initializer === undefined ||
+        selected.initializers.length !== 1 ||
         initializer.projection.length > 0 ||
-        state.conditionalInitializers.has(initializer.node))
+        state.conditionallySkippedExpressions.has(initializer.node))
         return [];
-    return callableIdsForNode(initializer.node, state, admitted, new Set([...seen, binding.bindingId]));
+    return callableIdsForNode(initializer.node, state, admitted, new Set([...seen, binding.bindingId]), read !== undefined);
 };
-const callableIdsForNode = (node, state, admitted, seen) => {
+const callableIdsForNode = (node, state, admitted, seen, snapshot = false) => {
     const unwrapped = unwrapJavaScriptExpression(node).node;
     if (unwrapped !== node)
-        return callableIdsForNode(unwrapped, state, admitted, seen);
+        return callableIdsForNode(unwrapped, state, admitted, seen, snapshot);
     const direct = semanticCallableIdForNode(node);
     if (direct !== null && admitted.has(direct))
         return [direct];
@@ -121,7 +118,7 @@ const callableIdsForNode = (node, state, admitted, seen) => {
         const binding = resolveSemanticBindingState(state, node, node.name);
         return binding === undefined
             ? []
-            : callableIdsForBinding(binding, state, admitted, seen);
+            : callableIdsForBinding(binding, state, admitted, seen, snapshot ? node : undefined);
     }
     return [];
 };

package/dist/domain/javascript/javascriptSemanticState.js

@@ -1,4 +1,24 @@
 import * as t from "@babel/types";
+/**
+ * Return one unconditional source initializer for a declared lexical binding.
+ * Repeated variable declarations without another initializer do not write it.
+ * This establishes a stable source fact only; it does not prove immutability or
+ * that the declaration has executed at a particular program point.
+ */
+export const semanticStableInitializer = (binding, state) => {
+    const [initializer] = binding?.initializers ?? [];
+    const [definition] = binding?.definitions ?? [];
+    return binding !== undefined &&
+        ((definition?.kind === "variable" &&
+            binding.definitions.every(({ kind }) => kind === "variable")) ||
+            (binding.definitions.length === 1 &&
+                (definition?.kind === "function" || definition?.kind === "class"))) &&
+        binding.initializers.length === 1 &&
+        initializer !== undefined &&
+        !state.conditionallySkippedExpressions.has(initializer.node)
+        ? initializer
+        : undefined;
+};
 /** Return the active scope from a non-empty construction stack. */
 export const currentSemanticScope = (stack) => {
     const scope = stack.at(-1);
@@ -8,9 +28,11 @@ export const currentSemanticScope = (stack) => {
 };
 /** Create a stable source-position identity for one lexical scope. */
 export const semanticScopeId = (kind, node) => `scope:${kind}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`;
+/** Create the canonical identity used by one binding in a lexical scope. */
+export const semanticBindingId = (scopeId, name) => `${scopeId}:binding:${encodeURIComponent(name)}`;
 /** Resolve one lexical name from the scope containing a node. */
 export const resolveSemanticBindingState = (state, node, name) => {
-    let scope = state.scopeByNode.get(node);
+    let scope = semanticScopeForNode(state, node);
     while (scope !== undefined) {
         const binding = scope.bindings.get(name);
         if (binding !== undefined)
@@ -26,7 +48,7 @@ export const resolveSemanticBindingState = (state, node, name) => {
 };
 /** Report whether an omitted binding scope blocks a trustworthy miss. */
 export const semanticResolutionBlocked = (state, node, name) => {
-    let scope = state.scopeByNode.get(node);
+    let scope = semanticScopeForNode(state, node);
     while (scope !== undefined) {
         if (scope.bindings.has(name))
             return false;
@@ -39,6 +61,24 @@ export const semanticResolutionBlocked = (state, node, name) => {
     }
     return false;
 };
+const semanticScopeForNode = (state, node) => {
+    let candidate = node;
+    while (candidate !== undefined) {
+        const scope = state.scopeByNode.get(candidate);
+        if (scope !== undefined) {
+            // Repeated references in a deep expression share this ancestry. Cache
+            // the traversed path without eagerly indexing nodes never resolved.
+            let descendant = node;
+            while (descendant !== undefined && descendant !== candidate) {
+                state.scopeByNode.set(descendant, scope);
+                descendant = state.parentsByNode.get(descendant);
+            }
+            return scope;
+        }
+        candidate = state.parentsByNode.get(candidate);
+    }
+    return undefined;
+};
 /** Resolve one name starting from an explicitly selected lexical scope. */
 export const resolveSemanticBindingFromScope = (scope, name, state) => {
     let candidate = scope;
@@ -72,5 +112,22 @@ export const semanticVariableScope = (scope, parent, state) => {
 };
 /** Identify a global name only when no lexical or dynamic environment shadows it. */
 export const isUnshadowedGlobal = (node, state, name) => t.isIdentifier(node, { name }) &&
-    resolveSemanticBindingState(state, node, name) === undefined &&
-    !semanticResolutionBlocked(state, node, name);
+    (resolveSemanticBindingState(state, node, name) === undefined
+        ? !semanticResolutionBlocked(state, node, name)
+        : isUnmodifiedCommonJsWrapperBinding(node, name, state));
+/** A program-level `var` redeclaration still denotes its untouched CJS wrapper parameter. */
+export const isUnmodifiedCommonJsWrapperBinding = (node, name, state) => {
+    // Parser sourceType separates explicit modules from script/CommonJS source;
+    // specifier resolution mode does not establish that distinction.
+    if (state.program.sourceType !== "script" ||
+        !["module", "exports", "require"].includes(name) ||
+        !t.isIdentifier(node, { name }))
+        return false;
+    const binding = resolveSemanticBindingState(state, node, name);
+    if (binding === undefined || binding.initializers.length !== 0)
+        return false;
+    const scope = state.scopesById.get(binding.scopeId);
+    return (scope?.kind === "program" &&
+        binding.declarationKinds.size > 0 &&
+        [...binding.declarationKinds].every((kind) => kind === "var"));
+};

package/dist/domain/javascript/javascriptSemanticTraversal.js

@@ -1,6 +1,6 @@
 import * as t from "@babel/types";
 /**
- * Visit every Babel AST node in deterministic source-tree order.
+ * Visit Babel AST nodes in deterministic source-tree order, excluding skipped subtrees.
  *
  * `readAncestors` returns a snapshot during `enter`, outermost-first and
  * ending with the direct parent. Callers
@@ -9,7 +9,13 @@ import * as t from "@babel/types";
  * has an ObjectProperty parent, so the parent alone cannot say whether the
  * identifier declares a binding or is assigned to.
  */
-export const traverseJavaScriptAst = (root, visitor) => {
+export const traverseJavaScriptAst = (root, visitor) => completeSemanticSteps(traverseJavaScriptAstSteps(root, visitor));
+/**
+ * {@link traverseJavaScriptAst} with a yield every 1,024 visited nodes, so a
+ * caller can serve control messages during one large traversal. Visit order
+ * and callbacks are identical.
+ */
+export function* traverseJavaScriptAstSteps(root, visitor) {
     const ancestors = [];
     const enter = (node, parent) => {
         visitor.enter(node, parent, () => [...ancestors]);
@@ -17,6 +23,7 @@ export const traverseJavaScriptAst = (root, visitor) => {
         return { node, parent, children: childNodes(node), nextIndex: 0 };
     };
     const pending = [enter(root, null)];
+    let visited = 1;
     while (pending.length > 0) {
         const current = pending.at(-1);
         if (current === undefined)
@@ -24,6 +31,11 @@ export const traverseJavaScriptAst = (root, visitor) => {
         const child = current.children[current.nextIndex];
         if (child !== undefined) {
             current.nextIndex += 1;
+            if (visited % 1024 === 0)
+                yield;
+            visited += 1;
+            if (visitor.skip?.(child) === true)
+                continue;
             pending.push(enter(child, current.node));
         }
         else {
@@ -32,6 +44,14 @@ export const traverseJavaScriptAst = (root, visitor) => {
             pending.pop();
         }
     }
+}
+/** Run cooperative analysis steps to completion without yielding control. */
+export const completeSemanticSteps = (steps) => {
+    for (;;) {
+        const step = steps.next();
+        if (step.done === true)
+            return step.value;
+    }
 };
 /**
  * Child Babel nodes in `VISITOR_KEYS` order. Single owner for AST child
@@ -39,9 +59,7 @@ export const traverseJavaScriptAst = (root, visitor) => {
  * not be reintroduced (they diverge on loc/comment fields and ordering).
  */
 export const childNodes = (node) => {
-    const keys = t.VISITOR_KEYS[node.type];
-    if (keys === undefined)
-        return [];
+    const keys = javaScriptAstChildKeys(node);
     const children = [];
     for (const key of keys) {
         const value = Reflect.get(node, key);
@@ -58,3 +76,5 @@ export const childNodes = (node) => {
     }
     return children;
 };
+/** Child-bearing fields; shared by traversal and structural AST comparison. */
+export const javaScriptAstChildKeys = (node) => t.VISITOR_KEYS[node.type] ?? [];