@geastack/compiler 1.0.15

package/dist/semantics/normalize/evaluation-order.d.ts

@@ -0,0 +1,16 @@
+import ts from 'typescript';
+/**
+ * A node's children in the order the language evaluates them.
+ *
+ * `ts.forEachChild` yields children in *source* order, which for almost every
+ * node is also evaluation order. A `for` statement is the exception the language
+ * itself defines: the incrementor is written before the body and runs after it.
+ * Walking source order there would give the incrementor a smaller evaluation
+ * index than the body, and any scheduler that breaks a tie by that index would
+ * then run `i++` before the statement that reads `i`.
+ *
+ * This is the one authority on that order. Both the census (which stamps the
+ * index) and the gating pass (which stamps scope membership) walk through it, so
+ * neither can disagree with the other about when something runs.
+ */
+export declare const forEachEvaluationChild: (node: ts.Node, visit: (child: ts.Node) => void) => void;

package/dist/semantics/normalize/evaluation-order.js

@@ -0,0 +1,37 @@
+import ts from 'typescript';
+/**
+ * A node's children in the order the language evaluates them.
+ *
+ * `ts.forEachChild` yields children in *source* order, which for almost every
+ * node is also evaluation order. A `for` statement is the exception the language
+ * itself defines: the incrementor is written before the body and runs after it.
+ * Walking source order there would give the incrementor a smaller evaluation
+ * index than the body, and any scheduler that breaks a tie by that index would
+ * then run `i++` before the statement that reads `i`.
+ *
+ * This is the one authority on that order. Both the census (which stamps the
+ * index) and the gating pass (which stamps scope membership) walk through it, so
+ * neither can disagree with the other about when something runs.
+ */
+export const forEachEvaluationChild = (node, visit) => {
+    // Destructuring evaluates its RHS before evaluating any target reference.
+    // An ordinary assignment still evaluates its LHS reference first.
+    if (ts.isBinaryExpression(node) &&
+        node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+        (ts.isObjectLiteralExpression(node.left) || ts.isArrayLiteralExpression(node.left))) {
+        visit(node.right);
+        visit(node.left);
+        return;
+    }
+    if (ts.isForStatement(node)) {
+        if (node.initializer)
+            visit(node.initializer);
+        if (node.condition)
+            visit(node.condition);
+        visit(node.statement);
+        if (node.incrementor)
+            visit(node.incrementor);
+        return;
+    }
+    ts.forEachChild(node, visit);
+};

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

