rea-agents 2.1.0 → 2.3.0

package/dist/application/JavaScriptSemanticGraphEvidence.js

@@ -0,0 +1,86 @@
+const INFERENCE_LIMITATION = "This relationship is a bounded static candidate; it does not prove runtime execution or causal flow.";
+/** Exact artifact-backed syntax evidence for one semantic graph node. */
+export const observedSemanticEvidence = (file, location) => ({
+    authority: "ast-static-analysis",
+    state: "observed",
+    confidence: "exact",
+    artifact: {
+        available: true,
+        artifact_id: `art_${file.sha256}`,
+        sha256: file.sha256,
+    },
+    location: location === null
+        ? { available: true, value: { kind: "artifact-path", path: file.path } }
+        : {
+            available: true,
+            value: { kind: "source-range", source: file.path, ...location },
+        },
+    extractor: {
+        name: "rea-javascript-semantic-analysis",
+        version: "1",
+        operation: "analyze_javascript_application",
+        executable_sha256: null,
+    },
+    coverage: {
+        status: "complete",
+        truncated: false,
+        omitted_count: 0,
+        limits: [],
+    },
+    limitations: [],
+    evidence_ids: [],
+});
+/** Conservative static relationship evidence derived from one syntax node. */
+export const inferredSemanticEvidence = (source) => ({
+    ...source.evidence,
+    authority: "static-relationship-inference",
+    state: "inferred",
+    confidence: "high",
+    limitations: [INFERENCE_LIMITATION],
+});
+/** Static relationship evidence anchored at the syntax that proves the link. */
+export const inferredSemanticEvidenceAt = (file, location) => ({
+    ...observedSemanticEvidence(file, location),
+    authority: "static-relationship-inference",
+    state: "inferred",
+    confidence: "high",
+    limitations: [INFERENCE_LIMITATION],
+});
+/** Explicit absence of semantic syntax for an artifact-level fallback root. */
+export const unavailableSemanticRootEvidence = (rootArtifactSha256) => ({
+    authority: "unknown",
+    state: "unavailable",
+    confidence: "unknown",
+    artifact: {
+        available: true,
+        artifact_id: `art_${rootArtifactSha256}`,
+        sha256: rootArtifactSha256,
+    },
+    location: {
+        available: false,
+        reason: "not-observed",
+        detail: "No admitted JavaScript source produced semantic IR.",
+    },
+    extractor: {
+        name: "rea-javascript-semantic-analysis",
+        version: "1",
+        operation: "analyze_javascript_application",
+        executable_sha256: null,
+    },
+    coverage: {
+        status: "unavailable",
+        truncated: false,
+        omitted_count: null,
+        limits: [],
+    },
+    limitations: ["This synthetic graph root does not claim a source location."],
+    evidence_ids: [],
+});
+/** Explicit unknown evidence at one unresolved dynamic syntax location. */
+export const unknownSemanticEvidence = (file, location) => ({
+    ...observedSemanticEvidence(file, location),
+    authority: "unknown",
+    state: "unknown",
+    confidence: "unknown",
+    limitations: ["Dynamic syntax prevents an exact static relationship."],
+});

package/dist/application/JavaScriptSemanticGraphFlowProjection.js

@@ -0,0 +1,72 @@
+import { createJavaScriptSemanticGraphUnknown } from "../domain/javascriptSemanticGraph.js";
+import { addSemanticGraphRelation, addSemanticGraphUnknown, } from "./JavaScriptSemanticGraphConstruction.js";
+import { inferredSemanticEvidenceAt, unknownSemanticEvidence, } from "./JavaScriptSemanticGraphEvidence.js";
+import { semanticNodesWithinRange } from "./JavaScriptSemanticGraphProjection.js";
+/** Link direct return expressions to their retained semantic references. */
+export const projectSemanticReturnValues = (context) => {
+    for (const callable of context.ir.callables)
+        for (const site of callable.returnSites) {
+            const returnNode = context.returnSiteNodes.get(site.returnSiteId);
+            const references = semanticNodesWithinRange(context.referenceNodes, site.location);
+            for (const reference of references)
+                addSemanticGraphRelation(context.state, {
+                    source: reference,
+                    target: returnNode,
+                    relation: "aliases",
+                    resolution: site.identityReferenceLocation !== null &&
+                        rangesEqual(reference.identity.source_range, site.identityReferenceLocation)
+                        ? "resolved"
+                        : "candidate",
+                });
+        }
+};
+const rangesEqual = (left, right) => left !== null &&
+    right !== null &&
+    left.start.line === right.start.line &&
+    left.start.column === right.start.column &&
+    left.end.line === right.end.line &&
+    left.end.column === right.end.column;
+/** Link each captured binding to the callable at the exact reference site. */
+export const projectSemanticClosureCaptures = (context) => {
+    for (const capture of context.ir.closureCaptures)
+        addSemanticGraphRelation(context.state, {
+            source: context.bindingNodes.get(capture.bindingId),
+            target: context.callableNodes.get(capture.callableId),
+            relation: "captures",
+            resolution: "resolved",
+            evidence: inferredSemanticEvidenceAt(context.file, capture.referenceLocation),
+        });
+};
+/** Retain bounded unresolved dynamic-call and dynamic-property frontiers. */
+export const projectSemanticFrontiers = (context) => {
+    for (const frontier of context.ir.frontiers) {
+        const unknown = createJavaScriptSemanticGraphUnknown({
+            node_id: frontier.callableId === null
+                ? context.moduleNode.node_id
+                : (context.callableNodes.get(frontier.callableId)?.node_id ??
+                    context.moduleNode.node_id),
+            family: frontier.kind === "dynamic-call" ? "call-flow" : "object-flow",
+            relation_kinds: frontier.kind === "dynamic-call"
+                ? ["calls"]
+                : ["reads-property", "writes-property"],
+            reason: frontier.kind,
+            detail: frontier.reason,
+            candidate_node_ids: [],
+            evidence: unknownSemanticEvidence(context.file, frontier.location),
+        });
+        addSemanticGraphUnknown(context.state, unknown);
+    }
+};
+/** Publish exact semantic analyzer limits reached by any admitted source file. */
+export const semanticRecoveryLimits = (analysis) => {
+    const limits = new Map();
+    for (const { semantic } of analysis.files) {
+        if (semantic === null)
+            continue;
+        for (const name of semantic.ir.coverage.limitsReached)
+            limits.set(`semantic.${name}`, semantic.limits[name]);
+    }
+    return [...limits]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, value]) => ({ name, value, unit: "items" }));
+};

