@scriptc/compiler 0.2.4 → 0.2.5

package/dist/frontend/lowering/lower-stmts.d.ts

@@ -19,134 +19,134 @@ import { type IrExpr, type IrStmt, type IrType, type SrcLoc } from "../../ir/ir.
  * shape. */
 export declare function provenanceElidedConstDecl(lowerer: Lowerer, decl: ts.VariableDeclaration): boolean;
 /** Lowers statements, one poison catch per statement so one unsupported
-   * construct doesn't hide the rest of the file's diagnostics. A single
-   * source statement may expand to several IR statements (multi-declaration
-   * `let a = 1, b = a + 1;`) but is counted once. */
+ * construct doesn't hide the rest of the file's diagnostics. A single
+ * source statement may expand to several IR statements (multi-declaration
+ * `let a = 1, b = a + 1;`) but is counted once. */
 export declare function lowerStmts(lowerer: Lowerer, stmts: readonly ts.Statement[]): IrStmt[];
 /** The hoisted-handler shape: a function declared BEFORE a const it
-   * captures, in the same (or an enclosing) statement list —
-   *
-   *   const cleanup = () => { process.removeListener("SIGINT", onSigInt); };
-   *   const onSigInt = () => handleSignal("SIGINT");
-   *
-   * JS hoists the BINDING to scope entry (TDZ) and initializes it at the
-   * declaration; a read before initialization throws ReferenceError. Model
-   * exactly that: when a reference fails to resolve anywhere on the
-   * function stack, look for its declaration LATER in an open statement
-   * list — a const with an initializer, pointer-backed type — and
-   * pre-declare it there as a TDZ box (varDecl init:null, boxed, tdz),
-   * registered in the list's scope frame so resolution finds it and
-   * threads captures normally. The source declaration later becomes the
-   * initializing `assign` (lowerVarDecl consumes tdzPredeclared). Reads
-   * test the box and throw Node's exact catchable ReferenceError while it
-   * is empty. Mutable bindings also guard writes; only the declaration's
-   * initializing assignment may leave the temporal dead zone. */
+ * captures, in the same (or an enclosing) statement list —
+ *
+ *   const cleanup = () => { process.removeListener("SIGINT", onSigInt); };
+ *   const onSigInt = () => handleSignal("SIGINT");
+ *
+ * JS hoists the BINDING to scope entry (TDZ) and initializes it at the
+ * declaration; a read before initialization throws ReferenceError. Model
+ * exactly that: when a reference fails to resolve anywhere on the
+ * function stack, look for its declaration LATER in an open statement
+ * list — a const with an initializer, pointer-backed type — and
+ * pre-declare it there as a TDZ box (varDecl init:null, boxed, tdz),
+ * registered in the list's scope frame so resolution finds it and
+ * threads captures normally. The source declaration later becomes the
+ * initializing `assign` (lowerVarDecl consumes tdzPredeclared). Reads
+ * test the box and throw Node's exact catchable ReferenceError while it
+ * is empty. Mutable bindings also guard writes; only the declaration's
+ * initializing assignment may leave the temporal dead zone. */
 export declare function predeclareForwardCapture(lowerer: Lowerer, symbol: ts.Symbol): boolean;
 /** The FUNCTION-DECLARATION twin of predeclareForwardCapture: JS hoists a
-   * nested `function f() {}` to scope entry — the binding is LIVE from the
-   * first statement, so a reference lexically above the declaration in the
-   * SAME function lowers the declaration eagerly at the reference (storage
-   * declaration and initializing assignment are pushed before the current
-   * statement's IR, registered in the list's scope frame) and the statement
-   * loop skips the source statement when it arrives
-   * (the owner's hoistedFnDecls). Forward references from nested functions
-   * lower the declaration under the owning statement list's context, then
-   * resume the caller and thread its captures normally. */
+ * nested `function f() {}` to scope entry — the binding is LIVE from the
+ * first statement, so a reference lexically above the declaration in the
+ * SAME function lowers the declaration eagerly at the reference (storage
+ * declaration and initializing assignment are pushed before the current
+ * statement's IR, registered in the list's scope frame) and the statement
+ * loop skips the source statement when it arrives
+ * (the owner's hoistedFnDecls). Forward references from nested functions
+ * lower the declaration under the owning statement list's context, then
+ * resume the caller and thread its captures normally. */
 export declare function predeclareForwardFnDecl(lowerer: Lowerer, symbol: ts.Symbol): boolean;
 /** True when `decl` (a variable declaration or a pattern name inside one)
-   * was declared with `var` — no const/let/using flag anywhere on its
-   * binding chain. */
+ * was declared with `var` — no const/let/using flag anywhere on its
+ * binding chain. */
 export declare function isVarDeclared(decl: ts.Node): boolean;
 /** `for (var x of ...)` loop variables: the ONE function-scoped binding
-   * every for-of desugar must ASSIGN per iteration instead of declaring a
-   * fresh per-pass local — a captured `var` loop variable is shared by
-   * every closure made in the loop (where `let` gets a fresh binding per
-   * iteration), and it persists after the loop. Returns the write target
-   * (a module global for top-level loops, the hoisted function slot
-   * otherwise); null when the binding isn't a `var` identifier. */
+ * every for-of desugar must ASSIGN per iteration instead of declaring a
+ * fresh per-pass local — a captured `var` loop variable is shared by
+ * every closure made in the loop (where `let` gets a fresh binding per
+ * iteration), and it persists after the loop. Returns the write target
+ * (a module global for top-level loops, the hoisted function slot
+ * otherwise); null when the binding isn't a `var` identifier. */
 export declare function forOfVarTarget(lowerer: Lowerer, decl: ts.VariableDeclaration): {
     id: string;
     type: IrType;
 } | null;
 /** The forward twin of hoistVarBinding, entered from resolution failure: a
-   * reference to a `var` whose declaration statement has not lowered yet —
-   * a read/write lexically above the declaration in the same function
-   * (legal under tsc exactly when the type carries `undefined`), or a
-   * nested function created above it that captures the binding. JS gives
-   * such reads `undefined`, never a TDZ error, so the hoisted slot must
-   * hold `undefined` from function entry — which is only honest for
-   * undefined-armed union types (the interned arm) and checked-dynamic
-   * bindings (the dyn undefined). Everything else returns false
-   * and the reference lands on the named fence in rejectUnresolvedSymbol:
-   * a slot of a narrower type has no bit pattern for the `undefined` Node
-   * would yield if the capture ran early, and guessing "it won't" is the
-   * silent-wrong-output sin. */
+ * reference to a `var` whose declaration statement has not lowered yet —
+ * a read/write lexically above the declaration in the same function
+ * (legal under tsc exactly when the type carries `undefined`), or a
+ * nested function created above it that captures the binding. JS gives
+ * such reads `undefined`, never a TDZ error, so the hoisted slot must
+ * hold `undefined` from function entry — which is only honest for
+ * undefined-armed union types (the interned arm) and checked-dynamic
+ * bindings (the dyn undefined). Everything else returns false
+ * and the reference lands on the named fence in rejectUnresolvedSymbol:
+ * a slot of a narrower type has no bit pattern for the `undefined` Node
+ * would yield if the capture ran early, and guessing "it won't" is the
+ * silent-wrong-output sin. */
 export declare function predeclareForwardVar(lowerer: Lowerer, symbol: ts.Symbol): boolean;
 /** Records the symbols a poisoned DECLARATION statement would have bound
-   * (identifier and pattern names alike, for-initializers included) so
-   * later references report the SC2004 cascade. Registered bindings win:
-   * lowerVarDecl's salvage path declares the local when it can, and
-   * resolution checks locals/globals before the fallthroughs consult
-   * blockedBindings. */
+ * (identifier and pattern names alike, for-initializers included) so
+ * later references report the SC2004 cascade. Registered bindings win:
+ * lowerVarDecl's salvage path declares the local when it can, and
+ * resolution checks locals/globals before the fallthroughs consult
+ * blockedBindings. */
 export declare function noteBlockedBindings(lowerer: Lowerer, stmt: ts.Statement): void;
 /** True when a reference/assignment fell through resolution because the
-   * binding's DECLARATION never compiled: a poisoned declaration statement
-   * (blockedBindings) or a deferred-diagnostic declaration (a blocked
-   * signature/class/global — deferred now, flushed earlier this pass, or
-   * flushed by the emit pass). */
+ * binding's DECLARATION never compiled: a poisoned declaration statement
+ * (blockedBindings) or a deferred-diagnostic declaration (a blocked
+ * signature/class/global — deferred now, flushed earlier this pass, or
+ * flushed by the emit pass). */
 export declare function isBlockedBinding(lowerer: Lowerer, symbol: ts.Symbol | null): boolean;
 /** Lowers a statement in a fresh lexical scope (if/while/for bodies). */
 export declare function lowerScopedBlock(lowerer: Lowerer, stmt: ts.Statement): IrStmt[];
 export declare function lowerStmt(lowerer: Lowerer, stmt: ts.Statement): IrStmt | IrStmt[] | null;
 /** A variable statement may carry several declarators (`let a = 1,
-   * b = a + 1;`): each lowers to its own varDecl IN ORDER, so later
-   * initializers see earlier bindings (JS-exact). `var` declarators ride
-   * the same path — their "declaration" is an assignment into the
-   * function-scoped hoisted slot (hoistVarBinding), so the mutability flag
-   * passed down covers let AND var. */
+ * b = a + 1;`): each lowers to its own varDecl IN ORDER, so later
+ * initializers see earlier bindings (JS-exact). `var` declarators ride
+ * the same path — their "declaration" is an assignment into the
+ * function-scoped hoisted slot (hoistVarBinding), so the mutability flag
+ * passed down covers let AND var. */
 export declare function lowerVarStatement(lowerer: Lowerer, stmt: ts.VariableStatement): IrStmt[];
 /** The numeric indexed source of a built-in value-iterator expression:
-   * `numbers.values()` or the equivalent
-   * `numbers[Symbol.iterator]()`, where numbers is number[] or one of the
-   * represented typed arrays (including Uint8Array). This is deliberately
-   * a syntax + provenance test rather than a mapping for the iterator
-   * object: it has observable mutable protocol state, represented by
-   * hidden locals only while a stored binding stays in one function. */
+ * `numbers.values()` or the equivalent
+ * `numbers[Symbol.iterator]()`, where numbers is number[] or one of the
+ * represented typed arrays (including Uint8Array). This is deliberately
+ * a syntax + provenance test rather than a mapping for the iterator
+ * object: it has observable mutable protocol state, represented by
+ * hidden locals only while a stored binding stays in one function. */
 export declare function numericIteratorSourceOf(lowerer: Lowerer, expr: ts.Expression | undefined): ts.Expression | null;
 /** Whether a checker type belongs to node:util.parseArgs's dyn-backed
  * declaration family. Module ancestry disambiguates short private helper
  * names such as `Token` from names in other standard-library modules. */
 export declare function isParseArgsDynCheckerType(lowerer: Lowerer, type: ts.Type): boolean;
 /** Destructuring declarations, desugared as sugar over indexed/field
-   * reads: the initializer evaluates ONCE into a hidden temp, then each
-   * bound name declares (or assigns its pre-registered module global) from
-   * a read of that temp — `const [a, b] = arr` reads indices 0 and 1,
-   * `const { x, y: z } = rec` reads the fields, nested patterns recurse
-   * through their own temps. Sources are arrays and records; array reads
-   * inherit the array divergence (a pattern longer than the array traps
-   * where JS binds undefined). Defaults, rest elements, and computed keys
-   * are fenced — each would need machinery beyond a read (an undefined
-   * test, surplus packing, dynamic lookup). */
+ * reads: the initializer evaluates ONCE into a hidden temp, then each
+ * bound name declares (or assigns its pre-registered module global) from
+ * a read of that temp — `const [a, b] = arr` reads indices 0 and 1,
+ * `const { x, y: z } = rec` reads the fields, nested patterns recurse
+ * through their own temps. Sources are arrays and records; array reads
+ * inherit the array divergence (a pattern longer than the array traps
+ * where JS binds undefined). Defaults, rest elements, and computed keys
+ * are fenced — each would need machinery beyond a read (an undefined
+ * test, surplus packing, dynamic lookup). */
 export declare function lowerDestructuringDecl(lowerer: Lowerer, decl: ts.VariableDeclaration, isLet: boolean): IrStmt[];
 /** One pattern level: emits a declaration (or global assignment) per
-   * bound name, recursing through hidden temps for nested patterns. */
+ * bound name, recursing through hidden temps for nested patterns. */
 export declare function lowerBindingPattern(lowerer: Lowerer, pattern: ts.ArrayBindingPattern | ts.ObjectBindingPattern, srcRef: () => IrExpr, srcType: IrType, isLet: boolean, out: IrStmt[], dynSpell?: string, allowDynObject?: boolean): void;
 /** The fences the island's element-wise object path shares: no rest
-   * (surplus packing over a handle) and no defaults (an engine undefined
-   * test) — the static positions now take both through their own
-   * machinery above. */
+ * (surplus packing over a handle) and no defaults (an engine undefined
+ * test) — the static positions now take both through their own
+ * machinery above. */
 export declare function checkBindingElement(lowerer: Lowerer, el: ts.BindingElement, allowDefault?: boolean): void;
 /** Declaration-position destructuring over an ISLAND source: the ENGINE
-   * runs the real pattern — a synthesized strict-mode
-   * `new Function("v", ...)` exactly like the assignment chain's
-   * (lowerJsvalDestructuringChain) — and the extracted values bind the
-   * declared names: a name whose declared type is a primitive exits
-   * eagerly (the island property-read rule), everything else stays a
-   * HANDLE whose use sites dispatch to engine ops. Holes, nesting, empty
-   * patterns (the object coercion check and the array iterator get+close
-   * both run — destructuring undefined throws Node's TypeError at Node's
-   * exit), rest, and transportable defaults all ride. False when the
-   * pattern has no engine form (the caller fences). */
+ * runs the real pattern — a synthesized strict-mode
+ * `new Function("v", ...)` exactly like the assignment chain's
+ * (lowerJsvalDestructuringChain) — and the extracted values bind the
+ * declared names: a name whose declared type is a primitive exits
+ * eagerly (the island property-read rule), everything else stays a
+ * HANDLE whose use sites dispatch to engine ops. Holes, nesting, empty
+ * patterns (the object coercion check and the array iterator get+close
+ * both run — destructuring undefined throws Node's TypeError at Node's
+ * exit), rest, and transportable defaults all ride. False when the
+ * pattern has no engine form (the caller fences). */
 export declare function lowerJsvalBindingPattern(lowerer: Lowerer, pattern: ts.ArrayBindingPattern | ts.ObjectBindingPattern, srcRef: () => IrExpr, isLet: boolean, out: IrStmt[]): boolean;
 export declare function bindPatternTarget(lowerer: Lowerer, name: ts.BindingName, value: IrExpr, isLet: boolean, out: IrStmt[], allowDynObject?: boolean): void;
 /** For-loop initializers evaluate declarators from left to right. The LLVM
@@ -159,74 +159,74 @@ export declare function hasJsTypeAnnotation(decl: ts.VariableDeclaration): boole
  * an any-valued callback. Keep those bindings open, including captured writes. */
 export declare function jsBindingHasOpenWrites(lowerer: Lowerer, decl: ts.VariableDeclaration): boolean;
 /** JS-exact switch (see docs/ir.md): one shared lexical scope for all case
-   * bodies, lazy source-order test evaluation, fall-through. tsc has already
-   * checked case-test comparability (TS2678) — the kind check below is the
-   * backstop for cases tsc lets through (e.g. `unknown as` casts). */
+ * bodies, lazy source-order test evaluation, fall-through. tsc has already
+ * checked case-test comparability (TS2678) — the kind check below is the
+ * backstop for cases tsc lets through (e.g. `unknown as` casts). */
 export declare function lowerSwitch(lowerer: Lowerer, stmt: ts.SwitchStatement): IrStmt;
 /** try/catch/finally:
-   * - `catch { }` (bindingless) discards the thrown value on entry.
-   * - `catch (e)` binds it as a CAUGHT local — a snapshot of the exception
-   *   cell, deliberately narrower than dyn: the supported uses are the
-   *   narrowing tests (`e instanceof C` over hierarchy classes, `typeof e
-   *   === "string"/"number"/"boolean"`), reads under a proven narrow
-   *   (caughtRead bridges them with caughtNarrow, trust-the-checker like
-   *   unionNarrow), and rethrow (`throw e`). Unsupported raw uses and
-   *   assignments are fenced (SC1063 and friends); destructuring patterns
-   *   are SC1062. Captures retain the snapshot beyond the catch scope.
-   *   The `: any` / `: unknown` annotations tsc admits both
-   *   lower the same way (tsc narrows either through the tests).
-   * - `finally` runs on normal completion, exception paths, and every
-   *   abrupt completion that crosses it. Return values are snapshotted
-   *   before cleanup; an abrupt completion inside the finally replaces the
-   *   pending one, matching JavaScript completion-record semantics.
-   * Each block is its own lexical scope (the binding lives in a scope
-   * WRAPPING the catch block, like the spec's catch environment). */
+ * - `catch { }` (bindingless) discards the thrown value on entry.
+ * - `catch (e)` binds it as a CAUGHT local — a snapshot of the exception
+ *   cell, deliberately narrower than dyn: the supported uses are the
+ *   narrowing tests (`e instanceof C` over hierarchy classes, `typeof e
+ *   === "string"/"number"/"boolean"`), reads under a proven narrow
+ *   (caughtRead bridges them with caughtNarrow, trust-the-checker like
+ *   unionNarrow), and rethrow (`throw e`). Unsupported raw uses and
+ *   assignments are fenced (SC1063 and friends); destructuring patterns
+ *   are SC1062. Captures retain the snapshot beyond the catch scope.
+ *   The `: any` / `: unknown` annotations tsc admits both
+ *   lower the same way (tsc narrows either through the tests).
+ * - `finally` runs on normal completion, exception paths, and every
+ *   abrupt completion that crosses it. Return values are snapshotted
+ *   before cleanup; an abrupt completion inside the finally replaces the
+ *   pending one, matching JavaScript completion-record semantics.
+ * Each block is its own lexical scope (the binding lives in a scope
+ * WRAPPING the catch block, like the spec's catch environment). */
 export declare function lowerTry(lowerer: Lowerer, stmt: ts.TryStatement): IrStmt;
 /** Expression-position statements: assignments, calls. Shared with
-   * for-loop init/update. Parens unwrap first — `(x = v);` is the plain
-   * assignment, and `({ a, b } = e);` (destructuring ASSIGNMENT, which JS
-   * requires parenthesized in statement position) lands in the
-   * object-literal-target branch below. */
+ * for-loop init/update. Parens unwrap first — `(x = v);` is the plain
+ * assignment, and `({ a, b } = e);` (destructuring ASSIGNMENT, which JS
+ * requires parenthesized in statement position) lands in the
+ * object-literal-target branch below. */
 export declare function lowerExprStatement(lowerer: Lowerer, expr: ts.Expression): IrStmt;
 /** `({ a, b: x } = e);`, `[a, b = 0, ...rest] = xs;` — destructuring
-   * assignment to EXISTING writable bindings, statement position, from a
-   * PRE-LOWERED source: for-of expression heads hand the per-iteration
-   * element in directly (no RHS expression exists there, so
-   * checked-dynamic sources fence — V8's TypeError spells the source
-   * text). Plain assignment statements ride
-   * lowerDestructuringAssignParts, which keeps the RHS expression for
-   * that spelling. */
+ * assignment to EXISTING writable bindings, statement position, from a
+ * PRE-LOWERED source: for-of expression heads hand the per-iteration
+ * element in directly (no RHS expression exists there, so
+ * checked-dynamic sources fence — V8's TypeError spells the source
+ * text). Plain assignment statements ride
+ * lowerDestructuringAssignParts, which keeps the RHS expression for
+ * that spelling. */
 export declare function lowerDestructuringAssign(lowerer: Lowerer, target: ts.ObjectLiteralExpression | ts.ArrayLiteralExpression, init: IrExpr, blame: ts.Node, loc: SrcLoc): IrStmt;
 /** Destructuring ASSIGNMENT (existing bindings — the declaration twin is
-   * lowerDestructuringDecl): the RHS evaluates ONCE into a hidden temp,
-   * each target assigns in source order, and the parts' VALUE is the
-   * temp — JS's assignment-expression value is the RHS value, so the same
-   * parts serve statement position (block) and expression position
-   * (seqExpr). Object patterns cover shorthand/renamed identifier targets
-   * over record sources and checked-dynamic sources (keyed reads behind
-   * V8's exact RequireObjectCoercible TypeError); array patterns cover
-   * identifier targets with optional defaults over arrays, tuples, and
-   * checked-dynamic sources (dynIterN's GetIterator semantics), elisions,
-   * a sole leading rest whose operand is itself an array pattern
-   * (`[...[a, b = 0]] = t` consumes the same elements as the inner
-   * pattern alone), and the EMPTY patterns (`({} = e)` requires object-
-   * coercibility, `[] = e` requires iterability — both pure for sources
-   * whose static type already proves it). Object patterns over record
-   * sources take defaults (`{ x = 1 }` — the undefined-arm test against
-   * the TARGET's own type) and rest (`{ ...bar }` — the unconsumed fields
-   * pack into a fresh record, JS's CopyDataProperties stance); array
-   * patterns take defaults everywhere (arrays carry the bounds test JS's
-   * past-the-end undefined demands) and rest packing the tail fresh
-   * (array slices, tuple tails). Nesting, computed keys, and member
-   * targets keep fences. */
+ * lowerDestructuringDecl): the RHS evaluates ONCE into a hidden temp,
+ * each target assigns in source order, and the parts' VALUE is the
+ * temp — JS's assignment-expression value is the RHS value, so the same
+ * parts serve statement position (block) and expression position
+ * (seqExpr). Object patterns cover shorthand/renamed identifier targets
+ * over record sources and checked-dynamic sources (keyed reads behind
+ * V8's exact RequireObjectCoercible TypeError); array patterns cover
+ * identifier targets with optional defaults over arrays, tuples, and
+ * checked-dynamic sources (dynIterN's GetIterator semantics), elisions,
+ * a sole leading rest whose operand is itself an array pattern
+ * (`[...[a, b = 0]] = t` consumes the same elements as the inner
+ * pattern alone), and the EMPTY patterns (`({} = e)` requires object-
+ * coercibility, `[] = e` requires iterability — both pure for sources
+ * whose static type already proves it). Object patterns over record
+ * sources take defaults (`{ x = 1 }` — the undefined-arm test against
+ * the TARGET's own type) and rest (`{ ...bar }` — the unconsumed fields
+ * pack into a fresh record, JS's CopyDataProperties stance); array
+ * patterns take defaults everywhere (arrays carry the bounds test JS's
+ * past-the-end undefined demands) and rest packing the tail fresh
+ * (array slices, tuple tails). Nesting, computed keys, and member
+ * targets keep fences. */
 export declare function lowerDestructuringAssignParts(lowerer: Lowerer, target: ts.ObjectLiteralExpression | ts.ArrayLiteralExpression, rhs: ts.Expression, loc: SrcLoc): {
     stmts: IrStmt[];
     value: IrExpr;
 };
 /** `for (const x of arr)` — arrays only. The lib types strings and Maps
-   * as iterable too, so those for-ofs typecheck and are fenced below with
-   * specific diagnostics; other iterables fail on their types. The loop
-   * variable is a fresh const binding per iteration (its own scope, like a
-   * loop body). */
+ * as iterable too, so those for-ofs typecheck and are fenced below with
+ * specific diagnostics; other iterables fail on their types. The loop
+ * variable is a fresh const binding per iteration (its own scope, like a
+ * loop body). */
 export declare function lowerForOf(lowerer: Lowerer, stmt: ts.ForOfStatement): IrStmt;
 export declare function lowerForStatement(lowerer: Lowerer, stmt: ts.ForStatement): IrStmt;