@geastack/compiler 1.0.15

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

@@ -0,0 +1,13 @@
+import type ts from 'typescript';
+import type { ValueFlowIndex } from './flow/model.js';
+/** Reassignment consumes the same settled writes as type inference and call attribution. */
+export interface ReassignedBindingCensus {
+    readonly isReassignedIn: (file: ts.SourceFile, symbol: ts.Symbol) => boolean;
+    readonly isReassignedAnywhere: (symbol: ts.Symbol) => boolean;
+}
+/**
+ * Being mentioned in a literal is a read, not a possible destructuring write.
+ * The flow index already distinguishes assignment-pattern targets from their
+ * keys, defaults and ordinary literal values, including shorthand targets.
+ */
+export declare const createReassignedBindingCensus: (checker: ts.TypeChecker, flow: ValueFlowIndex) => ReassignedBindingCensus;

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

@@ -0,0 +1,41 @@
+const reassignmentEdges = new Set([
+    'identifier-assignment',
+    'property-assignment',
+    'index-assignment',
+    'compound-assignment',
+    'logical-assignment',
+    'destructuring',
+    'destructuring-default',
+    'iteration-binding',
+    'delete'
+]);
+/**
+ * Being mentioned in a literal is a read, not a possible destructuring write.
+ * The flow index already distinguishes assignment-pattern targets from their
+ * keys, defaults and ordinary literal values, including shorthand targets.
+ */
+export const createReassignedBindingCensus = (checker, flow) => {
+    const byFile = new Map();
+    const all = new Set();
+    for (const write of flow.allWrites) {
+        if (write.slot !== 'whole' || !reassignmentEdges.has(write.edge))
+            continue;
+        const file = write.site.getSourceFile();
+        const written = byFile.get(file) ?? new Set();
+        byFile.set(file, written);
+        for (const symbol of [write.target.symbol, write.target.nameSymbol]) {
+            if (!symbol)
+                continue;
+            // Local and exported namespace symbols name the same mutable cell.
+            for (const identity of [symbol, checker.getExportSymbolOfSymbol(symbol)]) {
+                written.add(identity);
+                all.add(identity);
+            }
+        }
+    }
+    const has = (written, symbol) => written?.has(symbol) === true || written?.has(checker.getExportSymbolOfSymbol(symbol)) === true;
+    return {
+        isReassignedAnywhere: (symbol) => has(all, symbol),
+        isReassignedIn: (file, symbol) => has(byFile.get(file), symbol)
+    };
+};

package/dist/semantics/normalize/record-storage-families.d.ts

@@ -0,0 +1,11 @@
+import ts from 'typescript';
+import type { ValueFlowIndex } from './flow/model.js';
+import type { ParameterBindingCensus } from './parameter-bindings.js';
+/**
+ * Assignment-connected structural records share storage, including records
+ * reached through array/tuple views. Select a declared wider shape only when
+ * it retains every source field and the checker proves assignability. This
+ * happens before layout; copying array elements at the store breaks aliases.
+ * The settled value-flow inventory is the only source of connection edges.
+ */
+export declare const recordStorageFamilies: (checker: ts.TypeChecker, flow: ValueFlowIndex | undefined, parameters: ParameterBindingCensus) => ((type: ts.Type) => ts.Type);

package/dist/semantics/normalize/record-storage-families.js

