@scriptc/compiler 0.2.7 → 0.2.9

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

@@ -1,6 +1,8 @@
 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 { NanCodedReads } from "./nan-coded-reads.js";
 import { RuntimeOptionalLocals } from "./runtime-optional-locals.js";
 import type { WidthLift } from "./width-lift.js";
 import { type FnCtx } from "./function-context.js";
@@ -77,6 +79,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;
@@ -100,7 +107,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[];
@@ -351,6 +362,15 @@ 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>;
+    /** Typed-array element reads whose every consumer treats undefined like
+     * NaN, which lower to plain doubles (see nan-coded-reads.ts). Settled by
+     * analyzeRuntimeOptionalArrayReads before any body lowers. */
+    nanCodedReads: NanCodedReads | null;
+    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[]>>;
@@ -472,6 +492,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>;
@@ -489,6 +514,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>;
@@ -522,6 +558,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. */
@@ -818,6 +860,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. */
@@ -901,6 +946,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). */
@@ -957,6 +1012,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. */
@@ -1106,7 +1165,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
@@ -1388,6 +1455,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;
@@ -1530,6 +1598,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;
@@ -1857,6 +1933,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[];
@@ -2015,7 +2096,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;