reverseport 0.0.0-stage → 1.2.0

package/dist/domain/javascript/javascriptStaticAnalysisHelpers.js

@@ -0,0 +1,561 @@
+import { createHash } from "node:crypto";
+import { posix } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as t from "@babel/types";
+import { readExactJavaScriptLiteral, semanticStaticPropertyKey, semanticStaticPropertyName, unwrapJavaScriptExpression, } from "./javascriptAstValues.js";
+import { compareUnicodeCodePoints, compositeKey, } from "../unicodeCodePointOrder.js";
+/** Explicit result for source text that Babel cannot parse. */
+export const failedJavaScriptStaticAnalysis = () => ({
+    parse_status: "failed",
+    parse_error_count: 1,
+    visited_ast_nodes: 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 runtime name for a Webpack/Rspack push call. */
+export const chunkRuntime = (call) => {
+    if (!t.isMemberExpression(call.callee) &&
+        !t.isOptionalMemberExpression(call.callee))
+        return undefined;
+    if (semanticStaticPropertyName(call.callee.property, call.callee.computed) !==
+        "push")
+        return undefined;
+    return findChunkRuntime(call.callee.object);
+};
+const findChunkRuntime = (node) => {
+    const pending = [node];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined)
+            continue;
+        if (t.isIdentifier(current) &&
+            /(?:webpack|rspack)Chunk/iu.test(current.name))
+            return current.name;
+        if (t.isMemberExpression(current) ||
+            t.isOptionalMemberExpression(current)) {
+            const property = semanticStaticPropertyName(current.property, current.computed);
+            if (/(?:webpack|rspack)Chunk/iu.test(property))
+                return property;
+            if (t.isNode(current.object))
+                pending.push(current.object);
+            continue;
+        }
+        if (t.isAssignmentExpression(current)) {
+            pending.push(current.right, current.left);
+            continue;
+        }
+        if (t.isLogicalExpression(current) || t.isBinaryExpression(current)) {
+            pending.push(current.right, current.left);
+            continue;
+        }
+        const unwrapped = unwrapJavaScriptExpression(current).node;
+        if (unwrapped !== current)
+            pending.push(unwrapped);
+    }
+    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 literal or explicitly computed module key. */
+export const modulePropertyName = (property) => {
+    if (!t.isObjectMethod(property) && !t.isObjectProperty(property))
+        return `[unknown@${String(property.start ?? -1)}]`;
+    const key = semanticStaticPropertyKey(property.key, property.computed);
+    if (key !== null)
+        return key;
+    return property.computed
+        ? `[computed@${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 : null;
+};
+/** Collect all unique static literal values from an array. */
+export const staticArrayValues = (array) => {
+    const staticValues = array.elements.flatMap((element) => {
+        const value = argumentValue(element);
+        return value === undefined ? [] : [value];
+    });
+    const values = [...new Set(staticValues)].sort(compareUnicodeCodePoints);
+    return {
+        values,
+        unknown: array.elements.length - staticValues.length,
+    };
+};
+/** Classify whether inert path syntax is a module specifier or file expression. */
+export const staticPathResolutionContext = (node) => isFilesystemPathExpression(node)
+    ? "filesystem-expression"
+    : "module-specifier";
+/** Resolve a path composed only from inert literal syntax. */
+export const staticPath = (node) => {
+    if (t.isStringLiteral(node))
+        return node.value;
+    if (t.isTemplateLiteral(node) && node.expressions.length === 0)
+        return stringValue(node);
+    if (t.isBinaryExpression(node, { operator: "+" })) {
+        const left = staticPath(node.left);
+        const right = staticPath(node.right);
+        return left === undefined || right === undefined
+            ? undefined
+            : `${left}${right}`;
+    }
+    if (t.isCallExpression(node) || t.isNewExpression(node))
+        return staticCallPath(node);
+    return undefined;
+};
+const staticCallPath = (node) => {
+    const name = calleeName(node.callee);
+    if (name === "URL" || name.endsWith(".URL"))
+        return isFileIdentity(argumentNode(node.arguments[1]))
+            ? stringValue(node.arguments[0])
+            : undefined;
+    if (name === "fileURLToPath" || name.endsWith(".fileURLToPath")) {
+        return staticFileUrlPath(argumentNode(node.arguments[0]));
+    }
+    if ((name === "dirname" || name.endsWith(".dirname")) &&
+        isFileIdentity(argumentNode(node.arguments[0])))
+        return "";
+    if (name.endsWith(".resolve"))
+        return name === "win32.resolve" || name.endsWith(".win32.resolve")
+            ? undefined
+            : staticResolvedPath(node);
+    if (!name.endsWith(".join") && name !== "join")
+        return undefined;
+    const parts = [];
+    for (const argument of node.arguments) {
+        if (isDirectoryIdentity(argumentNode(argument)))
+            continue;
+        const value = t.isNode(argument) ? staticPath(argument) : undefined;
+        if (value === undefined)
+            return undefined;
+        parts.push(value);
+    }
+    return parts.length === 0 ? undefined : posix.join(...parts);
+};
+const staticFileUrlPath = (argument) => {
+    if (argument === undefined)
+        return undefined;
+    return isSourceFileUrl(argument)
+        ? sourceRelativeFileUrlPath(argument)
+        : staticPath(argument);
+};
+/** Project a known source-relative URL through the actual file URL decoder. */
+const sourceRelativeFileUrlPath = (node) => {
+    if (!isSourceFileUrl(node))
+        return undefined;
+    const value = stringValue(node.arguments[0]);
+    if (value === undefined ||
+        (value.split(/[?#]/u, 1)[0] ?? "") === "" ||
+        value !== value.trim() ||
+        value.includes("\\") ||
+        [...value].some((character) => character.charCodeAt(0) < 32) ||
+        /^[a-z][a-z0-9+.-]*:/iu.test(value) ||
+        value.startsWith("//") ||
+        /%(?:2e|2f|5c)/iu.test(value.split(/[?#]/u, 1)[0] ?? ""))
+        return undefined;
+    // A sufficiently deep inert anchor preserves any leading parent segments
+    // without using this host's cwd or inventing the application's directory.
+    const directory = `/${"source/".repeat(value.split("/").length + 1)}`;
+    try {
+        const resolved = new URL(value, `file://${directory}entry.js`);
+        const path = fileURLToPath(resolved, { windows: false });
+        if (value.startsWith("/"))
+            return path;
+        const relative = posix.relative(directory, path) || ".";
+        // Keep the established explicit source-directory observation spelling.
+        return value.startsWith("./") &&
+            relative !== "." &&
+            !relative.startsWith("../")
+            ? `./${relative}`
+            : relative;
+    }
+    catch (cause) {
+        // Malformed escapes and non-file URL forms remain unknown.
+        void cause;
+        return undefined;
+    }
+};
+const isSourceFileUrl = (node) => (t.isCallExpression(node) || t.isNewExpression(node)) &&
+    (calleeName(node.callee) === "URL" ||
+        calleeName(node.callee).endsWith(".URL")) &&
+    isFileIdentity(argumentNode(node.arguments[1]));
+const staticResolvedPath = (node) => {
+    const parts = [];
+    for (const argument of node.arguments) {
+        if (isDirectoryIdentity(argumentNode(argument))) {
+            parts.push(null);
+            continue;
+        }
+        const value = t.isNode(argument) ? staticPath(argument) : undefined;
+        // Validate every argument, including those before the last anchor.
+        if (value === undefined)
+            return undefined;
+        parts.push(value);
+    }
+    const anchor = parts.findLastIndex((part) => part === null || posix.isAbsolute(part));
+    // Relative-only calls depend on the target process cwd, which is unknown.
+    if (anchor === -1)
+        return undefined;
+    // A null anchor is the source directory; preserve its relative projection.
+    const path = posix.join(...parts.slice(anchor).filter((part) => part !== null));
+    return path === "/" ? path : path.replace(/\/$/u, "");
+};
+const isFilesystemPathExpression = (node) => {
+    if (t.isStringLiteral(node))
+        return node.value.startsWith("/");
+    if (isFileIdentity(node) || isDirectoryIdentity(node))
+        return true;
+    if (t.isBinaryExpression(node, { operator: "+" }))
+        return (isFilesystemPathExpression(node.left) ||
+            isFilesystemPathExpression(node.right));
+    if (t.isCallExpression(node) || t.isNewExpression(node)) {
+        const name = calleeName(node.callee);
+        if (name.endsWith(".resolve") && staticCallPath(node) !== undefined)
+            return true;
+        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);
+            });
+        return node.arguments.some((argument) => {
+            const value = argumentNode(argument);
+            return value !== undefined && isFilesystemPathExpression(value);
+        });
+    }
+    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" &&
+        semanticStaticPropertyName(node.property, node.computed) === "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])));
+};
+const XHR_METHODS = new Set([
+    "CONNECT",
+    "DELETE",
+    "GET",
+    "HEAD",
+    "OPTIONS",
+    "PATCH",
+    "POST",
+    "PUT",
+    "TRACE",
+]);
+/** An absolute HTTP(S)/WebSocket URL, or an absolute or relative path. */
+const isRequestUrlLiteral = (value) => /^(?:https?|wss?):\/\//iu.test(value) ||
+    value.startsWith("/") ||
+    value.startsWith("./") ||
+    value.startsWith("../");
+/**
+ * Browsing-context and document `open` take a URL or type first and a target
+ * name second. The name is only a spelling, since `parent` or `self` may be a
+ * local XHR binding, so it never overrides a literal HTTP method.
+ */
+const WINDOW_OPEN_CALL = /(?:^|\.)(?:window|self|globalThis|top|parent|opener|frames|document)\.open$/u;
+/** Node `fs.open` flag strings, which are never request URLs. */
+const FS_OPEN_FLAGS = new Set([
+    "a",
+    "a+",
+    "as",
+    "as+",
+    "ax",
+    "ax+",
+    "r",
+    "r+",
+    "rs",
+    "rs+",
+    "sa",
+    "sa+",
+    "sr",
+    "sr+",
+    "w",
+    "w+",
+    "wx",
+    "wx+",
+    "xa",
+    "xa+",
+    "xw",
+    "xw+",
+]);
+/** Reserved browsing-context names (ASCII case-insensitive). */
+const BROWSING_CONTEXT_KEYWORDS = new Set([
+    "_blank",
+    "_parent",
+    "_self",
+    "_top",
+]);
+/**
+ * Read `XMLHttpRequest.open(method, url)`. `fs.open(path, "r")` and
+ * `window.open(url, "_blank")` share the callee name. A literal method must
+ * be an HTTP method; with a computed method, the second literal is a URL
+ * unless it is provably an fs flag or a browsing-context keyword, or the
+ * receiver is spelled as a browsing context or storage. XHR normalizes the standard
+ * methods' case; extension methods such as WebDAV `PROPFIND` are
+ * conventionally uppercase tokens.
+ */
+const xhrOpenUrl = (name, methodNode, urlNode, receiverFact) => {
+    const url = stringValue(urlNode);
+    if (url === undefined)
+        return undefined;
+    // A lexical fact is stronger than the receiver's spelling. In particular,
+    // browser Window and Document globals overload `open` with URL/content APIs.
+    if (receiverFact === "window")
+        return undefined;
+    const method = stringValue(methodNode);
+    // IndexedDB and Cache Storage `open` take a name and a version, so a
+    // receiver spelled as storage needs a standard HTTP method literal.
+    const storage = receiverFact === "local-indexed-db" ||
+        receiverFact === "local-cache-storage" ||
+        receiverFact === "indexed-db" ||
+        receiverFact === "cache-storage" ||
+        storageKind(name) !== undefined;
+    if (method === undefined)
+        return storage ||
+            (receiverFact === undefined && WINDOW_OPEN_CALL.test(name)) ||
+            FS_OPEN_FLAGS.has(url) ||
+            BROWSING_CONTEXT_KEYWORDS.has(url.toLowerCase())
+            ? undefined
+            : url;
+    return XHR_METHODS.has(method.toUpperCase()) ||
+        ((!storage ||
+            receiverFact === "local-indexed-db" ||
+            receiverFact === "local-cache-storage") &&
+            /^[A-Z][A-Z-]*$/u.test(method))
+        ? url
+        : undefined;
+};
+const KEYED_COLLECTION_CONSTRUCTORS = new Set([
+    "FormData",
+    "Headers",
+    "Map",
+    "Set",
+    "URLSearchParams",
+    "WeakMap",
+    "WeakSet",
+]);
+/**
+ * Whether a get/delete receiver is spelled as a keyed collection: a
+ * constructed Map, Set, Headers, FormData, or URLSearchParams, or a
+ * `headers`/`searchParams` property. Spelling alone does not prove the
+ * binding, so callers keep URL and path literals as requests.
+ */
+const isKeyedCollectionReceiver = (callee) => {
+    if (!t.isMemberExpression(callee) && !t.isOptionalMemberExpression(callee))
+        return false;
+    const receiver = callee.object;
+    if (t.isNewExpression(receiver))
+        return (t.isIdentifier(receiver.callee) &&
+            KEYED_COLLECTION_CONSTRUCTORS.has(receiver.callee.name));
+    if (!t.isMemberExpression(receiver) &&
+        !t.isOptionalMemberExpression(receiver))
+        return false;
+    const property = semanticStaticPropertyName(receiver.property, receiver.computed);
+    return property === "headers" || property === "searchParams";
+};
+/** Select the literal URL argument for recognized network callees. */
+export const endpointArgument = (name, args, callee, receiverFact) => {
+    if (receiverFact === "window")
+        return undefined;
+    if (name === "fetch" || name.endsWith(".fetch") || name === "WebSocket")
+        return stringValue(args[0]);
+    if (name.endsWith(".open"))
+        return xhrOpenUrl(name, args[0], args[1], receiverFact);
+    const method = ["get", "post", "put", "patch", "delete", "request"].find((candidate) => name === candidate || name.endsWith(`.${candidate}`));
+    if (method !== undefined) {
+        const value = stringValue(args[0]);
+        // Only get and delete also belong to the keyed-collection APIs, whose
+        // keys are header, field, and parameter names rather than URLs or paths.
+        return value !== undefined &&
+            (method === "get" || method === "delete") &&
+            !isRequestUrlLiteral(value) &&
+            isKeyedCollectionReceiver(callee)
+            ? undefined
+            : value;
+    }
+    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 callee name from member syntax. */
+export const calleeName = (node) => {
+    const segments = [];
+    while (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
+        // Dynamic keys retain their syntax identity instead of inventing a name.
+        segments.push(memberPropertyName(node));
+        if (!t.isNode(node.object))
+            break;
+        node = node.object;
+    }
+    const base = t.isIdentifier(node)
+        ? node.name
+        : t.isImport(node)
+            ? "import"
+            : "";
+    segments.push(base);
+    segments.reverse();
+    const first = segments.findIndex((segment) => segment !== "");
+    return first === -1 ? "" : segments.slice(first).join(".");
+};
+/** Read a member property only when its syntax commits an exact name. */
+const memberPropertyName = (node) => node.computed &&
+    !t.isStringLiteral(node.property) &&
+    !t.isNumericLiteral(node.property)
+    ? `[computed@${String(node.property.start ?? -1)}]`
+    : semanticStaticPropertyName(node.property, node.computed);
+/**
+ * Return a string literal value without evaluating an expression. A template
+ * literal without substitutions denotes the same exact string.
+ */
+export const stringValue = (node) => {
+    if (node === null || node === undefined)
+        return undefined;
+    const literal = readExactJavaScriptLiteral(node);
+    return literal.found && typeof literal.value === "string"
+        ? literal.value
+        : undefined;
+};
+/** Return a string or numeric argument literal. */
+export const argumentValue = (node) => t.isNumericLiteral(node) ? String(node.value) : stringValue(node);
+/** 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 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),
+});
+/** Compare two exact source ranges. */
+export const sourceRangesEqual = (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 pointForOffset = (source, offset) => {
+    const before = source.slice(0, offset);
+    // Match JavaScript line terminators, treating CRLF as a single newline.
+    const lines = before.split(/\r\n|[\n\r\u2028\u2029]/u);
+    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] : []);
+/** Commit the static semantic content used to deduplicate registrations. */
+export const registrationKey = (registration) => 
+// Collision-free tuple: chunk/module keys are variable-length source-derived
+// lists, so NUL-joins would collapse ["a\0b"] with ["a", "b"].
+compositeKey([
+    registration.runtime,
+    registration.chunk_keys,
+    String(registration.unknown_chunk_keys),
+    registration.modules.map(({ module_key: key, source_sha256: digest }) => [
+        key,
+        digest,
+    ]),
+]);
+/** 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) => compareUnicodeCodePoints(key(left), key(right)));
+/** Hash exact UTF-8 source text. */
+export const sha256Text = (value) => createHash("sha256").update(value).digest("hex");
+/** 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: "Rollup", patterns: ["ROLLUP_FILE_URL", "import.meta.ROLLUP"] },
+    { name: "esbuild", patterns: ["__commonJS", "__esm"] },
+    { 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/javascript/javascriptStaticAnalysisState.js

@@ -0,0 +1,21 @@
+import { JavaScriptModuleRangeIndex } from "./javascriptStaticAnalysisFindings.js";
+/** Create isolated mutable state for one source analysis. */
+export const createJavaScriptAnalysisAccumulator = (sourceLength) => ({
+    references: [],
+    endpoints: [],
+    storage: [],
+    roles: [],
+    sourceMaps: [],
+    registrations: [],
+    browserWindows: [],
+    contextBridgeApis: [],
+    ipc: [],
+    senderValidations: [],
+    utilityProcesses: [],
+    nativeAddonBindings: [],
+    moduleRangeIndex: new JavaScriptModuleRangeIndex(sourceLength),
+    mediaElementPreloads: new WeakSet(),
+    seen: new Set(),
+    visitedNodes: 0,
+    unknownFindings: 0,
+});

package/dist/domain/javascript/javascriptStaticAnalysisTypes.js

@@ -0,0 +1,2 @@
+export {};
+/** Hard bounds applied to one AST-only JavaScript analysis. */