@@ -0,0 +1,109 @@
+import ts from 'typescript';
+import { inheritedAccessorOfAssignment } from '../inherited-accessor.js';
+/**
+ * Assignment-connected structural records share storage, including records
+ * reached through array/tuple views. Select a declared wider shape only when
+ * it retains every source field and the checker proves assignability. This
+ * happens before layout; copying array elements at the store breaks aliases.
+ * The settled value-flow inventory is the only source of connection edges.
+ */
+export const recordStorageFamilies = (checker, flow, parameters) => {
+    const parents = new Map();
+    // Fresh and widened views of a literal share its symbol, although the
+    // checker gives them distinct Type objects. They still name one allocation.
+    const symbolParents = new Map();
+    const root = (type) => {
+        const symbol = type.getSymbol();
+        const parent = parents.get(type) ?? (symbol ? symbolParents.get(symbol) : undefined);
+        if (!parent || parent === type)
+            return type;
+        const result = root(parent);
+        parents.set(type, result);
+        return result;
+    };
+    const plain = (type) => {
+        if (type.aliasTypeArguments?.length || (type.objectFlags & ts.ObjectFlags.Reference) !== 0)
+            return false;
+        if (!(type.flags & ts.TypeFlags.Object) || type.isClassOrInterface() || checker.isArrayType(type) || checker.isTupleType(type))
+            return false;
+        if (type.getCallSignatures().length || type.getConstructSignatures().length || checker.getIndexInfosOfType(type).length)
+            return false;
+        const properties = type.getProperties();
+        return properties.length > 0 && properties.every((p) => (p.flags & ts.SymbolFlags.Property) !== 0);
+    };
+    const elements = (type) => checker.isTupleType(type)
+        ? checker.getTypeArguments(type)
+        : checker.isArrayType(type)
+            ? [checker.getIndexTypeOfType(type, ts.IndexKind.Number)]
+            : null;
+    const pairs = new Map();
+    const connect = (source, target, depth = 0) => {
+        source = root(source);
+        target = root(target);
+        if (source === target || depth > 8)
+            return;
+        const seen = pairs.get(source) ?? new Set();
+        if (seen.has(target))
+            return;
+        seen.add(target);
+        pairs.set(source, seen);
+        if (source.isUnion()) {
+            for (const arm of source.types)
+                connect(arm, target, depth + 1);
+            return;
+        }
+        if (target.isUnion()) {
+            const array = elements(source) !== null;
+            const matches = target.types.filter((arm) => (elements(arm) !== null) === array && checker.isTypeAssignableTo(source, arm));
+            if (matches.length === 1)
+                connect(source, matches[0], depth + 1);
+            return;
+        }
+        const fromElements = elements(source), toElements = elements(target);
+        if (fromElements && toElements) {
+            for (const from of fromElements)
+                for (const to of toElements)
+                    connect(from, to, depth + 1);
+            return;
+        }
+        if (!plain(source) || !plain(target))
+            return;
+        const retains = (from, to) => {
+            const keys = new Set(to.getProperties().map((p) => p.name));
+            return from.getProperties().every((p) => keys.has(p.name)) && checker.isTypeAssignableTo(from, to);
+        };
+        const adopt = (from, to) => {
+            parents.set(from, to);
+            const symbol = from.getSymbol();
+            if (symbol && symbol !== to.getSymbol())
+                symbolParents.set(symbol, to);
+        };
+        if (retains(source, target))
+            adopt(source, target);
+        // A return or narrowed read can describe a stricter view of an already
+        // wider physical holder. Keep that holder; do not drop its optional slots.
+        else if (retains(target, source))
+            adopt(target, source);
+    };
+    const typeAt = (node) => parameters.typeAt(node) ?? checker.getTypeAtLocation(node);
+    for (const write of flow?.allWrites ?? []) {
+        if (!write.value || write.slot !== 'whole')
+            continue;
+        const declaration = write.target.declaration;
+        let target = null;
+        if (write.edge === 'return' && declaration && ts.isFunctionLike(declaration)) {
+            const signature = checker.getSignatureFromDeclaration(declaration);
+            if (signature)
+                target = checker.getReturnTypeOfSignature(signature);
+        }
+        else if (write.naming) {
+            const symbol = write.target.nameSymbol ?? write.target.symbol;
+            const member = symbol ? (inheritedAccessorOfAssignment(checker, symbol) ?? symbol) : null;
+            const setter = member?.declarations?.find(ts.isSetAccessorDeclaration);
+            target = setter?.parameters[0] ? typeAt(setter.parameters[0]) : typeAt(write.naming);
+        }
+        if (target)
+            connect(typeAt(write.value), target);
+    }
+    return root;
+};

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

