@geastack/compiler 1.0.15

package/dist/semantics/normalize/collection-bindings.js

@@ -0,0 +1,677 @@
+import ts from 'typescript';
+import { censusRefusal } from './census-refusal.js';
+import { disjointUnionTypeOf, joinOfWrites, widestOf } from './derived-expression-type.js';
+import { emptyParameterBindingCensus } from './parameter-bindings.js';
+import { forEachReachableStatement } from './reachability.js';
+/** A census that binds nothing, for callers that state no program. */
+export const emptyCollectionBindingCensus = {
+    typeArgumentsAt: () => null,
+    boundCount: 0,
+    refusals: [],
+    refusalOf: () => null,
+    arrayElementAt: () => null,
+    arrayRefusalOf: () => null,
+    arrayElementForRead: () => null,
+    arrayElementForOwner: () => null,
+    arrayRefusalForOwner: () => null,
+    arrayRefusalForRead: () => null,
+    typeArgumentsForOwner: () => null,
+    typeArgumentsForRead: () => null
+};
+/**
+ * The four standard collection constructor names, to the family each is --
+ * hardcoded for the same reason `host-protocols.ts`'s `keyedCollectionFamilies`
+ * is: these are core ECMAScript (`lib.es2015.collection.d.ts`), not something
+ * a host installs, so there is no table to read them from.
+ */
+const CONSTRUCTOR_NAMES = new Map([
+    ['Map', 'map'],
+    ['Set', 'set'],
+    ['WeakMap', 'weak-map'],
+    ['WeakSet', 'weak-set']
+]);
+const isUnusableEvidence = (type) => (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Void | ts.TypeFlags.Never)) !== 0;
+/**
+ * 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 const censusCollectionBindings = (checker, files, reachable, parameters = emptyParameterBindingCensus, 
+/**
+ * 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) => {
+    const anchor = files[0];
+    if (!anchor)
+        return emptyCollectionBindingCensus;
+    // The real global constructor VALUE symbols, resolved once -- comparing
+    // AGAINST these (never against the spelling `X` in `new X()`) is what keeps
+    // a program's own `class WeakMap` untouched: its constructor symbol is a
+    // different symbol than the one `resolveName` finds at global scope.
+    const constructorSymbols = new Map();
+    for (const [name, family] of CONSTRUCTOR_NAMES) {
+        const symbol = checker.resolveName(name, anchor, ts.SymbolFlags.Value, false);
+        if (symbol)
+            constructorSymbols.set(family, symbol);
+    }
+    /** The family this expression constructs, if it is genuinely the standard-library constructor -- `null` otherwise. */
+    const realConstructorFamily = (node) => {
+        if (!ts.isIdentifier(node.expression))
+            return null;
+        const family = CONSTRUCTOR_NAMES.get(node.expression.text);
+        if (!family)
+            return null;
+        const expected = constructorSymbols.get(family);
+        if (!expected)
+            return null;
+        return checker.getSymbolAtLocation(node.expression) === expected ? family : null;
+    };
+    /** A bare `new X()`: no explicit type arguments, no constructor argument -- the program stated nothing for this module to override. */
+    const bareConstruction = (node) => (node.typeArguments === undefined || node.typeArguments.length === 0) && (node.arguments === undefined || node.arguments.length === 0);
+    // Declaration-node identity is the stable key for EVERY owner this module
+    // tracks -- a variable, a class field, or a property -- not just the array
+    // case below: a property symbol is late-bound per lookup (`checker.
+    // getSymbolAtLocation` on a property name returns a DIFFERENT `ts.Symbol`
+    // object at its declaration than at each later access), but its
+    // declaration node is the same object every time. Keying `Map`/`Set`
+    // ownership by symbol (as this module used to) meant `this.m = new Map()`
+    // could never be tracked at all: a `BinaryExpression` whose LEFT is a
+    // `PropertyAccessExpression` was rejected outright (`owner-not-tracked`),
+    // and even resolving that symbol once would not have matched the DIFFERENT
+    // symbol object `this.m.set(...)` resolves to later. Declaration-node
+    // keying is what already lets the array census below track `state.probe`;
+    // extending it to `Map`/`Set` closes both problems with the same key.
+    const declNodeOf = (symbol) => symbol?.getDeclarations()?.[0] ?? null;
+    /** The declaration node backing a plain identifier or `x.prop` property access -- `null` for anything else. */
+    const ownerDeclOfExpr = (expr) => {
+        if (ts.isIdentifier(expr))
+            return declNodeOf(checker.getSymbolAtLocation(expr));
+        if (ts.isPropertyAccessExpression(expr))
+            return declNodeOf(checker.getSymbolAtLocation(expr.name));
+        return null;
+    };
+    /**
+     * The declaration this construction is bound to -- a variable's own name,
+     * a class field's own initializer, or the target of a plain `x = new
+     * WeakMap()` / `this.m = new WeakMap()` reassignment (identifier OR
+     * property access, via `ownerDeclOfExpr`). `null` for anything else
+     * (destructuring, an argument passed inline, ...): this module tracks USE
+     * SITES by declaration, so a construction with no trackable owner has
+     * nothing for a later `.get`/`.set` to be found against, and refuses
+     * rather than guessing at one.
+     */
+    const ownerDeclOf = (node) => {
+        const parent = node.parent;
+        if (ts.isVariableDeclaration(parent) && parent.initializer === node && ts.isIdentifier(parent.name)) {
+            return declNodeOf(checker.getSymbolAtLocation(parent.name));
+        }
+        if (ts.isPropertyDeclaration(parent) && parent.initializer === node && ts.isIdentifier(parent.name)) {
+            return declNodeOf(checker.getSymbolAtLocation(parent.name));
+        }
+        if (ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && parent.right === node) {
+            return ownerDeclOfExpr(parent.left);
+        }
+        return null;
+    };
+    /**
+     * Every declaration this owner's value is ALIASED into by direct identity
+     * -- `const b = a`, `b = a`, `o.p = a`, or `a` passed as a call argument
+     * reaching a callee's parameter slot -- so a write reaching the SAME
+     * reference through a different name is evidence for this owner too, not a
+     * different, unrelated cell.
+     *
+     * Follows exactly the edges that carry a value's whole identity (`flow`'s
+     * `whole`-slot writes only -- never the paired `member` write
+     * `property-assignment`/`index-assignment` also record for the RECEIVER,
+     * which states something about one of the receiver's members, not that the
+     * receiver itself became this reference), transitively, via
+     * `flowsFromDeclaration` -- the reverse edge `flow` already states for
+     * every write, so this is a graph walk over data the shared index already
+     * computed, not a second walk of the program.
+     */
+    const ALIAS_EDGES = new Set([
+        'declaration-initializer',
+        'identifier-assignment',
+        'property-assignment',
+        'index-assignment',
+        'call-argument'
+    ]);
+    const aliasClosureOf = (owner) => {
+        const seen = new Set([owner]);
+        const queue = [owner];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            for (const write of flow.flowsFromDeclaration(current)) {
+                if (write.slot !== 'whole' || !ALIAS_EDGES.has(write.edge))
+                    continue;
+                const target = write.target.declaration;
+                if (target && !seen.has(target)) {
+                    seen.add(target);
+                    queue.push(target);
+                }
+            }
+        }
+        return seen;
+    };
+    /**
+     * Render a refusal's subject -- the declaration or construction site a
+     * human (or a later tool) can find and inspect, not a re-derivable index.
+     * A tracked owner is always a `VariableDeclaration`/`PropertyDeclaration`/
+     * `PropertyAssignment`, all of which name themselves with a plain
+     * identifier; anything without one (a bare `new X()` this module could not
+     * attach to a declaration at all) falls back to its own source text.
+     */
+    const describeOwner = (node) => {
+        const sourceFile = node.getSourceFile();
+        const line = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+        const name = node.name;
+        const label = name && (ts.isIdentifier(name) || ts.isPrivateIdentifier(name)) ? name.text : node.getText(sourceFile);
+        return `${label} (${sourceFile.fileName}:${line})`;
+    };
+    const censusRefusals = [];
+    // Pass 1: every candidate `new X()`, grouped by owning declaration.
+    const byOwner = new Map();
+    const nodeOwner = new Map();
+    const nodeRefusal = new Map();
+    const collectConstructions = (node) => {
+        // Mirrors `value-flow.ts`'s own `visit` guard exactly (same `reachable`,
+        // same predicate): a class member reachability has pruned as dead --
+        // never dispatched by symbol (a static) or by key (an instance member) in
+        // live code -- contributes no write evidence to `flow` at all, by design
+        // ("excluded bodies cannot contribute callers or writes to the live
+        // program's typing evidence"). Before this guard, THIS walk had no such
+        // exclusion: it kept collecting a bare `new Map()`/`new Set()` inside a
+        // pruned method as a live candidate needing evidence, while `flow` -- the
+        // only source this module reads evidence from -- had already discarded
+        // every write inside that same body. The two walks disagreeing about what
+        // "the program" contains turned a dead body into a GUARANTEED refusal for
+        // every collection literal in it, not a measured one.
+        if (reachable.memberIsPruned(node))
+            return;
+        if (ts.isNewExpression(node)) {
+            const family = realConstructorFamily(node);
+            if (family && bareConstruction(node)) {
+                const owner = ownerDeclOf(node);
+                if (!owner) {
+                    nodeRefusal.set(node, 'owner-not-tracked');
+                    censusRefusals.push(censusRefusal('collection', 'owner-not-tracked', `bare \`new ${node.expression.getText(node.getSourceFile())}()\` is not bound to a trackable declaration -- not a plain variable/field initializer, and not a reassignment through one`, describeOwner(node)));
+                }
+                else {
+                    nodeOwner.set(node, owner);
+                    const existing = byOwner.get(owner);
+                    if (!existing)
+                        byOwner.set(owner, { family, nodes: [node] });
+                    else if (existing.family !== family) {
+                        nodeRefusal.set(node, 'family-disagreement');
+                        censusRefusals.push(censusRefusal('collection', 'family-disagreement', `this declaration already holds a \`${existing.family}\`; this \`new ${node.expression.getText(node.getSourceFile())}()\` assigns a disagreeing \`${family}\` to the same declaration`, describeOwner(owner)));
+                    }
+                    else
+                        existing.nodes.push(node);
+                }
+            }
+        }
+        ts.forEachChild(node, collectConstructions);
+    };
+    for (const file of files)
+        forEachReachableStatement(reachable, file, collectConstructions);
+    /** The checker's own answer, falling back to the composed parameter census -- the SAME `known ?? resolve` rule every other census here applies. */
+    const argumentType = (expr) => {
+        const own = checker.getTypeAtLocation(expr);
+        return isUnusableEvidence(own) ? parameters.typeAt(expr) : own;
+    };
+    // Pass 2: every `.get`/`.set`/`.has`/`.delete`/`.add` KEY/VALUE write that
+    // reaches one of the tracked collections above OR any cell in its alias
+    // closure -- read from `flow` rather than re-walked, so a receiver spelled
+    // `this.cache.set(...)`, `a.b.set(...)`, or reached only through a
+    // parameter the collection was passed to is evidence exactly like
+    // `m.set(...)` is: `flow`'s own `collection-key`/`collection-value` edges
+    // never restricted themselves to an identifier receiver in the first
+    // place, only this module's old re-derivation did.
+    const boundKey = new Map();
+    const boundValue = new Map();
+    const ownerRefusal = new Map();
+    const valueRefusal = new Map();
+    /** The `.set` value arguments of a collection refused `value-unresolved`, for `CollectionTypeArguments.valueEvidence`. */
+    const unresolvedValueArgs = new Map();
+    for (const [owner, entry] of byOwner) {
+        if (entry.nodes.some((node) => nodeRefusal.has(node))) {
+            ownerRefusal.set(owner, 'family-disagreement');
+            censusRefusals.push(censusRefusal('collection', 'family-disagreement', `at least one \`new\` assigned to this declaration disagreed on collection family with another (\`${entry.family}\` vs. a differing family)`, describeOwner(owner)));
+            continue;
+        }
+        const keyArgs = [];
+        const valueArgs = [];
+        for (const decl of aliasClosureOf(owner)) {
+            for (const write of flow.writesToDeclaration(decl)) {
+                if (write.edge === 'collection-key' && write.value)
+                    keyArgs.push(write.value);
+                else if (write.edge === 'collection-value' && write.value)
+                    valueArgs.push(write.value);
+            }
+        }
+        // K and V are INDEPENDENT questions about one storage, and a `continue`
+        // here answered neither because the first had no answer. three's
+        // `WebGLProperties` is the case that costs: `properties.set( object, map )`
+        // keys a `WeakMap` by an untyped parameter, so K is `key-unresolved` --
+        // while V is the 47-member bag the whole renderer reads back out of it,
+        // fully determined by that very same call. Every refusal below is a
+        // statement about K alone, and the checker's own (defaulted, workable) key
+        // argument survives each one exactly as it did when the whole collection
+        // was refused: `overriddenCollectionShape` keeps `typeArguments[0]`
+        // untouched when this census binds no key.
+        const key = (() => {
+            if (keyArgs.length === 0) {
+                ownerRefusal.set(owner, 'no-key-uses');
+                censusRefusals.push(censusRefusal('collection', 'no-key-uses', 'no `.get`/`.set`/`.has`/`.delete`/`.add` call with a key argument was observed reaching this collection (or any of its aliases)', describeOwner(owner)));
+                return null;
+            }
+            const keyTypes = [];
+            for (const arg of keyArgs) {
+                const type = argumentType(arg);
+                if (!type) {
+                    ownerRefusal.set(owner, 'key-unresolved');
+                    censusRefusals.push(censusRefusal('collection', 'key-unresolved', `the key argument \`${arg.getText(arg.getSourceFile())}\` could not be typed (the checker's own answer was unusable and the composed parameter census had nothing to add)`, describeOwner(owner)));
+                    return null;
+                }
+                keyTypes.push(type);
+            }
+            const joined = widestOf(checker, keyTypes);
+            if (!joined) {
+                ownerRefusal.set(owner, 'keys-disagree');
+                censusRefusals.push(censusRefusal('collection', 'keys-disagree', `the key arguments observed across this collection's calls do not join to one type: ${keyTypes.map((type) => checker.typeToString(type)).join(', ')}`, describeOwner(owner)));
+                return null;
+            }
+            // A `WeakMap`/`WeakSet` key must stay a REFERENCE -- ECMA-262 24.3/24.4
+            // admit only objects (and unregistered symbols) as weak keys, and
+            // `representation/collections.ts`'s `deriveKeyedCollection` refuses a
+            // weak key that lacks one, by design (a `WeakMap<number, T>` has no
+            // correct lowering, ever). Joining evidence across every `.set`/`.get`
+            // call the ordinary `widestOf` way is correct for `map`/`set` -- pure
+            // structural equality never asks about pointers -- but for the weak
+            // families it can join two or more UNRELATED class keys into a `T1 | T2`
+            // union, or widen a nullable receiver into `T | null`: both are still
+            // perfectly good TypeScript types, and both lower to a carrier
+            // (`tagged-union`, `optional(...)`) with no single pointer to compare,
+            // which the checker in `collections.ts` then refuses outright -- turning
+            // a WORKING (boxed, dynamically-keyed) WeakMap into a hard `unresolved`
+            // refusal. `WeakMap<object, V>`'s own DEFAULT (bound to nothing) already
+            // compiles today via `dynamic`'s admitted reference identity
+            // (`hasReferenceIdentity`'s own comment) -- this module must not narrow
+            // that into something WORSE than what it is replacing. `isUnion()` is the
+            // cheap, correct proxy at this layer for "does not reduce to one
+            // reference-bearing shape": every case this census has actually observed
+            // failing downstream (a tagged union of classes, an `optional(T, null)`)
+            // is a TS union, and a single class/interface/object type -- the only
+            // shape this runtime's weak families can pointer-compare -- never is one.
+            if ((entry.family === 'weak-map' || entry.family === 'weak-set') && joined.isUnion()) {
+                ownerRefusal.set(owner, 'weak-key-not-reference');
+                censusRefusals.push(censusRefusal('collection', 'weak-key-not-reference', `the joined key type \`${checker.typeToString(joined)}\` does not reduce to one reference-bearing shape, but a \`${entry.family}\` key must stay an object (ECMA-262 24.3/24.4)`, describeOwner(owner)));
+                return null;
+            }
+            return joined;
+        })();
+        if (key)
+            boundKey.set(owner, key);
+        if (entry.family !== 'map' && entry.family !== 'weak-map')
+            continue;
+        if (valueArgs.length === 0) {
+            valueRefusal.set(owner, 'no-value-uses');
+            censusRefusals.push(censusRefusal('collection', 'no-value-uses', 'no `.set` call with a value argument was observed reaching this collection (or any of its aliases)', describeOwner(owner)));
+            continue;
+        }
+        const valueTypes = [];
+        let everyValue = true;
+        for (const arg of valueArgs) {
+            const type = argumentType(arg);
+            if (!type) {
+                everyValue = false;
+                break;
+            }
+            valueTypes.push(type);
+        }
+        if (!everyValue) {
+            valueRefusal.set(owner, 'value-unresolved');
+            // The one refusal a later layer can lift -- see `valueEvidence`. The
+            // expressions are published whole rather than the ones that failed,
+            // because the resolver downstream must agree about ALL of them or
+            // answer nothing: a value slot half-derived from this census and half
+            // from the checker would be a second authority over one storage.
+            unresolvedValueArgs.set(owner, valueArgs);
+            censusRefusals.push(censusRefusal('collection', 'value-unresolved', "at least one `.set` value argument on this collection could not be typed (the checker's own answer was unusable and the composed parameter census had nothing to add) -- left open for structural-array-element.ts's bag resolution", describeOwner(owner)));
+            continue;
+        }
+        const value = widestOf(checker, valueTypes);
+        if (!value) {
+            valueRefusal.set(owner, 'values-disagree');
+            censusRefusals.push(censusRefusal('collection', 'values-disagree', `the \`.set\` value arguments observed do not join to one type: ${valueTypes.map((type) => checker.typeToString(type)).join(', ')}`, describeOwner(owner)));
+            continue;
+        }
+        boundValue.set(owner, value);
+    }
+    // --- Array element census -------------------------------------------
+    //
+    // An empty array literal with no contextual type is `never[]` -- TypeScript
+    // states nothing about what it will hold, correctly, because nothing in
+    // the literal itself says. For a plain `let`/`const` binding
+    // (`structural-layout-type.ts`'s `settleEvolving`/`boundSymbolOf`), the
+    // checker's OWN flow analysis settles this by re-asking at the binding's
+    // last reachable reference in the same file -- `let arr = []; ...
+    // arr.push(x); return arr` answers `number[]` there, and that is a BETTER
+    // answer than anything this module could derive, because it is
+    // flow-sensitive within the function. This module must not fight that: a
+    // candidate whose parent is exactly that shape (a `VariableDeclaration`
+    // with a plain identifier name, initialized directly by the literal) is
+    // left alone entirely, uncounted, so as never to second-guess an answer
+    // TypeScript already gets right.
+    //
+    // What TypeScript's evolving-array machinery does NOT reach is a literal
+    // that is not itself a variable's own initializer -- most concretely, a
+    // property of an object literal (`const state = { probe: [] }`). A
+    // property has no flow node of its own; `state.probe` is a
+    // `PropertyAccessExpression` at every read, never the plain identifier
+    // reference evolving-array settling requires, so the checker reports
+    // `never[]` at `state.probe.push(...)` forever, even though the property
+    // holds nine real `Vector3` instances by the time any of that code runs.
+    // That mismatched `never` is not inert: a downstream rule reasoning about
+    // reachability from a `never`-typed operand can and did treat code that
+    // runs every frame as dead (see the module-level history this fix
+    // responds to). Removing the false `never` at its source is the only fix
+    // that cannot be undone by some future consumer trusting the certificate.
+    //
+    // The tracking problem is harder than the `Map`/`Set` case above: a
+    // property is not held by one persistent variable `ownerSymbolOf` can
+    // resolve identically at every reference. Empirically (verified against
+    // this exact `WebGLLights.js` shape before writing this), `checker.
+    // getSymbolAtLocation` on a property name returns a DIFFERENT `ts.Symbol`
+    // object at the declaration than at each later `.prop` access -- late-bound
+    // per lookup, not one persistent identity the way a variable's symbol is.
+    // What IS stable across all of them is the symbol's OWN declaration node:
+    // `sym.getDeclarations()?.[0]` returns the same `PropertyAssignment` AST
+    // node (`probe: []` itself) every time, at the declaration and at every
+    // later `.probe` access. So ownership here is tracked by DECLARATION NODE,
+    // not by symbol object identity -- a strictly more general key that would
+    // also work for the variable case, but the variable case already has its
+    // own proven-working, declaration-keyed tracking above (`declNodeOf`/
+    // `ownerDeclOfExpr`, defined once, near the top of this function, and
+    // reused here) and is left untouched.
+    const isUnstatedEmptyArrayLiteral = (node) => {
+        if (!ts.isArrayLiteralExpression(node) || node.elements.length > 0)
+            return false;
+        const type = checker.getTypeAtLocation(node);
+        if (!checker.isArrayType(type))
+            return false;
+        const [element] = checker.getTypeArguments(type);
+        if (element === undefined || (element.flags & (ts.TypeFlags.Never | ts.TypeFlags.Any)) === 0)
+            return false;
+        // A contextual array type is a statement made by the surrounding
+        // annotation/signature. In particular, an explicit `any[]` remains a
+        // genuine dynamic boundary; only the checker-created never/any fallback
+        // of an uncontextualized `[]` is evidence-free storage this census may
+        // replace from its writes.
+        return checker.getContextualType(node) === undefined;
+    };
+    /**
+     * The owning declaration node for a candidate empty array literal, or `null`
+     * when it is not trackable at all.
+     *
+     * A plain variable's own initializer USED to be excluded here and left
+     * entirely to `settleEvolving` -- TypeScript's own flow-sensitive narrowing
+     * of an unannotated `let`/`const arr = []`. That measurement (binds 130 more
+     * arrays, boxed count unchanged) was taken against a gate that only counted
+     * a TOP-LEVEL `dynamic` carrier: `array-object{element: dynamic}` was
+     * invisible to it, so "unchanged" meant nothing about whether the element
+     * type was actually right.
+     *
+     * It is not always right. `settleEvolving`'s narrowing is flow-sensitive
+     * WITHIN one function; when the only pushes/writes to the array happen
+     * inside a NESTED function that closes over the binding (three.js's
+     * `PolyhedronGeometry` builds `const vertexBuffer = []` in a constructor and
+     * fills it only from a sibling nested `function subdivideFace(...)` it
+     * calls), the checker cannot narrow across that boundary and every outer
+     * read widens to `any[]` -- worse than `never[]`, because
+     * `structural-array-element.ts`'s own read guard used to only fire for a
+     * `never` element, so an `any[]`-widened read fell straight through to the
+     * `dynamic` element this whole census exists to avoid.
+     *
+     * Admission is based on the allocation stating no element type. Once its
+     * complete write set is known, every alias must use that storage element,
+     * including an earlier checker read narrowed before publication elsewhere.
+     */
+    const arrayOwnerDeclOf = (node) => {
+        const parent = node.parent;
+        if (ts.isVariableDeclaration(parent) && parent.initializer === node && ts.isIdentifier(parent.name)) {
+            return declNodeOf(checker.getSymbolAtLocation(parent.name));
+        }
+        if (ts.isPropertyAssignment(parent) && parent.initializer === node && ts.isIdentifier(parent.name)) {
+            return declNodeOf(checker.getSymbolAtLocation(parent.name));
+        }
+        if (ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && parent.right === node) {
+            return ownerDeclOfExpr(parent.left);
+        }
+        return null;
+    };
+    // Pass 3: every candidate empty array literal, grouped by owning declaration node.
+    const arraysByOwner = new Map();
+    const arrayNodeOwner = new Map();
+    const arrayNodeRefusal = new Map();
+    const collectArrayLiterals = (node) => {
+        // See the identical guard in `collectConstructions` above: this walk and
+        // `flow`'s own must agree on what counts as live code, or a member
+        // reachability has pruned as dead becomes a GUARANTEED `array:no-writes`
+        // for every empty-array candidate inside it -- not because the array is
+        // genuinely never written, but because the one place this census reads
+        // writes from (`flow`) was never asked to look inside a body it had
+        // already excluded. MEASURED on the three.js app: `AnimationClip.js`'s `parse`,
+        // `toJSON`, `CreateFromMorphTargetSequence` (named by symbol, never
+        // dispatched under that exact name anywhere reachable) and `clone`
+        // (opened by key, but not by this program's own `.clone()` call shapes)
+        // each push into a local array this way -- four false `no-writes`
+        // refusals from one missing exclusion, not four different defects.
+        if (reachable.memberIsPruned(node))
+            return;
+        if (isUnstatedEmptyArrayLiteral(node)) {
+            const owner = arrayOwnerDeclOf(node);
+            if (owner) {
+                arrayNodeOwner.set(node, owner);
+                const existing = arraysByOwner.get(owner);
+                if (existing)
+                    existing.push(node);
+                else
+                    arraysByOwner.set(owner, [node]);
+            }
+            // No `else` refusal here for the `settleEvolving`-owned or genuinely
+            // untrackable shapes: those are not this module's candidates at all,
+            // the same way a `new WeakMap()` passed inline as a call argument
+            // (rather than bound to a name) is invisible to the census above
+            // rather than counted as a refusal.
+        }
+        ts.forEachChild(node, collectArrayLiterals);
+    };
+    for (const file of files)
+        forEachReachableStatement(reachable, file, collectArrayLiterals);
+    // Pass 4: every `.push`/`.unshift`/`.fill` call and every genuine INDEX
+    // (non-literal-key) assignment reaching one of the tracked array literals
+    // above OR any cell in its alias closure -- read from `flow`'s
+    // `array-append`/`array-fill`/`index-assignment` edges rather than
+    // re-walked. This is what closes the alias case for arrays: `const helper
+    // = []; fill(helper)` where `fill`'s own body does `arr.push(x)` on its
+    // PARAMETER now composes, because `aliasClosureOf` follows the
+    // `call-argument` edge from `helper`'s declaration to that parameter's,
+    // and `flow` already recorded the parameter's own `array-append` writes.
+    // All three edge kinds feed the SAME join: this module does not prefer one
+    // kind of evidence over another, it requires every observed element value
+    // to agree, exactly as the key-argument census above does for
+    // `Map`/`Set`/`WeakMap`/`WeakSet`.
+    const boundElement = new Map();
+    const ownerArrayRefusal = new Map();
+    // Two allocations that reach the same held reference slot also share its
+    // physical element ABI. Join their whole alias component, rather than
+    // publishing incompatible answers according to which owner was visited last.
+    const arrayRoots = new Map();
+    const rootOf = (node) => {
+        const parent = arrayRoots.get(node);
+        if (!parent || parent === node)
+            return node;
+        const root = rootOf(parent);
+        arrayRoots.set(node, root);
+        return root;
+    };
+    for (const owner of arraysByOwner.keys()) {
+        for (const alias of aliasClosureOf(owner)) {
+            const ownerRoot = rootOf(owner);
+            arrayRoots.set(rootOf(alias), ownerRoot);
+            if (!arrayRoots.has(ownerRoot))
+                arrayRoots.set(ownerRoot, ownerRoot);
+        }
+    }
+    const arrayComponents = new Map();
+    for (const alias of arrayRoots.keys()) {
+        const root = rootOf(alias);
+        const component = arrayComponents.get(root) ?? new Set();
+        component.add(alias);
+        arrayComponents.set(root, component);
+    }
+    for (const [owner, aliases] of arrayComponents) {
+        const evidence = [];
+        for (const decl of aliases) {
+            for (const write of flow.writesToDeclaration(decl)) {
+                if ((write.edge === 'array-append' || write.edge === 'array-fill') && write.value)
+                    evidence.push(write.value);
+                else if (write.edge === 'index-assignment' && write.slot === 'element' && write.value)
+                    evidence.push(write.value);
+            }
+        }
+        if (evidence.length === 0) {
+            for (const alias of aliases)
+                ownerArrayRefusal.set(alias, 'array:no-writes');
+            censusRefusals.push(censusRefusal('collection', 'array-no-writes', 'no `.push`/`.unshift`/`.fill` call or index-assignment was observed writing an element into this empty array literal (or any of its aliases)', describeOwner(owner)));
+            continue;
+        }
+        const elementTypes = [];
+        // The refusal below names the OFFENDING WRITE, the same way the
+        // key-argument refusal above names its argument. A refusal that says only
+        // "at least one element" sends the reader back to re-derive which one of
+        // forty-eight `array.push(...)` sites it was -- and three's
+        // `getProgramCacheKey` has exactly that many, spread across three
+        // functions and reached through an alias closure, so the owner line alone
+        // does not locate it.
+        let unresolved = null;
+        for (const expr of evidence) {
+            const type = argumentType(expr);
+            if (!type) {
+                unresolved = expr;
+                break;
+            }
+            elementTypes.push(type);
+        }
+        if (unresolved) {
+            for (const alias of aliases)
+                ownerArrayRefusal.set(alias, 'array:element-unresolved');
+            const site = unresolved.getSourceFile();
+            censusRefusals.push(censusRefusal('collection', 'array-element-unresolved', `the element write \`${unresolved.getText(site)}\` (${site.fileName}:${site.getLineAndCharacterOfPosition(unresolved.getStart(site)).line + 1}) ` +
+                "could not be typed (the checker's own answer was unusable and the composed parameter census had nothing to add)", describeOwner(owner)));
+            continue;
+        }
+        // `joinOfWrites`, not bare `widestOf`: THE SAME WRITE-SET JOIN a cell's
+        // writes get, and for the same reason. `normals.push( 0, 0, 1 )` in
+        // three's `PlaneGeometry`/`CircleGeometry`/`RingGeometry` states three
+        // LITERAL types, none of which covers another, so `widestOf` alone
+        // refused `array:elements-disagree` -- while the array's READS were
+        // typed `number[]` by TypeScript's own evolving-array widening. Two
+        // authorities over one storage, surfacing as an unsatisfiable
+        // `binding-read-conversion:array-object(undefined)->array-object(scalar(
+        // number))` at every read. A literal argument's type is a fact about the
+        // CALL, not about the storage it lands in -- the same rule
+        // `parameter-bindings.ts` states at its own call sites and
+        // `local-bindings.ts`/`field-bindings.ts` get from this very function.
+        //
+        // And when no single type covers the writes, the SAME second question
+        // every sibling census asks: is the disagreement itself the answer?
+        // `var xs = []; xs.push(1); xs.push('a')` holds a `string | number`, and
+        // the checker's own evolving-array widening says so at every reference it
+        // can settle -- while this census alone refused `array:elements-disagree`,
+        // which sent the storage AND every `push` slot to the box for a program
+        // that declared nothing dynamic. `disjointUnionTypeOf` is that question
+        // answered as the `ts.Type` this census's contract carries, built to be
+        // the checker's own settled union object (see its comment for why the
+        // two must be identical rather than merely alike).
+        const element = joinOfWrites(checker, elementTypes) ?? disjointUnionTypeOf(checker, elementTypes);
+        if (!element) {
+            for (const alias of aliases)
+                ownerArrayRefusal.set(alias, 'array:elements-disagree');
+            censusRefusals.push(censusRefusal('collection', 'array-elements-disagree', `the element values written to this array do not join to one type and are not a sound disjoint union: ${elementTypes.map((type) => checker.typeToString(type)).join(', ')}`, describeOwner(owner)));
+            continue;
+        }
+        for (const alias of aliases)
+            boundElement.set(alias, element);
+    }
+    for (const [node, owner] of arrayNodeOwner) {
+        const reason = ownerArrayRefusal.get(owner);
+        if (reason)
+            arrayNodeRefusal.set(node, reason);
+    }
+    /**
+     * One owner's answer, or `null` when this census learned nothing about it.
+     *
+     * Shared by all three accessors so they cannot drift: an owner whose KEY was
+     * refused but whose VALUE resolved is still an answer, and it was three
+     * separate `if (!key) return null`s that made it look like nothing.
+     */
+    const boundArgumentsFor = (owner) => {
+        const key = boundKey.get(owner) ?? null;
+        const value = boundValue.get(owner) ?? null;
+        const valueEvidence = unresolvedValueArgs.get(owner) ?? [];
+        if (key === null && value === null && valueEvidence.length === 0)
+            return null;
+        return { key, value, valueEvidence };
+    };
+    return {
+        typeArgumentsAt: (node) => {
+            const owner = nodeOwner.get(node);
+            if (!owner)
+                return null;
+            return boundArgumentsFor(owner);
+        },
+        boundCount: boundKey.size,
+        refusals: censusRefusals,
+        refusalOf: (node) => {
+            const direct = nodeRefusal.get(node);
+            if (direct)
+                return direct;
+            const owner = nodeOwner.get(node);
+            return owner ? (ownerRefusal.get(owner) ?? null) : null;
+        },
+        arrayElementAt: (node) => {
+            const owner = arrayNodeOwner.get(node);
+            if (!owner)
+                return null;
+            return boundElement.get(owner) ?? null;
+        },
+        arrayRefusalOf: (node) => arrayNodeRefusal.get(node) ?? null,
+        arrayElementForRead: (expression) => {
+            const owner = ownerDeclOfExpr(expression);
+            return owner ? (boundElement.get(owner) ?? null) : null;
+        },
+        arrayElementForOwner: (declaration) => boundElement.get(declaration) ?? null,
+        arrayRefusalForOwner: (declaration) => ownerArrayRefusal.get(declaration) ?? null,
+        arrayRefusalForRead: (expression) => {
+            const owner = ownerDeclOfExpr(expression);
+            return owner ? (ownerArrayRefusal.get(owner) ?? null) : null;
+        },
+        typeArgumentsForOwner: (declaration) => {
+            return boundArgumentsFor(declaration);
+        },
+        typeArgumentsForRead: (expression) => {
+            const owner = ownerDeclOfExpr(expression);
+            if (!owner)
+                return null;
+            return boundArgumentsFor(owner);
+        }
+    };
+};