@geastack/compiler 1.0.15

package/dist/semantics/normalize/collection-bindings.d.ts

@@ -0,0 +1,278 @@
+import ts from 'typescript';
+import { type CensusRefusal } from './census-refusal.js';
+import { type ParameterBindingCensus } from './parameter-bindings.js';
+import type { ValueFlowIndex } from './flow/model.js';
+import { type ProgramReachability } from './reachability.js';
+/**
+ * The type arguments a bare `new Map()`/`new Set()`/`new WeakMap()`/`new
+ * WeakSet()` NEVER states, inferred from how the collection is actually used.
+ *
+ * `new WeakMap()` with no type arguments and no constructor argument gives
+ * the checker nothing to infer from, so `WeakMapConstructor`'s own declared
+ * default (`new <K extends object = object, V = any>(...)`) wins: K becomes
+ * the bare `object` keyword type. That default is TypeScript's fallback, not
+ * a fact about the program -- exactly the shape `local-bindings.ts` already
+ * handles for an unannotated `let` with no initializer, typed by joining its
+ * writes instead of trusting the checker's `any`. This module is the same
+ * move for a collection's type parameters: `buffers.set(attribute, {...})`
+ * one line after `const buffers = new WeakMap();` says what K actually is
+ * far more precisely than the constructor's own default does.
+ *
+ * Concretely, this is the mechanism behind three.js's WebGL renderer
+ * internals: `WebGLAttributes.js`, `WebGLEnvironments.js`,
+ * `WebGLState.js` and others cache host objects (`BufferAttribute`,
+ * `Texture`, framebuffers) in module-scope `WeakMap`s built with a bare `new
+ * WeakMap()`, keyed by whatever untyped parameter the surrounding function
+ * receives -- 56 `conversion:dynamic(declared-any-never-narrowed)->
+ * record(type|720,...)` obligations on the three.js app trace to
+ * exactly this shape, `type|720` being the bare `object` keyword type
+ * `structural.ts` interns for `WeakMap`'s defaulted `K`.
+ *
+ * ## What licenses inferring at all
+ *
+ * - Only a `new X()` with NO explicit type arguments and NO constructor
+ *   argument: the moment either is present, the program has stated its own
+ *   answer and this module has nothing to add -- overriding a stated type
+ *   would not be inference, it would be a second, disagreeing opinion.
+ * - `X` resolved by SYMBOL, never by spelling (`checker.resolveName`, the
+ *   same mechanism `host-protocols.ts`'s `keyedCollectionDeclarationsOf` and
+ *   `promiseDeclarationOf` already use to name `Map`/`Set`/`WeakMap`/
+ *   `WeakSet`/`Promise`/`Date` independently of the program's own text): a
+ *   program that declares its OWN `class WeakMap` is never touched, because
+ *   its constructor symbol is not the one `resolveName` finds at global
+ *   scope.
+ * - The collection's identity is tracked by the SYMBOL it is assigned to
+ *   (a `const`/`let` variable, or a later plain reassignment of one), exactly
+ *   the way `local-bindings.ts`'s `assignmentsBySymbol` tracks a cell -- so
+ *   `WebGLState.js`'s `currentDrawbuffers`, built once at module scope and
+ *   rebuilt inside a reset function, is one logical collection whose two
+ *   `new WeakMap()`s must describe the same K/V, not two independent guesses.
+ * - Every key argument observed across every `.get`/`.set`/`.has`/`.delete`/
+ *   `.add` call on that collection must agree (`widestOf`, the one join this
+ *   compiler's censuses use elsewhere) or the whole collection refuses,
+ *   rather than the union of disagreeing calls becoming a source-shaped guess
+ *   nobody wrote. `V` (from `.set`'s second argument) is independent of `K`:
+ *   a collection this module can bind `K` for but never sees `.set` called on
+ *   (or whose `.set` calls disagree) still answers `K`, leaving `V` `null` --
+ *   "no override", not "refuse everything because of the other half".
+ *
+ * ## Composition
+ *
+ * `parameters` is the already-composed parameter(+return+local) census,
+ * asked at every argument BEFORE this module reads the checker's own answer
+ * for it fails -- no, asked the same `known ?? resolve` way every other
+ * census here does: the checker's own answer first, and only when that is
+ * unusable evidence (`any`/`void`/`never`) does this module fall back to
+ * whatever the upstream census has already resolved for that argument. This
+ * is why the majority of these 56 sites will not bind on the parameter
+ * census's own: the key argument at each one is currently an unannotated
+ * local function parameter, `any` all the way down, and neither this module
+ * nor the checker has anything else to read yet. When the parameter census's
+ * own inference improves (an optimistic-fixpoint join over a
+ * self-referential parameter's own call sites is a separate, already-planned
+ * change), this module needs no change at all to start binding more of them
+ * -- it already asks `parameters.typeAt` for every argument.
+ *
+ * ## Ownership and evidence come from the shared value-flow index
+ *
+ * Two holes used to make this census blind to real writes, not merely to
+ * exotic syntax:
+ *
+ * - **The alias case.** `const helper = []; fill(helper); return helper` --
+ *   `fill`'s own body does `arr.push(x)` on its PARAMETER, a different
+ *   declaration than `helper`'s own. Ownership used to be tracked purely by
+ *   declaration identity, so a write reaching the array only through a
+ *   parameter it was passed to was invisible.
+ * - **The non-identifier receiver.** `this.cache.set(k, v)` or `a.b.set(k, v)`
+ *   -- evidence gathering used to require the receiver be a bare identifier
+ *   (`m.set(...)`), so a collection held by a property was invisible even
+ *   when its OWNER was tracked, and `this.m = new Map()` was refused
+ *   `owner-not-tracked` outright because ownership resolution only matched a
+ *   plain-identifier assignment target.
+ *
+ * Both are closed by reading `flow` (`flow/model.ts`), the one whole-program
+ * walk that already states every `array-append`/`array-fill`/`index-
+ * assignment`/`collection-key`/`collection-value` edge FOR ANY RECEIVER
+ * SHAPE it can name (identifier, `x.prop`, or a literal-keyed bracket --
+ * `flowTargetOf` draws that line once, for every consumer), and every
+ * `call-argument`/`declaration-initializer`/`identifier-assignment`/
+ * `property-assignment` edge that carries a value's IDENTITY into a new
+ * cell. `aliasClosureOf` below follows exactly the latter four kinds,
+ * restricted to the `whole`-slot write (the cell's entire contents became
+ * this reference, not merely one of its members), transitively, from an
+ * owner's own declaration: this closes the alias case for BOTH the `Map`/
+ * `Set` family and the array family with the same walk, and the
+ * non-identifier receiver case falls out for free because `flow` never
+ * restricted itself to identifiers in the first place -- there is no
+ * separate "non-identifier receiver" fix, just consulting the index instead
+ * of re-deriving a narrower answer beside it.
+ */
+export interface CollectionTypeArguments {
+    /**
+     * The inferred key type, or `null` when the census could not resolve one --
+     * see `refusalOf` for which of the four reasons. `null` here is NOT a
+     * refusal of the whole collection: K and V are independent questions about
+     * one storage, and the checker's own defaulted key argument stays in place
+     * for a collection whose VALUE this census did resolve.
+     */
+    readonly key: ts.Type | null;
+    /**
+     * The inferred value type, or `null` when no `.set` call was observed (or
+     * its arguments disagreed) for this collection -- meaning no override, not
+     * a refusal: `key` may still be usable on its own. Always `null` for a
+     * `Set`/`WeakSet`, which has no value slot to infer.
+     */
+    readonly value: ts.Type | null;
+    /**
+     * The `.set` VALUE arguments this census could not type, for the one
+     * refusal a later layer can still answer: `value-unresolved`.
+     *
+     * The checker calls `map` in `properties.set( object, map )` `any`, and the
+     * one authority that knows better -- the object-bag census -- cannot be
+     * consulted from here. A bag's answer is an `ObjectBagShape`, not a
+     * `ts.Type`, and only becomes one through `table.intern`; `frontend.ts`
+     * places `bags` AFTER `compose()` for exactly that reason, so this census
+     * runs first by construction. Publishing the expressions is what lets
+     * `structural-array-element.ts` -- where the table, the bag census and this
+     * one are all in scope -- finish the question this census had to leave open.
+     *
+     * Empty whenever `value` is non-null (nothing was left open) and whenever
+     * the refusal was anything else: `values-disagree` is a real disagreement
+     * about one storage, and no later layer makes it agree.
+     */
+    readonly valueEvidence: readonly ts.Expression[];
+}
+export interface CollectionBindingCensus {
+    /**
+     * The inferred type arguments for a `new Map()`/`new Set()`/`new
+     * WeakMap()`/`new WeakSet()` this census bound, or `null` when it did not
+     * (including: not a candidate at all, or refused -- see `refusalOf`).
+     */
+    readonly typeArgumentsAt: (node: ts.NewExpression) => CollectionTypeArguments | null;
+    /** How many DISTINCT collections (by owning symbol) this census bound at least a key for. */
+    readonly boundCount: number;
+    /**
+     * Every candidate collection or array literal this census could not bind --
+     * root, prose and owner, one `CensusRefusal` per refusal. See
+     * `census-refusal.ts` for why this replaced a bare `ReadonlyMap<string,
+     * number>`: a count says a cell went untyped, never WHICH one, so nothing
+     * downstream could act on a single refusal. A caller that still wants the
+     * old shape derives it with `censusRefusalCounts`.
+     */
+    readonly refusals: readonly CensusRefusal[];
+    /** Why this particular `new X()` was not bound (or its owner's collection was not), or `null` if it was, or if it was never a candidate. */
+    readonly refusalOf: (node: ts.NewExpression) => string | null;
+    /**
+     * The inferred element type for an empty, unannotated array literal this
+     * census bound (see the "Array element census" section below), or `null`
+     * when it did not.
+     */
+    readonly arrayElementAt: (node: ts.ArrayLiteralExpression) => ts.Type | null;
+    /** Why this particular empty array literal was not bound, or `null` if it was, or if it was never a candidate (including: `settleEvolving`'s territory, not this module's). */
+    readonly arrayRefusalOf: (node: ts.ArrayLiteralExpression) => string | null;
+    /**
+     * The element type for a READ of a cell this census bound an array for --
+     * `state.probe` and `this.children`, not just the `[]` that filled them.
+     *
+     * The census tracks an array by its OWNING DECLARATION, because that is what
+     * makes two `[]` literals assigned to one property one logical array. Every
+     * read of that property is a read of the same storage, so it carries the same
+     * element type, and this answers it from the same map rather than making the
+     * consumer reconstruct the owner. `arrayElementAt` answers the literal;
+     * this answers everywhere the literal's value is subsequently named.
+     */
+    readonly arrayElementForRead: (expression: ts.Expression) => ts.Type | null;
+    /**
+     * The same element type, asked instead by the CELL'S OWN DECLARATION -- the
+     * node a cell's own stored type is resolved from, which is neither the
+     * literal that filled it nor a later read of it.
+     *
+     * `const uvBuffer = []` publishes its carrier at the `VariableDeclaration`,
+     * and `checker.getTypeAtLocation` on that node answers `never[]`/`any[]`,
+     * so without this the cell carries `array-object(undefined)` while every
+     * READ of it carries `array-object(scalar(number))` from
+     * `arrayElementForRead` -- two authorities over one storage, which surfaces
+     * as an unsatisfiable `binding-read-conversion` obligation per read rather
+     * than as an error anywhere. MEASURED on the three.js app: 133 declarations whose own
+     * type is `never[]`/`any[]` already have an answer here, and the mismatch is
+     * the single largest family of unmet obligations (161 of 756).
+     *
+     * Owner-keyed, exactly like `typeArgumentsForOwner`: every literal feeding
+     * one owner is already required to agree (see the module header), so this is
+     * the SAME answer the literal and the reads get, not a second inference.
+     */
+    readonly arrayElementForOwner: (declaration: ts.Node) => ts.Type | null;
+    /**
+     * Why this declaration's array component was refused, or `null` if it was
+     * bound or is not part of a tracked array at all.
+     *
+     * Keyed by ANY declaration in the alias component -- the literal's owner,
+     * an alias variable, and the PARAMETER a callee receives the array through
+     * -- because `ownerArrayRefusal` is already written for every one of them.
+     * A refusal is a fact about one physical array, and every cell that names
+     * that array has to hear it: otherwise the owner falls back to the
+     * checker's `any[]` while `parameter-bindings.ts`, which resolves a
+     * parameter from its call sites and has never consulted this census, binds
+     * the SAME array to a concrete element type. Two carriers for one storage,
+     * and the emitter's only way to reconcile them is to copy -- which for a
+     * mutable `ArrayObject` silently drops every write the callee makes
+     * (three's `getProgramCacheKey`, measured).
+     */
+    readonly arrayRefusalForOwner: (declaration: ts.Node) => string | null;
+    /**
+     * The same refusal, asked at a READ of the cell -- `arrayElementForRead`'s
+     * counterpart, resolved through the same `ownerDeclOfExpr`.
+     *
+     * A refused array must read back the way it is STORED. TypeScript's
+     * evolving-array analysis is flow-sensitive, so it answers `never[]` at
+     * `const array = []` and a concrete union at a reference further down the
+     * same function; when this census binds the array, `arrayElementForRead`
+     * overrides both with one physical element and the two agree. When it
+     * REFUSES, nothing overrides anything, and the declaration keeps the box
+     * while a later read keeps the checker's narrower answer -- one storage,
+     * two carriers, which the emitter can only reconcile by copying.
+     */
+    readonly arrayRefusalForRead: (expression: ts.Expression) => string | null;
+    /**
+     * The same K/(V) `typeArgumentsAt` answers for one `new Map()`/`new Set()`/
+     * `new WeakMap()`/`new WeakSet()` site, asked instead by the OWNER'S OWN
+     * declaration (a `VariableDeclaration`/`PropertyDeclaration`) -- the node a
+     * cell's own, un-annotated stored type is resolved from, which is not
+     * generally the allocation expression itself: `private store = new Map()`
+     * types the FIELD from `checker.getTypeAtLocation` on the
+     * `PropertyDeclaration`, a different node than the `new Map()` it holds,
+     * and a cell rebuilt in more than one place (`this.m = new Map()` in a
+     * `reset()` method, alongside the constructor) has no single allocation
+     * site to ask at all. Every allocation feeding one owner is already required
+     * to agree (see the module header), so this is the same answer,
+     * OWNER-keyed rather than allocation-site-keyed -- not a second inference.
+     */
+    readonly typeArgumentsForOwner: (declaration: ts.Node) => CollectionTypeArguments | null;
+    /**
+     * `typeArgumentsForOwner`'s exact counterpart to `arrayElementForRead`: the
+     * K/(V) for a READ of a cell this census bound a collection for --
+     * `this.store` at `this.store.set(...)`, not just the `new Map()` that
+     * filled it. Resolves the expression to its owning declaration the same
+     * way every other read-site accessor here does, then defers to
+     * `typeArgumentsForOwner`.
+     */
+    readonly typeArgumentsForRead: (expression: ts.Expression) => CollectionTypeArguments | null;
+}
+/** A census that binds nothing, for callers that state no program. */
+export declare const emptyCollectionBindingCensus: CollectionBindingCensus;
+/**
+ * Whole-program census of every bare collection constructor's inferred type
+ * arguments, once every call site that reads/writes it agrees.
+ *
+ * `parameters` is the already-settled, composed census (parameter+return,
+ * optionally +local) -- asked at every observed argument exactly the way
+ * `local-bindings.ts` asks it at every write, so this module never reopens
+ * that fixpoint and never duplicates its resolution logic.
+ */
+export declare const censusCollectionBindings: (checker: ts.TypeChecker, files: readonly ts.SourceFile[], reachable: ProgramReachability, parameters: ParameterBindingCensus | undefined, 
+/**
+ * The whole-program value-flow index -- the ONE walk that states where every
+ * write is. This module's own four collection passes read their edges from
+ * it rather than re-deriving them; see `flow/model.ts`.
+ */
+flow: ValueFlowIndex) => CollectionBindingCensus;