@scriptc/compiler 0.0.3 → 0.0.5

package/dist/frontend/lowering/lower-builtins.js

@@ -6,7 +6,7 @@ import { builtinModules } from "node:module";
 import * as ts from "../ts7/adapter.js";
 import { dynUndefinedExpr, own } from "./lowerer.js";
 import { canonicalBuiltinModule, isJsSourceFile, locOf, requireSpecOf } from "../program.js";
-import { builtinModuleFnOf, FS_READDIR_DOCUMENTED_OPTIONS, FS_WATCH_DOCUMENTED_OPTIONS, FS_WRITE_FILE_DOCUMENTED_OPTIONS, READLINE_DOCUMENTED_OPTIONS, builtinConstLit, fenceOrDropOptionKey, isChildSurfaceMember, } from "./surfaces.js";
+import { builtinModuleFnOf, FS_READDIR_DOCUMENTED_OPTIONS, FS_WATCH_DOCUMENTED_OPTIONS, FS_WRITE_FILE_DOCUMENTED_OPTIONS, QS_PARSE_DOCUMENTED_OPTIONS, QS_STRINGIFY_DOCUMENTED_OPTIONS, READLINE_DOCUMENTED_OPTIONS, builtinConstLit, fenceOrDropOptionKey, isChildSurfaceMember, } from "./surfaces.js";
 import { conditionalSpreadOf } from "./lower-exprs.js";
 import { HTTP2_CONSTANTS } from "./http2-constants.js";
 import { timerStyleCallback } from "./lower-calls.js";
@@ -81,7 +81,7 @@ export function builtinImportOf(L, ident) {
     }
     // The RE-EXPORT FACADE hop: a binding acquired through a user module
     // that re-exports a builtin (`import { ok } from "./assert-facade.js"`
-    // over `export { ok } from "node:assert"` — prettier's
+    // over `export { ok } from "node:assert"` — the formatter idiom's
     // universal/assert idiom; the namespace-member spelling resolves to
     // the facade's ExportSpecifier the same way). The specifier here is a
     // user module, so provenance comes from the ALIAS CHAIN instead: the
@@ -180,6 +180,82 @@ export function lowerHttp2ConstantsProperty(L, expr) {
     }
     return builtinConstLit(value, locOf(expr));
 }
