@scriptc/compiler 0.2.3 → 0.2.5

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

@@ -0,0 +1,221 @@
+import type { IrModule } from "./ir.js";
+export interface RuntimeFeatures {
+    regex: boolean;
+    copying: boolean;
+    legacyTextDecoder: boolean;
+    fileHandle: boolean;
+    fetch: 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;
+}
+/** Inspect types and expressions together in one traversal. This is a fresh
+ * snapshot: callers may mutate an IR module between compilation passes. */
+export declare function moduleRuntimeFeatures(mod: IrModule): RuntimeFeatures;
+/** 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
+ * (native-toolchain.ts); regex-free programs keep the historical command line. The
+ * typed traversal visits type slots as well as executable nodes. */
+export declare function moduleUsesRegex(mod: IrModule): boolean;
+/** True when the module contains an intrinsic whose implementation lives
+ * in scr_copying.c. This is the link switch that keeps the optional
+ * Array-copying and typed-array bridge TU out of unrelated binaries. */
+export declare function moduleUsesCopying(mod: IrModule): boolean;
+/** True when a non-UTF-8 TextDecoder call survives lowering. This gates the
+ * generated legacy mapping tables inside scr_bytes.c; the default UTF-8
+ * decoder and unrelated Buffer users keep their prior runtime object. */
+export declare function moduleUsesLegacyTextDecoder(mod: IrModule): boolean;
+/** True when a FileHandle type survives in the module. This is the link
+ * switch for scr_file_handle.c; fs/promises.open carries the type inside its
+ * promise result even when no handle method is called. */
+export declare function moduleUsesFileHandle(mod: IrModule): boolean;
+/** True when user code lowers static fetch or the embedded npm graph
+ * reaches the engine's global fetch — the link switch that pulls scr_fetch.c +
+ * its socket/tls/zlib dependencies into the binary (native-toolchain.ts) and has the
+ * emitted main call scr_fetch_install. The npm graph records the embedded
+ * source fact with a parser + binder, so comments, strings, property names,
+ * and local `fetch` bindings do not change the link or target capability.
+ * Fetch-free graphs keep their exact historical link lines. */
+export declare function moduleUsesFetch(mod: IrModule): boolean;
+/** True when the module uses the process-events surface — the link switch
+ * that pulls scr_events.c into the binary and has the emitted main call
+ * scr_events_install (native-toolchain.ts + emitter; the scr_regex/scr_fetch/scr_zlib
+ * gating precedent). Event-free programs pay zero bytes and keep their
+ * exact link line. Same generic-walk shape as moduleUsesRegex. */
+export declare function moduleUsesProcessEvents(mod: IrModule): boolean;
+/** True when the module uses the node:events EventEmitter surface — the
+ * link switch that pulls scr_events_emitter.c into the binary (native-toolchain.ts; the
+ * scr_events.c gating precedent, but pure data structure: no install, no
+ * loop hooks). Two signals: the `%EventEmitter` class def rides the
+ * module (any emitter-typed value or `extends EventEmitter` subclass
+ * references it, and the emitted RC/trace helpers call scr_emitter_*),
+ * or an emitter.* libCall survived (the defaultMaxListeners statics carry
+ * no emitter-typed value). Emitter-free programs pay zero bytes and keep
+ * their exact link line. */
+export declare function moduleUsesEmitter(mod: IrModule): boolean;
+/** True when the program touches the node:stream surface (scr_stream.c —
+ * the moduleUsesEmitter story: the class defs ride the module whenever a
+ * stream-typed value exists, and every stream libCall names its unit).
+ * Stream programs always use the emitter unit too — the stream class
+ * defs pull `%EventEmitter` through their base chain, so
+ * 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 embedded npm graph has an edge into `builtin` — the
+ * island shim needs the corresponding native bridge linked (zlib's is
+ * the first; the emitted main installs it before any island entry). */
+export declare function moduleEmbedsBuiltin(mod: IrModule, builtin: string): boolean;
+/** Embedded module texts at least this long are DEFLATE-compressed into
+ * the emitted LLVM (island.ts; each stays plain when deflate does not
+ * shrink it) and inflated lazily by the island's module loader at first
+ * load. Below it the zlib round trip cannot pay for itself. */
+export declare const NPM_COMPRESS_MIN = 1024;
+/** True when the emitted npm tables will carry compressed module text —
+ * the SAME candidate test island.ts compresses by, so index.ts's
+ * zlib link switch and emitter.ts's inflater installation stay in
+ * lockstep with the emission (a candidate whose deflate happens not to
+ * shrink stays plain; the installed inflater is then just unused). */
+export declare function moduleEmbedsCompressedNpm(mod: IrModule): boolean;
+/** True when the module contains any zlib libCall (the static lowering)
+ * OR the embedded npm graph imports node:zlib (the island shim) — the
+ * link switch that pulls scr_zlib.c + the system libz into the binary
+ * (native-toolchain.ts); zlib-free programs keep their exact link line. Same
+ * generic-walk shape as moduleUsesRegex: `kind`/`fn` discriminants live
+ * only on IR objects. */
+export declare function moduleUsesZlib(mod: IrModule): boolean;
+/** True when the module contains any dc.* libCall — the link switch that
+ * pulls scr_dc.c (the diagnostics_channel registry and pub/sub) into the
+ * binary (native-toolchain.ts). Channel-free binaries keep their exact size class.
+ * Same walk shape as moduleUsesZlib. */
+export declare function moduleUsesDc(mod: IrModule): boolean;
+/** True when the module contains any assert libCall — the link switch
+ * that pulls scr_assert.c into the binary (native-toolchain.ts). scr_regex.c calls the
+ * assert throw/inspect helpers (assert.match lives there), so the regex
+ * switch also pulls scr_assert.c; assert-free, regex-free binaries keep
+ * the historical command line and size. Same walk shape as
+ * moduleUsesZlib. */
+export declare function moduleUsesAssert(mod: IrModule): boolean;
+/** True when the module contains any dynInvoke node or dyn.defineProps
+ * libCall — the link switch that pulls scr_dyn_invoke.c (the prototype-
+ * method dispatch on dyn receivers, plus scr_dyn_display and
+ * scr_dyn_define_props) into the binary (native-toolchain.ts; the assert gating
+ * precedent — dispatch-free binaries keep their exact size class). Same
+ * walk shape as moduleUsesZlib. */
+export declare function moduleUsesDynInvoke(mod: IrModule): boolean;
+/** True when the module contains any insp libCall — the link switch that
+ * pulls scr_inspect.c into the binary (native-toolchain.ts; the assert gating
+ * precedent — inspect-free binaries keep the historical command line and
+ * size class). Same walk shape as moduleUsesZlib. */
+/** True when the module needs scr_async_dyn.c — the checked-dynamic
+ * async surfaces (dyn-promise then/catch/finally reactions, await of a
+ * dyn value, `new Promise(setImmediate)`, AsyncLocalStorage, the
+ * unhandledRejection/warning process events). Also pulled by the
+ * dynInvoke and dc gates (their TUs call into this one) — native-toolchain.ts. Same
+ * walk shape as moduleUsesZlib. */
+export declare function moduleUsesDynAsync(mod: IrModule): boolean;
+export declare function moduleUsesInspect(mod: IrModule): boolean;
+/** True when the module reaches child_process or carries one of its runtime
+ * handle/result types. Besides the existing link consequence, this gates the
+ * checked-dynamic ChildProcess handle table installed from scr_child.c. */
+export declare function moduleUsesChildProcess(mod: IrModule): boolean;
+/** True when the module contains any net libCall — the link switch that
+ * pulls scr_net.c into the binary and has the emitted main call
+ * scr_net_install (native-toolchain.ts + emitter; the scr_events gating precedent).
+ * Net-free programs pay zero bytes and keep their exact link line. Same
+ * generic-walk shape as moduleUsesZlib. */
+export declare function moduleUsesNet(mod: IrModule): boolean;
+/** True when the module contains any sym.* libCall or a symbol-kind type
+ * anywhere in the IR — the link switch that pulls scr_symbol.c into the
+ * binary (native-toolchain.ts; the scr_net gating precedent — no install call, the
+ * Symbol.for registry initializes lazily). The TYPE check matters like
+ * net's: a symbol-typed local whose initializer compiled to a runtime
+ * fence still emits release calls that need the unit linked. Symbol-free
+ * programs pay zero bytes and keep their exact link line. */
+export declare function moduleUsesSymbol(mod: IrModule): boolean;
+/** True when bigint runtime operations or bigint-typed storage appears in
+ * the IR. The type check keeps retain/release references link-safe even
+ * when a producing statement was replaced by a runtime fence. */
+export declare function moduleUsesBigInt(mod: IrModule): boolean;
+/** True when the module uses the URLSearchParams surface — sp.* libCalls,
+ * the url.searchParams getter, or a searchParams-kind type anywhere on
+ * the IR (a fenced statement can leave a typed local whose release call
+ * still needs the unit linked) — the link switch that pulls
+ * scr_url_params.c into the binary (the moduleUsesSymbol precedent: pure
+ * data structure, no loop hooks, cross-compiles everywhere). sp-free
+ * programs keep their exact link line; scr_url.c itself stays
+ * always-linked and never references the unit. */
+export declare function moduleUsesSearchParams(mod: IrModule): boolean;
+/** True when the module uses the node:querystring surface — the qs.*
+ * libCalls that live in scr_qs.c (parse/stringify/unescape; qs.escape
+ * emits the always-linked component encoder and deliberately does NOT
+ * flip this switch) — the link switch that pulls scr_qs.c into the
+ * binary (the moduleUsesSearchParams precedent: pure data transforms, no
+ * loop hooks, cross-compiles everywhere). qs-free programs keep their
+ * exact link line. Same generic-walk shape as moduleUsesZlib. */
+export declare function moduleUsesQs(mod: IrModule): boolean;
+/** True when the module uses native util parsing, comparison, or styling.
+ * The utility units also follow their required symbol, inspection, and
+ * warning features, independently of the island's node:util shim. */
+export declare function moduleUsesParseArgs(mod: IrModule): boolean;
+/** True when the module contains any fs.watch/watcher.* libCall — the
+ * link switch that pulls scr_watch.c into the binary and has the emitted
+ * main call scr_watch_install (native-toolchain.ts + emitter; the scr_net gating
+ * precedent). Watch-free programs pay zero bytes and keep their exact
+ * link line. Same generic-walk shape as moduleUsesZlib. */
+export declare function moduleUsesFsWatch(mod: IrModule): boolean;
+/** True when the module contains any test.* libCall or a testCtx handle
+ * type — the link switch that pulls scr_test.c into the binary and has
+ * the emitted main return scr_test_exit_code() after the loop drains
+ * (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 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
+ * precedent — dns.lookup lives in the same unit, so either prefix
+ * answers). Dgram-free programs pay zero bytes and keep their exact link
+ * line. Same generic-walk shape as moduleUsesZlib. */
+export declare function moduleUsesDgram(mod: IrModule): boolean;
+/** True when the module contains any http.* libCall — the link switch
+ * that pulls scr_http.c into the binary (native-toolchain.ts; moduleUsesNet already
+ * answers true for these, so scr_net.c comes along). */
+export declare function moduleUsesHttpServer(mod: IrModule): boolean;
+/** True when the module uses the REAL h2 surface (scr_http2.c): any core
+ * http2.* libCall, or an h2 handle type left behind by a fenced statement
+ * (its emitted release call needs the unit — the moduleUsesNet story). */
+export declare function moduleUsesHttp2(mod: IrModule): boolean;
+/** True when the module contains any tls.* or https.* libCall — the link
+ * switch that pulls scr_tls.c and the vendored mbedTLS archive into the
+ * binary (native-toolchain.ts; moduleUsesNet and moduleUsesHttpServer already answer
+ * true for these, so scr_net.c and scr_http.c come along). TLS-free
+ * programs keep their exact link line and never build mbedTLS. */
+export declare function moduleUsesTls(mod: IrModule): boolean;
+/** True when the module contains any tlsca.* libCall — the link switch
+ * for scr_tls_ca.c, the CA-store introspection unit (getCACertificates /
+ * rootCertificates / setDefaultCACertificates). Deliberately SEPARATE
+ * from moduleUsesTls: the unit is plain PEM-block bookkeeping, so a
+ * program that only inspects the CA store never pulls mbedTLS. native-toolchain.ts
+ * 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;