package/dist/application/JavaScriptSemanticGraphProjection.js

@@ -0,0 +1,33 @@
+import { compareCodePoints } from "../domain/javascriptApplicationGraph.js";
+import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES } from "../domain/javascriptSemanticGraphSchemas.js";
+/** Find the innermost callable that contains one exact source range. */
+export const owningSemanticCallableNode = (location, ir, nodes) => {
+    if (location === null)
+        return undefined;
+    return ir.callables
+        .filter((callable) => contains(callable.location, location))
+        .sort((left, right) => compareCodePoints(positionKey(right.location), positionKey(left.location)))
+        .map(({ callableId }) => nodes.get(callableId))
+        .find((node) => node !== undefined);
+};
+/** Find retained semantic nodes whose exact ranges are within one expression. */
+export const semanticNodesWithinRange = (nodes, range) => nodes.filter((node) => node.identity.source_range !== null &&
+    contains(range, node.identity.source_range));
+/** Report extractor support without treating missing families as absence. */
+export const semanticFamilyStatus = (family, analysis, truncated) => {
+    if (!["call-flow", "closure", "data-flow", "object-flow"].includes(family))
+        return "unsupported";
+    if (truncated)
+        return "unknown";
+    return analysis.truncated_scopes === 0 ? "partial" : "unknown";
+};
+/** Compare two exact semantic source ranges. */
+export const semanticRangesEqual = (left, right) => left !== null &&
+    left.start.line === right.start.line &&
+    left.start.column === right.start.column &&
+    left.end.line === right.end.line &&
+    left.end.column === right.end.column;
+const contains = (outer, inner) => pointCompare(outer.start, inner.start) <= 0 &&
+    pointCompare(outer.end, inner.end) >= 0;
+const pointCompare = (left, right) => left.line - right.line || left.column - right.column;
+const positionKey = (range) => `${String(range.start.line).padStart(12, "0")}:${String(range.start.column).padStart(12, "0")}`;

package/dist/application/JavaScriptSemanticTraceService.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { AnalysisInputError, AnalysisProtocolError, } from "../domain/errors.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { queryJavaScriptSemanticGraph } from "../domain/javascriptSemanticQuery.js";
+import { JavaScriptSemanticQueryCursorError } from "../domain/javascriptSemanticQueryIdentity.js";
+import { javaScriptSemanticTraceResultSchema, traceJavaScriptSemanticsInputSchema, } from "../domain/javascriptSemanticTraceSchemas.js";
+import { err, ok } from "../domain/result.js";
+import { parseApplicationGraphEvidence } from "./JavaScriptApplicationEvidenceGraph.js";
+import { createJavaScriptSemanticTraceEvidence } from "./JavaScriptApplicationWorkflowEvidence.js";
+const OPERATION = "trace_javascript_semantics";
+/** Trace semantic relations from input already parsed by a trusted adapter. */
+export const traceJavaScriptSemanticsEvidenceValidated = (input) => {
+    try {
+        const source = parseApplicationGraphEvidence(input.application);
+        if (source.semanticGraph === null)
+            return err(new AnalysisInputError(OPERATION, undefined, [
+                {
+                    path: ["application"],
+                    reason: "invalid_value",
+                    expected: "analyze_javascript_application v2 Evidence; reanalyze the artifact with the current REA version",
+                },
+            ]));
+        const query = queryJavaScriptSemanticGraph(source.semanticGraph, input.query);
+        const result = javaScriptSemanticTraceResultSchema.parse({
+            ...query,
+            source_evidence_id: source.evidence.evidence_id,
+            evidence_links: [source.evidence.evidence_id],
+        });
+        return ok(createJavaScriptSemanticTraceEvidence({
+            application_evidence_id: source.evidence.evidence_id,
+            query: jsonValueSchema.parse(input.query),
+        }, result));
+    }
+    catch (cause) {
+        if (cause instanceof JavaScriptSemanticQueryCursorError)
+            return err(new AnalysisInputError(OPERATION, undefined, [
+                {
+                    path: ["query", "cursor"],
+                    reason: "invalid_value",
+                    expected: "a cursor returned by the same graph, query, and limits",
+                },
+            ]));
+        return err(new AnalysisProtocolError("JavaScript semantic trace failed", { cause }));
+    }
+};