@geastack/compiler 1.0.15

package/dist/semantics/normalize/object-bag-bindings.d.ts

@@ -0,0 +1,305 @@
+import ts from 'typescript';
+import type { StructuralTypeId } from '../../identity/ids.js';
+import type { StructuralTypeTable } from '../model/structural-type-table.js';
+import type { StructuralShape } from '../model/structural-types.js';
+import { type CensusRefusal } from './census-refusal.js';
+import { type ParameterBindingCensus } from './parameter-bindings.js';
+import type { ValueFlowIndex } from './flow/model.js';
+import { type BagAbsence } from './bag-absence.js';
+import { type ProgramReachability } from './reachability.js';
+/**
+ * The members an OPEN PROPERTY BAG carries, inferred from the properties the
+ * program actually writes on it.
+ *
+ * `{}` is the empty object type: zero members, no index signature. So every
+ * later `bag.program = p`, `bag.uniforms = u` or `bag[ key ] = value` writes a
+ * member the type does not have, the census answers `dynamic`, and a value
+ * whose members the program states perfectly well is boxed at every touch.
+ * That is the no-boxing rule's own defect: the members are stated, just not in
+ * the literal that created the storage.
+ *
+ * This is the same move `collection-bindings.ts` makes for a bare `new Map()`
+ * -- infer the type arguments the program never spelled from the uses it made
+ * -- applied to an object literal instead of a collection constructor, and it
+ * deliberately mirrors that module's discipline line for line: candidates are
+ * recognised syntactically, identity is tracked by DECLARATION rather than by
+ * spelling, every observed value for one slot must agree under the one join
+ * (`widestOf`), and anything that does not agree refuses the whole bag rather
+ * than becoming a source-shaped guess nobody wrote.
+ *
+ * The shape this exists for is ordinary JavaScript -- a per-object property
+ * bag, a keyed cache, a memo table, an options accumulator:
+ *
+ *     let map = registry.get( object );
+ *     if ( map === undefined ) { map = {}; registry.set( object, map ); }
+ *     return map;
+ *
+ * ## What licenses inferring at all
+ *
+ * - An empty literal supplies no initial fields. A populated data literal is
+ *   augmented only when later writes add a missing member; every allocation
+ *   field and its initial value participate in the same storage join.
+ * - Nothing already states the shape. Three spellings of "already stated" are
+ *   tested, because they are three different mechanisms: a contextual type on
+ *   the literal (an annotation, a JSDoc `@type`, a typed parameter or return
+ *   position), a type node on the owning declaration, and -- the one that is
+ *   easy to miss -- TypeScript's OWN expando inference, which in a JavaScript
+ *   file types `let output = {}` with the members that `output.geometries =
+ *   []` assigns two lines later. That last answer is flow-sensitive within the
+ *   function and better than this census can derive; overriding it made two
+ *   authorities for one storage whose conversions cannot be satisfied
+ *   (MEASURED: 52 unmet obligations on the three.js app, for zero carriers).
+ * - The literal is not the operand of an `as`/`satisfies` cast.
+ * - Every write to the cell is proved to be the same bag. A cell claimed
+ *   from one write and reassigned an untracked value at
+ *   another would answer the bag's record at every read while holding
+ *   something else: a silent miscompile with a clean certificate.
+ * - Identity is by the owner's DECLARATION NODE, the same key
+ *   `collection-bindings.ts`'s array census uses and for the same reason: a
+ *   property's `ts.Symbol` is late-bound per lookup and is not the same object
+ *   at the declaration as at a later `.prop` access, while
+ *   `symbol.getDeclarations()?.[0]` is stable across all of them.
+ * - Every named member must be WRITTEN somewhere. A key that is only ever read
+ *   has no observed value to derive a type from, and inventing one would be
+ *   exactly the guess this refuses; the whole bag refuses instead, leaving the
+ *   program exactly as it compiles today.
+ * - A computed write (`bag[ k ] = v`) licenses the index sidecar half, joined
+ *   the same way. A computed READ with no computed write refuses for the same
+ *   reason a read-only named key does.
+ *
+ * ## Aliases
+ *
+ * A bag usually does not receive its writes under its own name: it is returned
+ * from a function and written through an alias. So the bag's identity is
+ * propagated to a fixpoint over three purely syntactic, declaration-following
+ * edges -- a variable initialized by a bag expression, a function whose
+ * `return`s are all bag expressions, and a property assignment that aliases
+ * such a function (`return { get: get }`). This is deliberately NOT a general
+ * alias analysis and does not try to be: it follows declarations, the same way
+ * `collection-bindings.ts` resolves a `.set` call's receiver to the `new Map()`
+ * it belongs to, and anything it cannot follow simply never becomes a bag
+ * reference.
+ *
+ * The composed census stack (`frontend.ts`'s `compose`) cannot carry this on
+ * its own, and it is worth stating why rather than leaving it to be
+ * rediscovered: that composition propagates TYPES, and a bag has no type to
+ * propagate until its members are gathered -- which requires knowing, before
+ * any type exists, which distant expressions are the same storage. Identity
+ * has to be settled first; the composition is what then carries the resulting
+ * type outward, which is why this census is given the settled parameter census
+ * and asks it at every observed value -- including when resolving a member
+ * symbol, since `checker.getSymbolAtLocation` answers nothing for a property
+ * of an `any` receiver, which is the state the bags live in.
+ *
+ * ## What this does NOT reach, and why (measured, do not re-derive)
+ *
+ * The alias propagation works, and was verified on the largest bag in the
+ * corpus: one `{}` whose identity reaches 46 distinct property names written
+ * across four files. It still refuses, and the reason is worth recording
+ * because it is not a limit of this module:
+ *
+ * - The program `delete`s two of its NAMED members. A struct field cannot be
+ *   removed, so the refusal is correct. Routing a deleted member into the
+ *   index sidecar instead would need `emit-properties.ts` to resolve a
+ *   CONSTANT key that names no field into the sidecar, which
+ *   `preflight/property-access.ts` deliberately refuses to certify today (see
+ *   `recordWithIndexFieldText`'s own comment).
+ * - More decisively: of that bag's 46 members, about half have a written value
+ *   whose OWN type states nothing -- `_gl.createTexture()` and everything
+ *   downstream of it. Even with every alias edge and `delete` handled, those
+ *   members would derive as `dynamic`, so the boxes would MOVE from the bag
+ *   into its own fields rather than disappear. The boxing rooted at that bag
+ *   is not caused by the storage being `{}`; it is caused by the values put
+ *   into it being untyped, which is a different root with a different fix.
+ *
+ * So this census's ceiling is set by how well the program types the values it
+ * stores, not by how far the identity propagation reaches.
+ */
+/** The inferred shape of one open property bag. */
+export interface ObjectBagShape {
+    readonly absences?: readonly BagAbsence[];
+    /** Fields present in every allocation and never deleted through a tracked alias. */
+    readonly required?: ReadonlySet<string>;
+    /** Named members, keyed by property name, each the join of every value written to it. */
+    readonly members: ReadonlyMap<string, ts.Type>;
+    /** The value type of the string-keyed index sidecar, or `null` when the bag is never written with a computed key. */
+    readonly index: ts.Type | null;
+}
+/**
+ * The settled answer to "which declarations name the SAME bag" -- the exact
+ * fixpoint the frontend's evidence-policy tables name as this
+ * module's one obstacle to a `cells/` evidence policy: no per-node syntactic
+ * `candidatesOf` can state "this node is only known to be a candidate once a
+ * program-wide closure has converged," so the closure itself has to be
+ * published rather than restated.
+ *
+ * These are the raw maps the fixpoint below already builds (`bagOf`,
+ * `returnsBag`, `conflicted`, `ungrounded`), exposed read-only rather than
+ * copied or reshaped -- reshaping them would be a second, independently
+ * drifting spelling of the one answer this module computes. A consumer that
+ * needs a reverse index (every declaration mapped to one root) builds it once
+ * from `bagOf`'s entries, the same way this module's own `evidenceOf` is built
+ * from `bagRootOf`'s answer, rather than this module guessing which shape a
+ * future reader wants.
+ */
+export interface ObjectBagIdentity {
+    /** Every literal owner this fixpoint found, before `conflicted`/`ungrounded` decide which of them may publish a shape -- `literalsByOwner`'s key set. */
+    readonly roots: ReadonlySet<ts.Node>;
+    /** Every declaration proved to hold one bag, mapped to that bag's ROOT declaration (reflexive for a root: `bagOf.get(root) === root`). */
+    readonly bagOf: ReadonlyMap<ts.Node, ts.Node>;
+    /** Every callable whose `return`s all close on one bag, mapped to that bag's root. */
+    readonly returnsBag: ReadonlyMap<ts.Node, ts.Node>;
+    /** Roots that turned out to hold two different bags -- refused wholesale rather than merged. */
+    readonly conflicted: ReadonlySet<ts.Node>;
+    /** Roots whose owning cell also receives a value not proven to be that same root. */
+    readonly ungrounded: ReadonlySet<ts.Node>;
+}
+export interface ObjectBagCensus {
+    /** The settled bag-identity fixpoint, published for reuse -- see `ObjectBagIdentity`'s own header for why this is the one authority and not a shape a caller re-derives. */
+    readonly identity: ObjectBagIdentity;
+    /** The bag this expression holds -- a tracked `{}` literal, or any reference that resolves to one -- or `null`. */
+    readonly shapeAt: (expression: ts.Expression) => ObjectBagShape | null;
+    /**
+     * `shapeAt`'s counterpart keyed by the cell's OWN declaration, for a cell
+     * whose bag arrives by a later ASSIGNMENT rather than its initializer.
+     *
+     * `bagShapeTypeAt` asks a `VariableDeclaration` through its initializer,
+     * which is the right question when there is one -- but three's
+     * `WebGLProperties.get` writes `let map = properties.get( object ); if ( map
+     * === undefined ) { map = {}; ... }`, so the initializer is a CALL (which
+     * `shapeAt` deliberately refuses) and the bag is the assignment. This census
+     * already claimed that declaration for the bag -- `[BAG] BOUND
+     * WebGLProperties.js members=47` -- and nothing could ask for it, so the cell
+     * stayed `any`, `get`'s own return stayed `any`, and every
+     * `properties.get( material ).uniforms` in `WebGLRenderer.js` and
+     * `WebGLMaterials.js` was dynamic behind it.
+     *
+     * The same owner-keyed shape `collection-bindings.ts` grew for exactly this
+     * reason (`arrayElementForOwner`, `typeArgumentsForOwner`): not a second
+     * inference, the same one asked at the node a cell's stored carrier is
+     * actually published from.
+     */
+    readonly shapeForOwner: (declaration: ts.Node) => ObjectBagShape | null;
+    /** The allocation's checker type retains the same shape through type queries and aliases. */
+    readonly shapeForType: (type: ts.Type) => ObjectBagShape | null;
+    /**
+     * The bag a CALL returns -- the one question `shapeAt` refuses.
+     *
+     * `bagRootOf` already resolves it (through `returnsBag`, so the bag's
+     * identity propagates across a `return`); `shapeAt` withholds the answer
+     * because a call's result has TWO authorities -- the node's own type and the
+     * callee's resolved signature -- and moving only one made
+     * `producers/invocations.ts` find them disagreeing and WITHHOLD, taking its
+     * consumers with it: measured at withheld 8 -> 20, 22 operations silently
+     * gone on the three.js app.
+     *
+     * Withholding is what a producer does when a disagreement has no stated
+     * reason. `InvocationResultDivergence` is where a reason is stated, so this
+     * is published separately rather than folded into `shapeAt`: a caller that
+     * asks it takes on the obligation to declare the divergence
+     * (`bag-return-inference`), and every caller that does not keeps the old,
+     * safe behaviour untouched.
+     */
+    readonly callResultShapeAt: (expression: ts.CallExpression | ts.NewExpression) => ObjectBagShape | null;
+    /** The same returned storage at its callable declaration, where the ABI is published. */
+    readonly returnShapeOf: (declaration: ts.Node) => ObjectBagShape | null;
+    /**
+     * The `ts.Type` ONE slot of a tracked bag holds -- `bag.name` or `bag[ k ]`
+     * -- widened with `undefined` exactly as `bagShapeTypeAt` widens it.
+     *
+     * The bag's SHAPE has no `ts.Type` (it becomes a type only through
+     * `table.intern`), and that is why this census runs where it does. Its
+     * slots are a different question: a member's and an index's observed types
+     * are plain `ts.Type`s, so the `ts.Type`-shaped resolvers in
+     * `return-bindings.ts` and `local-bindings.ts` CAN consume them, and until
+     * this accessor existed they had no way to ask.
+     *
+     * That gap was load-bearing. Three's `WebGLExtensions` caches every
+     * extension in a `{}` and reads it straight back --
+     * `if ( extensions[ name ] !== undefined ) return extensions[ name ]` --
+     * so the return census refused the function (`return-index-signature-absent`)
+     * even though this census had already typed the index from the very next
+     * line's `extensions[ name ] = extension`. Everything downstream of
+     * `extensions.get( ... )` stayed dynamic behind that one refusal.
+     *
+     * `null` for an `any` slot: that is the census restating "nothing is known"
+     * at field granularity (see `joined`), and handing it back as an answer
+     * would turn a caller's honest refusal into a bound `any`.
+     */
+    readonly slotTypeAt: (expression: ts.Expression) => ts.Type | null;
+    /**
+     * The widening a bag slot's observed type gets -- `T` to `T | undefined`.
+     *
+     * Exported because BOTH spellings of a slot must be this exact type: the
+     * `ts.Type` one `slotTypeAt` hands the write-discovery censuses, and the
+     * structural one `bagShapeTypeAt` interns for the record's own field. Two
+     * separate constructions of "the same" union is the two-authorities defect
+     * in miniature, and it showed up as one the moment `slotTypeAt` existed:
+     * a `BufferSourceLike | number` slot came out
+     * `tagged-union(undefined|null|present:@ea12f89a)` from one side and
+     * `...@2c8ee8eb` from the other, and every read of it wanted a conversion
+     * between a carrier and itself.
+     *
+     * `getNullableType` rather than a hand-built union, because the checker
+     * FLATTENS: a slot already holding `T | null` comes back `T | null |
+     * undefined` with three arms side by side, never `(T | null) | undefined`
+     * with two absence tags stacked -- which `representation/optional.ts`
+     * refuses, correctly, and which cost 708 violations on the three.js app when this
+     * was spelled by hand.
+     */
+    readonly slotTypeOf: (type: ts.Type) => ts.Type;
+    /** How many DISTINCT bags (by owning declaration) this census bound. */
+    readonly boundCount: number;
+    /**
+     * Every candidate bag this census could not bind -- root, prose and owner,
+     * one `CensusRefusal` per refused root declaration. 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 expression's bag was not bound, or `null` if it was, or if it was never a candidate. */
+    readonly refusalOf: (expression: ts.Expression) => string | null;
+    /** A human-readable dump of every bound bag and refusal, for measurement only -- gated behind an env var at the one call site. */
+    readonly debugReport: () => string;
+}
+/** A census that binds nothing, for callers that state no program. */
+export declare const emptyObjectBagCensus: ObjectBagCensus;
+export declare const censusObjectBagBindings: (checker: ts.TypeChecker, files: readonly ts.SourceFile[], reachable: ProgramReachability, parameters: ParameterBindingCensus | undefined, 
+/**
+ * The whole-program value-flow index -- see `flow/model.ts`. This census's
+ * own identity resolution (`ownerDeclOfExpr`) reads a plain identifier's
+ * target from it rather than re-deriving `checker.getSymbolAtLocation`
+ * itself, the same edge-source swap `field-bindings.ts`/
+ * `collection-bindings.ts` already made. It is NOT a full swap of this
+ * census's write discovery -- see this module's own doc comment, "What the
+ * shared index cannot express", for why the rest (a property access on a
+ * receiver the index cannot name, a call-expression alias root) stays this
+ * census's own.
+ */
+flow: ValueFlowIndex) => ObjectBagCensus;
+/**
+ * The bag's inferred members, interned as an object shape -- the one place
+ * this census's answer enters the type system.
+ *
+ * It lives beside the census rather than in `structural.ts` because it is the
+ * bag's OWN shape rule, not a mapper rule: the optionality below is a fact
+ * about how this storage is filled, and a second copy of it in the mapper
+ * would be a second authority over the same question.
+ *
+ * Every later-added member is OPTIONAL, and its type includes `undefined`.
+ * Allocation fields present in every seed retain their required status unless
+ * a tracked deletion can remove them. A read of a later member that runs before
+ * its write really does observe `undefined` -- `if ( bag.init === undefined )`
+ * is the guard the shape exists to keep compiling. Making those later fields
+ * required would erase a real absent state. A slot whose own type already carries
+ * `null` is widened the same way and stays representable, because
+ * `bagSlotTypeOf` builds the union FLAT -- see its own comment for the
+ * measurement that settled that.
+ */
+export declare const bagShapeTypeAt: (table: StructuralTypeTable, typeOf: (type: ts.Type) => StructuralTypeId, bags: ObjectBagCensus, node: ts.Node) => StructuralTypeId | null;
+/** Type and value readers share one member/optionality publication, including recursive walks. */
+export declare const bagShapeOfType: (typeOf: (type: ts.Type) => StructuralTypeId, bags: ObjectBagCensus, type: ts.Type) => StructuralShape | null;
+/** A callable and its call sites publish the identical inferred bag layout. */
+export declare const bagReturnTypeOf: (table: StructuralTypeTable, typeOf: (type: ts.Type) => StructuralTypeId, bags: ObjectBagCensus, declaration: ts.Node) => StructuralTypeId | null;