@scriptc/compiler 0.3.5 → 0.4.0

package/dist/ir/runtime-features.d.ts

@@ -1,39 +1,141 @@
-import type { IrModule } from "./ir.js";
-export interface RuntimeFeatures {
-    regex: boolean;
-    copying: boolean;
-    legacyTextDecoder: boolean;
-    fileHandle: boolean;
-    fetch: boolean;
-    eventTarget: boolean;
-    processEvents: boolean;
-    emitter: boolean;
-    stream: boolean;
-    zlib: boolean;
-    dc: boolean;
-    assert: boolean;
-    dynInvoke: boolean;
-    dynAsync: boolean;
-    inspect: boolean;
-    childProcess: boolean;
-    net: boolean;
-    symbol: boolean;
-    bigint: boolean;
-    searchParams: boolean;
-    qs: boolean;
-    parseArgs: boolean;
-    fsWatch: boolean;
-    nodeTest: boolean;
-    dgram: boolean;
-    http: boolean;
-    http2: boolean;
-    tls: boolean;
-    tlsCa: boolean;
-    cipher: boolean;
-}
+import type { IrClassDef, IrExpr, IrModule, IrRecordShape, IrType, IrUnionDef } from "./ir.js";
+import type { IrLibFn } from "./builtin-signatures.js";
 /** Inspect types and expressions together in one traversal. This is a fresh
  * snapshot: callers may mutate an IR module between compilation passes. */
+/** The checked-dynamic undefined value (dynUndefinedExpr). */
+export declare function isDynUndefined(e: IrExpr): boolean;
 export declare function moduleRuntimeFeatures(mod: IrModule): RuntimeFeatures;
+/** The module's record shapes, unions and class layouts by id. */
+interface TypeTables {
+    records: Map<string, IrRecordShape>;
+    unions: Map<string, IrUnionDef>;
+    classes: Map<string, IrClassDef>;
+}
+/** The libCall nodes the rules below test. */
+type LibCallNode = IrExpr & {
+    kind: "libCall";
+};
+/** What makes a program need one optional runtime unit. The feature is set
+ * when any condition holds: `initial` from the module's declarations, a
+ * libCall named in `fns` or starting with one of `prefixes`, a libCall
+ * `libCall` accepts, another expression node `expr` accepts, or a type
+ * slot of one of the `types` kinds. A libCall or type that needs several
+ * units appears in each unit's rule. */
+interface RuntimeFeatureRule {
+    initial?: (mod: IrModule) => boolean;
+    fns?: readonly IrLibFn[];
+    prefixes?: readonly string[];
+    libCall?: (node: LibCallNode) => boolean;
+    expr?: (node: IrExpr, tables: () => TypeTables) => boolean;
+    types?: readonly IrType["kind"][];
+}
+/** One rule per runtime feature, sorted by name. A new feature is an
+ * entry here and its line in noRuntimeFeatures; RuntimeFeatures, the scan
+ * and its early exit derive from this table. */
+declare const RUNTIME_FEATURE_RULES: {
+    assert: RuntimeFeatureRule;
+    /** The program enters AsyncLocalStorage stores (store.run, enterWith,
+     * a diagnostics_channel store binding) or reads the test runner's
+     * context (getTestContext): its timer, immediate, tick and
+     * queueMicrotask scheduling goes through the runtime's *_als entry
+     * points, which carry the active stores into each callback. */
+    asyncContext: RuntimeFeatureRule;
+    /** scr_wasm.c converts i64 values through BigInt. */
+    bigint: RuntimeFeatureRule;
+    childProcess: RuntimeFeatureRule;
+    /** scr_cipher.c over the mbedTLS archive; DEP0182 reports through the
+     * process-warning unit, and unknown output encodings render through the
+     * inspect unit. */
+    cipher: RuntimeFeatureRule;
+    copying: RuntimeFeatureRule;
+    dc: RuntimeFeatureRule;
+    /** dns.lookup lives in the dgram unit. */
+    dgram: RuntimeFeatureRule;
+    /** node:dns/promises: scr_dns_promises.c over the dgram unit. */
+    dnsPromises: RuntimeFeatureRule;
+    dynAsync: RuntimeFeatureRule;
+    /** EventEmitter and the stream classes as untyped constructor values
+     * (scr_dyn_builtin_class.c), which call listeners through the dyn-invoke
+     * unit, render unhandled 'error' payloads through the inspect unit and
+     * create EventEmitter's private symbols through the symbol unit. */
+    dynBuiltinClass: RuntimeFeatureRule;
+    /** The stream classes as untyped constructor values with their stream
+     * half (scr_dyn_builtin_stream.c): native stream state for constructor
+     * functions, over the stream unit. */
+    dynBuiltinStream: RuntimeFeatureRule;
+    dynInvoke: RuntimeFeatureRule;
+    /** The program has dynamic-tier jsval operations (js.* builtins, the
+     * jsval pass): links the scr_js_* units (two-tier design I3). */
+    dynTier: RuntimeFeatureRule;
+    /** Checked-dynamic stream slots test values and pipe into JavaScript
+     * stream objects (scr_stream_dyn.c). */
+    streamDyn: RuntimeFeatureRule;
+    /** The stream unit emits through the emitter unit, also when the
+     * program constructs no stream (a pipeline of functions). */
+    emitter: RuntimeFeatureRule;
+    /** Subclasses of the runtime EventTarget/Event bases tear down and box
+     * through the EventTarget unit even when no event.* libCall survives. */
+    eventTarget: RuntimeFeatureRule;
+    /** events.once(emitter, name, { signal }) (scr_events_once_signal.c). */
+    eventsOnceSignal: RuntimeFeatureRule;
+    fetch: RuntimeFeatureRule;
+    fileHandle: RuntimeFeatureRule;
+    fsWatch: RuntimeFeatureRule;
+    /** A socket 'lookup' listener: the C main installs the net unit's
+     * lookup records (scr_net_lookup_install). */
+    netLookup: RuntimeFeatureRule;
+    http: RuntimeFeatureRule;
+    /** The real h2 surface (scr_http2.c); the legacy http2.* libCalls of the
+     * allowHTTP1 slice are served by scr_http.c and scr_tls.c. */
+    http2: RuntimeFeatureRule;
+    /** scr_test.c renders thrown strings with the inspect unit's string
+     * formatting; scr_util_callable.c wraps the inspect unit; readline's
+     * terminal unit prints completion errors through it when there is a
+     * completer. */
+    inspect: RuntimeFeatureRule;
+    legacyTextDecoder: RuntimeFeatureRule;
+    /** The program calls mock.timers members: its timer calls go through
+     * scr_test.c's mock-aware entry points. */
+    mockTimers: RuntimeFeatureRule;
+    net: RuntimeFeatureRule;
+    nodeTest: RuntimeFeatureRule;
+    /** scr_util_callable.c reads options through the parseArgs unit's
+     * descriptors. */
+    parseArgs: RuntimeFeatureRule;
+    /** perf_hooks event-loop metrics (eventLoopUtilization,
+     * monitorEventLoopDelay): scr_perf_loop.c. */
+    perfLoop: RuntimeFeatureRule;
+    processEvents: RuntimeFeatureRule;
+    /** scr_url_legacy.c parses and stringifies queries. */
+    qs: RuntimeFeatureRule;
+    /** scr_url_legacy.c lowercases and normalizes hostnames with the regex
+     * unit's libunicode, NODE_DEBUG matching in scr_util_callable.c and
+     * readline's terminal unit use the regex unit, and locale case mapping
+     * runs its default conversion. */
+    regex: RuntimeFeatureRule;
+    searchParams: RuntimeFeatureRule;
+    /** stdin setEncoding / string data listeners / stdio 'resize' events. A
+     * typed string 'data' listener takes setEncoding-decoded chunks; the
+     * process stream object's setEncoding and 'resize' members are reached
+     * by name (dynamic member calls and event-name strings). */
+    stdioExtended: RuntimeFeatureRule;
+    stream: RuntimeFeatureRule;
+    /** A Dirent row converted to dyn carries Node's Symbol(type) key
+     * (scr_dyn_dirent_finish, defined in scr_symbol.c). */
+    symbol: RuntimeFeatureRule;
+    tls: RuntimeFeatureRule;
+    tlsCa: RuntimeFeatureRule;
+    /** process.emitWarning is assigned (process.setEmitWarning). */
+    warningReplace: RuntimeFeatureRule;
+    /** The WebAssembly API (scr_wasm.c). */
+    wasm: RuntimeFeatureRule;
+    /** crypto.subtle importKey/sign/verify/digest and CryptoKey:
+     * scr_webcrypto.c. */
+    webcrypto: RuntimeFeatureRule;
+    zlib: RuntimeFeatureRule;
+};
+type RuntimeFeatureName = keyof typeof RUNTIME_FEATURE_RULES;
+export type RuntimeFeatures = Record<RuntimeFeatureName, boolean>;
 /** True when the module contains any regex construct — a regexLit /
  * regexIntrinsic node or a regex-typed slot anywhere. This is the link
  * switch that pulls scr_regex.c + the vendored libregexp into the binary
@@ -80,6 +182,11 @@ export declare function moduleUsesEmitter(mod: IrModule): boolean;
  * moduleUsesEmitter answers true whenever this does. Stream-free
  * programs pay zero bytes and keep their exact link line. */
 export declare function moduleUsesStream(mod: IrModule): boolean;
