rea-agents 2.0.0 → 2.1.0

package/dist/domain/javascriptStaticAnalysisBundler.js

@@ -0,0 +1,209 @@
+import * as t from "@babel/types";
+import { collectJavaScriptExports, fingerprintJavaScriptAst, } from "./javascriptAstFingerprint.js";
+import { addBoundedFinding } from "./javascriptStaticAnalysisFindings.js";
+import { argumentValue, calleeName, chunkRuntime, compareCodePoints, factoryRequireName, moduleFactory, modulePropertyName, range, registrationKey, sha256Text, sourceSlice, staticArrayValues, } from "./javascriptStaticAnalysisHelpers.js";
+/** Inspect a bundler registration call and recover its module table. */
+export const inspectBundlerRegistration = (source, call, accumulator, limits) => {
+    const runtime = chunkRuntime(call);
+    const entry = call.arguments[0];
+    if (runtime === undefined || !t.isArrayExpression(entry))
+        return;
+    const chunkIds = entry.elements[0];
+    const table = entry.elements[1];
+    const runtimeValue = runtimeMetadata(entry.elements[2], limits.maxFindings);
+    if (!t.isArrayExpression(chunkIds) || !t.isObjectExpression(table))
+        return;
+    const recovered = recoverBundlerModules(source, table, accumulator, limits);
+    const chunkKeys = staticArrayValues(chunkIds, Math.min(256, limits.maxFindings));
+    if (chunkKeys.omitted > 0) {
+        accumulator.droppedFindings += chunkKeys.omitted;
+        accumulator.structuralTruncation = true;
+    }
+    accumulator.unknownFindings += chunkKeys.unknown;
+    if (runtimeValue.omittedEntryModuleKeys > 0 ||
+        runtimeValue.omittedAsyncChunkKeys > 0 ||
+        recovered.omittedAsyncChunkKeys > 0) {
+        accumulator.droppedFindings +=
+            runtimeValue.omittedEntryModuleKeys +
+                runtimeValue.omittedAsyncChunkKeys +
+                recovered.omittedAsyncChunkKeys;
+        accumulator.structuralTruncation = true;
+    }
+    accumulator.unknownFindings +=
+        runtimeValue.unknownEntryModuleKeys +
+            runtimeValue.unknownAsyncChunkKeys +
+            recovered.unknownAsyncChunkKeys;
+    const asyncChunkKeys = boundedUniqueValues([...runtimeValue.asyncChunkKeys, ...recovered.asyncChunkKeys], Math.min(256, limits.maxFindings));
+    if (asyncChunkKeys.omitted > 0) {
+        accumulator.droppedFindings += asyncChunkKeys.omitted;
+        accumulator.structuralTruncation = true;
+    }
+    const registration = {
+        bundler: runtime.toLowerCase().includes("rspack")
+            ? "rspack"
+            : "webpack",
+        runtime,
+        chunk_keys: chunkKeys.values,
+        omitted_chunk_keys: chunkKeys.omitted,
+        unknown_chunk_keys: chunkKeys.unknown,
+        runtime_require_name: runtimeValue.requireName,
+        runtime_module_cache_status: bundlerModuleCacheStatus(source),
+        entry_module_keys: runtimeValue.entryModuleKeys,
+        omitted_entry_module_keys: runtimeValue.omittedEntryModuleKeys,
+        unknown_entry_module_keys: runtimeValue.unknownEntryModuleKeys,
+        async_chunk_keys: asyncChunkKeys.values,
+        omitted_async_chunk_keys: runtimeValue.omittedAsyncChunkKeys +
+            recovered.omittedAsyncChunkKeys +
+            asyncChunkKeys.omitted,
+        unknown_async_chunk_keys: runtimeValue.unknownAsyncChunkKeys + recovered.unknownAsyncChunkKeys,
+        modules: recovered.modules.sort((left, right) => compareCodePoints(left.module_key, right.module_key)),
+        location: range(call),
+    };
+    addBoundedFinding(accumulator, `registration\0${registrationKey(registration)}`, limits.maxFindings, () => accumulator.registrations.push(registration));
+};
+const recoverBundlerModules = (source, table, accumulator, limits) => {
+    const modules = [];
+    const asyncChunkKeys = [];
+    let omittedAsyncChunkKeys = 0;
+    let unknownAsyncChunkKeys = 0;
+    for (const property of table.properties) {
+        const recovered = recoverBundlerModule(source, property, accumulator, limits);
+        if (recovered === null)
+            continue;
+        modules.push(recovered.module);
+        asyncChunkKeys.push(...recovered.asyncChunkKeys);
+        omittedAsyncChunkKeys += recovered.omittedAsyncChunkKeys;
+        unknownAsyncChunkKeys += recovered.unknownAsyncChunkKeys;
+    }
+    return {
+        modules,
+        asyncChunkKeys,
+        omittedAsyncChunkKeys,
+        unknownAsyncChunkKeys,
+    };
+};
+const recoverBundlerModule = (source, property, accumulator, limits) => {
+    const factory = moduleFactory(property);
+    if (factory === undefined)
+        return null;
+    if (accumulator.moduleCount >= limits.maxModules) {
+        accumulator.droppedFindings += 1;
+        return null;
+    }
+    accumulator.moduleCount += 1;
+    const key = modulePropertyName(property);
+    if (key.startsWith("[computed@") || key.startsWith("[unknown@"))
+        accumulator.unknownFindings += 1;
+    const fingerprint = fingerprintJavaScriptAst(factory, Math.min(limits.maxAstNodes, 100_000));
+    const exportsValue = collectJavaScriptExports(factory, 256);
+    const requireName = factoryRequireName(factory);
+    const asyncChunks = collectBundlerAsyncChunkKeys(factory, requireName, limits.maxFindings);
+    if (fingerprint.truncated || exportsValue.truncated) {
+        accumulator.droppedFindings += 1;
+        accumulator.structuralTruncation = true;
+    }
+    if (typeof factory.start === "number" && typeof factory.end === "number")
+        accumulator.modules.push({
+            start: factory.start,
+            end: factory.end,
+            key,
+            requireName,
+        });
+    return {
+        module: {
+            module_key: key,
+            factory_require_name: requireName,
+            source_sha256: sha256Text(sourceSlice(source, factory)),
+            structural_fingerprint_sha256: fingerprint.truncated
+                ? null
+                : fingerprint.sha256,
+            structural_fingerprint_algorithm: fingerprint.truncated
+                ? null
+                : "babel-ast-v1",
+            structural_fingerprint_status: fingerprint.truncated
+                ? "truncated"
+                : "complete",
+            exports: exportsValue.values,
+            exports_truncated: exportsValue.truncated,
+            location: range(factory),
+        },
+        asyncChunkKeys: asyncChunks.values,
+        omittedAsyncChunkKeys: asyncChunks.omitted,
+        unknownAsyncChunkKeys: asyncChunks.unknown,
+    };
+};
+const runtimeMetadata = (node, maximum) => {
+    if (!isBundlerFunction(node))
+        return {
+            requireName: null,
+            entryModuleKeys: [],
+            omittedEntryModuleKeys: 0,
+            unknownEntryModuleKeys: node === null || node === undefined ? 0 : 1,
+            asyncChunkKeys: [],
+            omittedAsyncChunkKeys: 0,
+            unknownAsyncChunkKeys: 0,
+        };
+    const parameter = node.params[0];
+    const requireName = t.isIdentifier(parameter)
+        ? parameter.name.slice(0, 4_096)
+        : null;
+    if (requireName === null)
+        return {
+            requireName,
+            entryModuleKeys: [],
+            omittedEntryModuleKeys: 0,
+            unknownEntryModuleKeys: 1,
+            asyncChunkKeys: [],
+            omittedAsyncChunkKeys: 0,
+            unknownAsyncChunkKeys: 0,
+        };
+    const entries = collectBundlerEntryModuleKeys(node, requireName, maximum);
+    const asyncChunks = collectBundlerAsyncChunkKeys(node, requireName, maximum);
+    return {
+        requireName,
+        entryModuleKeys: entries.values,
+        omittedEntryModuleKeys: entries.omitted,
+        unknownEntryModuleKeys: entries.unknown,
+        asyncChunkKeys: asyncChunks.values,
+        omittedAsyncChunkKeys: asyncChunks.omitted,
+        unknownAsyncChunkKeys: asyncChunks.unknown,
+    };
+};
+const collectBundlerEntryModuleKeys = (factory, requireName, maximum) => collectBundlerCallArgumentValues(factory, requireName, maximum);
+const collectBundlerAsyncChunkKeys = (factory, requireName, maximum) => requireName === null
+    ? { values: [], omitted: 0, unknown: 0 }
+    : collectBundlerCallArgumentValues(factory, `${requireName}.e`, maximum);
+const collectBundlerCallArgumentValues = (factory, callee, maximum) => {
+    const values = [];
+    let unknown = 0;
+    t.traverseFast(factory, (node) => {
+        if (!t.isCallExpression(node) && !t.isNewExpression(node))
+            return undefined;
+        if (calleeName(node.callee) !== callee)
+            return undefined;
+        const value = argumentValue(node.arguments[0]);
+        if (value === undefined)
+            unknown += 1;
+        else
+            values.push(value);
+        return undefined;
+    });
+    return boundedUniqueValues(values, Math.min(256, maximum), unknown);
+};
+const isBundlerFunction = (node) => t.isFunctionExpression(node) ||
+    t.isArrowFunctionExpression(node) ||
+    t.isObjectMethod(node);
+const boundedUniqueValues = (values, maximum, unknown = 0) => {
+    const bounded = [
+        ...new Set(values.map((value) => value.slice(0, 4_096))),
+    ].sort(compareCodePoints);
+    const retained = bounded.slice(0, Math.max(0, maximum));
+    return {
+        values: retained,
+        omitted: Math.max(0, bounded.length - retained.length),
+        unknown,
+    };
+};
+const bundlerModuleCacheStatus = (source) => /\b(?:__webpack_module_cache__|__rspack_module_cache__|installedModules)\b/u.test(source)
+    ? "observed"
+    : "not-observed";