+/** True for any spelling of node:perf_hooks' `performance` object — the
+   * named import binding, a namespace/default-import member, the require
+   * twins (all through the shared builtin tables), or the GLOBAL Node
+   * exposes without any import (the module export and the global are one
+   * value; provenance-checked like console/process, so the bare
+   * identifier and the globalThis.performance member both land here and
+   * a user's own `performance` binding never does). */
+export function isPerfHooksPerformanceExpr(L, node) {
+    if (L.isStdlibGlobal(node, "performance"))
+        return true;
+    if (ts.isIdentifier(node)) {
+        const bi = builtinImportOf(L, node);
+        return bi !== null && bi.module === "perf_hooks" && bi.member === "performance";
+    }
+    if (ts.isPropertyAccessExpression(node) && !node.questionDotToken) {
+        const bi = L.builtinMemberOf(node);
+        return bi !== null && bi.module === "perf_hooks" && bi.member === "performance";
+    }
+    return false;
+}
+/** The node:perf_hooks spoke: `performance.now()` reads the runtime's
+   * monotonic clock anchored at process start — Node's timeOrigin for a
+   * compiled program, fractional milliseconds — and
+   * `performance.now.bind(performance)` (the mockable-clock idiom's
+   * getTimestamp) is the same clock as a plain () => number function
+   * value. Other members on the performance object fence by name; null
+   * for non-perf_hooks callees (the call chain keeps trying). */
+export function lowerPerfHooksCall(L, expr, access) {
+    if (access.questionDotToken)
+        return null;
+    const loc = locOf(expr);
+    if (access.name.text === "now" && isPerfHooksPerformanceExpr(L, access.expression)) {
+        if (expr.arguments.length !== 0) {
+            L.noLowering("performance.now with arguments", expr, "Node's performance.now takes none");
+        }
+        return { kind: "libCall", fn: "perf.now", args: [], type: F64, loc };
+    }
+    if (access.name.text === "bind" &&
+        ts.isPropertyAccessExpression(access.expression) &&
+        !access.expression.questionDotToken &&
+        access.expression.name.text === "now" &&
+        isPerfHooksPerformanceExpr(L, access.expression.expression)) {
+        if (expr.arguments.length !== 1 || !isPerfHooksPerformanceExpr(L, expr.arguments[0])) {
+            L.noLowering("this performance.now.bind form", expr, "performance.now.bind(performance) is the lowered function-value spelling");
+        }
+        return {
+            kind: "closure",
+            fnName: perfNowFnValueOf(L),
+            captures: [],
+            type: funcOf([], F64),
+            loc,
+        };
+    }
+    if (isPerfHooksPerformanceExpr(L, access.expression)) {
+        L.noLowering(`perf_hooks performance.${access.name.text}`, expr, "performance.now() — and its .bind(performance) function value — is the lowered surface");
+    }
+    return null;
+}
+/** The memoized () => number lifted wrapper behind
+   * performance.now.bind(performance): a plain function value over the
+   * same perf.now libCall. */
+function perfNowFnValueOf(L) {
+    const name = "%perf.now.value";
+    if (!L.liftedFns.some((f) => f.name === name)) {
+        const loc = { file: "<builtin>", start: 0, end: 0 };
+        L.liftedFns.push({
+            name,
+            params: [],
+            returnType: F64,
+            locals: [],
+            body: [{ kind: "return", value: { kind: "libCall", fn: "perf.now", args: [], type: F64, loc }, loc }],
+            loc,
+        });
+    }
+    return name;
+}
 /** True for `const { NGHTTP2_CANCEL, ... } = http2.constants` — a plain
    * object destructure (identifier elements, renames allowed, no rest/
    * defaults/nesting) over the constants object whose every name is in
@@ -306,6 +382,20 @@ export function lowerBuiltinModuleCall(L, expr, bi, fn, loc) {
     if (bi.module === "os" && bi.member === "userInfo") {
         return lowerOsUserInfoCall(L, expr, loc);
     }
+    // node:querystring — parse/stringify are entirely special-cased (the
+    // sep/eq/options completions, parse's call-site-shaped dictionary
+    // result, stringify's DOM-crossing object argument); decode/encode
+    // are Node's own aliases of the pair (`const decode = parse` in the
+    // module source) and take the same lowerings. escape/unescape ride
+    // the generic table tail below.
+    if (bi.module === "querystring") {
+        if (bi.member === "parse" || bi.member === "decode") {
+            return lowerQuerystringParseCall(L, expr, loc);
+        }
+        if (bi.member === "stringify" || bi.member === "encode") {
+            return lowerQuerystringStringifyCall(L, expr, loc);
+        }
+    }
     // node:timers/promises — setTimeout([delay]) and setImmediate(): void
     // promises the shared timer heap settles. The omitted delay completes
     // to Node's 1ms floor (scr_timer_coerce_ms clamps anyway; the literal
@@ -3881,6 +3971,149 @@ function lowerOsUserInfoCall(L, call, loc) {
     }
     return { kind: "recordLit", fields, type: result, loc };
 }
+/** querystring's sep/eq arguments: an omitted argument, the literal
+ * null, and the literal undefined all mean the default (Node's falsy
+ * rule — parse(s, null, null, opts) is the canonical maxKeys spelling);
+ * a string expression passes through (the runtime applies the same
+ * falsy rule to '' at runtime). Everything else fences. */
+function qsSepEqArg(L, node, dflt, what, loc) {
+    if (!node ||
+        node.kind === ts.SyntaxKind.NullKeyword ||
+        (ts.isIdentifier(node) && node.text === "undefined")) {
+        return { kind: "strLit", value: dflt, type: STRING, loc };
+    }
+    const v = L.lowerExpr(node);
+    if (v.type.kind !== "string") {
+        L.noLowering(`${what} with a '${L.fmt(v.type)}' separator`, node, "pass a string, or null/undefined for the default (narrow unions first)");
+    }
+    return v;
+}
+/** querystring.parse / querystring.decode: the scan runs in the runtime
+ * (scr_qs_parse_into fills the result dictionary's overflow map), so the
+ * frontend completes sep/eq/maxKeys to Node's defaults and verifies the
+ * call site's mapped result IS the ParsedUrlQuery dictionary — a pure
+ * index-signature record over `string | string[]` (an undefined arm
+ * tolerated: @types/node's Dict) — the networkInterfaces verification
+ * stance. The default decoder is the one lowered decoder; a custom
+ * decodeURIComponent option fences by name. */
+export function lowerQuerystringParseCall(L, call, loc) {
+    if (call.arguments.length > 4 || call.arguments.some(ts.isSpreadElement)) {
+        L.noLowering(`querystring.parse with ${call.arguments.length} arguments`, call);
+    }
+    const fence = () => L.noLowering("querystring.parse where the result is not the ParsedUrlQuery dictionary", call, "the `{ [key: string]: string | string[] }` shape is the supported result");
+    const result = L.mapTypeOf(L.typeOf(call));
+    if (result?.kind !== "record")
+        fence();
+    const dictShape = L.shapes.get(result.shapeId);
+    if (!dictShape || dictShape.tuple || dictShape.fields.length > 0 || !dictShape.indexValue)
+        fence();
+    const iv = dictShape.indexValue;
+    if (iv.kind !== "union")
+        fence();
+    const ivDef = L.unions.get(iv.unionId);
+    if (!ivDef)
+        fence();
+    let sawStr = false;
+    let sawArr = false;
+    for (const arm of ivDef.arms) {
+        if (arm.kind === "string")
+            sawStr = true;
+        else if (arm.kind === "array" && arm.elem.kind === "string")
+            sawArr = true;
+        // undefined rides @types/node's Dict; the f64 arm is the
+        // header-family canonicalization (types.ts interns every
+        // `string | string[]`-slotted dictionary as the one canonical
+        // header shape, whose slot adds number type-level only — parse
+        // never stores one).
+        else if (arm.kind !== "undefinedT" && arm.kind !== "f64")
+            fence();
+    }
+    if (!sawStr || !sawArr)
+        fence();
+    const str = call.arguments[0]
+        ? L.lowerExprExpecting(call.arguments[0], STRING)
+        : L.noLowering("querystring.parse without a query string", call);
+    const sep = qsSepEqArg(L, call.arguments[1], "&", "querystring.parse", loc);
+    const eq = qsSepEqArg(L, call.arguments[2], "=", "querystring.parse", loc);
+    // The options walk: maxKeys lowers (Node's rule — > 0 caps the pair
+    // count, 0 and negatives mean unlimited — lives in the runtime, so
+    // any number expression works); a custom decodeURIComponent changes
+    // every decoded byte and fences by name.
+    let maxKeys = { kind: "numLit", value: 1000, type: F64, loc };
+    const optsNode = call.arguments[3];
+    if (optsNode) {
+        if (!ts.isObjectLiteralExpression(optsNode)) {
+            L.noLowering("querystring.parse with a non-literal options argument", optsNode, "the supported form spells the options inline: parse(s, sep, eq, { maxKeys: n })");
+        }
+        for (const p of optsNode.properties) {
+            const m = optionMember(p);
+            if (!m) {
+                L.noLowering("querystring.parse with this options shape", p, "spreads and computed keys have no lowering — write each member inline");
+            }
+            if (m.name === "maxKeys") {
+                maxKeys = L.lowerExprExpecting(m.value, F64);
+            }
+            else if (m.name === "decodeURIComponent") {
+                L.noLowering("querystring.parse with a custom decodeURIComponent", p, "the default decoder is the lowered surface (strict decodeURIComponent with Node's lenient fallback)");
+            }
+            else {
+                fenceOrDropOptionKey(L, p, m.name, "querystring.parse", QS_PARSE_DOCUMENTED_OPTIONS, "maxKeys is the supported option");
+            }
+        }
+    }
+    return { kind: "libCall", fn: "qs.parse", args: [str, sep, eq, maxKeys], type: result, loc };
+}
+/** querystring.stringify / querystring.encode: the object crosses as a
+ * DOM value (dynFrom — JSON-safe records and, in JS sources, dyn values
+ * directly) and Node's encodeStringified rules run in the runtime
+ * (scr_qs_stringify), so arrays expand to repeated keys and
+ * null/undefined values are empty. The default encoder is the one
+ * lowered encoder; a custom encodeURIComponent option fences by name. */
+export function lowerQuerystringStringifyCall(L, call, loc) {
+    if (call.arguments.length > 4 || call.arguments.some(ts.isSpreadElement)) {
+        L.noLowering(`querystring.stringify with ${call.arguments.length} arguments`, call);
+    }
+    const objNode = call.arguments[0];
+    // stringify() / stringify(undefined) / stringify(null): Node answers
+    // '' for every non-object — the constant folds.
+    if (!objNode ||
+        objNode.kind === ts.SyntaxKind.NullKeyword ||
+        (ts.isIdentifier(objNode) && objNode.text === "undefined")) {
+        return { kind: "strLit", value: "", type: STRING, loc };
+    }
+    const objV = L.lowerExpr(objNode);
+    let obj;
+    if (objV.type.kind === "dyn") {
+        obj = objV;
+    }
+    else if (objV.type.kind === "record" && L.dynConvertible(objV.type)) {
+        obj = { kind: "dynFrom", value: objV, type: DYN, loc };
+    }
+    else {
+        L.noLowering(`querystring.stringify of '${L.fmt(objV.type)}' values`, objNode, "pass a record of string/number/boolean values (arrays of those expand to repeated keys; null/undefined values serialize empty)");
+    }
+    const sep = qsSepEqArg(L, call.arguments[1], "&", "querystring.stringify", loc);
+    const eq = qsSepEqArg(L, call.arguments[2], "=", "querystring.stringify", loc);
+    const optsNode = call.arguments[3];
+    if (optsNode) {
+        if (!ts.isObjectLiteralExpression(optsNode)) {
+            L.noLowering("querystring.stringify with a non-literal options argument", optsNode, "the supported form spells the options inline (and the only documented option, encodeURIComponent, has no lowering)");
+        }
+        for (const p of optsNode.properties) {
+            const m = optionMember(p);
+            if (!m) {
+                L.noLowering("querystring.stringify with this options shape", p, "spreads and computed keys have no lowering — write each member inline");
+            }
+            if (m.name === "encodeURIComponent") {
+                L.noLowering("querystring.stringify with a custom encodeURIComponent", p, "the default encoder (querystring.escape's component set) is the lowered surface");
+            }
+            else {
+                fenceOrDropOptionKey(L, p, m.name, "querystring.stringify", QS_STRINGIFY_DOCUMENTED_OPTIONS, "no stringify options have a lowering");
+            }
+        }
+    }
+    return { kind: "libCall", fn: "qs.stringify", args: [obj, sep, eq], type: STRING, loc };
+}
 export function lowerOsNetworkInterfacesCall(L, call, loc) {
     if (call.arguments.length !== 0) {
         L.noLowering(`networkInterfaces with ${call.arguments.length} arguments`, call, "networkInterfaces() takes no arguments");
@@ -5231,10 +5464,11 @@ export function isConsoleLog(L, call) {
     return consoleCallMember(L, call) === "log";
 }
 /** The console member of a `console.<member>(...)` call, for the lowered
-   * trio: "log" (stdout), and "error"/"warn" (both stderr — Node's warn IS
+   * set: "log"/"info"/"debug" (stdout — Node's info and debug ARE log
+   * under other names), and "error"/"warn" (both stderr — Node's warn IS
    * error under another name; the output is identical). Provenance-checked
-   * like every stdlib global. Null for anything else (console.info,
-   * console.table, a user's own console binding, ...). */
+   * like every stdlib global. Null for anything else (console.table, a
+   * user's own console binding, ...). */
 export function consoleCallMember(L, call) {
     if (!ts.isPropertyAccessExpression(call.expression))
         return null;
@@ -5242,7 +5476,7 @@ export function consoleCallMember(L, call) {
     if (access.questionDotToken || call.questionDotToken)
         return null;
     const name = access.name.text;
-    if (name !== "log" && name !== "error" && name !== "warn")
+    if (name !== "log" && name !== "info" && name !== "debug" && name !== "error" && name !== "warn")
         return null;
     return L.isStdlibGlobal(access.expression, "console") ? name : null;
 }