@@ -0,0 +1,260 @@
+import ts from 'typescript';
+import { type ParameterBindingCensus } from './parameter-bindings.js';
+import { type CollectionBindingCensus } from './collection-bindings.js';
+import { type ObjectBagCensus } from './object-bag-bindings.js';
+import type { ValueFlowIndex } from './flow/model.js';
+import { type ProgramReachability } from './reachability.js';
+import { type CensusRefusal } from './census-refusal.js';
+/**
+ * The type an unannotated JavaScript function actually RETURNS.
+ *
+ * The mirror of `parameter-bindings.ts`, one direction over. An unannotated
+ * parameter is typed `any` because TypeScript infers a parameter's type from
+ * its annotation alone; an unannotated function's return type is typed `any`
+ * for a related but distinct reason -- the checker DOES infer an unannotated
+ * return type from the function's own `return` statements, and usually
+ * succeeds, but for a function complicated enough (mutually recursive with
+ * its own return, too large a body, a shape the inferencer's heuristics give
+ * up on) it bails to `any` rather than reporting nothing. `properties.get(
+ * object)` in three.js's `WebGLProperties.js` returns `materialProperties`,
+ * an object literal the checker can type exactly -- the declared/inferred
+ * return of the enclosing factory is simply `any`, and every call to it reads
+ * as a dynamic value even though the object it hands back has a real shape.
+ *
+ * Every type this module produces comes out of the checker, read at a
+ * `return` statement's own expression or at one of its members -- never
+ * invented. What this module contributes is attributing that answer to the
+ * DECLARATION so a later call site can ask for it, and to a CALL EXPRESSION
+ * whose resolved signature names that declaration.
+ *
+ * ## Composing with the parameter census
+ *
+ * The two censuses answer questions in opposite directions over the same
+ * program -- what a PARAMETER holds, and what a RETURN produces -- and each
+ * can be the other's evidence: `provider(gl).getExtension(name)` inside a
+ * function whose own `gl` parameter this compiler bound from its callers
+ * needs that binding to type the receiver before this module can resolve
+ * what the call returns.
+ *
+ * The reverse direction -- a return type this module discovers feeding back
+ * into a parameter binding upstream -- is NOT re-run here. This module is a
+ * SINGLE ORDERED PASS: it is built from an already-settled
+ * `ParameterBindingCensus` (the caller runs `censusParameterBindings` to a
+ * fixpoint first, exactly as `structural.ts` already does) and never asks
+ * that census to reconsider anything. A true fixpoint over both censuses
+ * together was considered and rejected for this module: `parameter-bindings.
+ * ts` already runs its OWN fixpoint to convergence before this module ever
+ * sees it, and re-opening that fixpoint here would mean either mutating a
+ * module this compiler does not own or re-implementing its 12-round
+ * convergence loop wholesale duplicating ~700 lines this file would then have
+ * to keep in lockstep. What this single pass therefore cannot see: a
+ * parameter whose ONLY call-site evidence is the result of a function this
+ * module resolves stays exactly as unbound as it is today, because
+ * `censusParameterBindings` already finished before this module ran and does
+ * not get a second look. `parameter-bindings.ts`'s own `resolvedReturnTypeOf`
+ * covers the common case of that direction already -- it is a looser,
+ * un-refusal-counted version of this module's algorithm, reached from inside
+ * that fixpoint's own argument resolution -- so the gap this single pass
+ * leaves is narrower than it first appears: only the return shapes THIS
+ * module resolves and that looser one does not (a stricter cast rule, a
+ * disagreement this module refuses that the other one guessed past, explicit
+ * recursion detection) are invisible to a parameter bound upstream of it.
+ *
+ * ## What it refuses
+ *
+ * Every refusal below leaves the function's return exactly as the checker
+ * already reports it -- `any`, boxed -- because a wrong type is far worse
+ * than a boxed one:
+ *
+ * - a generator (`function*`): its `return` value is not what a caller
+ *   observes at all, `Generator<T, TReturn, TNext>` is, and this module makes
+ *   no claim about that protocol.
+ * - an `async` function: what a caller of an async function observes is
+ *   whatever `await`ing its `Promise` produces, one more layer removed from
+ *   any `return` statement's own type than this module reaches for.
+ * - a function with no `return` statement at all, or a bare `return;` among
+ *   its returns: the first always evaluates to `undefined` and the second
+ *   sometimes does, and `void`/`undefined` are exactly the unusable evidence
+ *   `isUnusableEvidence` already refuses everywhere else in this compiler.
+ * - a function whose closing brace is reachable on some path that never hits
+ *   a `return` -- `T | undefined`, unless the checker itself already reports
+ *   that at some return's own expression, which it will not, so this is
+ *   refused rather than guessed at from source shape.
+ * - a `return` whose own expression is an `as`/`<T>` cast: the program is
+ *   making a statement, honoured exactly as `parameter-bindings.ts` honours a
+ *   parameter declared `: any` -- taken at the checker's own face value for
+ *   that expression, and not read PAST, because a cast is precisely where the
+ *   checker's answer stops being derived from anything else.
+ * - a `return` that (directly, or through a chain this module can resolve)
+ *   calls the function's own declaration, or a declaration already being
+ *   resolved on the same call stack: two functions calling each other's
+ *   return value to determine their own is exactly the circularity the
+ *   checker itself bails to `any` over, and this module bails the same way
+ *   rather than looping.
+ * - two or more `return`s whose types disagree, tested by the shared
+ *   `widestOf` (`derived-expression-type.ts`) -- the identical join
+ *   `parameter-bindings.ts` uses for two call sites: agreement is never
+ *   spelling, and a union of this compiler's own making is a guess nobody
+ *   wrote.
+ */
+export interface ReturnBindingCensus {
+    /**
+     * The type this node's evaluation actually produces, once an unannotated
+     * function's inferred `any` return is replaced by what its `return`
+     * statements produce -- or `null` when nothing here improves on the
+     * checker's own answer.
+     *
+     * Answers exactly two shapes of node: the function-like declaration itself
+     * (the same declaration a `resolvedSignature.declaration` points at), and a
+     * call or `new` expression whose resolved signature names one of those
+     * declarations. Anything else -- a bare identifier, a property access --
+     * is `null` here; a consumer that needs a settled type at one of those
+     * reaches it through the call or declaration this module already answers,
+     * the same way `parameter-bindings.ts`'s own internal resolver does.
+     */
+    readonly typeAt: (node: ts.Node) => ts.Type | null;
+    /** The member list for a SYNTHESIZED disjoint-union carrier at this node -- see `ParameterBindingCensus.unionArmsAt`, the same rule asked of a function's `return`s instead of a parameter's argument set. */
+    readonly unionArmsAt: (node: ts.Node) => readonly ts.Type[] | null;
+    /**
+     * The narrowed return type of a declaration whose ANNOTATION this census
+     * read as an upper bound -- the return form of
+     * `ParameterBindingCensus.statedTypeAt`, needed for the identical reason its
+     * own doc gives: the checker's answer there is a perfectly good structure,
+     * so the guarded census fallback never fires.
+     */
+    readonly statedTypeAt: (node: ts.Node) => ts.Type | null;
+    /** How many declarations this census bound a return type for, for measurement. */
+    readonly boundCount: number;
+    /** Why each declaration this census could not bind was refused, one entry per declaration and each carrying its own owner -- see `census-refusal.ts`. */
+    readonly refusals: readonly CensusRefusal[];
+    /** Why this particular declaration was not bound, for attributing one declaration rather than a total. */
+    readonly refusalOf: (declaration: ts.SignatureDeclaration) => string | null;
+}
+/** A census that binds nothing, for callers that state no program. */
+export declare const emptyReturnBindingCensus: ReturnBindingCensus;
+/**
+ * Whether a type is, or is built from, a type parameter -- a hole rather than one layout.
+ *
+ * BOTH argument lists, always -- never chosen by the presence of `target`. An
+ * instantiated ANONYMOUS type -- a mapped alias like `Record<K, V>` or tsc's
+ * `Mutable<T>` -- has a `target` (the open anonymous type it was instantiated
+ * from) and NO `typeArguments`, so picking one list by whether `target` is set
+ * read `Record<string, WithCount<T>[]>` as mentioning nothing: `target` is
+ * defined (the mapped type's own open shape), so the old code took
+ * `typeArguments` (empty for a mapped instantiation) and never looked at
+ * `aliasTypeArguments`, where `T` actually lives. `specialization.ts`'s
+ * `containsHole` documents the identical gotcha and already combines both
+ * lists; this is the same fix; see its comment for the tsc self-compile
+ * regression that shape caused there.
+ *
+ * The consequence here was narrower but still wrong at the source:
+ * `producers/invocations.ts`'s `parameterShapeOf` asks this to decide whether
+ * a parameter's own resolved-signature TYPE has already closed a hole its
+ * DECLARATION still states open. For a generic class's constructor parameter
+ * typed `Record<string, WithCount<T>[]>`, the declared side read as "mentions
+ * nothing" (this bug), so `substituted` was false and the OPEN, unsubstituted
+ * declared type was published as the parameter's carrier for every call --
+ * identical for `new Box<number>(...)` and `new Box<string>(...)` alike, since
+ * both read the one shared, uninstantiated parameter declaration. That is
+ * `test/runtime/generic-function-composite-filling-in-class-copy.ts`'s
+ * `array-object@<hash>` refusal: an unresolved composite masquerading as a
+ * structural type because nothing upstream believed it still had a hole.
+ */
+export declare const mentionsTypeParameter: (type: ts.Type, depth?: number) => boolean;
+/**
+ * Whole-program census of what every unannotated function actually returns.
+ *
+ * `parameters` is the ALREADY-SETTLED output of `censusParameterBindings`
+ * (or `emptyParameterBindingCensus` when none is available) -- settled
+ * before this runs, never re-opened by it. See this module's header comment
+ * for why a single ordered pass was chosen over re-deriving a joint
+ * fixpoint, and what that choice cannot see.
+ */
+export declare const censusReturnBindings: (checker: ts.TypeChecker, files: readonly ts.SourceFile[], reachable: ProgramReachability, parameters: ParameterBindingCensus | undefined, 
+/**
+ * The array/collection census for THIS SAME round -- see `frontend.ts`'s
+ * `compose`, which now computes `collections` from the prior round's
+ * settled parameter view and hands it to every census in the CURRENT
+ * round, this one included, rather than only to `createStructuralMapper`
+ * after the whole fixpoint has already finished with it.
+ *
+ * Consulted at exactly one point below (the element-access arm of
+ * `resolveExpr`), as `collections.arrayElementForRead` -- the element type
+ * of a tracked accumulator array, asked at the RECEIVER expression rather
+ * than the whole indexed read. `findLightProbeGrid( volumes, object )`
+ * (`WebGLRenderer.js`) is the exemplar: `return volumes[ 0 ]` where
+ * `volumes` is an unannotated parameter whose real evidence is a
+ * module-scope `const lightProbeGridArray = []` filled by `.push` calls
+ * elsewhere -- exactly what `collection-bindings.ts`'s array census exists
+ * to type, and exactly the shape this module's own resolvers could not
+ * reach before, because that census ran only after this whole fixpoint
+ * settled. `emptyCollectionBindingCensus` (every caller before this
+ * change) makes this identical to the previous behaviour.
+ */
+collections: CollectionBindingCensus | undefined, 
+/**
+ * The whole-program value-flow index -- the ONE walk that states where every
+ * write is. This module's own two private write-discovery walks
+ * (`assignmentsBySymbol`, `containerSetsBySymbol`) read their edges from it
+ * rather than re-deriving them; see `flow/model.ts`. An edge-SOURCE swap: the
+ * policy below (which writes are evidence, how they join) is unchanged.
+ */
+flow: ValueFlowIndex, 
+/**
+ * The same-round property-bag census. Consulted at exactly one point below
+ * (the element/property-access arm of `resolveExpr`), as `slotTypeAt` --
+ * the ONE question about a bag this module can consume, since a slot's own
+ * type is a plain `ts.Type` even though the bag's shape is not. See that
+ * accessor's own header for the refusal it removes.
+ */
+bags?: ObjectBagCensus) => ReturnBindingCensus;
+/**
+ * A `ParameterBindingCensus`-shaped view that answers from BOTH censuses:
+ * `parameters`'s own answer first (a parameter binding is the more direct
+ * fact), the return census otherwise.
+ *
+ * This is the seam meant for `frontend.ts`, which is the one place that
+ * builds `ParameterBindingCensus` and hands it to `createStructuralMapper`
+ * (`structural.ts`) -- neither of which this module owns or edits. Composed
+ * this way, `structural-layout-type.ts`'s existing `parameters.typeAt(node)`
+ * fallback (already-landed code, untouched by this module) starts answering
+ * for a call site this census resolves too, with NO edit needed to either
+ * file: swap `frontend.ts`'s
+ *
+ *   const parameters = censusParameterBindings(compiled.checker, compiled.sourceFiles)
+ *
+ * for
+ *
+ *   const parameters = withReturnBindings(
+ *     compiled.checker,
+ *     compiled.sourceFiles,
+ *     censusParameterBindings(compiled.checker, compiled.sourceFiles)
+ *   )
+ *
+ * and the rest of the pipeline is unchanged. Exported so that edit, when
+ * made by whoever owns `frontend.ts`, is one line.
+ */
+/**
+ * The composed view AND the census inside it, for the one caller that needs
+ * both halves to be the SAME instance.
+ *
+ * `withReturnBindings` builds a census and hides it, which is right for every
+ * consumer that only ever asks a node. It is wrong for a consumer that has to
+ * agree with one: `producers/invocations.ts` reads a call's RESULT through the
+ * composed view (`context.types.typeAt(node)`) and needs this census's answer
+ * for the same call's CALLEE, and building a second census to ask would
+ * reintroduce exactly the two-authority split it is there to close -- two
+ * fixpoints over the same program can settle differently, and the one that
+ * answers the result would not be the one that answers the signature.
+ *
+ * So the instance is handed out rather than reconstructed. `withReturnBindings`
+ * stays the seam for everyone else and is now this function's `view`.
+ */
+export declare const composeReturnBindings: (checker: ts.TypeChecker, files: readonly ts.SourceFile[], reachable: ProgramReachability, parameters: ParameterBindingCensus, collections: CollectionBindingCensus | undefined, 
+/** The whole-program value-flow index -- see `censusReturnBindings`'s own parameter. */
+flow: ValueFlowIndex, 
+/** The same-round property-bag census -- see `censusReturnBindings`'s own parameter. */
+bags?: ObjectBagCensus) => {
+    readonly view: ParameterBindingCensus;
+    readonly returns: ReturnBindingCensus;
+};