@loopdive/js2 0.57.0

package/dist/codegen/coercion-engine.d.ts

@@ -0,0 +1,154 @@
+import { Instr, ValType } from '../ir/types.js';
+import { ts } from '../ts-api.js';
+import { CodegenContext, FunctionContext } from './context/types.js';
+/**
+ * The three coercion modes the backend dispatches over. Derived once from the
+ * three ad-hoc spellings that exist today so callers stop re-testing them.
+ *
+ *   - `"standalone"`        — `noJsHost(ctx)` (--target wasi / standalone): pure
+ *     Wasm, native `$AnyString` strings, no JS host bridge.
+ *   - `"native-strings-host"` — `ctx.nativeStrings` with a JS host present:
+ *     native `$AnyString` strings but the host `__extern_*` bridge is available.
+ *   - `"js-host"`           — classic externref `wasm:js-string` strings.
+ */
+export type CoercionMode = "js-host" | "native-strings-host" | "standalone";
+export declare function coercionMode(ctx: CodegenContext): CoercionMode;
+/**
+ * The ToString hint, distinguishing the genuinely-different per-context spec
+ * operations the matrices encode for a struct/ref operand:
+ *   - `"string"`  — ToString proper (§7.1.17): a template span (`` `${obj}` ``)
+ *     and `String(obj)` walk @@toPrimitive("string")/toString.
+ *   - `"default"` — the `+` operator's ToPrimitive(default) (valueOf-first,
+ *     §7.1.1.1 / #2022): `obj + ""` must use `valueOf`. Only differs from
+ *     `"string"` on the struct/ref arm.
+ */
+export type ToStringHint = "string" | "default";
+/**
+ * Emit `ToString(operand)` for an operand that has ALREADY been compiled to the
+ * top of the value stack with ValType `valType` and static TS type `tsType`.
+ *
+ * This is the consolidated cascade the expression-based ToString copies shared:
+ *   void            → "undefined"
+ *   i32 boolean     → "true"/"false"          (emitBoolToString)
+ *   f64/i32/i64     → number_toString          (numeric stringify)
+ *   externref null  → "null"
+ *   externref undef → "undefined"
+ *   externref str   → passthrough (already a string)
+ *   externref other → __extern_toString / __extern_to_string_default (by hint)
+ *   ref/ref_null    → tryStructToString → $__any_to_string  (native)
+ *                     coerceType(hint) / __extern_to_string_default (host)
+ *
+ * Returns the ValType left on the stack (externref in js-host mode, a native
+ * `ref $AnyString` in native/standalone mode), or `null` for the void arm where
+ * a string literal was pushed (callers treat both as "a string is on the stack").
+ *
+ * Each caller passes its own `hint` so the per-context policy (template "string"
+ * vs `+` "default") is preserved byte-for-byte.
+ *
+ * NOTE on Symbol: §7.1.17 ToString(Symbol) throws TypeError. The callers guard
+ * that BEFORE compiling the operand (`tryThrowOnSymbolStringCoercion`), because
+ * the throw must short-circuit operand evaluation; the engine assumes a
+ * non-symbol operand on the stack.
+ */
+export declare function emitToString(ctx: CodegenContext, fctx: FunctionContext, valType: ValType | null, tsType: ts.Type, hint: ToStringHint): ValType;
+/**
+ * Compile `operand` then emit `ToString(operand)`. The expression-based
+ * convenience wrapper for the `+`-concat / String() callers. Symbol guarding is
+ * the caller's responsibility (must short-circuit before operand evaluation).
+ */
+export declare function compileAndEmitToString(ctx: CodegenContext, fctx: FunctionContext, operand: ts.Expression, tsType: ts.Type, hint: ToStringHint): ValType;
+/**
+ * Emit `ToNumber(operand)` (→ f64) for an operand ALREADY compiled to the top of
+ * the value stack with ValType `valType`. The consolidation of the `Number(x)`
+ * matrix (N2) and the unary `+`/`-`/`~` coercion arms (N1):
+ *
+ *   i64 (BigInt)         → f64.convert_i64_s
+ *   externref            → __unbox_number (js-host) | coerceType(f64,"number") (standalone)
+ *   ref/ref_null         → coerceType(f64,"number")  (object @@toPrimitive("number")/valueOf)
+ *   i32 (number/bool)    → f64.convert_i32_s
+ *   f64                  → no-op
+ *
+ * Returns the ValType left on the stack (`{kind:"f64"}` for every coercing arm;
+ * the original `valType` for the already-f64 no-op).
+ *
+ * NOTE — what stays in the caller (NOT folded here, because each is a *source*
+ * special-case that must run BEFORE the operand is on the stack as a plain
+ * value, or is policy that differs per caller):
+ *   - ToNumber(Symbol) throws TypeError (§7.1.4) — guarded before operand eval.
+ *   - the #2160 `Number(arr)` array→ToString→StringToNumber pre-check.
+ *   - the native-string-ref (`$AnyString`/`$NativeString`) → `__str_to_number`
+ *     (§7.1.4.1) arm — it dispatches on the ref's *typeIdx* (string-struct vs a
+ *     generic object struct), which the caller already resolves; a generic ref
+ *     falls to `coerceType(f64,"number")` here.
+ * The caller handles those, then calls `emitToNumber` for the remaining cascade.
+ */
+export declare function emitToNumber(ctx: CodegenContext, fctx: FunctionContext, valType: ValType | null): ValType;
+/**
+ * Append `ToBoolean(value)` (§7.1.2 → i32, 1 = truthy) for a value of ValType
+ * `valType` already on the stack into `sink`. The consolidation of the two
+ * hand-rolled truthiness sites that #2085 already aligned:
+ *   - `ensureI32Condition` (index.ts, B1 — the canonical, pushes to `fctx.body`)
+ *   - `buildToBooleanInstrs` (array-methods.ts, B2 — returns an `Instr[]`)
+ *
+ * The `sink` parameter unifies those two emission styles: B1 passes `fctx.body`,
+ * B2 passes a fresh array it then returns. Both produce the SAME sequence — this
+ * is behaviour-neutral (the #2085 fix already made B2 use `|x|>0` like B1, so
+ * there is no longer a NaN-truthy divergence to surface).
+ *
+ *   null valType → i32.const 0  (compile failed upstream → keep Wasm valid: falsy)
+ *   f64          → |x| > 0       (NaN, +0, -0 all falsy)
+ *   externref    → __is_truthy   (0/NaN/null/undefined/"" → falsy); ref.is_null fallback
+ *   any-boxed ref→ __any_unbox_bool (proper JS truthiness on the boxed value)
+ *   native str ref→ flatten → len > 0 (empty string falsy)
+ *   other ref    → non-null (ref.is_null; i32.eqz)
+ *   i64          → nonzero
+ *   i32          → as-is (already 0/1-valued)
+ */
+export declare function emitToBoolean(ctx: CodegenContext, valType: ValType | null, sink: Instr[]): Instr[];
+/**
+ * #1917 Step E3 — `emitStrictEq` / `emitLooseEq`: the **dispatch layer** for
+ * `any`-operand equality. These decide WHICH helper to call (`__any_strict_eq`
+ * for `===`/`!==`; `__any_eq` for `==`/`!=`), marshal both operands into the
+ * boxed `$AnyValue` shape, emit the `call`, and apply the `!=`/`!==` negation.
+ *
+ * They are a WRAPPER, not a re-derivation: the tag-5 field-4 3-way classifier
+ * (boxed-number vs proto-identity vs content equality, #2040/#2585 — the
+ * `tag5StringEqThen` machinery) lives in the `__any_eq`/`__any_strict_eq` helper
+ * *bodies* in any-helpers.ts. The engine never copies that logic; it only
+ * selects the helper and boxes the operands. This is a byte-neutral extraction
+ * of the equality arms of `compileAnyBinaryDispatch`.
+ *
+ * @param negate when true, the loose/strict-equal result is i32.eqz'd (the
+ *   `!=` / `!==` half). The helper itself always computes `==`/`===`.
+ * @returns the i32 result ValType, or `null` if the helper is unavailable or an
+ *   operand failed to compile (caller falls back).
+ */
+export declare function emitStrictEq(ctx: CodegenContext, fctx: FunctionContext, expr: ts.BinaryExpression, negate: boolean): ValType | null;
+export declare function emitLooseEq(ctx: CodegenContext, fctx: FunctionContext, expr: ts.BinaryExpression, negate: boolean): ValType | null;
+/**
+ * #1917 equality finale, slice E6 — the standalone externref-vs-externref
+ * loose-equality tail.
+ *
+ * For two opaque `any` externref operands that were NOT eqref-identical, the
+ * standalone/WASI lane (no JS host) routes through the NATIVE §7.2.15
+ * IsLooselyEqual instead of the unsatisfiable `__host_loose_eq` import (#2081):
+ * box both externrefs to `$AnyValue` via `__any_from_extern` (tag5 string / tag3
+ * number / tag4 bool / tag1 null) and call the keystone `__any_eq` helper (whose
+ * tag-5 field-4 classifier owns the String⇄Number / proto-identity arms). This
+ * is the SAME tag-5-sensitive boxing E3 does for the any/any case, just sourced
+ * from two pre-computed externref temps instead of freshly-compiled operands.
+ *
+ * Returns the instruction SEQUENCE (this caller builds an `Instr[]` for an
+ * `if`-arm, it does not emit live), or `null` when the helpers are unavailable so
+ * the caller can fall through to its host-import path exactly as before. WRAPPER,
+ * not a re-derivation: the classifier stays in `__any_eq`'s body (any-helpers.ts).
+ *
+ * @param tmpLeft  local index holding the left externref operand.
+ * @param tmpRight local index holding the right externref operand.
+ * @param negate   append `i32.eqz` for the `!=` form.
+ */
+export declare function emitAnyEqFromExternTemps(ctx: CodegenContext, tmpLeft: number, tmpRight: number, negate: boolean): Instr[] | null;
+export declare function registerStringHelperEmitters(emitters: {
+    boolToString: (ctx: CodegenContext, fctx: FunctionContext) => void;
+    nativeStringRefFromExternref: (ctx: CodegenContext, fctx: FunctionContext) => void;
+}): void;

