@scriptc/compiler 0.3.5 → 0.4.0

package/dist/frontend/lowering/builtins/filesystem.js

@@ -4,15 +4,16 @@ import { ladderFenceExpr } from "../lowerer.js";
 import { isJsSourceFile, locOf } from "../../program.js";
 import { builtinModuleFnOf, FS_READDIR_DOCUMENTED_OPTIONS, FS_WATCH_DOCUMENTED_OPTIONS, fenceOrDropOptionKey, } from "../surfaces.js";
 import { defaultAfterUndefined, lowerStaticallyUndefinedArgument } from "../optional-arguments.js";
-import { BOOL, BYTES_U8, DIR_T, DYN, F64, FILEHANDLE_T, FSWATCHER_T, STRING, VOID, arrayOf, isUnitType, typeEquals, } from "../../../ir/ir.js";
+import { BOOL, BYTES_U8, DIR_T, DYN, F64, FILEHANDLE_T, FSWATCHER_T, STATS_T, STRING, VOID, arrayOf, isUnitType, typeEquals, } from "../../../ir/ir.js";
 import { optionMember, lowerBuiltinOptionalDefault } from "./arguments.js";
+import { isSafeToDiscard } from "../expressions/evaluation-safety.js";
 /** Normalize fs.readSync/fs.writeSync's shorthand and inline-options buffer
  * forms into the existing fixed-width descriptor IR. fd and buffer bind
  * first, option values bind in object-literal order, and only then do the
  * default window expressions read the bound buffer length. */
 export function lowerFsSyncBufferWindow(lowerer, expr, loc, fn, source, supported) {
-    const fdValue = lowerer.lowerExprExpecting(expr.arguments[0], F64);
-    const bufferValue = lowerer.lowerExprExpecting(expr.arguments[1], BYTES_U8);
+    const fdValue = lowerer.lowerExprExpecting(expr.arguments.nodes[0], F64);
+    const bufferValue = lowerer.lowerExprExpecting(expr.arguments.nodes[1], BYTES_U8);
     const fdLocal = lowerer.declareHiddenLocal("%fsSyncFd", F64);
     const bufferLocal = lowerer.declareHiddenLocal("%fsSyncBuffer", BYTES_U8);
     const stmts = [
@@ -48,7 +49,7 @@ export function lowerFsSyncBufferWindow(lowerer, expr, loc, fn, source, supporte
         if (!ts.isObjectLiteralExpression(source.node)) {
             lowerer.noLowering(`${fn} with a non-literal options argument`, source.node, supported);
         }
-        for (const property of source.node.properties) {
+        for (const property of source.node.properties.nodes) {
             const member = optionMember(property);
             if (member === null) {
                 lowerer.noLowering(`${fn} with a non-plain options member`, property, supported);
@@ -141,12 +142,12 @@ export function lowerFsTimestampValue(lowerer, node, loc) {
 export function lowerFsToUnixTimestampCall(lowerer, expr, bi, loc) {
     if (bi.module !== "fs" || bi.member !== "_toUnixTimestamp")
         return null;
-    if (expr.arguments.length !== 1 || ts.isSpreadElement(expr.arguments[0]))
+    if (expr.arguments.nodes.length !== 1 || ts.isSpreadElement(expr.arguments.nodes[0]))
         return null;
     return {
         kind: "libCall",
         fn: "fs.toUnixTimestamp",
-        args: [lowerFsTimestampValue(lowerer, expr.arguments[0], loc)],
+        args: [lowerFsTimestampValue(lowerer, expr.arguments.nodes[0], loc)],
         type: F64,
         loc,
     };
@@ -164,7 +165,7 @@ function opendirLowers(lowerer, args) {
         return true;
     if (!ts.isObjectLiteralExpression(options))
         return false;
-    return options.properties.every((property) => {
+    return options.properties.nodes.every((property) => {
         const option = optionMember(property);
         if (!option)
             return false;
@@ -193,9 +194,9 @@ export function lowerFsLadderCall(lowerer, expr, bi, loc) {
     }
     if (bi.module !== "fs" && bi.module !== "fs/promises")
         return null;
-    if (!isJsSourceFile(expr.getSourceFile()))
+    if (!isJsSourceFile(ts.getSourceFileOfNode(expr)))
         return null;
-    const args = expr.arguments;
+    const args = expr.arguments.nodes;
     if (args.some(ts.isSpreadElement))
         return null;
     // Every ladder argument crosses as a dyn value; an argument that
@@ -253,11 +254,11 @@ export function lowerFsLadderCall(lowerer, expr, bi, loc) {
                 ts.isIdentifier(pathNode.expression) &&
                 pathNode.expression.text === "URL" &&
                 lowerer.mapTypeOf(lowerer.typeOf(pathNode))?.kind === "url" &&
-                pathNode.arguments?.length === 1 &&
-                ts.isStringLiteral(pathNode.arguments[0])) {
+                pathNode.arguments?.nodes.length === 1 &&
+                ts.isStringLiteral(pathNode.arguments.nodes[0])) {
                 let parsed = null;
                 try {
-                    parsed = new URL(pathNode.arguments[0].text);
+                    parsed = new URL(pathNode.arguments.nodes[0].text);
                 }
                 catch {
                     parsed = null;
@@ -443,8 +444,8 @@ export function lowerStringOrBytesWrite(lowerer, call, dataType, arms, append) {
         kind: "call",
         callee: helper,
         args: [
-            lowerer.lowerExprExpecting(call.arguments[0], STRING),
-            lowerer.lowerExprExpecting(call.arguments[1], dataType),
+            lowerer.lowerExprExpecting(call.arguments.nodes[0], STRING),
+            lowerer.lowerExprExpecting(call.arguments.nodes[1], dataType),
         ],
         type: VOID,
         loc,
@@ -567,7 +568,7 @@ export function lowerFileHandleMethodCall(lowerer, call, access) {
         return lowerBuiltinOptionalDefault(lowerer, node, STRING, dflt, true);
     };
     if (name === "sync" || name === "datasync") {
-        if (call.arguments.length !== 0)
+        if (call.arguments.nodes.length !== 0)
             lowerer.noLowering(`FileHandle.${name} with arguments`, call);
         return {
             kind: "libCall",
@@ -578,34 +579,34 @@ export function lowerFileHandleMethodCall(lowerer, call, access) {
         };
     }
     if (name === "truncate" || name === "chmod") {
-        if (call.arguments.length > 1 || (name === "chmod" && call.arguments.length !== 1))
-            lowerer.noLowering(`FileHandle.${name} with ${call.arguments.length} arguments`, call);
+        if (call.arguments.nodes.length > 1 || (name === "chmod" && call.arguments.nodes.length !== 1))
+            lowerer.noLowering(`FileHandle.${name} with ${call.arguments.nodes.length} arguments`, call);
         return {
             kind: "libCall",
             fn: name === "truncate" ? "fileHandle.truncate" : "fileHandle.chmod",
-            args: [receiver(), num(call.arguments[0], 0).value],
+            args: [receiver(), num(call.arguments.nodes[0], 0).value],
             type: promise(VOID),
             loc,
         };
     }
     if (name === "utimes") {
-        if (call.arguments.length !== 2 || call.arguments.some(ts.isSpreadElement))
+        if (call.arguments.nodes.length !== 2 || call.arguments.nodes.some(ts.isSpreadElement))
             lowerer.noLowering("FileHandle.utimes with this argument shape", call);
         return {
             kind: "libCall",
             fn: "fileHandle.utimes",
             args: [
                 receiver(),
-                lowerFsTimestampValue(lowerer, call.arguments[0], loc),
-                lowerFsTimestampValue(lowerer, call.arguments[1], loc),
+                lowerFsTimestampValue(lowerer, call.arguments.nodes[0], loc),
+                lowerFsTimestampValue(lowerer, call.arguments.nodes[1], loc),
             ],
             type: promise(VOID),
             loc,
         };
     }
     if (name === "readv" || name === "writev") {
-        if (call.arguments.length < 1 || call.arguments.length > 2)
-            lowerer.noLowering(`FileHandle.${name} with ${call.arguments.length} arguments`, call);
+        if (call.arguments.nodes.length < 1 || call.arguments.nodes.length > 2)
+            lowerer.noLowering(`FileHandle.${name} with ${call.arguments.nodes.length} arguments`, call);
         const type = lowerer.mapTypeOf(lowerer.typeOf(call));
         if (type?.kind !== "promise" || type.inner.kind !== "record")
             lowerer.badType(call, lowerer.typeOf(call));
@@ -614,15 +615,15 @@ export function lowerFileHandleMethodCall(lowerer, call, access) {
             fn: name === "readv" ? "fileHandle.readv" : "fileHandle.writev",
             args: [
                 receiver(),
-                lowerer.lowerExprExpecting(call.arguments[0], arrayOf(BYTES_U8)),
-                num(call.arguments[1], -1).value,
+                lowerer.lowerExprExpecting(call.arguments.nodes[0], arrayOf(BYTES_U8)),
+                num(call.arguments.nodes[1], -1).value,
             ],
             type,
             loc,
         };
     }
     if (name === "close" || name === "stat") {
-        if (call.arguments.length !== 0)
+        if (call.arguments.nodes.length !== 0)
             lowerer.noLowering(`FileHandle.${name} with arguments`, call);
         return {
             kind: "libCall",
@@ -633,13 +634,13 @@ export function lowerFileHandleMethodCall(lowerer, call, access) {
         };
     }
     if (name === "readFile") {
-        if (call.arguments.length > 1) {
-            lowerer.noLowering(`FileHandle.readFile with ${call.arguments.length} arguments`, call);
+        if (call.arguments.nodes.length > 1) {
+            lowerer.noLowering(`FileHandle.readFile with ${call.arguments.nodes.length} arguments`, call);
         }
         const type = lowerer.mapTypeOf(lowerer.typeOf(call));
         if (type?.kind !== "promise")
             lowerer.badType(call, lowerer.typeOf(call));
-        const encoding = utf8(call.arguments[0]);
+        const encoding = utf8(call.arguments.nodes[0]);
         if (typeEquals(type.inner, BYTES_U8)) {
             return {
                 kind: "libCall",
@@ -660,14 +661,14 @@ export function lowerFileHandleMethodCall(lowerer, call, access) {
         };
     }
     if (name === "writeFile" || name === "appendFile") {
-        if (call.arguments.length < 1 || call.arguments.length > 2) {
-            lowerer.noLowering(`FileHandle.${name} with ${call.arguments.length} arguments`, call);
+        if (call.arguments.nodes.length < 1 || call.arguments.nodes.length > 2) {
+            lowerer.noLowering(`FileHandle.${name} with ${call.arguments.nodes.length} arguments`, call);
         }
-        const dataNode = call.arguments[0];
+        const dataNode = call.arguments.nodes[0];
         const dataT = lowerer.mapTypeOf(lowerer.typeOf(dataNode));
         // Evaluate a supplied utf8 encoding even for Buffer data, matching
         // Node's argument order; it does not affect the bytes.
-        const encoding = utf8(call.arguments[1]);
+        const encoding = utf8(call.arguments.nodes[1]);
         if (dataT?.kind === "string") {
             return {
                 kind: "libCall",
@@ -689,16 +690,16 @@ export function lowerFileHandleMethodCall(lowerer, call, access) {
         lowerer.noLowering(`FileHandle.${name} of '${dataT ? lowerer.fmt(dataT) : lowerer.checker.typeToString(lowerer.typeOf(dataNode))}' data`, dataNode, "string and Uint8Array data are supported");
     }
     if (name === "read" || name === "write") {
-        const firstNode = call.arguments[0];
+        const firstNode = call.arguments.nodes[0];
         const firstT = firstNode ? lowerer.mapTypeOf(lowerer.typeOf(firstNode)) : undefined;
-        const secondT = call.arguments[1]
-            ? lowerer.mapTypeOf(lowerer.typeOf(call.arguments[1]))
+        const secondT = call.arguments.nodes[1]
+            ? lowerer.mapTypeOf(lowerer.typeOf(call.arguments.nodes[1]))
             : undefined;
         const readOptions = name === "read" &&
             (!firstNode || firstT?.kind === "record" || (firstT && isUnitType(firstT)));
         const bufferOptions = firstT?.kind === "bytes" && firstT.elem === "u8" && secondT?.kind === "record";
         if (readOptions || bufferOptions) {
-            if (call.arguments.length > (bufferOptions ? 2 : 1))
+            if (call.arguments.nodes.length > (bufferOptions ? 2 : 1))
                 lowerer.noLowering(`FileHandle.${name} options with extra arguments`, call);
             const type = lowerer.mapTypeOf(lowerer.typeOf(call));
             if (type?.kind !== "promise" || type.inner.kind !== "record")
@@ -713,7 +714,7 @@ export function lowerFileHandleMethodCall(lowerer, call, access) {
             let buffer = bufferOptions
                 ? stage(lowerer.lowerExprExpecting(firstNode, BYTES_U8), "%fhWindowBuffer")
                 : undefined;
-            const optionsNode = bufferOptions ? call.arguments[1] : firstNode;
+            const optionsNode = bufferOptions ? call.arguments.nodes[1] : firstNode;
             const options = optionsNode
                 ? stage(lowerer.lowerExpr(optionsNode), "%fhWindowOptions")
                 : undefined;
@@ -774,17 +775,17 @@ export function lowerFileHandleMethodCall(lowerer, call, access) {
         }
     }
     if (name === "read") {
-        if (call.arguments.length < 1 || call.arguments.length > 4) {
-            lowerer.noLowering(`FileHandle.read with ${call.arguments.length} arguments`, call, "use read(buffer[, offset[, length[, position]]])");
+        if (call.arguments.nodes.length < 1 || call.arguments.nodes.length > 4) {
+            lowerer.noLowering(`FileHandle.read with ${call.arguments.nodes.length} arguments`, call, "use read(buffer[, offset[, length[, position]]])");
         }
-        const buffer = lowerer.lowerExprExpecting(call.arguments[0], BYTES_U8);
+        const buffer = lowerer.lowerExprExpecting(call.arguments.nodes[0], BYTES_U8);
         const type = lowerer.mapTypeOf(lowerer.typeOf(call));
         if (type?.kind !== "promise" || type.inner.kind !== "record") {
             lowerer.badType(call, lowerer.typeOf(call));
         }
-        const offset = num(call.arguments[1], 0);
-        const length = num(call.arguments[2], -1);
-        const position = num(call.arguments[3], -1);
+        const offset = num(call.arguments.nodes[1], 0);
+        const length = num(call.arguments.nodes[2], -1);
+        const position = num(call.arguments.nodes[3], -1);
         return {
             kind: "libCall",
             fn: "fileHandle.read",
@@ -794,19 +795,19 @@ export function lowerFileHandleMethodCall(lowerer, call, access) {
         };
     }
     if (name === "write") {
-        if (call.arguments.length < 1 || call.arguments.length > 4) {
-            lowerer.noLowering(`FileHandle.write with ${call.arguments.length} arguments`, call);
+        if (call.arguments.nodes.length < 1 || call.arguments.nodes.length > 4) {
+            lowerer.noLowering(`FileHandle.write with ${call.arguments.nodes.length} arguments`, call);
         }
-        const dataNode = call.arguments[0];
+        const dataNode = call.arguments.nodes[0];
         const dataT = lowerer.mapTypeOf(lowerer.typeOf(dataNode));
         const type = lowerer.mapTypeOf(lowerer.typeOf(call));
         if (type?.kind !== "promise" || type.inner.kind !== "record") {
             lowerer.badType(call, lowerer.typeOf(call));
         }
         if (dataT?.kind === "bytes" && dataT.elem === "u8") {
-            const offset = num(call.arguments[1], 0);
-            const length = num(call.arguments[2], -1);
-            const position = num(call.arguments[3], -1);
+            const offset = num(call.arguments.nodes[1], 0);
+            const length = num(call.arguments.nodes[2], -1);
+            const position = num(call.arguments.nodes[3], -1);
             return {
                 kind: "libCall",
                 fn: "fileHandle.writeBytes",
@@ -823,10 +824,10 @@ export function lowerFileHandleMethodCall(lowerer, call, access) {
             };
         }
         if (dataT?.kind === "string") {
-            if (call.arguments.length > 3) {
-                lowerer.noLowering(`FileHandle.write(string) with ${call.arguments.length} arguments`, call, 'use write(string[, position[, "utf8"]])');
+            if (call.arguments.nodes.length > 3) {
+                lowerer.noLowering(`FileHandle.write(string) with ${call.arguments.nodes.length} arguments`, call, 'use write(string[, position[, "utf8"]])');
             }
-            const position = num(call.arguments[1], -1);
+            const position = num(call.arguments.nodes[1], -1);
             return {
                 kind: "libCall",
                 fn: "fileHandle.writeStr",
@@ -834,7 +835,7 @@ export function lowerFileHandleMethodCall(lowerer, call, access) {
                     receiver(),
                     lowerer.lowerExprExpecting(dataNode, STRING),
                     position.value,
-                    utf8(call.arguments[2]),
+                    utf8(call.arguments.nodes[2]),
                 ],
                 type,
                 loc,
@@ -850,7 +851,7 @@ export function lowerFileHandleMethodCall(lowerer, call, access) {
  * readLines is `new readline.Interface({ input: createReadStream(options),
  * crlfDelay: Infinity })`. */
 function lowerFileHandleStreamCall(lowerer, call, name, receiver, loc) {
-    const args = call.arguments;
+    const args = call.arguments.nodes;
     if (args.some(ts.isSpreadElement) || args.length > 1) {
         lowerer.noLowering(`FileHandle.${name} with ${args.length} arguments`, call);
     }
@@ -906,7 +907,7 @@ export function lowerDirMethodCall(lowerer, call, access) {
         return null;
     const name = access.name.text;
     const loc = locOf(call);
-    if (DIR_METHODS.has(name) && call.arguments.length === 0) {
+    if (DIR_METHODS.has(name) && call.arguments.nodes.length === 0) {
         const receiver = lowerer.lowerExprExpecting(access.expression, DIR_T);
         if (name === "closeSync")
             return { kind: "libCall", fn: "dir.closeSync", args: [receiver], type: VOID, loc };
@@ -953,15 +954,19 @@ export const STATS_TYPE_TESTS = {
  * isSymbolicLink — take lstatSync's, Node's own split). Anything else
  * fences member-qualified. Null for non-Stats receivers. */
 export function lowerStatsMethodCall(lowerer, call, access) {
-    if (call.questionDotToken || access.questionDotToken)
+    // `stat?.isFile()` on a `Stats | undefined` receiver: the optional-chain
+    // lowering guards the receiver, then re-enters here with it narrowed.
+    if ((call.questionDotToken && !lowerer.chainHandled.has(call)) ||
+        (access.questionDotToken && !lowerer.chainHandled.has(access))) {
         return null;
+    }
     if (lowerer.mapTypeOf(lowerer.typeOf(access.expression))?.kind !== "stats")
         return null;
     if (!lowerer.isStdlibMember(access))
         return null;
     const name = access.name.text;
     const fn = Object.hasOwn(STATS_TYPE_TESTS, name) ? STATS_TYPE_TESTS[name] : undefined;
-    if (fn && call.arguments.length === 0) {
+    if (fn && call.arguments.nodes.length === 0) {
         const receiver = lowerer.lowerExpr(access.expression);
         return { kind: "libCall", fn, args: [receiver], type: BOOL, loc: locOf(call) };
     }
@@ -981,17 +986,17 @@ export function lowerStatsMethodCall(lowerer, call, access) {
  * undocumented keys drop like Node. An open watcher keeps the loop
  * alive until watcher.close(). */
 export function lowerFsWatchCall(lowerer, expr, loc) {
-    if (expr.arguments.length < 1 ||
-        expr.arguments.length > 3 ||
-        expr.arguments.some(ts.isSpreadElement)) {
+    if (expr.arguments.nodes.length < 1 ||
+        expr.arguments.nodes.length > 3 ||
+        expr.arguments.nodes.some(ts.isSpreadElement)) {
         lowerer.noLowering("fs.watch with this argument shape", expr, "the supported forms are watch(path[, options][, listener])");
     }
-    const hasOptions = expr.arguments.length >= 2 && ts.isObjectLiteralExpression(expr.arguments[1]);
-    if (expr.arguments.length === 3 && !hasOptions) {
-        lowerer.noLowering("fs.watch with a non-literal options argument", expr.arguments[1], "pass the options as an object literal: watch(path, { recursive?, persistent?, encoding? }, listener)");
+    const hasOptions = expr.arguments.nodes.length >= 2 && ts.isObjectLiteralExpression(expr.arguments.nodes[1]);
+    if (expr.arguments.nodes.length === 3 && !hasOptions) {
+        lowerer.noLowering("fs.watch with a non-literal options argument", expr.arguments.nodes[1], "pass the options as an object literal: watch(path, { recursive?, persistent?, encoding? }, listener)");
     }
     if (hasOptions) {
-        for (const prop of expr.arguments[1].properties) {
+        for (const prop of expr.arguments.nodes[1].properties.nodes) {
             if (!ts.isPropertyAssignment(prop) && !ts.isShorthandPropertyAssignment(prop)) {
                 lowerer.noLowering("fs.watch options with computed keys or spreads", prop, "each option must be a plain `name: value` entry with a literal key");
             }
@@ -1026,14 +1031,14 @@ export function lowerFsWatchCall(lowerer, expr, loc) {
             // An undocumented key, dropped like Node drops it.
         }
     }
-    const path = lowerer.lowerExprExpecting(expr.arguments[0], STRING);
+    const path = lowerer.lowerExprExpecting(expr.arguments.nodes[0], STRING);
     const args = [path];
     const listenerArg = hasOptions
-        ? expr.arguments.length === 3
-            ? expr.arguments[2]
+        ? expr.arguments.nodes.length === 3
+            ? expr.arguments.nodes[2]
             : null
-        : expr.arguments.length === 2
-            ? expr.arguments[1]
+        : expr.arguments.nodes.length === 2
+            ? expr.arguments.nodes[1]
             : null;
     if (listenerArg !== null) {
         const cb = lowerer.lowerExpr(listenerArg);
@@ -1067,7 +1072,7 @@ export function lowerWatcherMethodCall(lowerer, call, access) {
         return null;
     const name = access.name.text;
     const loc = locOf(call);
-    if (name === "close" && call.arguments.length === 0) {
+    if (name === "close" && call.arguments.nodes.length === 0) {
         const receiver = lowerer.lowerExpr(access.expression);
         return { kind: "libCall", fn: "watcher.close", args: [receiver], type: VOID, loc };
     }
@@ -1094,12 +1099,12 @@ export function lowerWatcherMethodCall(lowerer, call, access) {
 export function lowerFsReaddirTypesCall(lowerer, call, loc, promiseForm) {
     const operation = promiseForm ? "fs.promises.readdir" : "readdirSync";
     const spelling = promiseForm ? "readdir" : "readdirSync";
-    const optsNode = call.arguments[1];
+    const optsNode = call.arguments.nodes[1];
     if (!ts.isObjectLiteralExpression(optsNode)) {
         lowerer.noLowering(`${operation} with a non-literal options argument`, optsNode, `pass the options inline so each member can be checked: ${spelling}(path, { withFileTypes: true })`);
     }
     let sawWithFileTypes = false;
-    for (const p of optsNode.properties) {
+    for (const p of optsNode.properties.nodes) {
         const m = optionMember(p);
         if (!m) {
             lowerer.noLowering(`${operation} with this options shape`, p, "spreads and computed keys have no lowering — write each member inline");
@@ -1146,7 +1151,7 @@ export function lowerFsReaddirTypesCall(lowerer, call, loc, promiseForm) {
         !shape.fields.some((f) => f.name === "%dtype")) {
         fence();
     }
-    const path = lowerer.lowerExprExpecting(call.arguments[0], STRING);
+    const path = lowerer.lowerExprExpecting(call.arguments.nodes[0], STRING);
     return {
         kind: "libCall",
         fn: promiseForm ? "fsp.readdirTypes" : "fs.readdirTypesSync",
@@ -1155,6 +1160,138 @@ export function lowerFsReaddirTypesCall(lowerer, call, loc, promiseForm) {
         loc,
     };
 }
+/** fs.statSync / fs.lstatSync's documented option keys. */
+const FS_STAT_DOCUMENTED_OPTIONS = new Set(["bigint", "throwIfNoEntry"]);
+/** fs.statSync / fs.lstatSync(path, options). The options are an object
+ * literal, where throwIfNoEntry takes any boolean and bigint must be a
+ * literal false (BigIntStats has no lowering), or a stored record whose
+ * only member is a boolean throwIfNoEntry. When the call's type is
+ * `Stats | undefined`, the call lowers to the probe, which answers
+ * undefined for a missing entry without building the error. An explicitly
+ * undefined options argument is the one-argument form. */
+export function lowerFsStatOptionsCall(lowerer, call, loc, noFollow) {
+    const spelling = noFollow ? "lstatSync" : "statSync";
+    const plainFn = noFollow ? "fs.lstatSync" : "fs.statSync";
+    const optsNode = call.arguments.nodes[1];
+    const path = lowerer.lowerExprExpecting(call.arguments.nodes[0], STRING);
+    // The path binds first, then the options' effects, then the stat runs.
+    const plainAfter = (effect) => {
+        if (effect === null)
+            return { kind: "libCall", fn: plainFn, args: [path], type: STATS_T, loc };
+        const pathLocal = lowerer.declareHiddenLocal("%statPath", STRING);
+        return {
+            kind: "seqExpr",
+            stmts: [
+                { kind: "varDecl", localId: pathLocal.id, init: path, loc: path.loc },
+                { kind: "exprStmt", expr: effect, loc: effect.loc },
+            ],
+            result: {
+                kind: "libCall",
+                fn: plainFn,
+                args: [varRef(pathLocal.id, STRING, loc)],
+                type: STATS_T,
+                loc,
+            },
+            type: STATS_T,
+            loc,
+        };
+    };
+    const undefinedOptions = lowerStaticallyUndefinedArgument(lowerer, optsNode);
+    if (undefinedOptions !== null) {
+        return plainAfter(isSafeToDiscard(undefinedOptions) ? null : undefinedOptions);
+    }
+    let throwIfNoEntry = null;
+    if (!ts.isObjectLiteralExpression(optsNode)) {
+        // A stored options record (`const statSyncOptions = { throwIfNoEntry:
+        // false }`): the flag is read from it at the call, as Node reads
+        // options.throwIfNoEntry.
+        const optsType = lowerer.mapTypeOf(lowerer.typeOf(optsNode));
+        const shape = optsType?.kind === "record" ? lowerer.shapes.get(optsType.shapeId) : undefined;
+        const field = shape?.fields.find((f) => f.name === "throwIfNoEntry");
+        if (optsType?.kind !== "record" ||
+            !shape ||
+            shape.tuple ||
+            shape.indexValue ||
+            shape.fields.length !== 1 ||
+            field?.type.kind !== "bool") {
+            lowerer.noLowering(`${spelling} with this options value`, optsNode, `pass an object literal, or a record whose only member is a boolean throwIfNoEntry: ${spelling}(path, { throwIfNoEntry: false })`);
+        }
+        const opts = lowerer.lowerExpr(optsNode);
+        if (opts.type.kind === "record") {
+            throwIfNoEntry = {
+                kind: "recordGet",
+                obj: opts,
+                shapeId: opts.type.shapeId,
+                field: "throwIfNoEntry",
+                type: BOOL,
+                loc,
+            };
+        }
+        else if (opts.type.kind === "dyn") {
+            // A JavaScript binding held as a dynamic value: Node keeps throwing
+            // unless the member is exactly false.
+            throwIfNoEntry = {
+                kind: "dynScalarEq",
+                left: {
+                    kind: "dynKeyGet",
+                    key: { kind: "strLit", value: "throwIfNoEntry", type: STRING, loc },
+                    optional: true,
+                    value: opts,
+                    type: DYN,
+                    loc,
+                },
+                right: boolLit(false, loc),
+                negated: true,
+                type: BOOL,
+                loc,
+            };
+        }
+        else {
+            lowerer.noLowering(`${spelling} with this options value`, optsNode, "pass an object literal");
+        }
+    }
+    for (const p of ts.isObjectLiteralExpression(optsNode) ? optsNode.properties.nodes : []) {
+        const m = optionMember(p);
+        if (!m) {
+            lowerer.noLowering(`${spelling} with this options shape`, p, "spreads and computed keys have no lowering — write each member inline");
+        }
+        if (m.name === "throwIfNoEntry") {
+            throwIfNoEntry = lowerer.lowerExprExpecting(m.value, BOOL);
+        }
+        else if (m.name === "bigint") {
+            const t = lowerer.typeOf(m.value);
+            if (!(t.flags & ts.TypeFlags.BooleanLiteral) || lowerer.checker.typeToString(t) !== "false") {
+                lowerer.noLowering(`${spelling} with bigint: true`, m.value, "BigIntStats has no lowering; omit bigint for Stats");
+            }
+        }
+        else {
+            fenceOrDropOptionKey(lowerer, p, m.name, spelling, FS_STAT_DOCUMENTED_OPTIONS, "throwIfNoEntry and bigint: false are the supported options");
+        }
+    }
+    const callType = lowerer.mapTypeOf(lowerer.typeOf(call));
+    if (callType?.kind === "stats") {
+        // A runtime flag that is false answers undefined, which a Stats result
+        // cannot hold.
+        if (throwIfNoEntry !== null && !(throwIfNoEntry.kind === "boolLit" && throwIfNoEntry.value)) {
+            lowerer.noLowering(`${spelling} with a runtime-valued throwIfNoEntry where the result is typed Stats`, call, "the result must be Stats | undefined when throwIfNoEntry may be false");
+        }
+        return plainAfter(null);
+    }
+    const def = callType?.kind === "union" ? lowerer.unions.get(callType.unionId) : undefined;
+    if (!def ||
+        def.arms.length !== 2 ||
+        !def.arms.some((a) => a.kind === "stats") ||
+        !def.arms.some((a) => a.kind === "undefinedT")) {
+        lowerer.noLowering(`${spelling}(path, options) where the result is not Stats or Stats | undefined`, call, `${spelling}(path, { throwIfNoEntry: false }) answers Stats | undefined`);
+    }
+    return {
+        kind: "libCall",
+        fn: noFollow ? "fs.lstatProbeSync" : "fs.statProbeSync",
+        args: [path, throwIfNoEntry ?? boolLit(true, loc)],
+        type: callType,
+        loc,
+    };
+}
 /** `d.isFile()` / `d.isDirectory()` / `d.isSymbolicLink()` on a Dirent-
  * typed receiver (the interned record — provenance via the checker's
  * Dirent symbol, the StringDecoder pattern): a read of the hidden
@@ -1166,7 +1303,7 @@ export function lowerDirentMethodCall(lowerer, call, access) {
     if (!lowerer.isStdlibMember(access))
         return null;
     const recvSym = lowerer.typeOf(access.expression).getSymbol();
-    if (recvSym?.name !== "Dirent")
+    if (recvSym === undefined || ts.symbolName(recvSym) !== "Dirent")
         return null;
     const receiver = lowerer.lowerExpr(access.expression);
     if (receiver.type.kind !== "record")
@@ -1181,7 +1318,7 @@ export function lowerDirentMethodCall(lowerer, call, access) {
     if (code < 0) {
         lowerer.noLowering(`Dirent.${name}`, call, "name, parentPath, isFile(), isDirectory(), and isSymbolicLink() are the supported Dirent members", lowerer.checker.getSymbolAtLocation(access.name));
     }
-    if (call.arguments.length !== 0)
+    if (call.arguments.nodes.length !== 0)
         lowerer.noLowering(`Dirent.${name} with arguments`, call);
     const dtype = {
         kind: "recordGet",