rea-agents 1.6.0 → 2.0.0

package/dist/domain/javascriptStaticAnalysis.js

@@ -0,0 +1,346 @@
+import { parse } from "@babel/parser";
+import * as t from "@babel/types";
+import { collectJavaScriptExports, fingerprintJavaScriptAst, } from "./javascriptAstFingerprint.js";
+import { STATIC_ROUTE_CALL_NAMES, argumentValue, calleeName, chunkRuntime, compareCodePoints, detectVendors, endpointArgument, failedJavaScriptStaticAnalysis, factoryRequireName, moduleFactory, modulePropertyName, prefixedArgument, propertyName, range, rangeForOffsets, registrationKey, sanitizeCandidate, sha256Text, sortedUnique, sourceSlice, staticArrayValues, staticPath, storageKind, stringValue, } from "./javascriptStaticAnalysisHelpers.js";
+import { createJavaScriptAnalysisAccumulator, } from "./javascriptStaticAnalysisState.js";
+import { addBoundedFinding, addLocatedFinding, finalizeLocatedFindings, moduleAtOffset, } from "./javascriptStaticAnalysisFindings.js";
+import { inspectElectronStaticNode } from "./electronStaticAnalysis.js";
+/** Parse one bounded JavaScript artifact and recover static structure only. */
+export const analyzeJavaScriptStaticSource = (source, limits) => {
+    let file;
+    try {
+        file = parse(source, {
+            sourceType: "unambiguous",
+            errorRecovery: true,
+            plugins: ["jsx", "typescript"],
+        });
+    }
+    catch {
+        return failedJavaScriptStaticAnalysis();
+    }
+    const accumulator = createJavaScriptAnalysisAccumulator();
+    traverseStaticSource(source, file, accumulator, limits);
+    addSourceMapDirectives(source, accumulator, limits.maxFindings);
+    return finalizeStaticAnalysis(source, file, accumulator, limits);
+};
+const traverseStaticSource = (source, file, accumulator, limits) => {
+    if (limits.now() > limits.deadline)
+        accumulator.truncated = true;
+    if (!accumulator.truncated)
+        t.traverseFast(file, (node) => {
+            accumulator.visitedNodes += 1;
+            if (accumulator.visitedNodes > limits.maxAstNodes ||
+                (accumulator.visitedNodes % 1_024 === 0 &&
+                    limits.now() > limits.deadline)) {
+                accumulator.truncated = true;
+                return t.traverseFast.stop;
+            }
+            inspectNode(source, node, accumulator, limits);
+            return undefined;
+        });
+};
+const finalizeStaticAnalysis = (source, file, accumulator, limits) => {
+    const parserErrors = file.errors.length;
+    const limitations = [
+        ...(parserErrors === 0
+            ? []
+            : [
+                "The parser recovered from syntax errors; affected facts are partial.",
+            ]),
+        ...(accumulator.truncated
+            ? ["AST analysis stopped at the configured node or time bound."]
+            : []),
+        ...(accumulator.droppedFindings === 0
+            ? []
+            : ["Static findings were truncated at the configured finding bound."]),
+        ...(accumulator.structuralTruncation
+            ? ["Bundler metadata reached a per-record structural bound."]
+            : []),
+        ...(accumulator.unknownFindings === 0
+            ? []
+            : [
+                "One or more static keys, expressions, or Electron boundary values were dynamic and remain unknown.",
+            ]),
+        "JavaScript syntax was parsed as data and was never evaluated.",
+    ];
+    return {
+        parse_status: accumulator.truncated || accumulator.droppedFindings > 0
+            ? "truncated"
+            : parserErrors > 0 || accumulator.unknownFindings > 0
+                ? "partial"
+                : "complete",
+        parse_error_count: parserErrors,
+        visited_ast_nodes: Math.min(accumulator.visitedNodes, limits.maxAstNodes),
+        dropped_findings: accumulator.droppedFindings,
+        references: finalizeLocatedFindings(accumulator.references, accumulator.modules),
+        endpoints: finalizeLocatedFindings(accumulator.endpoints, accumulator.modules),
+        storage: finalizeLocatedFindings(accumulator.storage, accumulator.modules),
+        bundler_registrations: sortedUnique(accumulator.registrations, registrationKey),
+        role_paths: finalizeLocatedFindings(accumulator.roles, accumulator.modules),
+        source_map_urls: accumulator.sourceMaps,
+        vendors: detectVendors(source),
+        electron: {
+            browser_windows: finalizeLocatedFindings(accumulator.browserWindows, accumulator.modules),
+            context_bridge_apis: finalizeLocatedFindings(accumulator.contextBridgeApis, accumulator.modules),
+            ipc: finalizeLocatedFindings(accumulator.ipc, accumulator.modules),
+            sender_validations: finalizeLocatedFindings(accumulator.senderValidations, accumulator.modules),
+            utility_processes: finalizeLocatedFindings(accumulator.utilityProcesses, accumulator.modules),
+            native_addon_bindings: finalizeLocatedFindings(accumulator.nativeAddonBindings, accumulator.modules),
+        },
+        limitations,
+    };
+};
+const inspectNode = (source, node, accumulator, limits) => {
+    const findings = {
+        source,
+        accumulator,
+        maximum: limits.maxFindings,
+    };
+    inspectElectronStaticNode(node, findings);
+    if (t.isCallExpression(node)) {
+        inspectBundlerRegistration(source, node, accumulator, limits);
+        inspectCall(node, findings);
+    }
+    else if (t.isNewExpression(node))
+        inspectCall(node, findings);
+    if ((t.isImportDeclaration(node) || t.isExportAllDeclaration(node)) &&
+        node.source !== undefined)
+        addReference(findings, {
+            node,
+            kind: "static-import",
+            specifier: node.source.value,
+        });
+    else if (t.isExportNamedDeclaration(node) && node.source != null)
+        addReference(findings, {
+            node,
+            kind: "static-import",
+            specifier: node.source.value,
+        });
+    else if (t.isImportExpression(node))
+        addReference(findings, {
+            node,
+            kind: "dynamic-import",
+            specifier: stringValue(node.source),
+        });
+    if (t.isObjectProperty(node)) {
+        inspectRouteProperty(node, findings);
+        inspectRoleProperty(node, findings);
+    }
+};
+const inspectCall = (node, context) => {
+    const { accumulator } = context;
+    const name = calleeName(node.callee);
+    const first = stringValue(node.arguments[0]);
+    const module = moduleAtOffset(node.start, accumulator.modules);
+    const moduleRequire = module?.requireName !== null && name === module?.requireName;
+    if (name === "require" ||
+        name.endsWith(".require") ||
+        name.includes("__webpack_require__") ||
+        moduleRequire)
+        addReference(context, {
+            node,
+            kind: "require",
+            specifier: argumentValue(node.arguments[0]),
+        });
+    if (name.endsWith(".e") && name.includes("require"))
+        addReference(context, {
+            node,
+            kind: "dynamic-import",
+            specifier: prefixedArgument("chunk:", node.arguments[0]),
+        });
+    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,
+                mechanism: `call:${name}`,
+                module_key: null,
+                location: range(node),
+            },
+        });
+};
+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];
+    if (!t.isArrayExpression(chunkIds) || !t.isObjectExpression(table))
+        return;
+    const modules = [];
+    for (const property of table.properties) {
+        const factory = moduleFactory(property);
+        if (factory === undefined)
+            continue;
+        if (accumulator.moduleCount >= limits.maxModules) {
+            accumulator.droppedFindings += 1;
+            continue;
+        }
+        accumulator.moduleCount += 1;
+        const key = modulePropertyName(property);
+        if (key.startsWith("[computed@") || key.startsWith("[unknown@"))
+            accumulator.unknownFindings += 1;
+        const exactSource = sourceSlice(source, factory);
+        const fingerprint = fingerprintJavaScriptAst(factory, Math.min(limits.maxAstNodes, 100_000));
+        const exportsValue = collectJavaScriptExports(factory, 256);
+        if (fingerprint.truncated || exportsValue.truncated) {
+            accumulator.droppedFindings += 1;
+            accumulator.structuralTruncation = true;
+        }
+        modules.push({
+            module_key: key,
+            source_sha256: sha256Text(exactSource),
+            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),
+        });
+        if (typeof factory.start === "number" && typeof factory.end === "number")
+            accumulator.modules.push({
+                start: factory.start,
+                end: factory.end,
+                key,
+                requireName: factoryRequireName(factory),
+            });
+    }
+    const chunkKeys = staticArrayValues(chunkIds, Math.min(256, limits.maxFindings));
+    if (chunkKeys.omitted > 0) {
+        accumulator.droppedFindings += chunkKeys.omitted;
+        accumulator.structuralTruncation = true;
+    }
+    accumulator.unknownFindings += chunkKeys.unknown;
+    const registration = {
+        bundler: runtime.toLowerCase().includes("rspack")
+            ? "rspack"
+            : "webpack",
+        runtime,
+        chunk_keys: chunkKeys.values,
+        omitted_chunk_keys: chunkKeys.omitted,
+        unknown_chunk_keys: chunkKeys.unknown,
+        modules: 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 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 = endpointArgument(name, node.arguments);
+    if (endpoint !== undefined)
+        addEndpoint(context, {
+            node,
+            kind: "network",
+            value: endpoint,
+            mechanism: `call:${name}`,
+        });
+};
+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}`,
+        });
+};
+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,
+            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),
+        },
+    });
+};
+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),
+    },
+});
+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/javascriptStaticAnalysisFindings.js

@@ -0,0 +1,39 @@
+/** Add one module-attributable finding under the shared global finding bound. */
+export const addLocatedFinding = (context, input) => addBoundedFinding(context.accumulator, `${input.key}\0${String(input.node.start)}`, context.maximum, () => input.collection.push({
+    offset: input.node.start ?? -1,
+    value: input.value,
+}));
+/** Reserve one deterministic finding key before mutating an accumulator. */
+export const addBoundedFinding = (accumulator, key, maximum, add) => {
+    if (accumulator.seen.has(key))
+        return;
+    if (accumulatedFindingCount(accumulator) >= maximum) {
+        accumulator.droppedFindings += 1;
+        return;
+    }
+    accumulator.seen.add(key);
+    add();
+};
+/** Attach recovered bundle-module ownership to findings after traversal. */
+export const finalizeLocatedFindings = (values, modules) => values.map(({ offset, value }) => ({
+    ...value,
+    module_key: moduleAtOffset(offset, modules)?.key ?? null,
+}));
+/** Locate the recovered bundle factory containing one exact source offset. */
+export const moduleAtOffset = (offset, modules) => {
+    if (offset === null || offset === undefined)
+        return undefined;
+    return modules.find(({ start, end }) => offset >= start && offset <= end);
+};
+const accumulatedFindingCount = (accumulator) => accumulator.references.length +
+    accumulator.endpoints.length +
+    accumulator.storage.length +
+    accumulator.roles.length +
+    accumulator.sourceMaps.length +
+    accumulator.registrations.length +
+    accumulator.browserWindows.length +
+    accumulator.contextBridgeApis.length +
+    accumulator.ipc.length +
+    accumulator.senderValidations.length +
+    accumulator.utilityProcesses.length +
+    accumulator.nativeAddonBindings.length;

package/dist/domain/javascriptStaticAnalysisHelpers.js

@@ -0,0 +1,274 @@
+import { createHash } from "node:crypto";
+import { posix } from "node:path";
+import * as t from "@babel/types";
+import { sanitizeBrowserUrl } from "./browserObservation.js";
+/** Explicit result for source text that Babel cannot parse. */
+export const failedJavaScriptStaticAnalysis = () => ({
+    parse_status: "failed",
+    parse_error_count: 1,
+    visited_ast_nodes: 0,
+    dropped_findings: 0,
+    references: [],
+    endpoints: [],
+    storage: [],
+    bundler_registrations: [],
+    role_paths: [],
+    source_map_urls: [],
+    vendors: [],
+    electron: {
+        browser_windows: [],
+        context_bridge_apis: [],
+        ipc: [],
+        sender_validations: [],
+        utility_processes: [],
+        native_addon_bindings: [],
+    },
+    limitations: [
+        "JavaScript source could not be parsed; absence of findings is not evidence of absence.",
+        "JavaScript syntax was parsed as data and was never evaluated.",
+    ],
+});
+/** Normalize one Babel call/new argument into the inert node shared by inspectors. */
+export const argumentNode = (argument) => argument !== null && t.isNode(argument) ? argument : undefined;
+/** Recognize the bounded runtime name for a Webpack/Rspack push call. */
+export const chunkRuntime = (call) => {
+    if (!t.isMemberExpression(call.callee) &&
+        !t.isOptionalMemberExpression(call.callee))
+        return undefined;
+    if (propertyName(call.callee.property) !== "push")
+        return undefined;
+    return findChunkRuntime(call.callee.object, 0);
+};
+const findChunkRuntime = (node, depth) => {
+    if (depth >= 128)
+        return undefined;
+    if (t.isIdentifier(node) && /(?:webpack|rspack)Chunk/iu.test(node.name))
+        return node.name.slice(0, 4_096);
+    if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
+        const property = propertyName(node.property);
+        if (/(?:webpack|rspack)Chunk/iu.test(property))
+            return property.slice(0, 4_096);
+        return t.isNode(node.object)
+            ? findChunkRuntime(node.object, depth + 1)
+            : undefined;
+    }
+    if (t.isAssignmentExpression(node))
+        return (findChunkRuntime(node.left, depth + 1) ??
+            findChunkRuntime(node.right, depth + 1));
+    if (t.isLogicalExpression(node) || t.isBinaryExpression(node))
+        return (findChunkRuntime(node.left, depth + 1) ??
+            findChunkRuntime(node.right, depth + 1));
+    if (t.isParenthesizedExpression(node) || t.isTSAsExpression(node))
+        return findChunkRuntime(node.expression, depth + 1);
+    return undefined;
+};
+/** Return a literal function factory from one module-table property. */
+export const moduleFactory = (property) => {
+    if (t.isObjectMethod(property))
+        return property;
+    if (t.isObjectProperty(property) &&
+        (t.isFunctionExpression(property.value) ||
+            t.isArrowFunctionExpression(property.value)))
+        return property.value;
+    return undefined;
+};
+/** Derive a bounded literal or explicitly computed module key. */
+export const modulePropertyName = (property) => t.isObjectMethod(property) || t.isObjectProperty(property)
+    ? property.computed &&
+        !t.isStringLiteral(property.key) &&
+        !t.isNumericLiteral(property.key)
+        ? `[computed@${String(property.start ?? -1)}]`
+        : propertyName(property.key).slice(0, 4_096) ||
+            `[unknown@${String(property.start ?? -1)}]`
+    : `[unknown@${String(property.start ?? -1)}]`;
+/** Read the factory-local bundler require parameter when declared. */
+export const factoryRequireName = (factory) => {
+    const parameter = factory.params[2];
+    return t.isIdentifier(parameter) ? parameter.name.slice(0, 4_096) : null;
+};
+/** Collect bounded unique literal values and explicit omissions from an array. */
+export const staticArrayValues = (array, maximum) => {
+    const staticValues = array.elements.flatMap((element) => {
+        const value = argumentValue(element);
+        return value === undefined ? [] : [value.slice(0, 4_096)];
+    });
+    const values = [...new Set(staticValues)].sort(compareCodePoints);
+    return {
+        values: values.slice(0, maximum),
+        omitted: Math.max(0, values.length - maximum),
+        unknown: array.elements.length - staticValues.length,
+    };
+};
+/** Resolve a bounded path composed only from inert literal syntax. */
+export const staticPath = (node) => staticPathAt(node, 0);
+const staticPathAt = (node, depth) => {
+    if (depth >= 128)
+        return undefined;
+    if (t.isStringLiteral(node))
+        return node.value.slice(0, 4_096);
+    if (t.isTemplateLiteral(node) && node.expressions.length === 0) {
+        const value = node.quasis[0]?.value.cooked ?? node.quasis[0]?.value.raw;
+        return value?.slice(0, 4_096);
+    }
+    if (t.isBinaryExpression(node, { operator: "+" })) {
+        const left = staticPathAt(node.left, depth + 1);
+        const right = staticPathAt(node.right, depth + 1);
+        return left === undefined || right === undefined
+            ? undefined
+            : `${left}${right}`.slice(0, 4_096);
+    }
+    if (t.isCallExpression(node) || t.isNewExpression(node))
+        return staticCallPath(node, depth);
+    return undefined;
+};
+const staticCallPath = (node, depth) => {
+    const name = calleeName(node.callee);
+    if (name === "URL" || name.endsWith(".URL"))
+        return stringValue(node.arguments[0]);
+    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" }))
+            continue;
+        const value = t.isNode(argument)
+            ? staticPathAt(argument, depth + 1)
+            : undefined;
+        if (value === undefined)
+            return undefined;
+        parts.push(value);
+    }
+    return parts.length === 0 ? undefined : posix.join(...parts).slice(0, 4_096);
+};
+/** Select the literal URL argument for recognized network callees. */
+export const endpointArgument = (name, args) => {
+    if (name === "fetch" || name.endsWith(".fetch") || name === "WebSocket")
+        return stringValue(args[0]);
+    if (name.endsWith(".open") && stringValue(args[1]) !== undefined)
+        return stringValue(args[1]);
+    if (["get", "post", "put", "patch", "delete", "request"].some((method) => name === method || name.endsWith(`.${method}`)))
+        return stringValue(args[0]);
+    if (name.endsWith("loadURL"))
+        return stringValue(args[0]);
+    return undefined;
+};
+/** Classify a recognized storage API call name. */
+export const storageKind = (name) => {
+    if (name.includes("localStorage."))
+        return "local-storage";
+    if (name.includes("sessionStorage."))
+        return "session-storage";
+    if (name.endsWith("indexedDB.open"))
+        return "indexed-db";
+    if (name.endsWith("caches.open"))
+        return "cache-storage";
+    if (name === "Database" || name.endsWith(".Database"))
+        return "sqlite";
+    return undefined;
+};
+/** Produce a dotted bounded callee name from member syntax. */
+export const calleeName = (node) => calleeNameAt(node, 0);
+const calleeNameAt = (node, depth) => {
+    if (depth >= 128)
+        return "[deep]";
+    if (t.isIdentifier(node))
+        return node.name.slice(0, 4_096);
+    if (t.isImport(node))
+        return "import";
+    if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
+        const object = t.isNode(node.object)
+            ? calleeNameAt(node.object, depth + 1)
+            : "";
+        const property = propertyName(node.property);
+        return (object === "" ? property : `${object}.${property}`).slice(0, 4_096);
+    }
+    return "";
+};
+/** Read a literal property name without evaluating computed syntax. */
+export const propertyName = (node) => {
+    if (t.isIdentifier(node))
+        return node.name.slice(0, 4_096);
+    if (t.isStringLiteral(node) || t.isNumericLiteral(node))
+        return String(node.value).slice(0, 4_096);
+    return "";
+};
+/** Return a string literal value without evaluating an expression. */
+export const stringValue = (node) => t.isStringLiteral(node) ? node.value.slice(0, 4_096) : undefined;
+/** Return a string or numeric argument literal. */
+export const argumentValue = (node) => {
+    if (t.isStringLiteral(node) || t.isNumericLiteral(node))
+        return String(node.value).slice(0, 4_096);
+    return undefined;
+};
+/** Prefix a static argument value when one is available. */
+export const prefixedArgument = (prefix, node) => {
+    const value = argumentValue(node);
+    return value === undefined ? undefined : `${prefix}${value}`;
+};
+/** Retain the exact bounded source span represented by an AST node. */
+export const sourceSlice = (source, node) => typeof node.start !== "number" || typeof node.end !== "number"
+    ? ""
+    : source.slice(node.start, node.end);
+/** Convert Babel locations into the stable graph source-range shape. */
+export const range = (node) => ({
+    start: {
+        line: node.loc?.start.line ?? 1,
+        column: node.loc?.start.column ?? 0,
+    },
+    end: {
+        line: node.loc?.end.line ?? node.loc?.start.line ?? 1,
+        column: node.loc?.end.column ?? node.loc?.start.column ?? 0,
+    },
+});
+/** Convert exact text offsets into a source range. */
+export const rangeForOffsets = (source, start, end) => ({
+    start: pointForOffset(source, start),
+    end: pointForOffset(source, end),
+});
+const pointForOffset = (source, offset) => {
+    const before = source.slice(0, offset);
+    const lines = before.split("\n");
+    return { line: lines.length, column: lines.at(-1)?.length ?? 0 };
+};
+/** Observe known bundler/framework marker strings without claiming dependency use. */
+export const detectVendors = (source) => vendorPatterns.flatMap(({ name, patterns }) => patterns.some((pattern) => source.includes(pattern)) ? [name] : []);
+/** Remove credentials, fragments, and query values from endpoint candidates. */
+export const sanitizeCandidate = (value) => {
+    const bounded = value.slice(0, 4_096);
+    try {
+        const parsed = new URL(bounded, "https://rea.invalid");
+        const sanitized = sanitizeBrowserUrl(parsed.href).url;
+        return parsed.origin === "https://rea.invalid"
+            ? sanitized.replace("https://rea.invalid", "")
+            : sanitized;
+    }
+    catch {
+        return bounded.split("#", 1)[0]?.split("?", 1)[0] ?? "";
+    }
+};
+/** Commit the static semantic content used to deduplicate registrations. */
+export const registrationKey = (registration) => `${registration.runtime}\0${registration.chunk_keys.join("\0")}\0${String(registration.omitted_chunk_keys)}\0${String(registration.unknown_chunk_keys)}\0${registration.modules.map(({ module_key: key, source_sha256: digest }) => `${key}:${digest}`).join("\0")}`;
+/** Sort values by a deterministic unique semantic key. */
+export const sortedUnique = (values, key) => [...new Map(values.map((value) => [key(value), value])).values()].sort((left, right) => compareCodePoints(key(left), key(right)));
+/** Hash exact UTF-8 source text. */
+export const sha256Text = (value) => createHash("sha256").update(value).digest("hex");
+/** Compare strings by Unicode code point for canonical ordering. */
+export const compareCodePoints = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+/** Recognized route-construction call suffixes. */
+export const STATIC_ROUTE_CALL_NAMES = [
+    "route",
+    "addRoute",
+    "useRoutes",
+    "createBrowserRouter",
+    "createHashRouter",
+];
+const vendorPatterns = [
+    { name: "webpack", patterns: ["__webpack_require__", "webpackChunk"] },
+    { name: "Rspack", patterns: ["__webpack_require__.f", "rspackChunk"] },
+    { name: "Vite", patterns: ["__vite__", "import.meta.hot"] },
+    { name: "React", patterns: ["React.createElement", "react/jsx-runtime"] },
+    { name: "Vue", patterns: ["__VUE__", "createApp("] },
+    { name: "Next.js", patterns: ["__NEXT_DATA__", "/_next/"] },
+    { name: "Angular", patterns: ["ɵɵdefineComponent"] },
+    { name: "Svelte", patterns: ["svelte/internal"] },
+];

package/dist/domain/javascriptStaticAnalysisState.js

@@ -0,0 +1,23 @@
+/** Create isolated mutable state for one bounded source analysis. */
+export const createJavaScriptAnalysisAccumulator = () => ({
+    references: [],
+    endpoints: [],
+    storage: [],
+    roles: [],
+    sourceMaps: [],
+    registrations: [],
+    browserWindows: [],
+    contextBridgeApis: [],
+    ipc: [],
+    senderValidations: [],
+    utilityProcesses: [],
+    nativeAddonBindings: [],
+    modules: [],
+    seen: new Set(),
+    visitedNodes: 0,
+    droppedFindings: 0,
+    moduleCount: 0,
+    unknownFindings: 0,
+    structuralTruncation: false,
+    truncated: false,
+});

package/dist/domain/javascriptStaticAnalysisTypes.js

@@ -0,0 +1 @@
+export {};