@geastack/compiler 1.0.15

package/dist/semantics/normalize/keyof.js

@@ -0,0 +1,110 @@
+const resolved = (id) => ({ kind: 'resolved', id });
+const unmodelled = (reason) => ({ kind: 'unmodelled', reason });
+export const createKeyofResolver = (table) => {
+    /** The literal (or unique-symbol) key type `keyof` contributes for one member. */
+    const literalKeyShapeOf = (key) => key.kind === 'symbol'
+        ? { kind: 'unique-symbol', declaration: key.declaration }
+        : key.kind === 'number'
+            ? { kind: 'literal', primitive: 'number', text: String(key.value) }
+            : { kind: 'literal', primitive: 'string', text: key.value };
+    const anyKeyDomain = () => table.intern({
+        kind: 'union',
+        members: [
+            table.intern({ kind: 'primitive', primitive: 'string' }),
+            table.intern({ kind: 'primitive', primitive: 'number' }),
+            table.intern({ kind: 'primitive', primitive: 'symbol' })
+        ]
+    });
+    /**
+     * `keyof T`'s shape, read back from `T`'s own already-interned shape rather
+     * than re-derived from the checker.
+     *
+     * By the time `typeOf` is asked for a genuine `keyof` node at all, `T`'s
+     * keys were *not* statically enumerable to the checker: whenever they are,
+     * TypeScript collapses `keyof T` into an ordinary union of literal key
+     * types before this layer ever sees it (verified against the checker
+     * directly -- `keyof` of a closed interface, of a union, and of an
+     * intersection of two closed interfaces all arrive already resolved to a
+     * plain `UnionType`, matched by the earlier `type.isUnion()` branch, not by
+     * this one). So the honest cases here are: `T` is a bare type parameter (no
+     * member set exists to name yet), `T` is `any`/`unknown`/`never` (whose
+     * `keyof` is a fixed answer the language states outright, not derived from
+     * any member list), or `T` is some other deferred construct this layer does
+     * not expand. Everything else -- a plain record reached through some other
+     * path that still left it deferred -- is resolved exactly, by reading the
+     * same member keys the record's own shape already published: a symbol key
+     * becomes the identical `unique-symbol` anchor its member carries, so two
+     * mentions of `keyof` on the same shape and a direct read of that member's
+     * key stay one identity instead of acquiring two.
+     */
+    const keyofOfShapeId = (id) => {
+        const shape = table.get(id).shape;
+        switch (shape.kind) {
+            case 'object': {
+                // An index signature's own key domain, unioned with the literal keys
+                // the declared members contribute -- which is what the language
+                // answers, not an approximation of it. `keyof { [k: string]: V }` is
+                // `string | number`: TypeScript admits a numeric key wherever a string
+                // index does, because a property access `x[0]` on such a type is legal
+                // and its key stringifies. A NUMBER index alone admits only `number`,
+                // and a symbol index only `symbol`.
+                //
+                // A literal member key is dropped when an index already covers its
+                // domain, for the same reason TypeScript reduces `string | "a"` to
+                // `string`: keeping both would publish a union whose arms overlap, and
+                // an overlapping union is what a tagged-union carrier cannot discriminate.
+                //
+                // This used to be refused outright. The refusal was honest about the
+                // risk (a silently narrow key domain) but it is not narrow to state the
+                // domain the language states, and mongodb's `Document` -- an index
+                // signature with no declared members -- put it behind 78 of the probe's
+                // mandatory obligations.
+                const indexed = (key) => shape.index.some((one) => one.key === key && !one.finite);
+                const primitive = (name) => table.intern({ kind: 'primitive', primitive: name });
+                const domain = [];
+                if (indexed('string'))
+                    domain.push(primitive('string'), primitive('number'));
+                else if (indexed('number'))
+                    domain.push(primitive('number'));
+                if (indexed('symbol'))
+                    domain.push(primitive('symbol'));
+                const absorbed = (key) => key.kind === 'symbol' ? indexed('symbol') : key.kind === 'number' ? indexed('number') || indexed('string') : indexed('string');
+                const memberIds = shape.members
+                    .filter((member) => !absorbed(member.key))
+                    .map((member) => table.intern(literalKeyShapeOf(member.key)));
+                const keys = [...new Set([...domain, ...memberIds])];
+                if (keys.length === 0)
+                    return resolved(table.intern({ kind: 'primitive', primitive: 'never' }));
+                const [only] = keys;
+                return resolved(keys.length === 1 && only ? only : table.intern({ kind: 'union', members: keys }));
+            }
+            case 'declared':
+            case 'class-instance':
+                return shape.body
+                    ? keyofOfShapeId(shape.body)
+                    : unmodelled(`keyof of declaration ${shape.declaration} without a structural body is not modelled`);
+            case 'primitive':
+                // `keyof any` and `keyof never` both name the entire key domain --
+                // nothing is known about the value, so every property-key type is
+                // admissible. `keyof unknown` is the opposite extreme: nothing can be
+                // read off an `unknown` value at all, so its key domain is empty.
+                if (shape.primitive === 'any' || shape.primitive === 'never')
+                    return resolved(anyKeyDomain());
+                if (shape.primitive === 'unknown')
+                    return resolved(table.intern({ kind: 'primitive', primitive: 'never' }));
+                return unmodelled(`keyof of primitive ${shape.primitive} is not modelled`);
+            case 'type-parameter':
+                return unmodelled(`keyof of type parameter ${shape.declaration} without a resolved base is not modelled`);
+            default:
+                // A union, an intersection, an array/tuple, a signature, and an
+                // already-`unresolved` base all have a real `keyof` answer in the
+                // language (distributed key intersection/union for the first two, the
+                // element/prototype key set for the rest) that this layer does not
+                // derive; naming the base's own kind is what tells a caller which
+                // capability is missing, rather than folding every one of them into
+                // one opaque "not modelled" reason.
+                return unmodelled(`keyof of a ${shape.kind} base is not modelled`);
+        }
+    };
+    return keyofOfShapeId;
+};

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

