@geastack/compiler 1.0.15

package/dist/semantics/normalize/structural-declarations.d.ts

@@ -0,0 +1,395 @@
+import ts from 'typescript';
+import type { DeclarationId } from '../../identity/ids.js';
+import type { StructuralAccessor } from '../model/structural-types.js';
+import { type ParameterBindingCensus } from './parameter-bindings.js';
+import { type ProgramReachability } from './reachability.js';
+/**
+ * The type of the value a declaration binds, asked of the declaration's own
+ * name rather than of the declaration node.
+ *
+ * The two differ, and the difference is the point: a node's type at its own
+ * position can be the *declared* type of the thing being defined, while the
+ * symbol its name introduces carries what a reader of that name receives. For
+ * a method those coincide; for anything whose name is introduced by a
+ * declaration the checker treats specially they do not, and the name is the
+ * authority on what the binding holds. A class is the motivating case: the
+ * checker's own type AT a class declaration node is its *instance* type, and
+ * only asking after the class's own name symbol recovers the constructor.
+ *
+ * A function expression or arrow function is excluded from that: for both,
+ * `ts.getNameOfDeclaration` never reads the node's own name (a *named*
+ * function expression's name included) and instead always defers to
+ * `getAssignedName`, which walks up to whatever the value is being stored
+ * into -- a variable declarator, a property assignment, a binding element --
+ * and answers with THAT construct's own declared type. For
+ * `activeRecorder.ondataavailable = (event) => {}` this resolves to the
+ * property's declared `Handler | null`, not the arrow's own
+ * `(event: Event) => void`. Handing that union back as a *callable
+ * allocation's* own shape is the same defect `accessorSignatureOf`'s doc
+ * comment already names for accessors ("reading the property's type there
+ * hands the callable carrier a scalar"): one call to
+ * `OrdinaryFunctionCreate`/`InstantiateArrowFunctionExpression` allocates a
+ * plain callable independent of wherever it is later stored, and an optional
+ * or nullable wrapper is a fact about that later BINDING, never about this
+ * value -- so it must not reach `allocations.ts`'s `shape` field for the
+ * allocation itself. A method or a plain function declaration never takes
+ * this path: `getNameOfDeclaration` reads their OWN name directly, so no
+ * assignment target's type can substitute for theirs.
+ *
+ * `null` when the declaration introduces no name the checker resolves to a
+ * symbol, which is the caller's cue to fall back to the node's own type --
+ * exactly what a function expression or arrow function now always does.
+ */
+export declare const declaredValueTypeOf: (checker: ts.TypeChecker, node: ts.Declaration) => ts.Type | null;
+/**
+ * The type of the FUNCTION LITERAL a declaration is initialized with, when the
+ * declaration's own annotation is an overload set and the literal is not.
+ *
+ * `class Context { json: JSONRespond = (object, arg?, headers?) => {...} }`
+ * (hono's `context.ts`) is the shape. `JSONRespond` declares two call
+ * signatures differing at a shared parameter -- `status?: U` in one,
+ * `init?: ResponseOrInit<U>` in the other -- so `sharedAbiOf` (derive.ts)
+ * rightly finds no single convention and `widestSubsumingAbi` (host-abi.ts)
+ * rightly declines to widen, since that only forgives a TRAILING-optional
+ * difference and not a differing type at a shared position. The member then
+ * carries `unresolved(no primitive joining 2 overload signatures into one
+ * calling convention)`.
+ *
+ * But nothing with two conventions is ever allocated here. A function or arrow
+ * LITERAL cannot itself be overloaded -- only a `function` declaration merges
+ * that way -- so the checker types this initializer as exactly one signature,
+ * whose second parameter is the union `U | ResponseOrInit<U>` the body already
+ * discriminates on at runtime (`typeof arg === 'number' ? ...`). One physical
+ * convention, which this backend does model.
+ *
+ * This is `declaredValueTypeOf`'s own rule one level out. That function already
+ * refuses to let a storage slot's declared type reach a callable ALLOCATION's
+ * shape, for the reason its comment gives: the allocation is independent of
+ * wherever the value is later stored. The same is true of a member whose
+ * initializer is that allocation -- so the member's physical type is the
+ * literal's, not the annotation's.
+ *
+ * Sound because the checker has already proved the literal assignable to every
+ * declared overload; that is what let the program typecheck at all. This reads
+ * back the concrete answer the checker computed for the literal rather than
+ * inventing one. `null` whenever either half of the premise fails -- no
+ * function-literal initializer, or a declared type that was never an overload
+ * set -- so nothing that already resolves is re-derived.
+ */
+/**
+ * The single physical type of a node that DECLARES a binding annotated with an
+ * overloaded type, or `null` when the node is not one.
+ *
+ * `physicalInitializerTypeOf` asks this of a declaration whose type is already
+ * in hand; this is the same question asked of a bare node, which is what
+ * `structural.ts`'s `typeAt` has -- the BINDING's own type, as opposed to the
+ * ALLOCATION's, which `valueTypeAt` answers from the initializer directly. Both
+ * have to agree: hono's `export const parseBody: ParseBody = async (...)`
+ * allocated one async arrow and bound it under `ParseBody`'s two overloads, so
+ * the value had one convention and the name it is read through had none.
+ */
+export declare const physicalOverloadTypeAt: (checker: ts.TypeChecker, node: ts.Node, parameters?: ParameterBindingCensus) => ts.Type | null;
+export declare const physicalInitializerTypeOf: (checker: ts.TypeChecker, declaration: ts.Declaration, declared: ts.Type, parameters?: ParameterBindingCensus) => ts.Type | null;
+/**
+ * The type a `new String(x)` allocation actually has, when a declaration or a
+ * same-module reference to it is annotated with something else.
+ *
+ * hono's `utils/html.ts`: `const escapedString = new String(value) as
+ * HtmlEscapedString`. The declared/annotated type is `HtmlEscapedString =
+ * string & HtmlEscaped`, which `deriveIntersection` (representation/derive.ts)
+ * deliberately collapses to plain `string` -- correct for the alias in
+ * general, and wrong for the one value this expression actually allocates: a
+ * String WRAPPER OBJECT with identity, not a primitive. `as` changes only the
+ * STATIC view a reader gets; it does not change what `new String(...)`
+ * constructs at runtime.
+ *
+ * `physicalInitializerTypeOf`'s exact shape one level over: that function
+ * recovers the one convention a function LITERAL actually has past an
+ * overloaded annotation; this recovers the one OBJECT a `new String(...)`
+ * expression actually allocates past a widened/cast annotation. Both exist
+ * because the checker's type at the BINDING can legitimately differ from the
+ * type of the value physically stored there, and both must be asked
+ * uniformly at every site that reads the binding back, not only at its
+ * declaration -- `structural.ts`'s `typeAt` is exactly that uniform point,
+ * for the same reason it already calls `physicalOverloadTypeAt` there. A
+ * held cell and every read of it must agree, or a store/read pair would
+ * disagree about the binding's own carrier for no reason the program stated.
+ *
+ * Deliberately narrow, for the identical blast-radius reason
+ * `physicalInitializerTypeOf`'s own comment gives for its narrower cases: this
+ * does not see through an arbitrary `as`-cast pattern. It fires only when the
+ * unwrapped initializer is itself a `new` expression whose resolved type's
+ * symbol is literally named `String`, declared ambiently. `Number`/`Boolean`/
+ * every other constructor is untouched.
+ *
+ * A same-module IDENTIFIER reference reaches the same answer by walking to
+ * its declaring `VariableDeclaration`, gated to `const` only.
+ */
+export declare const physicalStringObjectTypeAt: (checker: ts.TypeChecker, node: ts.Node, parameters?: ParameterBindingCensus) => ts.Type | null;
+/**
+ * The signature a get/set accessor declaration implements, or `null` for a node
+ * that is not one.
+ *
+ * An accessor's name symbol is the *property* it implements, so its type is
+ * that property's -- `number` for `get value(): number`. What is allocated at
+ * an accessor declaration is the accessor function, whose type is its own
+ * signature. Reading the property's type there hands the callable carrier a
+ * scalar, and a call through it then has no convention to select at all.
+ */
+export declare const accessorSignatureOf: (checker: ts.TypeChecker, node: ts.Declaration) => ts.Signature | null;
+/**
+ * The field a get/set accessor PAIR does nothing but forward to, when both
+ * halves are exactly one statement long and agree on the identical access --
+ * `get image() { return this.source.data }` / `set image(value) {
+ * this.source.data = value }` (three's `Texture`) is the motivating shape.
+ * `null` for anything that is not provably this exact shape.
+ *
+ * This states only the SYNTACTIC fact: which access both bodies name, and
+ * that the setter's whole right-hand side is its own parameter untouched --
+ * nothing here asks whether the target the access names is itself a plain
+ * field, whether it even exists, or whether some sibling class overrides
+ * either half differently. Those are per-owner, per-family questions that
+ * need the checker and the class family's own closure, and belong beside the
+ * caller that already asks them one owner at a time --
+ * `accessorPassthroughDataMemberOf` (`flow/source-class-data.ts`), next to
+ * `isSourceDataDeclaration`, which this function's result is deliberately
+ * NOT allowed to bypass: a target that is itself an accessor still refuses.
+ *
+ * Deliberately narrow, for the same reason `physicalStringObjectTypeAt` above
+ * gives: guessing at a looser shape (a body with an early return, a
+ * multi-statement setter, a right-hand side that merely INCLUDES the
+ * parameter) risks calling something a passthrough that quietly does more,
+ * which would make a read of the alias silently skip real behavior.
+ */
+export declare const accessorPassthroughAliasOf: (getter: ts.GetAccessorDeclaration, setter: ts.SetAccessorDeclaration) => {
+    readonly receiverField: string | null;
+    readonly key: string;
+} | null;
+/**
+ * The MEMBER a passthrough accessor pair forwards to -- the storage half of
+ * the syntactic fact `accessorPassthroughAliasOf` states.
+ *
+ * three's `Texture` writes `get image() { return this.source.data }` and the
+ * matching setter, and annotates the GETTER `@type {?Object}`. That annotation
+ * is an upper bound on what may be read back, never a statement about what the
+ * slot holds -- the slot IS `Source.data`, and nothing else can be. But
+ * `Object | null` is not `any`/`void`/`never`, so every authority gated on
+ * `isUnusableEvidence` treats it as a final answer and never asks the census
+ * that knows better. `Texture.image` is read dozens of times across
+ * `WebGLTextures.js` alone, and each read boxed.
+ *
+ * The receiver type is taken from the getter's OWN access node rather than
+ * rebuilt from the owning class's symbol: the node is what the program
+ * actually wrote, the checker already types it in its real lexical position,
+ * and reconstructing an instance type from a class declaration would answer a
+ * different question for a constructor function or a class expression.
+ *
+ * Fails closed on a target that is itself an accessor. Forwarding to a second
+ * accessor is not storage -- it is another body that may do anything -- and
+ * admitting it is how a passthrough proof turns into a chain of guesses.
+ */
+export declare const accessorPassthroughMemberTargetOf: (checker: ts.TypeChecker, symbol: ts.Symbol) => {
+    readonly symbol: ts.Symbol;
+    readonly declaration: ts.Declaration;
+} | null;
+/**
+ * The one signature an OVERLOADED function or method's implementation
+ * declares, or `null` when the node is not an overload set's implementation.
+ *
+ * `class HonoRequest { param(key: string): string; param(): Record<...>;
+ * param(key?: string): unknown { ... } }` (hono's `request.ts`) is the shape,
+ * and it is `physicalInitializerTypeOf`'s twin at TypeScript's other spelling
+ * of the same thing. Asked through the symbol, the type is every OVERLOAD
+ * signature and never the implementation's -- that is the checker's rule, and
+ * it is right for call resolution -- so `sharedAbiOf` (derive.ts) sees N
+ * conventions and refuses. But the implementation is the only body that ever
+ * runs, and it declares exactly one; N is a fact about how the method may be
+ * CALLED, never about the single function that exists.
+ *
+ * `accessorSignatureOf` above already reaches past the symbol for the same
+ * class of reason (an accessor's name symbol is the property, not the
+ * function), and this asks the checker the identical way -- from the
+ * declaration node rather than the symbol.
+ *
+ * Resolve the body's declaration from the symbol: a call-site value declaration
+ * can be the first overload, which has no body of its own. The same function
+ * object still implements the symbol's one body.
+ *
+ * ⚠ A second DECLARATION is not a second overload. TypeScript's JS expando
+ * inference makes `SourceNode.fromStringWithSourceMap = function ...` a
+ * declaration of the `SourceNode` SYMBOL, so a pre-class constructor function
+ * with any static on it has two declarations and no overloads at all. Reading
+ * the signature off its body then returns the CALL signature alone and throws
+ * away the construct signature TS's JS inference attached to the symbol -- the
+ * declaration's cell became `function-value-dispatch` while every reference
+ * stayed `function-and-constructor`, which is 96 rows of tsc's self-compile
+ * concentrated in the `source-map` packages, and a two-authorities defect of
+ * exactly the kind this compiler exists to avoid. So the set is recognized by
+ * an actual overload being present: a method/function declaration with NO
+ * body, which is the only thing an overload signature can be.
+ */
+export declare const implementationSignatureOf: (checker: ts.TypeChecker, node: ts.Declaration) => ts.Signature | null;
+/**
+ * The signature a `?`-marked class METHOD implements, when it has a real
+ * body -- or `null` when the node is not one.
+ *
+ * `bar?(): string { ... }` inside a class is not a member that may or may
+ * not be defined: `DefineMethod` runs unconditionally during
+ * `ClassDefinitionEvaluation`, so the method exists on every instance the
+ * moment the class is instantiated. The `?` states a fact about READING
+ * `bar` through a structural interface that does not require it -- a
+ * caller who only knows the interface may see `undefined` -- never a fact
+ * about whether THIS declaration's own function object gets created.
+ *
+ * `declaredValueTypeOf` (above) asks the checker for the member SYMBOL's
+ * type, and for an optional member the checker answers `T | undefined`
+ * whether the query is symbol- or node-based -- `getTypeOfSymbolAtLocation`
+ * and `getTypeAtLocation` on the declaration itself agree, verified
+ * directly against the checker rather than assumed. That answer is
+ * CORRECT for "what does reading this member give you" and simply the
+ * wrong question for an ALLOCATION's own shape: `class-lifecycle.ts`'s
+ * `allocateFunctionObject` asks `valueTypeAt` for what `DefineMethod`
+ * creates, not for what a later read of the member sees.
+ *
+ * `accessorSignatureOf` and `implementationSignatureOf` above already
+ * reach past the symbol for the identical reason (an accessor's/overload
+ * set's symbol answers a different question than the one physical function
+ * being allocated); this is the same move for the third case `questionToken`
+ * introduces. Gated on there being a body, so an interface or `.d.ts`
+ * member SIGNATURE (`ts.isMethodSignature`) is untouched: that node
+ * allocates nothing at all, and `?` there states exactly what it says --
+ * an implementer MAY omit the member.
+ */
+export declare const optionalMethodSignatureOf: (checker: ts.TypeChecker, node: ts.Declaration) => ts.Signature | null;
+/**
+ * The accessor pair behind an *object literal's* member, or `null`.
+ *
+ * Restricted to object literals on purpose. A class accessor is installed by a
+ * class-evaluation event and read back from the class layout
+ * (`projection/classes.ts`), so naming it here as well would be a second
+ * authority over one member. An accessor declared in an interface or a `.d.ts`
+ * has no body at all, so there is nothing for a reader to call and it stays an
+ * ordinary member of a shape the host implements.
+ */
+export declare const literalAccessorOf: (symbol: ts.Symbol, identities: {
+    readonly declarationIdOf: (declaration: ts.Declaration) => DeclarationId;
+}) => StructuralAccessor | null;
+/**
+ * The one signature an OVERLOADED CONSTRUCTOR's implementation declares, or
+ * `null` when the class does not overload its constructor.
+ *
+ * `implementationSignatureOf` above states the rule; this is the same fact at
+ * TypeScript's other spelling of it. `class Long { constructor(low: number,
+ * high?: number, unsigned?: boolean); constructor(value: bigint, unsigned?:
+ * boolean); constructor(value: string, unsigned?: boolean); constructor(
+ * lowOrValue: number | bigint | string = 0, highOrUnsigned?: number | boolean,
+ * unsigned?: boolean) { ... } }` (bson's `long.ts`) declares three ways to
+ * CALL `new Long`, and exactly one frame the body runs with. `sharedAbiOf`
+ * (derive.ts), asked for a convention the three share, correctly finds none
+ * and refuses -- and refusing is wrong here for the same reason it was wrong
+ * for a method: the three are views of one physical constructor, and the
+ * implementation is the one that states its frame.
+ *
+ * A constructor has no name, so the symbol test `implementationSignatureOf`
+ * uses cannot be spelled here. The class's own member list is the same
+ * question asked where it can be answered: an overload set is precisely a
+ * class carrying more than one `ConstructorDeclaration`, of which at most one
+ * has a body.
+ *
+ * Gated on the class declaring no type parameters. `getSignatureFromDeclaration`
+ * answers from the declaration, so its signature is the UNINSTANTIATED one;
+ * for a generic class that would silently drop the instantiation the
+ * constructor type was reached through. Such a class keeps refusing exactly as
+ * it does today rather than being answered with the wrong frame.
+ */
+export declare const constructorImplementationSignatureOf: (checker: ts.TypeChecker, declaration: ts.Node) => ts.Signature | null;
+/**
+ * The source of a mapped type that changes only MODIFIERS -- `Mutable<T>`,
+ * `Readonly<T>` -- or `null` for every mapped type that changes what the
+ * object holds.
+ *
+ * `type Mutable<T extends object> = { -readonly [K in keyof T]: T[K] }`
+ * (tsc's `utilities.ts`) states the same storage as `T`: `readonly` is a
+ * checker-side permission, not a physical fact, and every field keeps its own
+ * key and its own type. So `Mutable<Node>` IS `Node`, and walking it as a
+ * fresh anonymous object was not merely wasteful -- it re-entered the alias
+ * once per nested instantiation and refused with "type alias Mutable
+ * re-entered with no equivalent active instantiation", 4,503 unmet
+ * obligations on the tsc self-compile, all of them behind
+ * `nodeFactory.ts`'s `update<T extends Node>(updated: Mutable<T>, original:
+ * T)`.
+ *
+ * Every other mapped type is refused here, by construction rather than by a
+ * name list:
+ *
+ * - `Partial<T>`/`Required<T>` carry a `?` modifier, which IS physical (a
+ *   presence bit), so a question token of either sign disqualifies.
+ * - `Pick<T, K>`/`Record<K, V>` constrain the key variable to something other
+ *   than `keyof <source>`, so they change the key set.
+ * - A remapped key (`as`) changes the names, and a body that is anything but
+ *   the identity `T[K]` changes the values.
+ *
+ * Answered through the ALIAS's own type arguments: an instantiation's type
+ * arguments are where the source actually is (the mapped type's own instance
+ * carries the substitution internally, and the checker does not publish it).
+ * A mapped type reached without an alias keeps the general path.
+ */
+export declare const modifierOnlyMappedSourceOf: (type: ts.Type) => ts.Type | null;
+/**
+ * What the IMPLEMENTERS of a declared member prove about it, keyed on the
+ * declared member's own symbol.
+ *
+ * `literalAccessorOf` above answers for a literal laid out as ITSELF. This
+ * answers the other case -- a literal laid out as a contextual DECLARED type --
+ * for the two questions whose answer lives in the implementation rather than in
+ * the declaration, and it answers both from ONE walk because both are the same
+ * lookup: which literal members implement which declared member.
+ *
+ *  - `accessorBodiesOf`: `interface C { get next(): T }` has no body, so the
+ *    interface's member is ordinary data of a shape the host implements, and
+ *    the implementing literal's `get next() { ... }` had nowhere to install its
+ *    body -- `producers/allocations.ts` refuses that by name rather than
+ *    allocating a record with an unset callable slot.
+ *  - `implementationReadsReceiver`: a `MethodSignature` has no body, so there is
+ *    no `this`-reading body to gate a receiver on the way an object literal's
+ *    own method is gated. The implementers have one. Without this, the SPELLING
+ *    of the declaration decided the calling convention: the literal's
+ *    `next() { return this.label }` took a receiver and the interface member it
+ *    satisfies took none, and storing one into the other is a conversion between
+ *    two conventions that C++ does not have.
+ *
+ * Keyed on the declared member's own DECLARATION (`declaredMemberKeyOf` below,
+ * which says why a symbol is not a stable identity for one member), and global,
+ * for one reason each:
+ *
+ *  - `RecordAccessor.getter` is one `FunctionId` and an accessor occupies no
+ *    storage, so "is this member an accessor" is a fact about the TYPE while
+ *    "whose body backs it" is a fact about the ALLOCATION. Keying off the layout
+ *    site would silently hand every allocation the first implementer's body,
+ *    because shapes are interned by type; putting the bodies in the interning
+ *    key would mint two shapes for one declared type, which then could not
+ *    convert to each other though the program says they are the same type.
+ *  - so the only sound answer is a program-wide one that REFUSES when two
+ *    implementers of one named type disagree. A conflicted member is left out
+ *    entirely, which returns it to the named refusal -- fail-closed, never
+ *    "whichever was walked first".
+ *
+ * Why a census and not a branch: granting EVERY interface method a receiver is
+ * a measured regression (`structural-receiver.ts` records it, twice) -- it costs
+ * `overload-set-as-value.ts` and `control-flow-structural-view.ts`, whose
+ * members no implementer reads a receiver for. The proof has to come from an
+ * implementation, which is what this supplies.
+ *
+ * Matched on the contextual type's own property SYMBOL, never on the written
+ * name, so a computed well-known-symbol member is tested exactly as a written
+ * one is.
+ */
+export interface DeclaredMemberCensus {
+    readonly accessorBodiesOf: (symbol: ts.Symbol) => StructuralAccessor | null;
+    readonly implementationReadsReceiver: (symbol: ts.Symbol) => boolean;
+    readonly declaredMemberImplementedBy: (name: ts.PropertyName) => ts.Symbol | null;
+}
+export declare const emptyDeclaredMemberCensus: DeclaredMemberCensus;
+export declare const censusDeclaredMembers: (checker: ts.TypeChecker, sourceFiles: readonly ts.SourceFile[], identities: {
+    readonly declarationIdOf: (declaration: ts.Declaration) => DeclarationId;
+}, readsReceiver: (body: ts.Node) => boolean, reachable: ProgramReachability) => DeclaredMemberCensus;