@scriptc/compiler 0.3.2 → 0.3.4

package/dist/frontend/type-mapper.js

@@ -1,7 +1,8 @@
 import { InternalCompilerError } from "../errors.js";
+import { mockCallRecordType, mockContextType } from "./mock-shapes.js";
 import * as ts from "./ts7/adapter.js";
 import { bodyReadsArguments } from "./arguments-usage.js";
-import { BYTES_ELEMENT_NAME, arrayOf, BOOL, bytesOf, canConvertToDyn, CHILD_T, CRYPTOHASH_T, CRYPTOHMAC_T, DATE_T, DYN, F64, funcOf, isSupportedArrayElem, isSupportedIndexValue, isSupportedMapKey, isSupportedMapValue, isSupportedSetElem, isUnitType, mapOf, NULL_T, PROCSTREAM_T, RUNTIME_EMITTER_CLASS, RUNTIME_ERROR_CLASSES, RUNTIME_STREAM_CLASSES, setOf, STRING, SYMBOL_T, typeEquals, typeKey, unionContainerArmsOk, UNDEFINED_T, VOID, } from "../ir/ir.js";
+import { BYTES_ELEMENT_NAME, arrayOf, BOOL, bytesOf, canConvertToDyn, CHILD_T, CRYPTOHASH_T, CRYPTOHMAC_T, DATE_T, DYN, F64, funcOf, isSupportedArrayElem, isSupportedIndexValue, isSupportedMapKey, isSupportedMapValue, isSupportedSetElem, isUnitType, mapOf, NULL_T, PROCSTREAM_T, RUNTIME_EMITTER_CLASS, RUNTIME_ERROR_CLASSES, RUNTIME_STREAM_CLASSES, ZLIB_STREAM_MODES, setOf, STRING, SYMBOL_T, typeEquals, typeKey, unionContainerArmsOk, UNDEFINED_T, VOID, } from "../ir/ir.js";
 import { BIGINT_T } from "../ir/ir.js";
 import { literalValues } from "./literal-values.js";
 import { remapUnionDiscriminant } from "./union-discriminants.js";
@@ -87,7 +88,26 @@ export const FETCH_AMBIENT_TYPES = [
     "ReadableStreamReadResult",
     "ReadableStreamReadValueResult",
     "ReadableStreamReadDoneResult",
+    "Blob",
+    "File",
+    "BlobPropertyBag",
+    "FilePropertyBag",
+    "BlobOptions",
+    "FileOptions",
 ];