@@ -0,0 +1,176 @@
+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 CommonJsModuleRecordCensus } from './commonjs-module-record.js';
+import { type CensusRefusal } from './census-refusal.js';
+/**
+ * The type an unannotated `let`/`var` cell holds, when the program never
+ * initializes it and fills it in later -- `let extensions, capabilities,
+ * state, info;` followed by `extensions = new WebGLExtensions( _gl );` deeper
+ * in the same module, three.js's `WebGLRenderer.js`'s own idiom for emulating
+ * a private module scope inside one constructor.
+ *
+ * `parameter-bindings.ts` already computes this exact join internally
+ * (`writeSetTypeOf`, gated by its own `lateAssignment` flag) but never
+ * PUBLISHES it: its own header comment records why -- publishing a cell with
+ * no initializer at its DECLARATION manufactured twelve new
+ * `binding-read-conversion:...` obligations the one time it was tried
+ * ungated. This module exists to make that publication safe rather than to
+ * abandon it, by keeping the one invariant `binding-read-conversion`
+ * (`preflight/obligations-graph.ts`'s `buildBindingReadObligations`) actually
+ * checks: a cell's declared carrier and EVERY read's carrier must agree, or a
+ * conversion obligation appears where none existed before. The failure mode
+ * that produced twelve obligations was an INCONSISTENCY -- the declaration
+ * answered one type and some read of the same cell answered a different one
+ * (most likely because the declaration was typed but not every reference was)
+ * -- not a defect in the join itself. This module answers `typeAt` for the
+ * declaration AND for every read that resolves through it with the SAME
+ * computation, so the two can never drift apart the way that experiment did.
+ *
+ * Every type this module produces comes out of the checker, at the RIGHT-HAND
+ * SIDE of a real assignment the program wrote -- never invented, and never the
+ * declaration's own (nonexistent) initializer.
+ *
+ * ## Why this needs its own resolver, not just `parameters.typeAt`
+ *
+ * `WebGLCapabilities`'s constructor reads `state.buffers` where `state` is
+ * itself one of these late-filled cells: `parameters.typeAt` (the composed
+ * parameter+return census) already walks a property access down to its
+ * receiver internally, but only ever bottoms out where ITS OWN authority
+ * stops -- a parameter, or (via the return census) a return expression -- and
+ * answers `null` the moment the chain passes through a cell with no
+ * initializer, exactly the gap this module fills. Since that walk is private
+ * to `parameter-bindings.ts` and not exported, this module runs the identical
+ * shape of walk itself (`return-bindings.ts`'s own `resolveLocalBinding` is
+ * the precedent for doing this rather than reaching into the other file's
+ * internals), asking `parameters.typeAt` FIRST at every identifier and
+ * falling back to this module's own write-set resolution only where that
+ * authority has nothing to say.
+ *
+ * ## What it refuses
+ *
+ * Every refusal leaves the cell exactly as it is today -- `any`, boxed --
+ * because a wrong type is far worse than a boxed one:
+ *
+ * - an annotated declaration, one with an initializer, a destructured name, or
+ *   an ambient one (`declare let x`, whose cell a host owns): none of these is
+ *   this module's to type, either because the program already stated
+ *   something or because `parameter-bindings.ts`'s own `writeSetTypeOf`
+ *   already covers it (an initializer is present).
+ * - a symbol with no assignment anywhere: a cell nothing ever writes stays
+ *   exactly the checker's own answer.
+ * - any write whose own type is unusable evidence (`any`/`void`/`never`) or
+ *   otherwise unresolved, the identical rule every other census in this
+ *   compiler applies, and a `return`/`as`/`<T>` cast is honoured at face
+ *   value and never read past, matching `parameter-bindings.ts` and
+ *   `return-bindings.ts`.
+ * - two or more writes whose types disagree, tested the identical way two
+ *   call sites or two `return`s must agree elsewhere (`widestOf`): agreement
+ *   is never spelling, and a union of this compiler's own making is a guess
+ *   nobody wrote. Two shapes are NOT a disagreement and are admitted by
+ *   `joinOfWrites` after `widestOf` itself has refused -- a `null`/`undefined`
+ *   write, which states the cell's own ABSENCE rather than a rival type
+ *   (`T | null`, the `optional` carrier this compiler already has), and a set
+ *   of differing LITERALS of one primitive, which is the widening
+ *   TypeScript's own mutable-binding rule would have applied at a
+ *   single-write declaration. See that function's own comment for both.
+ * - a cell whose resolution depends on itself, directly or through another
+ *   cell's own unresolved write: refused rather than looped.
+ */
+export interface LocalBindingCensus {
+    /**
+     * The type this node holds, once an unannotated `let`/`var` cell with no
+     * initializer carries what its assignments (jointly) produce -- or `null`
+     * when nothing here improves on the checker's/upstream census's own answer.
+     *
+     * Answers at a `VariableDeclaration` with no initializer (the cell's own
+     * declaration, which is what `producers/bindings.ts`'s `declare` action
+     * publishes as the cell's carrier) and at any node whose resolution passes
+     * through one -- an identifier reading it, a property access, a call.
+     */
+    readonly typeAt: (node: ts.Node) => ts.Type | null;
+    /** This census's settled local-cell answer, without inherited expression inference. */
+    readonly bindingTypeAt: (node: ts.Node) => ts.Type | null;
+    /** A construction-proven local type that deliberately outranks an upstream usable checker answer. */
+    readonly preferredTypeAt: (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 cell's write set instead of a parameter's argument set. */
+    readonly unionArmsAt: (node: ts.Node) => readonly ts.Type[] | null;
+    /** How many declarations this census bound, for measurement. */
+    readonly boundCount: number;
+    /**
+     * Every declaration or binding-pattern leaf this census could not bind, one
+     * `CensusRefusal` each -- the owner is what makes this a list something
+     * downstream can act on, rather than a count that only says a cell went
+     * untyped. `census-refusal.ts`'s `censusRefusalCounts` derives the old
+     * count-per-reason shape for a caller that still wants it.
+     */
+    readonly refusals: readonly CensusRefusal[];
+    /** Why this particular declaration was not bound. */
+    readonly refusalOf: (declaration: ts.VariableDeclaration) => string | null;
+}
+/** A census that binds nothing, for callers that state no program. */
+export declare const emptyLocalBindingCensus: LocalBindingCensus;
+/**
+ * Whole-program census of what every unannotated, uninitialized `let`/`var`
+ * cell holds, once every assignment to it agrees.
+ *
+ * `parameters` is the ALREADY-SETTLED, composed parameter+return census
+ * (`withReturnBindings(...)`, or `emptyParameterBindingCensus` when none is
+ * available) -- asked first at every identifier, exactly as `return-bindings.
+ * ts`'s own local resolver asks it first. This module never reopens that
+ * fixpoint; it only adds what neither authority could answer because the
+ * chain passed through a cell with no initializer.
+ */
+export declare const censusLocalBindings: (checker: ts.TypeChecker, files: readonly ts.SourceFile[], reachable: ProgramReachability, parameters: ParameterBindingCensus | undefined, 
+/** The same-round array census -- see `return-bindings.ts`'s identical parameter for why, and `frontend.ts`'s `compose`. */
+collections: CollectionBindingCensus | undefined, 
+/**
+ * The whole-program value-flow index -- the ONE walk that states where every
+ * write is. This module's own private write-discovery walk
+ * (`assignmentsBySymbol`) reads its 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 where a WRITE or an
+ * initializer reads one slot off a tracked bag -- `bag.name`, `bag[ k ]` --
+ * as `slotTypeAt`, the one question about a bag whose answer is a plain
+ * `ts.Type` and so the only one this module can consume. See that
+ * accessor's own header.
+ */
+bags?: ObjectBagCensus, 
+/**
+ * The prior OUTER composed view. `parameters` above is the newly rebuilt
+ * parameter+return stage and intentionally contains only those domains; it
+ * cannot carry this local census's own synthesized arms back to itself.
+ * This input is used only as the previous element of the local arm lattice.
+ */
+prior?: ParameterBindingCensus, 
+/** Exact, authenticated `module.exports = callable` proofs for this program's CommonJS modules. */
+moduleRecords?: CommonJsModuleRecordCensus) => LocalBindingCensus;
+/**
+ * A `ParameterBindingCensus`-shaped view answering from BOTH: `parameters`'s
+ * own answer first, this census's otherwise -- the seam meant for
+ * `frontend.ts`, composed exactly as `return-bindings.ts`'s own
+ * `withReturnBindings` is: swap
+ *
+ *   const parameters = withReturnBindings(checker, files, censusParameterBindings(checker, files))
+ *
+ * for
+ *
+ *   const parameters = withLocalBindings(checker, files, withReturnBindings(checker, files, censusParameterBindings(checker, files)))
+ *
+ * and the rest of the pipeline (`createStructuralMapper` and everything past
+ * it) is unchanged.
+ */
+export declare const withLocalBindings: (checker: ts.TypeChecker, files: readonly ts.SourceFile[], reachable: ProgramReachability, parameters: ParameterBindingCensus, collections: CollectionBindingCensus | undefined, 
+/** The whole-program value-flow index -- see `censusLocalBindings`'s own parameter. */
+flow: ValueFlowIndex, 
+/** The same-round property-bag census -- see `censusLocalBindings`'s own parameter. */
+bags?: ObjectBagCensus, 
+/** The prior outer view carrying this domain's own arm facts. */
+prior?: ParameterBindingCensus, moduleRecords?: CommonJsModuleRecordCensus) => ParameterBindingCensus;