@scriptc/compiler 0.3.1 → 0.3.3

package/dist/frontend/type-mapper.js

@@ -72,7 +72,12 @@ export const FETCH_AMBIENT_TYPES = [
     "ResponseInit",
     "RequestInit",
     "Event",
+    "CustomEvent",
     "EventTarget",
+    "AddEventListenerOptions",
+    "EventListenerOptions",
+    "EventInit",
+    "CustomEventInit",
     "AbortController",
     "AbortSignal",
     "Headers",
@@ -82,10 +87,20 @@ export const FETCH_AMBIENT_TYPES = [
     "ReadableStreamReadResult",
     "ReadableStreamReadValueResult",
     "ReadableStreamReadDoneResult",
+    "Blob",
+    "File",
+    "BlobPropertyBag",
+    "FilePropertyBag",
+    "BlobOptions",
+    "FileOptions",
 ];
-/** node:util.parseArgs's public and @types/node helper type names. Values
+/** node:util.parseArgs's public and @types/node helper type names, plus
+ * util.debuglog's DebugLogger (a native function value with an `enabled`
+ * accessor) and the DebugLoggerFunction its callback receives. Values
  * behind this surface use the checked-dynamic tree; see mapTypeInner. */
 const PARSE_ARGS_DYN_TYPES = new Set([
+    "DebugLogger",
+    "DebugLoggerFunction",
     "ParseArgsConfig",
     "ParseArgsOptionDescriptor",
     "ParseArgsOptionsConfig",
@@ -637,6 +652,8 @@ export function formatIrType(t, shapes, unions, seen = new Set()) {
                 return append("Stats");
             case "fileHandle":
                 return append("FileHandle");
+            case "dir":
+                return append("Dir");
             case "spawnRes":
                 return append("SpawnSyncReturns");
             case "child":
@@ -712,6 +729,34 @@ function esOwnKeyOrder(names) {
     const indices = names.filter(isArrayIndex).sort((a, b) => Number(a) - Number(b));
     return indices.length === 0 ? names : [...indices, ...names.filter((n) => !isArrayIndex(n))];
 }
+/** The hidden field that marks the perf_hooks entry record shape. */
+export const PERF_ENTRY_MARKER = "%perfEntry";
+/** PerformanceEntry's toJSON fields, in toJSON's order. */
+export const PERF_ENTRY_FIELDS = ["name", "entryType", "startTime", "duration", "detail"];
+/** The record shape behind PerformanceEntry, PerformanceMark and
+ * PerformanceMeasure values (see mapType). The marker is an always-absent
+ * optional, so dyn conversions and key walks never see it. */
+export function perfEntryShape(shapes, unions) {
+    return shapes.intern([
+        { name: PERF_ENTRY_MARKER, type: withUndefinedArm(F64, unions) },
+        { name: "detail", type: DYN },
+        { name: "duration", type: F64 },
+        { name: "entryType", type: STRING },
+        { name: "name", type: STRING },
+        { name: "startTime", type: F64 },
+    ], false, undefined, PERF_ENTRY_FIELDS);
+}
+/** toJSON()'s plain object over an entry: the same fields without the
+ * marker. */
+export function perfEntryJsonShape(shapes) {
+    return shapes.intern([
+        { name: "detail", type: DYN },
+        { name: "duration", type: F64 },
+        { name: "entryType", type: STRING },
+        { name: "name", type: STRING },
+        { name: "startTime", type: F64 },
+    ], false, undefined, PERF_ENTRY_FIELDS);
+}
 function isDeclaredInAmbientModule(d, name) {
     let node = d.parent;
     while (node) {
@@ -840,6 +885,77 @@ let mapTypeDepth = 0;
  * a bump between entry and exit stays fenced (recursive generic-open types
  * stay fenced instead of interning a per-context-wrong shape). */
 let contextResolutions = 0;
+/** node:url's legacy record interfaces: url.parse()'s Url instance (and
+ * its two query-typed refinements), url.format()'s UrlObject input, and the
+ * URL form's URLFormatOptions. The values are checked-dynamic objects —
+ * Node's Url instance carries its class name and null fields, and format()
+ * reads any object's fields with JS truthiness. */
+const LEGACY_URL_TYPES = new Set([
+    "Url",
+    "UrlObject",
+    "UrlWithParsedQuery",
+    "UrlWithStringQuery",
+    "URLFormatOptions",
+]);
+export function isLegacyUrlType(type, ctx) {
+    const symbol = type.getAliasSymbol() ?? type.getSymbol();
+    return isLegacyUrlSymbol(symbol, ctx);
+}
+/** A symbol declared as one of node:url's legacy record interfaces, or as
+ * a member of one. */
+export function isLegacyUrlSymbol(symbol, ctx) {
+    if (!symbol)
+        return false;
+    for (const d of ctx.checker.declarationsOf(symbol)) {
+        if (!ctx.isStdlibFile(d.getSourceFile()))
+            continue;
+        let family = false;
+        for (let n = d; n; n = n.parent) {
+            if (ts.isInterfaceDeclaration(n) && LEGACY_URL_TYPES.has(n.name.text))
+                family = true;
+            if (ts.isModuleDeclaration(n) && ts.isStringLiteral(n.name)) {
+                if (family && (n.name.text === "url" || n.name.text === "node:url"))
+                    return true;
+                break;
+            }
+        }
+    }
+    return false;
+}
+/** os.constants and its groups — @types/node's `namespace constants`
+ * (errno, dlopen, priority) and SignalConstants, and the fallback's twins:
+ * the runtime's checked-dynamic constants object, whose members vary by
+ * platform. */
+export function isOsConstantsType(type, ctx) {
+    return (isOsConstantsSymbol(type.getAliasSymbol(), ctx, true) ||
+        isOsConstantsSymbol(type.getSymbol(), ctx, true));
+}
+/** A symbol declared as os.constants or one of its groups (a namespace, or
+ * with `types`, the SignalConstants alias; without it, the `signals`
+ * constant). The binding-symbol form needs no type query. */
+export function isOsConstantsSymbol(symbol, ctx, types = false) {
+    if (!symbol)
+        return false;
+    for (const d of ctx.checker.declarationsOf(symbol)) {
+        const alias = types && ts.isTypeAliasDeclaration(d) && d.name.text === "SignalConstants";
+        const signals = !types && ts.isVariableDeclaration(d) && ts.isIdentifier(d.name) && d.name.text === "signals";
+        if (!(alias || signals || ts.isModuleDeclaration(d)) || !ctx.isStdlibFile(d.getSourceFile()))
+            continue;
+        let inConstants = ts.isModuleDeclaration(d) && d.name.text === "constants";
+        for (let n = d.parent; n; n = n.parent) {
+            if (!ts.isModuleDeclaration(n))
+                continue;
+            if (ts.isStringLiteral(n.name)) {
+                if ((n.name.text === "os" || n.name.text === "node:os") && (alias || inConstants))
+                    return true;
+                break;
+            }
+            if (n.name.text === "constants")
+                inConstants = true;
+        }
+    }
+    return false;
+}
 /** worker_threads' Worker and MessagePort: owned runtime handles that keep
  * their live object representation (DYN) wherever they are stored. */
 function isWorkerHandleSymbol(symbol, ctx) {
@@ -941,6 +1057,8 @@ function mapTypeInner(type, ctx) {
         checker.declarationsOf(directAlias).some((decl) => ctx.isStdlibFile(decl.getSourceFile()))) {
         return { kind: "object", className: "%Error" };
     }
+    if (isOsConstantsType(type, ctx) || isLegacyUrlType(type, ctx))
+        return DYN;
     // Immutable<T> (@scriptc/types) is a deep-readonly view: the value is
     // still the T it maps.
     const immutableSource = immutableSourceType(type, ctx);
@@ -1175,6 +1293,20 @@ function mapTypeInner(type, ctx) {
             return hasStr ? STRING : F64;
         }
     }
+    // @scriptc/experimental's LifetimeRegion: a synthetic program class,
+    // provenance-checked by the package's declaration file.
+    {
+        const regionSym = widened.getSymbol();
+        if (regionSym?.name === "LifetimeRegion") {
+            for (const d of checker.declarationsOf(regionSym)) {
+                if (!ts.isClassDeclaration(d))
+                    continue;
+                const region = ctx.lifetimeRegionClass?.(d);
+                if (region)
+                    return region;
+            }
+        }
+    }
     // Declaration-only package types have no compiled implementation.
     // Primitive and container types retain their structural mappings; types
     // owned by the standard library or explicit host mappings are handled
@@ -1228,8 +1360,12 @@ function mapTypeInner(type, ctx) {
         // changing this public representation. This is dynFallbackType's JS stance promoted into
         // the mapping itself; construction sites build dynArrLit (the checked-dynamic tree
         // array literal) and typed sources convert per element at the slot.
+        // Arrays of class-backed protocol values are the exception: each
+        // element is one checked-dynamic value (a class capsule or an object),
+        // so a native array of them keeps every element's identity and passes
+        // method calls a receiver they can dispatch.
         if (elem.kind === "dyn")
-            return DYN;
+            return ctx.classImplementedProtocol?.(elemTs) ? arrayOf(DYN) : DYN;
         // The shared predicate is the runtime/backend storage contract. In
         // particular, valid standalone values such as Date and opaque
         // handles do not automatically have an array element representation.
@@ -1508,7 +1644,7 @@ function mapTypeInner(type, ctx) {
     // it lowers like `unknown` (the dyn) — the same rule as `object` and
     // the empty object type, provenance-checked so a user's own `interface
     // Object` still maps as a record. Its Object.prototype member surface
-    // (`x.toString()`) fences at each use site, never silently.
+    // (`x.toString()`) fences at each use site with an explicit error.
     if (isStdlibInterface("Object"))
         return DYN;
     // NodeJS.Module / the shipped fallback's ScriptcModule: a process-lifetime
@@ -1542,17 +1678,17 @@ function mapTypeInner(type, ctx) {
             (isDeclaredInAmbientModule(d, "events") || isDeclaredInAmbientNamespace(d, "NodeJS")))) {
         return { kind: "object", className: RUNTIME_EMITTER_CLASS };
     }
-    // readline.Interface: the interface value is an f64 handle into the
-    // runtime's registry (the Timeout-id precedent). The NAME is generic,
-    // so the provenance check adds the enclosing ambient module, like
-    // net.Server (@types/node also declares Interface in
-    // readline/promises — that one stays unmapped and fences).
+    // readline.Interface and readline/promises.Interface: the interface
+    // value is an f64 handle into the runtime's registry (the Timeout-id
+    // precedent). The NAME is generic, so the provenance check adds the
+    // enclosing ambient module, like net.Server.
     if (psym?.name === "Interface" &&
         checker
             .declarationsOf(psym)
             .some((d) => (ts.isInterfaceDeclaration(d) || ts.isClassDeclaration(d)) &&
             ctx.isStdlibFile(d.getSourceFile()) &&
-            isDeclaredInAmbientModule(d, "readline"))) {
+            (isDeclaredInAmbientModule(d, "readline") ||
+                isDeclaredInAmbientModule(d, "readline/promises")))) {
         return F64;
     }
     // diagnostics_channel.Channel: the channel value is an f64 handle into
@@ -1745,6 +1881,16 @@ function mapTypeInner(type, ctx) {
             return null;
         return genResultRecord(elem, VOID, ctx.shapes, ctx.unions);
     }
+    // node:crypto's KeyObject: secret keys are native handles (scr_lib.c)
+    // whose getters and methods dispatch through the handle. The JsonWebKey
+    // that export() returns is a plain checked-dynamic object.
+    if ((psym?.name === "KeyObject" || psym?.name === "JsonWebKey") &&
+        checker
+            .declarationsOf(psym)
+            .some((d) => (ts.isClassDeclaration(d) || ts.isInterfaceDeclaration(d)) &&
+            ctx.isStdlibFile(d.getSourceFile()))) {
+        return DYN;
+    }
     if (psym &&
         FETCH_AMBIENT_TYPES.includes(psym.name) &&
         !(psym.name === "ReadableStream" &&
@@ -1759,8 +1905,10 @@ function mapTypeInner(type, ctx) {
     }
     // The stdlib Console interface (the global console and node:console
     // Console instances) is a native handle carried by the checked-dynamic
-    // representation and consumed by the console method lowerings.
-    if (psym?.name === "Console" &&
+    // representation and consumed by the console method lowerings. The
+    // stdlib Disposable (events.addAbortListener's result) is a checked
+    // object carrying its Symbol.dispose method.
+    if ((psym?.name === "Console" || psym?.name === "Disposable") &&
         checker
             .declarationsOf(psym)
             .some((d) => ts.isInterfaceDeclaration(d) && ctx.isStdlibFile(d.getSourceFile()))) {
@@ -1861,7 +2009,8 @@ function mapTypeInner(type, ctx) {
     if (isStdlibInterface("ArrayBuffer") ||
         isStdlibInterface("SharedArrayBuffer") ||
         isStdlibInterface("PropertyDescriptor") ||
-        isStdlibInterface("ProcessVersions"))
+        isStdlibInterface("ProcessVersions") ||
+        isStdlibInterface("ProcessRelease"))
         return DYN;
     if (Object.values(BYTES_ELEMENT_NAME).some((name) => isStdlibInterface(`${name}Constructor`)))
         return DYN;
@@ -1959,6 +2108,16 @@ function mapTypeInner(type, ctx) {
             isDeclaredInAmbientModule(d, "fs/promises"))) {
         return { kind: "fileHandle" };
     }
+    // fs.Dir: an open directory stream, declared in "fs" by both the
+    // fallback and @types/node.
+    if (psym?.name === "Dir" &&
+        checker
+            .declarationsOf(psym)
+            .some((d) => (ts.isInterfaceDeclaration(d) || ts.isClassDeclaration(d)) &&
+            ctx.isStdlibFile(d.getSourceFile()) &&
+            isDeclaredInAmbientModule(d, "fs"))) {
+        return { kind: "dir" };
+    }
     // child_process.SpawnSyncReturns: @types/node's generic interface (the
     // Buffer/string split is re-checked at the stdout/stderr READ — status
     // reads work either way) or the fallback declarations' plain interface.
@@ -2363,13 +2522,11 @@ function mapTypeInner(type, ctx) {
         }
     }
     // PromiseSettledResult<T>'s parts: the lib's PromiseFulfilledResult<T> /
-    // PromiseRejectedResult interfaces map to the documented HONEST SUBSET
-    // record { status: string }. The manual-allSettled pattern this
-    // mapping exists for (pMap) discards them. Construction literals still
-    // EVALUATE a dropped initializer for its effects — the awaited mapper —
-    // via the object-literal lowering's drop path. Both interfaces intern
-    // the SAME shape, so the settled union collapses to one record arm and
-    // status keeps its string reads/comparisons. SEMANTICS.md 46.
+    // PromiseRejectedResult interfaces map to the records { status, value }
+    // and { status, reason } (the reason is `any`, a dyn slot), interned
+    // explicitly. The settled union is a two-record union discriminated by
+    // the `status` literals, so `r.status === "fulfilled"` narrows to the
+    // arm that reads `value`.
     // net/dgram AddressInfo and dgram RemoteInfo: stdlib interfaces over
     // data properties, interned EXPLICITLY (the record path's provenance
     // fence keeps .d.ts shapes out of the structural walk — the
@@ -2387,7 +2544,8 @@ function mapTypeInner(type, ctx) {
     // is string[]; unsupported runtime modes throw at the call), and the
     // accepted-but-inert maxBuffer/windowsHide. Members outside this set
     // (env, killSignal, shell, uid, ...) keep the shape unmatched — their
-    // literals fence at the shape check instead of silently dropping.
+    // literals fence at the shape check instead of being dropped without a
+    // diagnostic.
     if (isStdlibInterface("ExecFileSyncOptionsWithStringEncoding")) {
         const optStr = withUndefinedArm(STRING, ctx.unions);
         const optNum = withUndefinedArm(F64, ctx.unions);
@@ -2497,10 +2655,11 @@ function mapTypeInner(type, ctx) {
     // hidden %dtype field carries the entry kind (libuv's UV_DIRENT
     // encoding) that the isFile/isDirectory/isSymbolicLink call lowerings
     // read (lowerDirentMethodCall — the StringDecoder pattern, so the
-    // %-field never surfaces through the lowered Dirent surface itself;
-    // JSON.stringify of a Dirent would show it — the documented
-    // internal-shape edge). @types/node declares Dirent<Name> generic over
-    // the name's encoding — only the string instantiation maps (the
+    // %-field never surfaces through the lowered Dirent surface itself).
+    // A row converted to dyn takes Node's Dirent prototype and Symbol(type)
+    // key, with %dtype non-enumerable (scr_dyn_dirent_finish), and inspect
+    // renders rows through that view. @types/node declares Dirent<Name>
+    // generic over the name's encoding — only the string instantiation maps (the
     // encoding:'buffer' readdir form has no lowering); the shipped fallback
     // declares it concrete (an interface; @types/node uses a class — both
     // provenance-checked, the Buffer/URL pattern).
@@ -2535,6 +2694,47 @@ function mapTypeInner(type, ctx) {
     // string arm. Key order is Node's runtime insertion order (node_os.cc
     // builds uid, gid, username, homedir, shell), so Object.keys over the
     // record answers exactly Node.
+    // os.CpuInfo (os.cpus()'s element), path.ParsedPath (path.parse()'s
+    // result) and path.FormatInputPathObject (path.format()'s argument):
+    // stdlib data interfaces interned explicitly, the AddressInfo pattern.
+    // Key order is Node's own (lib/os.js builds { model, speed, times:
+    // { user, nice, sys, idle, irq } }; path.parse builds { root, dir, base,
+    // ext, name }).
+    const cpuTimes = () => ({
+        kind: "record",
+        shapeId: ctx.shapes.intern(["idle", "irq", "nice", "sys", "user"].map((name) => ({ name, type: F64 })), false, undefined, ["user", "nice", "sys", "idle", "irq"]),
+    });
+    if (psym &&
+        checker
+            .declarationsOf(psym)
+            .some((d) => ts.isTypeLiteralNode(d) &&
+            ts.isPropertySignature(d.parent) &&
+            ts.isIdentifier(d.parent.name) &&
+            d.parent.name.text === "times" &&
+            ts.isInterfaceDeclaration(d.parent.parent) &&
+            d.parent.parent.name.text === "CpuInfo" &&
+            ctx.isStdlibFile(d.getSourceFile())))
+        return cpuTimes();
+    if (isStdlibInterface("CpuInfo")) {
+        const times = cpuTimes();
+        return {
+            kind: "record",
+            shapeId: ctx.shapes.intern([
+                { name: "model", type: STRING },
+                { name: "speed", type: F64 },
+                { name: "times", type: times },
+            ], false, undefined, ["model", "speed", "times"]),
+        };
+    }
+    if (isStdlibInterface("ParsedPath") || isStdlibInterface("FormatInputPathObject")) {
+        const field = psym.name === "ParsedPath" ? STRING : withUndefinedArm(STRING, ctx.unions);
+        if (!field)
+            return null;
+        return {
+            kind: "record",
+            shapeId: ctx.shapes.intern(["base", "dir", "ext", "name", "root"].map((name) => ({ name, type: field })), false, undefined, ["root", "dir", "base", "ext", "name"]),
+        };
+    }
     if (isStdlibInterface("UserInfo")) {
         const args = checker.getTypeArguments(widened);
         if (args.length > 1)
@@ -2579,6 +2779,31 @@ function mapTypeInner(type, ctx) {
             ], false, undefined, ["fingerprint", "validFrom", "validTo"]),
         };
     }
+    // perf_hooks' PerformanceEntry, PerformanceMark and PerformanceMeasure
+    // (performance.mark/measure and the getEntries family): ONE record shape
+    // for the three classes, so marks and measures share PerformanceEntry[]
+    // arrays. The visible fields are toJSON's, in its order; the hidden
+    // marker field keeps the shape distinct from a structurally equal user
+    // record (util.inspect names the class from entryType, like Node).
+    // @types/node declares the classes in perf_hooks and global interfaces
+    // over them; the shipped fallback declares the classes.
+    if ((psym?.name === "PerformanceEntry" ||
+        psym?.name === "PerformanceMark" ||
+        psym?.name === "PerformanceMeasure") &&
+        checker
+            .declarationsOf(psym)
+            .some((d) => (ts.isInterfaceDeclaration(d) || ts.isClassDeclaration(d)) &&
+            ctx.isStdlibFile(d.getSourceFile()))) {
+        return { kind: "record", shapeId: perfEntryShape(ctx.shapes, ctx.unions) };
+    }
+    // process.memoryUsage()'s record, in Node's key order.
+    if (isStdlibInterface("MemoryUsage")) {
+        const names = ["rss", "heapTotal", "heapUsed", "external", "arrayBuffers"];
+        return {
+            kind: "record",
+            shapeId: ctx.shapes.intern([...names].sort().map((name) => ({ name, type: F64 })), false, undefined, names),
+        };
+    }
     // process.cpuUsage()/threadCpuUsage()'s {user, system} microsecond
     // record and resourceUsage()'s getrusage record — stdlib data
     // interfaces interned explicitly (the RemoteInfo pattern; declared
@@ -2665,10 +2890,34 @@ function mapTypeInner(type, ctx) {
             ]),
         };
     }
-    if (isStdlibInterface("PromiseFulfilledResult") || isStdlibInterface("PromiseRejectedResult")) {
+    if (isStdlibInterface("PromiseFulfilledResult")) {
+        const arg = checker.getTypeArguments(widened)[0];
+        if (!arg)
+            return null;
+        // A valueless fulfillment (Promise<void>) still has its `value`
+        // property, always undefined: a dyn slot holds it, as it holds any.
+        const mapped = arg.flags &
+            (ts.TypeFlags.Void | ts.TypeFlags.Undefined | ts.TypeFlags.Never | ts.TypeFlags.Any)
+            ? DYN
+            : mapType(arg, ctx);
+        if (!mapped)
+            return null;
+        const valueT = mapped.kind === "void" || isUnitType(mapped) ? DYN : mapped;
         return {
             kind: "record",
-            shapeId: ctx.shapes.intern([{ name: "status", type: STRING }], false, undefined, ["status"]),
+            shapeId: ctx.shapes.intern([
+                { name: "status", type: STRING },
+                { name: "value", type: valueT },
+            ], false, undefined, ["status", "value"]),
+        };
+    }
+    if (isStdlibInterface("PromiseRejectedResult")) {
+        return {
+            kind: "record",
+            shapeId: ctx.shapes.intern([
+                { name: "reason", type: DYN },
+                { name: "status", type: STRING },
+            ], false, undefined, ["status", "reason"]),
         };
     }
     // Function types: exactly one call signature, no generics, and every
@@ -2992,7 +3241,16 @@ function mapTypeInner(type, ctx) {
             const byKey = new Map();
             const recordParts = [];
             const substitutedUnions = [];
-            for (const part of ts.constituentTypes(widened)) {
+            // The lib's `T extends readonly unknown[] | []` idiom (Promise.all,
+            // allSettled) maps an array input to `X[] | []`: the empty tuple is
+            // one of the array's own values.
+            const parts = ts.constituentTypes(widened);
+            const emptyTuple = (part) => checker.isTupleType(part) &&
+                checker.getTypeArguments(part).length === 0;
+            const hasArrayPart = parts.some((part) => checker.isArrayType(part));
+            for (const part of parts) {
+                if (hasArrayPart && emptyTuple(part))
+                    continue;
                 // TypeScript's client can retain impossible intersections in a
                 // distributed union. They have no inhabitants and no runtime tag.
                 if (checker.isNeverType(part))
@@ -4303,7 +4561,7 @@ function mapRecordTypeInner(widened, ctx) {
             return DYN;
         // A computed shape with NO members is not a real empty record: inside a
         // generic body `Partial<T>` resolves to no members at all (keyof T is
-        // still unknown there) — interning `{}` would be silently wrong. The
+        // still unknown there) — interning `{}` would give a wrong type. The
         // degenerate empties (`Partial<{}>`, `Omit<C, keyof C>`) go with it.
         // An INDEX-SIGNATURE shape is exempt: `Record<string, T>` legitimately
         // has zero declared members — the signature is the shape.
@@ -4343,8 +4601,8 @@ function mapRecordTypeInner(widened, ctx) {
                 // accessor MEMBERS map the same way so accessor records cross
                 // annotated boundaries (`function f(p: { get x(): number })`) —
                 // tsc lets a plain DATA property satisfy such a member, but the
-                // exact-shape stance turns that into a loud shape-mismatch fence
-                // at the literal, never a silent split. JS-file literals keep
+                // exact-shape stance turns that into a shape-mismatch diagnostic
+                // at the literal instead of an undiagnosed split. JS-file literals keep
                 // their existing paths (the CJS export-table narrowing and the
                 // checked-dynamic fallback), and .d.ts declarations stay out with
                 // the rest of the lib's type worlds.