@scriptc/compiler 0.2.9 → 0.2.10

package/dist/frontend/lowering/narrowing-stability.d.ts

@@ -0,0 +1,100 @@
+import * as ts from "../ts7/adapter.js";
+import type { IrType } from "../../ir/ir.js";
+import type { Lowerer } from "./lowerer.js";
+/** Whether TypeScript's control-flow narrowing of a mutable reference still
+ * holds when the narrowed read executes.
+ *
+ * TypeScript narrows property references (`o.p`, `this.a.b`) and bindings
+ * after assignments and tests, and keeps that narrowing across calls: a
+ * callback, method or getter that clears or replaces the property (or a
+ * closure that reassigns the binding) leaves the reference typed by its old
+ * value. Lowering bridges a narrowed union read with an UNCHECKED payload
+ * extraction and folds `?.`, truthiness and `typeof` by the narrowed type,
+ * so such a read would interpret the wrong arm. This analysis decides when
+ * the narrowing is provably current:
+ *
+ * - every property in the reference is construction-only (no store to its
+ *   name anywhere in the program except `this.name = ...` directly in a
+ *   constructor body, no accessor of that name, no reflective or computed
+ *   store into class instances) and the root binding is never assigned
+ *   from another function; or
+ * - nothing between the earliest occurrence of the same reference in the
+ *   use's function and the use can run other code or store the property
+ *   through another reference: no call or construction (except standard
+ *   library operations that cannot call back), tagged template, `await`,
+ *   `yield`, user accessor, user iteration or user conversion hook, and no
+ *   store to a property of the same name through a different reference.
+ *   A loop around the use that starts inside that span contributes its
+ *   whole body, since its back edge reaches the use again.
+ *
+ * TypeScript never carries a property narrowing into a nested function,
+ * and every narrowing (an assignment, test, predicate or assertion of the
+ * reference) is an occurrence of the reference, so a narrowed use always
+ * has one earlier in its own function. Spurious occurrences only move the
+ * span start earlier, which keeps the answer conservative. */
+export declare class NarrowingStability {
+    private readonly lowerer;
+    private files;
+    private programFacts;
+    private readonly facts;
+    private readonly verdicts;
+    private readonly effects;
+    private readonly capturedMutable;
+    private readonly identifierWrites;
+    private readonly widened;
+    private readonly plainContainers;
+    constructor(lowerer: Lowerer);
+    setFiles(files: readonly ts.SourceFile[]): void;
+    /** The declared type a narrowed read in an absence or type test (or in a
+     * slot that accepts that declared type) must observe instead of the
+     * checker's stale narrowing, or null to keep the checker's type. */
+    widenedType(node: ts.Node): ts.Type | null;
+    /** The checker narrows this reference below its declared type, and the
+     * narrowing may be stale at runtime: its read must check the stored
+     * value instead of trusting the narrowed type. */
+    untrusted(node: ts.Node, narrowed: IrType): boolean;
+    private bindingOf;
+    private computeWidened;
+    /** A read in a call or construction argument (directly or inside a literal
+     * argument) reaches the callee's own lowering with the declared type. User
+     * callees coerce any value of their parameter type, and so do the
+     * standard library's generic slots: a parameter typed by a type parameter
+     * (`push(...items: T[])`, `Map.set(key: K, value: V)`) and the console
+     * methods, which format any value. Other standard-library lowerings are
+     * specialized to the argument types programs pass and can refuse the
+     * declared union (`JSON.stringify` of a possibly-undefined value,
+     * `clearInterval` of a nullable handle). Those arguments keep the checker's
+     * narrowing, and maybeNarrow reads them through the checked extraction. */
+    private argumentSlotIsGeneric;
+    private mentionsTypeParameter;
+    /** The type of the accessed property as declared on the receiver's
+     * (instantiated) type, before any flow narrowing of this reference. */
+    private declaredPropertyType;
+    private trusted;
+    private computeTrusted;
+    /** The root binding can change between the narrowing and the use, or
+     * names a namespace whose exported bindings are assigned as variables
+     * (invisible to the member-store census). */
+    private rootCapturedMutable;
+    /** No intervening code between the reference's earliest occurrence in
+     * the use's function and the use can change it. */
+    private currentSinceNarrowing;
+    private isPlainContainerWrite;
+    private constructionOnly;
+    /** A `let`/`var`/parameter binding assigned from a function other than
+     * the one that declares it: any call may change it. */
+    private isCapturedMutable;
+    private writesIn;
+    private program;
+    private functionFacts;
+    /** Whether evaluating this candidate can run code other than standard
+     * library operations that cannot call back into the program. */
+    private isEffect;
+    private computeEffect;
+    private isInertLibraryCall;
+    private isInertConstruction;
+    /** No argument is a function the callee could invoke. */
+    private inertArguments;
+    private isPrimitive;
+    private isBuiltinIterable;
+}