package/dist/codegen/coercion-plan.d.ts

@@ -0,0 +1,29 @@
+import { Instr, ValType } from '../ir/types.js';
+/** Box/unbox helper funcIdxs the numeric box-unbox rows need (null = unavailable). */
+export interface CoercionHelpers {
+    boxNumberIdx: number | null;
+    unboxNumberIdx: number | null;
+}
+export interface CoercionPlan {
+    instrs: Instr[];
+    /**
+     * True when the sequence cannot preserve the value (drops it and pushes a
+     * placeholder). A lossy plan in a branch/local fixup masks an upstream
+     * emitter bug; #1918 will surface these as diagnostics. Today only the
+     * genuine "no representation bridge exists" rows are lossy.
+     */
+    lossy?: boolean;
+}
+/**
+ * The canonical scalar / numeric / box-unbox coercion table.
+ *
+ * Returns the instruction sequence to convert a value of ValType `from` (top of
+ * stack) to ValType `to`, or `null` when this pair is **not** a row this table
+ * owns — i.e. it needs an `fctx` temporary (guarded ref.cast: externref/eqref/
+ * anyref → ref/ref_null) or `ctx` (AnyValue→externref helper). Callers fall
+ * back to their own handling for `null`.
+ *
+ * Same-kind pairs return `{ instrs: [] }` (no-op) so callers can treat a
+ * non-null result as "handled".
+ */
+export declare function coercionPlan(from: ValType, to: ValType, helpers: CoercionHelpers): CoercionPlan | null;

