@loopdive/js2 0.57.0

package/dist/ir/passes/alloc-discipline.d.ts

@@ -0,0 +1,19 @@
+import { AllocSiteRegistry } from '../alloc-registry.js';
+import { AllocSiteId, IrInstr } from '../nodes.js';
+/**
+ * Inline/monomorphize path — a statically-duplicated allocation is a distinct
+ * runtime allocation, so its clone gets a FRESH id (kind/type copied from the
+ * source site). Returns `instr` unchanged when there is no registry or the
+ * instr carries no `alloc`. Only the top-level `alloc` is forked here; nested
+ * bodies are handled by recursing through the caller (inline never splices
+ * body-bearing instrs — see canInline). For safety this also forks nested
+ * allocs when present.
+ */
+export declare function forkAllocInInstr(instr: IrInstr, registry: AllocSiteRegistry | undefined): IrInstr;
+/** Walk an instr + nested bodies, yielding every `alloc` id present. */
+export declare function allocIdsIn(instr: IrInstr): Iterable<AllocSiteId>;
+/**
+ * Rule 3 — retire every allocation id carried by `instr` (and nested bodies).
+ * No-op when no registry is supplied (test builders never minted ids).
+ */
+export declare function retireAllocsIn(instr: IrInstr, registry: AllocSiteRegistry | undefined): void;

package/dist/ir/passes/constant-fold.d.ts

@@ -0,0 +1,7 @@
+import { IrFunction } from '../nodes.js';
+import { AllocSiteRegistry } from '../alloc-registry.js';
+/**
+ * Fold constant `prim`/`br_if` instructions. Returns the same reference
+ * when no changes are made.
+ */
+export declare function constantFold(fn: IrFunction, registry?: AllocSiteRegistry): IrFunction;

package/dist/ir/passes/dead-code.d.ts

@@ -0,0 +1,18 @@
+import { IrFunction, IrInstr } from '../nodes.js';
+import { AllocSiteRegistry } from '../alloc-registry.js';
+/**
+ * Run dead-code elimination on an IR function. Returns the same reference
+ * when no changes are made (so integration.ts can detect fixpoint via
+ * reference equality).
+ */
+export declare function deadCode(fn: IrFunction, registry?: AllocSiteRegistry): IrFunction;
+/**
+ * Side-effecting instructions are always kept regardless of use count.
+ *
+ * - `raw.wasm` — opaque Wasm ops with unknown effects (spec #1167a mandates
+ *    this stays live).
+ * - `call` — conservatively treated as having side effects. Purity analysis
+ *    is a later pass.
+ * - `global.set` — writes observable state.
+ */
+export declare function isSideEffecting(i: IrInstr): boolean;

package/dist/ir/passes/inline-small.d.ts

@@ -0,0 +1,7 @@
+import { IrModule } from '../nodes.js';
+import { AllocSiteRegistry } from '../alloc-registry.js';
+/**
+ * Inline small, non-recursive, single-block callees across the module.
+ * Returns the same `IrModule` reference when no function changes.
+ */
+export declare function inlineSmall(mod: IrModule, registry?: AllocSiteRegistry): IrModule;

package/dist/ir/passes/monomorphize.d.ts

@@ -0,0 +1,21 @@
+import { IrModule, IrType } from '../nodes.js';
+import { AllocSiteRegistry } from '../alloc-registry.js';
+/**
+ * Signature of an IR-only clone. The caller integrates this into its
+ * `calleeTypes` override map so downstream passes see the narrowed types.
+ */
+export interface MonomorphizeCloneSignature {
+    readonly params: readonly IrType[];
+    readonly returnType: IrType;
+}
+export interface MonomorphizeResult {
+    readonly module: IrModule;
+    /** Map from clone name → signature. Empty when the pass made no changes. */
+    readonly cloneSignatures: ReadonlyMap<string, MonomorphizeCloneSignature>;
+}
+/**
+ * Monomorphize polymorphic callees across an IR module. Returns the input
+ * module unchanged (and an empty signature map) when no profitable clones
+ * exist or the growth budget would be exceeded.
+ */
+export declare function monomorphize(mod: IrModule, registry?: AllocSiteRegistry): MonomorphizeResult;

package/dist/ir/passes/simplify-cfg.d.ts

@@ -0,0 +1,19 @@
+import { IrFunction } from '../nodes.js';
+/**
+ * Merge trivially-linked blocks. Returns the same reference when no
+ * changes are made.
+ *
+ * Pre-conditions (enforced upstream by the CF + DCE pipeline):
+ *   - `func.blocks[i].id === i` (enforced by verify.ts:41-45).
+ *   - Unreachable blocks have already been removed by DCE.
+ *
+ * Merge rule: a block A whose terminator is `br(B)` may absorb B if:
+ *   (a) B has exactly one predecessor (A itself);
+ *   (b) A != B (no self-loop);
+ *   (c) B is not the entry block (blocks[0] must stay at index 0);
+ *   (d) B has no block args (merging would require arg substitution,
+ *       which Phase 3a leaves to a future pass — from-ast.ts and CF
+ *       never introduce block args, so this is a safety guard rather
+ *       than a real restriction).
+ */
+export declare function simplifyCFG(fn: IrFunction): IrFunction;

