rea-agents 1.7.0 → 2.1.0

package/dist/domain/webBundleAnalyzerInspection.js

@@ -0,0 +1,307 @@
+import { parse } from "@babel/parser";
+import * as t from "@babel/types";
+import { calleeName, endpointArgument, location, locationFields, objectString, objectValue, propertyName, resolveSpecifier, sanitizeCandidate, stringArgument, } from "./webBundleAnalyzerAst.js";
+export const analyzeScript = (script, input, accumulator) => {
+    let file;
+    try {
+        file = parse(script.source.artifact.text, {
+            sourceType: "unambiguous",
+            errorRecovery: true,
+            plugins: ["jsx", "typescript"],
+        });
+    }
+    catch {
+        accumulator.parseFailures += 1;
+        return;
+    }
+    accumulator.parsedScripts += 1;
+    detectVendorFingerprints(script, accumulator, input.analysis_limits.max_findings);
+    t.traverseFast(file, (node) => {
+        accumulator.visitedNodes += 1;
+        if (accumulator.visitedNodes > input.analysis_limits.max_ast_nodes) {
+            accumulator.astLimitReached = true;
+            return t.traverseFast.stop;
+        }
+        inspectNode(script, node, accumulator, input.analysis_limits.max_findings);
+        return undefined;
+    });
+};
+const inspectNode = (script, node, accumulator, maximumFindings) => {
+    if ((t.isImportDeclaration(node) || t.isExportAllDeclaration(node)) &&
+        node.source !== undefined)
+        addEdge({
+            script,
+            specifier: node.source.value,
+            kind: "static_import",
+            node,
+            accumulator,
+            maximumFindings,
+        });
+    else if (t.isExportNamedDeclaration(node) && node.source != null)
+        addEdge({
+            script,
+            specifier: node.source.value,
+            kind: "static_import",
+            node,
+            accumulator,
+            maximumFindings,
+        });
+    else if (t.isImportExpression(node) && t.isStringLiteral(node.source))
+        addEdge({
+            script,
+            specifier: node.source.value,
+            kind: "dynamic_import",
+            node,
+            accumulator,
+            maximumFindings,
+        });
+    if (t.isObjectProperty(node))
+        inspectRouteProperty(script, node, accumulator, maximumFindings);
+    if (t.isCallExpression(node) || t.isNewExpression(node))
+        inspectCall(script, node, accumulator, maximumFindings);
+};
+const inspectCall = (script, node, accumulator, maximumFindings) => {
+    const name = calleeName(node.callee);
+    const first = stringArgument(node.arguments[0]);
+    if ((name === "require" || name.endsWith(".require")) && first !== undefined)
+        addEdge({
+            script,
+            specifier: first,
+            kind: "require",
+            node,
+            accumulator,
+            maximumFindings,
+        });
+    if ((name === "importScripts" || name.endsWith(".importScripts")) &&
+        first !== undefined)
+        addEdge({
+            script,
+            specifier: first,
+            kind: "worker_import",
+            node,
+            accumulator,
+            maximumFindings,
+        });
+    if (routeCallNames.some((candidate) => name === candidate || name.endsWith(`.${candidate}`))) {
+        if (first !== undefined)
+            addFinding({
+                collection: accumulator.routes,
+                script,
+                rawValue: first,
+                mechanism: `call:${name}`,
+                node,
+                accumulator,
+                maximumFindings,
+            });
+        addRouteFrameworkInference({
+            script,
+            name,
+            node,
+            accumulator,
+            maximumFindings,
+        });
+    }
+    const endpoint = endpointArgument(name, node.arguments);
+    if (endpoint !== undefined)
+        addFinding({
+            collection: accumulator.endpoints,
+            script,
+            rawValue: endpoint,
+            mechanism: `call:${name}`,
+            node,
+            accumulator,
+            maximumFindings,
+        });
+    if (name.endsWith("modelContext.registerTool") ||
+        name === "modelContext.registerTool")
+        addWebMcpDeclaration(script, node, accumulator, maximumFindings);
+};
+const inspectRouteProperty = (script, node, accumulator, maximumFindings) => {
+    const key = propertyName(node.key);
+    if ((key === "path" || key === "route") && t.isStringLiteral(node.value))
+        addFinding({
+            collection: accumulator.routes,
+            script,
+            rawValue: node.value.value,
+            mechanism: `property:${key}`,
+            node,
+            accumulator,
+            maximumFindings,
+        });
+};
+const addEdge = (context) => {
+    const bounded = context.specifier.slice(0, 4_096);
+    const key = `edge\0${context.script.script_key}\0${context.kind}\0${bounded}`;
+    addBounded(context.accumulator, key, context.maximumFindings, () => context.accumulator.edges.push({
+        from_script_key: context.script.script_key,
+        kind: context.kind,
+        specifier: bounded,
+        resolved_url: resolveSpecifier(bounded, context.script.url),
+        location: location(context.script.script_key, context.node),
+    }));
+};
+const addFinding = (context) => {
+    const value = sanitizeCandidate(context.rawValue);
+    const key = `finding\0${context.mechanism}\0${context.script.script_key}\0${value}`;
+    addBounded(context.accumulator, key, context.maximumFindings, () => context.collection.push({
+        value,
+        mechanism: context.mechanism,
+        location: location(context.script.script_key, context.node),
+    }));
+};
+const addWebMcpDeclaration = (script, node, accumulator, maximumFindings) => {
+    const declaration = node.arguments[0];
+    if (!t.isObjectExpression(declaration))
+        return;
+    const name = objectString(declaration, "name");
+    const description = objectString(declaration, "description");
+    const schema = objectValue(declaration, "inputSchema") ??
+        objectValue(declaration, "input_schema");
+    const declaredProperties = t.isObjectExpression(schema)
+        ? objectValue(schema, "properties")
+        : undefined;
+    const propertyObject = t.isObjectExpression(declaredProperties)
+        ? declaredProperties
+        : schema;
+    const schemaPropertyNames = t.isObjectExpression(propertyObject)
+        ? propertyObject.properties.flatMap((property) => t.isObjectProperty(property)
+            ? [propertyName(property.key)].filter(Boolean)
+            : [])
+        : [];
+    const key = `webmcp\0${script.script_key}\0${name ?? ""}\0${schemaPropertyNames.join("\0")}`;
+    addBounded(accumulator, key, maximumFindings, () => accumulator.webMcp.push({
+        name: name?.slice(0, 256) ?? null,
+        description: description?.slice(0, 2_048) ?? null,
+        schema_property_names: [...new Set(schemaPropertyNames)]
+            .sort()
+            .slice(0, 256),
+        trust: "page-declared-untrusted",
+        location: location(script.script_key, node),
+    }));
+};
+const detectVendorFingerprints = (script, accumulator, maximumFindings) => {
+    const text = script.source.artifact.text;
+    for (const detector of vendorDetectors) {
+        if (!detector.patterns.some((pattern) => text.includes(pattern)))
+            continue;
+        const key = `vendor\0${script.script_key}\0${detector.value}`;
+        addBounded(accumulator, key, maximumFindings, () => accumulator.inferences.push({
+            kind: detector.kind,
+            value: detector.value,
+            confidence: detector.confidence,
+            basis: [basis(script, detector.detector)],
+        }));
+    }
+};
+const addRouteFrameworkInference = (context) => {
+    const value = context.name.endsWith("useRoutes") ||
+        context.name.endsWith("createBrowserRouter")
+        ? "React Router-compatible route API"
+        : "Generic route registration API";
+    const key = `route-framework\0${context.script.script_key}\0${value}`;
+    addBounded(context.accumulator, key, context.maximumFindings, () => context.accumulator.inferences.push({
+        kind: "route_framework",
+        value,
+        confidence: "medium",
+        basis: [
+            {
+                ...basis(context.script, `call:${context.name}`),
+                ...locationFields(context.node),
+            },
+        ],
+    }));
+};
+const addBounded = (accumulator, key, maximum, add) => {
+    if (accumulator.seen.has(key))
+        return;
+    const findings = accumulator.edges.length +
+        accumulator.routes.length +
+        accumulator.endpoints.length +
+        accumulator.webMcp.length +
+        accumulator.inferences.length;
+    if (findings >= maximum) {
+        accumulator.droppedFindings += 1;
+        return;
+    }
+    accumulator.seen.add(key);
+    add();
+};
+const basis = (script, detector) => ({
+    script_key: script.script_key,
+    artifact_sha256: script.source.artifact.sha256,
+    line: null,
+    column: null,
+    detector,
+});
+export const emptyAccumulator = () => ({
+    edges: [],
+    routes: [],
+    endpoints: [],
+    webMcp: [],
+    inferences: [],
+    seen: new Set(),
+    visitedNodes: 0,
+    parsedScripts: 0,
+    parseFailures: 0,
+    droppedFindings: 0,
+    astLimitReached: false,
+});
+export const isIncludedScript = (script) => script.source.included;
+const routeCallNames = [
+    "route",
+    "addRoute",
+    "useRoutes",
+    "createBrowserRouter",
+    "createHashRouter",
+];
+const vendorDetectors = [
+    {
+        value: "webpack",
+        detector: "webpack-runtime",
+        patterns: ["__webpack_require__"],
+        confidence: "high",
+        kind: "bundle_runtime",
+    },
+    {
+        value: "Vite",
+        detector: "vite-runtime",
+        patterns: ["__vite__", "import.meta.hot"],
+        confidence: "medium",
+        kind: "bundle_runtime",
+    },
+    {
+        value: "React",
+        detector: "react-runtime",
+        patterns: ["__REACT_DEVTOOLS_GLOBAL_HOOK__", "React.createElement"],
+        confidence: "medium",
+        kind: "vendor_fingerprint",
+    },
+    {
+        value: "Vue",
+        detector: "vue-runtime",
+        patterns: ["__VUE__", "createApp("],
+        confidence: "medium",
+        kind: "vendor_fingerprint",
+    },
+    {
+        value: "Next.js",
+        detector: "next-runtime",
+        patterns: ["__NEXT_DATA__", "/_next/"],
+        confidence: "high",
+        kind: "vendor_fingerprint",
+    },
+    {
+        value: "Angular",
+        detector: "angular-runtime",
+        patterns: ["ɵɵdefineComponent"],
+        confidence: "high",
+        kind: "vendor_fingerprint",
+    },
+    {
+        value: "Svelte",
+        detector: "svelte-runtime",
+        patterns: ["svelte/internal"],
+        confidence: "medium",
+        kind: "vendor_fingerprint",
+    },
+];

