@geastack/compiler 1.0.15

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

@@ -0,0 +1,202 @@
+import ts from 'typescript';
+import { type StructuralDisagreement, type StructuralFormViolation } from './structural-rules.js';
+import type { ValueFlowIndex } from './flow/model.js';
+import { type DeclaredMemberCensus } from './structural-declarations.js';
+import type { DeclarationId, StructuralTypeId } from '../../identity/ids.js';
+import type { StructuralTypeTable } from '../model/structural-type-table.js';
+import type { IdentityTable } from './identities.js';
+import { type AbsentGlobalCensus } from './absent-globals.js';
+import { type ParameterBindingCensus } from './parameter-bindings.js';
+import { type CollectionBindingCensus } from './collection-bindings.js';
+import { type ObjectBagCensus } from './object-bag-bindings.js';
+import type { InstantiationCensus } from './instantiation.js';
+import { type SpecializationCensus } from './specialization.js';
+import { type SpecializationPath } from './identities.js';
+import { type InterfaceFamilyCensus } from '../interface-families.js';
+import { type CommonJsModuleRecordCensus } from './commonjs-module-record.js';
+/**
+ * Mapping checker types onto canonical structural shapes.
+ *
+ * The checker's own type objects are not usable as identity: they are per-
+ * program, they carry target-irrelevant flags, and `typeToString` prints two
+ * unrelated anonymous objects identically. So every type is translated once
+ * into a shape whose canonical key decides identity.
+ *
+ * When a type cannot be named without inventing authority -- a declarationless
+ * object whose members cannot be enumerated, a checker construct this layer does
+ * not model -- the answer is `unresolved` with a reason. That is a real answer
+ * that fails closed downstream, not a gap to paper over with `any`.
+ */
+/**
+ * One copy of a generic class as the deriver sees it: its ordinal, its
+ * layout-relevant fillings folded to structural ids, and the constructor
+ * anchor typed inside it (the `class-constructor` shape whose `construct`
+ * is the copy's own convention).
+ */
+export interface ClassCopyKey {
+    readonly ordinal: number;
+    readonly typeArguments: readonly StructuralTypeId[];
+    readonly constructor: StructuralTypeId;
+}
+export interface StructuralMapper {
+    /**
+     * The same mapper, resolving type parameters as the named monomorphized copy
+     * binds them.
+     *
+     * A view rather than a parameter on every method: `typeOf` recurses through a
+     * dozen shape builders and threading a path through all of them would put the
+     * same forwarded argument in every signature. Each view keeps its own
+     * recursion anchors, because `T` really is a different shape in each copy and
+     * one memo shared between them would hand the second copy the first one's
+     * answer. They share the intern table, which is correct -- a shape is a shape
+     * whichever copy produced it.
+     */
+    /**
+     * `bindingPath` separates the two questions one path usually answers
+     * together: which copy STAMPS the identities this view mints, and which
+     * copies BIND the type parameters it substitutes.
+     *
+     * They are the same path everywhere but one: a call's RESOLVED signature is
+     * a hybrid, whose shape belongs to the callee's declaration and whose type
+     * arguments the checker substituted from the CALLER's frame. Scoping it
+     * wholly to the callee keeps nested declared types out of the caller's
+     * copy -- which is why `producers/shared.ts` scopes it at all -- but leaves
+     * a caller type parameter the checker substituted in with nothing to bind
+     * it, so `outer<T>(op: T) { inner(op) }` published a callee carrier over a
+     * naked `T`. Scoping it wholly to the caller binds that parameter and mints
+     * a second copy of every declared type inside the callee's own signature.
+     * Neither path answers both; this takes each from the one that owns it.
+     */
+    readonly forSpecialization: (path: SpecializationPath, bindingPath?: SpecializationPath) => StructuralMapper;
+    /**
+     * What THIS copy binds a type parameter to, returned unchanged when it binds
+     * nothing (or the candidate is not a parameter at all).
+     *
+     * Exposed because "did this copy replace this parameter" is a question a
+     * producer has to ask before it can tell a constraint-resolved answer from a
+     * substituted one -- `producers/shared.ts`'s `boundReceiverTypeParameter`,
+     * where the checker resolves a member on `T`'s CONSTRAINT and the copy knows
+     * the concrete receiver that overrides it.
+     */
+    readonly substituteTypeParameter: (candidate: ts.Type) => ts.Type;
+    readonly typeOf: (type: ts.Type) => StructuralTypeId;
+    readonly typeAt: (node: ts.Node) => StructuralTypeId;
+    readonly mutableMethodStorageTypeAt: (node: ts.MethodDeclaration) => StructuralTypeId | null;
+    readonly mutableMethodReadTypeAt: (node: ts.Node) => StructuralTypeId | null;
+    /**
+     * What a `Function.prototype.bind` call produces -- the bound callable,
+     * receiver-less -- or `null` for any other node. One answer for the two
+     * places that state a call's result: `typeAt` on the call and the
+     * invocation producer's selected return type (`producers/invocations.ts`),
+     * which the producer fails closed on when they disagree.
+     */
+    readonly boundCallResultAt: (node: ts.Node) => StructuralTypeId | null;
+    /** The result of every native constructor alternative, shared with the invocation's selected return. */
+    readonly constructResultAt: (node: ts.Node) => StructuralTypeId | null;
+    /** The carrier of the value a declaration binds, which for a class is its constructor object rather than its instances. */
+    readonly valueTypeAt: (node: ts.Declaration) => StructuralTypeId;
+    /**
+     * The INSTANCE side of a class node. A class declaration's node type already
+     * is its instance type, but a class EXPRESSION is an expression, and the
+     * checker types it as its value -- the constructor -- so `typeAt` on
+     * `let C = class { y = 4 }` names the constructor object where an instance
+     * receiver was meant. Answered from the constructor type's own construct
+     * signature, which is the same instance type the class's methods receive
+     * (`structural-receiver.ts`'s anonymous-expression branch).
+     */
+    readonly instanceTypeAt: (node: ts.ClassLikeDeclaration) => StructuralTypeId;
+    /**
+     * The signature of a member read off an evolving array, over the element
+     * the census proved rather than the `any`/`never` the checker still holds
+     * at the read -- see `evolvingArrayMemberTypeAt` in this file. Exposed so
+     * the invocation producer's `resolvedCalleeSignatureType` can prefer it
+     * over the checker's resolved signature, which is instantiated from the
+     * same stale receiver type and would otherwise re-box every argument.
+     */
+    readonly evolvingArrayMemberTypeAt: (node: ts.Node) => StructuralTypeId | null;
+    /**
+     * `Object.getOwnPropertyDescriptor(receiver, key)`'s result, minted from the
+     * receiver's own structural shape -- see this file's own
+     * `objectDescriptorReturnTypeAt` for why `typeAt` already answers a bare
+     * CallExpression this way, and why this is exposed the same way
+     * `evolvingArrayMemberTypeAt` is: `producers/shared.ts`'s own
+     * `objectDescriptorReturnTypeAt` (the invocation producer's own result
+     * override, so `mintResult` and `context.types.typeAt` publish the
+     * identical answer `validateInvocationResult` requires) delegates here
+     * rather than re-deriving the same decision a second way.
+     */
+    readonly objectDescriptorReturnTypeAt: (node: ts.Node) => StructuralTypeId | null;
+    /**
+     * The shape of one call's own resolved signature -- the convention that
+     * specific call actually invokes, with every one of the callee's own type
+     * parameters already substituted by the checker's own argument inference.
+     *
+     * This exists because a generic method's *property* type and the *call*
+     * made through it are two different questions: `arr.map`'s property type
+     * carries `map`'s own unbound `<U>`, since nothing at that position has
+     * committed to a value for it, but `checker.getResolvedSignature` on the
+     * `CallExpression` invoking it has already committed -- that is what
+     * resolving a call site over an overload set and inferring its type
+     * arguments both mean. Building the shape from the resolved signature
+     * instead of the property is exact for this one call, not an approximation:
+     * the language itself performed this exact substitution to type-check the
+     * call, and this reads that answer back rather than redoing the inference.
+     */
+    readonly resolvedSignatureTypeOf: (signature: ts.Signature, kind: 'call' | 'construct', resultOverride?: ts.Type) => StructuralTypeId;
+    /**
+     * The raw `ts.Type` `typeAt` resolves a node to, one step before interning.
+     * `producers/invocations.ts`'s `buildSelectedSignature` is the one caller:
+     * a call's `SelectedSignature.returnType` and that SAME call's own
+     * published result (`resultType`, via `context.types.typeAt(node)`) are
+     * two computations of one fact, and `validateInvocationResult` refuses the
+     * program when they disagree. `buildSelectedSignature` already tries the
+     * checker's own answer and `context.returns` (the DECLARATION's own
+     * return-statement census) first; once both are unusable evidence -- a
+     * generic default collapsing the checker's answer to `any`, and no
+     * function body for `context.returns` to read at all (hono's `H` resolves
+     * to an abstract call-signature member, not a declaration with `return`s)
+     * -- only this node-level, CALL-SITE census may still have a real answer,
+     * and building a signature shape needs a raw `ts.Type` override, not
+     * `typeAt`'s interned id. This is that same resolution
+     * (`absentSubstitutedTypeAt`) exposed, so the two sides can never derive a
+     * different answer for one node.
+     */
+    readonly rawTypeAt: (node: ts.Node) => ts.Type;
+    /** The census's pre-default read type of an array-pattern element, when it bound one -- see `ParameterBindingCensus.patternReadTypeAt`. */
+    readonly patternReadTypeAt: (element: ts.BindingElement) => ts.Type | null;
+    /**
+     * Every node for which two of `structuralRules` both had an answer.
+     *
+     * Empty unless `GEA_STRUCTURAL_DISAGREEMENT` is set, and that is not a
+     * convenience: collecting it asks rules the chain would have stopped before,
+     * which INTERNS structural ids the compilation never needed and renumbers
+     * every `gea_record_type_N` after them. So a run that publishes this list is
+     * a run whose emitted C++ nobody may compare, so nothing on the normal path
+     * publishes it.
+     *
+     * Shared by every specialization view, because a disagreement is a property
+     * of the rule set, not of the copy that happened to ask.
+     */
+    readonly structuralDisagreements: readonly StructuralDisagreement[];
+    /**
+     * Rules caught answering for a form their `forms` does not claim.
+     *
+     * Empty unless `GEA_STRUCTURAL_FORM_AUDIT` is set, and non-empty is a defect
+     * in the rule set itself, not in the program being compiled: a rule whose
+     * declared domain is wrong is silently never asked for a whole syntactic
+     * form. See `structuralFormAuditEnabled`.
+     */
+    readonly structuralFormViolations: readonly StructuralFormViolation[];
+    /**
+     * The copies of every generic class whose copies can differ in layout,
+     * keyed by the class's root declaration id: each copy's ordinal with its
+     * layout-relevant fillings folded to structural ids -- exactly the tail of
+     * the class's constructor anchor key inside that copy. Read after typing
+     * by the deriver (`physicalClassDeclarationOf`), which groups them by the
+     * REPRESENTATION of those fillings and names each group by its lowest
+     * ordinal. Empty for a class every one of whose copies agrees on its
+     * relevant fillings; see `SpecializationCensus.copiesMayDifferInLayout`.
+     */
+    readonly classCopies: () => ReadonlyMap<DeclarationId, readonly ClassCopyKey[]>;
+}
+export declare const createStructuralMapper: (checker: ts.TypeChecker, identities: IdentityTable, table: StructuralTypeTable, instantiations?: InstantiationCensus, specializations?: SpecializationCensus, parameters?: ParameterBindingCensus, absent?: AbsentGlobalCensus, collections?: CollectionBindingCensus, bags?: ObjectBagCensus, flow?: ValueFlowIndex, families?: InterfaceFamilyCensus, moduleRecords?: CommonJsModuleRecordCensus, declaredMembers?: DeclaredMemberCensus, isIntrinsicDescriptorCall?: (call: ts.CallExpression) => boolean) => StructuralMapper;