@scriptc/compiler 0.0.36 → 0.1.2

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

@@ -85,6 +85,9 @@ export interface FnCtx {
     generator?: {
         yieldT: IrType;
         nextT: IrType;
+        resultType: IrType & {
+            kind: "record";
+        };
     } | null;
     /** VARIADIC `arguments` form (rest-marked func type with no declared
      * rest param): the synthetic trailing dyn-array param `arguments`
@@ -103,17 +106,13 @@ export interface FnCtx {
             node: ts.Expression | null;
         }[];
     } | null;
-    /** Enclosing control constructs, innermost last: loops/switches/labeled
-     * blocks (jump targets — `labels` carries their JS label names so labeled
-     * break/continue resolve), try-with-finally regions ("tryFinally" — a
-     * try/catch body guarded by a finally: `return` crosses them now via the
-     * backend's pending-return path; break/continue still reject), and
-     * finally BLOCKS themselves ("finallyBlock" — jumps out stay rejected: a
-     * return there would REPLACE a pending completion, a model the emitter
-     * doesn't implement; see rejectJumpCrossingFinally). Per function: a
-     * nested function's jumps never bind to enclosing constructs. */
+    /** Enclosing jump targets, innermost last. `labels` carries the source
+     * statement's JS label names so labeled break/continue resolve. Finally
+     * regions do not appear here: the backends route every abrupt completion
+     * through the cleanup regions it crosses. Per function, so a nested
+     * function's jumps never bind to enclosing constructs. */
     ctl: {
-        kind: "loop" | "switch" | "block" | "tryFinally" | "finallyBlock";
+        kind: "loop" | "switch" | "block";
         labels?: string[];
     }[];
 }