package/dist/ir/passes/tagged-union-types.d.ts

@@ -0,0 +1,45 @@
+import { IrUnionLowering } from '../lower.js';
+import { StructTypeDef, ValType } from '../types.js';
+/** Canonical tag constants — see module header. */
+export declare const UNION_TAG_F64 = 0;
+export declare const UNION_TAG_I32 = 1;
+export declare const UNION_TAG_NULL = 2;
+export declare const UNION_TAG_STRING = 3;
+/**
+ * Field layout within every $union_* struct. Keep this fixed across all
+ * unions so tag reads and value reads don't have to dispatch on member set.
+ */
+export declare const UNION_TAG_FIELD_IDX = 0;
+export declare const UNION_VAL_FIELD_IDX = 1;
+/**
+ * Minimal module-type sink — any container that can accept a WasmGC struct
+ * type and report its index. Concretely the codegen module's
+ * `ctx.mod.types`, but keeping the interface narrow makes the registry
+ * independently unit-testable.
+ */
+export interface UnionTypeSink {
+    /** Append `def` and return its module-wide type index. */
+    push(def: StructTypeDef): number;
+}
+/**
+ * Per-module registry of tagged-union struct types. Call `resolve(members)`
+ * to get the `$union_<members>` lowering (registered lazily). Repeated
+ * calls with equivalent member sets return the same lowering.
+ */
+export declare class UnionStructRegistry {
+    private readonly sink;
+    private readonly cache;
+    constructor(sink: UnionTypeSink);
+    /**
+     * Resolve the lowering for a union member set. Returns `null` when the
+     * union is not representable under V1 rules (heterogeneous widths, or
+     * contains reference-type members).
+     */
+    resolve(members: readonly ValType[]): IrUnionLowering | null;
+}
+/**
+ * Canonical tag constant for a ValType that may appear in a union. Kept as
+ * a free function so unit tests can exercise it without instantiating the
+ * full registry.
+ */
+export declare function tagFor(member: ValType): number;

package/dist/ir/passes/tagged-unions.d.ts

@@ -0,0 +1,22 @@
+import { IrModule } from '../nodes.js';
+export interface TaggedUnionsError {
+    readonly func: string;
+    readonly block: number;
+    readonly message: string;
+}
+export interface TaggedUnionsResult {
+    readonly module: IrModule;
+    readonly errors: readonly TaggedUnionsError[];
+}
+/**
+ * Run the tagged-unions pass. V1: validates that every `box`/`unbox`/
+ * `tag.test` operand references a registry-supported union; returns the
+ * module unchanged. Errors are reported but non-fatal — the caller decides
+ * whether to fall back.
+ */
+export declare function taggedUnions(mod: IrModule): IrModule;
+/**
+ * Variant exposed for tests / callers that want the full error list.
+ * Most pipeline callers should use `taggedUnions` which discards errors.
+ */
+export declare function runTaggedUnions(mod: IrModule): TaggedUnionsResult;

package/dist/ir/propagate.d.ts