package/dist/codegen/context/bodies.d.ts

@@ -0,0 +1,4 @@
+import { Instr } from '../../ir/types.js';
+import { FunctionContext } from './types.js';
+export declare function pushBody(fctx: FunctionContext): Instr[];
+export declare function popBody(fctx: FunctionContext, saved: Instr[]): void;

package/dist/codegen/context/create-context.d.ts

@@ -0,0 +1,4 @@
+import { ts } from '../../ts-api.js';
+import { WasmModule } from '../../ir/types.js';
+import { CodegenContext, CodegenOptions } from './types.js';
+export declare function createCodegenContext(mod: WasmModule, checker: ts.TypeChecker, options?: CodegenOptions): CodegenContext;

package/dist/codegen/context/errors.d.ts

@@ -0,0 +1,39 @@
+import { ts } from '../../ts-api.js';
+import { CodegenContext, CodegenError } from './types.js';
+/**
+ * #1921 — diagnostic severity for the helpers below. Omitting it defaults to
+ * `"error"`, which fails the build. Pass `"degrade"` only for a *deliberate*
+ * compile-with-fallback-value site (and reference the tracking issue in the
+ * message), or `"warning"` for a purely informational diagnostic.
+ */
+type ReportSeverity = NonNullable<CodegenError["severity"]>;
+/**
+ * #1921 — does this codegen diagnostic fail the build?
+ *
+ * The compile-failure gate keys on {@link CodegenError.severity}, not on a
+ * `"Codegen error:"` message prefix. An omitted severity is treated as
+ * `"error"` so a forgotten classification fails loudly instead of silently
+ * degrading the binary with a stack-balancer placeholder (#1918). `"warning"`
+ * (IR-fallback channel) and `"degrade"` (deliberate compile-with-fallback-value)
+ * are non-fatal.
+ */
+export declare function isFatalCodegenDiagnostic(err: {
+    severity?: CodegenError["severity"];
+}): boolean;
+/**
+ * Report a compile error with source location extracted from the given AST node.
+ * Falls back to ctx.lastKnownNode when the node lacks source file context.
+ *
+ * #1921 — the diagnostic carries an explicit `severity: "error"` by default so
+ * the compile-failure gate keys on severity rather than a `"Codegen error:"`
+ * message prefix. Pass `"degrade"` for a deliberate compile-with-fallback site.
+ */
+export declare function reportError(ctx: CodegenContext, node: ts.Node, message: string, severity?: ReportSeverity): void;
+/**
+ * Report a compile error when no AST node is available.
+ * Uses ctx.lastKnownNode for location if possible.
+ *
+ * #1921 — defaults to `severity: "error"` (see {@link reportError}).
+ */
+export declare function reportErrorNoNode(ctx: CodegenContext, message: string, severity?: ReportSeverity): void;
+export {};

