@scriptc/compiler 0.2.4 → 0.2.6

package/dist/frontend/lowering/generic-functions.d.ts

@@ -0,0 +1,271 @@
+import * as ts from "../ts7/adapter.js";
+import type { Lowerer } from "./lowerer.js";
+import { type IrExpr, type IrFunction, type IrType } from "../../ir/ir.js";
+import { type ClassInfo } from "./lower-classes.js";
+import { type ParamShape } from "./call-signatures.js";
+import { type InstantiationPath } from "./instantiation-path.js";
+/** A generic function-like declaration, collected instead of an FnSig —
+ * top-level generic function declarations, class GENERIC METHODS (own type
+ * parameters, instance and static), and object-literal generic methods.
+ * The body is NOT lowered at collection: each call site's checker-resolved
+ * signature (type arguments substituted) becomes an instantiation key, and
+ * the body is lowered once per distinct key (monomorphization). */
+export interface GenericFnInfo {
+    decl: ts.FunctionDeclaration | ts.MethodDeclaration | ts.FunctionExpression | ts.ArrowFunction;
+    /** Unqualified source name, for diagnostics. */
+    baseName: string;
+    /** Program-wide qualified name; instance `n` is named `<qualified>%<n>`
+     * ('%' cannot appear in a TS identifier, so instance names can never
+     * collide with user functions). */
+    qualifiedName: string;
+    /** Declaration-order type parameter symbols. */
+    typeParams: ts.Symbol[];
+    /** Lazily computed (keyofConstrainedTypeParams): the type parameters
+     * declared `K extends keyof …`. Their bound LITERAL keys are semantic —
+     * the body's `o[k]` reads the named field — so instances key on the
+     * literal (no cross-literal sharing) and keep the checker types
+     * (tsBindings) the body resolves through. */
+    keyofTps?: Set<ts.Symbol>;
+    /** Instantiation key (comma-joined typeKeys of the mapped param types +
+     * `=>` + return typeKey) → instance. Key identity IS signature identity:
+     * two call sites whose inferred types map to the same IR types share one
+     * native function. */
+    instances: Map<string, GenericInstance>;
+    /** CLASS-member generic methods: the declaring ClassInfo and flavor.
+     * Instance methods take `this` (object:<declarer>) as param 0 and lower
+     * under the declarer's instantiation bindings (generic-class receivers)
+     * MERGED with the method instantiation's own; statics lower as plain
+     * module functions with an exact receiver or the this/super fence. Absent for
+     * top-level functions and object-literal methods. */
+    member?: {
+        cls: ClassInfo;
+        kind: "method" | "static";
+    };
+    /** Direct static calls specialize lexical this for the proven receiver. */
+    staticReceiver?: ClassInfo;
+    receiverSpecializations?: Map<string, GenericFnInfo>;
+    /** Object-literal generic methods (`{ m<T>(x: T) {...} }` and generic
+     * arrow/function-expression properties): lowered as plain module
+     * functions — `this` inside is fenced (rejectThisInObjectMethod) and the
+     * defining literal must sit at module scope (no enclosing frame to
+     * capture). */
+    objectLiteral?: true;
+    /** IMPLICIT-ANY monomorphization (npm-static JS): parallel to
+     * decl.parameters — the param's own symbol when the slot is a BINDABLE
+     * implicit-any parameter (untyped, identifier-named, never written in
+     * the body), null for typed or unbindable slots. Present ⇔ this info
+     * monomorphizes over its implicit-any params instead of declared type
+     * parameters (typeParams stays empty): each call site's WIDENED argument
+     * checker types key an instantiation, exactly the generic machinery —
+     * the untyped params ARE the type parameters (see implicitCallInstance). */
+    implicitParams?: (ts.Symbol | null)[];
+}
+export interface GenericInstance {
+    path: InstantiationPath;
+    name: string;
+    /** 0 for the first instance of a base function — the only one whose
+     * statements count toward coverage stats (re-instantiations re-visit the
+     * same source lines). */
+    ordinal: number;
+    params: ParamShape[];
+    returnType: IrType;
+    /** Type-parameter symbol → concrete IR type, consulted by mapType (via
+     * typeParamResolver) while the instance body lowers. */
+    bindings: Map<ts.Symbol, IrType>;
+    /** Call-keyed instances: type-parameter symbol → the bound CHECKER type
+     * (pre-widening), consulted while the body lowers where the IrType
+     * binding has already lost what the body needs — `T[K]` and `o[k]` reads
+     * whose K is bound to one literal key (typeParamTsBindings). */
+    tsBindings?: Map<ts.Symbol, ts.Type>;
+    /** Rendered type arguments ("<number, string>") for diagnostics. */
+    typeArgsText: string;
+    /** Implicit instances only: param symbol → the call site's (widened)
+     * checker type, consulted by the Lowerer's typeOf while this instance's
+     * body lowers (the implicit twin of `bindings`). */
+    implicitArgTypes?: Map<ts.Symbol, ts.Type>;
+    /** Implicit instances only: eager-lowering lifecycle. "lowering" while
+     * the body builds (a re-demand is same-key recursion: the caller uses
+     * the PINNED fallback returnType and returnPinned locks it); "done" once
+     * returnType holds the inferred (or pinned) truth. */
+    implicitState?: "lowering" | "done" | "failed";
+    /** Same-key recursion observed the fallback return type mid-lowering, so
+     * the ABI is locked to it — the return post-pass coerces every return
+     * value to the pinned type instead of adopting the inferred one. */
+    returnPinned?: boolean;
+    /** Implicit instances only: the declared return did not map (the
+     * any-params poisoned it) — the body lowers in return-INFERENCE mode
+     * (returnType holds the DYN recursion pin until the post-pass settles). */
+    implicitInferReturn?: true;
+}
+/** Registers a top-level generic function. Only the SYNTAX is checked
+ * here — parameter/return types mention the type parameters and cannot
+ * map yet; the body is lowered per instantiation, on demand (an unused
+ * generic function requires no body lowering). Called inside
+ * collectSignature's poison catch. */
+export declare function collectGenericSignature(lowerer: Lowerer, decl: ts.FunctionDeclaration): void;
+export declare function genericFnOf(lowerer: Lowerer, ident: ts.Identifier): GenericFnInfo | null;
+/** Call of a generic top-level function. The checker already inferred (or
+ * was told, via explicit type arguments) the concrete signature —
+ * getResolvedSignature returns it with type arguments substituted. The
+ * mapped param+return IR types form the INSTANTIATION KEY; the first call
+ * with a new key queues the body for monomorphic lowering as
+ * `<qualifiedName>%<n>`, and every call lowers to a direct `call` of that
+ * instance. */
+export declare function lowerGenericCall(lowerer: Lowerer, expr: ts.CallExpression, info: GenericFnInfo): IrExpr;
+/** The instance a CALL of a generic function-like names: resolved
+ * signature → mapped param shapes/return → interned instance. Shared by
+ * top-level generic calls, class generic-method calls (the caller
+ * prepends the receiver), and object-literal generic-method calls. */
+export declare function genericCallInstance(lowerer: Lowerer, expr: ts.CallExpression, info: GenericFnInfo): GenericInstance;
+/** Type-parameter symbol → concrete IR type for one instantiation.
+ * Explicit type arguments bind directly; the rest come from structurally
+ * matching each DECLARED param/return type (which mentions the type
+ * parameters) against the checker's INSTANTIATED one — the latter is the
+ * former with the substitution applied, so the shapes are parallel by
+ * construction. A type parameter left unbound only matters if the body
+ * mentions it, where mapType fails and badType names the shape
+ * (carrying the instantiation context). */
+export declare function inferTypeParamBindings(lowerer: Lowerer, expr: ts.CallExpression, info: GenericFnInfo, rsig: ts.Signature, tsBindings?: Map<ts.Symbol, ts.Type>): Map<ts.Symbol, IrType>;
+/** Lowers ONE monomorphic instance of a generic function: the same body
+ * AST, re-lowered with the type parameters bound (threaded into every
+ * mapType call via typeParamResolver — the checker keeps reporting the
+ * unsubstituted `T`s inside the body). Coverage stats count a base
+ * function's statements once: only the FIRST instance contributes. */
+export declare function lowerGenericInstance(lowerer: Lowerer, info: GenericFnInfo, inst: GenericInstance): IrFunction;
+/** A generic function taken as a VALUE, monomorphized by flow. A function
+ * value needs ONE concrete signature; tsc pins one at exactly two
+ * reference shapes — an instantiation EXPRESSION (`identity<number>`,
+ * whose own checker type is the substituted signature) and a reference
+ * whose CONTEXTUAL type completes the signature (`const f: (x: number) =>
+ * number = identity`, `take(identity)`). The declared signature unifies
+ * against the pinned one to recover the bindings; the instance then
+ * registers in the SAME table call sites use (one compiled copy per
+ * signature however it is reached), and the value is the instance's
+ * zero-capture closure — `f === f` holds within an instantiation, the
+ * declared-function identity rule. References with no pinning context
+ * (the slot keeps `<T>(x: T) => T`) fence by name. */
+export declare function lowerGenericFnValue(lowerer: Lowerer, ref: ts.Expression, info: GenericFnInfo): IrExpr;
+/** The npm-static gate: implicit-any monomorphization applies to functions
+ * DECLARED in an opted-in package's JS files (user JS keeps today's
+ * checked-dynamic story until the corpus is re-baselined). */
+export declare function implicitMonoFile(sf: ts.SourceFile): boolean;
+/** The implicit-type-parameter slots of a JS function-like: parallel to
+ * decl.parameters, the param SYMBOL where the slot is a bindable
+ * implicit param (identifier-named, broad inferred/JSDoc type, not
+ * rest/optional/defaulted, never written), null elsewhere. Package JS
+ * methods may also specialize class parameters: JSDoc names a nominal
+ * class even when the body accepts other objects with the same members.
+ * Null overall when nothing qualifies — the declaration keeps its ABI. */
+export declare function implicitAnyParamSymbolsOf(lowerer: Lowerer, decl: ts.FunctionDeclaration | ts.MethodDeclaration | ts.FunctionExpression | ts.ArrowFunction, classParams?: boolean): (ts.Symbol | null)[] | null;
+/** True when a `this.method(...)` call targets an implicit npm-static
+ * method whose result is settled from its lowered body rather than the
+ * checker declaration. Uninitialized-local inference uses this to avoid
+ * freezing an evolving `any` slot to stale JSDoc. */
+export declare function implicitMethodCallInfersReturn(lowerer: Lowerer, call: ts.CallExpression): boolean;
+/** The instance a CALL of an implicit-any function-like names: each
+ * bindable implicit param takes the call's WIDENED argument checker type
+ * when it maps statically (DYN otherwise — today's slot), typed params
+ * keep their declared shapes, and the param-type tuple is the
+ * instantiation key. New keys lower EAGERLY (return inference — see the
+ * section comment); a same-key re-demand mid-lowering pins the fallback
+ * return type. */
+export declare function implicitCallInstance(lowerer: Lowerer, call: ts.CallExpression, info: GenericFnInfo): GenericInstance;
+/** The all-dyn DEFAULT instance — today's compiled body exactly: what a
+ * VALUE reference of an implicit-any function names (indirect calls
+ * carry no per-site types to bind). */
+export declare function implicitDefaultInstance(lowerer: Lowerer, blame: ts.Node, info: GenericFnInfo): GenericInstance;
+/** The implicit-any twin of bindingGenericFnNodeOf, for LOCAL and module
+ * bindings alike (`const knownBy = (cmd) => [cmd.name()].concat(...)`
+ * inside a method body — commander's _registerCommand shape): the
+ * initializer function-like when the WHOLE declaration qualifies for
+ * implicit monomorphization, else null — non-qualifying shapes keep
+ * today's closure story silently (never a fence: the flag must not make
+ * working code worse). Qualification: an npm-static JS file, a const (or
+ * never-reassigned, never-redeclared) identifier binding, an
+ * arrow/function-expression initializer with bindable implicit-any
+ * params, and a body with NO captures — no `this`/`super`, and no
+ * reference to a function-scoped declaration outside itself (compiled
+ * instances are module functions; module-scope references are fine).
+ * Cached per declaration on lowerer.implicitLocalFns. */
+export declare function implicitLocalFnNodeOf(lowerer: Lowerer, decl: ts.VariableDeclaration): ts.FunctionExpression | ts.ArrowFunction | null;
+/** Registers (or returns) the GenericFnInfo of a qualifying implicit-any
+ * function-value binding — implicitLocalFnNodeOf's companion, the
+ * bindingGenericFnInfoOf shape: the info enters genericFnsBySymbol under
+ * the binding's symbol (and a named function expression's inner name),
+ * so calls and value references resolve through genericFnOf; the
+ * declaration statement emits nothing and the binding has no runtime
+ * value. The declaration's source position joins the qualified name —
+ * two same-named locals in one file stay distinct. */
+export declare function implicitLocalFnInfoOf(lowerer: Lowerer, decl: ts.VariableDeclaration, fnNode: ts.FunctionExpression | ts.ArrowFunction): GenericFnInfo;
+/** The function-like node behind an object-literal generic-method member:
+ * the MethodDeclaration itself (`{ m<T>(x: T) {...} }`) or a generic
+ * arrow/function-expression property's initializer (`{ m: <T>(x: T) =>
+ * ... }`). Null when the property's declaration isn't that shape. */
+export declare function objLitGenericFnNodeOf(lowerer: Lowerer, propSym: ts.Symbol): {
+    fnNode: ts.MethodDeclaration | ts.FunctionExpression | ts.ArrowFunction;
+    literal: ts.ObjectLiteralExpression;
+} | null;
+/** The interned GenericFnInfo for one object-literal generic method, with
+ * the supportability fences applied ONCE per declaration: the defining
+ * literal must sit at module scope (the compiled instance is a plain
+ * module function — an enclosing frame would need captures), and
+ * async/generator forms keep the method fences. The name is source-
+ * position-derived (`%ol<start>.<name>`, qualified per file) —
+ * deterministic across the discovery and emit passes. */
+export declare function objLitGenericFnInfoOf(lowerer: Lowerer, blame: ts.Node, name: string, found: {
+    fnNode: ts.MethodDeclaration | ts.FunctionExpression | ts.ArrowFunction;
+    literal: ts.ObjectLiteralExpression;
+}): GenericFnInfo;
+/** The generic function-like INITIALIZER behind a binding declaration —
+ * `const f = <T>(x: T) => x` or `const f = function g<T>(x: T) {...}`
+ * (parens stripped). Null when the declaration isn't that shape; the
+ * SHAPE only — whether the binding qualifies (module scope, never
+ * reassigned) is bindingGenericFnInfoOf's business. */
+export declare function bindingGenericFnNodeOf(decl: ts.VariableDeclaration): ts.FunctionExpression | ts.ArrowFunction | null;
+/** The CONTEXTUAL twin of bindingGenericFnNodeOf: `const g: Mapper = (x)
+ * => x` where `type Mapper = <T>(x: T) => T` — the initializer declares
+ * no type parameters of its own, but the ANNOTATION's one call signature
+ * does, and the checker types the arrow's parameters by those (`x: T`).
+ * Such a binding monomorphizes exactly like `const g = <T>(x: T) => x`;
+ * bindingGenericFnInfoOf reads the type parameters off the annotation's
+ * signature. Null when the shape doesn't match (a concrete annotation, a
+ * generic arrow — the syntactic probe's case, an overloaded alias). */
+export declare function bindingContextualGenericFnNodeOf(lowerer: Lowerer, decl: ts.VariableDeclaration): ts.FunctionExpression | ts.ArrowFunction | null;
+/** The interned GenericFnInfo for one generic arrow/function-expression
+ * binding initializer, with the supportability fences applied ONCE per
+ * declaration: the binding must sit at module scope (the compiled
+ * instances are plain module functions — an enclosing frame would need
+ * captures) and must provably HOLD the initializer once initialized — a
+ * const, or a let/var nothing in its declaring file ever writes (ESM
+ * import bindings are read-only, so the file scan is the whole story;
+ * observing the UNINITIALIZED state needs a hoisted early call, the
+ * same temporal hole const TDZ leaves — the object-literal generic-
+ * method receiver stance). Successful registration enters the info
+ * in genericFnsBySymbol under the binding's symbol — and under a named
+ * function expression's own inner name (it binds itself inside the
+ * body, the class-expression rule) — so every genericFnOf consumer
+ * (calls, pinned values, instantiation expressions, namespace and CJS
+ * member paths) resolves it like a top-level generic declaration. */
+export declare function bindingGenericFnInfoOf(lowerer: Lowerer, decl: ts.VariableDeclaration, fnNode: ts.FunctionExpression | ts.ArrowFunction): GenericFnInfo;
+/** `const h = id` — a binding ALIASING a generic function (a top-level
+ * declaration, a registered generic binding, or another alias — resolved
+ * left to right in declaration order). The alias registers the SAME info
+ * under its own symbol, so calls (`h(3)`) and pinned values (`take(h)`)
+ * resolve exactly like the target's own name, and the binding itself has
+ * no runtime value (a generic function value cannot materialize). Claims
+ * only bindings whose OWN type still keeps type parameters — a
+ * concrete-annotated alias (`const h: (x: number) => number = id`) is a
+ * pinned VALUE, the existing lowerGenericFnValue story. Null when the
+ * shape doesn't match or the target isn't a registered generic; fences
+ * (reassignment, var redeclaration) report by name inside. */
+export declare function bindingGenericFnAliasInfoOf(lowerer: Lowerer, decl: ts.VariableDeclaration): GenericFnInfo | null;
+/** Static resolution stands in for the receiver's runtime value, so an
+ * object-literal generic-method receiver must provably HOLD the defining
+ * literal: a direct read of a binding whose initializer IS that literal
+ * and that nothing ever reassigns — a const, or a let with no write in
+ * its declaring file (ESM import bindings are read-only, so the file
+ * scan is the whole story). The read is pure — call and value sites skip
+ * evaluating it entirely. A reassignable binding could hold a
+ * structurally identical literal with a DIFFERENT body, which static
+ * resolution would silently miss. */
+export declare function requireObjLitGenericReceiver(lowerer: Lowerer, blame: ts.Node, recvExpr: ts.Expression, literal: ts.ObjectLiteralExpression, name: string): void;