@scriptc/compiler 0.4.5 → 0.4.6

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

@@ -6,7 +6,7 @@ import { lowerFsPath } from "./fs-paths.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, STATS_T, STRING, VOID, arrayOf, isUnitType, typeEquals, } from "../../../ir/ir.js";
+import { BIGINT_STATS_T, 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
@@ -951,6 +951,17 @@ export const STATS_TYPE_TESTS = {
     isFIFO: "stats.isFIFO",
     isSocket: "stats.isSocket",
 };
+/** The same type tests on a BigIntStats receiver (statSync with
+ * `{ bigint: true }`): one more snapshot read, no bigint arithmetic. */
+const BIGINT_STATS_TYPE_TESTS = {
+    isFile: "bigstats.isFile",
+    isDirectory: "bigstats.isDirectory",
+    isSymbolicLink: "bigstats.isSymbolicLink",
+    isBlockDevice: "bigstats.isBlockDevice",
+    isCharacterDevice: "bigstats.isCharacterDevice",
+    isFIFO: "bigstats.isFIFO",
+    isSocket: "bigstats.isSocket",
+};
 /** Method calls on Stats-typed receivers: the type tests are pure reads on
  * the stat snapshot (a followed statSync snapshot never answers true to
  * isSymbolicLink — take lstatSync's, Node's own split). Anything else
@@ -962,12 +973,16 @@ export function lowerStatsMethodCall(lowerer, call, access) {
         (access.questionDotToken && !lowerer.chainHandled.has(access))) {
         return null;
     }
-    if (lowerer.mapTypeOf(lowerer.typeOf(access.expression))?.kind !== "stats")
+    const receiverKind = lowerer.mapTypeOf(lowerer.typeOf(access.expression))?.kind;
+    if (receiverKind !== "stats" && receiverKind !== "bigintStats")
         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;
+    // BigIntStats' type tests are the same snapshot mode read; only the kind
+    // of the handle differs.
+    const table = receiverKind === "bigintStats" ? BIGINT_STATS_TYPE_TESTS : STATS_TYPE_TESTS;
+    const fn = Object.hasOwn(table, name) ? table[name] : undefined;
     if (fn && call.arguments.nodes.length === 0) {
         const receiver = lowerer.lowerExpr(access.expression);
         return { kind: "libCall", fn, args: [receiver], type: BOOL, loc: locOf(call) };
@@ -1106,6 +1121,7 @@ export function lowerFsReaddirTypesCall(lowerer, call, loc, promiseForm) {
         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;
+    let recursive = null;
     for (const p of optsNode.properties.nodes) {
         const m = optionMember(p);
         if (!m) {
@@ -1124,12 +1140,32 @@ export function lowerFsReaddirTypesCall(lowerer, call, loc, promiseForm) {
                 lowerer.noLowering(`${operation} with a non-utf8 encoding`, m.value, "names decode as utf8 (the default); encoding: 'buffer' has no lowering");
             }
         }
+        else if (m.name === "recursive" && !promiseForm) {
+            recursive = m.value;
+        }
         else {
             // The options-record stance: recursive (a documented knob with
-            // no lowering) fences by name; undocumented keys drop like Node.
+            // no lowering here) fences by name; undocumented keys drop like Node.
             fenceOrDropOptionKey(lowerer, p, m.name, operation, FS_READDIR_DOCUMENTED_OPTIONS, "withFileTypes: true (and the default encoding) is the supported options surface — recursive listings want an explicit walk");
         }
     }
+    if (recursive !== null) {
+        // Only the `true`/`false` keywords fold; any other expression, even one
+        // typed as a literal, evaluates at run time for its effects.
+        let flag = recursive;
+        while (ts.isParenthesizedExpression(flag))
+            flag = flag.expression;
+        const literal = flag.kind === ts.SyntaxKind.TrueKeyword
+            ? "true"
+            : flag.kind === ts.SyntaxKind.FalseKeyword
+                ? "false"
+                : null;
+        if (sawWithFileTypes && literal !== "false") {
+            lowerer.noLowering(`${operation} with withFileTypes and recursive`, recursive, "recursive: true lists relative names; withFileTypes: true lists one directory's Dirents");
+        }
+        if (!sawWithFileTypes)
+            return lowerFsReaddirRecursive(lowerer, call, recursive, literal, loc);
+    }
     if (!sawWithFileTypes) {
         lowerer.noLowering(`${operation} with 2 arguments`, call, `${spelling}(path) lists names; ${spelling}(path, { withFileTypes: true }) lists Dirents`);
     }
@@ -1162,24 +1198,121 @@ export function lowerFsReaddirTypesCall(lowerer, call, loc, promiseForm) {
         loc,
     };
 }
+/** `fs.readdirSync(path, { recursive })` without withFileTypes: the
+ * relative names of every entry below the path when `recursive` is true
+ * (scr_fs_readdir_recursive, Node's queue order), the directory's own names
+ * when it is false. A recursive flag that is not a boolean literal selects
+ * between the two at run time, after the path is evaluated. */
+function lowerFsReaddirRecursive(lowerer, call, recursive, literal, loc) {
+    const names = arrayOf(STRING);
+    // @types/node types the call `string[] | Buffer[]` when the options name
+    // no encoding; the names are strings, so the call is the string[] arm.
+    const callType = lowerer.mapTypeOf(lowerer.typeOf(call));
+    if (!callType ||
+        !(typeEquals(callType, names) ||
+            (callType.kind === "union" && lowerer.armTag(callType.unionId, names) >= 0))) {
+        lowerer.noLowering("readdirSync(path, { recursive }) where the result is not a string array", call, "names decode as utf8 strings (the default encoding)");
+    }
+    return lowerFsReaddirNames(lowerer, call, recursive, literal, names, loc);
+}
+function lowerFsReaddirNames(lowerer, call, recursive, literal, names, loc) {
+    const path = lowerFsPath(lowerer, call.arguments.nodes[0]);
+    const listing = (fn, arg) => ({
+        kind: "libCall",
+        fn,
+        args: [arg],
+        type: names,
+        loc,
+    });
+    if (literal === "true")
+        return listing("fs.readdirRecursiveSync", path);
+    if (literal === "false")
+        return listing("fs.readdirSync", path);
+    const pathLocal = lowerer.declareHiddenLocal("%readdirPath", STRING);
+    const pathRef = varRef(pathLocal.id, STRING, loc);
+    const flag = lowerer.lowerExprExpecting(recursive, BOOL);
+    return {
+        kind: "seqExpr",
+        stmts: [{ kind: "varDecl", localId: pathLocal.id, init: path, loc }],
+        result: {
+            kind: "ternary",
+            cond: flag,
+            then: listing("fs.readdirRecursiveSync", pathRef),
+            else_: listing("fs.readdirSync", pathRef),
+            type: names,
+            loc,
+        },
+        type: names,
+        loc,
+    };
+}
 /** fs.statSync / fs.lstatSync's documented option keys. */
 const FS_STAT_DOCUMENTED_OPTIONS = new Set(["bigint", "throwIfNoEntry"]);
+/** fs.fstatSync's: an open descriptor never misses, so there is no
+ * throwIfNoEntry. */
+const FS_FSTAT_DOCUMENTED_OPTIONS = new Set(["bigint"]);
+/** The stat representation a mapped result type carries: BigIntStats and
+ * `BigIntStats | undefined` read the bigint member table, Stats and
+ * `Stats | undefined` the number one; anything else is neither. */
+function statRepresentation(callType, arms) {
+    const kindOf = (t) => t.kind === "bigintStats" ? "bigint" : t.kind === "stats" ? "number" : null;
+    if (callType === undefined || callType === null)
+        return null;
+    const own = kindOf(callType);
+    if (own !== null)
+        return own;
+    if (arms !== undefined) {
+        for (const arm of arms) {
+            const repr = kindOf(arm);
+            if (repr !== null)
+                return repr;
+        }
+    }
+    return null;
+}
+/** The `bigint` option member. The literal picks the representation —
+ * BigIntStats for true, Stats for false — and the call's own type must
+ * already agree with it, because a `Stats | BigIntStats`-valued flag has no
+ * static member table. Answers the member's lowered value when evaluating
+ * it can have an effect (`bigint: (count++, true)`), which the call then
+ * runs in its place among the options; null when it can be dropped. */
+function checkStatBigintOption(lowerer, value, spelling, representation) {
+    const t = lowerer.typeOf(value);
+    const literal = t.flags & ts.TypeFlags.BooleanLiteral ? lowerer.checker.typeToString(t) : null;
+    if (literal === null) {
+        lowerer.noLowering(`${spelling} with a runtime-valued bigint option`, value, "pass the literal true or false: the result's representation is chosen statically");
+    }
+    if (representation === null || (literal === "true") !== (representation === "bigint")) {
+        lowerer.noLowering(`${spelling} with bigint: ${literal} where the result is not ${literal === "true" ? "BigIntStats" : "Stats"}`, value, "pass bigint: true to receive BigIntStats, or omit it to receive Stats");
+    }
+    const lowered = lowerer.lowerExprExpecting(value, BOOL);
+    return isSafeToDiscard(lowered) ? null : lowered;
+}
 /** 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. */
+ * literal, where throwIfNoEntry takes any boolean and bigint is the literal
+ * true (BigIntStats) or false (Stats), or a stored record whose only member
+ * is a boolean throwIfNoEntry. When the call's type is
+ * `Stats | undefined` (or `BigIntStats | 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 = lowerFsPath(lowerer, call.arguments.nodes[0]);
+    // `{ bigint: true }` selects Node's BigIntStats: the SAME snapshot handle,
+    // read through the bigint member table. The checker's answer for the call
+    // already names the variant, so the mapped call type is the source of
+    // truth and the option member below has to agree with it.
+    const callType = lowerer.mapTypeOf(lowerer.typeOf(call));
+    const def = callType?.kind === "union" ? lowerer.unions.get(callType.unionId) : undefined;
+    const representation = statRepresentation(callType, def?.arms);
+    const statsType = representation === "bigint" ? BIGINT_STATS_T : STATS_T;
     // 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 };
+            return { kind: "libCall", fn: plainFn, args: [path], type: statsType, loc };
         const pathLocal = lowerer.declareHiddenLocal("%statPath", STRING);
         return {
             kind: "seqExpr",
@@ -1191,10 +1324,10 @@ export function lowerFsStatOptionsCall(lowerer, call, loc, noFollow) {
                 kind: "libCall",
                 fn: plainFn,
                 args: [varRef(pathLocal.id, STRING, loc)],
-                type: STATS_T,
+                type: statsType,
                 loc,
             },
-            type: STATS_T,
+            type: statsType,
             loc,
         };
     };
@@ -1252,6 +1385,10 @@ export function lowerFsStatOptionsCall(lowerer, call, loc, noFollow) {
             lowerer.noLowering(`${spelling} with this options value`, optsNode, "pass an object literal");
         }
     }
+    // The members in source order, when a bigint member has an effect: the
+    // throwIfNoEntry value ("throwIfNoEntry") and each effect.
+    const members = [];
+    let bigintEffect = false;
     for (const p of ts.isObjectLiteralExpression(optsNode) ? optsNode.properties.nodes : []) {
         const m = optionMember(p);
         if (!m) {
@@ -1259,39 +1396,148 @@ export function lowerFsStatOptionsCall(lowerer, call, loc, noFollow) {
         }
         if (m.name === "throwIfNoEntry") {
             throwIfNoEntry = lowerer.lowerExprExpecting(m.value, BOOL);
+            members.push("throwIfNoEntry");
         }
         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");
+            const effect = checkStatBigintOption(lowerer, m.value, spelling, representation);
+            if (effect !== null) {
+                members.push(effect);
+                bigintEffect = true;
             }
         }
         else {
-            fenceOrDropOptionKey(lowerer, p, m.name, spelling, FS_STAT_DOCUMENTED_OPTIONS, "throwIfNoEntry and bigint: false are the supported options");
+            fenceOrDropOptionKey(lowerer, p, m.name, spelling, FS_STAT_DOCUMENTED_OPTIONS, "throwIfNoEntry and bigint are the supported options");
         }
     }
-    const callType = lowerer.mapTypeOf(lowerer.typeOf(call));
-    if (callType?.kind === "stats") {
+    // With a bigint member's effect, the path binds first, then the members
+    // run in source order (a runtime throwIfNoEntry into a local), then the
+    // stat; without one, the call evaluates its operands in that order itself.
+    const ordered = (stat) => {
+        if (!bigintEffect)
+            return stat(path, throwIfNoEntry);
+        const pathLocal = lowerer.declareHiddenLocal("%statPath", STRING);
+        const stmts = [{ kind: "varDecl", localId: pathLocal.id, init: path, loc: path.loc }];
+        let flag = throwIfNoEntry;
+        for (const member of members) {
+            if (member !== "throwIfNoEntry") {
+                stmts.push({ kind: "exprStmt", expr: member, loc: member.loc });
+            }
+            else if (flag !== null && flag.kind !== "boolLit") {
+                const flagLocal = lowerer.declareHiddenLocal("%statThrowIfNoEntry", BOOL);
+                stmts.push({ kind: "varDecl", localId: flagLocal.id, init: flag, loc: flag.loc });
+                flag = varRef(flagLocal.id, BOOL, flag.loc);
+            }
+        }
+        const result = stat(varRef(pathLocal.id, STRING, loc), flag);
+        return { kind: "seqExpr", stmts, result, type: result.type, loc };
+    };
+    if (callType?.kind === "stats" || callType?.kind === "bigintStats") {
         // 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);
+        if (!bigintEffect)
+            return plainAfter(null);
+        return ordered((pathArg) => ({
+            kind: "libCall",
+            fn: plainFn,
+            args: [pathArg],
+            type: statsType,
+            loc,
+        }));
     }
-    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 === "stats" || a.kind === "bigintStats") ||
         !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 {
+    return ordered((pathArg, flag) => ({
         kind: "libCall",
         fn: noFollow ? "fs.lstatProbeSync" : "fs.statProbeSync",
-        args: [path, throwIfNoEntry ?? boolLit(true, loc)],
+        args: [pathArg, flag ?? boolLit(true, loc)],
         type: callType,
         loc,
+    }));
+}
+/** fs.fstatSync(fd, options): the descriptor form of the same snapshot.
+ * Node documents only `bigint` here — an open descriptor cannot miss, so the
+ * result is Stats or BigIntStats, never undefined. */
+export function lowerFsStatFdOptionsCall(lowerer, call, loc) {
+    const spelling = "fstatSync";
+    const fd = lowerer.lowerExprExpecting(call.arguments.nodes[0], F64);
+    const optsNode = call.arguments.nodes[1];
+    const callType = lowerer.mapTypeOf(lowerer.typeOf(call));
+    const representation = statRepresentation(callType, undefined);
+    const statsType = representation === "bigint" ? BIGINT_STATS_T : STATS_T;
+    const plain = () => ({
+        kind: "libCall",
+        fn: "fs.fstatSync",
+        args: [fd],
+        type: statsType,
+        loc,
+    });
+    const undefinedOptions = lowerStaticallyUndefinedArgument(lowerer, optsNode);
+    if (undefinedOptions !== null) {
+        if (isSafeToDiscard(undefinedOptions))
+            return plain();
+        // The descriptor binds first, then the options' effects, then the stat.
+        const fdLocal = lowerer.declareHiddenLocal("%fstatFd", F64);
+        return {
+            kind: "seqExpr",
+            stmts: [
+                { kind: "varDecl", localId: fdLocal.id, init: fd, loc: fd.loc },
+                { kind: "exprStmt", expr: undefinedOptions, loc: undefinedOptions.loc },
+            ],
+            result: {
+                kind: "libCall",
+                fn: "fs.fstatSync",
+                args: [varRef(fdLocal.id, F64, loc)],
+                type: statsType,
+                loc,
+            },
+            type: statsType,
+            loc,
+        };
+    }
+    if (!ts.isObjectLiteralExpression(optsNode)) {
+        lowerer.noLowering(`${spelling} with this options value`, optsNode, `pass an object literal: ${spelling}(fd, { bigint: true })`);
+    }
+    const effects = [];
+    for (const p of 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 === "bigint") {
+            const effect = checkStatBigintOption(lowerer, m.value, spelling, representation);
+            if (effect !== null)
+                effects.push(effect);
+        }
+        else {
+            fenceOrDropOptionKey(lowerer, p, m.name, spelling, FS_FSTAT_DOCUMENTED_OPTIONS, "bigint is the supported option");
+        }
+    }
+    if (effects.length === 0)
+        return plain();
+    // The descriptor binds first, then the bigint member's effect, then the stat.
+    const fdLocal = lowerer.declareHiddenLocal("%fstatFd", F64);
+    return {
+        kind: "seqExpr",
+        stmts: [
+            { kind: "varDecl", localId: fdLocal.id, init: fd, loc: fd.loc },
+            ...effects.map((expr) => ({ kind: "exprStmt", expr, loc: expr.loc })),
+        ],
+        result: {
+            kind: "libCall",
+            fn: "fs.fstatSync",
+            args: [varRef(fdLocal.id, F64, loc)],
+            type: statsType,
+            loc,
+        },
+        type: statsType,
+        loc,
     };
 }
 /** `d.isFile()` / `d.isDirectory()` / `d.isSymbolicLink()` on a Dirent-