package/dist/codegen/context/locals.d.ts

@@ -0,0 +1,69 @@
+import { ValType } from '../../ir/types.js';
+import { FunctionContext } from './types.js';
+export declare function allocLocal(fctx: FunctionContext, name: string, type: ValType): number;
+/**
+ * #1847 — snapshot of the local-allocation state, for tentative compilation
+ * that may be rolled back. Captures the locals-vector length so callers can
+ * truncate, plus the `localMap` names present at snapshot time so we can drop
+ * any name `allocLocal` added afterwards (whose slot the truncation removes).
+ *
+ * Tentative-compile sites previously truncated `fctx.locals.length` (and
+ * `fctx.body.length`) but left `fctx.localMap` pointing at slots past the
+ * truncated vector — an unbalanced state. Snapshot/restore keeps the three in
+ * sync.
+ */
+export interface LocalsSnapshot {
+    readonly localsLen: number;
+    /**
+     * Full `localMap` entries (name → slot index) at snapshot time. Restoring the
+     * complete map — not just the key SET — is required because a speculative
+     * compile may **re-point an EXISTING name** to a freshly-allocated slot, not
+     * only add new names: closure-capture boxing
+     * (`fctx.localMap.set(cap.name, boxedLocalIdx)` in closures.ts) re-aims an
+     * outer variable at its boxed ref-cell. A key-set-only snapshot can delete the
+     * newly-added box slot but leaves the outer name pointing at the (now
+     * truncated) box index, so a post-rollback read of that variable emits a
+     * `local.get` past the function's local count — `local index out of range`
+     * at emit time. #2029 (tagged-template tag = a closure capturing an outer
+     * local; the tagged-template probe boxed `calls`→slot N, rolled back, and
+     * `return calls` then read the stale slot N).
+     */
+    readonly mapEntries: ReadonlyArray<readonly [string, number]>;
+    /** `boxedCaptures` names present at snapshot time (to drop added ones). */
+    readonly boxedNames: ReadonlySet<string>;
+}
+export declare function snapshotLocals(fctx: FunctionContext): LocalsSnapshot;
+/**
+ * #1847 — undo allocations made since `snap`: truncate the locals vector and
+ * restore `localMap` to its EXACT snapshot state (drop added names AND reset
+ * re-pointed existing names to their snapshot slot — see {@link LocalsSnapshot}
+ * `mapEntries` for why the value, not just the key, must be restored). Does NOT
+ * touch `fctx.body` — callers truncate that themselves (the body length to
+ * roll back to is site-specific and often captured separately).
+ *
+ * `tempFreeList` is left as-is on purpose: it only ever holds indices that were
+ * valid at allocation time, and the temp-local reuse path keys buckets by type;
+ * a rolled-back tentative compile that released a temp would have pushed a slot
+ * index that is now beyond `locals.length`. To keep the free-list from handing
+ * out a truncated slot, we prune any bucket entry that points past the new
+ * locals length.
+ */
+export declare function restoreLocals(fctx: FunctionContext, snap: LocalsSnapshot): void;
+export declare function allocTempLocal(fctx: FunctionContext, type: ValType): number;
+export declare function releaseTempLocal(fctx: FunctionContext, index: number): void;
+export declare function getLocalType(fctx: FunctionContext, index: number): ValType | undefined;
+/**
+ * Post-processing pass: eliminate duplicate local declarations.
+ *
+ * When the same variable name appears more than once in fctx.locals (due to
+ * sibling block scopes, try/catch blocks, or for-loops with the same counter
+ * name), this merges the duplicates by:
+ * 1. Keeping the first occurrence of each name (lowest index)
+ * 2. Rewriting all local.get/set/tee instructions that reference duplicate
+ *    slots to use the canonical (first) slot instead
+ * 3. Compacting fctx.locals to remove the now-unreferenced duplicate entries
+ *
+ * This handles ALL remaining duplicate local patterns uniformly, regardless
+ * of how they were generated (sibling for-loops, try/catch, for-of, etc.).
+ */
+export declare function deduplicateLocals(fctx: FunctionContext): void;