package/dist/domain/javascriptStaticAnalysisCalls.js

@@ -0,0 +1,180 @@
+import * as t from "@babel/types";
+import { addBoundedFinding, addLocatedFinding, moduleAtOffset, } from "./javascriptStaticAnalysisFindings.js";
+import { STATIC_ROUTE_CALL_NAMES, argumentValue, calleeName, endpointArgument as endpointArgumentHelper, prefixedArgument, propertyName, range, rangeForOffsets, sanitizeCandidate, sourceSlice, staticPath, staticPathResolutionContext, storageKind, stringValue, } from "./javascriptStaticAnalysisHelpers.js";
+/** Inspect one call or new expression for references, endpoints, storage, and roles. */
+export const inspectCall = (node, context) => {
+    const { accumulator } = context;
+    const name = calleeName(node.callee);
+    const first = stringValue(node.arguments[0]);
+    const module = moduleAtOffset(node.start, context.accumulator.modules);
+    const moduleRequireName = module?.requireName ?? null;
+    const requireCall = requireCallSpecifier(node, name, moduleRequireName);
+    if (requireCall !== null)
+        addReference(context, {
+            node,
+            kind: "require",
+            specifier: requireCall.specifier,
+        });
+    const chunkLoad = chunkLoadSpecifier(node, name, moduleRequireName);
+    if (chunkLoad !== null)
+        addReference(context, {
+            node,
+            kind: "dynamic-import",
+            specifier: chunkLoad.specifier,
+        });
+    if (name === "Worker" || name.endsWith(".Worker"))
+        addReference(context, { node, kind: "worker", specifier: first });
+    if (name.endsWith("serviceWorker.register"))
+        addReference(context, { node, kind: "service-worker", specifier: first });
+    inspectEndpointCall(node, name, first, context);
+    inspectStorageCall(node, name, first, context);
+    if (name.endsWith("loadFile") && first !== undefined)
+        addLocatedFinding(context, {
+            collection: accumulator.roles,
+            key: `role\0renderer\0${first}`,
+            node,
+            value: {
+                role: "renderer",
+                path: first,
+                resolution_context: "filesystem-expression",
+                mechanism: `call:${name}`,
+                module_key: null,
+                location: range(node),
+            },
+        });
+    if (name.endsWith("loadURL") && first !== undefined)
+        addLocatedFinding(context, {
+            collection: accumulator.roles,
+            key: `role\0renderer\0${first}`,
+            node,
+            value: {
+                role: "renderer",
+                path: first,
+                resolution_context: "module-specifier",
+                mechanism: `call:${name}`,
+                module_key: null,
+                location: range(node),
+            },
+        });
+};
+const requireCallSpecifier = (node, name, moduleRequireName) => {
+    if (name === "require" || name.endsWith(".require"))
+        return { specifier: argumentValue(node.arguments[0]) };
+    if (name === "__webpack_require__" || name === moduleRequireName)
+        return { specifier: argumentValue(node.arguments[0]) };
+    if (name === "__webpack_require__.bind" ||
+        (moduleRequireName !== null && name === `${moduleRequireName}.bind`))
+        return { specifier: argumentValue(node.arguments[1]) };
+    return null;
+};
+const chunkLoadSpecifier = (node, name, moduleRequireName) => {
+    if (name !== "__webpack_require__.e" &&
+        (moduleRequireName === null || name !== `${moduleRequireName}.e`))
+        return null;
+    return { specifier: prefixedArgument("chunk:", node.arguments[0]) };
+};
+const inspectEndpointCall = (node, name, first, context) => {
+    const route = STATIC_ROUTE_CALL_NAMES.some((candidate) => name === candidate || name.endsWith(`.${candidate}`));
+    if (route && first !== undefined)
+        addEndpoint(context, {
+            node,
+            kind: "route",
+            value: first,
+            mechanism: `call:${name}`,
+        });
+    const endpoint = endpointArgumentHelper(name, node.arguments);
+    if (endpoint !== undefined)
+        addEndpoint(context, {
+            node,
+            kind: "network",
+            value: endpoint,
+            mechanism: `call:${name}`,
+        });
+};
+export const inspectRouteProperty = (node, context) => {
+    const key = propertyName(node.key);
+    if ((key === "path" || key === "route") && t.isStringLiteral(node.value))
+        addEndpoint(context, {
+            node,
+            kind: "route",
+            value: node.value.value,
+            mechanism: `property:${key}`,
+        });
+};
+export const inspectRoleProperty = (node, context) => {
+    if (propertyName(node.key) !== "preload")
+        return;
+    const path = staticPath(node.value);
+    if (path === undefined)
+        return;
+    addLocatedFinding(context, {
+        collection: context.accumulator.roles,
+        key: `role\0preload\0${path}`,
+        node,
+        value: {
+            role: "preload",
+            path,
+            resolution_context: staticPathResolutionContext(node.value),
+            mechanism: "property:preload",
+            module_key: null,
+            location: range(node),
+        },
+    });
+};
+const inspectStorageCall = (node, name, first, context) => {
+    const storage = storageKind(name);
+    if (storage === undefined)
+        return;
+    addLocatedFinding(context, {
+        collection: context.accumulator.storage,
+        key: `storage\0${storage}\0${first ?? ""}`,
+        node,
+        value: {
+            kind: storage,
+            name: first ?? null,
+            mechanism: `call:${name}`,
+            module_key: null,
+            location: range(node),
+        },
+    });
+};
+export const addReference = (context, input) => {
+    const boundedSpecifier = input.specifier?.slice(0, 4_096) ?? null;
+    const expression = boundedSpecifier === null
+        ? sourceSlice(context.source, input.node).slice(0, 4_096)
+        : null;
+    addLocatedFinding(context, {
+        collection: context.accumulator.references,
+        key: `reference\0${input.kind}\0${boundedSpecifier ?? expression}`,
+        node: input.node,
+        value: {
+            kind: input.kind,
+            specifier: boundedSpecifier,
+            expression,
+            module_key: null,
+            location: range(input.node),
+        },
+    });
+};
+const addEndpoint = (context, input) => addLocatedFinding(context, {
+    collection: context.accumulator.endpoints,
+    key: `endpoint\0${input.kind}\0${input.value}`,
+    node: input.node,
+    value: {
+        kind: input.kind,
+        value: sanitizeCandidate(input.value),
+        mechanism: input.mechanism,
+        module_key: null,
+        location: range(input.node),
+    },
+});
+export const addSourceMapDirectives = (source, accumulator, maximum) => {
+    for (const match of source.matchAll(/\/\/[#@]\s*sourceMappingURL\s*=\s*([^\s]+)/gu)) {
+        const declared = match[1]?.slice(0, 4_096);
+        if (declared === undefined)
+            continue;
+        const start = match.index;
+        const location = rangeForOffsets(source, start, start + match[0].length);
+        addBoundedFinding(accumulator, `source-map\0${declared}`, maximum, () => accumulator.sourceMaps.push({ declared_url: declared, location }));
+    }
+};

package/dist/domain/javascriptStaticAnalysisHelpers.js

@@ -101,6 +101,10 @@ export const staticArrayValues = (array, maximum) => {
 };
 /** Resolve a bounded path composed only from inert literal syntax. */
 export const staticPath = (node) => staticPathAt(node, 0);
+/** Classify whether inert path syntax is a module specifier or file expression. */
+export const staticPathResolutionContext = (node) => isFilesystemPathExpression(node, 0)
+    ? "filesystem-expression"
+    : "module-specifier";
 const staticPathAt = (node, depth) => {
     if (depth >= 128)
         return undefined;
@@ -124,12 +128,23 @@ const staticPathAt = (node, depth) => {
 const staticCallPath = (node, depth) => {
     const name = calleeName(node.callee);
     if (name === "URL" || name.endsWith(".URL"))
-        return stringValue(node.arguments[0]);
+        return isFileIdentity(argumentNode(node.arguments[1]))
+            ? stringValue(node.arguments[0])
+            : undefined;
+    if (name === "fileURLToPath" || name.endsWith(".fileURLToPath")) {
+        const argument = argumentNode(node.arguments[0]);
+        return argument === undefined
+            ? undefined
+            : staticPathAt(argument, depth + 1);
+    }
+    if ((name === "dirname" || name.endsWith(".dirname")) &&
+        isFileIdentity(argumentNode(node.arguments[0])))
+        return "";
     if (!name.endsWith(".join") && !name.endsWith(".resolve") && name !== "join")
         return undefined;
     const parts = [];
     for (const argument of node.arguments) {
-        if (t.isIdentifier(argument, { name: "__dirname" }))
+        if (isDirectoryIdentity(argumentNode(argument)))
             continue;
         const value = t.isNode(argument)
             ? staticPathAt(argument, depth + 1)
@@ -140,6 +155,60 @@ const staticCallPath = (node, depth) => {
     }
     return parts.length === 0 ? undefined : posix.join(...parts).slice(0, 4_096);
 };
+const isFilesystemPathExpression = (node, depth) => {
+    if (depth >= 128)
+        return false;
+    if (t.isStringLiteral(node))
+        return node.value.startsWith("/");
+    if (isFileIdentity(node) || isDirectoryIdentity(node))
+        return true;
+    if (t.isBinaryExpression(node, { operator: "+" }))
+        return (isFilesystemPathExpression(node.left, depth + 1) ||
+            isFilesystemPathExpression(node.right, depth + 1));
+    if (t.isCallExpression(node) || t.isNewExpression(node)) {
+        const name = calleeName(node.callee);
+        if (name === "URL" || name.endsWith(".URL"))
+            return isFileIdentity(argumentNode(node.arguments[1]));
+        if (name === "fileURLToPath" || name.endsWith(".fileURLToPath"))
+            return node.arguments.some((argument) => {
+                const value = argumentNode(argument);
+                return (value !== undefined && isFilesystemPathExpression(value, depth + 1));
+            });
+        return node.arguments.some((argument) => {
+            const value = argumentNode(argument);
+            return (value !== undefined && isFilesystemPathExpression(value, depth + 1));
+        });
+    }
+    return false;
+};
+const isDirectoryIdentity = (node) => {
+    if (t.isIdentifier(node, { name: "__dirname" }))
+        return true;
+    if (!t.isCallExpression(node) && !t.isNewExpression(node))
+        return false;
+    const name = calleeName(node.callee);
+    if (name === "URL" || name.endsWith(".URL"))
+        return isFileIdentity(argumentNode(node.arguments[1]));
+    return ((name === "dirname" || name.endsWith(".dirname")) &&
+        isFileIdentity(argumentNode(node.arguments[0])));
+};
+const isFileIdentity = (node) => {
+    if (t.isIdentifier(node, { name: "__filename" }))
+        return true;
+    if (node === undefined)
+        return false;
+    if (t.isMemberExpression(node) &&
+        t.isMetaProperty(node.object) &&
+        node.object.meta.name === "import" &&
+        node.object.property.name === "meta" &&
+        propertyName(node.property) === "url")
+        return true;
+    if (!t.isCallExpression(node))
+        return false;
+    const name = calleeName(node.callee);
+    return ((name === "fileURLToPath" || name.endsWith(".fileURLToPath")) &&
+        isFileIdentity(argumentNode(node.arguments[0])));
+};
 /** Select the literal URL argument for recognized network callees. */
 export const endpointArgument = (name, args) => {
     if (name === "fetch" || name.endsWith(".fetch") || name === "WebSocket")

package/dist/domain/knownPageCoverage.js

@@ -0,0 +1,21 @@
+/**
+ * Assess source-page and downstream-projection completeness without treating an
+ * unreturned row as absent. `includedCount` is the number retained downstream.
+ */
+export const assessKnownPageCoverage = (page, includedCount = page.items.length) => {
+    const observedCount = Math.min(page.total, page.returned, page.items.length);
+    const retainedCount = Math.min(observedCount, Math.max(0, Math.floor(includedCount)));
+    const sourceOmittedCount = Math.max(0, page.total - observedCount);
+    const sourceComplete = page.complete &&
+        page.offset === 0 &&
+        page.returned === page.total &&
+        sourceOmittedCount === 0;
+    const omittedCount = Math.max(0, page.total - retainedCount);
+    return {
+        complete: sourceComplete && omittedCount === 0,
+        sourceComplete,
+        includedCount: retainedCount,
+        omittedCount,
+        sourceOmittedCount,
+    };
+};