+/** True when the program links scr_dyn_builtin_stream.c (stream classes
+ * as untyped constructor values): its runtime streams box through that
+ * unit's view and checked casts to the stream classes accept constructor-
+ * function streams. Programs without it keep their exact code. */
+export declare function moduleUsesDynBuiltinStream(mod: IrModule): boolean;
 export declare const NPM_COMPRESS_MIN = 1024;
 export declare function moduleUsesZlib(mod: IrModule): boolean;
 /** True when the module contains any dc.* libCall — the link switch that
@@ -165,6 +272,11 @@ export declare function moduleUsesFsWatch(mod: IrModule): boolean;
  * (native-toolchain.ts + emitter; the moduleUsesDgram shape). Test-free programs pay
  * zero bytes and keep their exact link line. */
 export declare function moduleUsesNodeTest(mod: IrModule): boolean;
+/** True when the module calls a mock.timers member (a test.mockTimers* or
+ * test.ctxMockTimers* libCall). The emitter then routes the timer calls
+ * through scr_test.c's mock-aware entry points; other programs keep the
+ * loop's timer functions. */
+export declare function moduleUsesMockTimers(mod: IrModule): boolean;
 /** True when the module contains any dgram.* or dns.* libCall — the
  * link switch that pulls scr_dgram.c into the binary and has the emitted
  * main call scr_dgram_install (native-toolchain.ts + emitter; the scr_net gating
@@ -194,3 +306,8 @@ export declare function moduleUsesTls(mod: IrModule): boolean;
  * also compiles the unit whenever TLS itself links — scr_tls.c consults
  * the unit's default-set override for its trust anchors. */
 export declare function moduleUsesTlsCa(mod: IrModule): boolean;
+/** True when the module has dynamic-tier jsval operations: the link switch
+ * for the scr_js_* runtime units (two-tier design I3). Programs without
+ * them never link a scr_js_ symbol. */
+export declare function moduleUsesDynTier(mod: IrModule): boolean;
+export {};