@@ -0,0 +1,167 @@
+import ts from 'typescript';
+import { type ParameterBindingCensus } from './parameter-bindings.js';
+import { type CollectionBindingCensus } from './collection-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 class FIELD holds, when the program never declares
+ * it and only ever assigns it -- `this.view = null;` in `OrthographicCamera`'s
+ * constructor, reassigned a real object later in `setViewOffset`. TypeScript's
+ * own JS-class inference DOES give `view` a symbol from these assignments
+ * alone (no `view;` field declaration exists anywhere in the class), but
+ * `symbol.declarations` for it is a bare list of the `BinaryExpression`
+ * assignments themselves -- there is no annotation, no initializer at a
+ * single site, nothing else for the checker to read -- and the checker's own
+ * answer for the property lands on `any`.
+ *
+ * This is `local-bindings.ts`'s exact question -- an unannotated storage
+ * location typed by joining every write to it -- asked of a different
+ * DECLARATION KIND. A `let`/`var` cell is keyed by its `VariableDeclaration`
+ * node and filled from `assignmentsBySymbol`; a class field has no
+ * declaration node of its own at all, only a SYMBOL whose every declaration
+ * IS one of the writes. So this module keys directly on that symbol instead
+ * of re-deriving one from a declaration list, and otherwise runs the
+ * identical join: `known(write) ?? resolveExpr(write)` at every assignment's
+ * right-hand side, the shared `joinOfWrites` to settle on one carrier, refuse on
+ * disagreement or unusable evidence, stop at an `as`/`<T>` cast.
+ *
+ * ## Why a field is safe to publish where a bare cell needed care
+ *
+ * `local-bindings.ts`'s own header records why publishing a no-initializer
+ * cell's type at its DECLARATION once manufactured twelve spurious
+ * `binding-read-conversion` obligations: the declare-site and some read of
+ * the same cell answered two different types. That risk was about
+ * INCONSISTENCY between two authorities, not about publishing a write-set
+ * join per se -- and this module inherits the same cure `local-bindings.ts`
+ * used: `typeAt` answers a field's own write sites AND every read that
+ * resolves to the same symbol from the ONE `resolveSymbol` computation, so
+ * the two can never drift apart. A field additionally has no bare
+ * "declare, no initializer" cell state at all -- `producers/bindings.ts`'s
+ * `declare` action is a `let`/`var` idiom; a field is written by an ordinary
+ * property-assignment operation from its very first write, so there is no
+ * analogous zero-value moment this module's answer could contradict.
+ *
+ * ## What it refuses
+ *
+ * Every refusal leaves the field exactly as it is today -- `any`, boxed --
+ * because a wrong type is far worse than a boxed one:
+ *
+ * - any symbol carrying a REAL declaration the program gave a TYPE -- an
+ *   annotated field, one with its own initializer, a JSDoc-typed member, a
+ *   getter/setter: the program already said something, or an existing
+ *   authority already answers it.
+ * - any write whose own type is unusable evidence (`any`/`void`/`never`) or
+ *   otherwise unresolved -- identical to `local-bindings.ts` and
+ *   `parameter-bindings.ts`.
+ * - two or more writes whose types genuinely disagree, tested with
+ *   `derived-expression-type.ts`'s shared `joinOfWrites`: agreement is never
+ *   spelling, and a union of this compiler's own making is a guess nobody
+ *   wrote.
+ * - a field whose resolution depends on itself, directly or through another
+ *   field's/cell's own unresolved write: refused rather than looped.
+ *
+ * ## The second shape: a BARE `field;` declaration
+ *
+ * `class Camera { aspect; }` -- a `PropertyDeclaration` with no annotation,
+ * no initializer and no JSDoc tag -- states that the storage EXISTS and
+ * nothing whatever about what it holds; the checker's own answer for it is
+ * `any`. The original rule turned every `PropertyDeclaration` away on the
+ * reasoning that "TypeScript already reads an unannotated field
+ * declaration's own initializer", which is true of `aspect = 1;` and vacuous
+ * for `aspect;`: there is no initializer to read, so nothing reads anything
+ * and every `camera.aspect` boxes.
+ *
+ * That is the SAME question this module already answers one shape over --
+ * storage the program declared but never typed, filled by the writes the
+ * program makes to it -- so it is answered from the same `resolveSymbol`
+ * join rather than by a second module with a second opinion. The only
+ * difference is where the writes come from: a field with no declaration at
+ * all finds them in `symbol.declarations` (every declaration IS a write),
+ * while a bare-declared field has exactly one declaration and its writes
+ * have to be gathered from the program, exactly as `local-bindings.ts`
+ * gathers a `let` cell's with `assignmentsBySymbol`.
+ *
+ * ## Per-HIERARCHY, deliberately
+ *
+ * Identity here is the SYMBOL, never the spelling -- so a subclass writing
+ * `this.aspect = ...` against a base that declares `aspect;` contributes to
+ * the BASE symbol's join, because TypeScript's own property lookup resolves
+ * that write to the base's declaration. That is the correct scope: there is
+ * ONE storage slot, declared on the base, and every subclass writes it. A
+ * subclass that RE-declares `aspect;` shadows the base slot with a second
+ * symbol and gets its own independent join -- also correct, and also a
+ * consequence of keying on the symbol rather than on the name.
+ *
+ * This complements `subclass-member-overlay-transform.ts` rather than
+ * overlapping it: that transform states a member the base NEVER declares,
+ * from the subclasses that do; this types a slot the base DOES declare and
+ * nobody annotates. A symbol that transform has already given a JSDoc type
+ * is, by the rule above, no longer a candidate here.
+ */
+export interface FieldBindingCensus {
+    /**
+     * The type this node holds, once an unannotated field carries what its
+     * assignments (jointly) produce -- or `null` when nothing here improves on
+     * the checker's/upstream census's own answer. Answers at ANY node whose
+     * resolution passes through a bound field: a `this.field = value` write's
+     * own left-hand side, a `this.field` read, or a chain through either.
+     */
+    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 field's write set instead of a parameter's argument set. */
+    readonly unionArmsAt: (node: ts.Node) => readonly ts.Type[] | null;
+    /**
+     * The narrowed type of a field whose ANNOTATION this census read as an upper
+     * bound -- the field form of `ParameterBindingCensus.statedTypeAt`, and
+     * needed for the identical reason: `structural-layout-type.ts`'s ordinary
+     * census fallback fires only where the checker answered `any` or a vacuous
+     * type, and the whole point of a stated field is that the checker's answer
+     * is a perfectly good structure with one unstated leaf. Answers at the
+     * declaration and at every property access that resolves to it, from the
+     * one `resolveSymbol` computation, so the cell and its reads cannot split.
+     */
+    readonly statedTypeAt: (node: ts.Node) => ts.Type | null;
+    /** How many field symbols this census bound, for measurement. */
+    readonly boundCount: number;
+    /**
+     * Every field symbol 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 says a cell went untyped without saying which.
+     * `census-refusal.ts`'s `censusRefusalCounts` derives the old count-per-
+     * reason map for any reader that still wants that shape.
+     */
+    readonly refusals: readonly CensusRefusal[];
+    /** Why this particular field symbol was not bound. */
+    readonly refusalOf: (symbol: ts.Symbol) => string | null;
+}
+/** A census that binds nothing, for callers that state no program. */
+export declare const emptyFieldBindingCensus: FieldBindingCensus;
+/**
+ * Whole-program census of what every unannotated, assignment-only class
+ * field holds, once every write to it agrees.
+ *
+ * `parameters` is the already-settled, composed census this runs on top of
+ * (parameters + returns + locals, in whatever order `frontend.ts` composed
+ * them) -- asked first at every identifier, exactly as `local-bindings.ts`
+ * asks it first. This module never reopens that fixpoint; it only adds what
+ * none of those authorities could answer because the chain passed through a
+ * field with no declaration of its own.
+ */
+export declare const censusFieldBindings: (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 write discovery reads its edges from it rather
+ * than re-deriving them; see `flow/model.ts`.
+ */
+flow: ValueFlowIndex) => FieldBindingCensus;
+/**
+ * A `ParameterBindingCensus`-shaped view answering from BOTH: `parameters`'s
+ * own answer first, this census's otherwise -- composed exactly as
+ * `local-bindings.ts`'s own `withLocalBindings` is, and meant to sit
+ * immediately after it in `frontend.ts`:
+ *
+ *   const parameters = withFieldBindings(checker, files, withLocalBindings(checker, files, withReturnBindings(...)))
+ */
+export declare const withFieldBindings: (checker: ts.TypeChecker, files: readonly ts.SourceFile[], reachable: ProgramReachability, parameters: ParameterBindingCensus, collections: CollectionBindingCensus | undefined, flow: ValueFlowIndex) => ParameterBindingCensus;