@scriptc/compiler 0.0.0 → 0.0.2

package/dist/frontend/lowering/surfaces.d.ts

@@ -0,0 +1,272 @@
+import * as ts from "../ts7/adapter.js";
+import type { Lowerer } from "./lowerer.js";
+import { UNSUPPORTED } from "../../diagnostics/diagnostic.js";
+import { IrExpr, IrLibFn, IrStrIntrinsicMethod, IrType } from "../../ir/nodes.js";
+/** Statement-level constructs rejected wholesale, keyed by syntax kind. */
+export declare const UNSUPPORTED_STMT: Partial<Record<ts.SyntaxKind, {
+    code: keyof typeof UNSUPPORTED;
+    feature?: string;
+}>>;
+export declare const UNSUPPORTED_EXPR: Partial<Record<ts.SyntaxKind, {
+    code: keyof typeof UNSUPPORTED;
+    feature?: string;
+}>>;
+/** The narrow-first hint every union fence shares — how to get from a
+ * union-typed value to the single arm the static compiler can use. One
+ * string so the fences speak with one voice (and match SC2003's hint). */
+export declare const NARROW_FIRST = "narrow first: check a discriminant field, or compare with '!== undefined'/'!== null' for unit arms";
+/** True iff evaluating the option value can have no observable effect —
+ * the drop-safety test of the options-record stance. Literals, identifier
+ * reads (shorthand included), closures (created, never called — the key
+ * is unknown, so nothing can reach it), prefix +/-/! over these, and
+ * object/array literals of these all qualify; anything with a call,
+ * a property read (getters), or an assignment does not. */
+export declare function sideEffectFreeOptionValue(node: ts.Expression): boolean;
+/** The stance's tail: `key` is outside the walk's lowered set. Documented
+ * keys of the API fence by name (pointed per-key hints first, the walk's
+ * supported-options hint otherwise); undocumented keys drop like Node
+ * drops them when the value is side-effect-free, and fence when it is
+ * not. `prop` is the property entry (assignment or shorthand) for spans. */
+export declare function fenceOrDropOptionKey(L: Lowerer, prop: ts.ObjectLiteralElementLike, key: string, api: string, documented: ReadonlySet<string>, supportedHint: string, pointedHints?: Record<string, string | undefined>): void;
+/** http.request/http.get's documented option keys (Node v24 — the
+ * `http.request(options)` and `net.socket.connect` tables); everything
+ * else on a client options literal is undocumented and drops. */
+export declare const HTTP_CLIENT_DOCUMENTED_OPTIONS: ReadonlySet<string>;
+/** http.createServer / http.Server's documented option keys (Node v24 —
+ * http.createServer options + the net.Server knobs it forwards). The
+ * lowered pair is requireHostHeader/joinDuplicateHeaders; the rest fence
+ * by name here, and unknown keys drop like Node drops them. */
+export declare const HTTP_SERVER_DOCUMENTED_OPTIONS: ReadonlySet<string>;
+/** https.request adds tls.connect's client-side TLS knobs. */
+export declare const HTTPS_CLIENT_DOCUMENTED_OPTIONS: ReadonlySet<string>;
+/** tls.createServer / tls.createSecureContext / https.createServer /
+ * http2.createSecureServer's documented TLS-side option keys (Node v24 —
+ * tls.createSecureContext + tls.createServer + net.createServer). */
+export declare const TLS_SERVER_DOCUMENTED_OPTIONS: ReadonlySet<string>;
+/** http2.createSecureServer's documented keys: the h2 knobs on top of the
+ * TLS server set. */
+export declare const HTTP2_SECURE_SERVER_DOCUMENTED_OPTIONS: ReadonlySet<string>;
+/** fs.watch's documented option keys. */
+export declare const FS_WATCH_DOCUMENTED_OPTIONS: ReadonlySet<string>;
+/** fs.readdirSync's documented option keys. */
+export declare const FS_READDIR_DOCUMENTED_OPTIONS: ReadonlySet<string>;
+/** fs.writeFileSync's documented option keys. */
+export declare const FS_WRITE_FILE_DOCUMENTED_OPTIONS: ReadonlySet<string>;
+/** dns.lookup's documented option keys. */
+export declare const DNS_LOOKUP_DOCUMENTED_OPTIONS: ReadonlySet<string>;
+/** readline.createInterface's documented option keys. */
+export declare const READLINE_DOCUMENTED_OPTIONS: ReadonlySet<string>;
+/** The lowered Array<T> method surface. Like STR_METHODS, membership is
+ * only half the check — the resolved symbol must be declared by the
+ * standard library (isStdlibMember); lib-declared array methods outside
+ * this set hit the SC2020 fence. */
+export declare const ARRAY_METHODS: Set<string>;
+/** The lowered Map<K, V> method surface. Like ARRAY_METHODS, membership is
+ * only half the check — the resolved symbol must be declared by the
+ * standard library (isStdlibMember). `size` is a property, handled in
+ * property-access position. */
+export declare const MAP_METHODS: Set<string>;
+/** The lowered Set<T> method surface — Map's minus get/set plus add.
+ * `size` is a property, handled in property-access position. */
+export declare const SET_METHODS: Set<string>;
+/** The ES2025 Set composition surface (union/intersection/…): desugared
+ * to interned helper loops over the set iteration primitives — no user
+ * code runs mid-loop, so the walks need no enter/exit bracketing. The
+ * lib accepts any ReadonlySetLike argument; only a real Set lowers (the
+ * argument's has/size must be the builtins for the desugar to BE the
+ * spec's algorithm). */
+export declare const SET_COMBINE_METHODS: Set<string>;
+export type CompoundOp = "+" | "-" | "*" | "/" | "%" | "**" | "&" | "|" | "^" | "<<" | ">>" | ">>>";
+export declare const COMPOUND_ASSIGN_OPS: Partial<Record<ts.SyntaxKind, CompoundOp>>;
+/** String methods lowered to `strIntrinsic` (`.length` is handled in
+ * property-access position). Membership here is only half the check: the
+ * resolved symbol must also be declared by the standard library (see
+ * isStdlibMember), so a user-declared `slice` on some other type can never
+ * smuggle itself in by name. `minArgs`/`maxArgs` pin the LOWERED call
+ * forms: the lib declares wider signatures (optional position/fromIndex
+ * parameters) that typecheck but have no lowering — those forms are fenced
+ * per site instead of silently dropping arguments. */
+export declare const STR_METHODS: Record<string, {
+    method: IrStrIntrinsicMethod;
+    result: IrType;
+    minArgs: number;
+    maxArgs: number;
+}>;
+/** One member of the island-backed ambient surface: declared argument
+ * types (tsc enforces them at call sites; the arity double-checks the
+ * table against the ambient file) and the validated island-exit target the
+ * engine's result must satisfy. */
+export interface IslandFnEntry {
+    args: IrType[];
+    ret: IrType;
+}
+export declare const ISL_N1: IslandFnEntry;
+export declare const ISL_N2: IslandFnEntry;
+export declare const boundaryIntoIslandMsg: (typeName: string) => string;
+export declare const boundaryOutOfIslandMsg: (typeName: string) => string;
+/** The island-backed surface — standard-library APIs with no static
+ * runtime implementation (Math.*, number/string methods beyond the
+ * intrinsic set, parseFloat, ...). ONE table drives both sides of the
+ * gate: under --dynamic each entry lowers to marshal → engine execution →
+ * validated exit to the declared return type; without the flag each use
+ * site is a per-site SC2012. Membership here is only half the check — the
+ * resolved symbol must be declared by the standard library (provenance,
+ * never names), so a user's own `parseFloat` or `.toFixed` takes the
+ * ordinary paths. The lib declares MORE than this table (extra members,
+ * optional-parameter forms): everything untabled falls through to the
+ * SC2020 lib fence — never an ICE, never a link error. Exported so the
+ * table-vs-lib consistency test can check every entry against the lib's
+ * own declarations — a drifted entry fails a test instead of surprising a
+ * user. */
+export declare const ISLAND_SURFACE: {
+    /** `Math.<fn>(...)` lowers to callMethod(globalGet("Math"), fn, args);
+     * the readonly number props (`Math.PI`) to getProp(globalGet("Math")).
+     * min/max/atan2/hypot/pow are declared with exactly two parameters
+     * (rest/optional parameters aren't representable). */
+    math: {
+        fns: Record<string, IslandFnEntry | undefined>;
+        props: Record<string, IrType | undefined>;
+    };
+    /** Methods on `number` receivers. The receiver marshals by value; the
+     * engine auto-boxes primitives on method calls, so `this` binds the
+     * number exactly as in JS. toString takes an EXPLICIT radix (radix-free
+     * conversion is the static template-literal path). */
+    number: Record<string, IslandFnEntry | undefined>;
+    /** Methods on `string` receivers beyond the static strIntrinsic set
+     * (split/pad/trimStart/trimEnd moved to STR_METHODS — static now).
+     * replace/replaceAll take STRING patterns (no regex is declared). `at`
+     * returns `string`: out of range, the engine yields undefined and the
+     * validated exit refuses it with a catchable TypeError (the documented
+     * divergence from `string | undefined`). */
+    string: Record<string, IslandFnEntry | undefined>;
+    /** Global functions: parseInt and isNaN are STATIC (lower-calls.ts →
+     * num.parseInt/num.isNaN), and parseFloat/isFinite lower statically
+     * over EXACTLY-typed arguments (a string for parseFloat, a number for
+     * isFinite — num.parseFloat/number.isFinite); these island entries
+     * carry every OTHER argument shape, where the ToNumber/ToString
+     * coercions stay engine territory. */
+    globals: Record<string, IslandFnEntry | undefined>;
+};
+/** Math members with a STATIC lowering — each is one C call that IS the
+ * JS operation, at the tabled arity (floor: libm's floor; min/max: the
+ * NaN-poisoning ±0-ordered scalar folds; random: arc4random-backed
+ * uniform [0,1) — SEMANTICS.md 62). Checked BEFORE the island table
+ * (lowerIslandMethodCall), so the tabled arities compile statically and
+ * other arities keep the island/fence story; unioned with the island
+ * table for the methods-as-values fence (lowerMathProperty). */
+export declare const STATIC_MATH_FNS: Record<string, {
+    fn: IrLibFn;
+    arity: number;
+} | undefined>;
+/** One lowerable builtin-module FUNCTION: `fn`'s libCall with `params`
+ * completed exactly. `variadicPack` marks Node's rest-parameter functions
+ * (path.join/resolve): every argument lowers as a string and the frontend
+ * packs them into ONE string[] array-literal argument, so the C ABI stays
+ * fixed-arity. `defaults` completes omitted TRAILING arguments with string
+ * literals (path.basename's suffix → "", a Node no-op). */
+export interface BuiltinModuleFn {
+    fn: IrLibFn;
+    params: IrType[];
+    result: IrType;
+    variadicPack?: boolean;
+    defaults?: string[];
+}
+export declare const BUILTIN_MODULE_FNS: Record<string, Record<string, BuiltinModuleFn | undefined> | undefined>;
+/** Builtin-module CONSTANTS (value reads of named imports): each lowers to
+ * a literal of its value's kind. The bare-module values are the TARGET
+ * platform's (builtinModuleConstOf swaps the win32 values in under a win32
+ * triple — Node's own platform conditionals); the named namespaces answer
+ * THEIR platform's constants everywhere. worker_threads/cluster carry the
+ * main-thread truths: a compiled binary IS the main thread (no JS-engine
+ * thread machinery) and never runs as a cluster worker (cluster forks the
+ * node binary itself) — Node's own answers for a directly-run script. */
+export declare const BUILTIN_MODULE_CONSTS: Record<string, Record<string, string | number | boolean | undefined> | undefined>;
+/** BUILTIN_MODULE_FNS with the platform-conditional modules bound per
+ * TARGET: a win32 triple compiles Node-on-Windows semantics — `path` is
+ * path.win32 and url's bridge takes the win32 flavors. Fence wording is
+ * unaffected — callers keep naming the module the source spelled. */
+export declare function builtinModuleFnsOf(L: Lowerer, module: string): Record<string, BuiltinModuleFn | undefined> | undefined;
+/** One MEMBER's table entry, own-property-safe (`path.toString` must not
+ * answer Object.prototype.toString as a BuiltinModuleFn). */
+export declare function builtinModuleFnOf(L: Lowerer, module: string, member: string): BuiltinModuleFn | undefined;
+/** One member's fence hint, own-property-safe (a collision would print an
+ * inherited function into the diagnostic text). */
+export declare function builtinFenceHintOf(module: string, member: string): string | undefined;
+/** BUILTIN_MODULE_CONSTS with the win32-target overrides applied — the
+ * constants twin of builtinModuleFnsOf. */
+export declare function builtinModuleConstOf(L: Lowerer, module: string, member: string): string | number | boolean | undefined;
+/** The IR literal of a builtin-module constant — one place so both value
+ * paths (named-import bindings and namespace member reads) emit the same
+ * kinds. */
+export declare function builtinConstLit(value: string | number | boolean, loc: {
+    file: string;
+    start: number;
+    end: number;
+}): IrExpr;
+/** Member-specific hints for RECOGNIZED builtin modules whose member has
+ * no lowering. deflateSync/inflateSync lower now (Buffers are real);
+ * the rest of the zlib surface points at the lowered pair. */
+export declare const ZLIB_HINT = "deflateSync and inflateSync are the lowered zlib surface";
+export declare const BUILTIN_MODULE_FENCE_HINTS: Record<string, Record<string, string | undefined> | undefined>;
+/** The MEMBER chokepoint of the lib fence: called from the property-read
+   * and method-call fallbacks after every lowering has passed. When the
+   * accessed member is stdlib-declared, the use is standard-library surface
+   * with no lowering — report SC2020 naming `<container>.<member>` (the
+   * receiver's global name when it IS a stdlib global like Math or Promise,
+   * its widened type text otherwise). Returns silently for non-stdlib
+   * members so the caller's generic rejection applies. */
+export declare function stdlibMemberFence(L: Lowerer, access: ts.PropertyAccessExpression): void;
+/** True iff the accessed member is declared by the standard library —
+   * the same technique as isConsoleLog: trust declarations, not names. */
+export declare function isStdlibMember(L: Lowerer, access: ts.PropertyAccessExpression): boolean;
+/** The provenance check the CHILD receiver lowerings use: a stdlib
+   * member, OR a member the user's own child-shaped interface declares
+   * (the NgrokChildProcess idiom — mapType's duck rule admits an
+   * interface only when EVERY member names the lowered ChildProcess
+   * surface, so accepting its members here cannot widen the surface;
+   * the receiver-kind gate already proved the type maps to child). */
+export declare function isChildSurfaceMember(L: Lowerer, access: ts.PropertyAccessExpression): boolean;
+/** True iff some declaration of the symbol lives in the standard library
+   * (shipped ambient or default lib — the provenance half of every
+   * supported-surface check). `some`, not `[0]`: divergence overrides merge
+   * with lib interfaces, so a member can carry declarations from both. A
+   * user's own declaration is in neither, so shadowing never matches. */
+export declare function isStdlibSymbol(L: Lowerer, symbol: ts.Symbol | undefined): boolean;
+/** The canonical stdlib-global name `expr` denotes, or null. Three
+   * spellings reach the same global (Node's own aliasing):
+   *   - the bare identifier (`process`), name + provenance checked;
+   *   - the `global` identifier — Node's alias of globalThis — and
+   *     `globalThis` itself both canonicalize to "globalThis";
+   *   - a property read off globalThis (`globalThis.process`,
+   *     `global.process`) — `declare var` globals ARE properties of
+   *     `typeof globalThis`, same symbol either way;
+   *   - a local alias binding (`const process = globalThis.process`, the
+   *     tamper-guard prologue) registered in stdlibGlobalAliases. */
+export declare function stdlibGlobalNameOf(L: Lowerer, expr: ts.Expression): string | null;
+/** True iff `expr` denotes THE standard-library global `name` — name AND
+   * provenance, because neither alone suffices: several globals share
+   * member names (Math.log must never lower as console.log), and a user
+   * binding shadowing a global's name has a different, non-stdlib symbol.
+   * All of stdlibGlobalNameOf's spellings answer (globalThis.process is
+   * process; `const process = globalThis.process` aliases through). */
+export declare function isStdlibGlobal(L: Lowerer, expr: ts.Expression, name: string): boolean;
+/** The member name of a `<global>.<member>` access whose receiver is THE
+   * standard-library global `name` (console, JSON, process, Math). Null for
+   * anything else, so property-lowering chains keep trying other
+   * receivers. */
+export declare function stdlibGlobalMember(L: Lowerer, access: ts.PropertyAccessExpression, name: string): string | null;
+/** `const process = globalThis.process` (and any `const x = <stdlib
+   * global>` snapshot — the suite harness's tamper-guard prologue): the
+   * binding is pure alias plumbing. Nothing in a compiled program can
+   * reassign a stdlib global, so the snapshot IS the global: the symbol
+   * registers in stdlibGlobalAliases (every receiver check resolves
+   * through it — see stdlibGlobalNameOf) and the declaration emits
+   * nothing. Only the globals with lowered member surfaces alias this
+   * way; aliasing, say, `Math` would change nothing (its members lower
+   * by receiver too). Returns true when recognized. */
+export declare function stdlibGlobalAliasDecl(L: Lowerer, nameNode: ts.Node, init: ts.Expression | undefined): boolean;
+/** True iff the symbol is declared ONLY by the adopted @types/node
+   * surface (no es-lib or shipped-ambient declaration merges in) — chooses
+   * the SC2020 fence's wording: "typed by @types/node", not "standard
+   * library". */
+export declare function nodeTypesOnlySymbol(L: Lowerer, sym: ts.Symbol | null | undefined): boolean;