@scriptc/compiler 0.0.9 → 0.0.11

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

@@ -2,10 +2,16 @@
  * crypto, child_process spawn/spawnSync and child/stats/spawn-result
  * methods), JSON.parse/stringify, process properties/methods and
  * process.env access, and console.log detection. */
+import { readFileSync } from "node:fs";
 import { builtinModules } from "node:module";
+import { dirname, resolve } from "node:path";
 import * as ts from "../ts7/adapter.js";
-import { dynUndefinedExpr, nodeThrowExpr, own } from "./lowerer.js";
+import { PoisonError, dynUndefinedExpr, ladderFenceExpr, nodeThrowExpr, own } from "./lowerer.js";
 import { canonicalBuiltinModule, isJsSourceFile, locOf, requireSpecOf } from "../program.js";
+import { isRelativeSpecifier } from "../shared.js";
+import { probeNodeRequireRefusal } from "../npm.js";
+import { isNpmStaticPackage } from "../npm-static.js";
+import { invalidJsonModuleDiag, requiresDynamicImportDiag } from "../../diagnostics/diagnostic.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, lowerDynObjectLiteral } from "./lower-exprs.js";
 import { HTTP2_CONSTANTS } from "./http2-constants.js";
@@ -132,9 +138,17 @@ export function builtinMemberRequireDecl(nameNode, init) {
 export function builtinNamespaceDestructureModuleOf(L, decl) {
     if (decl.name === undefined || !ts.isObjectBindingPattern(decl.name) || decl.initializer === undefined)
         return null;
-    if (!ts.isIdentifier(decl.initializer))
-        return null;
-    const module = L.builtinNamespaceModuleOf(decl.initializer);
+    // `const { join } = require("node:path")` through a createRequire
+    // binding: the call IS the namespace — same table keying.
+    let module = null;
+    const init = stripTypeCasts(decl.initializer);
+    if (ts.isCallExpression(init)) {
+        const cr = createRequireSpecOf(L, init);
+        module = cr !== null && cr.spec !== null ? canonicalBuiltinModule(cr.spec) : null;
+    }
+    else if (ts.isIdentifier(init)) {
+        module = L.builtinNamespaceModuleOf(init);
+    }
     if (module === null)
         return null;
     for (const el of decl.name.elements) {
@@ -145,6 +159,223 @@ export function builtinNamespaceDestructureModuleOf(L, decl) {
     }
     return module;
 }
+/* ── node:module — createRequire's static erasure ─────────────────────
+ * The config/version-reading pattern real CLIs ship:
+ *   import { createRequire } from "node:module";
+ *   const require = createRequire(import.meta.url);
+ *   const pkg = require("../package.json");
+ * A compiled program's module graph is fixed at build time, so the
+ * indirection ERASES where the required specifier is a static string
+ * literal naming something the compiler already handles: a builtin (the
+ * binding is a namespace import in const clothing), a relative .json
+ * document (the file bakes and parses like JSON.parse of its text), or
+ * an installed npm package (the island's require-condition entry under
+ * --dynamic). Dynamic specifiers and other targets fence by name. */
+/** Strips the type-only wrappers the require pattern rides in typed
+   * code (`require("node:os") as typeof import("node:os")` — the
+   * fallback declarations answer `unknown`, so the cast IS the idiom),
+   * plus parens, legacy assertions, and non-null suffixes. */
+export function stripTypeCasts(e) {
+    let cur = e;
+    while (ts.isParenthesizedExpression(cur) || ts.isAsExpression(cur) ||
+        ts.isTypeAssertion(cur) || ts.isNonNullExpression(cur)) {
+        cur = cur.expression;
+    }
+    return cur;
+}
+/** The `createRequire(<base>)` call over the node:module import binding
+   * with a supported base — import.meta.url, import.meta.filename, or
+   * __filename, every spelling of "this file" — or null. The base never
+   * LOWERS (import.meta has no value representation): it only names the
+   * file whose directory anchors the returned require's relative
+   * resolution, and every supported spelling names the call's own file. */
+export function createRequireBaseCallOf(L, expr) {
+    const e = stripTypeCasts(expr);
+    if (!ts.isCallExpression(e) || e.questionDotToken)
+        return null;
+    if (!ts.isIdentifier(e.expression))
+        return null;
+    const bi = builtinImportOf(L, e.expression);
+    if (!bi || bi.module !== "module" || bi.member !== "createRequire")
+        return null;
+    if (e.arguments.length !== 1)
+        return null;
+    const base = stripTypeCasts(e.arguments[0]);
+    if (ts.isIdentifier(base) && base.text === "__filename")
+        return e;
+    if (ts.isPropertyAccessExpression(base) &&
+        !base.questionDotToken &&
+        ts.isMetaProperty(base.expression) &&
+        base.expression.keywordToken === ts.SyntaxKind.ImportKeyword &&
+        (base.name.text === "url" || base.name.text === "filename")) {
+        return e;
+    }
+    return null;
+}
+/** True for `const require = createRequire(import.meta.url)` — the
+   * binding is compile-time plumbing (each call through it resolves per
+   * site) with no storage and no code; both declaration walks skip by
+   * this test. A reassignable (let/var) binding never matches — callers
+   * gate on constness like the other alias decls. */
+export function createRequireBindingDecl(L, nameNode, init) {
+    if (!ts.isIdentifier(nameNode) || init === undefined)
+        return false;
+    return createRequireBaseCallOf(L, init) !== null;
+}
+/** The declaring source file when `callee` denotes a createRequire-made
+   * require: a CONST binding over createRequire(import.meta.url) (the
+   * binding's own file anchors resolution) or the inline
+   * `createRequire(import.meta.url)(...)` spelling (the call's file).
+   * Null off the pattern, so call chains keep trying. */
+export function createRequireCalleeFileOf(L, callee) {
+    const e = stripTypeCasts(callee);
+    if (ts.isCallExpression(e)) {
+        return createRequireBaseCallOf(L, e) !== null ? e.getSourceFile() : null;
+    }
+    if (!ts.isIdentifier(e))
+        return null;
+    const symbol = L.checker.getSymbolAtLocation(e);
+    const decl = symbol ? L.checker.declarationsOf(symbol)[0] : undefined;
+    if (!decl || !ts.isVariableDeclaration(decl) || decl.initializer === undefined)
+        return null;
+    if (!ts.isVariableDeclarationList(decl.parent) || (decl.parent.flags & ts.NodeFlags.Const) === 0)
+        return null;
+    return createRequireBaseCallOf(L, decl.initializer) !== null ? decl.getSourceFile() : null;
+}
+/** The static require of `R("spec")` through a createRequire binding:
+   * the literal specifier plus the file anchoring relative resolution.
+   * Null when the callee is not a createRequire-made require; a matching
+   * callee with a non-literal (or missing) specifier answers spec null,
+   * so the call lowering fences by name instead of falling through to
+   * the generic call paths. */
+export function createRequireSpecOf(L, call) {
+    if (call.questionDotToken)
+        return null;
+    const baseFile = createRequireCalleeFileOf(L, call.expression);
+    if (baseFile === null)
+        return null;
+    if (call.arguments.length !== 1)
+        return { spec: null, baseFile };
+    const a = call.arguments[0];
+    return { spec: ts.isStringLiteralLike(a) ? a.text : null, baseFile };
+}
+/** True for `const fs = require("node:fs")` through a createRequire
+   * binding — a builtin namespace import in const clothing: alias
+   * plumbing with no storage (uses resolve through
+   * builtinNamespaceModuleOf's createRequire arm); both declaration
+   * walks skip by this test. */
+export function createRequireNamespaceDecl(L, nameNode, init) {
+    if (!ts.isIdentifier(nameNode) || init === undefined)
+        return false;
+    const call = stripTypeCasts(init);
+    if (!ts.isCallExpression(call))
+        return false;
+    const cr = createRequireSpecOf(L, call);
+    return cr !== null && cr.spec !== null && canonicalBuiltinModule(cr.spec) !== null;
+}
+/** `require("spec")` through a createRequire binding — the erasure per
+   * target. Builtins are reached here only OUTSIDE the const-namespace-
+   * binding shape (that declaration erases; member uses resolve through
+   * the namespace tables) and fence toward it. A relative .json document
+   * bakes: the file's text validates as JSON at compile time and the
+   * call lowers to json.parse over the baked literal — JSON.parse's
+   * checked-dynamic `unknown` stance, and exactly Node's value (require
+   * of JSON IS JSON.parse of the file; the per-call re-parse forgoes
+   * Node's module-cache identity, unobservable without mutation). A bare
+   * specifier NOTHING installed resolves compiles to Node's catchable
+   * MODULE_NOT_FOUND throw (the optional-dependency try/require
+   * pattern); an installed package loads through the island's
+   * require-condition entry under --dynamic (collectCreateRequires
+   * embedded it) and reports the requires-dynamic diagnostic in a static
+   * build. Null when the callee is not a createRequire require. */
+export function lowerCreateRequireCall(L, call, loc) {
+    const cr = createRequireSpecOf(L, call);
+    if (cr === null)
+        return null;
+    if (cr.spec === null) {
+        L.noLowering("createRequire's require with this argument shape", call, "the compiled module graph is fixed at build time — the one lowered form is require(\"<static string literal>\")");
+    }
+    const spec = cr.spec;
+    if (canonicalBuiltinModule(spec) !== null) {
+        L.unsupported("SC1090", call, `module namespace objects as values (bind it first: const m = require("${spec}"), then access members through the binding)`);
+    }
+    if (spec.startsWith("#")) {
+        L.noLowering(`createRequire's require of the '${spec}' project import`, call, "imports-field specifiers have no require lowering yet — import the target statically");
+    }
+    if (isRelativeSpecifier(spec) || spec.startsWith("/")) {
+        if (!spec.endsWith(".json")) {
+            L.noLowering(`createRequire's require of '${spec}'`, call, "relative requires lower for .json documents only — a program module is a static import");
+        }
+        const abs = spec.startsWith("/")
+            ? spec
+            : resolve(dirname(cr.baseFile.fileName), spec);
+        let text = null;
+        try {
+            text = readFileSync(abs, "utf8");
+        }
+        catch {
+            /* the fence below speaks */
+        }
+        if (text === null) {
+            L.noLowering(`createRequire's require of '${spec}' (no file at ${abs})`, call, "the required document resolves at build time — check the path against the requiring file");
+        }
+        try {
+            JSON.parse(text);
+        }
+        catch (e) {
+            L.pushDiag(invalidJsonModuleDiag(abs, e instanceof Error ? e.message : String(e), loc));
+            throw new PoisonError();
+        }
+        return {
+            kind: "libCall",
+            fn: "json.parse",
+            args: [{ kind: "strLit", value: text, type: STRING, loc }],
+            type: DYN,
+            loc,
+        };
+    }
+    // Bare package specifiers. --npm-static opt-ins are program modules —
+    // their exports bind through static imports, not a require value.
+    const pkgName = spec.startsWith("@")
+        ? spec.split("/").slice(0, 2).join("/")
+        : spec.split("/")[0];
+    if (isNpmStaticPackage(pkgName)) {
+        L.noLowering(`createRequire's require of the --npm-static package '${pkgName}'`, call, "the opted-in package compiles as program modules — import it statically");
+    }
+    const refusal = probeNodeRequireRefusal(cr.baseFile.fileName, spec);
+    if (refusal !== null) {
+        // Node's require-site MODULE_NOT_FOUND, catchable — the compiled
+        // expression IS that throw (the typed dummy is abandoned by the
+        // pending check's unwind).
+        return nodeThrowExpr(0, "MODULE_NOT_FOUND", refusal.message, DYN, loc);
+    }
+    if (!L.dynamic) {
+        L.pushDiag(requiresDynamicImportDiag(pkgName, loc));
+        throw new PoisonError();
+    }
+    const res = L.createRequireImports.get(`${cr.baseFile.fileName}\u0000${spec}`);
+    if (res === undefined) {
+        // Collection never saw the site (a shape this walk and that walk
+        // disagree on) — fence rather than mis-embed.
+        L.noLowering(`createRequire's require of '${spec}'`, call, undefined);
+    }
+    if (res === "")
+        throw new PoisonError(); // reported at collection
+    // A CJS facade's default IS module.exports (Node's require answer);
+    // an ESM-resolved entry answers its namespace (Node's require(esm)).
+    const exportName = res.format === "esm" ? "*" : "default";
+    return {
+        kind: "libCall",
+        fn: "island.import",
+        args: [
+            { kind: "strLit", value: res.entryKey, type: STRING, loc },
+            { kind: "strLit", value: exportName, type: STRING, loc },
+            { kind: "strLit", value: spec, type: STRING, loc },
+        ],
+        type: JSVAL,
+        loc,
+    };
+}
 /** True when `node` denotes the http2.constants OBJECT — any of its
    * spellings: `http2.constants` through a namespace/require binding, a
    * destructured or member-bound `constants` alias from the http2 module,
@@ -371,6 +602,151 @@ export function lowerFsToUnixTimestampCall(L, expr, bi, loc) {
     }
     return null;
 }
+/** The fs validation-ladder spoke (checked-dynamic lane, JS sources
+ * only — TypeScript keeps its compile fences): implemented-namespace
+ * calls whose misuse Node rejects with typed errors lower to fs.*Chk
+ * libCalls that replicate the validation ladder over DOM values and
+ * throw Node's exact ERR_INVALID_ARG_TYPE / ERR_INVALID_ARG_VALUE /
+ * ERR_OUT_OF_RANGE — the honest tail (the real operation where one
+ * exists, the compiler-rendered SC2020 fence otherwise) runs only
+ * after every validation passes, exactly Node's order. Null when this
+ * is not a claimed member/shape (the table or fence path stands). */
+export function lowerFsLadderCall(L, expr, bi, loc) {
+    if (bi.module !== "fs" && bi.module !== "fs/promises")
+        return null;
+    if (!isJsSourceFile(expr.getSourceFile()))
+        return null;
+    const args = expr.arguments;
+    if (args.some(ts.isSpreadElement))
+        return null;
+    // Every ladder argument crosses as a DOM value; an argument that
+    // cannot leaves the historical fence in place.
+    const dynArg = (node) => {
+        if (!node)
+            return dynUndefinedExpr(loc);
+        const raw = L.lowerExpr(node);
+        if (raw.type.kind === "dyn")
+            return raw;
+        if (raw.kind === "unitLit" || L.dynConvertible(raw.type)) {
+            return { kind: "dynFrom", value: raw, type: DYN, loc };
+        }
+        return null;
+    };
+    const dynArgs = (nodes) => {
+        const out = [];
+        for (const n of nodes) {
+            const v = dynArg(n);
+            if (v === null)
+                return null;
+            out.push(v);
+        }
+        return out;
+    };
+    const resultT = L.mapTypeOf(L.typeOf(expr)) ?? DYN;
+    const chk = (fn, chkArgs, type) => ({ kind: "libCall", fn, args: chkArgs, type, loc });
+    if (bi.module === "fs/promises") {
+        if (bi.member !== "lchmod" || args.length !== 2)
+            return null;
+        const a = dynArgs([args[0], args[1]]);
+        return a && chk("fsp.lchmodChk", a, { kind: "promise", inner: VOID });
+    }
+    switch (bi.member) {
+        case "exists": {
+            // The REAL deprecated-API shape: the callback validates
+            // synchronously (Node's one throwing arm), invalid paths answer
+            // false THROUGH it, and the answer is asynchronous.
+            // A provably-non-file `new URL('<literal>')` path (the suite's
+            // https://foo probe): Node answers false through the callback
+            // synchronously — the DOM has no URL kind, so the path slot
+            // carries the unvalidatable token instead (construction of a
+            // parseable literal is effect-free; file: URLs keep the fence —
+            // they would need the real path conversion).
+            let pathNode = args[0];
+            let pathExpr = null;
+            if (pathNode && ts.isNewExpression(pathNode) && ts.isIdentifier(pathNode.expression) &&
+                pathNode.expression.text === "URL" && L.mapTypeOf(L.typeOf(pathNode))?.kind === "url" &&
+                pathNode.arguments?.length === 1 && ts.isStringLiteral(pathNode.arguments[0])) {
+                let parsed = null;
+                try {
+                    parsed = new URL(pathNode.arguments[0].text);
+                }
+                catch {
+                    parsed = null;
+                }
+                if (parsed === null || parsed.protocol === "file:")
+                    return null;
+                pathExpr = dynUndefinedExpr(loc);
+                pathNode = undefined;
+            }
+            pathExpr ??= dynArg(pathNode);
+            const cbExpr = dynArg(args[1]);
+            if (pathExpr === null || cbExpr === null)
+                return null;
+            return chk("fs.existsChk", [pathExpr, cbExpr], DYN);
+        }
+        case "mkdtemp": {
+            // mkdtemp(prefix[, options], callback) — the callback is the
+            // LAST argument (makeCallback runs first, then the prefix).
+            const a = dynArgs([args[0], args.length >= 2 ? args[args.length - 1] : undefined]);
+            return a && chk("fs.mkdtempChk", [...a, ladderFenceExpr(L, "fs.mkdtemp", expr)], resultT);
+        }
+        case "mkdtempSync": {
+            // The table serves the plain string 1-arg form; the ladder takes
+            // every other shape — prefix/encoding validation, then the REAL
+            // mkdtemp when the options leave utf8 semantics.
+            if (args.length === 1 && L.mapTypeOf(L.typeOf(args[0]))?.kind === "string")
+                return null;
+            if (args.length > 2)
+                return null;
+            const a = dynArgs([args[0], args[1]]);
+            return a && chk("fs.mkdtempSyncChk", [...a, ladderFenceExpr(L, "fs.mkdtempSync with these options", expr)], STRING);
+        }
+        case "readFile": {
+            // readFile(path[, options], callback): callback, assertEncoding,
+            // path — then the async read fences.
+            const a = dynArgs([args[0], args.length >= 3 ? args[1] : undefined, args.length >= 2 ? args[args.length - 1] : undefined]);
+            return a && chk("fs.readFileChk", [...a, ladderFenceExpr(L, "fs.readFile", expr)], resultT);
+        }
+        case "opendirSync": {
+            const a = dynArgs([args[0], args[1]]);
+            return a && chk("fs.opendirChk", [...a, ladderFenceExpr(L, "fs.opendirSync", expr)], resultT);
+        }
+        case "watchFile": {
+            // watchFile(filename[, options], listener): the path first, the
+            // listener's function contract second; real watching fences.
+            const a = dynArgs([args[0], args.length >= 2 ? args[args.length - 1] : undefined]);
+            return a && chk("fs.watchFileChk", [...a, ladderFenceExpr(L, "fs.watchFile", expr)], resultT);
+        }
+        case "lchmod": {
+            // lchmod(path, mode, callback): callback, path, mode — macOS
+            // shapes (non-APPLE answers Node's not-a-function TypeError).
+            const a = dynArgs([args[0], args[1], args[2]]);
+            return a && chk("fs.lchmodChk", [...a, ladderFenceExpr(L, "fs.lchmod", expr)], resultT);
+        }
+        case "lchmodSync": {
+            if (args.length > 2)
+                return null;
+            const a = dynArgs([args[0], args[1]]);
+            return a && chk("fs.lchmodSyncChk", a, DYN);
+        }
+        case "read": {
+            // read(fd, buffer, offset, length, position, callback) — the
+            // positional form's full ladder; options-object forms keep the
+            // fence (their misuse arms are not in the target set).
+            if (args.length < 4)
+                return null;
+            const a = dynArgs([args[0], args[1], args[2], args[3], args.length >= 6 ? args[4] : undefined]);
+            return a && chk("fs.readChk", [...a, ladderFenceExpr(L, "fs.read", expr)], resultT);
+        }
+        case "createReadStream":
+        case "createWriteStream": {
+            const a = dynArgs([args[0], args[1]]);
+            return a && chk("fs.streamOptsChk", [...a, ladderFenceExpr(L, `fs.${bi.member}`, expr)], resultT);
+        }
+        default:
+            return null;
+    }
+}
 export function lowerBuiltinModuleCall(L, expr, bi, fn, loc) {
     const name = expr.expression.getText();
     if (bi.module === "child_process" && bi.member === "spawnSync") {