rea-agents 1.7.0 → 2.1.0

package/dist/domain/javascriptRuntimeStaticCandidates.js

@@ -0,0 +1,193 @@
+import { isAbsolute, posix, relative } from "node:path";
+import { compareCodePoints, } from "./javascriptApplicationGraph.js";
+/** Index statically reconstructed entities that can receive runtime matches. */
+export const collectStaticRuntimeCandidates = (layers) => layers
+    .flatMap((layer) => candidatesForLayer(layer))
+    .sort((left, right) => compareCodePoints(left.layer.layerId, right.layer.layerId) ||
+    compareCodePoints(left.node.node_id, right.node.node_id));
+/** Translate one already-authorized runtime location into artifact paths. */
+export const mappedRuntimePaths = (layer, entity) => {
+    const paths = [];
+    if (entity.location.kind === "file" && layer.result.format === "directory") {
+        const path = pathBelowRoot(layer.result.input_path, entity.location.value);
+        if (path !== null)
+            paths.push({ path, basis: "artifact-path" });
+    }
+    for (const mapping of layer.runtimeMappings) {
+        const suffix = mapping.kind === "file-root" && entity.location.kind === "file"
+            ? pathBelowRoot(mapping.root, entity.location.value)
+            : mapping.kind === "url-prefix" && entity.location.kind === "url"
+                ? pathBelowUrlPrefix(mapping.prefix, entity.location.value)
+                : null;
+        if (suffix === null)
+            continue;
+        const path = safeArtifactPath(mapping.artifact_prefix, suffix);
+        if (path === null)
+            continue;
+        paths.push({
+            path,
+            basis: mapping.kind === "file-root"
+                ? "operator-file-mapping"
+                : "operator-url-mapping",
+        });
+    }
+    return uniqueMappedPaths(paths);
+};
+/** Precompute the artifact prefixes exercised by a bounded runtime set. */
+export const createStaticRuntimeScope = (layer, entities) => ({
+    artifactPrefixes: activeArtifactPrefixes(layer, entities),
+    pathsByNodeId: indexStaticPaths(layer.graph),
+});
+/** Whether one static node falls under a mapping exercised by this runtime set. */
+export const staticNodeWithinRuntimeScope = (node, scope) => (scope.pathsByNodeId.get(node.node_id) ?? []).some((path) => scope.artifactPrefixes.some((prefix) => pathWithinPrefix(path, prefix)));
+const candidatesForLayer = (layer) => {
+    const graph = layer.graph;
+    const pathsByNodeId = indexStaticPaths(graph);
+    return graph.nodes.flatMap((node) => {
+        const category = candidateCategory(node);
+        if (category === null)
+            return [];
+        return [
+            {
+                layer,
+                node,
+                category,
+                paths: pathsByNodeId.get(node.node_id) ?? [],
+                digests: candidateDigests(node),
+            },
+        ];
+    });
+};
+const candidateCategory = (node) => {
+    if (node.kind === "electron-renderer")
+        return "renderer";
+    if (node.kind === "javascript-asset" ||
+        (node.kind === "javascript-module" && !isStaticSourceModule(node)))
+        return "javascript";
+    if (node.kind === "worker")
+        return "worker";
+    if (node.kind === "service-worker")
+        return "service-worker";
+    return null;
+};
+const isStaticSourceModule = (node) => node.observations.some(({ properties }) => properties.semantic_role === "source-module");
+const indexStaticPaths = (graph) => {
+    const nodes = new Map(graph.nodes.map((candidate) => [candidate.node_id, candidate]));
+    const relatedBySource = new Map();
+    for (const edge of graph.edges) {
+        if (edge.relation !== "maps_to")
+            continue;
+        const target = nodes.get(edge.target_node_id);
+        if (target === undefined)
+            continue;
+        const related = relatedBySource.get(edge.source_node_id);
+        if (related === undefined)
+            relatedBySource.set(edge.source_node_id, [target]);
+        else
+            related.push(target);
+    }
+    return new Map(graph.nodes.map((node) => [
+        node.node_id,
+        uniqueSorted([
+            ...nodePaths(node),
+            ...(relatedBySource.get(node.node_id) ?? []).flatMap(nodePaths),
+        ]),
+    ]));
+};
+const nodePaths = (node) => {
+    const paths = [];
+    if (node.identity.strategy === "canonical-path")
+        paths.push(node.identity.path);
+    for (const observation of node.observations) {
+        for (const property of ["path", "resolved_path", "declared_path"])
+            if (typeof observation.properties[property] === "string")
+                paths.push(observation.properties[property]);
+        if (observation.evidence.location.available &&
+            observation.evidence.location.value.kind === "artifact-path")
+            paths.push(observation.evidence.location.value.path);
+    }
+    return paths
+        .map(normalizeArtifactPath)
+        .filter((path) => path !== null && path !== "artifact-root");
+};
+const candidateDigests = (node) => {
+    const values = [];
+    if (node.kind === "javascript-asset" &&
+        node.identity.strategy === "content-digest")
+        values.push({
+            sha256: node.identity.sha256,
+            basis: "content-sha256",
+        });
+    if (node.kind === "javascript-module")
+        for (const observation of node.observations) {
+            const digest = observation.properties.source_sha256;
+            if (typeof digest === "string" && /^[a-f0-9]{64}$/u.test(digest))
+                values.push({ sha256: digest, basis: "module-source-sha256" });
+        }
+    return [
+        ...new Map(values.map((value) => [`${value.basis}:${value.sha256}`, value])).values(),
+    ];
+};
+const pathBelowRoot = (root, value) => {
+    const remainder = relative(root, value);
+    if (remainder === "" ||
+        remainder.startsWith("..") ||
+        isAbsolute(remainder) ||
+        remainder.includes("\\"))
+        return null;
+    return normalizeArtifactPath(remainder);
+};
+const pathBelowUrlPrefix = (prefix, value) => {
+    let base;
+    let candidate;
+    try {
+        base = new URL(prefix);
+        candidate = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (base.origin !== candidate.origin ||
+        !candidate.pathname.startsWith(base.pathname))
+        return null;
+    try {
+        return normalizeArtifactPath(decodeURIComponent(candidate.pathname.slice(base.pathname.length)));
+    }
+    catch {
+        return null;
+    }
+};
+const activeArtifactPrefixes = (layer, entities) => {
+    const prefixes = new Set();
+    if (layer.result.format === "directory" &&
+        entities.some(({ location }) => location.kind === "file" &&
+            pathBelowRoot(layer.result.input_path, location.value) !== null))
+        prefixes.add("");
+    for (const mapping of layer.runtimeMappings)
+        if (entities.some(({ location }) => mapping.kind === "file-root" && location.kind === "file"
+            ? pathBelowRoot(mapping.root, location.value) !== null
+            : mapping.kind === "url-prefix" && location.kind === "url"
+                ? pathBelowUrlPrefix(mapping.prefix, location.value) !== null
+                : false))
+            prefixes.add(mapping.artifact_prefix);
+    return [...prefixes].sort(compareCodePoints);
+};
+const pathWithinPrefix = (path, prefix) => prefix === "" || path === prefix || path.startsWith(`${prefix}/`);
+const safeArtifactPath = (prefix, suffix) => normalizeArtifactPath(prefix === "" ? suffix : posix.join(prefix, suffix));
+const normalizeArtifactPath = (value) => {
+    const normalized = posix
+        .normalize(value.replaceAll("\\", "/"))
+        .replace(/^\.\//u, "");
+    return normalized !== "" &&
+        normalized !== "." &&
+        normalized !== ".." &&
+        !normalized.startsWith("/") &&
+        !normalized.startsWith("../")
+        ? normalized
+        : null;
+};
+const uniqueMappedPaths = (values) => [
+    ...new Map(values.map((value) => [`${value.basis}:${value.path}`, value])).values(),
+].sort((left, right) => compareCodePoints(left.path, right.path) ||
+    compareCodePoints(left.basis, right.basis));
+const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);

package/dist/domain/javascriptSemanticAnalysis.js

@@ -0,0 +1,386 @@
+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 { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
+import { compareCodePoints, propertyName, range, } from "./javascriptStaticAnalysisHelpers.js";
+/** Recover bounded lexical bindings, aliases, constants, and module links. */
+export const analyzeJavaScriptSemantics = (source, inputLimits = {}) => {
+    const limits = { ...DEFAULT_JAVASCRIPT_SEMANTIC_LIMITS, ...inputLimits };
+    let file;
+    try {
+        file = parse(source, {
+            sourceType: "unambiguous",
+            errorRecovery: true,
+            plugins: ["jsx", "typescript"],
+        });
+    }
+    catch {
+        return failedJavaScriptSemanticIr();
+    }
+    const state = createState(file.program, limits);
+    collectDefinitions(file.program, state);
+    const references = collectSemanticReferences(file.program, state);
+    const parserPartial = file.errors.length > 0;
+    return {
+        schema: "JavaScriptSemanticIR",
+        schemaVersion: 1,
+        scopes: immutableSemanticScopes(state),
+        bindings: immutableSemanticBindings(state),
+        callables: [...state.callables],
+        references,
+        moduleLinks: [...state.moduleLinks],
+        coverage: {
+            status: state.limitsReached.size > 0
+                ? "truncated"
+                : parserPartial
+                    ? "partial"
+                    : "complete",
+            omittedCount: state.limitsReached.size > 0 ? state.omittedCount : 0,
+            limitsReached: [...state.limitsReached].sort(compareCodePoints),
+        },
+        limitations: [
+            ...(parserPartial
+                ? [
+                    "The parser recovered from syntax errors; affected bindings are partial.",
+                ]
+                : []),
+            ...(state.limitsReached.size === 0
+                ? []
+                : ["Semantic recovery stopped retaining facts at explicit limits."]),
+            "Values and aliases were recovered from inert syntax only; no JavaScript was executed.",
+            "Cross-function mutation and dynamic property resolution remain unknown.",
+        ],
+    };
+};
+const createState = (program, limits) => {
+    const root = {
+        scopeId: semanticScopeId("program", program),
+        parentScopeId: null,
+        kind: "program",
+        location: range(program),
+        bindingsComplete: true,
+        bindings: new Map(),
+    };
+    return {
+        limits,
+        scopes: [root],
+        scopesById: new Map([[root.scopeId, root]]),
+        scopeByNode: new WeakMap([[program, root]]),
+        bindingsById: new Map(),
+        callables: [],
+        moduleLinks: [],
+        limitsReached: new Set(),
+        omittedCount: 0,
+    };
+};
+const collectDefinitions = (program, state) => {
+    const stack = [
+        currentSemanticScope(state.scopes),
+    ];
+    const openedScopes = new WeakSet();
+    traverseJavaScriptAst(program, {
+        enter: (node, parent) => {
+            const parentScope = currentSemanticScope(stack);
+            bindOuterDeclaration(node, parentScope, state);
+            const nested = nestedScope(node, parent, parentScope, state);
+            if (nested !== undefined) {
+                stack.push(nested);
+                openedScopes.add(node);
+            }
+            const scope = currentSemanticScope(stack);
+            state.scopeByNode.set(node, scope);
+            collectSemanticCallable({
+                node,
+                parent,
+                containerScope: parentScope,
+                bodyScope: nested,
+                state,
+            });
+            bindInnerDeclaration(node, parent, scope, state);
+            collectSemanticModuleLink(node, state);
+        },
+        exit: (node) => {
+            if (openedScopes.has(node))
+                stack.pop();
+        },
+    });
+};
+const bindOuterDeclaration = (node, scope, state) => {
+    if (t.isFunctionDeclaration(node) && t.isIdentifier(node.id))
+        addBinding({
+            state,
+            scope,
+            name: node.id.name,
+            kind: "function",
+            mutable: false,
+            definitionNode: node.id,
+            initializer: node,
+        });
+    else if (t.isClassDeclaration(node) && t.isIdentifier(node.id))
+        addBinding({
+            state,
+            scope,
+            name: node.id.name,
+            kind: "class",
+            mutable: false,
+            definitionNode: node.id,
+            initializer: node,
+        });
+};
+const bindInnerDeclaration = (node, parent, scope, state) => {
+    if (t.isImportDeclaration(node))
+        bindImports(node, scope, state);
+    else if (t.isVariableDeclarator(node))
+        bindPattern({
+            pattern: node.id,
+            initializer: node.init ?? null,
+            scope: variableScope(scope, parent, state),
+            state,
+            mutable: parent !== null && t.isVariableDeclaration(parent)
+                ? parent.kind !== "const"
+                : true,
+        });
+    else if (t.isFunction(node))
+        bindFunctionLocals(node, scope, state);
+    else if (t.isCatchClause(node) && node.param != null)
+        bindPattern({
+            pattern: node.param,
+            initializer: null,
+            scope,
+            state,
+            mutable: true,
+            kind: "catch",
+        });
+    else if (t.isAssignmentExpression(node) && t.isIdentifier(node.left))
+        addAssignment(node.left, node.right, scope, state);
+};
+const nestedScope = (node, parent, parentScope, state) => {
+    const kind = scopeKind(node, parent);
+    if (kind === undefined)
+        return undefined;
+    if (state.scopes.length >= state.limits.maxScopes) {
+        reachSemanticLimit(state, "maxScopes");
+        return {
+            scopeId: `${semanticScopeId(kind, node)}:omitted`,
+            parentScopeId: parentScope.scopeId,
+            kind,
+            location: range(node),
+            bindingsComplete: false,
+            bindings: new Map(),
+        };
+    }
+    const scope = {
+        scopeId: semanticScopeId(kind, node),
+        parentScopeId: parentScope.scopeId,
+        kind,
+        location: range(node),
+        bindingsComplete: true,
+        bindings: new Map(),
+    };
+    state.scopes.push(scope);
+    state.scopesById.set(scope.scopeId, scope);
+    return scope;
+};
+const scopeKind = (node, parent) => {
+    if (t.isFunction(node))
+        return "function";
+    if (t.isClass(node))
+        return "class";
+    if (t.isCatchClause(node))
+        return "catch";
+    if (t.isBlockStatement(node) &&
+        !(parent !== null && t.isFunction(parent) && parent.body === node))
+        return "block";
+    return undefined;
+};
+const bindImports = (node, scope, state) => {
+    for (const specifier of node.specifiers) {
+        const importedPath = t.isImportDefaultSpecifier(specifier)
+            ? ["default"]
+            : t.isImportNamespaceSpecifier(specifier)
+                ? []
+                : [propertyName(specifier.imported) || "[dynamic]"];
+        addBinding({
+            state,
+            scope,
+            name: specifier.local.name,
+            kind: "import",
+            mutable: false,
+            definitionNode: specifier.local,
+            initializer: null,
+            directOrigin: { specifier: node.source.value, importedPath },
+        });
+    }
+};
+const bindFunctionLocals = (node, scope, state) => {
+    if (t.isFunctionExpression(node) && t.isIdentifier(node.id))
+        addBinding({
+            state,
+            scope,
+            name: node.id.name,
+            kind: "function",
+            mutable: false,
+            definitionNode: node.id,
+            initializer: node,
+        });
+    for (const parameter of node.params)
+        bindPattern({
+            pattern: t.isTSParameterProperty(parameter)
+                ? parameter.parameter
+                : parameter,
+            initializer: null,
+            scope,
+            state,
+            mutable: true,
+            kind: "parameter",
+        });
+};
+const bindPattern = (input) => {
+    const { pattern, initializer, scope, state, mutable, kind = "variable", projection = [], } = input;
+    if (t.isTSParameterProperty(pattern)) {
+        bindPattern({ ...input, pattern: pattern.parameter });
+        return;
+    }
+    if (t.isIdentifier(pattern)) {
+        const baseOrigin = semanticModuleOrigin(initializer, []);
+        const directOrigin = baseOrigin === undefined || projection.includes(null)
+            ? undefined
+            : {
+                ...baseOrigin,
+                importedPath: [
+                    ...baseOrigin.importedPath,
+                    ...projection.map((segment) => String(segment)),
+                ],
+            };
+        addBinding({
+            state,
+            scope,
+            name: pattern.name,
+            kind,
+            mutable,
+            definitionNode: pattern,
+            initializer,
+            ...(directOrigin === undefined ? {} : { directOrigin }),
+            projection,
+        });
+        return;
+    }
+    if (t.isAssignmentPattern(pattern)) {
+        bindPattern({
+            ...input,
+            pattern: pattern.left,
+            initializer: initializer ?? pattern.right,
+        });
+        return;
+    }
+    if (t.isRestElement(pattern)) {
+        bindPattern({
+            ...input,
+            pattern: pattern.argument,
+            initializer: null,
+            mutable: true,
+        });
+        return;
+    }
+    if (t.isObjectPattern(pattern))
+        for (const property of pattern.properties) {
+            if (t.isRestElement(property))
+                bindPattern({
+                    ...input,
+                    pattern: property.argument,
+                    initializer: null,
+                    mutable: true,
+                    projection: [],
+                });
+            else {
+                const name = semanticStaticPropertyName(property.key, property.computed);
+                bindPattern({
+                    ...input,
+                    pattern: property.value,
+                    projection: [...projection, name === "" ? null : name],
+                });
+            }
+        }
+    else if (t.isArrayPattern(pattern))
+        pattern.elements.forEach((element, index) => {
+            if (element !== null)
+                bindPattern({
+                    ...input,
+                    pattern: element,
+                    projection: [...projection, index],
+                });
+        });
+};
+const addBinding = (input) => {
+    const { state, scope, name, kind, mutable, definitionNode, initializer, directOrigin, projection = [], } = input;
+    let binding = scope.bindings.get(name);
+    if (binding === undefined) {
+        if (!scope.bindingsComplete) {
+            state.omittedCount += 1;
+            return;
+        }
+        if (state.bindingsById.size >= state.limits.maxBindings) {
+            scope.bindingsComplete = false;
+            reachSemanticLimit(state, "maxBindings");
+            return;
+        }
+        binding = createBinding(scope, name, kind, mutable);
+        scope.bindings.set(name, binding);
+        state.bindingsById.set(binding.bindingId, binding);
+    }
+    binding.mutable ||= mutable;
+    binding.definitions.push({ kind, location: range(definitionNode) });
+    if (initializer !== null)
+        binding.initializers.push({ node: initializer, projection });
+    if (directOrigin !== undefined)
+        binding.directOrigins.push(directOrigin);
+};
+const createBinding = (scope, name, kind, mutable) => ({
+    bindingId: `${scope.scopeId}:binding:${encodeURIComponent(name)}`,
+    scopeId: scope.scopeId,
+    name,
+    kind,
+    mutable,
+    definitions: [],
+    initializers: [],
+    directOrigins: [],
+});
+const addAssignment = (identifier, initializer, scope, state) => {
+    const binding = resolveFromScope(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/javascriptSemanticIr.js

@@ -0,0 +1,30 @@
+/** Conservative defaults for one source file. */
+export const DEFAULT_JAVASCRIPT_SEMANTIC_LIMITS = {
+    maxScopes: 4_096,
+    maxBindings: 20_000,
+    maxCallables: 20_000,
+    maxReferences: 100_000,
+    maxModuleLinks: 20_000,
+    maxValueDepth: 16,
+    maxUnionValues: 32,
+    maxObjectProperties: 256,
+};
+/** Find the innermost resolved reference at one source coordinate. */
+export const semanticReferenceAt = (ir, line, column) => ir.references.find(({ location }) => location.start.line === line && location.start.column === column);
+/** Read one binding by its deterministic semantic identifier. */
+export const semanticBinding = (ir, bindingId) => ir.bindings.find(({ bindingId: candidate }) => candidate === bindingId);
+/** Fail-closed result when Babel cannot produce an inert syntax tree. */
+export const failedJavaScriptSemanticIr = () => ({
+    schema: "JavaScriptSemanticIR",
+    schemaVersion: 1,
+    scopes: [],
+    bindings: [],
+    callables: [],
+    references: [],
+    moduleLinks: [],
+    coverage: { status: "failed", omittedCount: null, limitsReached: [] },
+    limitations: [
+        "JavaScript parsing failed; no semantic absence claim is available.",
+        "No JavaScript was executed.",
+    ],
+});