@geastack/compiler 1.0.15

package/dist/semantics/normalize/absent-globals.js

@@ -0,0 +1,191 @@
+import ts from 'typescript';
+import { isValueReference } from './census.js';
+import { valueSymbolAt } from './unresolvable-names.js';
+/** A census that answers for nothing, for a compilation whose hosts state no absent name. */
+export const emptyAbsentGlobalCensus = {
+    typeAt: () => null,
+    substituteAbsentType: (type) => type,
+    absentCount: 0,
+    declarations: new Set()
+};
+/**
+ * Whether a declaration is ambient -- the same test `producers/bindings.ts`
+ * uses to decide a binding is external, and deliberately the same one: this
+ * census exists to contradict exactly the declarations that test admits, so
+ * asking a different question would leave a gap between what is believed and
+ * what can be denied.
+ */
+const isAmbient = (node) => {
+    if ((ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Ambient) !== 0)
+        return true;
+    for (let current = node.parent; current; current = current.parent) {
+        if (ts.isModuleDeclaration(current) && (ts.getCombinedModifierFlags(current) & ts.ModifierFlags.Ambient) !== 0)
+            return true;
+    }
+    return false;
+};
+/**
+ * The ambient VALUE declaration a name introduces, or `null`.
+ *
+ * A value, not a type: `interface ImageData` and `declare var ImageData` are two
+ * declarations of one name, and only the second one is a thing the program can
+ * hold. Answering `undefined` for the interface would say the TYPE does not
+ * exist, which is a different and false claim -- a program may still receive an
+ * `ImageData` from somewhere and only be unable to name the constructor.
+ */
+const ambientValueDeclarationOf = (symbol, platform) => {
+    for (const declaration of symbol.declarations ?? []) {
+        if (isValueDeclaration(declaration)) {
+            if (isAmbient(declaration) && platform(declaration))
+                return declaration;
+        }
+    }
+    return null;
+};
+/**
+ * Whether a declaration introduces a VALUE a program could hold.
+ *
+ * `declare class XRWebGLBinding { ... }` is one declaration that is BOTH the
+ * type and the constructor value, so it belongs here as much as `declare var`
+ * does -- `@types/webxr` declares its whole surface that way, and leaving
+ * classes out meant a host could not deny a single WebXR name. `interface`
+ * alone still does not qualify, for the reason above: an interface names no
+ * value.
+ */
+const isValueDeclaration = (node) => ts.isVariableDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node);
+/**
+ * Whether a declaration is the STANDARD LIBRARY's own.
+ *
+ * `SourceFile.hasNoDefaultLib` is the checker's own fact rather than a path
+ * guess: every `lib.*.d.ts` TypeScript ships opens with
+ * `/// <reference no-default-lib="true"/>`, and nothing else sets it. The same
+ * test `host-protocols.ts` computes `standardLibrary` from, for the same
+ * reason it exists there -- a host's table is keyed by NAME, and a name match
+ * alone would let one host's claim silently override a PROGRAM's own
+ * `declare var VideoFrame`. A program that declares the name itself is
+ * asserting something about its own environment, and denying that is a larger
+ * claim than "the platform's standard library declares this and I do not
+ * implement it".
+ */
+const isStandardLibrary = (node) => node.getSourceFile().hasNoDefaultLib;
+/**
+ * The test for "this declaration is the platform's, not the program's".
+ *
+ * `hasNoDefaultLib` alone is too narrow. `@types/webxr` is a DefinitelyTyped
+ * package describing a browser API; it stands in exactly the relation to the
+ * program that `lib.dom.d.ts` does -- the program installed it, did not write
+ * it, and holds no opinion about whether the platform implements it. Restricted
+ * to `hasNoDefaultLib`, a host could deny `HTMLImageElement` and not
+ * `XRWebGLLayer`, which is an accident of which file TypeScript happens to ship
+ * rather than a distinction about authority. It cost the three.js app 81 unmet
+ * obligations for `XRWebGLLayer@1`/`XRWebGLBinding@1` -- names three.js itself
+ * guards with `typeof XRWebGLBinding !== 'undefined'`.
+ *
+ * What the original narrowness protected is still protected: a PROGRAM's own
+ * `declare var VideoFrame` is an assertion about its own environment, and
+ * denying that would be a larger claim than a host may make. That is why the
+ * widening is `isDeclarationFile` AND `isSourceFileFromExternalLibrary` -- the
+ * program's own sources, including its own `.d.ts` files, are untouched, and
+ * `isSourceFileFromExternalLibrary` is the program's own answer rather than a
+ * path guess.
+ */
+export const platformDeclarationTest = (program) => (node) => {
+    const file = node.getSourceFile();
+    return isStandardLibrary(node) || (file.isDeclarationFile && program.isSourceFileFromExternalLibrary(file));
+};
+/**
+ * Whether a type's own declaring symbol names an ambient TYPE this census
+ * denies.
+ *
+ * The same two tests `isAmbient`/`isStandardLibrary` already apply to a VALUE
+ * declaration, applied here to whichever declaration kind actually introduces
+ * a TYPE -- an `interface`, a `class`, or a `type` alias -- because none of
+ * those match `ambientValueDeclarationOf`'s `VariableDeclaration`/
+ * `FunctionDeclaration` filter, and a TYPE has no single declaration to begin
+ * with: `interface HTMLImageElement extends HTMLElement` merges across
+ * several files in `lib.dom.d.ts`, so every declaration the symbol carries is
+ * checked rather than just the first. Both `type.getSymbol()` (an interface or
+ * class reference) and `type.aliasSymbol` (a `type X = ...` reference kept
+ * its alias identity) are consulted, because either can be the name a host
+ * lists.
+ */
+const isAbsentAmbientType = (symbol, absent, platform) => {
+    if (!symbol || !absent.has(symbol.getName()))
+        return false;
+    return (symbol.declarations ?? []).some((declaration) => isAmbient(declaration) && platform(declaration));
+};
+/**
+ * The census for one program.
+ *
+ * Resolve the name's symbol before applying a host fact. A program's own
+ * `const ImageData = ...`, or an import bound to that name, stays untouched.
+ * Platform declarations and references with no declaration can both receive
+ * the host's explicit absence fact. Missing declarations alone never establish
+ * absence: the installed host must have listed the name independently.
+ */
+export const censusAbsentGlobals = (checker, files, absent, platform, namespacePaths) => {
+    if (absent.size === 0)
+        return emptyAbsentGlobalCensus;
+    const undefinedType = checker.getUndefinedType();
+    const answered = new Set();
+    const declarations = new Set();
+    const undeclaredAbsentNames = new Set();
+    const admit = (name, node) => {
+        if (!absent.has(name.text))
+            return;
+        if (!isValueReference(name, namespacePaths))
+            return;
+        const symbol = valueSymbolAt(checker, name);
+        if (!symbol) {
+            // This is still the host's explicit absence statement, not a deduction
+            // from a missing declaration. Older standard libraries may not declare
+            // a newer API at all. A local binding would have a symbol and follows
+            // the existing platform-declaration check below.
+            answered.add(node);
+            undeclaredAbsentNames.add(name.text);
+            return;
+        }
+        const declaration = ambientValueDeclarationOf(symbol, platform);
+        if (!declaration)
+            return;
+        declarations.add(declaration);
+        answered.add(node);
+        // The DECLARATION too, reached through the reference. The standard
+        // library's own files are not among the files walked below, so a lib.dom
+        // `declare var VideoFrame` is only ever seen from a program that mentions
+        // it -- and a cell whose declaration kept the constructor carrier while
+        // every reference answered `undefined` would be two carriers for one cell.
+        answered.add(declaration);
+        if ((ts.isVariableDeclaration(declaration) || ts.isFunctionDeclaration(declaration)) && declaration.name) {
+            answered.add(declaration.name);
+        }
+    };
+    for (const file of files) {
+        const visit = (node) => {
+            // The declaration itself, so the cell and its readers agree.
+            if (isValueDeclaration(node) && node.name && ts.isIdentifier(node.name)) {
+                if (isAmbient(node) && platform(node) && absent.has(node.name.text)) {
+                    declarations.add(node);
+                    answered.add(node);
+                    answered.add(node.name);
+                }
+            }
+            else if (ts.isIdentifier(node)) {
+                admit(node, node);
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(file);
+    }
+    // Built once, not per call: `getNeverType()` is the same object every time,
+    // and every `substituteAbsentType` call would otherwise ask the checker for
+    // it again.
+    const neverType = checker.getNeverType();
+    const substituteAbsentType = (type) => isAbsentAmbientType(type.getSymbol() ?? type.aliasSymbol, absent, platform) ? neverType : type;
+    return {
+        typeAt: (node) => (answered.has(node) ? undefinedType : null),
+        substituteAbsentType,
+        absentCount: declarations.size + undeclaredAbsentNames.size,
+        declarations
+    };
+};

package/dist/semantics/normalize/arguments-objects.d.ts

@@ -0,0 +1,43 @@
+import ts from 'typescript';
+/**
+ * Which identifiers in this program are the magic `arguments` binding, and
+ * what shape each one's value takes.
+ *
+ * The question is semantic -- it needs a `ts.TypeChecker`, because the only
+ * thing that distinguishes the magic binding from an ordinary variable
+ * someone named `arguments` is that its symbol declares nothing anywhere
+ * (`isArgumentsObjectIdentifier`, `producers/bindings.ts`). The layer that
+ * has to ask it is not: `references.ts`'s `citeExpressionResult` is a pure
+ * predictor over syntax and identities, and threading a checker into it would
+ * put one somewhere the architecture gate would rather it were not.
+ *
+ * So the checker answers once, here, and hands the citer a lookup -- exactly
+ * the shape `absent-globals.ts` already uses for its own
+ * checker-needs-to-answer-a-syntactic-layer question, and built beside it in
+ * `frontend.ts` for the same reason.
+ */
+export interface ArgumentsObjectCensus {
+    /** All references to each lexical arguments frame, including unsupported frames. */
+    readonly usesByOwner: ReadonlyMap<ts.SignatureDeclaration, readonly ts.Identifier[]>;
+    /**
+     * The phantom rest parameter's ordinal for an `arguments` identifier whose
+     * value this compiler can build, and `null` for every other node --
+     * including an `arguments` inside a function the checker published no
+     * phantom for, which is a shape nothing here has confirmed the meaning of
+     * and must keep failing closed rather than be guessed at.
+     */
+    readonly phantomOrdinalOf: (node: ts.Node) => number | null;
+    /** How many reference sites this census recognized, for measurement. */
+    readonly count: number;
+}
+export declare const emptyArgumentsObjectCensus: ArgumentsObjectCensus;
+/**
+ * One walk, one checker question per candidate identifier.
+ *
+ * Only identifiers spelled `arguments` are asked about at all: the predicate's
+ * own first test is that spelling, so every other node would cost a symbol
+ * resolution to answer `null`, and this walk runs over every source file of a
+ * program the size of three.js.
+ */
+export declare const censusArgumentsObjects: (checker: ts.TypeChecker, files: readonly ts.SourceFile[]) => ArgumentsObjectCensus;
+export declare const argumentsObjectUsesAt: (checker: ts.TypeChecker, body: ts.SignatureDeclaration) => readonly ts.Identifier[] | undefined;

package/dist/semantics/normalize/arguments-objects.js

@@ -0,0 +1,60 @@
+import ts from 'typescript';
+import { enclosingArgumentsFunction, implicitArgumentsSlotOf, isArgumentsObjectIdentifier } from './implicit-arguments.js';
+export const emptyArgumentsObjectCensus = { phantomOrdinalOf: () => null, usesByOwner: new Map(), count: 0 };
+/**
+ * One walk, one checker question per candidate identifier.
+ *
+ * Only identifiers spelled `arguments` are asked about at all: the predicate's
+ * own first test is that spelling, so every other node would cost a symbol
+ * resolution to answer `null`, and this walk runs over every source file of a
+ * program the size of three.js.
+ */
+export const censusArgumentsObjects = (checker, files) => {
+    const ordinals = new Map();
+    const usesByOwner = new Map();
+    const ownerOrdinals = new Map();
+    const visit = (node) => {
+        if (isArgumentsObjectIdentifier(node, checker)) {
+            const owner = enclosingArgumentsFunction(node);
+            if (owner) {
+                let ordinal = ownerOrdinals.get(owner);
+                if (ordinal === undefined) {
+                    const signature = checker.getSignatureFromDeclaration(owner);
+                    ordinal = signature ? (implicitArgumentsSlotOf(signature)?.ordinal ?? null) : null;
+                    ownerOrdinals.set(owner, ordinal);
+                }
+                const uses = usesByOwner.get(owner) ?? [];
+                uses.push(node);
+                usesByOwner.set(owner, uses);
+                if (ordinal !== null)
+                    ordinals.set(node, ordinal);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    for (const file of files)
+        visit(file);
+    return { phantomOrdinalOf: (node) => ordinals.get(node) ?? null, usesByOwner, count: ordinals.size };
+};
+/**
+ * Whether a callable body reads its own `arguments` object, memoized per file
+ * for the life of the checker.
+ *
+ * `sourceInvocationFrame` cannot publish a complete frame without this fact --
+ * a body that reads `arguments[0]` reaches an actual argument through a cell no
+ * parameter names -- and it takes the lookup as a parameter because
+ * `callable-reach.ts` keys a memo on the function's identity. The census
+ * itself depends on nothing but the file, so a consumer that has no such memo
+ * should not have to build a fourth private cache to ask; it asks here.
+ */
+const censusesByChecker = new WeakMap();
+export const argumentsObjectUsesAt = (checker, body) => {
+    let byFile = censusesByChecker.get(checker);
+    if (!byFile)
+        censusesByChecker.set(checker, (byFile = new Map()));
+    const file = body.getSourceFile();
+    let census = byFile.get(file);
+    if (!census)
+        byFile.set(file, (census = censusArgumentsObjects(checker, [file])));
+    return census.usesByOwner.get(body);
+};

package/dist/semantics/normalize/asserted-arm-absence.d.ts

@@ -0,0 +1,28 @@
+import ts from 'typescript';
+/**
+ * Whether a named read through a type assertion may land on a union arm that
+ * has no such member at all.
+ *
+ * `typeof (options?.body as ReadableStream)?.getReader` in `@hono/node-server`
+ * reads off a `string | Buffer | ReadableStream | ...` value. The assertion
+ * changes the checker's type and never the value, and the property producer
+ * already dispatches the read on the value's real arms; on the string arm
+ * 6.2.5.5 GetV answers `undefined`. The checker's type for the read is the
+ * asserted arm's bare method, which cannot hold that `undefined`, so the arm
+ * had nowhere to put it and rendered a TypeError -- for a program that only
+ * asked whether the member was there.
+ *
+ * One predicate for the two places that publish the read's type: the property
+ * producer (the `[[Get]]` itself) and the local-binding census (a `const`
+ * initialized by the read, whose checker type is the same bare method).
+ *
+ * A callee is excluded: calling the `undefined` does throw, and the callee's
+ * type is the resolved signature. So are an assertion to `any`/`unknown`, a
+ * receiver that is not a union (a genuinely unknown value keeps the
+ * assertion's checked unbox), and an arm with a string index signature, which
+ * answers its element type.
+ *
+ * `receiverTypeOf` is the caller's own reading of the asserted operand, so
+ * each caller keeps the receiver authority it already uses.
+ */
+export declare const assertedReceiverArmMayLackMember: (checker: ts.TypeChecker, node: ts.Expression, receiverTypeOf: (receiver: ts.Expression) => ts.Type) => boolean;

package/dist/semantics/normalize/asserted-arm-absence.js

@@ -0,0 +1,61 @@
+import ts from 'typescript';
+import { enclosingCallIfCallee } from './producers/erasure.js';
+/**
+ * Whether a named read through a type assertion may land on a union arm that
+ * has no such member at all.
+ *
+ * `typeof (options?.body as ReadableStream)?.getReader` in `@hono/node-server`
+ * reads off a `string | Buffer | ReadableStream | ...` value. The assertion
+ * changes the checker's type and never the value, and the property producer
+ * already dispatches the read on the value's real arms; on the string arm
+ * 6.2.5.5 GetV answers `undefined`. The checker's type for the read is the
+ * asserted arm's bare method, which cannot hold that `undefined`, so the arm
+ * had nowhere to put it and rendered a TypeError -- for a program that only
+ * asked whether the member was there.
+ *
+ * One predicate for the two places that publish the read's type: the property
+ * producer (the `[[Get]]` itself) and the local-binding census (a `const`
+ * initialized by the read, whose checker type is the same bare method).
+ *
+ * A callee is excluded: calling the `undefined` does throw, and the callee's
+ * type is the resolved signature. So are an assertion to `any`/`unknown`, a
+ * receiver that is not a union (a genuinely unknown value keeps the
+ * assertion's checked unbox), and an arm with a string index signature, which
+ * answers its element type.
+ *
+ * `receiverTypeOf` is the caller's own reading of the asserted operand, so
+ * each caller keeps the receiver authority it already uses.
+ */
+export const assertedReceiverArmMayLackMember = (checker, node, receiverTypeOf) => {
+    if (!ts.isPropertyAccessExpression(node) || enclosingCallIfCallee(node) !== null)
+        return false;
+    let receiver = node.expression;
+    let asserted = false;
+    while (ts.isNonNullExpression(receiver) ||
+        ts.isParenthesizedExpression(receiver) ||
+        ts.isAsExpression(receiver) ||
+        ts.isTypeAssertionExpression(receiver)) {
+        asserted ||= ts.isAsExpression(receiver) || ts.isTypeAssertionExpression(receiver);
+        receiver = receiver.expression;
+    }
+    if (!asserted)
+        return false;
+    // An `as any` claims no member, so it has no asserted arm to be wrong about.
+    if ((checker.getTypeAtLocation(node.expression).flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0)
+        return false;
+    const physical = receiverTypeOf(receiver);
+    if (!physical.isUnion())
+        return false;
+    const name = node.name.text;
+    const absentFlags = ts.TypeFlags.Undefined | ts.TypeFlags.Null | ts.TypeFlags.Void | ts.TypeFlags.Never;
+    return physical.types.some((arm) => {
+        if ((arm.flags & absentFlags) !== 0)
+            return false;
+        const apparent = checker.getApparentType(arm);
+        // Only a STRING index signature answers a dotted name: `String`'s own
+        // numeric one never matches an identifier.
+        if (checker.getIndexInfoOfType(apparent, ts.IndexKind.String) !== undefined)
+            return false;
+        return checker.getPropertyOfType(apparent, name) === undefined;
+    });
+};

package/dist/semantics/normalize/assignment-patterns.d.ts

@@ -0,0 +1,70 @@
+import ts from 'typescript';
+/** Only the colon form with a noncomputed __proto__ key sets an object's prototype. */
+export declare const isObjectLiteralPrototypeSetter: (node: ts.Node) => boolean;
+/** Literal syntax denotes a pattern only in an assignment target position. */
+export declare const isAssignmentPattern: (node: ts.Node) => boolean;
+export type ObjectAssignmentElement = ts.PropertyAssignment | ts.ShorthandPropertyAssignment;
+export declare const isObjectAssignmentElement: (node: ts.Node) => node is ObjectAssignmentElement;
+/** A target reference is evaluated, but its old value is never read. */
+export declare const objectAssignmentElementOfTarget: (node: ts.Node) => ObjectAssignmentElement | null;
+/** Nested patterns and loop-head patterns have separate source protocols. */
+export declare const objectAssignmentSource: (pattern: ts.ObjectLiteralExpression) => ts.Expression | null;
+/** The array pattern's own top-level source -- the array-literal twin of `objectAssignmentSource`. */
+export declare const arrayAssignmentSource: (pattern: ts.ArrayLiteralExpression) => ts.Expression | null;
+/**
+ * Whether `node` is a direct element of an array-literal assignment pattern:
+ * a bare target, a defaulted target's whole `=` expression, a rest target's
+ * whole `...` spread, an elision, or a nested pattern. Used to keep these
+ * wrapper shapes out of their ordinary census families (`=` is otherwise
+ * `computation`, `...` is otherwise `protocol`) -- the pattern's own
+ * candidate is the sole producer of whatever operations they key.
+ */
+export declare const isArrayAssignmentPatternElement: (node: ts.Node) => boolean;
+export interface ArrayAssignmentTarget {
+    readonly pattern: ts.ArrayLiteralExpression;
+    readonly position: number;
+    /**
+     * Whichever node the array pattern's own contribution keys its
+     * extraction/default operations on: the target itself for a bare element,
+     * the enclosing `=`/`...` node otherwise.
+     */
+    readonly keyNode: ts.Expression;
+    readonly defaulted: boolean;
+}
+/**
+ * The array-pattern position a write target belongs to, whether written bare
+ * (`[a] = x`), defaulted (`[a = 1] = x`) or as the rest target (`[...a] = x`).
+ *
+ * A write candidate recomputes `keyNode` and `defaulted` rather than looking
+ * them up, the same predictive-citation discipline `citeBoundElementValue`
+ * uses for a binding pattern's element: the pattern's own contribution mints
+ * its extraction/default operations from exactly these two facts, so a
+ * second, independent computation of them here is sound only because both
+ * sides derive them from the same syntax rather than one publishing and the
+ * other guessing.
+ */
+export declare const arrayAssignmentTargetOf: (node: ts.Node) => ArrayAssignmentTarget | null;
+/**
+ * A "simple" array assignment write target -- a name or a property reference,
+ * never a nested pattern (which gets its own recursive `destructuring`
+ * candidate the same way a nested binding pattern does).
+ */
+export declare const arrayAssignmentWriteTargetOf: (node: ts.Node) => ArrayAssignmentTarget | null;
+/**
+ * The literal a nested array-pattern's OWN elements are drawn from -- either
+ * the top-level source (`arrayAssignmentSource`), or, when `pattern` is
+ * itself one element of an ENCLOSING pattern (`[a, [b]] = [1, [2]]`), that
+ * enclosing pattern's own literal element at the same position, recursively.
+ * Stops the moment either the outer source or the recovered element is not
+ * itself a literal -- there is no sound way to index INTO an arbitrary
+ * expression's type without `checker.createArrayType`, which is
+ * checker-internal (`structural-array-element.ts`'s header documents the
+ * identical wall for `never[]`).
+ *
+ * Shared between `local-bindings.ts` (recovering a bare element's evidence
+ * expression) and `structural-array-element.ts` (recovering a REST target's
+ * source, which needs the pattern's source as a whole rather than one
+ * position of it) -- both ask the same "what literal is this pattern reading
+ * from" question and must never derive two different answers for it.
+ */
+export declare const arrayAssignmentPatternSourceExpression: (pattern: ts.ArrayLiteralExpression) => ts.Expression | null;

package/dist/semantics/normalize/assignment-patterns.js

@@ -0,0 +1,147 @@
+import ts from 'typescript';
+/** Only the colon form with a noncomputed __proto__ key sets an object's prototype. */
+export const isObjectLiteralPrototypeSetter = (node) => ts.isPropertyAssignment(node) && (ts.isIdentifier(node.name) || ts.isStringLiteralLike(node.name)) && node.name.text === '__proto__';
+/** Literal syntax denotes a pattern only in an assignment target position. */
+export const isAssignmentPattern = (node) => {
+    let current = node;
+    let parent = node.parent;
+    while (parent) {
+        if (ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && parent.left === current)
+            return true;
+        if (ts.isForOfStatement(parent) && parent.initializer === current)
+            return true;
+        if (ts.isPropertyAssignment(parent) ||
+            ts.isShorthandPropertyAssignment(parent) ||
+            ts.isObjectLiteralExpression(parent) ||
+            ts.isArrayLiteralExpression(parent) ||
+            ts.isSpreadAssignment(parent) ||
+            ts.isSpreadElement(parent)) {
+            current = parent;
+            parent = parent.parent;
+            continue;
+        }
+        return false;
+    }
+    return false;
+};
+export const isObjectAssignmentElement = (node) => (ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node)) &&
+    node.parent !== undefined &&
+    ts.isObjectLiteralExpression(node.parent) &&
+    isAssignmentPattern(node.parent);
+/** A target reference is evaluated, but its old value is never read. */
+export const objectAssignmentElementOfTarget = (node) => {
+    let current = node;
+    while (current.parent && ts.isParenthesizedExpression(current.parent))
+        current = current.parent;
+    const parent = current.parent;
+    if (!parent || !isObjectAssignmentElement(parent))
+        return null;
+    return (ts.isPropertyAssignment(parent) ? parent.initializer : parent.name) === current ? parent : null;
+};
+/** Nested patterns and loop-head patterns have separate source protocols. */
+export const objectAssignmentSource = (pattern) => {
+    const parent = pattern.parent;
+    return ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && parent.left === pattern
+        ? parent.right
+        : null;
+};
+/** The array pattern's own top-level source -- the array-literal twin of `objectAssignmentSource`. */
+export const arrayAssignmentSource = (pattern) => {
+    const parent = pattern.parent;
+    return ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && parent.left === pattern
+        ? parent.right
+        : null;
+};
+/**
+ * Whether `node` is a direct element of an array-literal assignment pattern:
+ * a bare target, a defaulted target's whole `=` expression, a rest target's
+ * whole `...` spread, an elision, or a nested pattern. Used to keep these
+ * wrapper shapes out of their ordinary census families (`=` is otherwise
+ * `computation`, `...` is otherwise `protocol`) -- the pattern's own
+ * candidate is the sole producer of whatever operations they key.
+ */
+export const isArrayAssignmentPatternElement = (node) => {
+    const parent = node.parent;
+    return (parent !== undefined &&
+        ts.isArrayLiteralExpression(parent) &&
+        isAssignmentPattern(parent) &&
+        parent.elements.includes(node));
+};
+/**
+ * The array-pattern position a write target belongs to, whether written bare
+ * (`[a] = x`), defaulted (`[a = 1] = x`) or as the rest target (`[...a] = x`).
+ *
+ * A write candidate recomputes `keyNode` and `defaulted` rather than looking
+ * them up, the same predictive-citation discipline `citeBoundElementValue`
+ * uses for a binding pattern's element: the pattern's own contribution mints
+ * its extraction/default operations from exactly these two facts, so a
+ * second, independent computation of them here is sound only because both
+ * sides derive them from the same syntax rather than one publishing and the
+ * other guessing.
+ */
+export const arrayAssignmentTargetOf = (node) => {
+    const asElement = (candidate) => {
+        const parent = candidate.parent;
+        if (!parent || !ts.isArrayLiteralExpression(parent) || !isAssignmentPattern(parent))
+            return null;
+        const position = parent.elements.indexOf(candidate);
+        return position < 0 ? null : { pattern: parent, position };
+    };
+    if (!ts.isExpression(node))
+        return null;
+    const own = asElement(node);
+    if (own)
+        return { pattern: own.pattern, position: own.position, keyNode: node, defaulted: false };
+    const parent = node.parent;
+    if (parent && ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && parent.left === node) {
+        const wrapper = asElement(parent);
+        if (wrapper)
+            return { pattern: wrapper.pattern, position: wrapper.position, keyNode: parent, defaulted: true };
+    }
+    if (parent && ts.isSpreadElement(parent) && parent.expression === node) {
+        const wrapper = asElement(parent);
+        if (wrapper)
+            return { pattern: wrapper.pattern, position: wrapper.position, keyNode: parent, defaulted: false };
+    }
+    return null;
+};
+/**
+ * A "simple" array assignment write target -- a name or a property reference,
+ * never a nested pattern (which gets its own recursive `destructuring`
+ * candidate the same way a nested binding pattern does).
+ */
+export const arrayAssignmentWriteTargetOf = (node) => {
+    if (!ts.isIdentifier(node) && !ts.isPropertyAccessExpression(node) && !ts.isElementAccessExpression(node))
+        return null;
+    return arrayAssignmentTargetOf(node);
+};
+/**
+ * The literal a nested array-pattern's OWN elements are drawn from -- either
+ * the top-level source (`arrayAssignmentSource`), or, when `pattern` is
+ * itself one element of an ENCLOSING pattern (`[a, [b]] = [1, [2]]`), that
+ * enclosing pattern's own literal element at the same position, recursively.
+ * Stops the moment either the outer source or the recovered element is not
+ * itself a literal -- there is no sound way to index INTO an arbitrary
+ * expression's type without `checker.createArrayType`, which is
+ * checker-internal (`structural-array-element.ts`'s header documents the
+ * identical wall for `never[]`).
+ *
+ * Shared between `local-bindings.ts` (recovering a bare element's evidence
+ * expression) and `structural-array-element.ts` (recovering a REST target's
+ * source, which needs the pattern's source as a whole rather than one
+ * position of it) -- both ask the same "what literal is this pattern reading
+ * from" question and must never derive two different answers for it.
+ */
+export const arrayAssignmentPatternSourceExpression = (pattern) => {
+    const direct = arrayAssignmentSource(pattern);
+    if (direct)
+        return direct;
+    const nested = arrayAssignmentTargetOf(pattern);
+    if (!nested || ts.isSpreadElement(nested.keyNode))
+        return null;
+    const outerSource = arrayAssignmentPatternSourceExpression(nested.pattern);
+    if (!outerSource || !ts.isArrayLiteralExpression(outerSource))
+        return null;
+    const element = outerSource.elements[nested.position];
+    return element && !ts.isSpreadElement(element) && !ts.isOmittedExpression(element) ? element : null;
+};

package/dist/semantics/normalize/bag-absence.d.ts

@@ -0,0 +1,8 @@
+import ts from 'typescript';
+export type BagAbsence = 'null' | 'undefined';
+/** Absence belongs to a binding, not to the bag object it may later hold.
+ * Follow the same storage aliases as bag inference, preserving initial and
+ * assigned nullish values across returned aliases. This deliberately retains
+ * absence when the checker cannot prove a read excludes it.
+ */
+export declare const createBagAbsenceResolver: (checker: ts.TypeChecker, ownerOf: (expression: ts.Expression) => ts.Node | null, calleeOf: (expression: ts.Expression) => ts.Node | null, writesTo: ReadonlyMap<ts.Node, readonly ts.Expression[]>, returnsOf: ReadonlyMap<ts.Node, readonly (ts.Expression | null)[]>) => ((node: ts.Node) => readonly BagAbsence[]);

package/dist/semantics/normalize/bag-absence.js

@@ -0,0 +1,42 @@
+import ts from 'typescript';
+/** Absence belongs to a binding, not to the bag object it may later hold.
+ * Follow the same storage aliases as bag inference, preserving initial and
+ * assigned nullish values across returned aliases. This deliberately retains
+ * absence when the checker cannot prove a read excludes it.
+ */
+export const createBagAbsenceResolver = (checker, ownerOf, calleeOf, writesTo, returnsOf) => {
+    const visit = (node, seen) => {
+        if (seen.has(node))
+            return [];
+        const next = new Set(seen).add(node);
+        const join = (nodes) => [
+            ...new Set(nodes.flatMap((value) => (value ? visit(value, next) : ['undefined'])))
+        ];
+        if (ts.isVariableDeclaration(node) || ts.isPropertyDeclaration(node)) {
+            return join([node.initializer ?? null, ...(writesTo.get(node) ?? [])]);
+        }
+        if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) || ts.isNonNullExpression(node))
+            return visit(node.expression, next);
+        if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+            const callee = calleeOf(node.expression);
+            return callee ? join(returnsOf.get(callee) ?? []) : [];
+        }
+        if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node))
+            return join(returnsOf.get(node) ?? []);
+        const type = checker.getTypeAtLocation(node);
+        const arms = type.isUnion() ? type.types : [type];
+        const explicit = arms.flatMap((arm) => (arm.flags & ts.TypeFlags.Null) !== 0 ? ['null'] : (arm.flags & ts.TypeFlags.Undefined) !== 0 ? ['undefined'] : []);
+        if (ts.isIdentifier(node) || ts.isPropertyAccessExpression(node)) {
+            const owner = ownerOf(node);
+            if (owner) {
+                const inferred = visit(owner, next);
+                // A checker flow narrowing can exclude absence; an erased type cannot.
+                if ((type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) === 0)
+                    return inferred.filter((absence) => explicit.includes(absence));
+                return [...new Set([...explicit, ...inferred])];
+            }
+        }
+        return explicit;
+    };
+    return (node) => visit(node, new Set());
+};