rea-agents 2.1.0 → 2.3.0

package/dist/domain/javascriptRuntimeReconciliationParsing.js

@@ -22,16 +22,16 @@ export const digestCanonical = (value) => {
 };
 const parseStaticLayer = (layer) => {
     const evidence = parseEvidence(layer.analysis);
+    const result = javascriptApplicationAnalysisResultSchema.parse(evidence.normalized_result);
     assertEvidenceIdentity(evidence, {
         operation: "analyze_javascript_application",
-        predicate: "rea.javascript-application-analysis/v1",
+        predicate: `rea.javascript-application-analysis/v${String(result.schema_version)}`,
         providerId: "rea-javascript-application",
         providerName: "REA JavaScript application analyzer",
         providerVersion: "1",
         authority: "shipped-artifact",
         confidence: "derived",
     });
-    const result = javascriptApplicationAnalysisResultSchema.parse(evidence.normalized_result);
     if (evidence.subject === null ||
         evidence.subject.digest.sha256 !== result.root_artifact_sha256 ||
         evidence.subject.format !== result.format ||

package/dist/domain/javascriptSemanticAnalysis.js

@@ -2,8 +2,10 @@ import { parse } from "@babel/parser";
 import * as t from "@babel/types";
 import { DEFAULT_JAVASCRIPT_SEMANTIC_LIMITS, failedJavaScriptSemanticIr, } from "./javascriptSemanticIr.js";
 import { collectSemanticModuleLink, collectSemanticCallable, collectSemanticReferences, immutableSemanticBindings, immutableSemanticScopes, reachSemanticLimit, semanticModuleOrigin, semanticStaticPropertyName, } from "./javascriptSemanticProjection.js";
-import { currentSemanticScope, semanticScopeId, } from "./javascriptSemanticState.js";
+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 { compareCodePoints, propertyName, range, } from "./javascriptStaticAnalysisHelpers.js";
 /** Recover bounded lexical bindings, aliases, constants, and module links. */
 export const analyzeJavaScriptSemantics = (source, inputLimits = {}) => {
@@ -23,14 +25,19 @@ export const analyzeJavaScriptSemantics = (source, inputLimits = {}) => {
     collectDefinitions(file.program, state);
     const references = collectSemanticReferences(file.program, state);
     const parserPartial = file.errors.length > 0;
+    const bindings = immutableSemanticBindings(state);
+    const callables = collectSemanticReturns(file.program, state, parserPartial);
+    const moduleLinks = resolveSemanticModuleCallables(state, callables);
+    const calls = collectJavaScriptSemanticCalls(file.program, state, callables);
     return {
         schema: "JavaScriptSemanticIR",
-        schemaVersion: 1,
+        schemaVersion: 3,
         scopes: immutableSemanticScopes(state),
-        bindings: immutableSemanticBindings(state),
-        callables: [...state.callables],
+        bindings,
+        callables,
         references,
-        moduleLinks: [...state.moduleLinks],
+        moduleLinks,
+        ...calls,
         coverage: {
             status: state.limitsReached.size > 0
                 ? "truncated"
@@ -50,6 +57,8 @@ export const analyzeJavaScriptSemantics = (source, inputLimits = {}) => {
                 ? []
                 : ["Semantic recovery stopped retaining facts at explicit limits."]),
             "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.",
             "Cross-function mutation and dynamic property resolution remain unknown.",
         ],
     };
@@ -70,6 +79,7 @@ const createState = (program, limits) => {
         scopeByNode: new WeakMap([[program, root]]),
         bindingsById: new Map(),
         callables: [],
+        callableNodesById: new Map(),
         moduleLinks: [],
         limitsReached: new Set(),
         omittedCount: 0,
@@ -136,7 +146,7 @@ const bindInnerDeclaration = (node, parent, scope, state) => {
         bindPattern({
             pattern: node.id,
             initializer: node.init ?? null,
-            scope: variableScope(scope, parent, state),
+            scope: semanticVariableScope(scope, parent, state),
             state,
             mutable: parent !== null && t.isVariableDeclaration(parent)
                 ? parent.kind !== "const"
@@ -348,39 +358,10 @@ const createBinding = (scope, name, kind, mutable) => ({
     directOrigins: [],
 });
 const addAssignment = (identifier, initializer, scope, state) => {
-    const binding = resolveFromScope(scope, identifier.name, state);
+    const binding = resolveSemanticBindingFromScope(scope, identifier.name, state);
     if (binding === undefined)
         return;
     binding.mutable = true;
     binding.definitions.push({ kind: "assignment", location: range(identifier) });
     binding.initializers.push({ node: initializer, projection: [] });
 };
-const resolveFromScope = (scope, name, state) => {
-    let candidate = scope;
-    while (candidate !== undefined) {
-        const binding = candidate.bindings.get(name);
-        if (binding !== undefined)
-            return binding;
-        if (!candidate.bindingsComplete)
-            return undefined;
-        candidate =
-            candidate.parentScopeId === null
-                ? undefined
-                : state.scopesById.get(candidate.parentScopeId);
-    }
-    return undefined;
-};
-const variableScope = (scope, parent, state) => {
-    if (!(parent !== null && t.isVariableDeclaration(parent, { kind: "var" })))
-        return scope;
-    let candidate = scope;
-    while (candidate.kind === "block" || candidate.kind === "catch") {
-        const outer = candidate.parentScopeId === null
-            ? undefined
-            : state.scopesById.get(candidate.parentScopeId);
-        if (outer === undefined)
-            break;
-        candidate = outer;
-    }
-    return candidate;
-};

package/dist/domain/javascriptSemanticCallResolution.js

@@ -0,0 +1,129 @@
+import * as t from "@babel/types";
+import { reachSemanticLimit, semanticCallableIdForNode, } from "./javascriptSemanticProjection.js";
+import { resolveSemanticBindingState, } from "./javascriptSemanticState.js";
+import { compareCodePoints, range } from "./javascriptStaticAnalysisHelpers.js";
+/** Resolve bounded local callable candidates without following dynamic properties. */
+export const resolveLocalCallables = (input) => resolveCallables(input.node, {
+    state: input.state,
+    callableById: input.callableById,
+    seenBindings: input.seenBindings,
+    depth: input.depth,
+    bindingCache: input.bindingCache,
+});
+const resolveCallables = (node, context) => {
+    if (context.depth >= context.state.limits.maxValueDepth) {
+        reachSemanticLimit(context.state, "maxValueDepth");
+        return {
+            callableIds: [],
+            complete: false,
+            reason: "Call target depth limit reached.",
+        };
+    }
+    const direct = semanticCallableIdForNode(node);
+    if (direct !== null && context.callableById.has(direct))
+        return {
+            callableIds: [direct],
+            complete: true,
+            reason: "Direct local callable.",
+        };
+    if (t.isIdentifier(node))
+        return resolveIdentifier(node, context);
+    if (t.isTSAsExpression(node) ||
+        t.isTSTypeAssertion(node) ||
+        t.isTSNonNullExpression(node))
+        return resolveCallables(node.expression, nestedContext(context));
+    if (t.isConditionalExpression(node) || t.isLogicalExpression(node))
+        return resolveAlternatives(t.isConditionalExpression(node) ? node.consequent : node.left, t.isConditionalExpression(node) ? node.alternate : node.right, context);
+    return {
+        callableIds: [],
+        complete: false,
+        reason: `Unsupported ${node.type} call target.`,
+    };
+};
+const resolveIdentifier = (node, context) => {
+    const binding = resolveSemanticBindingState(context.state, node, node.name);
+    return binding === undefined
+        ? {
+            callableIds: [],
+            complete: false,
+            reason: `Unresolved call target ${node.name}.`,
+        }
+        : resolveBindingCallables(binding, nestedContext(context));
+};
+const resolveAlternatives = (left, right, context) => {
+    const candidates = [left, right].map((candidate) => resolveCallables(candidate, nestedContext(context)));
+    return {
+        callableIds: uniqueCallableIds(candidates.flatMap(({ callableIds }) => callableIds)),
+        complete: candidates.every(({ complete }) => complete),
+        reason: "Conditional or logical call target has multiple candidates.",
+    };
+};
+const resolveBindingCallables = (binding, context) => {
+    const cached = context.bindingCache.get(binding.bindingId);
+    if (cached !== undefined)
+        return cached;
+    if (context.seenBindings.has(binding.bindingId))
+        return {
+            callableIds: [],
+            complete: false,
+            reason: `Call target alias cycle at ${binding.name}.`,
+        };
+    if (binding.initializers.length === 0)
+        return missingBindingInitializer(binding);
+    const candidateContext = {
+        ...nestedContext(context),
+        seenBindings: new Set([...context.seenBindings, binding.bindingId]),
+    };
+    const candidates = binding.initializers.map(({ node, projection }) => projection.length === 0
+        ? resolveCallables(node, candidateContext)
+        : {
+            callableIds: [],
+            complete: false,
+            reason: `Projected call target ${binding.name} is unresolved.`,
+        });
+    const callableIds = uniqueCallableIds(candidates.flatMap((candidate) => candidate.callableIds));
+    const resolution = {
+        callableIds,
+        complete: candidates.every(({ complete }) => complete),
+        reason: callableIds.length === 1 && candidates.every(({ complete }) => complete)
+            ? "Unique local callable target."
+            : `Call target ${binding.name} has ambiguous or unsupported assignments.`,
+    };
+    if (resolution.complete)
+        context.bindingCache.set(binding.bindingId, resolution);
+    return resolution;
+};
+const missingBindingInitializer = (binding) => ({
+    callableIds: [],
+    complete: false,
+    reason: binding.kind === "import"
+        ? `Call target ${binding.name} is imported from outside this source.`
+        : `Call target ${binding.name} has no local initializer.`,
+});
+/** Find all bindings introduced by one positional parameter pattern. */
+export const parameterBindings = (callable, index, state) => {
+    if (callable.bodyScopeId === null)
+        return [];
+    const scope = state.scopesById.get(callable.bodyScopeId);
+    if (scope === undefined)
+        return [];
+    return [...scope.bindings.values()]
+        .filter((binding) => binding.kind === "parameter" &&
+        binding.definitions.some(({ kind, location }) => kind === "parameter" &&
+            parameterIndex(callable, location, state) === index))
+        .sort((left, right) => compareCodePoints(left.bindingId, right.bindingId));
+};
+const parameterIndex = (callable, location, state) => {
+    const node = state.callableNodesById.get(callable.callableId);
+    if (!t.isFunction(node))
+        return -1;
+    return node.params.findIndex((parameter) => rangeContains(range(parameter), location));
+};
+const rangeContains = (outer, inner) => (outer.start.line < inner.start.line ||
+    (outer.start.line === inner.start.line &&
+        outer.start.column <= inner.start.column)) &&
+    (outer.end.line > inner.end.line ||
+        (outer.end.line === inner.end.line &&
+            outer.end.column >= inner.end.column));
+const nestedContext = (context) => ({ ...context, depth: context.depth + 1 });
+const uniqueCallableIds = (values) => [...new Set(values)].sort(compareCodePoints);

package/dist/domain/javascriptSemanticCalls.js

@@ -0,0 +1,269 @@
+import * as t from "@babel/types";
+import { reachSemanticLimit, semanticCallableIdForNode, semanticReferenceRole, semanticStaticPropertyName, } from "./javascriptSemanticProjection.js";
+import { resolveSemanticBindingState, } from "./javascriptSemanticState.js";
+import { parameterBindings, resolveLocalCallables, } from "./javascriptSemanticCallResolution.js";
+import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
+import { range } from "./javascriptStaticAnalysisHelpers.js";
+/** Recover bounded direct-call and lexical-capture candidates from inert syntax. */
+export const collectJavaScriptSemanticCalls = (program, state, callables) => {
+    const output = {
+        callSites: [],
+        argumentFlows: [],
+        callReturnFlows: [],
+        callResultFlows: [],
+        closureCaptures: [],
+        frontiers: [],
+        retainedArguments: 0,
+    };
+    const callableById = new Map(callables.map((callable) => [callable.callableId, callable]));
+    const context = {
+        state,
+        callableById,
+        output,
+        bindingResolutionCache: new Map(),
+        parameterBindingCache: new Map(),
+    };
+    const callableStack = [];
+    traverseJavaScriptAst(program, {
+        enter: (node, parent) => {
+            const callableId = semanticCallableIdForNode(node);
+            const callable = callableId === null ? undefined : callableById.get(callableId);
+            if (callable !== undefined)
+                callableStack.push(callable);
+            const owner = enclosingFunction(callableStack);
+            collectCapture(node, parent, owner, context);
+            collectDynamicProperty(node, owner, state, output);
+            if (t.isCallExpression(node) ||
+                t.isOptionalCallExpression(node) ||
+                t.isNewExpression(node))
+                collectCallSite(node, parent, owner, context);
+        },
+        exit: (node) => {
+            const callableId = semanticCallableIdForNode(node);
+            if (callableId !== null &&
+                callableStack.at(-1)?.callableId === callableId)
+                callableStack.pop();
+        },
+    });
+    return {
+        callSites: output.callSites,
+        argumentFlows: output.argumentFlows,
+        callReturnFlows: output.callReturnFlows,
+        callResultFlows: output.callResultFlows,
+        closureCaptures: output.closureCaptures,
+        frontiers: output.frontiers,
+    };
+};
+const collectCallSite = (node, parent, owner, context) => {
+    const { state, callableById, output } = context;
+    if (output.callSites.length >= state.limits.maxCallSites) {
+        reachSemanticLimit(state, "maxCallSites");
+        return;
+    }
+    const resolution = resolveLocalCallables({
+        node: node.callee,
+        state,
+        callableById,
+        seenBindings: new Set(),
+        depth: 0,
+        bindingCache: context.bindingResolutionCache,
+    });
+    const callSiteId = semanticCallSiteId(node);
+    const argumentsValue = retainedArguments(node.arguments, state, output);
+    const site = {
+        callSiteId,
+        kind: t.isNewExpression(node) ? "construct" : "call",
+        callerCallableId: owner?.callableId ?? null,
+        location: range(node),
+        calleeLocation: range(node.callee),
+        resolution: resolution.callableIds.length === 1 && resolution.complete
+            ? "exact"
+            : resolution.callableIds.length > 0
+                ? "ambiguous"
+                : "unresolved",
+        calleeCallableIds: resolution.callableIds,
+        arguments: argumentsValue,
+    };
+    output.callSites.push(site);
+    collectCallResultFlow(site, node, parent, context);
+    if (site.resolution !== "exact")
+        addFrontier({
+            kind: "dynamic-call",
+            callableId: owner?.callableId ?? null,
+            location: range(node.callee),
+            reason: resolution.reason,
+        }, state, output);
+    collectArgumentFlows(site, node, context);
+    if (site.kind === "call")
+        collectReturnFlows(site, callableById, state, output);
+};
+const collectCallResultFlow = (site, node, parent, context) => {
+    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;
+    if (identifier === null)
+        return;
+    const binding = resolveSemanticBindingState(context.state, identifier, identifier.name);
+    const identifierRange = range(identifier);
+    const definition = binding?.definitions.find(({ location }) => location.start.line === identifierRange.start.line &&
+        location.start.column === identifierRange.start.column &&
+        location.end.line === identifierRange.end.line &&
+        location.end.column === identifierRange.end.column);
+    if (binding === undefined || definition === undefined)
+        return;
+    context.output.callResultFlows.push({
+        callSiteId: site.callSiteId,
+        bindingId: binding.bindingId,
+        definitionLocation: definition.location,
+    });
+};
+const retainedArguments = (nodes, state, output) => {
+    const retained = [];
+    for (const [index, node] of nodes.entries()) {
+        if (output.retainedArguments >= state.limits.maxCallArguments) {
+            reachSemanticLimit(state, "maxCallArguments");
+            break;
+        }
+        output.retainedArguments += 1;
+        retained.push({
+            index,
+            location: range(node),
+            spread: t.isSpreadElement(node),
+        });
+    }
+    return retained;
+};
+const collectArgumentFlows = (site, node, context) => {
+    const { state, callableById, output } = context;
+    const retainedIndexes = new Set(site.arguments.map(({ index }) => index));
+    let positionIsExact = true;
+    for (const [index, argument] of node.arguments.entries()) {
+        if (t.isSpreadElement(argument)) {
+            positionIsExact = false;
+            continue;
+        }
+        if (!positionIsExact ||
+            !retainedIndexes.has(index) ||
+            !t.isExpression(argument))
+            continue;
+        for (const callableId of site.calleeCallableIds) {
+            const callable = callableById.get(callableId);
+            if (callable === undefined)
+                continue;
+            for (const parameter of cachedParameterBindings(callable, index, context)) {
+                if (output.argumentFlows.length >= state.limits.maxArgumentFlows) {
+                    reachSemanticLimit(state, "maxArgumentFlows");
+                    return;
+                }
+                const definition = parameter.definitions.find(({ kind }) => kind === "parameter");
+                if (definition === undefined)
+                    continue;
+                output.argumentFlows.push({
+                    callSiteId: site.callSiteId,
+                    argumentIndex: index,
+                    argumentLocation: range(argument),
+                    callableId,
+                    parameterBindingId: parameter.bindingId,
+                    parameterLocation: definition.location,
+                });
+            }
+        }
+    }
+};
+const cachedParameterBindings = (callable, index, context) => {
+    const key = `${callable.callableId}:${String(index)}`;
+    const cached = context.parameterBindingCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const bindings = parameterBindings(callable, index, context.state);
+    context.parameterBindingCache.set(key, bindings);
+    return bindings;
+};
+const collectReturnFlows = (site, callableById, state, output) => {
+    for (const callableId of site.calleeCallableIds) {
+        const callable = callableById.get(callableId);
+        if (callable === undefined)
+            continue;
+        for (const returnSite of callable.returnSites) {
+            if (output.callReturnFlows.length >= state.limits.maxCallReturnFlows) {
+                reachSemanticLimit(state, "maxCallReturnFlows");
+                return;
+            }
+            output.callReturnFlows.push({
+                callSiteId: site.callSiteId,
+                callableId,
+                returnSiteId: returnSite.returnSiteId,
+                returnLocation: returnSite.location,
+            });
+        }
+    }
+};
+const collectCapture = (node, parent, owner, context) => {
+    const { state, output } = context;
+    if (!t.isIdentifier(node) ||
+        parent === null ||
+        owner === undefined ||
+        owner.bodyScopeId === null)
+        return;
+    if (semanticReferenceRole(node, parent) === null)
+        return;
+    const binding = resolveSemanticBindingState(state, node, node.name);
+    if (binding === undefined ||
+        bindingIsWithinCallable(binding, owner.bodyScopeId, state))
+        return;
+    if (output.closureCaptures.length >= state.limits.maxClosureCaptures) {
+        reachSemanticLimit(state, "maxClosureCaptures");
+        return;
+    }
+    output.closureCaptures.push({
+        callableId: owner.callableId,
+        bindingId: binding.bindingId,
+        referenceLocation: range(node),
+    });
+};
+const collectDynamicProperty = (node, owner, state, output) => {
+    if ((t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) &&
+        semanticStaticPropertyName(node.property, node.computed) === "")
+        addFrontier({
+            kind: "dynamic-property",
+            callableId: owner?.callableId ?? null,
+            location: range(node.property),
+            reason: "Computed member property is not a static string or number.",
+        }, state, output);
+    else if ((t.isObjectProperty(node) || t.isObjectMethod(node)) &&
+        node.computed &&
+        semanticStaticPropertyName(node.key, true) === "")
+        addFrontier({
+            kind: "dynamic-property",
+            callableId: owner?.callableId ?? null,
+            location: range(node.key),
+            reason: "Computed object property is not a static string or number.",
+        }, state, output);
+};
+const addFrontier = (frontier, state, output) => {
+    if (output.frontiers.length >= state.limits.maxFrontiers) {
+        reachSemanticLimit(state, "maxFrontiers");
+        return;
+    }
+    output.frontiers.push(frontier);
+};
+const bindingIsWithinCallable = (binding, bodyScopeId, state) => {
+    let scope = state.scopesById.get(binding.scopeId);
+    while (scope !== undefined) {
+        if (scope.scopeId === bodyScopeId)
+            return true;
+        scope =
+            scope.parentScopeId === null
+                ? undefined
+                : state.scopesById.get(scope.parentScopeId);
+    }
+    return false;
+};
+const enclosingFunction = (stack) => stack.findLast(({ kind }) => kind !== "class");
+const semanticCallSiteId = (node) => `call:${t.isNewExpression(node) ? "construct" : "call"}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`;