@coana-tech/cli 15.0.1 → 15.0.2

package/repos/coana-tech/spar/runtime/dist/approx.js

@@ -0,0 +1,1060 @@
+// Approximate interpretation runtime for SPAR.
+// Adapted from Jelly's src/approx/approx.ts.
+//
+// Code transformation is delegated to the Rust parent process via FIFO/stdin IPC.
+// Logging goes to stdout (inherited).
+import { dirname, resolve } from "path";
+import Module, { createRequire } from "module";
+import { Hints } from "./hints.js";
+import { isProxy, makeBaseProxy, makeModuleProxy, stdlibProxy, theArgumentsProxy, theProxy } from "./proxy.js";
+import logger, { logToFile, writeStdOutIfActive } from "./logger.js";
+import { options } from "./options.js";
+import { pathToFileURL } from "url";
+import { patchGlobalBuiltins, WHITELISTED } from "./sandbox.js";
+import { inspect } from "util";
+import { openSync, readSync, writeSync } from "fs";
+import { MessageChannel } from "worker_threads";
+const require = createRequire(import.meta.url);
+// get options from parent process
+Object.assign(options, JSON.parse(process.argv[2]));
+// prepare logging
+logger.level = options.loglevel;
+if (options.logfile)
+    logToFile(options.logfile);
+const PREFIX = "_J$";
+/**
+ * Execution is aborted if loopCount reaches this limit.
+ */
+const LOOP_COUNT_LIMIT = 2500; // TODO: good value?
+/**
+ * Execution is aborted if stackSize reaches this limit.
+ */
+const STACK_SIZE_LIMIT = 50; // TODO: good value?
+/**
+ * Object allocation sites and types.
+ */
+const objLoc = new WeakMap();
+/**
+ * Functions and classes discovered but not yet visited.
+ */
+const unvisitedFunctionsAndClasses = new Map();
+/**
+ * Base objects for unvisited functions.
+ */
+const baseObjects = new Map();
+/**
+ * Collected hints.
+ */
+const hints = new Hints();
+/**
+ * Stack of dynamic properties in objects and classes.
+ * New entries are added by $init, contents added by $comp, used by $alloc.
+ */
+const constr = [];
+/**
+ * Dynamic class instance fields for postponed write hints.
+ */
+const dynamicClassInstanceFields = new WeakMap();
+/**
+ * Total number of times a loop body is entered.
+ */
+let loopCount = 0;
+/**
+ * Call stack size (approximate).
+ */
+let stackSize = 0;
+/**
+ * Total size of code (excluding dynamically generated code).
+ */
+let totalCodeSize = 0;
+const NATIVE_CONSTRUCTORS = new Set([
+    Object, Boolean, Error, AggregateError, EvalError, RangeError, ReferenceError, SyntaxError, TypeError,
+    URIError, Number, BigInt, Date, String, RegExp, Array, Int8Array, Uint8Array, Uint8ClampedArray,
+    Int16Array, Uint16Array, Int32Array, Uint32Array, BigInt64Array, BigUint64Array, Float32Array,
+    Float64Array, Map, Set, WeakMap, WeakSet, ArrayBuffer, SharedArrayBuffer, DataView, Promise, Proxy
+]);
+/**
+ * Maps native constructors to their specific AllocType
+ * (matching ObjectKind in the static analysis).
+ */
+const NATIVE_ALLOC_TYPES = new Map([
+    [Map, "Map"], [Set, "Set"], [WeakMap, "WeakMap"], [WeakSet, "WeakSet"], [WeakRef, "WeakRef"],
+    [Promise, "Promise"], [Date, "Date"], [RegExp, "RegExp"],
+    [Error, "Error"], [AggregateError, "Error"], [EvalError, "Error"], [RangeError, "Error"],
+    [ReferenceError, "Error"], [SyntaxError, "Error"], [TypeError, "Error"], [URIError, "Error"],
+]);
+function getNativeAllocType(ctor, result) {
+    if (Array.isArray(result))
+        return "Array";
+    if (typeof result === "function")
+        return "Function";
+    return NATIVE_ALLOC_TYPES.get(ctor) ?? "Object";
+}
+function getLocationJSON(mod, loc) {
+    return `${hints.moduleIndex.get(mod) ?? "?"}:${loc}`;
+}
+function getProp(prop) {
+    return typeof prop === "symbol" ? String(prop) : `"${String(prop)}"`;
+}
+function getObjLoc(obj) {
+    return objLoc.get(obj) ?? [undefined, undefined];
+}
+function locToString(obj) {
+    const lt = objLoc.get(obj);
+    if (lt) {
+        const [loc, type] = lt;
+        return `${loc}:${type}`;
+    }
+    else
+        return "?";
+}
+function mapArrayAdd(key, value, map) {
+    let arr = map.get(key);
+    if (!arr) {
+        arr = [];
+        map.set(key, arr);
+    }
+    arr.push(value);
+}
+class ApproxError extends Error {
+    constructor(msg) {
+        super(msg);
+    }
+    toString() {
+        return `ApproxError: ${this.message}`;
+    }
+}
+function incrementStackSize() {
+    if (stackSize++ > STACK_SIZE_LIMIT) {
+        stackSize = 0;
+        throw new ApproxError("Maximum stack size exceeded");
+    }
+}
+function decrementStackSize() {
+    stackSize--;
+}
+function handleException(ex) {
+    if (ex instanceof ApproxError || ex instanceof RangeError || ex.toString().startsWith("Error: Cannot find module"))
+        throw ex; // ensures that abort, stack overflow, and module load exceptions do not get swallowed
+    if (logger.isDebugEnabled())
+        logger.debug(`Suppressed exception: ${ex}`);
+    return theProxy;
+}
+/**
+ * Process pending write hints for class instance fields.
+ * @param fun function that has been instantiated
+ * @param res new instance
+ */
+function processPendingWriteHints(fun, res) {
+    const cs = dynamicClassInstanceFields.get(fun);
+    if (cs) {
+        for (const c of cs) {
+            const val = Object.getOwnPropertyDescriptor(res, c.prop)?.value;
+            const [baseLoc, baseType] = getObjLoc(res);
+            const [valLoc, valType] = getObjLoc(val);
+            if (baseLoc && baseType && valLoc && valType)
+                hints.addWriteHint({
+                    type: "normal",
+                    loc: getLocationJSON(c.mod, c.loc),
+                    baseLoc,
+                    baseType,
+                    prop: c.prop,
+                    valLoc,
+                    valType
+                });
+        }
+        dynamicClassInstanceFields.delete(fun); // once per class is enough
+    }
+}
+/**
+ * Overriding of special native functions where the call location is needed.
+ * @param mod module name
+ * @param loc source location
+ * @param base base value (undefined if absent)
+ * @param fun function
+ * @param args arguments
+ * @param isNew true if constructor call
+ * @return if proceed is true then proceed with the call, otherwise return the result value
+ */
+function callPre(mod, loc, base, fun, args, isNew) {
+    if (fun === Function) {
+        const funargs = args.slice(0, args.length - 1);
+        const funbody = args[args.length - 1] ?? "";
+        let error = false;
+        for (const a of funargs)
+            if (typeof a !== "string") {
+                error = true;
+                break;
+            }
+        if (!error) {
+            const str = `function anonymous(${funargs.join(",")}){${funbody}}`;
+            if (logger.isVerboseEnabled())
+                logger.verbose(`Function ${mod}:${loc} (code length: ${str.length})`);
+            if (logger.isDebugEnabled())
+                logger.debug(str);
+            const transformed = requestTransform(`${mod}:eval[${loc}]`, String(funbody), "commonjs");
+            const result = fun(...funargs, transformed);
+            hints.addEvalHint({
+                loc: getLocationJSON(mod, loc),
+                str
+            });
+            objLoc.set(result, [getLocationJSON(mod, loc), "Function"]);
+            return { proceed: false, result };
+        }
+    }
+    else if (!isNew)
+        if (fun.name === "require" && "resolve" in fun && "cache" in fun) { // probably a require function
+            const str = typeof args[0] === "string" && args[0].startsWith("node:") ? args[0].substring(5) : args[0];
+            if (Module.isBuiltin(str) && !WHITELISTED.has(str)) {
+                if (logger.isDebugEnabled())
+                    logger.debug(`Intercepting require "${args[0]}"`);
+                return { proceed: false, result: stdlibProxy(fun(args[0])) };
+            }
+        }
+        else
+            switch (fun) {
+                case eval:
+                    const str = args[0];
+                    if (logger.isVerboseEnabled())
+                        logger.verbose(`Indirect eval ${mod}:${loc} (code length: ${typeof str === "string" ? str.length : "?"})`);
+                    if (typeof str === "string")
+                        hints.addEvalHint({
+                            loc: getLocationJSON(mod, loc),
+                            str
+                        });
+                    const transformed = requestTransform(`${mod}:eval[${loc}]`, str, "commonjs");
+                    const result = fun(transformed);
+                    return { proceed: false, result };
+                case Function.prototype.apply:
+                    return callPre(mod, loc, args[0], base, args[1] ?? [], false);
+                case Function.prototype.call:
+                    return callPre(mod, loc, args[0], base, args.slice(1), false);
+                case Reflect.apply:
+                    return callPre(mod, loc, args[1], args[0], args[2], false);
+                case Reflect.construct:
+                    return callPre(mod, loc, args[1], args[0], args[2], true);
+            }
+    return { proceed: true };
+}
+/**
+ * Post-processing of special native functions.
+ * @param mod module name
+ * @param loc source location
+ * @param fun function
+ * @param args arguments
+ * @param val result value
+ * @param base the receiver object, if method call
+ */
+function callPost(mod, loc, fun, args, val, base) {
+    /**
+     * Copies properties according to a property descriptor.
+     * @param to object to copy to
+     * @param prop property
+     * @param descriptor property descriptor
+     */
+    function copyFromDescriptor(to, prop, descriptor) {
+        const [baseLoc, baseType] = getObjLoc(to);
+        if (baseLoc && baseType) {
+            if ("value" in descriptor) {
+                const [valLoc, valType] = getObjLoc(descriptor.value);
+                if (valLoc && valType)
+                    hints.addWriteHint({
+                        type: "normal",
+                        loc: getLocationJSON(mod, loc),
+                        baseLoc,
+                        baseType,
+                        prop,
+                        valLoc,
+                        valType
+                    });
+            }
+            if ("get" in descriptor) {
+                const [valLoc, valType] = getObjLoc(descriptor.get);
+                if (valLoc && valType)
+                    hints.addWriteHint({
+                        type: "get",
+                        loc: getLocationJSON(mod, loc),
+                        baseLoc,
+                        baseType,
+                        prop,
+                        valLoc,
+                        valType
+                    });
+            }
+            if ("set" in descriptor) {
+                const [valLoc, valType] = getObjLoc(descriptor.set);
+                if (valLoc && valType)
+                    hints.addWriteHint({ type: "set", loc: getLocationJSON(mod, loc), baseLoc, baseType, prop, valLoc, valType });
+            }
+        }
+    }
+    switch (fun) {
+        case Object.create: {
+            objLoc.set(val, [getLocationJSON(mod, loc), "Object"]);
+            break;
+        }
+        case Object.assign: {
+            const target = args.at(0);
+            for (const arg of args.slice(1))
+                for (const [prop, val] of Object.entries(Object.getOwnPropertyDescriptors(arg)))
+                    if (val.enumerable)
+                        copyFromDescriptor(target, prop, val);
+            break;
+        }
+        case Object.defineProperty: {
+            copyFromDescriptor(args.at(0), args.at(1), args.at(2));
+            break;
+        }
+        case Object.defineProperties: {
+            const target = args.at(0);
+            for (const [prop, val] of Object.entries(args.at(1)))
+                copyFromDescriptor(target, prop, val);
+            break;
+        }
+        case Array.from:
+        case Array.of:
+        case Array.prototype.concat:
+        case Array.prototype.flat:
+        case Array.prototype.filter:
+        case Array.prototype.slice: {
+            objLoc.set(val, [getLocationJSON(mod, loc), "Array"]);
+            break;
+        }
+        case Function.prototype.bind: {
+            const [baseLoc, baseAllocType] = getObjLoc(base);
+            if (!baseLoc || !baseAllocType)
+                return;
+            objLoc.set(val, [baseLoc, baseAllocType]);
+            baseObjects.set(baseLoc, args[0]);
+            break;
+        }
+        case Reflect.get: {
+            // TODO: produce read hint for Reflect.get
+            break;
+        }
+        case Reflect.set: {
+            // TODO: produce write hint for Reflect.set
+            break;
+        }
+        case Reflect.defineProperty: {
+            // TODO: produce write hint for Reflect.defineProperty
+            break;
+        }
+    }
+}
+// SPAR_IPC_FIFO:  Node.js → Rust (transform requests, execution results)
+const ipcFifoPath = process.env.SPAR_IPC_FIFO;
+if (!ipcFifoPath)
+    throw new Error("SPAR_IPC_FIFO environment variable not set");
+const ipcFd = openSync(ipcFifoPath, "w");
+// Synchronous line read from stdin (fd 0).
+// stdin: Rust → Node.js main thread (file requests, CJS transform responses)
+// Used for receiving transform responses and file requests.
+const stdinBuffer = Buffer.alloc(65536);
+let stdinLeftover = "";
+function readLineSync() {
+    while (true) {
+        const nlIdx = stdinLeftover.indexOf('\n');
+        if (nlIdx !== -1) {
+            const line = stdinLeftover.substring(0, nlIdx);
+            stdinLeftover = stdinLeftover.substring(nlIdx + 1);
+            return line;
+        }
+        const bytesRead = readSync(0, stdinBuffer, 0, stdinBuffer.length, null);
+        if (bytesRead === 0)
+            throw new Error("stdin closed unexpectedly");
+        stdinLeftover += stdinBuffer.toString("utf8", 0, bytesRead);
+    }
+}
+function sendToParent(msg) {
+    const json = JSON.stringify(msg) + '\n';
+    writeSync(ipcFd, json);
+}
+/**
+ * Request code transformation from the Rust parent.
+ * Synchronous: sends request to stdout, reads response from stdin.
+ * @param file module name
+ * @param source the code
+ * @param mode CJS/ESM
+ * @return transformed code, or "" if transformation failed
+ */
+function requestTransform(file, source, mode) {
+    sendToParent({ transform: file, source, sourceType: mode });
+    const line = readLineSync();
+    const resp = JSON.parse(line);
+    return resp.transformed;
+}
+/**
+ * Instruments a CJS source file by requesting transformation from the Rust parent.
+ * @param filename file path
+ * @param code the code
+ */
+function transformModule(filename, code) {
+    if (!(typeof filename === "string" && typeof code === "string"))
+        return ""; // value likely generated by the proxy, ignore
+    // Resolve symlinks for basedir comparison
+    let resolvedFilename = filename;
+    try {
+        resolvedFilename = require("fs").realpathSync(filename);
+    }
+    catch { }
+    let resolvedBasedir = options.basedir;
+    try {
+        resolvedBasedir = require("fs").realpathSync(options.basedir);
+    }
+    catch { }
+    if (!resolvedFilename.startsWith(resolvedBasedir)) {
+        if (logger.isVerboseEnabled())
+            logger.verbose(`Ignoring module outside basedir: ${filename}`);
+        return `module.exports = ${PREFIX}proxy`;
+    }
+    writeStdOutIfActive(`Loading module ${filename} (${Math.ceil(code.length / 1024)}KB)`);
+    if (logger.isVerboseEnabled())
+        logger.verbose(`Instrumenting ${filename}`);
+    totalCodeSize += code.length;
+    return requestTransform(filename, code, "commonjs");
+}
+const g = globalThis;
+for (const [name, val] of Object.entries({
+    /**
+     * The proxy mock object.
+     */
+    proxy: theProxy,
+    /**
+     * Sandboxed builtin modules (used by hooks.ts).
+     */
+    builtin: Object.fromEntries(Module.builtinModules
+        .filter(m => !WHITELISTED.has(m))
+        .map(m => [m, stdlibProxy(require(m))])),
+    /**
+     * Records the entry of a module.
+     * Also wraps the module object to prevent access to module.constructor.
+     */
+    start(mod, modobj) {
+        const i = hints.addModule(mod);
+        if (logger.isDebugEnabled())
+            logger.debug(`$start ${mod}: ${i}`);
+        if (modobj && modobj.exports) { // undefined for ESM modules (don't have dynamic exports anyway)
+            objLoc.set(modobj.exports, [`${i}`, "Object"]); // allocation site for module.exports
+            return makeModuleProxy(modobj); // FIXME: assigning to module fails in strict mode (suppressed exception)
+        }
+        return undefined; // undefined for ESM modules (don't have dynamic exports anyway)
+    },
+    /**
+     * Records the entry of an object expression or class.
+     */
+    init() {
+        logger.debug("$init");
+        constr.push([]);
+    },
+    /**
+     * Records the exit of an object expression, class or function and collects the allocation sites.
+     * @param mod module name
+     * @param loc source location
+     * @param obj new object
+     * @param hasInit if true, the call matches a call to $init
+     * @param isClass if true, the object is a class constructor
+     * @return the new object
+     */
+    alloc(mod, loc, obj, hasInit, isClass) {
+        if (typeof obj === "object" || typeof obj === "function" || Array.isArray(obj)) {
+            if (logger.isDebugEnabled())
+                logger.debug(`$alloc ${mod}:${loc}: ${Array.isArray(obj) ? "array" : typeof obj}`);
+            const s = getLocationJSON(mod, loc);
+            if (Array.isArray(obj))
+                objLoc.set(obj, [s, "Array"]); // allocation site for array
+            else if (typeof obj === "object")
+                objLoc.set(obj, [s, "Object"]); // allocation site for object expression
+            else {
+                if (isClass)
+                    objLoc.set(obj, [s, "Class"]); // allocation site for class
+                else
+                    objLoc.set(obj, [s, "Function"]); // allocation site for function
+                if (obj.prototype)
+                    objLoc.set(obj.prototype, [s, "Prototype"]); // allocation site for (non-arrow) function or class prototype
+            }
+            if (typeof obj === "function" && !hints.functions.has(s) && !unvisitedFunctionsAndClasses.has(s))
+                unvisitedFunctionsAndClasses.set(s, { fun: obj, isClass });
+            if (hasInit)
+                for (const c of constr.pop()) {
+                    let type;
+                    let valLoc, valType;
+                    let baseLoc = s, baseType;
+                    if (typeof obj === "function") { // class
+                        baseType = c.isStatic ? "Class" : "Prototype";
+                        const desc = Object.getOwnPropertyDescriptor(c.isStatic ? obj : obj.prototype, c.prop);
+                        switch (c.kind) {
+                            case "field":
+                                if (!c.isStatic) {
+                                    // class instance field, need to postpone hint until location of value is known at 'new'
+                                    mapArrayAdd(obj, c, dynamicClassInstanceFields);
+                                    continue;
+                                }
+                                type = "normal";
+                                [valLoc, valType] = getObjLoc(desc?.value);
+                                break;
+                            case "method":
+                                type = "normal";
+                                valLoc = getLocationJSON(c.mod, c.loc);
+                                valType = "Function";
+                                const v = desc?.value;
+                                if (v)
+                                    objLoc.set(v, [valLoc, valType]);
+                                break;
+                            case "get":
+                            case "set":
+                                type = c.kind;
+                                valLoc = getLocationJSON(c.mod, c.loc);
+                                valType = "Function";
+                                const a = desc?.[c.kind];
+                                if (a)
+                                    objLoc.set(a, [valLoc, valType]);
+                                break;
+                        }
+                    }
+                    else { // object
+                        baseType = "Object";
+                        const desc = Object.getOwnPropertyDescriptor(obj, c.prop);
+                        switch (c.kind) {
+                            case "field":
+                                type = "normal";
+                                [valLoc, valType] = getObjLoc(desc?.value);
+                                break;
+                            case "method":
+                                type = "normal";
+                                valLoc = getLocationJSON(c.mod, c.loc);
+                                valType = "Function";
+                                const v = desc?.value;
+                                if (v)
+                                    objLoc.set(v, [valLoc, valType]);
+                                break;
+                            case "get":
+                            case "set":
+                                type = c.kind;
+                                valLoc = getLocationJSON(c.mod, c.loc);
+                                valType = "Function";
+                                const a = desc?.[c.kind];
+                                if (a)
+                                    objLoc.set(a, [valLoc, valType]);
+                                break;
+                        }
+                    }
+                    if (c.isDynamic && valLoc && valType)
+                        hints.addWriteHint({
+                            type,
+                            loc: getLocationJSON(c.mod, c.loc),
+                            baseLoc,
+                            baseType,
+                            prop: c.prop,
+                            valLoc,
+                            valType
+                        });
+                }
+        }
+        return obj;
+    },
+    /**
+     * Performs a (static or dynamic) property write operation and collects a write hint.
+     * @param mod module name
+     * @param loc source location
+     * @param base base value
+     * @param prop property value
+     * @param val value being assigned
+     * @param isDynamic if true, the property name is a computed value
+     * @return the value being assigned
+     */
+    pw(mod, loc, base, prop, val, isDynamic) {
+        if (base === undefined) {
+            if (logger.isDebugEnabled())
+                logger.debug(`Suppressed exception: TypeError: Cannot set properties of undefined`);
+            return undefined;
+        }
+        if (typeof prop === "symbol" || Array.isArray(base))
+            return base[prop]; // ignoring symbols and writes to arrays
+        if (isProxy(base) || isProxy(val))
+            return theProxy;
+        const p = String(prop);
+        if (logger.isDebugEnabled())
+            logger.debug(`$pw ${mod}:${loc}: ${locToString(base)}${isDynamic ? `[${getProp(prop)}]` : `.${String(prop)}`} = ${locToString(val)}`);
+        try {
+            base[p] = val;
+        }
+        catch (ex) {
+            if (logger.isDebugEnabled())
+                logger.debug(`Suppressed exception: ${ex}`);
+        }
+        if (typeof val === "function") {
+            const loc = objLoc.get(val);
+            if (loc) {
+                const [funloc] = loc;
+                if (!baseObjects.has(funloc))
+                    baseObjects.set(funloc, base);
+            }
+        }
+        const [baseLoc, baseType] = getObjLoc(base);
+        const [valLoc, valType] = getObjLoc(val);
+        if (baseLoc && baseType && valLoc && valType)
+            hints.addWriteHint({
+                type: "normal",
+                loc: getLocationJSON(mod, loc),
+                baseLoc,
+                baseType,
+                prop: p,
+                valLoc,
+                valType
+            });
+        return val;
+    },
+    /**
+     * Performs a dynamic property read operation and collects a read hint.
+     * @param mod module name
+     * @param loc source location
+     * @param base base value
+     * @param prop property value
+     * @return the result value
+     */
+    dpr(mod, loc, base, prop) {
+        if (base === undefined) {
+            if (logger.isDebugEnabled())
+                logger.debug(`Suppressed exception: TypeError: Cannot read properties of undefined`);
+            return undefined;
+        }
+        if (Array.isArray(base))
+            return base[prop]; // ignoring reads from arrays
+        if (isProxy(base))
+            return theProxy;
+        const p = typeof prop === "symbol" ? prop : String(prop);
+        let val;
+        try {
+            val = base[p];
+        }
+        catch (ex) {
+            if (logger.isDebugEnabled())
+                logger.debug(`Suppressed exception: ${ex}`);
+            return theProxy;
+        }
+        if (isProxy(val))
+            return theProxy;
+        if (logger.isDebugEnabled())
+            logger.debug(`$dpr ${mod}:${loc}: ${locToString(base)}[${getProp(prop)}] -> ${locToString(val)}`);
+        const [valLoc, valType] = getObjLoc(val);
+        if (valLoc && valType)
+            hints.addReadHint({
+                loc: getLocationJSON(mod, loc),
+                prop: typeof p === "string" ? p : undefined,
+                valLoc,
+                valType
+            });
+        return val;
+    },
+    /**
+     * Performs a function call and models special native functions.
+     * @param mod module name
+     * @param loc source location
+     * @param fun function being called
+     * @param isOptionalCall if true, this is an optional call
+     * @param args arguments
+     * @return the call result value
+     */
+    fun(mod, loc, fun, isOptionalCall, ...args) {
+        if (logger.isDebugEnabled())
+            logger.debug(`$fun ${mod}:${loc}${isOptionalCall ? " optional" : ""}`);
+        if (isOptionalCall && (fun === undefined || fun === null))
+            return undefined;
+        if (typeof fun !== "function")
+            return theProxy;
+        try {
+            incrementStackSize();
+            const { proceed, result } = callPre(mod, loc, undefined, fun, args, false);
+            if (proceed) {
+                const res = Reflect.apply(fun, undefined, args);
+                callPost(mod, loc, fun, args, res);
+                return res;
+            }
+            else
+                return result;
+        }
+        catch (ex) {
+            return handleException(ex);
+        }
+        finally {
+            decrementStackSize();
+        }
+    },
+    /**
+     * Performs a method call and models special native functions.
+     * @param mod module name
+     * @param loc source location
+     * @param base base value
+     * @param prop property value
+     * @param isDynamic if true, the method name is a computed value
+     * @param isOptionalMember if true, the method expression is an optional member expression
+     * @param isOptionalCall if true, this is an optional call
+     * @param args arguments
+     * @return the call result value
+     */
+    method(mod, loc, base, prop, isDynamic, isOptionalMember, isOptionalCall, ...args) {
+        if (logger.isDebugEnabled())
+            logger.debug(`$method ${mod}:${loc}${isDynamic ? " dynamic" : ""}${isOptionalMember ? " optionalMember" : ""}${isOptionalCall ? " optionalCall" : ""}`);
+        let fun;
+        try {
+            fun = isOptionalMember && (base === undefined || base === null) ? undefined : base[prop];
+        }
+        catch (ex) {
+            if (logger.isDebugEnabled())
+                logger.debug(`Suppressed exception: ${ex}`);
+            return theProxy;
+        }
+        if (isOptionalCall && (fun === undefined || fun === null))
+            return undefined;
+        if (typeof fun !== "function") {
+            if (logger.isDebugEnabled())
+                logger.debug(`Suppressed exception: TypeError: Must be a function`);
+            return theProxy;
+        }
+        try {
+            incrementStackSize();
+            const { proceed, result } = callPre(mod, loc, base, fun, args, false);
+            if (proceed) {
+                const res = Reflect.apply(fun, base, args);
+                callPost(mod, loc, fun, args, res, base);
+                return res;
+            }
+            else
+                return result;
+        }
+        catch (ex) {
+            return handleException(ex);
+        }
+        finally {
+            decrementStackSize();
+        }
+    },
+    /**
+     * Performs a 'new' operation.
+     * @param mod module name
+     * @param loc source location
+     * @param fun the constructor to instantiate
+     * @param args arguments
+     * @return the result value
+     */
+    new(mod, loc, fun, ...args) {
+        logger.debug("$new");
+        if (typeof fun !== "function") {
+            if (logger.isDebugEnabled())
+                logger.debug(`Suppressed exception: TypeError: Must be a function`);
+            return theProxy;
+        }
+        try {
+            incrementStackSize();
+            const { proceed, result } = callPre(mod, loc, undefined, fun, args, true);
+            if (proceed) {
+                const res = Reflect.construct(fun, args);
+                // For implicit constructors (no _J$this), set objLoc on the instance
+                // using the class's own objLoc (set by _J$alloc).
+                if (typeof res === "object" && res !== null && !objLoc.has(res)) {
+                    const [classLoc] = getObjLoc(fun);
+                    if (classLoc)
+                        objLoc.set(res, [classLoc, "Object"]);
+                }
+                processPendingWriteHints(fun, res);
+                if (NATIVE_CONSTRUCTORS.has(fun) && (typeof res === "object" || typeof res === "function")) {
+                    const t = getNativeAllocType(fun, res);
+                    if (t)
+                        objLoc.set(res, [getLocationJSON(mod, loc), t]);
+                }
+                return res;
+            }
+            else
+                return result;
+        }
+        catch (ex) {
+            return handleException(ex);
+        }
+        finally {
+            decrementStackSize();
+        }
+    },
+    /**
+     * Records a dynamic property to be processed later by $alloc.
+     * @param mod module name
+     * @param loc source location
+     * @param prop property value
+     * @param kind kind of property
+     * @param isStatic if true this is a static field
+     * @param isDynamic if true, the property name is a computed value
+     * @return the property value
+     */
+    comp(mod, loc, prop, kind, isStatic, isDynamic) {
+        if (logger.isDebugEnabled())
+            logger.debug(`$comp ${mod}:${loc} ${getProp(prop)} ${kind}`);
+        if (typeof prop !== "symbol")
+            constr.at(constr.length - 1).push({ mod, loc, prop: String(prop), kind, isStatic, isDynamic });
+        return prop;
+    },
+    /**
+     * Registers that a function or class constructor has been visited.
+     * @param mod module name
+     * @param loc source location
+     */
+    enter(mod, loc) {
+        if (logger.isDebugEnabled())
+            logger.debug(`$enter ${mod}:${loc}`);
+        const s = getLocationJSON(mod, loc);
+        unvisitedFunctionsAndClasses.delete(s);
+        hints.addFunction(s);
+    },
+    /**
+     * Registers 'this' in a function or class constructor.
+     * @param mod module name
+     * @param loc source location
+     * @param thiss the 'this' object
+     * @returns the 'this' object
+     */
+    this(mod, loc, thiss) {
+        logger.debug(`$this ${mod}:${loc}`);
+        if (thiss) {
+            const s = getLocationJSON(mod, loc);
+            objLoc.set(thiss, [s, "Object"]); // allocation site for 'new' expression
+        }
+        return thiss;
+    },
+    /**
+     * Invoked when entering a catch block to make sure AbortExceptions are passed through.
+     * @param ex the exception
+     */
+    catch(ex) {
+        logger.debug("$catch");
+        if (ex instanceof ApproxError)
+            throw ex; // ensures that abort exceptions do not get swallowed
+    },
+    /**
+     * Invoked when entering a loop body to terminate long-running executions.
+     */
+    loop() {
+        logger.debug("$loop");
+        if (loopCount++ > LOOP_COUNT_LIMIT) {
+            loopCount = 0;
+            throw new ApproxError("Loop limit reached");
+        }
+    },
+    /**
+     * Records a direct eval call and instruments the code.
+     * @param mod module name
+     * @param loc source location
+     * @param str eval string
+     * @return the instrumented eval string
+     */
+    eval(mod, loc, str) {
+        if (logger.isDebugEnabled())
+            logger.debug(`$eval ${mod}:${loc} (code length: ${typeof str === "string" ? str.length : "?"})`);
+        if (typeof str === "string")
+            hints.addEvalHint({
+                loc: getLocationJSON(mod, loc),
+                str
+            });
+        return requestTransform(`${mod}:eval[${loc}]`, str, "commonjs");
+    },
+    /**
+     * Records a dynamic require/import.
+     * @param mod name of module containing the require/import
+     * @param loc source location
+     * @param str module string
+     * @return the module string
+     */
+    require(mod, loc, str) {
+        if (Module.isBuiltin(str))
+            return str;
+        if (logger.isDebugEnabled())
+            logger.debug(`$require ${mod}:${loc} "${str}"`);
+        if (typeof str === "string")
+            hints.addRequireHint({
+                loc: getLocationJSON(mod, loc),
+                str
+            });
+        return str;
+    },
+    /**
+     * Freezes the given object.
+     */
+    freeze(obj) {
+        Object.freeze(obj);
+    }
+}))
+    g[PREFIX + name] = val;
+/**
+ * Log function for testing and debugging.
+ * @param msg message
+ */
+g.$log = function (msg) {
+    writeStdOutIfActive("");
+    logger.info(`$log: ${inspect(msg, { depth: 1 })}`);
+};
+const realSetTimeout = setTimeout;
+/**
+ * Performs forced execution of functions that have been found but not visited.
+ */
+async function forceExecuteUnvisitedFunctions() {
+    let numForced = 0, numForcedExceptions = 0;
+    for (const [loc, { fun, isClass }] of unvisitedFunctionsAndClasses) {
+        const sloc = `${hints.modules[parseInt(loc)]}${loc.substring(loc.indexOf(":"))}`;
+        const msg = `Force-executing ${isClass ? "constructor" : "function"} ${sloc} (${unvisitedFunctionsAndClasses.size - 1} pending)`;
+        if (logger.isVerboseEnabled())
+            logger.verbose(msg);
+        else
+            writeStdOutIfActive(msg);
+        try {
+            const args = theArgumentsProxy;
+            if (isClass)
+                Reflect.construct(fun, args);
+            else {
+                const base = baseObjects.get(loc);
+                let res = Reflect.apply(fun, makeBaseProxy(base), args);
+                if (res && typeof res === "object" && (Symbol.iterator in res || Symbol.asyncIterator in res) && typeof res.next === "function") // fun is a generator function
+                    res.next(); // TODO: currently only invoking 'next' once
+                if (res instanceof Promise) {
+                    if (logger.isDebugEnabled())
+                        logger.debug("Awaiting promise");
+                    res = await Promise.race([res, new Promise(resolve => realSetTimeout(resolve, 100))]);
+                }
+            }
+            if (logger.isDebugEnabled())
+                logger.debug("Function completed successfully");
+        }
+        catch (err) {
+            if (logger.isVerboseEnabled())
+                logger.verbose(`Function completed with exception: ${err instanceof Error && logger.isDebugEnabled() ? err.stack : err}`);
+            numForcedExceptions++;
+        }
+        // Skip check for classes without explicit constructors — there is no constructor body
+        // to instrument with _J$enter, so the location is never added to hints.functions.
+        // (Jelly avoids this by inserting synthetic constructors during Babel preprocessing.)
+        if (!isClass && !hints.functions.has(loc)) {
+            const sloc = `${hints.modules[parseInt(loc)]}${loc.substring(loc.indexOf(":"))}`;
+            logger.error(`Error: Function ${sloc} should be visited now`);
+        }
+        numForced++;
+        unvisitedFunctionsAndClasses.delete(loc);
+        baseObjects.delete(loc);
+        loopCount = 0;
+    }
+    return { numForced, numForcedExceptions };
+}
+// intercept ESM module loading
+// SPAR_HOOKS_FIFO: Rust → Node.js hooks thread (ESM transform responses)
+const { port1, port2 } = new MessageChannel();
+Module.register("./hooks.js", {
+    parentURL: import.meta.url,
+    data: {
+        opts: options,
+        port2,
+        ipcFifoPath,
+        hooksFifoPath: process.env.SPAR_HOOKS_FIFO,
+    },
+    transferList: [port2]
+});
+port1.on("message", (msg) => {
+    switch (msg.type) {
+        case "log":
+            logger[msg.level]?.(msg.str);
+            break;
+        case "metadata":
+            totalCodeSize += msg.codeSize;
+            break;
+    }
+});
+// intercept CJS module loading
+const realCompile = Module.prototype._compile;
+Module.prototype._compile = function (content, filename) {
+    if (typeof content !== "string" || typeof filename !== "string")
+        return; // protect against accidental calls
+    if (logger.isVerboseEnabled())
+        logger.verbose(`Loading ${filename} (CJS loader)`);
+    content = transformModule(filename, content);
+    try {
+        return realCompile.call(this, content, filename);
+    }
+    catch (err) {
+        if (String(err).includes("SyntaxError"))
+            logger.verbose(`Unable to load ${filename} (trying to load ESM module as CJS?)`); // TODO: retry using ESM loader?
+        else
+            logger.warn(`Unable to load ${filename}: ${err instanceof Error && logger.isDebugEnabled() ? err.stack : err}`);
+        return realCompile.call(this, `module.exports = ${PREFIX}proxy`, filename);
+    }
+};
+// detect uncaught exceptions
+process.on('uncaughtException', (err) => {
+    logger.warn(`Unexpected exception (insufficient sandboxing?): ${err instanceof Error && logger.isDebugEnabled() ? err.stack : err}`); // should not happen if sandboxing is done properly
+});
+process.on("unhandledRejection", (err) => {
+    logger.verbose(`Unhandled promise rejection: ${err instanceof Error ? err.stack : err}`); // (usually harmless)
+});
+const chdir = process.chdir.bind(process);
+const dynamicImport = new Function("s", "return import(s)"); // prevents ts compilation to require
+// In ESM, 'module' is not defined. Create a fake module object for CJS compatibility.
+const fakeModule = {
+    filename: import.meta.filename ?? "",
+    path: import.meta.dirname ?? "",
+    paths: [],
+    exports: {},
+};
+// evaluate the code received from the master process, force execute unvisited functions, and return the resulting hints
+async function main() {
+    while (true) {
+        let line;
+        try {
+            line = readLineSync();
+        }
+        catch {
+            break; // stdin closed
+        }
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            logger.error(`Invalid JSON from parent: ${line}`);
+            continue;
+        }
+        if (!("file" in msg)) {
+            // Not a file request (could be something else in the future)
+            continue;
+        }
+        logger.verbose(`Starting approximate interpretation of ${msg.file}`);
+        let moduleException = false;
+        fakeModule.filename = msg.file;
+        fakeModule.path = dirname(msg.file);
+        fakeModule.paths = [resolve(dirname(msg.file), "node_modules")];
+        chdir(dirname(msg.file));
+        try {
+            await dynamicImport(pathToFileURL(msg.file));
+            if (logger.isDebugEnabled())
+                logger.debug(`Module completed successfully: ${msg.file}`);
+        }
+        catch (err) {
+            if (logger.isVerboseEnabled())
+                logger.verbose(`Uncaught exception for ${msg.file}: ${err instanceof Error && logger.isDebugEnabled() ? err.stack : err}`);
+            moduleException = true;
+        }
+        loopCount = 0;
+        const { numForced, numForcedExceptions } = await forceExecuteUnvisitedFunctions();
+        logger.verbose("Approximate interpretation completed");
+        sendToParent({
+            hints: hints.toJSON(),
+            numForced,
+            numForcedExceptions,
+            moduleException,
+            totalCodeSize,
+        });
+        // keeping visited modules and functions, but the hints are no longer needed in this process
+        hints.clearHints();
+        totalCodeSize = 0;
+    }
+}
+// sandbox global builtins
+patchGlobalBuiltins();
+// start processing
+main().catch(err => {
+    logger.error(`Fatal error: ${err instanceof Error ? err.stack : err}`);
+    process.exit(1);
+});