@scriptc/compiler 0.1.6 → 0.2.0

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

@@ -1,11 +1,29 @@
 import * as ts from "../ts7/adapter.js";
-import type { Lowerer } from "./lowerer.js";
-import { IrClassDef, IrExpr, IrFunction, IrLocal, IrStmt, IrType, SrcLoc } from "../../ir/ir.js";
+import type { FnCtx, Lowerer } from "./lowerer.js";
+import { type IrClassDef, type IrExpr, type IrFunction, type IrLocal, type IrStmt, type IrType, type SrcLoc } from "../../ir/ir.js";
 import { type GenericFnInfo, type ParamShape } from "./lower-calls.js";
+import { type ScrDiagnostic } from "../../diagnostics/diagnostic.js";
 import { type EmitOverrideRec } from "./lower-event-emitter.js";
 import { type MixinInstanceInfo } from "./lower-mixins.js";
+export declare function returnsOnlyThis(member: ts.MethodDeclaration): boolean;
+export declare function storedClassValueType(lowerer: Lowerer, expression: ts.Expression): IrType | null;
+export interface ClassMethodSignature {
+    params: ParamShape[];
+    ret: IrType;
+    abstract?: true;
+    async?: true;
+    gen?: NonNullable<IrFunction["generator"]>;
+}
 export interface ClassInfo {
     def: IrClassDef;
+    localPrototypeData?: true;
+    localClass?: {
+        context: FnCtx | null;
+        bodies: Map<string, IrFunction>;
+        captureSources: string[];
+        ready: boolean;
+        baseExpression?: ts.Expression;
+    };
     /** ALL fields visible on instances — the inherited ones included — for
      * receiver-side lookup (def.fields carries the layout order). */
     fields: Map<string, IrType>;
@@ -15,7 +33,12 @@ export interface ClassInfo {
     fieldOrder: {
         name: string;
         type: IrType;
-        initializer: ts.Expression | undefined; /** Redeclared INHERITED field: the initializer assigns the base slot at this position; no new slot (def.fields excludes it). */
+        initializer: ts.Expression | undefined;
+        /** A bare JS dyn field defines undefined at its declaration position,
+         * even if an earlier initializer or base constructor wrote the slot. */
+        undefinedInitializer?: SrcLoc;
+        /** Redeclared field: initialize the existing slot at this position;
+         * no new slot (def.fields excludes it). */
         redeclared?: true;
     }[];
     /** OWN declared methods only — inherited lookups walk the base chain
@@ -27,16 +50,12 @@ export interface ClassInfo {
      * inherited private name are fenced at collection, and tsc confines
      * every access site to the declaring class's body, so the base-chain
      * walk IS lexical resolution and privates never join vtables (JS's
-     * no-dynamic-dispatch semantics by construction). A `gen` entry is a
-     * #private GENERATOR method: the body is a generator IrFunction and
-     * calls enter through its gen-spawn wrapper. */
-    methods: Map<string, {
-        params: ParamShape[];
-        ret: IrType;
-        abstract?: true;
-        async?: true;
-        gen?: NonNullable<IrFunction["generator"]>;
-    }>;
+     * no-dynamic-dispatch semantics by construction). A `gen` entry has a
+     * generator body whose direct calls enter through its spawn wrapper. */
+    methods: Map<string, ClassMethodSignature>;
+    /** Own JS overrides whose signature cannot use the inherited ABI. The slot
+     * retains that ABI, but its implementation throws before executing. */
+    methodEntryFences?: Map<string, ScrDiagnostic>;
     /** OWN GENERIC instance methods (own type parameters — `m<T>(x: T)`),
      * monomorphized per call site like top-level generic functions: instance
      * `n` is the module function `%C.m%n` taking `this` as param 0. They
@@ -103,6 +122,13 @@ export interface ClassInfo {
      * (forwarding the completed ABI values; defaults apply in the base). */
     ctorParams: ParamShape[];
     base: ClassInfo | null;
+    /** A module class may inherit a compiled ordinary JS constructor. Its
+     * callable and prototype are captured when the class declaration runs. */
+    callableBase?: {
+        expression: ts.Expression;
+        constructorId: string;
+        prototypeId: string;
+    };
     /** DIRECT subclasses, filled as derived classes collect — the frontend's
      * side of whole-program devirtualization (overrideBelow). */
     subclasses: ClassInfo[];
@@ -129,17 +155,20 @@ export interface ClassInfo {
         globalId: string;
         readonly: boolean;
     }[];
+    /** Shared expando data added after a JS class declaration. */
+    staticDataHelper?: string;
     /** STATIC methods — ordinary module functions named `%C.static:m` (the
      * accessor-colon trick: no user identifier can spell it, and statics
      * never join vtables, so IrClassDef doesn't know them). `C.m(args)` is
      * a direct call; `const f = C.m` a zero-capture closure; calls through
      * class VALUES devirtualize when no strict descendant redeclares the
-     * member. `this`/`super` inside fence at lowering (JS binds `this` to
-     * the RECEIVER class — dynamic). Absent on builtin classes. */
+     * member. Receiver-dependent methods specialize for exact receivers;
+     * detached methods and `super` retain their fences. Absent on builtins. */
     staticMethods?: Map<string, {
         params: ParamShape[];
         ret: IrType;
         member: ts.MethodDeclaration;
+        receiverInfo?: GenericFnInfo;
     }>;
     /** `static { ... }` blocks, in declaration order. They are DECLARATION-TIME
      * CODE, not shape: JS runs each block once when the class statement
@@ -150,14 +179,15 @@ export interface ClassInfo {
      * constructor value — no value form here) fences at collection. Absent on
      * builtin classes and classes without blocks. */
     staticBlocks?: ts.ClassStaticBlockDeclaration[];
-    /** SYMBOL-KEYED fields (`this[kLimit] = v` where kLimit is a module-level
-     * `const k = Symbol(...)`): the key's unique-symbol identity is a
-     * compile-time constant, so each key resolves to an ORDINARY hidden slot
-     * in the static layout — no runtime symbol table exists. The map goes
-     * key-symbol → layout field name (`Symbol(limit)`, Node's inspect
-     * spelling); inherited entries are seeded from the base like `fields`.
+    /** SYMBOL-KEYED fields with stable module-level Symbol()/Symbol.for()
+     * keys: each identity resolves to an ordinary hidden slot in the static
+     * layout. Registry keys share one identity across declarations. The map
+     * goes key identity → reserved layout field name; inspect recovers the
+     * Symbol(limit) spelling. Inherited entries are seeded from the base.
      * Absent on builtin classes and classes with no symbol-keyed fields. */
     symbolFields?: Map<ts.Symbol, string>;
+    /** Stable symbol keys for computed instance methods. */
+    symbolMethods?: Map<ts.Symbol, string>;
     /** GENERIC class FAMILY (`class Box<T>` itself): the synthetic,
      * never-constructed ancestor every instantiation extends. It owns what
      * JS's one runtime `Box` owns — the statics (one storage location for
@@ -265,7 +295,7 @@ export interface GenericClassInfo {
         poisoned?: boolean;
     }>;
 }
-/** The builtin Error hierarchy (Error + TypeError/RangeError/SyntaxError)
+/** The builtin Error hierarchy
    * as eagerly-registered ClassInfos: mapType names them the moment a lib
    * Error type appears, so the infos must exist before any lowering. They
    * are runtime-provided — no decl, no lowerable bodies; `new`/super()/
@@ -364,7 +394,7 @@ mixin?: {
    * unmapped, the fenced-JS-class story. Null answers (unmappable type
    * arguments, the instance cap, an uncollected family) make the whole
    * reference unmappable — per-site diagnostics own the fence. */
-export declare function genericClassInstanceType(lowerer: Lowerer, decl: ts.ClassLikeDeclaration, ref: ts.Type): IrType | null;
+export declare function genericClassInstanceType(lowerer: Lowerer, decl: ts.ClassLikeDeclaration, ref: ts.Type, mapArgument?: (type: ts.Type) => IrType | null): IrType | null;
 /** The `%init` statements for one class's static readonly fields AND
    * static blocks, interleaved in member order — emitted at the class
    * statement's source position (see lowerFileInit's merge), exactly when
@@ -404,6 +434,7 @@ export declare function findStaticOn(lowerer: Lowerer, info: ClassInfo | null, n
         params: ParamShape[];
         ret: IrType;
         member: ts.MethodDeclaration;
+        receiverInfo?: GenericFnInfo;
     };
     field?: undefined;
 } | null;
@@ -433,6 +464,13 @@ export declare function classValueRef(lowerer: Lowerer, info: ClassInfo, blame:
    * which is what keeps newValue completion against C's one signature
    * sound for every value legally in the slot. */
 export declare function ctorAbiEquals(lowerer: Lowerer, sub: ClassInfo, sup: ClassInfo): boolean;
+/** Writable storage for an own static field named through its exact class.
+ * Inherited writes create a new subclass property in JS, so they must not
+ * update the declaring class's global. */
+export declare function staticFieldWriteTarget(lowerer: Lowerer, access: ts.PropertyAccessExpression): {
+    id: string;
+    type: IrType;
+} | null;
 /** `C.x` where C is a class declared in the program and x a static
    * member of its chain: field reads are the module global, static
    * methods become interned closures, and `.name` folds to the class's
@@ -440,18 +478,11 @@ export declare function ctorAbiEquals(lowerer: Lowerer, sub: ClassInfo, sup: Cla
    * fall through to the ordinary chain so the static fence or the
    * generic member rejection names the site. */
 export declare function lowerStaticFieldRead(lowerer: Lowerer, expr: ts.PropertyAccessExpression): IrExpr | null;
-/** A class EXPRESSION's ClassInfo: collection on first encounter (the
-   * declaration path over the shared ClassLikeDeclaration machinery, with
-   * NamedEvaluation supplying the runtime .name), idempotent per node —
-   * tryLowerExpression's speculative visits and the heritage recursion reuse the
-   * first collection. The honest v1 boundary is TOP-LEVEL evaluation
-   * positions only: each evaluation of a class expression in JS mints a
-   * DISTINCT class (fresh identity, fresh statics), and one immortal
-   * class object is exact only for expressions that evaluate exactly
-   * once. Statics-bearing expressions additionally restrict to positions
-   * where "immediately before the enclosing statement" IS the evaluation
-   * point (lowerFileInit drains pendingClassExprInits there). */
-export declare function lowerClassExpressionInfo(lowerer: Lowerer, expr: ts.ClassExpression): ClassInfo;
+/** Collect a class expression once per enclosing specialization. Function-local
+ * evaluations allocate fresh constructor objects; top-level expressions use
+ * immortal templates. Static initialization remains limited to whole top-level
+ * initializers, where pendingClassExprInits preserves its evaluation point. */
+export declare function lowerClassExpressionInfo(lowerer: Lowerer, expr: ts.ClassLikeDeclaration): ClassInfo;
 /** `class {…}` in expression position: a class definition bound to no
    * statement — once the static side is a value, the expression IS the
    * definition plus a classRef over it. A DECORATED class expression
@@ -460,7 +491,7 @@ export declare function lowerClassExpressionInfo(lowerer: Lowerer, expr: ts.Clas
    * ReferenceError, so it lowers to exactly that read — every evaluation
    * throws identically, which is why the once-evaluated restriction and
    * the member fences don't apply. */
-export declare function lowerClassExpression(lowerer: Lowerer, expr: ts.ClassExpression): IrExpr;
+export declare function lowerClassExpression(lowerer: Lowerer, expr: ts.ClassLikeDeclaration): IrExpr;
 /** The EXACT class a receiver expression is statically known to BE (not
    * merely be typed by): the class name itself, or a `const` binding
    * whose initializer is a class expression / class name. Such receivers
@@ -532,6 +563,16 @@ export declare function findGenericMethodOn(lowerer: Lowerer, info: ClassInfo |
     declarer: ClassInfo;
     info: GenericFnInfo;
 } | null;
+/** True when some STRICT descendant of `info` re-declares the generic
+   * method `name` — overrideBelow's twin: generic methods have no vtable
+   * slot, so a call that could reach an override compiles only when the
+   * receiver's runtime class is statically exact. */
+export declare function genericOverrideBelow(lowerer: Lowerer, info: ClassInfo, name: string): boolean;
+/** Discover overrides before choosing inferred method ABIs. Class collection
+ * visits bases first, including imported bases and class expressions, so the
+ * collected subclass graph cannot answer this question yet. The checker
+ * hierarchy identifies the original declarations through aliases as well. */
+export declare function collectVirtualJsMethods(lowerer: Lowerer, files: readonly ts.SourceFile[]): void;
 /** The receiver's EXACT runtime class, when the expression proves it: a
    * `new C(...)` expression directly, or a const binding initialized with
    * one (the binding can never be reassigned to a subclass instance).
@@ -688,19 +729,16 @@ export declare function lowerSuperAccessorRead(lowerer: Lowerer, access: ts.Prop
 export declare function lowerSuperAccessorWrite(lowerer: Lowerer, access: ts.PropertyAccessExpression, rhs: ts.Expression, loc: SrcLoc): IrStmt;
 /** True when `info`'s EFFECTIVE constructor — its own, or the one
    * inherited through ctor-less bases — is a builtin error class's. Such
-   * classes construct with the error message rule, and their synthesized
-   * constructors forward one plain string to error.ctor. */
+   * classes construct with the error argument rule, and their synthesized
+   * constructors forward both checked-dynamic values to error.ctorOptions. */
 export declare function inheritsBuiltinErrorCtor(lowerer: Lowerer, info: ClassInfo): boolean;
 /** The EventEmitter twin: a ctor-less chain into the emitter base
    * inherits `new C()` — zero arguments (the options bag fences). */
 export declare function inheritsBuiltinEmitterCtor(lowerer: Lowerer, info: ClassInfo): boolean;
-/** `new C(args)` for a class declared in the program (imports resolve
-   * through aliases, so cross-module classes construct too). */
-/** The single message argument of a builtin Error construction or
- * super() call: "" when omitted or explicitly undefined (Node's message
- * property default), the string otherwise. The lib signature's second
- * parameter (options/cause) has no lowering. */
-export declare function errorMessageArg(lowerer: Lowerer, args: readonly ts.Expression[], loc: SrcLoc, blame: ts.Node): IrExpr;
+/** Preserve argument evaluation order and option presence through builtin
+ * and inherited Error constructors. Checked-dynamic conversion retains
+ * Error identity and distinguishes a missing cause from undefined. */
+export declare function errorConstructorArgs(lowerer: Lowerer, args: readonly ts.Expression[], loc: SrcLoc, blame: ts.Node): IrExpr[];
 export declare function lowerNew(lowerer: Lowerer, expr: ts.NewExpression): IrExpr;
 /** A getter/setter invocation over an accessor target's receiver — the
    * same whole-program devirtualization as method calls: a virtualCall