package/dist/codegen/context/source-pos.d.ts

@@ -0,0 +1,5 @@
+import { ts } from '../../ts-api.js';
+import { Instr } from '../../ir/types.js';
+import { CodegenContext, SourcePos } from './types.js';
+export declare function getSourcePos(ctx: CodegenContext, node: ts.Node): SourcePos | undefined;
+export declare function attachSourcePos(instr: Instr, sourcePos: SourcePos | undefined): Instr;

package/dist/codegen/context/speculative.d.ts

@@ -0,0 +1,95 @@
+import { CodegenContext, FunctionContext } from './types.js';
+import { LocalsSnapshot } from './locals.js';
+/**
+ * A transactional snapshot of the codegen state a speculative compile can
+ * mutate. Capture with {@link snapshotSpeculative}; undo with
+ * {@link rollbackSpeculative}. Discard (no-op) to commit.
+ *
+ * The snapshot is near-O(1): every field is an integer read or a reference copy
+ * (`snapshotLocals` copies the localMap ENTRIES — name→slot — so a re-pointed
+ * existing name can be restored, not just dropped; locals are typically tiny;
+ * crucially the funcMap is NOT copied — rollback derives the names to delete
+ * from the popped import descriptors, which each carry their `name`). This keeps
+ * the helper cheap enough to wrap even the hot `compileExpression` path.
+ */
+export interface SpeculativeSnapshot {
+    /** `fctx.body.length` at snapshot time — the rollback truncation target. */
+    readonly bodyLen: number;
+    /** Locals / localMap / temp-free-list snapshot (#1847). */
+    readonly locals: LocalsSnapshot;
+    /** `ctx.errors.length` — diagnostics pushed during the probe are discarded. */
+    readonly errorsLen: number;
+    /** `ctx.mod.imports.length` — imports appended during the probe are popped. */
+    readonly importsLen: number;
+    /** `ctx.numImportFuncs` — restored so the func index space is rewound. */
+    readonly numImportFuncs: number;
+    /** `ctx.numImportGlobals` — restored if the probe added an import global. */
+    readonly numImportGlobals: number;
+    /**
+     * `ctx.pendingLateImportShift` reference at snapshot time. A probe that armed
+     * the deferred shift (called `ensureLateImport` while `pendingLateImportShift`
+     * was null) is rewound by restoring this exact reference (usually `null`).
+     */
+    readonly pendingLateImportShift: CodegenContext["pendingLateImportShift"];
+    /** `mod.types.length` — see {@link rollbackSpeculative} for why this is advisory. */
+    readonly typesLen: number;
+}
+/**
+ * Capture a transactional snapshot of all state a speculative compile may
+ * mutate. O(localMap.size) for the locals key-set copy; everything else is a
+ * handful of integer / reference reads (no funcMap copy — see
+ * {@link rollbackSpeculative}).
+ */
+export declare function snapshotSpeculative(ctx: CodegenContext, fctx: FunctionContext): SpeculativeSnapshot;
+/**
+ * Undo every mutation made since {@link snapshotSpeculative} produced `snap`.
+ *
+ * - Truncate `fctx.body` to the snapshot length (the classic rollback).
+ * - Restore locals / localMap / temp-free-list (#1847 `restoreLocals`).
+ * - Drop diagnostics pushed during the probe (`ctx.errors`).
+ * - Pop late imports registered during the probe off `ctx.mod.imports`, rewind
+ *   `numImportFuncs` / `numImportGlobals`, delete their `funcMap` entries, and
+ *   restore the deferred-shift latch. This is the leak the #1919 helper exists
+ *   to close: because the probe never flushed the shift (the documented
+ *   invariant), the appended imports never shifted any already-emitted index, so
+ *   popping them and resetting the counters returns the import space exactly to
+ *   the pre-probe state with no body re-walk required.
+ *
+ * Registered Wasm TYPES (`ctx.mod.types` / `funcTypeCache` / struct maps) are
+ * deliberately NOT truncated. Type registration is content-addressed and
+ * idempotent (`addFuncType` dedups by signature; `getOrRegisterVecType` &c. cache
+ * by element kind), and type indices — unlike function indices — are never
+ * shifted by later import additions. A type registered during a rolled-back
+ * probe is therefore inert: it is either reused verbatim by the committed
+ * re-compile or pruned by dead-type elimination if truly unreferenced. Truncating
+ * it would risk desyncing a struct type registered earlier and still referenced
+ * (see `project_type_index_shift_and_deadelim`). `typesLen` is kept on the
+ * snapshot only for diagnostics / a future tightening, not acted on here.
+ */
+export declare function rollbackSpeculative(ctx: CodegenContext, fctx: FunctionContext, snap: SpeculativeSnapshot): void;
+/**
+ * Run `fn` as a speculative compile. `fn` returns a result and decides whether
+ * to keep ({@link SpeculativeOutcome.commit} `true`) or discard the emitted
+ * state. On `commit: false` (or if `fn` throws) the entire transaction is rolled
+ * back via {@link rollbackSpeculative} and `value` is still returned to the
+ * caller (so a probe can inspect the produced type after rollback).
+ *
+ * Use this for "try to lower; keep the body iff the shape matched" sites. For
+ * the pure "what ValType does this compile to, then always discard" probe use
+ * {@link probeCompiledType}, which is a thin wrapper that always rolls back.
+ */
+export interface SpeculativeOutcome<T> {
+    commit: boolean;
+    value: T;
+}
+export declare function withSpeculativeCompile<T>(ctx: CodegenContext, fctx: FunctionContext, fn: () => SpeculativeOutcome<T>): T;
+/**
+ * The dominant probe shape: compile `fn` purely to learn the ValType it
+ * produces, then ALWAYS roll back every side effect (body, locals, imports,
+ * errors). Returns whatever `fn` returns (typically the probed `ValType | null`).
+ *
+ * This replaces the raw `const savedLen = fctx.body.length; … ;
+ * fctx.body.length = savedLen;` idiom — which restored only the body — with a
+ * full transactional rollback.
+ */
+export declare function probeCompiledType<T>(ctx: CodegenContext, fctx: FunctionContext, fn: () => T): T;