rea-agents 2.2.0 → 2.3.0

package/dist/domain/javascriptExportShapeVariants.js

@@ -0,0 +1,272 @@
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+import { canonicalExportShapeValue, digestExportShapeValue, } from "./javascriptExportShapeComparisonIdentity.js";
+/** Pair variants only through reciprocal unique exact literal discriminants. */
+export const pairJavaScriptExportShapeVariants = (left, right) => {
+    const leftKeys = discriminantOccurrences(left);
+    const rightKeys = discriminantOccurrences(right);
+    const edges = new Map();
+    const leftTargets = new Map();
+    const rightTargets = new Map();
+    for (const [key, leftOccurrence] of leftKeys) {
+        const rightOccurrence = rightKeys.get(key);
+        if (leftOccurrence.indexes.length !== 1 ||
+            rightOccurrence?.indexes.length !== 1)
+            continue;
+        const leftIndex = leftOccurrence.indexes[0];
+        const rightIndex = rightOccurrence.indexes[0];
+        if (leftIndex === undefined || rightIndex === undefined)
+            continue;
+        const edgeKey = `${String(leftIndex)}:${String(rightIndex)}`;
+        edges.set(edgeKey, [
+            ...(edges.get(edgeKey) ?? []),
+            leftOccurrence.discriminant,
+        ]);
+        addTarget(leftTargets, leftIndex, rightIndex);
+        addTarget(rightTargets, rightIndex, leftIndex);
+    }
+    const pairs = reciprocalPairs(leftTargets, rightTargets, edges);
+    const pairedLeft = new Set(pairs.map(({ leftIndex }) => leftIndex));
+    const pairedRight = new Set(pairs.map(({ rightIndex }) => rightIndex));
+    return {
+        pairs,
+        unpairedLeft: indexesNotIn(left, pairedLeft),
+        unpairedRight: indexesNotIn(right, pairedRight),
+    };
+};
+/** Build bounded-ready field and unpaired-variant changes before caller slicing. */
+export const buildJavaScriptExportShapeChanges = (input) => {
+    if (input.leftSelection.selection.status !== "selected" ||
+        input.rightSelection.selection.status !== "selected")
+        return [selectionUnknownChange(input)];
+    if (input.leftShapes.length === 0 || input.rightShapes.length === 0)
+        return [emptyShapeUnknownChange(input)];
+    const paired = input.pairing.pairs.flatMap((pair) => {
+        const left = input.leftShapes[pair.leftIndex];
+        const right = input.rightShapes[pair.rightIndex];
+        return left === undefined || right === undefined
+            ? []
+            : diffPair(left, right, pair.discriminant, input.evidenceLinks);
+    });
+    const unpairedLeft = input.pairing.unpairedLeft.flatMap((index) => {
+        const shape = input.leftShapes[index];
+        return shape === undefined
+            ? []
+            : [unpairedChange("left", shape, input.evidenceLinks)];
+    });
+    const unpairedRight = input.pairing.unpairedRight.flatMap((index) => {
+        const shape = input.rightShapes[index];
+        return shape === undefined
+            ? []
+            : [unpairedChange("right", shape, input.evidenceLinks)];
+    });
+    return [...paired, ...unpairedLeft, ...unpairedRight];
+};
+/** Sort changes by semantic content rather than traversal order. */
+export const compareJavaScriptExportShapeChanges = (left, right) => compareCodePoints(canonicalExportShapeValue(changeSortKey(left)), canonicalExportShapeValue(changeSortKey(right)));
+/** Report whether any retained shape lacks complete property coverage. */
+export const hasPartialJavaScriptExportPropertyCoverage = (shapes) => shapes.some((shape) => shape.property_coverage.some(({ status }) => status === "partial"));
+const discriminantOccurrences = (shapes) => {
+    const output = new Map();
+    shapes.forEach((shape, index) => {
+        for (const field of shape.fields) {
+            const value = literalValue(field);
+            if (!value.found)
+                continue;
+            const discriminant = { path: field.path, value: value.value };
+            const key = canonicalExportShapeValue(discriminant);
+            const current = output.get(key);
+            output.set(key, {
+                discriminant,
+                indexes: [...(current?.indexes ?? []), index],
+            });
+        }
+    });
+    return output;
+};
+const reciprocalPairs = (leftTargets, rightTargets, edges) => {
+    const pairs = [];
+    for (const [leftIndex, targets] of leftTargets) {
+        if (targets.size !== 1)
+            continue;
+        const rightIndex = [...targets][0];
+        if (rightIndex === undefined ||
+            rightTargets.get(rightIndex)?.size !== 1 ||
+            !rightTargets.get(rightIndex)?.has(leftIndex))
+            continue;
+        const discriminants = edges
+            .get(`${String(leftIndex)}:${String(rightIndex)}`)
+            ?.toSorted(compareDiscriminants);
+        const discriminant = discriminants?.[0];
+        if (discriminant !== undefined)
+            pairs.push({ leftIndex, rightIndex, discriminant });
+    }
+    return pairs.sort((first, second) => compareDiscriminants(first.discriminant, second.discriminant));
+};
+const addTarget = (map, source, target) => {
+    const values = map.get(source) ?? new Set();
+    values.add(target);
+    map.set(source, values);
+};
+const indexesNotIn = (shapes, paired) => shapes.map((_, index) => index).filter((index) => !paired.has(index));
+const compareDiscriminants = (left, right) => compareCodePoints(canonicalExportShapeValue(left), canonicalExportShapeValue(right));
+const selectionUnknownChange = (input) => changeWithId({
+    status: "unknown",
+    path: "",
+    discriminant: null,
+    left: selectionAvailability(input.leftSelection.selection, "left"),
+    right: selectionAvailability(input.rightSelection.selection, "right"),
+    left_source_range: null,
+    right_source_range: null,
+    evidence_links: input.evidenceLinks,
+    limitations: [
+        "Both selectors must resolve one exact export with trusted static return shapes before comparison.",
+    ],
+});
+const emptyShapeUnknownChange = (input) => changeWithId({
+    status: "unknown",
+    path: "",
+    discriminant: null,
+    left: emptyShapeAvailability(input.leftShapes, "left"),
+    right: emptyShapeAvailability(input.rightShapes, "right"),
+    left_source_range: null,
+    right_source_range: null,
+    evidence_links: input.evidenceLinks,
+    limitations: [
+        "At least one selected export has no retained direct return shape.",
+    ],
+});
+const diffPair = (left, right, discriminant, evidenceLinks) => {
+    const leftFields = new Map(left.fields.map((field) => [field.path, field]));
+    const rightFields = new Map(right.fields.map((field) => [field.path, field]));
+    const paths = uniqueSorted([...leftFields.keys(), ...rightFields.keys()]);
+    return paths.flatMap((path) => {
+        const leftField = leftFields.get(path);
+        const rightField = rightFields.get(path);
+        const status = fieldChangeStatus({
+            leftShape: left,
+            rightShape: right,
+            path,
+            leftField,
+            rightField,
+        });
+        if (status === null)
+            return [];
+        return [
+            changeWithId({
+                status,
+                path,
+                discriminant,
+                left: fieldAvailability(leftField),
+                right: fieldAvailability(rightField),
+                left_source_range: left.source_range,
+                right_source_range: right.source_range,
+                evidence_links: evidenceLinks,
+                limitations: status === "unknown"
+                    ? [
+                        "The static value or relevant parent-property coverage is incomplete.",
+                    ]
+                    : [],
+            }),
+        ];
+    });
+};
+const fieldChangeStatus = ({ leftShape, rightShape, path, leftField, rightField, }) => {
+    if (leftField !== undefined && rightField !== undefined) {
+        if (canonicalExportShapeValue(leftField) ===
+            canonicalExportShapeValue(rightField))
+            return null;
+        return leftField.state === "unknown" || rightField.state === "unknown"
+            ? "unknown"
+            : "changed";
+    }
+    const present = leftField ?? rightField;
+    if (present === undefined)
+        return null;
+    const parent = parentPointer(path);
+    const parentsComplete = propertyCoverageComplete(leftShape, parent) &&
+        propertyCoverageComplete(rightShape, parent);
+    if (present.state === "unknown" || !parentsComplete)
+        return "unknown";
+    return leftField === undefined ? "added" : "removed";
+};
+const propertyCoverageComplete = (shape, path) => path !== null &&
+    shape.property_coverage.some((coverage) => coverage.path === path && coverage.status === "complete");
+const parentPointer = (path) => {
+    if (path === "")
+        return null;
+    const separator = path.lastIndexOf("/");
+    return separator < 0 ? null : path.slice(0, separator);
+};
+const fieldAvailability = (field) => {
+    if (field === undefined)
+        return { availability: "absent" };
+    if (field.state === "unknown")
+        return {
+            availability: "unknown",
+            reason: field.reason ?? "Static field value is unknown.",
+        };
+    if (field.state === "union")
+        return { availability: "union", values: primitiveArray(field.value) };
+    const literal = literalValue(field);
+    return literal.found
+        ? { availability: "literal", value: literal.value }
+        : {
+            availability: "unknown",
+            reason: "Static literal field failed its projection boundary.",
+        };
+};
+const selectionAvailability = (selection, side) => ({
+    availability: "unknown",
+    reason: `${capitalize(side)} export selection is ${selection.status}.`,
+});
+const emptyShapeAvailability = (shapes, side) => ({
+    availability: "unknown",
+    reason: shapes.length === 0
+        ? `${capitalize(side)} export has no retained direct return shape.`
+        : `${capitalize(side)} export return shape cannot be paired without an opposite variant.`,
+});
+const unpairedChange = (side, shape, evidenceLinks) => changeWithId({
+    status: "unknown",
+    path: "",
+    discriminant: null,
+    left: {
+        availability: "unknown",
+        reason: side === "left"
+            ? "Left return variant has no unique exact cross-version pairing."
+            : "No left return variant was uniquely paired with this right variant.",
+    },
+    right: {
+        availability: "unknown",
+        reason: side === "right"
+            ? "Right return variant has no unique exact cross-version pairing."
+            : "No right return variant was uniquely paired with this left variant.",
+    },
+    left_source_range: side === "left" ? shape.source_range : null,
+    right_source_range: side === "right" ? shape.source_range : null,
+    evidence_links: evidenceLinks,
+    limitations: [
+        "The return variant was not paired because no reciprocal unique literal discriminant exists.",
+    ],
+});
+const changeWithId = (semantic) => ({
+    ...semantic,
+    change_id: `jesc_change_${digestExportShapeValue(semantic)}`,
+});
+const changeSortKey = (change) => ({
+    discriminant: change.discriminant,
+    path: change.path,
+    status: change.status,
+    left_source_range: change.left_source_range,
+    right_source_range: change.right_source_range,
+    change_id: change.change_id,
+});
+const literalValue = (field) => field.state === "literal" && isPrimitive(field.value)
+    ? { found: true, value: field.value }
+    : { found: false };
+const primitiveArray = (value) => Array.isArray(value) ? value.filter(isPrimitive) : [];
+const isPrimitive = (value) => value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean";
+const capitalize = (value) => `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
+const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);

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);