@@ -0,0 +1,135 @@
+import { ts } from '../ts-api.js';
+/**
+ * Atoms are the non-composite lattice elements. `LatticeAtom` excludes
+ * `unknown`, `union`, and `dynamic`; those can never be members of a union.
+ *
+ * #1231 — the `object` atom now carries a recursive structural shape
+ * (a name-sorted list of `(name, atom)` field bindings) instead of an
+ * opaque `shape: string` discriminator. This lets propagation flow
+ * concrete field types end-to-end (e.g. `{x: f64, y: f64}`) so the IR
+ * can emit typed structs and skip box/unbox round-trips on property
+ * access. The lattice height is bounded via a depth cap of
+ * `LATTICE_OBJECT_SHAPE_MAX_DEPTH` (set to 3, matching the legacy
+ * `resolveWasmType` depth guard); shapes deeper than the cap widen to
+ * `dynamic` so the fixpoint always terminates.
+ */
+export type LatticeAtom = {
+    readonly kind: "f64";
+} | {
+    readonly kind: "i32";
+} | {
+    readonly kind: "u32";
+} | {
+    readonly kind: "bool";
+} | {
+    readonly kind: "string";
+} | {
+    readonly kind: "object";
+    readonly fields: readonly {
+        readonly name: string;
+        readonly type: LatticeAtom;
+    }[];
+};
+export type LatticeType = {
+    readonly kind: "unknown";
+} | LatticeAtom | {
+    readonly kind: "union";
+    readonly members: readonly LatticeAtom[];
+} | {
+    readonly kind: "dynamic";
+};
+/** Maximum union-member count before we widen to `dynamic`. */
+export declare const LATTICE_UNION_MAX_MEMBERS = 4;
+/**
+ * Maximum recursive depth of `LatticeAtom.object` shapes. Object shapes
+ * deeper than the cap widen to `dynamic` so the propagation lattice has
+ * bounded height and the worklist fixpoint terminates. Matches the
+ * legacy `resolveWasmType` depth guard at `codegen/index.ts:5255`.
+ */
+export declare const LATTICE_OBJECT_SHAPE_MAX_DEPTH = 3;
+/**
+ * #1126 Stage 2 — integer-domain inference flag. Default **OFF** until
+ * Stage 3 lands the emitter side. While off, all producer rules below
+ * fall back to their pre-#1126 behaviour (`F64` for numeric literals,
+ * `DYNAMIC` for bitwise/shift ops, etc.) so this PR cannot change the
+ * shape of any compiled function.
+ *
+ * To opt in locally: `JS2WASM_IR_I32_DOMAIN=1 npm test`.
+ *
+ * This mirrors the staged-rollout pattern from #1231 (object shapes)
+ * and #1238 (pseudo-extern Array). When Stage 3 ships, the default
+ * flips to ON and the env var becomes an opt-out (`=0`) emergency hatch.
+ */
+declare function i32DomainEnabled(): boolean;
+export interface TypeMapEntry {
+    readonly params: readonly LatticeType[];
+    readonly returnType: LatticeType;
+}
+export type TypeMap = ReadonlyMap<string, TypeMapEntry>;
+/**
+ * Build a TypeMap over every named top-level function declaration in the
+ * source file. Unresolvable types stay at `unknown`. Functions that the
+ * selector wouldn't claim anyway (missing body, duplicate names, etc.) are
+ * omitted.
+ *
+ * The TypeMap is only consulted by the selector and the AST→IR lowerer;
+ * nothing else depends on it, so the cost is paid once per compilation.
+ */
+export declare function buildTypeMap(sourceFile: ts.SourceFile, checker: ts.TypeChecker): TypeMap;
+declare function typeNodeToLattice(node: ts.TypeNode): LatticeType | null;
+declare function tsTypeToLattice(ty: ts.Type, _checker: ts.TypeChecker): LatticeType;
+/**
+ * Structural type of an expression, using the given param/local scope and
+ * the current TypeMap iteration state for cross-function return types.
+ *
+ * Conservative for unsupported nodes → `dynamic`.
+ */
+declare function inferExpr(expr: ts.Expression, scope: ReadonlyMap<string, LatticeType>, entries: ReadonlyMap<string, {
+    params: LatticeType[];
+    returnType: LatticeType;
+}>): LatticeType;
+declare function join(a: LatticeType, b: LatticeType): LatticeType;
+/** Build a canonical union from a list of atoms (dedupe + sort). */
+declare function makeUnion(members: readonly LatticeAtom[]): LatticeType;
+/**
+ * Lower a `LatticeType` to the middle-end `IrType` used by `from-ast.ts`
+ * / `lower.ts`. Returns `null` when the lattice value is not representable
+ * as a concrete IR type (unknown, dynamic, or a union with members the
+ * tagged-union registry doesn't support).
+ *
+ * V1 union mapping:
+ *   - `{f64, bool}`        → `IrType.union<f64, i32>`        (i32 holds bool)
+ *   - `{f64, string}`      → null (heterogeneous-width, deferred)
+ *   - `{object(A), object(B)}` → null (reference unions, deferred)
+ */
+export declare function lowerTypeToIrType(t: LatticeType): import('./nodes.js').IrType | null;
+export declare const _internals: {
+    join: typeof join;
+    inferExpr: typeof inferExpr;
+    tsTypeToLattice: typeof tsTypeToLattice;
+    typeNodeToLattice: typeof typeNodeToLattice;
+    makeUnion: typeof makeUnion;
+    F64: {
+        readonly kind: "f64";
+    };
+    I32: {
+        readonly kind: "i32";
+    };
+    U32: {
+        readonly kind: "u32";
+    };
+    BOOL: {
+        readonly kind: "bool";
+    };
+    STRING: {
+        readonly kind: "string";
+    };
+    UNKNOWN: {
+        readonly kind: "unknown";
+    };
+    DYNAMIC: {
+        readonly kind: "dynamic";
+    };
+    i32DomainEnabled: typeof i32DomainEnabled;
+};
+export {};

package/dist/ir/select.d.ts