package/dist/domain/webBundleAnalyzerResult.js

@@ -0,0 +1,120 @@
+import { webBundleAnalysisSchema, } from "./webBundleAnalysis.js";
+export const buildWebBundleAnalysis = (inspection, sourceScripts, sourceMaps, accumulator) => {
+    const unavailable = inspection.scripts.items
+        .filter((script) => !script.source.included)
+        .map(({ script_key }) => script_key);
+    const sourceMapIncomplete = sourceMaps.status === "partial" || sourceMaps.status === "unavailable";
+    const partial = accumulator.parseFailures > 0 ||
+        unavailable.length > 0 ||
+        sourceMapIncomplete;
+    const truncated = accumulator.astLimitReached ||
+        accumulator.droppedFindings > 0 ||
+        sourceMaps.status === "truncated";
+    return webBundleAnalysisSchema.parse({
+        schema_version: 1,
+        capture: buildCaptureObservation(inspection, sourceScripts),
+        observations: {
+            chunks: {
+                nodes: sourceScripts.map(chunkNode),
+                edges: accumulator.edges,
+            },
+            routes: accumulator.routes,
+            endpoints: accumulator.endpoints,
+            webmcp_declarations: accumulator.webMcp,
+            source_maps: sourceMaps,
+        },
+        inferences: accumulator.inferences,
+        unknowns: buildUnknowns({
+            sourceScripts,
+            unavailable,
+            parseFailures: accumulator.parseFailures,
+            sourceMaps,
+        }),
+        completeness: buildCompleteness({
+            truncated,
+            partial,
+            parsedScripts: accumulator.parsedScripts,
+            parseFailures: accumulator.parseFailures,
+            visitedNodes: accumulator.visitedNodes,
+            droppedFindings: accumulator.droppedFindings,
+        }),
+        limitations: bundleLimitations(),
+    });
+};
+const buildCaptureObservation = (inspection, sourceScripts) => ({
+    target_url: inspection.target.url,
+    scripts_observed: inspection.scripts.total,
+    scripts_analyzed: sourceScripts.length,
+    source_artifacts: sourceScripts.map(sourceArtifact),
+});
+const sourceArtifact = (script) => {
+    if (!script.source.included)
+        throw new TypeError("Filtered source changed");
+    const { text: _text, ...artifact } = script.source.artifact;
+    return { ...artifact, text_available: true };
+};
+const chunkNode = (script) => {
+    if (!script.source.included)
+        throw new TypeError("Filtered source changed");
+    return {
+        script_key: script.script_key,
+        url: script.url,
+        artifact_sha256: script.source.artifact.sha256,
+        bytes: script.source.artifact.bytes,
+    };
+};
+const buildUnknowns = (input) => [
+    ...(input.unavailable.length === 0
+        ? []
+        : [
+            {
+                dimension: "script_source",
+                reason: "Source artifact was not captured within approved limits",
+                affected_script_keys: input.unavailable,
+            },
+        ]),
+    ...(input.parseFailures === 0
+        ? []
+        : [
+            {
+                dimension: "javascript_ast",
+                reason: "One or more source artifacts could not be parsed",
+                affected_script_keys: input.sourceScripts.map(({ script_key }) => script_key),
+            },
+        ]),
+    ...(input.sourceMaps.status === "not_requested" ||
+        input.sourceMaps.status === "included"
+        ? []
+        : [
+            {
+                dimension: "source_maps",
+                reason: input.sourceMaps.status === "truncated"
+                    ? "Source-map evidence was truncated by approved limits"
+                    : "One or more requested source maps were unavailable or incomplete",
+                affected_script_keys: [
+                    ...new Set([
+                        ...input.sourceMaps.items
+                            .filter(({ status }) => status !== "included")
+                            .map(({ script_key }) => script_key),
+                        ...input.sourceMaps.dropped_script_keys,
+                    ]),
+                ].sort(),
+            },
+        ]),
+];
+const buildCompleteness = (input) => ({
+    status: input.truncated
+        ? "truncated"
+        : input.partial
+            ? "partial"
+            : "complete_within_limits",
+    parsed_scripts: input.parsedScripts,
+    parse_failures: input.parseFailures,
+    visited_ast_nodes: input.visitedNodes,
+    dropped_findings: input.droppedFindings,
+});
+const bundleLimitations = () => [
+    "Static bundle findings are observations or bounded inferences; REA does not execute captured JavaScript.",
+    "String-built routes and endpoints, encrypted configuration, and server-side behavior may remain unknown.",
+    "Page-declared WebMCP metadata is untrusted and is never registered or invoked as an REA tool.",
+];