rea-agents 2.4.0 → 2.5.0

package/dist/domain/javascriptRuntimeReconciliationResult.js

@@ -45,9 +45,9 @@ const captureSummaries = (captures, runtime) => captures.map((capture) => {
         kind: capture.kind,
         target_node_id: targetNode.node_id,
         target_key: capture.inspection.target.target_id,
-        target_location: capture.kind === "browser"
-            ? capture.inspection.target.url.slice(0, 4_096)
-            : capture.inspection.target.file_path.slice(0, 4_096),
+        target_location: ("url" in capture.inspection.target
+            ? capture.inspection.target.url
+            : capture.inspection.target.file_path).slice(0, 4_096),
         frames: capture.inspection.frames.length,
         scripts: capture.inspection.scripts.items.length,
         workers: capture.inspection.workers.length,

package/dist/domain/javascriptRuntimeReconciliationRuntime.js

@@ -197,7 +197,7 @@ const runtimeEvidence = (capture, input) => ({
         name: capture.evidence.provider.id,
         version: capture.evidence.provider.version ??
             (capture.kind === "browser" ? "2" : "1"),
-        operation: capture.kind === "browser" ? "inspect_web_page" : "inspect_electron_page",
+        operation: capture.evidence.operation,
         executable_sha256: null,
     },
     coverage: runtimeSectionCoverage(capture, input.section),
@@ -260,7 +260,7 @@ const runtimeRelationshipEvidence = (capture, entity) => ({
         name: capture.evidence.provider.id,
         version: capture.evidence.provider.version ??
             (capture.kind === "browser" ? "2" : "1"),
-        operation: capture.kind === "browser" ? "inspect_web_page" : "inspect_electron_page",
+        operation: capture.evidence.operation,
         executable_sha256: null,
     },
     coverage: runtimeSectionCoverage(capture, entity.section),

package/dist/domain/javascriptRuntimeReconciliationSchemas.js

@@ -133,7 +133,7 @@ const layerSummarySchema = z.strictObject({
 const captureSummarySchema = z.strictObject({
     evidence_id: evidenceIdSchema,
     capture_sha256: digestSchema,
-    kind: z.enum(["browser", "electron"]),
+    kind: z.enum(["browser", "electron", "v8-inspector"]),
     target_node_id: nodeIdSchema,
     target_key: boundedTextSchema,
     target_location: boundedTextSchema,

package/dist/domain/javascriptSemanticAnalysis.js

@@ -5,7 +5,7 @@ import { collectSemanticModuleLink, collectSemanticCallable, collectSemanticRefe
 import { currentSemanticScope, resolveSemanticBindingFromScope, semanticScopeId, semanticVariableScope, } from "./javascriptSemanticState.js";
 import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
 import { collectSemanticReturns, resolveSemanticModuleCallables, } from "./javascriptSemanticReturns.js";
-import { collectJavaScriptSemanticCalls } from "./javascriptSemanticCalls.js";
+import { collectJavaScriptDerivedSemantics } from "./javascriptSemanticDerivedAnalysis.js";
 import { compareCodePoints, propertyName, range, } from "./javascriptStaticAnalysisHelpers.js";
 /** Recover bounded lexical bindings, aliases, constants, and module links. */
 export const analyzeJavaScriptSemantics = (source, inputLimits = {}) => {
@@ -28,16 +28,16 @@ export const analyzeJavaScriptSemantics = (source, inputLimits = {}) => {
     const bindings = immutableSemanticBindings(state);
     const callables = collectSemanticReturns(file.program, state, parserPartial);
     const moduleLinks = resolveSemanticModuleCallables(state, callables);
-    const calls = collectJavaScriptSemanticCalls(file.program, state, callables);
+    const derived = collectJavaScriptDerivedSemantics(file.program, state, callables, parserPartial);
     return {
         schema: "JavaScriptSemanticIR",
-        schemaVersion: 3,
+        schemaVersion: 4,
         scopes: immutableSemanticScopes(state),
         bindings,
         callables,
         references,
         moduleLinks,
-        ...calls,
+        ...derived,
         coverage: {
             status: state.limitsReached.size > 0
                 ? "truncated"
@@ -59,6 +59,7 @@ export const analyzeJavaScriptSemantics = (source, inputLimits = {}) => {
             "Values and aliases were recovered from inert syntax only; no JavaScript was executed.",
             "Return sites include only direct callable returns; nested callable returns remain separate.",
             "Local call, argument, return, and closure relations are static candidates and do not prove runtime invocation.",
+            "Promise ownership covers explicit unshadowed Promise construction, static factories, aggregation, chaining, and await syntax only.",
             "Cross-function mutation and dynamic property resolution remain unknown.",
         ],
     };

package/dist/domain/javascriptSemanticAsyncEffects.js

@@ -0,0 +1,253 @@
+import * as t from "@babel/types";
+import { reachSemanticLimit, semanticCallableIdForNode, semanticStaticPropertyName, } from "./javascriptSemanticProjection.js";
+import { resolveSemanticBindingState, semanticResolutionBlocked, } from "./javascriptSemanticState.js";
+import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
+import { range } from "./javascriptStaticAnalysisHelpers.js";
+const EVENT_REGISTER_METHODS = [
+    "on",
+    "once",
+    "addListener",
+    "prependListener",
+    "prependOnceListener",
+];
+const EVENT_REMOVE_METHODS = [
+    "off",
+    "removeListener",
+    "removeAllListeners",
+];
+const EVENT_METHODS = [
+    ...EVENT_REGISTER_METHODS,
+    ...EVENT_REMOVE_METHODS,
+    "emit",
+];
+const TIMER_SCHEDULE_METHODS = [
+    "setTimeout",
+    "setInterval",
+    "setImmediate",
+];
+const TIMER_CANCEL_METHODS = [
+    "clearTimeout",
+    "clearInterval",
+    "clearImmediate",
+];
+/** Recover explicit EventEmitter and Node timer candidates from inert syntax. */
+export const collectJavaScriptSemanticAsyncEffects = (program, state, callables) => {
+    const events = [];
+    const timers = [];
+    const callableIds = new Set(callables.map(({ callableId }) => callableId));
+    const callableStack = [];
+    traverseJavaScriptAst(program, {
+        enter: (node, parent) => {
+            const callableId = semanticCallableIdForNode(node);
+            if (callableId !== null && callableIds.has(callableId))
+                callableStack.push(callableId);
+            if (!t.isCallExpression(node) && !t.isOptionalCallExpression(node))
+                return;
+            const ownerCallableId = callableStack.at(-1) ?? null;
+            collectEvent(node, ownerCallableId, state, events);
+            collectTimer({ node, parent, ownerCallableId, state, output: timers });
+        },
+        exit: (node) => {
+            const callableId = semanticCallableIdForNode(node);
+            if (callableId !== null && callableStack.at(-1) === callableId)
+                callableStack.pop();
+        },
+    });
+    return {
+        eventOperations: events,
+        timerOperations: resolveTimers(timers),
+    };
+};
+const collectEvent = (node, ownerCallableId, state, output) => {
+    const member = memberCallee(node);
+    if (member === null)
+        return;
+    const method = EVENT_METHODS.find((candidate) => candidate ===
+        semanticStaticPropertyName(member.property, member.computed));
+    if (method === undefined)
+        return;
+    const kind = eventKind(method);
+    if (output.length >= state.limits.maxEventOperations) {
+        reachSemanticLimit(state, "maxEventOperations");
+        return;
+    }
+    const eventArgument = node.arguments[0];
+    const listenerArgument = node.arguments[1];
+    const emitter = emitterIdentity(member.object, state);
+    const eventName = literalString(eventArgument);
+    output.push({
+        eventId: `event:${kind}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
+        kind,
+        method,
+        location: range(node),
+        ownerCallableId,
+        emitterKey: emitter.key,
+        emitterBindingId: emitter.bindingId,
+        eventName,
+        listenerBindingId: bindingId(listenerArgument, state),
+        listenerLocation: t.isNode(listenerArgument)
+            ? range(listenerArgument)
+            : null,
+        resolution: eventName === null
+            ? "unresolved"
+            : emitter.complete
+                ? "complete"
+                : "partial",
+    });
+};
+const eventKind = (method) => {
+    if (EVENT_REGISTER_METHODS.some((candidate) => candidate === method))
+        return "register";
+    if (EVENT_REMOVE_METHODS.some((candidate) => candidate === method))
+        return "remove";
+    return "dispatch";
+};
+const emitterIdentity = (node, state) => {
+    if (t.isIdentifier(node)) {
+        const binding = resolveSemanticBindingState(state, node, node.name);
+        if (binding !== undefined)
+            return {
+                key: `binding:${binding.bindingId}`,
+                bindingId: binding.bindingId,
+                complete: true,
+            };
+        return {
+            key: `global:${node.name}`,
+            bindingId: null,
+            complete: !semanticResolutionBlocked(state, node, node.name),
+        };
+    }
+    if (t.isThisExpression(node))
+        return { key: "this", bindingId: null, complete: true };
+    return {
+        key: `expression:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
+        bindingId: null,
+        complete: false,
+    };
+};
+const collectTimer = (input) => {
+    const { node, parent, ownerCallableId, state, output } = input;
+    const method = timerMethod(node.callee, state);
+    if (method === null)
+        return;
+    if (output.length >= state.limits.maxTimerOperations) {
+        reachSemanticLimit(state, "maxTimerOperations");
+        return;
+    }
+    const kind = TIMER_SCHEDULE_METHODS.some((candidate) => candidate === method)
+        ? "schedule"
+        : "cancel";
+    output.push({
+        node,
+        method,
+        kind,
+        ownerCallableId,
+        handleBindingId: kind === "schedule"
+            ? assignedBindingId(parent, node, state)
+            : bindingId(node.arguments[0], state),
+    });
+};
+const resolveTimers = (candidates) => {
+    const schedulesByBinding = new Map();
+    for (const candidate of candidates) {
+        if (candidate.kind !== "schedule" || candidate.handleBindingId === null)
+            continue;
+        const existing = schedulesByBinding.get(candidate.handleBindingId) ?? [];
+        existing.push(candidate);
+        schedulesByBinding.set(candidate.handleBindingId, existing);
+    }
+    return candidates.map((candidate) => {
+        const linked = candidate.kind === "cancel" && candidate.handleBindingId !== null
+            ? (schedulesByBinding.get(candidate.handleBindingId) ?? [])
+            : [];
+        return {
+            timerId: timerId(candidate),
+            kind: candidate.kind,
+            method: candidate.method,
+            location: range(candidate.node),
+            ownerCallableId: candidate.ownerCallableId,
+            handleBindingId: candidate.handleBindingId,
+            linkedTimerId: linked.length === 1 && linked[0] !== undefined
+                ? timerId(linked[0])
+                : null,
+            delayMilliseconds: timerDelay(candidate),
+            resolution: candidate.kind === "schedule"
+                ? "complete"
+                : linked.length === 1
+                    ? "complete"
+                    : linked.length > 1
+                        ? "partial"
+                        : "unresolved",
+        };
+    });
+};
+const timerMethod = (callee, state) => {
+    if (t.isIdentifier(callee)) {
+        const binding = resolveSemanticBindingState(state, callee, callee.name);
+        if (binding === undefined) {
+            const method = admittedTimerMethod(callee.name);
+            if (method === null)
+                return null;
+            return semanticResolutionBlocked(state, callee, callee.name)
+                ? 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;
+};
+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) && importedPath.length === 0) ?? false;
+const timerModule = (specifier) => specifier === "timers" || specifier === "node:timers";
+const assignedBindingId = (parent, node, state) => {
+    const identifier = t.isVariableDeclarator(parent) &&
+        parent.init === node &&
+        t.isIdentifier(parent.id)
+        ? parent.id
+        : t.isAssignmentExpression(parent) &&
+            parent.right === node &&
+            t.isIdentifier(parent.left)
+            ? parent.left
+            : null;
+    return identifier === null
+        ? null
+        : (resolveSemanticBindingState(state, identifier, identifier.name)
+            ?.bindingId ?? null);
+};
+const bindingId = (node, state) => t.isIdentifier(node)
+    ? (resolveSemanticBindingState(state, node, node.name)?.bindingId ?? null)
+    : null;
+const literalString = (node) => {
+    if (t.isStringLiteral(node))
+        return node.value;
+    if (t.isTemplateLiteral(node) && node.expressions.length === 0)
+        return node.quasis[0]?.value.cooked ?? node.quasis[0]?.value.raw ?? null;
+    return null;
+};
+const timerDelay = (candidate) => {
+    if (candidate.kind !== "schedule" || candidate.method === "setImmediate")
+        return null;
+    const delay = candidate.node.arguments[1];
+    return t.isNumericLiteral(delay) ? delay.value : null;
+};
+const timerId = (candidate) => `timer:${candidate.kind}:${String(candidate.node.start ?? -1)}:${String(candidate.node.end ?? -1)}`;
+const memberCallee = (node) => t.isMemberExpression(node.callee) || t.isOptionalMemberExpression(node.callee)
+    ? node.callee
+    : null;

package/dist/domain/javascriptSemanticChildProcesses.js

@@ -0,0 +1,237 @@
+import * as t from "@babel/types";
+import { reachSemanticLimit, semanticCallableIdForNode, semanticStaticPropertyName, } from "./javascriptSemanticProjection.js";
+import { resolveSemanticBindingState, } from "./javascriptSemanticState.js";
+import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
+import { compareCodePoints, propertyName, range, } from "./javascriptStaticAnalysisHelpers.js";
+const CHILD_PROCESS_METHODS = ["spawn", "exec", "execFile", "fork"];
+const CHILD_LISTENER_METHODS = ["on", "once", "addListener"];
+/** Recover explicit asynchronous node:child_process ownership candidates. */
+export const collectJavaScriptSemanticChildProcesses = (program, state, callables) => {
+    const candidates = collectSpawns(program, state, callables);
+    const childProcessSpawns = candidates.map((candidate) => immutableSpawn(candidate));
+    return {
+        childProcessSpawns,
+        childProcessInteractions: collectInteractions(program, state, callables, candidates),
+    };
+};
+const collectSpawns = (program, state, callables) => {
+    const output = [];
+    const admittedCallables = new Set(callables.map(({ callableId }) => callableId));
+    const callableStack = [];
+    traverseJavaScriptAst(program, {
+        enter: (node, parent) => {
+            const callableId = semanticCallableIdForNode(node);
+            if (callableId !== null && admittedCallables.has(callableId))
+                callableStack.push(callableId);
+            if (!t.isCallExpression(node) && !t.isOptionalCallExpression(node))
+                return;
+            const method = childProcessMethod(node.callee, state);
+            if (method === null)
+                return;
+            if (operationLimitReached(output.length, state))
+                return;
+            output.push({
+                node,
+                method,
+                ownerCallableId: callableStack.at(-1) ?? null,
+                resultBindingId: assignedBindingId(parent, node, state),
+            });
+        },
+        exit: (node) => popCallable(node, callableStack),
+    });
+    return output;
+};
+const immutableSpawn = (candidate) => {
+    const options = spawnOptions(candidate);
+    const command = literalString(candidate.node.arguments[0]);
+    return {
+        processId: spawnId(candidate),
+        method: candidate.method,
+        location: range(candidate.node),
+        ownerCallableId: candidate.ownerCallableId,
+        resultBindingId: candidate.resultBindingId,
+        command,
+        argvCount: spawnArgvCount(candidate),
+        environmentSupplied: objectHasProperty(options, "env"),
+        stdioMode: stdioMode(options),
+        resolution: command === null ? "partial" : "complete",
+    };
+};
+const collectInteractions = (program, state, callables, spawns) => {
+    const output = [];
+    const callableIds = new Set(callables.map(({ callableId }) => callableId));
+    const callableStack = [];
+    const spawnByNode = new WeakMap();
+    const spawnsByBinding = new Map();
+    for (const spawn of spawns) {
+        spawnByNode.set(spawn.node, spawn);
+        if (spawn.resultBindingId === null)
+            continue;
+        const existing = spawnsByBinding.get(spawn.resultBindingId) ?? [];
+        existing.push(spawn);
+        spawnsByBinding.set(spawn.resultBindingId, existing);
+    }
+    const context = {
+        state,
+        spawnByNode,
+        spawnsByBinding,
+    };
+    traverseJavaScriptAst(program, {
+        enter: (node) => {
+            const callableId = semanticCallableIdForNode(node);
+            if (callableId !== null && callableIds.has(callableId))
+                callableStack.push(callableId);
+            if (!t.isCallExpression(node) && !t.isOptionalCallExpression(node))
+                return;
+            const interaction = childInteraction(node, callableStack.at(-1) ?? null, context);
+            if (interaction === null)
+                return;
+            if (operationLimitReached(spawns.length + output.length, state))
+                return;
+            output.push(interaction);
+        },
+        exit: (node) => popCallable(node, callableStack),
+    });
+    return output;
+};
+const childInteraction = (node, ownerCallableId, context) => {
+    const { state, spawnByNode, spawnsByBinding } = context;
+    const member = memberCallee(node);
+    if (member === null)
+        return null;
+    const method = semanticStaticPropertyName(member.property, member.computed);
+    const binding = objectBinding(member.object, state);
+    const linked = resolveChildCandidates(member.object, binding, spawnByNode, spawnsByBinding);
+    if (linked.length === 0)
+        return null;
+    const classification = classifyInteraction(method, node.arguments[0]);
+    if (classification === null)
+        return null;
+    const { kind, interactionMethod, eventName } = classification;
+    const listener = node.arguments[1];
+    return {
+        interactionId: `child:${kind}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
+        kind,
+        method: interactionMethod,
+        location: range(node),
+        ownerCallableId,
+        processBindingId: binding?.bindingId ?? null,
+        linkedProcessIds: linked
+            .map((candidate) => spawnId(candidate))
+            .sort(compareCodePoints),
+        eventName: kind === "listener" ? eventName : null,
+        signalName: kind === "signal"
+            ? (literalString(node.arguments[0]) ?? "SIGTERM")
+            : null,
+        listenerLocation: kind === "listener" && t.isNode(listener) ? range(listener) : null,
+        resolution: linked.length === 1 ? "complete" : "partial",
+    };
+};
+const classifyInteraction = (method, argument) => {
+    if (method === "kill")
+        return { kind: "signal", interactionMethod: "kill", eventName: null };
+    const listenerMethod = CHILD_LISTENER_METHODS.find((candidate) => candidate === method);
+    const eventName = literalString(argument);
+    return listenerMethod !== undefined &&
+        (eventName === "exit" || eventName === "error")
+        ? { kind: "listener", interactionMethod: listenerMethod, eventName }
+        : null;
+};
+const childProcessMethod = (callee, state) => {
+    if (t.isIdentifier(callee)) {
+        const binding = resolveSemanticBindingState(state, callee, callee.name);
+        return binding === undefined ? null : methodFromBinding(binding);
+    }
+    if (!t.isMemberExpression(callee) && !t.isOptionalMemberExpression(callee))
+        return null;
+    const method = admittedChildMethod(semanticStaticPropertyName(callee.property, callee.computed));
+    if (method === null || !t.isIdentifier(callee.object))
+        return null;
+    const binding = resolveSemanticBindingState(state, callee.object, callee.object.name);
+    return childProcessNamespace(binding) ? method : null;
+};
+const methodFromBinding = (binding) => {
+    for (const { specifier, importedPath } of binding.directOrigins) {
+        if (!childProcessModule(specifier))
+            continue;
+        const method = admittedChildMethod(importedPath.at(-1) ?? "");
+        if (method !== null)
+            return method;
+    }
+    return null;
+};
+const admittedChildMethod = (value) => CHILD_PROCESS_METHODS.find((candidate) => candidate === value) ?? null;
+const childProcessNamespace = (binding) => binding?.directOrigins.some(({ specifier, importedPath }) => childProcessModule(specifier) && importedPath.length === 0) ?? false;
+const childProcessModule = (specifier) => specifier === "child_process" || specifier === "node:child_process";
+const resolveChildCandidates = (node, binding, spawnByNode, spawnsByBinding) => {
+    const direct = spawnByNode.get(node);
+    if (direct !== undefined)
+        return [direct];
+    return binding === undefined
+        ? []
+        : (spawnsByBinding.get(binding.bindingId) ?? []);
+};
+const spawnOptions = (candidate) => {
+    const index = candidate.method === "exec" ? 1 : 2;
+    const value = candidate.node.arguments[index];
+    return t.isObjectExpression(value) ? value : null;
+};
+const spawnArgvCount = (candidate) => {
+    if (candidate.method === "exec")
+        return null;
+    const args = candidate.node.arguments[1];
+    return t.isArrayExpression(args) ? args.elements.length : null;
+};
+const objectHasProperty = (object, name) => objectProperty(object, name) !== null;
+const stdioMode = (options) => {
+    const property = objectProperty(options, "stdio");
+    if (property === null || !t.isObjectProperty(property))
+        return "default";
+    if (t.isStringLiteral(property.value))
+        return property.value.value;
+    if (t.isArrayExpression(property.value))
+        return "array";
+    return "dynamic";
+};
+const objectProperty = (object, name) => object?.properties.find((property) => (t.isObjectMethod(property) || t.isObjectProperty(property)) &&
+    propertyName(property.key) === name) ?? null;
+const objectBinding = (node, state) => t.isIdentifier(node)
+    ? resolveSemanticBindingState(state, node, node.name)
+    : undefined;
+const assignedBindingId = (parent, node, state) => {
+    const identifier = t.isVariableDeclarator(parent) &&
+        parent.init === node &&
+        t.isIdentifier(parent.id)
+        ? parent.id
+        : t.isAssignmentExpression(parent) &&
+            parent.right === node &&
+            t.isIdentifier(parent.left)
+            ? parent.left
+            : null;
+    return identifier === null
+        ? null
+        : (resolveSemanticBindingState(state, identifier, identifier.name)
+            ?.bindingId ?? null);
+};
+const literalString = (node) => {
+    if (t.isStringLiteral(node))
+        return node.value;
+    if (t.isTemplateLiteral(node) && node.expressions.length === 0)
+        return node.quasis[0]?.value.cooked ?? node.quasis[0]?.value.raw ?? null;
+    return null;
+};
+const operationLimitReached = (retained, state) => {
+    if (retained < state.limits.maxChildProcessOperations)
+        return false;
+    reachSemanticLimit(state, "maxChildProcessOperations");
+    return true;
+};
+const popCallable = (node, stack) => {
+    const callableId = semanticCallableIdForNode(node);
+    if (callableId !== null && stack.at(-1) === callableId)
+        stack.pop();
+};
+const spawnId = (candidate) => `child:spawn:${String(candidate.node.start ?? -1)}:${String(candidate.node.end ?? -1)}`;
+const memberCallee = (node) => t.isMemberExpression(node.callee) || t.isOptionalMemberExpression(node.callee)
+    ? node.callee
+    : null;