rea-agents 6.2.0 → 6.4.0

package/dist/domain/javascript/javascriptSemanticReturnedReferences.js

@@ -0,0 +1,219 @@
+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() },
+        ];
+        for (let cursor = 0; cursor < pending.length; cursor++) {
+            const item = pending[cursor];
+            if (item === undefined)
+                break;
+            const node = unwrapJavaScriptExpression(item.node).node;
+            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

@@ -1,12 +1,14 @@
 import * as t from "@babel/types";
 import { semanticContainer, semanticPropertyPointer, } from "./javascriptSemanticSlots.js";
-import { compareCodePoints } from "../canonicalOrdering.js";
+import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
 import { semanticCallableIdForNode } from "./javascriptSemanticProjection.js";
+import { unwrapJavaScriptExpression } from "./javascriptAstValues.js";
 import { resolveSemanticBindingState, } from "./javascriptSemanticState.js";
 import { evaluateSemanticExpression } from "./javascriptSemanticValues.js";
 import { range } from "./javascriptStaticAnalysisHelpers.js";
 import { semanticReturnCoverage } from "./javascriptSemanticCoverage.js";
 import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
+import { semanticCallableResultExpressions } from "./javascriptSemanticCallableResults.js";
 /** Evaluate direct returns while excluding every nested callable. */
 export const collectSemanticReturns = (program, state, parserPartial) => {
     const nodes = callableNodes(program);
@@ -42,20 +44,25 @@ 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)}`;
+const semanticReturnSiteId = (callableId, location) => [
+    callableId,
+    "return",
+    String(location.start.line),
+    String(location.start.column),
+    String(location.end.line),
+    String(location.end.column),
+].join(":");
 /** Link exports to callables only when lexical resolution is unique and exact. */
 export const resolveSemanticModuleCallables = (state, callables) => {
     const callableIds = new Set(callables.map(({ callableId }) => callableId));
-    const root = state.scopes.find(({ kind }) => kind === "program");
     return state.moduleLinks.map((link) => {
-        if (link.callableId !== null && callableIds.has(link.callableId))
-            return link;
-        if (link.localName === null || root === undefined)
-            return { ...link, callableId: null };
-        const named = callables.filter(({ name, containerScopeId }) => name === link.localName && containerScopeId === root.scopeId);
-        if (named.length === 1)
-            return { ...link, callableId: named[0]?.callableId ?? null };
-        const binding = root.bindings.get(link.localName);
+        // 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)
+            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());
@@ -76,44 +83,27 @@ const callableNodes = (program) => {
     });
     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 childNodes = (node) => (t.VISITOR_KEYS[node.type] ?? []).flatMap((key) => {
-    const value = Reflect.get(node, key);
-    if (t.isNode(value))
-        return [value];
-    return Array.isArray(value)
-        ? value.filter((item) => t.isNode(item))
-        : [];
-});
+const directReturnExpressions = (callable) => semanticCallableResultExpressions(callable)
+    .filter(({ kind }) => kind === "return")
+    .map(({ node, site }) => ({ node, location: range(site) }));
 const callableIdsForBinding = (binding, state, admitted, seen) => {
-    if (seen.has(binding.bindingId) || binding.initializers.length !== 1)
+    // 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"))
         return [];
     const initializer = binding.initializers[0];
-    if (initializer === undefined || initializer.projection.length > 0)
+    if (initializer === undefined ||
+        initializer.projection.length > 0 ||
+        state.conditionalInitializers.has(initializer.node))
         return [];
     return callableIdsForNode(initializer.node, state, admitted, new Set([...seen, binding.bindingId]));
 };
 const callableIdsForNode = (node, state, admitted, seen) => {
+    const unwrapped = unwrapJavaScriptExpression(node).node;
+    if (unwrapped !== node)
+        return callableIdsForNode(unwrapped, state, admitted, seen);
     const direct = semanticCallableIdForNode(node);
     if (direct !== null && admitted.has(direct))
         return [direct];
@@ -123,10 +113,6 @@ const callableIdsForNode = (node, state, admitted, seen) => {
             ? []
             : callableIdsForBinding(binding, state, admitted, seen);
     }
-    if (t.isTSAsExpression(node) ||
-        t.isTSTypeAssertion(node) ||
-        t.isTSNonNullExpression(node))
-        return callableIdsForNode(node.expression, state, admitted, seen);
     return [];
 };
 /** Flatten a semantic value to bounded JSON-pointer leaves for graph projection. */
@@ -134,8 +120,8 @@ export const flattenSemanticReturnValue = (value) => {
     const fields = [];
     const propertyCoverage = [];
     flattenValue(value, "", fields, propertyCoverage);
-    fields.sort((left, right) => compareCodePoints(left.path, right.path));
-    propertyCoverage.sort((left, right) => compareCodePoints(left.path, right.path));
+    fields.sort((left, right) => compareUnicodeCodePoints(left.path, right.path));
+    propertyCoverage.sort((left, right) => compareUnicodeCodePoints(left.path, right.path));
     return { fields, propertyCoverage };
 };
 const flattenValue = (value, path, fields, coverage, presence = "present") => {

package/dist/domain/javascript/javascriptSemanticState.js

@@ -8,9 +8,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 +28,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 +41,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;

package/dist/domain/javascript/javascriptSemanticTraversal.js

@@ -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,9 @@ export const traverseJavaScriptAst = (root, visitor) => {
         const child = current.children[current.nextIndex];
         if (child !== undefined) {
             current.nextIndex += 1;
+            if (visited % 1024 === 0)
+                yield;
+            visited += 1;
             pending.push(enter(child, current.node));
         }
         else {
@@ -32,8 +42,21 @@ 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;
+    }
 };
-const childNodes = (node) => {
+/**
+ * Child Babel nodes in `VISITOR_KEYS` order. Single owner for AST child
+ * expansion; bespoke `Object.values` / duplicated `childNodes` walkers must
+ * 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 [];