@scriptc/compiler 0.0.0 → 0.0.2

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

@@ -0,0 +1,361 @@
+import * as ts from "../ts7/adapter.js";
+import type { Lowerer } from "./lowerer.js";
+import { IrExpr, IrLocal, IrStmt, IrType, SrcLoc } from "../../ir/nodes.js";
+/** --provenance-sources: true when `decl` is a declarator of a
+ * pureAnnotatedDeadConst statement in a FETCHED SOURCE module whose
+ * declared type has no static mapping — the declaration ELIDES: no
+ * global registers, no code emits, no build diagnostic. The `@__PURE__`
+ * annotation is the author's own declaration that dropping the unused
+ * initializer is safe (the bundler contract — tree-shaken dists of these
+ * packages genuinely ship without it), and a REACHED use of the binding
+ * still fails the build through its per-site fence (no storage exists to
+ * resolve to), so only genuinely-unused bindings ride this. Third-party
+ * fetched source only: the program's own TypeScript keeps its compile
+ * fences. The type probe's diagnostics roll back — elision must not leak
+ * them onto the build — and the elision records ONCE (by position) into
+ * provenanceElided for the coverage report's provenance section. Both
+ * collectGlobals and lowerVarDecl gate on this, BEFORE the mixin/alias
+ * probes that would otherwise claim (and diagnose) the call-initializer
+ * shape. */
+export declare function provenanceElidedConstDecl(L: 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. */
+export declare function lowerStmts(L: 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. CONST ONLY: `let` would need the same trap on writes, a
+   * surface nothing yet needs. */
+export declare function predeclareForwardCapture(L: 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 (varDecl
+   * 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 (L.hoistedFnDecls). Same-function only: the declaration's own
+   * lowering runs under the ctx that owns its statement list, and a
+   * cross-function early capture would need lowering under a DIFFERENT
+   * ctx than the one currently open — that shape keeps the honest fence. */
+export declare function predeclareForwardFnDecl(L: 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. */
+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. */
+export declare function forOfVarTarget(L: Lowerer, decl: ts.VariableDeclaration): {
+    id: string;
+    type: IrType;
+} | null;
+/** `var` declarations hoist to their FUNCTION: the binding exists across
+   * the whole enclosing function body regardless of block position, and
+   * every same-name `var` in that function is the SAME binding (tsc merges
+   * the declarations into one symbol, so symbol-keyed resolution gets the
+   * merge for free). This mints the one function-scoped slot on first
+   * encounter: an IrLocal registered in the function's ROOT scope frame
+   * (never popped by block exits) whose `varDecl` is PUSHED into the
+   * function-root statement list at the current position — everything
+   * already lowered never referenced the symbol (resolution would have
+   * found it), so the position is observationally function entry. Types
+   * with an undefined arm initialize to the interned undefined (JS's
+   * hoisted value — reads before the first assignment are `undefined`, and
+   * tsc's flow analysis rejects such reads for every OTHER type); the rest
+   * start empty, their pre-assignment reads impossible by that analysis.
+   * A `var` merging with a PARAMETER of the same name (one symbol in JS
+   * and in tsc's binder) resolves to the parameter's slot — `var x = 2`
+   * simply overwrites the argument, exactly Node. The source declaration
+   * lowers to a plain `assign` (see lowerVarDecl), so a declaration inside
+   * a loop re-ASSIGNS the one binding per pass and never resets it — the
+   * classic capture semantics fall out: closures made in a loop share the
+   * single boxed binding, where `let` gets a fresh box per iteration. */
+export declare function hoistVarBinding(L: Lowerer, symbol: ts.Symbol, nameNode: ts.Identifier): IrLocal;
+/** 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 DOM 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(L: 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. */
+export declare function noteBlockedBindings(L: 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). */
+export declare function isBlockedBinding(L: Lowerer, symbol: ts.Symbol | null): boolean;
+/** Lowers a statement in a fresh lexical scope (if/while/for bodies). */
+export declare function lowerScopedBlock(L: Lowerer, stmt: ts.Statement): IrStmt[];
+/** The finally fences. `return` crossing OUT of a try/catch body guarded
+   * by a finally is SUPPORTED now (the backend's pending-return path runs
+   * every crossed finally inner-to-outer before the function returns, the
+   * value snapshotted first — Node-exact); what stays rejected is (a) any
+   * jump out of a finally BLOCK itself (a return there would REPLACE a
+   * pending completion — clearing a still-propagating exception or
+   * abandoning a pending return, a model the emitter doesn't implement),
+   * and (b) break/continue crossing a try-with-finally (their targets bind
+   * inside the function; the pending-action plumbing exists only for
+   * return, the shape real code needs). Rejected, not miscompiled. Plain
+   * try/catch is transparent to jumps (it never appears in ctl). A LABELED
+   * jump walks outward past every construct (labeled targets can be
+   * arbitrarily far out) until the entry carrying its label, applying the
+   * same finally fences to everything crossed on the way. */
+export declare function rejectJumpCrossingFinally(L: Lowerer, kw: "break" | "continue" | "return", stmt: ts.Statement, label?: string): void;
+/** `lbl: stmt` — labeled statements. A label chain collapses to one name
+   * list (`a: b: while ...` — both names target the same loop, JS-exact).
+   * Loops and switches take the labels DIRECTLY (a labeled continue needs
+   * the loop's own continue point — the condition/update — and a labeled
+   * switch-break its end): pendingLabels hands them to the construct's own
+   * lowering, which consumes them before lowering anything nested (so an
+   * inner loop can never steal them). Every other labeled statement wraps
+   * in a labeled BLOCK — `break lbl` exits it (the only jump tsc allows to
+   * target a non-loop label), and a label nothing jumps to is just the
+   * statement itself. Loop shapes whose lowering is a label-free desugar
+   * (container/matchAll/stdin for-ofs, union switches) DROP the labels
+   * after consuming them: an unused label costs nothing, and a labeled
+   * jump naming one fences by name at the jump site instead of compiling
+   * against the wrong target. */
+export declare function lowerLabeled(L: Lowerer, stmt: ts.LabeledStatement): IrStmt | IrStmt[] | null;
+export declare function lowerStmt(L: 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. */
+export declare function lowerVarStatement(L: Lowerer, stmt: ts.VariableStatement): IrStmt[];
+/** 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). */
+export declare function lowerDestructuringDecl(L: 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. */
+export declare function lowerBindingPattern(L: Lowerer, pattern: ts.ArrayBindingPattern | ts.ObjectBindingPattern, srcRef: () => IrExpr, srcType: IrType, isLet: boolean, out: IrStmt[]): void;
+/** The STATIC property name of a destructuring key: identifiers spell
+   * themselves, string/numeric-literal keys and COMPUTED keys fold through
+   * foldedStringKeyOf — pure single-name expressions only (`{ [k]: v }`
+   * where k's checker type spells one property name; tsc late-bound the
+   * source's field under exactly that name, and pure keys make skipping
+   * the evaluation exact). Null for runtime-valued keys — the callers
+   * fence, or route island sources to the engine pattern. */
+export declare function patternKeyNameOf(L: Lowerer, prop: ts.PropertyName): string | null;
+/** 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. */
+export declare function checkBindingElement(L: Lowerer, el: ts.BindingElement, allowDefault?: boolean): void;
+/** A declaration pattern rebuilt as ENGINE source with every bound name
+   * renamed __0..__n (pattern order): holes, nesting, rest, and
+   * transportable defaults all survive verbatim, so the engine runs the
+   * REAL pattern — the iterator protocol on array patterns,
+   * RequireObjectCoercible on object patterns, JS's own default rule.
+   * Null when any element has no engine form (computed keys — a compiled
+   * expression the pattern text cannot carry — or untransportable
+   * defaults). */
+export declare function enginePatternSpec(L: Lowerer, pattern: ts.ArrayBindingPattern | ts.ObjectBindingPattern): {
+    text: string;
+    binds: ts.Identifier[];
+    extras: ts.Expression[];
+} | null;
+/** 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). */
+export declare function lowerJsvalBindingPattern(L: Lowerer, pattern: ts.ArrayBindingPattern | ts.ObjectBindingPattern, srcRef: () => IrExpr, isLet: boolean, out: IrStmt[]): boolean;
+/** Binds one destructured name to its value — the identifier tail of
+   * lowerVarDecl (module-global assignment for pre-registered file-scope
+   * names, declareLocal otherwise), or a nested pattern through its own
+   * hidden temp. */
+export declare function bindPatternTarget(L: Lowerer, name: ts.BindingName, value: IrExpr, isLet: boolean, out: IrStmt[]): void;
+/** For-loop initializers. let/const stay restricted to ONE declarator (JS
+   * per-iteration binding copies for several captured loop variables are
+   * not modeled yet); `var` initializers take any number — a `var` is ONE
+   * function-scoped binding with no per-iteration copies to model, so
+   * `for (var i = 0, n = xs.length; ...)` is just two hoisted-slot
+   * assignments (wrapped in a block when several). Statement position goes
+   * through lowerVarStatement. */
+export declare function lowerVarDeclList(L: Lowerer, list: ts.VariableDeclarationList): IrStmt | null;
+export declare function lowerVarDecl(L: Lowerer, decl: ts.VariableDeclaration, isLet: boolean): IrStmt | null;
+/** 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). */
+export declare function lowerSwitch(L: Lowerer, stmt: ts.SwitchStatement): IrStmt;
+/** Switch on a UNION-typed discriminant (`switch (m.type)` over
+   * `string | undefined`): desugared to an if/else-if chain of per-union
+   * strict-equality tests (unionEq — the case value wraps into the union,
+   * exactly `disc === test`), because the backend switch compares plain
+   * primitives only. The desugar is JS-exact for the shape it accepts and
+   * fences everything it cannot reproduce:
+   * - the discriminant rides every test, so it must be a plain
+   *   side-effect-free read (bind it to a const first otherwise);
+   * - tests evaluate lazily in source order (the chain's short-circuit IS
+   *   the switch's test order — grouped empty cases `case a: case b:` OR
+   *   their tests, still in order);
+   * - each non-final clause must EXIT (a trailing unconditional break —
+   *   dropped, it's the chain's own exit — or a return/throw/continue):
+   *   real fall-through between bodies has no if/else shape;
+   * - any OTHER unlabeled break binding to this switch (a conditional
+   *   early break) is fenced — desugared, it would bind to an enclosing
+   *   loop instead;
+   * - `default` may sit anywhere in source (JS tests every case first;
+   *   the chain's final else reproduces that as long as its body exits or
+   *   is last).
+   * Case bodies share ONE lexical scope, exactly like the real switch. */
+export declare function lowerUnionSwitch(L: Lowerer, stmt: ts.SwitchStatement, disc: IrExpr): IrStmt;
+/** try/catch/finally. Supported subset:
+   * - `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`). Raw uses, captures, and
+   *   assignment are fenced (SC1063 and friends); destructuring patterns
+   *   are SC1062. The `: any` / `: unknown` annotations tsc admits both
+   *   lower the same way (tsc narrows either through the tests).
+   * - `finally` runs on normal completion, on exception paths, and on the
+   *   way out of a `return` in the try/catch body (the backend's
+   *   pending-return path — inner-to-outer through nested finallys, the
+   *   value snapshotted before the finally runs, Node-exact).
+   *   break/continue crossing a try-with-finally stay rejected, as does
+   *   any jump out of the finally body itself (it would replace a pending
+   *   completion — rejectJumpCrossingFinally). Plain try/catch places no
+   *   restriction on jumps.
+   * 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(L: 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. */
+export declare function lowerExprStatement(L: 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. */
+export declare function lowerDestructuringAssign(L: 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. */
+export declare function lowerDestructuringAssignParts(L: 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). */
+export declare function lowerForOf(L: Lowerer, stmt: ts.ForOfStatement): IrStmt;
+/** A DIRECT `s.matchAll(re)` call: a stdlib matchAll property call on a
+   * string-typed receiver with one regex-typed argument (parens stripped).
+   * The shape the companion-index machinery serves. */
+export declare function directMatchAllCallOf(L: Lowerer, e: ts.Expression): ts.CallExpression | null;
+/** for-in loops. The key set is Node's own-enumerable-keys walk, lowered
+   * per receiver kind:
+   * - RECORDS (fixed shapes): iteration over exactly the keys Object.keys
+   *   answers — the shared interned keys helper (recordKeysArrayCall):
+   *   declaration order, fields holding the undefined arm of their union
+   *   skipped at runtime (SEMANTICS.md 37's rules verbatim). The key list
+   *   snapshots at loop entry, which IS Node's for-in contract for keys
+   *   ADDED during the walk (never visited); fixed shapes cannot lose keys
+   *   mid-loop (no delete), so the snapshot is exact.
+   * - INDEX-SIGNATURE shapes: the same Object.keys hybrid/pure walk
+   *   (declared fields first, then the overflow in JS own-key order —
+   *   objectIterOverIndexShape's "keys" arm, same intern key). Adds during
+   *   the loop are correctly NOT visited (the snapshot); PURE shapes —
+   *   the one record kind where `delete obj[k]` is lowered — additionally
+   *   guard every visit with a live presence test, Node's HasProperty
+   *   re-check, so keys deleted before their turn are skipped exactly
+   *   like Node.
+   * - ARRAYS: Node's canonical ascending index strings. The key set
+   *   snapshots at entry (pushes during the body are NOT visited — V8's
+   *   own-keys snapshot, verified against Node) while each visit re-checks
+   *   presence (i < live length), so pops during the body skip exactly
+   *   like Node. Sparse arrays cannot exist here (hole creation traps).
+   * - globalThis: the harness's leaked-globals sweep — a compiled binary's
+   *   global bindings are compile-time names, never enumerable runtime
+   *   properties, so the enumeration is honestly EMPTY (zero iterations;
+   *   the body typechecked but never evaluates — SEMANTICS.md documents
+   *   the divergence).
+   * - class instances fence: which keys exist on one depends on runtime
+   *   property creation (unset declared fields, useDefineForClassFields)
+   *   that the struct model does not track — named, not guessed.
+   * Bindings mirror for-of's: const/let declare the per-iteration string
+   * local, `var` assigns the hoisted shared slot, a pre-declared
+   * identifier target assigns per pass; destructuring heads are tsc
+   * errors. */
+export declare function lowerForIn(L: Lowerer, stmt: ts.ForInStatement): IrStmt;
+export declare function lowerForStatement(L: Lowerer, stmt: ts.ForStatement): IrStmt;