@scriptc/compiler 0.2.6 → 0.2.8

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

@@ -1,5 +1,7 @@
+import { type CycleInitFlag } from "./cycle-initialization.js";
 import type { FieldLift } from "./coercions/structural-plans.js";
 import { CoercionState } from "./coercions/state.js";
+import { StringIndexBounds } from "./string-index-bounds.js";
 import { RuntimeOptionalLocals } from "./runtime-optional-locals.js";
 import type { WidthLift } from "./width-lift.js";
 import { type FnCtx } from "./function-context.js";
@@ -76,6 +78,11 @@ export declare function boundIdentifiersOf(name: ts.BindingName): ts.Identifier[
 /** Inspect executable children directly, without boxing the statement tree
  * into checked-dynamic storage just to calculate coverage. */
 export declare function stmtUsesIsland(stmts: IrStmt | IrStmt[]): boolean;
+/** Statements a never-lowered body would have contributed to the coverage
+ * totals: every element of a statement list (blocks, case clauses), plus
+ * the single-statement bodies of control flow, nested functions included —
+ * the same accounting lowerStmts applies to bodies that do lower. */
+export declare function countBodyStatements(root: ts.Node): number;
 export interface LowerResult {
     /** Present iff diagnostics is empty. */
     module: IrModule | null;
@@ -99,7 +106,11 @@ export interface LowerResult {
     unreached?: {
         diagnostics: ScrDiagnostic[];
         stats: LowerStats;
+        runtimeFences?: ScrDiagnostic[];
     };
+    /** Compile-time-detectable behavior differences from Node (SC6xxx
+     * divergence warnings) in the program's own modules. Never failures. */
+    divergences?: ScrDiagnostic[];
     /** --dynamic only: every Node builtin the embedded npm graph imports,
      * shimmed or not — the coverage report's island honesty. */
     npmBuiltins?: NpmBuiltinUse[];
@@ -350,6 +361,11 @@ export declare class Lowerer {
     /** Per-symbol result of the never-reassigned file scan
      * (bindingNeverReassigned — object-literal generic-method receivers). */
     readonly neverReassignedCache: Map<ts.Symbol, boolean>;
+    private stringIndexBoundsCache;
+    /** Proofs that a string element read names an existing code unit. The
+     * indexed-read analysis and expression lowering share one instance, so a
+     * read's representation and its callers' signatures always agree. */
+    get stringIndexBounds(): StringIndexBounds;
     /** Syntactic writes indexed once per JS scope. Symbol and RHS type
      * checks remain contextual to each binding probe. */
     readonly jsBindingWritesByOwner: Map<import("../ts7/ast-node.js").AstNode, Map<string, ts.BinaryExpression[]>>;
@@ -471,6 +487,11 @@ export declare class Lowerer {
      * prepass. This includes explicit annotations: unchecked TS annotations do
      * not prove that an array property read produced a value. */
     readonly runtimeOptionalBindingTypes: Map<ts.Symbol, IrType>;
+    /** Bindings that receive an unchecked indexed read (or a value derived
+     * from one) through an initializer or assignment. The checker narrows a
+     * declared optional binding to that read's bare type, so presence tests
+     * on these bindings consult the stored tag instead. */
+    readonly runtimeOptionalAssignedSymbols: Set<ts.Symbol>;
     /** Concise callback/lambda returns promoted by the HOF callback prepass;
      * arrows have no declaration symbol to key in fnSigsBySymbol. */
     readonly runtimeOptionalFunctionReturns: Map<import("../ts7/ast-node.js").AstNode, IrType>;
@@ -488,6 +509,17 @@ export declare class Lowerer {
      * every name destructured from a present source optional. */
     readonly runtimeOptionalPatternTypes: Map<import("../ts7/ast-node.js").AstNode, IrType>;
     readonly runtimeOptionalReduceTypes: Map<ts.CallExpression, IrType>;
+    /** Non-null assertions whose value is forwarded into a slot promoted to
+     * hold undefined. `x!` has no runtime effect, so these keep the stored
+     * undefined state instead of trapping before any dereference. */
+    readonly runtimeOptionalAssertions: Set<ts.NonNullExpression>;
+    /** Array callback calls whose receiver the optional-read analysis proved
+     * never holds an explicit undefined (or a hole, for the find family):
+     * their callbacks take the element type itself. */
+    readonly presentElementCalls: Set<ts.CallExpression>;
+    /** for-of loops over arrays that can hold neither holes nor undefined:
+     * each pass reads the element payload directly. */
+    readonly presentElementLoops: Set<ts.ForOfStatement>;
     /** Capture entries and their origin share one mutable box. Normalize each
      * entry to the origin so writes and flow proofs stay synchronized. */
     readonly runtimeOptionalRoots: Map<IrLocal, IrLocal>;
@@ -521,6 +553,12 @@ export declare class Lowerer {
     promoteRuntimeOptionalParameter(node: ts.Node, type: IrType): IrType;
     promoteRuntimeOptionalFunctionReturn(node: ts.Node, type: IrType): IrType;
     runtimeOptionalFunctionReturnType(node: ts.Node, fallback: IrType): IrType;
+    /** True when `actual` is `declared` with some record fields (directly,
+     * in nested records, or in an array's element records) widened to runtime-optional unions:
+     * fields filled from unchecked indexed reads the checker calls present.
+     * Inferred bindings and destructured parameters keep that layout instead
+     * of narrowing it away. */
+    isRuntimeOptionalRecordVariant(actual: IrType, declared: IrType): boolean;
     /** Promote one field of a record storage shape to the value's runtime
      * type. Shapes are immutable by identity, so this interns a sibling shape
      * and records the field as runtime-optional for property-read narrowing. */
@@ -537,6 +575,8 @@ export declare class Lowerer {
     /** True while re-lowering a base function's 2nd+ instance: the same source
      * statements were already counted for the first instance. */
     suppressStats: boolean;
+    /** Comparisons interned by operand representations and equality semantics. */
+    readonly equalityHelpers: Map<string, string>;
     /** Synthetic array-HOF loop functions (map/filter/forEach desugar),
      * interned per method + element/callback-result type: key → fn name. */
     readonly arrHofHelpers: Map<string, string>;
@@ -633,6 +673,10 @@ export declare class Lowerer {
      * node carrying the ?. token is marked handled so the receiver-typed
      * lowerings stop declining it (chainBlocked). */
     readonly chainRecvByNode: Map<import("../ts7/ast-node.js").AstNode, IrExpr>;
+    /** Lowered void calls whose checked type is `never` (they throw or exit).
+     * TypeScript lets such a call stand where any value is expected;
+     * coerceToExpected turns them into diverging sequences. */
+    readonly neverValued: Set<IrExpr>;
     readonly chainNarrowedType: Map<import("../ts7/ast-node.js").AstNode, ts.Type>;
     readonly chainHandled: Set<import("../ts7/ast-node.js").AstNode>;
     /** for-of-over-matchAll bindings whose `.index` reads the companion-index
@@ -676,6 +720,8 @@ export declare class Lowerer {
     /** Named method slots observed before class collection need a callable
      * ABI and shared prototype descriptors instead of call-site specialization. */
     readonly prototypeMethodAccesses: Map<string, import("../ts7/ast-node.js").AstNode>;
+    /** Field names whose complete source census stores only lexical arrows. */
+    readonly receiverFreeCallbackFields: Set<string>;
     /** Inferred JS methods participating in an override chain keep a vtable
      * ABI instead of call-site specialization. Filled before class collection. */
     readonly virtualJsMethods: Set<ts.MethodDeclaration>;
@@ -809,6 +855,9 @@ export declare class Lowerer {
      * and therefore becomes the cycle's evaluation root. Dynamic imports
      * wait on this shared verdict rather than a build-time-selected member. */
     readonly asyncCyclePromiseOf: Map<ts.SourceFile, string>;
+    /** Modules whose evaluation an import() can request again after it threw,
+     * computed on first use (lower-modules.ts importRetryModules). */
+    importRetryModules: ReadonlySet<ts.SourceFile> | null;
     /** Record-shape interner: canonical (name-sorted) field list → shapeId.
      * Threaded into every mapType call; its `shapes` array becomes
      * IrModule.records. */
@@ -860,6 +909,10 @@ export declare class Lowerer {
      * function called above the declaration statement reads that, never a
      * NULL slot. Filled by collectGlobals. */
     readonly varGlobalEntryInits: Map<ts.SourceFile, IrGlobal[]>;
+    /** Import-cycle bindings with an initialization flag, by global id, and
+     * the top-level statements declaring them (cycle-initialization.ts). */
+    readonly cycleInitFlags: Map<string, CycleInitFlag>;
+    readonly cycleInitDeclarations: Map<ts.StatementBase, CycleInitFlag[]>;
     get ctx(): FnCtx;
     get scopes(): Map<ts.Symbol, IrLocal>[];
     /** Names of bodies a prior reachability pass reached; null lowers everything. */
@@ -888,6 +941,16 @@ export declare class Lowerer {
      * coverage remainder as alreadyFlushed). */
     readonly flushedSymbols: Set<ts.Symbol>;
     readonly alreadyFlushed: ReadonlySet<ts.Symbol>;
+    /** Deferred diagnostics a flush handed to a capture buffer (diagSink)
+     * instead of the build, keyed by the copy in that buffer. A buffer can
+     * be discarded (a declined probe, a collection that succeeded) or
+     * re-deferred under another declaration, so the declaration stays
+     * deferred until one of these copies reaches `diags` (pushDiag commits
+     * it); until then a later flush reports the diagnostics again. */
+    readonly pendingFlushes: Map<ScrDiagnostic, {
+        symbol: ts.Symbol;
+        source: ScrDiagnostic;
+    }>;
     /** The build's target platform ("win32" | "darwin" | "linux" | ...):
      * selects the platform-keyed builtin surfaces (builtinModuleFnsOf /
      * builtinModuleConstOf in surfaces.ts). */
@@ -944,6 +1007,10 @@ export declare class Lowerer {
     registerBuiltinErrorClasses(): void;
     private classProtocols;
     classImplementedProtocol(type: ts.Type): boolean;
+    /** Declared class fields may store a DYN value only when its static type
+     * names checked protocol identity or an owned runtime handle (a Worker
+     * or MessagePort); `unknown` and `any` fields stay refused. */
+    classFieldStoresDyn(type: ts.Type): boolean;
     /** The nominal identity of a checker module-namespace type. Program
      * modules use their normalized absolute source name; supported builtins
      * use the lowering tables' canonical bare name. */
@@ -1093,7 +1160,15 @@ export declare class Lowerer {
      * registered ClassInfo — the shape of a JS class whose collection fenced.
      * Used by run()'s global pruning; shapes/unions recurse with a seen-set
      * (interned ids can nest). */
-    typeNamesUnregisteredClass(t: IrType, seen?: Set<string>): boolean;
+    typeNamesUnregisteredClass(t: IrType): boolean;
+    /** The first class name typeNamesUnregisteredClass finds in `t`. */
+    unregisteredClassOf(t: IrType, seen: Set<string>): string | null;
+    /** A declaration whose signature blocked never lowers its body, so its
+     * statements would otherwise vanish from the coverage totals and the
+     * percentage would overstate how much of the program compiles. Count
+     * every statement the body holds as attempted and failed, in addition to
+     * the skipped-function tally. */
+    private countSkippedBody;
     /** Whether run() counts a signature-blocked declaration in
      * stats.functionsSkipped: whole-program passes and the coverage
      * remainder do; an externally-gated emit pass leaves the counting to the
@@ -1291,6 +1366,8 @@ export declare class Lowerer {
     literalUnionArm(unionId: string, values: readonly UnionLiteral[]): (IrType & {
         kind: "record";
     }) | null;
+    /** Widen only the result view; identical parameter ABIs preserve closure identity. */
+    coerceCovariantFunction(expr: IrExpr, expected: IrType): IrExpr | null;
     /** Implicit union construction. Wherever a value flows into a typed slot
      * (initializer, assignment, call argument, return, field write, record
      * literal field, ternary arm) whose expected type is a union and the
@@ -1373,6 +1450,7 @@ export declare class Lowerer {
     }, toId: string, loc: SrcLoc): string | null;
     unionRetagHelper(fromId: string, toId: string, loc: SrcLoc, trappable?: ReadonlySet<number>): string | null;
     narrowedArmHelper(fromId: string, target: IrType, loc: SrcLoc): string | null;
+    checkedNarrowCall(helper: string, value: IrExpr, type: IrType, loc: SrcLoc): IrExpr;
     deferredReadHelper(fromId: string, target: IrType, loc: SrcLoc): string | null;
     jsvalLiftable(t: IrType, visiting?: Set<string>): boolean;
     jsvalLiftExpr(e: IrExpr, loc: SrcLoc): IrExpr;
@@ -1472,6 +1550,23 @@ export declare class Lowerer {
     paramShapes(params: readonly ts.ParameterDeclaration[]): ParamShape[];
     completeArgs(argNodes: readonly ts.Expression[], shapes: readonly ParamShape[], loc: SrcLoc, blame: ts.Node): IrExpr[];
     wrappedUndefined(type: IrType, loc: SrcLoc): IrExpr | null;
+    /** The value an OMITTED or deleted property leaves in a record field
+     * slot of `type`: the ABSENT state for undefined-armed unions (the slot
+     * reads as undefined but the property does not exist), the dyn
+     * undefined for 'unknown' slots, and null when the slot cannot be
+     * missing. Only legal as a direct field-slot write (IR fieldAbsent). */
+    absentFieldValue(type: IrType, loc: SrcLoc): IrExpr | null;
+    /** A field copy that keeps absence: `value` (the converted read of
+     * `field` from record `obj`, which must be repeatable) when the source
+     * property exists, else the target slot's ABSENT state. Fields that are
+     * always present, and targets that cannot be absent, copy `value`
+     * as-is. Only legal as a direct field-slot write. */
+    presenceKeepingCopy(obj: IrExpr, shapeId: string, field: string, value: IrExpr, loc: SrcLoc): IrExpr;
+    /** Own-property presence of declared field `field` on record `obj`
+     * (borrowed — callers pass a repeatable receiver): a runtime test for
+     * undefined-armed union fields, which can be absent, and `true` for
+     * every other declared field. */
+    recordFieldPresent(obj: IrExpr, shapeId: string, field: string, loc: SrcLoc): IrExpr;
     /** The entry value of a binding JS initializes to `undefined` (an
      * initializer-less declaration, a hoisted `var` before its statement):
      * undefined-armed unions hold the interned undefined arm, and 'any'
@@ -1498,6 +1593,14 @@ export declare class Lowerer {
      * may follow) — reached-but-broken declarations report the same set of
      * diagnostics the eager collector historically produced. */
     flushDeferred(symbol: ts.Symbol): void;
+    /** flushDeferred without the collection-pass guard: for declarations
+     * whose diagnostics must report eagerly (class statements with
+     * declaration-time code, extended bases — collectClassShapeDeferring). */
+    reportDeferred(symbol: ts.Symbol): void;
+    /** A flushed copy of a deferred diagnostic reached `diags`: that
+     * diagnostic is reported, so it leaves the declaration's deferred list
+     * (the declaration counts as flushed for the coverage remainder). */
+    private commitFlush;
     flushDeferredClass(className: string): void;
     collectSignature(decl: ts.FunctionDeclaration): void;
     collectSignatureInner(decl: ts.FunctionDeclaration): void;
@@ -1645,6 +1748,11 @@ export declare class Lowerer {
     lowerDefaultExport(stmt: ts.ExportAssignment): IrStmt | null;
     buildMain(): IrFunction;
     declareLocal(nameNode: ts.Node, name: string, type: IrType, mutable: boolean): IrLocal;
+    /** A never-returning call in a value position of type `expected`: the
+     * call runs for its effects (it throws or exits), and the expression ends
+     * in an unreachable trap instead of producing a value. The result reads an
+     * uninitialized hidden local that control never reaches. */
+    divergentValue(call: IrExpr, expected: IrType): IrExpr;
     /** A function-scope local bound to NO ts.Symbol — the hidden ABI slot of a
      * defaulted parameter (the parameter's symbol binds to the separately-
      * declared body local; nothing in the source can name this one). */
@@ -1820,6 +1928,11 @@ export declare class Lowerer {
     classIteratorDrainCall(src: IrExpr, loc: SrcLoc, elemT?: IrType): IrExpr | null;
     classIteratorRestDrainCall(cit: ClassIteratorInfo, itVal: IrExpr, loc: SrcLoc): IrExpr;
     fieldGetExpr(target: FieldTarget, loc: SrcLoc, blame: ts.Node): IrExpr;
+    /** The undefined-armed slot read behind a checked deferred-init field
+     * read, or null. Consumers that observe undefined itself (equality,
+     * typeof, truthiness, nullish defaults) test the slot instead of the
+     * checked extraction, which throws for an unassigned field. */
+    deferredFieldSlot(value: IrExpr): IrExpr | null;
     fieldSetStmt(target: FieldTarget, value: IrExpr, loc: SrcLoc, blame: ts.Node): IrStmt;
     lowerFieldCompound(access: ts.PropertyAccessExpression | ts.ElementAccessExpression, op: CompoundOp, rhsNode: ts.Expression | null, loc: SrcLoc): IrStmt;
     errorConstructorArgs(args: readonly ts.Expression[], loc: SrcLoc, blame: ts.Node): IrExpr[];
@@ -1978,7 +2091,7 @@ export declare class Lowerer {
     lowerPromiseMethodCall(call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
     lowerPromiseStaticCall(call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;
     lowerNumberStaticProperty(expr: ts.PropertyAccessExpression): IrExpr | null;
-    requireDynamicApi(feature: string, node: ts.Node): void;
+    requireDynamicApi(feature: string, node: ts.Node, hint?: string): void;
     lowerMathProperty(expr: ts.PropertyAccessExpression): IrExpr | null;
     islandGlobalFnOf(ident: ts.Identifier): IslandFnEntry | null;
     lowerIslandMethodCall(call: ts.CallExpression, access: ts.PropertyAccessExpression): IrExpr | null;