+/** node:crypto's Cipheriv and Decipheriv names in @types/node. */
+export const CIPHER_TYPE_NAMES = new Set([
+    "Cipheriv",
+    "Decipheriv",
+    "CipherCCM",
+    "CipherGCM",
+    "CipherOCB",
+    "CipherChaCha20Poly1305",
+    "DecipherCCM",
+    "DecipherGCM",
+    "DecipherOCB",
+    "DecipherChaCha20Poly1305",
+]);
 /** 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
@@ -646,6 +666,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":
@@ -721,6 +743,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) {
@@ -849,6 +899,43 @@ 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
@@ -984,7 +1071,7 @@ function mapTypeInner(type, ctx) {
         checker.declarationsOf(directAlias).some((decl) => ctx.isStdlibFile(decl.getSourceFile()))) {
         return { kind: "object", className: "%Error" };
     }
-    if (isOsConstantsType(type, ctx))
+    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.
@@ -1220,17 +1307,18 @@ function mapTypeInner(type, ctx) {
             return hasStr ? STRING : F64;
         }
     }
-    // @scriptc/experimental's LifetimeRegion: a synthetic program class,
-    // provenance-checked by the package's declaration file.
+    // @scriptc/experimental's LifetimeRegion and InternTable: synthetic
+    // program classes, provenance-checked by the package's declaration file.
     {
-        const regionSym = widened.getSymbol();
-        if (regionSym?.name === "LifetimeRegion") {
-            for (const d of checker.declarationsOf(regionSym)) {
+        const classSym = widened.getSymbol();
+        const name = classSym?.name;
+        if (name === "LifetimeRegion" || name === "InternTable") {
+            for (const d of checker.declarationsOf(classSym)) {
                 if (!ts.isClassDeclaration(d))
                     continue;
-                const region = ctx.lifetimeRegionClass?.(d);
-                if (region)
-                    return region;
+                const synthetic = name === "LifetimeRegion" ? ctx.lifetimeRegionClass?.(d) : ctx.internTableClass?.(d);
+                if (synthetic)
+                    return synthetic;
             }
         }
     }
@@ -1287,8 +1375,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.
@@ -1562,12 +1654,19 @@ function mapTypeInner(type, ctx) {
         if (isStdlibInterface(rec.lib))
             return { kind: "object", className: irName };
     }
+    // node:assert's AssertionError is declared as a class (in the shipped
+    // fallback and in @types/node), not as a lib interface.
+    if (psym?.name === "AssertionError" &&
+        checker
+            .declarationsOf(psym)
+            .some((d) => ts.isClassDeclaration(d) && ctx.isStdlibFile(d.getSourceFile())))
+        return { kind: "object", className: "%AssertionError" };
     // The lib's `Object` interface is a TOP type: tsc admits every
     // non-nullish value into an `Object` slot (`const x: Object = "s"`), so
     // 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
@@ -1601,17 +1700,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
@@ -1804,6 +1903,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" &&
@@ -1827,6 +1936,14 @@ function mapTypeInner(type, ctx) {
             .some((d) => ts.isInterfaceDeclaration(d) && ctx.isStdlibFile(d.getSourceFile()))) {
         return DYN;
     }
+    // node:crypto Cipheriv/Decipheriv values (and @types/node's per-mode
+    // interfaces over them) are native handles carried by the checked-dynamic
+    // representation; lowerCipherMethodCall dispatches their methods.
+    if (psym !== undefined &&
+        CIPHER_TYPE_NAMES.has(psym.name) &&
+        checker.declarationsOf(psym).some((d) => ctx.isStdlibFile(d.getSourceFile()))) {
+        return DYN;
+    }
     // ReadonlyMap/ReadonlySet are the SAME runtime values as Map/Set — the
     // readonly-ness is a checker-only view (no mutating members on the
     // interface), so both map to the identical IR kinds and the read-side
@@ -1922,7 +2039,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;
@@ -2020,6 +2138,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.
@@ -2183,6 +2311,18 @@ function mapTypeInner(type, ctx) {
             return { kind: "object", className: irName };
         }
     }
+    // node:zlib's stream classes (the shipped fallback declarations): their
+    // instances are runtime Transform streams.
+    if (psym !== undefined &&
+        ZLIB_STREAM_MODES.has(psym.name) &&
+        checker
+            .declarationsOf(psym)
+            .some((d) => ts.isClassDeclaration(d) &&
+            ctx.isStdlibFile(d.getSourceFile()) &&
+            !isNodeTypesPath(d.getSourceFile().fileName) &&
+            isDeclaredInAmbientModule(d, "zlib"))) {
+        return { kind: "object", className: "%Transform" };
+    }
     if ((psym?.name === "Readable" &&
         checker
             .declarationsOf(psym)
@@ -2221,6 +2361,23 @@ function mapTypeInner(type, ctx) {
             isDeclaredInAmbientModule(d, "test"))) {
         return { kind: "testCtx" };
     }
+    // node:test's MockFunctionContext<F> and MockFunctionCall<F>: compiler
+    // records built from F (mock-shapes.ts). Mock<F> then maps as the hybrid
+    // { %call: F, mock } record through mapHybridCallableIntersection.
+    if ((psym?.name === "MockFunctionContext" || psym?.name === "MockFunctionCall") &&
+        checker
+            .declarationsOf(psym)
+            .some((d) => ts.isInterfaceDeclaration(d) &&
+            ctx.isStdlibFile(d.getSourceFile()) &&
+            isDeclaredInAmbientModule(d, "test"))) {
+        const fnTs = checker.getTypeArguments(widened)[0];
+        const fn = fnTs ? mapType(fnTs, ctx) : null;
+        if (!fn || fn.kind !== "func")
+            return null;
+        return psym.name === "MockFunctionContext"
+            ? mockContextType(fn, ctx)
+            : mockCallRecordType(fn, ctx);
+    }
     // NodeJS.ErrnoException: @types/node's `interface ErrnoException extends
     // Error` (dns/fs callback error types). It IS an Error at runtime — map
     // it to the runtime %Error hierarchy like the lib Error interfaces
@@ -2435,6 +2592,16 @@ function mapTypeInner(type, ctx) {
     // PromiseFulfilledResult precedent). RemoteInfo's 'IPv4' | 'IPv6'
     // family widens to string here; the runtime only ever answers "IPv4"
     // (udp4 is the one lowered socket type).
+    // dns.lookup's all: true entries: { address, family }.
+    if (isStdlibInterface("LookupAddress")) {
+        return {
+            kind: "record",
+            shapeId: ctx.shapes.intern([
+                { name: "address", type: STRING },
+                { name: "family", type: F64 },
+            ], false, undefined, ["address", "family"]),
+        };
+    }
     // child_process.ExecFileSyncOptionsWithStringEncoding: the exec-options
     // interface interned explicitly on the AddressInfo pattern, so a TYPED
     // options value (`const commandOptions: ExecFileSyncOptions... = {...}`,
@@ -2446,7 +2613,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);
@@ -2478,6 +2646,30 @@ function mapTypeInner(type, ctx) {
             ], false, undefined, ["address", "family", "port"]),
         };
     }
+    // net's 'drop' payload: the record the runtime's address object checks
+    // into, each optional field with its declared type.
+    if (isStdlibInterface("DropArgument")) {
+        const known = [
+            "localAddress",
+            "localPort",
+            "localFamily",
+            "remoteAddress",
+            "remotePort",
+            "remoteFamily",
+        ];
+        const fields = [];
+        for (const property of checker.getPropertiesOfType(widened)) {
+            if (!known.includes(property.name))
+                return null;
+            const type = mapType(checker.getTypeOfSymbol(property), ctx);
+            if (!type)
+                return null;
+            fields.push({ name: property.name, type });
+        }
+        const order = fields.map((field) => field.name);
+        fields.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        return { kind: "record", shapeId: ctx.shapes.intern(fields, false, undefined, order) };
+    }
     // Filesystem options are data records. Keep their declared optional fields
     // instead of allowing arbitrary standard-library interfaces into records.
     if ((psym?.name === "FileReadOptions" ||
@@ -2556,10 +2748,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).
@@ -2679,6 +2872,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
@@ -4436,7 +4654,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.
@@ -4476,8 +4694,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.