@@ -191,7 +190,7 @@ export interface LowerOptions {
      * path.win32 keep answering THEIR platform everywhere, like Node's. */
     targetPlatform?: string;
     /** Node's startup refusal (LoadResult.startupCrash — preflight's
-     * resolution walk and CJS named-import link check): the program
+     * resolution walk and named-import link checks): the program
      * compiles to that startup crash. */
     startupCrash?: StartupCrash | null;
     /** LIBRARY mode's reachability roots: the profile-mapped exports of the
@@ -242,10 +241,7 @@ interface RuntimeFenceFunctionTarget extends RuntimeFenceBase {
     returnType: IrType;
     paramsMutable?: boolean;
     async?: true;
-    generator?: {
-        yieldT: IrType;
-        nextT: IrType;
-    };
+    generator?: NonNullable<IrFunction["generator"]>;
 }
 interface RuntimeFenceClosureTarget extends Omit<RuntimeFenceFunctionTarget, "kind"> {
     kind: "closure";
@@ -267,8 +263,8 @@ export interface LowererMode {
     /** The build's target platform (LowerOptions.targetPlatform — lowerToIr
      * passes it to every pass). Defaults to the host. */
     targetPlatform?: string;
-    /** Node's startup refusal (preflight's resolution walk / CJS named-
-     * import link check): %main opens with exactly this throw, before any
+    /** Node's startup refusal (preflight's resolution walk / named-import
+     * link checks): %main opens with exactly this throw, before any
      * module init — Node refuses the whole graph before anything evaluates,
      * so nothing runs. */
     startupCrash?: StartupCrash | null;
@@ -432,7 +428,7 @@ export declare class Lowerer {
      * (reading 'fn')"); nullish-to-nullish flows lower to nothing. The map
      * answers which unit the binding holds (the TypeError names it). Null
      * entries cache probed non-qualifiers. */
-    readonly nullishBindings: Map<ts.Symbol, "undefined" | "null" | null>;
+    readonly nullishBindings: Map<ts.Symbol, "null" | "undefined" | null>;
     /** DEAD bindings of unmappable types: never READ anywhere in the
      * program, declared with no initializer or a value-only one (a function
      * literal), every write's RHS side-effect-free. Node materializes the
@@ -504,10 +500,70 @@ export declare class Lowerer {
     /** All storage slots widened for runtime absence, including slots whose
      * current control-flow branch has temporarily narrowed the value. */
     readonly runtimeOptionalStorageLocals: Set<IrLocal>;
+    /** Globals whose checker-bare type was widened because an indexed read can
+     * carry undefined at runtime. Identifier reads keep the union tag so
+     * typeof and later boundaries observe the real value. */
+    readonly runtimeOptionalGlobals: Set<IrGlobal>;
+    /** Bindings whose unchecked string arithmetic can produce either a number
+     * (NaN for an absent read) or a string. Preserve that result union at bare
+     * reads instead of applying the checker-bare string narrowing adapter. */
+    readonly runtimeOptionalArithmeticLocals: Set<IrLocal>;
+    readonly runtimeOptionalArithmeticGlobals: Set<IrGlobal>;
+    /** Binding symbols whose IR storage type was widened by the indexed-read
+     * 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>;
+    /** Concise callback/lambda returns promoted by the HOF callback prepass;
+     * arrows have no declaration symbol to key in fnSigsBySymbol. */
+    readonly runtimeOptionalFunctionReturns: WeakMap<ts.Node, IrType>;
+    /** Arithmetic over an unchecked string read can answer either NaN or a
+     * string. Bindings and returns use this marker to retain that result union
+     * through checker-bare string annotations. */
+    readonly runtimeOptionalArithmeticTypes: WeakMap<ts.Node, IrType>;
+    /** Record fields promoted to an undefined-armed union by an indexed-read
+     * value. The key is the concrete emitted shape and field name. */
+    readonly runtimeOptionalFields: Set<string>;
+    /** Callback pattern parameters carry an optional source without making
+     * every name destructured from a present source optional. */
+    readonly runtimeOptionalPatternTypes: WeakMap<ts.Node, IrType>;
+    readonly runtimeOptionalReduceTypes: WeakMap<ts.CallExpression, IrType>;
     /** 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>;
     runtimeOptionalRootOf(local: IrLocal): IrLocal;
+    runtimeOptionalBindingType(node: ts.Node): IrType | null;
+    runtimeOptionalBindingType(node: ts.Node, fallback: IrType): IrType;
+    runtimeOptionalIdentifierValue(node: ts.Expression): {
+        value: IrExpr;
+        present: IrType;
+        unionId: string;
+    } | null;
+    /** Recover the original optional union when a checked single-arm helper
+     * was installed before a strict property consumer could name its member.
+     * Recovery is limited to array element reads and storage roots marked by
+     * the optional-read analysis, so ordinary assertions keep their generic
+     * checked-narrow behavior. */
+    runtimeOptionalSourceValue(node: ts.Expression, value: IrExpr): IrExpr | null;
+    /** A strict property or method receiver over an array-derived optional
+     * value. Reuse a plain read directly or stabilize an effectful receiver
+     * once, throw Node's member-read TypeError for a unit arm, and extract the
+     * expected present arm otherwise. */
+    runtimeOptionalPropertyReceiver(node: ts.Expression, value: IrExpr, expected: IrType, member: string): IrExpr | null;
+    runtimeOptionalFieldKey(shapeId: string, field: string): string;
+    isRuntimeOptionalField(shapeId: string, field: string): boolean;
+    isRuntimeOptionalGlobal(global: IrGlobal): boolean;
+    isRuntimeOptionalArithmeticGlobal(global: IrGlobal): boolean;
+    /** The union produced when an unchecked array read reaches a typed slot
+     * whose checker type is the corresponding bare arm. */
+    runtimeOptionalWidening(actual: IrType, expected: IrType): IrType | null;
+    runtimeOptionalType(t: IrType): IrType;
+    promoteRuntimeOptionalParameter(node: ts.Node, type: IrType): IrType;
+    promoteRuntimeOptionalFunctionReturn(node: ts.Node, type: IrType): IrType;
+    runtimeOptionalFunctionReturnType(node: ts.Node, fallback: IrType): IrType;
+    /** 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. */
+    runtimeOptionalRecordField(type: IrType, field: string, fieldType: IrType): IrType;
     /** Runs `fn` with the given aliased-typeof narrows applied (and restored
      * after) — the branch-scoping primitive. */
     narrowingAliases<T>(narrows: readonly {
@@ -592,6 +648,10 @@ export declare class Lowerer {
         };
     }>;
     readonly narrowHelpers: Map<string, string>;
+    /** Exact members of narrowHelpers produced by narrowedArmHelper. This
+     * lets property consumers recognize an earlier checked extraction by
+     * provenance instead of relying on its generated-name prefix. */
+    private readonly checkedNarrowHelpers;
     /** Interned `%iter.drain.<n>` helpers (classIteratorDrainCall): one per
      * receiver class — the eager drain of a class iterable's protocol into
      * a fresh element array, behind array/call spreads. */
@@ -722,11 +782,17 @@ export declare class Lowerer {
      * non-instantiated one (its only value members are import= aliases,
      * still resolved statically). Ambient blocks never register — their
      * members keep the ReferenceError/fence paths (lower-namespaces.ts). */
-    readonly nsBlocks: Map<ts.Node, "typeOnly" | "flattened">;
+    readonly nsBlocks: Map<ts.Node, "flattened" | "typeOnly">;
     /** File → its %init function name, filled by prepareModuleInits before
      * any body lowers: import headers and inline require statements call
      * dependency inits by these names. */
     readonly initNameOf: Map<ts.SourceFile, string>;
+    /** CommonJS module objects are scalar handles into the runtime registry.
+     * IDs are assigned in deterministic module order before any body lowers;
+     * the feature gate stays false for programs that never inspect the graph. */
+    readonly cjsModuleIdOf: Map<ts.SourceFile, number>;
+    readonly cjsModuleFiles: ts.SourceFile[];
+    cjsModuleGraphEnabled: boolean;
     /** File → the id of its run-once guard global (a bool module global,
      * false at program start). Every non-entry module gets one: its %init
      * may be called from several importers/requirers, and the guard is what
@@ -924,8 +990,8 @@ export declare class Lowerer {
      * references never call this helper and remain ordinary checker input. */
     externalTypeSpecifierOf(expr: ts.Expression): string | null;
     /** The source file a checker-resolved module-specifier node names. The
-     * checker path covers package.json aliases as well as relative imports;
-     * resolveImport is the fallback for the latter. */
+     * checker path is preferred; resolveImport is the canonical fallback for
+     * every project-module spelling. */
     private moduleSourceFileOf;
     /** Follow one project-module export through the checker's resolved export
      * table, then recover its exact external route where alias declarations
@@ -966,10 +1032,10 @@ export declare class Lowerer {
      * machinery. */
     private cjsDefaultImportDepOf;
     /** True when `expr` is an identifier bound by a top-level
-     * `const x = require("./local")` of a RELATIVE module — the CommonJS
-     * namespace binding — or of a bare specifier naming an opted-in
-     * --npm-static package (its CJS entry is a program module, so the
-     * binding is the same namespace over the same export table), or by a
+     * `const x = require("./local")` of a project module — relative,
+     * tsconfig-aliased, or package.json-mediated — or of a bare specifier
+     * naming an opted-in --npm-static package (its CJS entry is a program
+     * module, so the binding is the same namespace over the same export table), or by a
      * DEFAULT import of a CommonJS JS module (`import d from "./lib.cjs"`:
      * Node binds d to module.exports, the same value require answers).
      * Member accesses on it resolve through the export table (property
@@ -1006,6 +1072,12 @@ export declare class Lowerer {
     wantBody(name: string): boolean;
     collectNpmImports(parts: FileParts[]): void;
     collectJsonImports(parts: FileParts[]): void;
+    /** Discover the unchecked-array values that cross static ABI/storage
+     * boundaries before any function body or module initializer is emitted.
+     * TypeScript's default indexed-access type is a useful source annotation,
+     * but it is not a runtime proof; promoting only the affected slots keeps
+     * the rest of the dense ABI unchanged. */
+    analyzeRuntimeOptionalArrayReads(parts: FileParts[]): void;
     run(): LowerResult;
     /** Final retention, pruning, and module assembly shared by ordinary emit
      * and the retained reachability worklist. */
@@ -1142,9 +1214,10 @@ export declare class Lowerer {
      * isArrayValueType so Array.isArray's predicate and its narrowing bridge
      * cannot disagree about fixed tuple arms. */
     arrayValueTags(unionId: string): number[];
-    /** isJsonSafeType with this Lowerer's registries — the shared fence for
-     * what JSON.stringify accepts and what a checked cast can validate. */
+    /** Checked JSON conversion excludes undefined array slots because JSON
+     * text cannot preserve that distinction. */
     jsonSafe(t: IrType): boolean;
+    jsonStringifySafe(t: IrType): boolean;
     /** True when a type is a BARE undefined-armed union — the one JSON-unsafe
      * shape whose rejections deserve their own wording: Node's stringify of
      * bare undefined is not a string at all and JSON text never matches the
@@ -1898,12 +1971,9 @@ export declare class Lowerer {
     rejectUnresolved(ident: ts.Identifier, fallback: string): never;
     rejectUnresolvedSymbol(symbol: ts.Symbol | null, name: string, node: ts.Node, fallback: string): never;
     lowerScopedBlock(stmt: ts.Statement): IrStmt[];
-    /** Lowers inside a control-construct marker (loop/switch/labeled block/
-     * try-with-finally/finally block) so the jump fences below know what a
-     * break/continue/return crosses. `labels` carries the construct's JS
-     * label names when the source statement was labeled — labeled jumps
-     * resolve against them. */
-    inCtl<T>(kind: "loop" | "switch" | "block" | "tryFinally" | "finallyBlock", fn: () => T, labels?: string[]): T;
+    /** Lowers inside a jump-target marker. `labels` carries the construct's
+     * source label names so labeled jumps resolve against them. */
+    inCtl<T>(kind: "loop" | "switch" | "block", fn: () => T, labels?: string[]): T;
     /** The label names a `lbl:` chain put on the statement currently being
      * lowered — set by lowerLabeled around lowering the labeled construct,
      * consumed exactly once by the construct's own lowering (takeLabels).
@@ -1911,7 +1981,6 @@ export declare class Lowerer {
      * silently dropping a label would compile `break lbl` wrong. */
     pendingLabels: string[] | null;
     takeLabels(): string[] | undefined;
-    rejectJumpCrossingFinally(kw: "break" | "continue" | "return", stmt: ts.Statement, label?: string): void;
     lowerStmt(stmt: ts.Statement): IrStmt | IrStmt[] | null;
     lowerVarStatement(stmt: ts.VariableStatement): IrStmt[];
     lowerDestructuringDecl(decl: ts.VariableDeclaration, isLet: boolean): IrStmt[];
@@ -1981,6 +2050,8 @@ export declare class Lowerer {
     caughtLocalOf(node: ts.Expression): IrLocal | null;
     caughtToString(node: ts.Expression): IrExpr | null;
     lowerInstanceOf(expr: ts.BinaryExpression, loc: SrcLoc): IrExpr;
+    private withRuntimeOptionalClassValue;
+    private withExpressionOverride;
     lowerCall(expr: ts.CallExpression): IrExpr;
     isTopLevelFnSymbol(ident: ts.Identifier): boolean;
     lowerNestedFunctionDecl(stmt: ts.FunctionDeclaration): IrStmt;
@@ -2083,6 +2154,10 @@ export declare class Lowerer {
         module: string;
         member: string;
     }, fn: BuiltinModuleFn, loc: SrcLoc): IrExpr;
+    lowerTimersPromisesSetInterval(expr: ts.CallExpression, bi: {
+        module: string;
+        member: string;
+    }, loc: SrcLoc): IrExpr | null;
     lowerFsToUnixTimestampCall(expr: ts.CallExpression, bi: {
         module: string;
         member: string;