rea-agents 6.3.0 → 6.4.0

package/dist/domain/javascript/javascriptSemanticPropertyPaths.js

@@ -21,3 +21,80 @@ export const semanticPropertyPathKeyMatches = (key, name) => {
     const index = semanticArrayIndex(name);
     return index !== null && index >= key.startIndex;
 };
+const coverageNode = () => ({
+    terminal: false,
+    exact: new Map(),
+    selectors: new Map(),
+});
+/** Index exact effect prefixes without widening distinct member paths. */
+export class SemanticPropertyPathCoverage {
+    #root = coverageNode();
+    /** Retain a path only when no previously retained prefix covers it. */
+    retain(path) {
+        if (this.covers(path))
+            return false;
+        let node = this.#root;
+        for (const key of path) {
+            if (key !== null && typeof key !== "object") {
+                const name = String(key);
+                let child = node.exact.get(name);
+                if (child === undefined) {
+                    child = coverageNode();
+                    node.exact.set(name, child);
+                }
+                node = child;
+            }
+            else {
+                const identity = JSON.stringify(key);
+                let selected = node.selectors.get(identity);
+                if (selected === undefined) {
+                    selected = { key, node: coverageNode() };
+                    node.selectors.set(identity, selected);
+                }
+                node = selected.node;
+            }
+        }
+        node.terminal = true;
+        node.exact.clear();
+        node.selectors.clear();
+        return true;
+    }
+    /** Query retained prefixes without changing the coverage index. */
+    covers(path) {
+        const pending = [{ node: this.#root, offset: 0 }];
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (current === undefined)
+                break;
+            if (current.node.terminal)
+                return true;
+            const key = path[current.offset];
+            if (key === undefined)
+                continue;
+            if (key !== null && typeof key !== "object") {
+                const exact = current.node.exact.get(String(key));
+                if (exact !== undefined)
+                    pending.push({ node: exact, offset: current.offset + 1 });
+            }
+            for (const selected of current.node.selectors.values()) {
+                if (keyCovers(selected.key, key))
+                    pending.push({ node: selected.node, offset: current.offset + 1 });
+            }
+        }
+        return false;
+    }
+}
+const keyCovers = (covering, key) => {
+    if (covering === null)
+        return true;
+    if (key === null)
+        return false;
+    if (typeof key !== "object")
+        return typeof covering === "object"
+            ? semanticPropertyPathKeyMatches(covering, String(key))
+            : String(covering) === String(key);
+    return (typeof covering === "object" &&
+        covering.excludedKeys.every((name) => key.excludedKeys.includes(name)) &&
+        (covering.startIndex === undefined ||
+            (key.startIndex !== undefined && covering.startIndex <= key.startIndex)));
+};

package/dist/domain/javascript/javascriptSemanticQuery.js

@@ -1,4 +1,3 @@
-import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
 import { isJavaScriptSemanticOwnershipRelation as ownershipRelation } from "./javascriptSemanticQueryRelations.js";
 import { javaScriptSemanticQueryInputSchema, javaScriptSemanticQueryResultSchema, } from "./javascriptSemanticQuerySchemas.js";
 import { assessJavaScriptSemanticQuery } from "./javascriptSemanticQueryAssessment.js";
@@ -8,13 +7,11 @@ export const queryJavaScriptSemanticGraph = (graph, rawInput) => {
     const input = javaScriptSemanticQueryInputSchema.parse(rawInput);
     const queryId = queryIdentifier(graph, input);
     const seeds = resolveSeeds(graph, input);
-    const admission = admitSeeds(graph, seeds);
-    const retainedSeeds = admission.nodeIds;
+    const nodes = new Map(graph.nodes.map((node) => [node.node_id, node]));
     const adjacency = buildAdjacency(graph.relations, input);
-    const traversal = traverse(graph, retainedSeeds, adjacency);
+    const traversal = traverse(nodes, seeds, adjacency);
     const result = createQueryResult(graph, traversal);
-    const allRelevantUnknowns = relevantUnknownFrontiers(graph, traversal.nodeIds, input);
-    const relevantUnknowns = allRelevantUnknowns;
+    const relevantUnknowns = relevantUnknownFrontiers(graph, traversal.nodeIds, input);
     const candidateRelations = relevantCandidateRelationCount(graph, traversal.nodeIds, input);
     const expectedMatches = expectedMatchesFor(result.retainedNodes, result.retainedRelations, input);
     const retainedContextIds = new Set([
@@ -36,7 +33,7 @@ export const queryJavaScriptSemanticGraph = (graph, rawInput) => {
         seed: input.seed,
         direction: input.direction,
         status: assessment.status,
-        seed_node_ids: retainedSeeds,
+        seed_node_ids: seeds,
         evidence_contexts: graph.evidence_contexts.filter(({ context_id }) => retainedContextIds.has(context_id)),
         nodes: result.retainedNodes,
         relations: result.retainedRelations,
@@ -48,7 +45,7 @@ export const queryJavaScriptSemanticGraph = (graph, rawInput) => {
             traversed_relations: traversal.relationIds.size,
             traversed_functions: traversal.functionIds.size,
             traversed_modules: traversal.modules.size,
-            relevant_unknowns: allRelevantUnknowns.length,
+            relevant_unknowns: relevantUnknowns.length,
         },
         coverage: assessment.coverage,
         limitations: assessment.limitations,
@@ -59,17 +56,6 @@ const createQueryResult = (graph, traversal) => {
     const retainedRelations = graph.relations.filter(({ relation_id }) => traversal.relationIds.has(relation_id));
     return { retainedNodes, retainedRelations };
 };
-const admitSeeds = (graph, seeds) => {
-    const nodes = new Map(graph.nodes.map((node) => [node.node_id, node]));
-    const retained = [];
-    for (const nodeId of seeds) {
-        const node = nodes.get(nodeId);
-        if (node === undefined)
-            continue;
-        retained.push(nodeId);
-    }
-    return { nodeIds: retained };
-};
 const buildAdjacency = (relations, input) => {
     const adjacency = new Map();
     const allowed = input.allowed_relations === undefined
@@ -83,8 +69,6 @@ const buildAdjacency = (relations, input) => {
             continue;
         addDirectedEntries(adjacency, relation, input.direction);
     }
-    for (const entries of adjacency.values())
-        entries.sort((left, right) => compareUnicodeCodePoints(`${left.relation.relation_id}\0${left.nextNodeId}`, `${right.relation.relation_id}\0${right.nextNodeId}`));
     return adjacency;
 };
 const addDirectedEntries = (adjacency, relation, direction) => {
@@ -110,8 +94,7 @@ const addEntry = (adjacency, from, nextNodeId, relation) => {
     entries.push({ relation, nextNodeId });
     adjacency.set(from, entries);
 };
-const traverse = (graph, seeds, adjacency) => {
-    const nodes = new Map(graph.nodes.map((node) => [node.node_id, node]));
+const traverse = (nodes, seeds, adjacency) => {
     const nodeIds = new Set(seeds);
     const relationIds = new Set();
     const functionIds = new Set();
@@ -159,12 +142,27 @@ const relevantUnknownFrontiers = (graph, nodeIds, input) => {
             unknown.relation_kinds.some((relation) => allowed.has(relation))));
 };
 const relevantCandidateRelationCount = (graph, nodeIds, input) => {
-    const adjacency = buildAdjacency(graph.relations.filter(({ resolution }) => resolution === "candidate"), { ...input, include_ambiguous_dynamic_edges: true });
-    const relevant = new Set();
-    for (const nodeId of nodeIds)
-        for (const { relation } of adjacency.get(nodeId) ?? [])
-            relevant.add(relation.relation_id);
-    return relevant.size;
+    const allowed = input.allowed_relations === undefined
+        ? null
+        : new Set(input.allowed_relations);
+    let relevant = 0;
+    for (const relation of graph.relations) {
+        if (relation.resolution !== "candidate" ||
+            (allowed !== null && !allowed.has(relation.relation)))
+            continue;
+        const sourceIsRelevant = nodeIds.has(relation.source_node_id);
+        const targetIsRelevant = nodeIds.has(relation.target_node_id);
+        if ((input.direction === "callers" &&
+            relation.relation === "calls" &&
+            targetIsRelevant) ||
+            (input.direction === "ownership" &&
+                ownershipRelation(relation.relation) &&
+                (sourceIsRelevant || targetIsRelevant)) ||
+            (input.direction === "backward-provenance" && targetIsRelevant) ||
+            (input.direction === "forward-influence" && sourceIsRelevant))
+            relevant += 1;
+    }
+    return relevant;
 };
 const expectedMatchesFor = (nodes, relations, input) => {
     if (input.expected === null)

package/dist/domain/javascript/javascriptSemanticQueryIdentity.js

@@ -51,9 +51,7 @@ const seedMatches = (node, input, fingerprintFunctions) => {
     if (seed.kind === "function")
         return fingerprintFunctions.has(node.node_id);
     if (seed.kind === "literal")
-        return (node.kind === "literal" &&
-            canonicalJavaScriptSemanticQueryJson(node.properties.value) ===
-                canonicalJavaScriptSemanticQueryJson(seed.value));
+        return node.kind === "literal" && node.properties.value === seed.value;
     if (seed.kind === "property")
         return node.kind === "property-slot" && node.properties.name === seed.name;
     if (seed.kind === "endpoint")

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

@@ -7,7 +7,8 @@ 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 { 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);
@@ -43,7 +44,14 @@ 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));
@@ -75,27 +83,9 @@ 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 directReturnExpressions = (callable) => semanticCallableResultExpressions(callable)
+    .filter(({ kind }) => kind === "return")
+    .map(({ node, site }) => ({ node, location: range(site) }));
 const callableIdsForBinding = (binding, state, admitted, seen) => {
     // A single initializer does not prove an assignment executes or replace
     // the unknown incoming value of a parameter/catch binding.

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,6 +42,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