@@ -0,0 +1,81 @@
+import { ts } from '../ts-api.js';
+import { TypeMap } from './propagate.js';
+/**
+ * #1169q telemetry — record why a top-level FunctionDeclaration didn't make
+ * it into the IR claim set. The intent is to drive the legacy retirement:
+ * once the count of unintended fallbacks (excluding deferred features) is
+ * zero against the test262 corpus, the legacy expression / statement
+ * emitters can be retired.
+ */
+export type IrFallbackReason = "unnamed" | "type-parameters" | "non-export-modifier" | "async-generator" | "async-function" | "return-type-not-resolvable" | "param-type-not-resolvable" | "param-shape-rejected" | "destructuring-param-complex" | "body-shape-rejected" | "external-call" | "call-graph-closure" | "type-resolution-failure" | "class-method" | "deferred-feature";
+export interface IrFallback {
+    readonly name: string;
+    readonly reason: IrFallbackReason;
+}
+/**
+ * (#1371) Whitelist of `Math.<name>(arg)` unary calls the IR can lower to a
+ * plain Wasm `f64.<op>` instruction without any host import. Each entry maps
+ * 1:1 to an op in the `IrUnop` extended set (`src/ir/nodes.ts`). Restricting
+ * the whitelist to ops with direct Wasm equivalents preserves bit-exact JS
+ * semantics:
+ *  - `Math.round` is intentionally excluded — JS rounds 0.5 → 1 (away from
+ *    zero) but `f64.nearest` rounds to even, so a 1:1 lowering is unsound.
+ *  - `Math.min` / `Math.max` are binary and live in `IR_MATH_BINARY_WHITELIST`
+ *    (deferred — needs an `IrBinop` extension).
+ */
+export declare const IR_MATH_UNARY_WHITELIST: ReadonlySet<string>;
+/**
+ * Map a whitelisted `Math.<name>` to its corresponding IR `f64.<op>` tag.
+ * Lives next to the whitelist so callers (selector + lowerer) share one
+ * source of truth.
+ */
+export declare function mathUnaryToIrOp(name: string): "f64.abs" | "f64.sqrt" | "f64.floor" | "f64.ceil" | "f64.trunc" | null;
+export interface IrSelection {
+    readonly funcs: ReadonlySet<string>;
+    /** #1370 Phase A — synthetic-name set keyed by `${className}_${methodName}`
+     *  for instance/static methods, and `${className}_new` for constructors.
+     *  Populated when class members are IR-eligible. The naming convention
+     *  matches `ctx.funcMap` (see `class-bodies.ts:216,275,284`) so Phase B
+     *  can patch pre-allocated function slots by direct lookup.
+     *
+     *  Phase A is selector-only — the `IrSelection.classMembers` is reported
+     *  but `compileIrPathFunctions` does NOT yet patch class-method bodies.
+     *  Phase B wires the integration loop. */
+    readonly classMembers?: ReadonlySet<string>;
+    /** Top-level FunctionDeclaration names that did NOT make it into `funcs`,
+     *  paired with the rejection reason. Only populated when
+     *  `IrSelectionOptions.trackFallbacks` is true. */
+    readonly fallbacks?: ReadonlyArray<IrFallback>;
+}
+export interface IrSelectionOptions {
+    readonly experimentalIR?: boolean;
+    /** When true, the returned selection includes a `fallbacks` array listing
+     *  every top-level FunctionDeclaration that the selector did NOT claim
+     *  along with the reason it was rejected. Off by default — populating
+     *  this list adds a small per-function overhead. */
+    readonly trackFallbacks?: boolean;
+    /**
+     * (#1373b Slice 1) When true, async functions (no `*`) are eligible to
+     * flow through the IR's CPS lowering (Phase C). When false (default),
+     * the selector buckets them into the `"async-function"` fallback reason
+     * and the legacy direct-codegen path takes over.
+     *
+     * Even when true, individual async functions are still rejected by the
+     * selector if their body uses features the Phase C lowering can't handle
+     * yet (try/catch around await — see `isAsyncIrReady`).
+     *
+     * Threaded from `CodegenContext.supportsAsyncIr` via `integration.ts`.
+     */
+    readonly supportsAsyncIr?: boolean;
+}
+/**
+ * (#1373b Slice 1) Centralised gate for whether the IR path can claim a
+ * given async function. The first scaffolding slice hardcodes the answer
+ * to `false` regardless of context — only later slices flip this on once
+ * the CPS continuation synthesis (Slice 2) is parity-tested.
+ *
+ * Body-shape checks (try/catch wrapping await, etc.) live here too so the
+ * selector and lowerer share a single source of truth on what's accepted.
+ */
+export declare function isAsyncIrReady(options: IrSelectionOptions | undefined, _fn: ts.FunctionLikeDeclaration): boolean;
+export declare function planIrCompilation(sourceFile: ts.SourceFile, options?: IrSelectionOptions, typeMap?: TypeMap): IrSelection;