@geastack/compiler 1.0.15

package/dist/semantics/normalize/flow/callable-reach.d.ts

@@ -0,0 +1,237 @@
+import ts from 'typescript';
+import { type SourceClass, type ValueFlowIndex } from './model.js';
+import { type ExactClassAllocationOrigins } from './member-call-forwarding.js';
+import { type CallableArrayOriginAuthority } from './callable-array-origins.js';
+import { type SourceInvocationFact } from './invocation-facts.js';
+import { type ComputedKeySetAuthority } from './computed-key-set.js';
+/**
+ * The two transitive questions about a FUNCTION VALUE that no census could
+ * answer for itself: which callables can reach a call's callee position, and
+ * which calls can reach a callable.
+ *
+ * Every write-discovery census asks the same thing about a callable it wants
+ * to type from its callers -- "have I seen ALL of them?" -- and each answered
+ * it with a private, purely LOCAL test: is every mention of this function's
+ * own name a call I already counted? That test is right about what it can see
+ * and blind to one whole shape of program:
+ *
+ *     function each( list, cb ) { for (...) cb( list[ i ] ); }
+ *     each( items, function ( item ) { ... } );
+ *
+ * `cb`'s callers are enumerable and `cb( list[i] )` is the callback's ONLY
+ * caller -- but the two facts live one indirection apart, so a census looking
+ * at the callback sees a value handed to a caller it cannot name, and a census
+ * looking at `cb( ... )` sees a call whose callee has no declaration. Measured
+ * on the three.js app: 169 unannotated parameters are refused
+ * `function-escapes:unnamed:CallExpression` for exactly this, and every one of
+ * them is a `function-value-dispatch` ABI publishing `dynamic` for a
+ * parameter whose real type the program states at the call.
+ *
+ * ## What makes an answer here SOUND
+ *
+ * A wrong parameter type is a silent miscompile; a dynamic one is a box. So
+ * this layer answers only when it can prove CLOSURE -- that the set it
+ * reports is complete, not merely non-empty -- and otherwise refuses BY NAME.
+ * Two independent closures are needed and both are proved, never assumed:
+ *
+ * 1. **The callable's value goes nowhere else.** Only a callable written
+ *    directly in an argument position qualifies here: such an expression node
+ *    occurs once in the whole program and is named by nothing, so the
+ *    parameter slot it lands in is provably the only place its value can be.
+ *    A callable reached by NAME does not qualify -- a name can be imported
+ *    into another module, where it resolves to an alias symbol this index
+ *    files under a different key, so "no other mention" would be a claim
+ *    about the current module rather than the program.
+ * 2. **Every mention of the receiving slot is explained.** A parameter is the
+ *    one cell kind for which that is decidable cheaply and completely: it is
+ *    scoped to one function body and no import, export or property lookup can
+ *    name it, so `referencesToDeclaration` really is all of them. Each is
+ *    either a CALL through the slot (evidence) or a mention that provably
+ *    cannot call or leak the value (`if ( cb )`, `typeof cb`, `cb !== null`).
+ *    Anything else -- `h( cb )`, `this.saved = cb`, `cb.bind( ... )`,
+ *    `cb || noop` (which yields the value onward) -- means the value reaches
+ *    somewhere unenumerated, and the callable stays refused.
+ *
+ * Both are stated over the shared flow index rather than re-walked here, so
+ * this composes edges the index already publishes (`call-argument` for the
+ * write, `referencesToDeclaration` for the mentions) instead of adding a
+ * seventh private walk. It performs no type query, only symbol resolution, so
+ * -- like the index itself -- it is a fixed property of the program and safe
+ * to build once, ahead of every census round.
+ */
+export interface CallableReachIndex {
+    /**
+     * Every call that can reach this callable through a cell, or `null` when
+     * this layer cannot prove the set is CLOSED.
+     *
+     * `null` is the normal answer and the safe one: it means "no proof", and a
+     * consumer must then keep whatever refusal it already had. A non-null answer
+     * is a proof that these are ALL of the callable's callers apart from the
+     * direct, syntactically-named ones its consumer already enumerates itself.
+     */
+    readonly enumeratedCallSitesOf: (declaration: ts.SignatureDeclaration) => readonly ts.CallExpression[] | null;
+    /**
+     * Every callable a call's callee position can reach, for a callee the
+     * checker resolves to no declaration.
+     *
+     * Unlike `enumeratedCallSitesOf` this needs no closure proof, because it
+     * only ever ADDS evidence: a call that may dispatch into any of several
+     * callables is a call site of each, exactly as a virtual call is a call site
+     * of every override, and a consumer joining that evidence either agrees or
+     * refuses on disagreement. Missing some of the set weakens the answer;
+     * it cannot falsify one.
+     */
+    readonly calleesOf: (call: ts.CallExpression) => readonly ts.SignatureDeclaration[];
+    /** How many callables this layer proved closed, for measurement. */
+    readonly closedCount: number;
+    /** Why each candidate callable was refused, counted by reason -- so a low count has an attribution rather than a guess. */
+    readonly refusals: ReadonlyMap<string, number>;
+}
+/** A layer over no program, for callers that state none. */
+export declare const emptyCallableReachIndex: CallableReachIndex;
+/** A newly inferred inline member callback needs every value use accounted
+ * for. Method-name references alone are insufficient: `consume(obj.hook)` is
+ * an escape even though the name is part of a normal property access. Follow
+ * local aliases only to classify their complete shared reference inventory;
+ * calls through an alias must still appear in the caller's counted set. */
+interface ClosedValueMode {
+    readonly roots: readonly ts.Expression[];
+    readonly terminalUse: (reference: ts.Expression) => boolean | null;
+    /**
+     * What this value question IS, for the proof memo. A caller that mints
+     * `roots` and `terminalUse` afresh per call (every record-root proof does)
+     * hands the memo a key no later call can match; naming the question by
+     * content lets the same record family under the same key share one answer.
+     * Omitted, the mode object itself is the key.
+     */
+    readonly identity?: string;
+    /**
+     * A re-entrancy park the CALLER established for this very question and
+     * releases the moment this proof returns. It is this proof's own
+     * coinduction, exactly like `member` and its families: the answer is the
+     * greatest fixpoint over "assume this question true", not a fact borrowed
+     * from an enclosing proof. Naming it here is what lets `share` discharge
+     * it instead of recording it as an assumption -- and that distinction is
+     * the whole value of the memo, because every one of these parks is a
+     * freshly allocated object that no later call can ever present again.
+     */
+    readonly ownPark?: object;
+    /** Where mentions are anchored when there are no roots (`closedCallableAuthorityOf`). */
+    readonly anchor?: ts.Node;
+    /** A consumer with finalized intrinsic identities may discharge this directly. */
+    readonly explicitInvocationIsIntact?: (call: ts.CallExpression) => boolean;
+    /** Handed this proof's own frame and caller queries before the walk runs. */
+    readonly expose?: (authority: ClosedInvocationAuthority) => void;
+    readonly exposeOrigins?: (authority: ClosedValueOriginAuthority) => void;
+    /** A data-slot proof follows every instance of these owners. Its field
+     * contents are collected separately from the uses of the owning object. */
+    readonly field?: {
+        readonly owners: ReadonlySet<SourceClass>;
+        readonly key: string;
+    };
+}
+/** Complete value sources from one shared caller, receiver and slot proof.
+ * @semanticCategory generic-primitive
+ */
+export interface ClosedValueOriginAuthority {
+    readonly bindingValuesOf: (declaration: ts.VariableDeclaration) => readonly ts.Expression[] | null;
+    readonly classAllocationsOf: (expression: ts.Expression) => ExactClassAllocationOrigins | null;
+    readonly parameterValuesOf: (parameter: ts.ParameterDeclaration) => readonly ts.Expression[] | null;
+    readonly fieldValuesOf: (expression: ts.PropertyAccessExpression | ts.ElementAccessExpression) => readonly ts.Expression[] | null;
+}
+export declare const closedValueOriginAuthorityOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, anchor: ts.Expression) => ClosedValueOriginAuthority;
+/** Allocation origins with the shared closed-frame and source-slot authority. */
+export declare const closedClassAllocationOriginsOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, expression: ts.Expression) => ExactClassAllocationOrigins | null;
+/**
+ * This module's own frame and caller queries -- `parameterValuesOf` and
+ * `closedCallerSitesOf`, the same closures every proof here asks -- for a
+ * consumer that has to pass a real `ClosedCallableAuthority` (the host
+ * mutation census, `class-family-member-read`, `array-element-continuation`,
+ * `computed-key-set`). Each call opens one proof context whose memos the two
+ * closures share; hold one per flow index and census round, never across
+ * rounds. A program with no call, class or array literal has no frame to
+ * answer for, and every query refuses.
+ */
+/** @semanticCategory generic-primitive */
+export interface ClosedInvocationAuthority extends ComputedKeySetAuthority {
+    /** Complete source bodies entered by this call, including member receivers. */
+    readonly invocationFactOf: (call: ts.CallExpression) => SourceInvocationFact | null;
+    /** The call throws before entering any body: its callee cell only ever holds `null`/`undefined`. */
+    readonly callThroughUncallable?: (call: ts.CallExpression | ts.NewExpression) => boolean;
+    /**
+     * Every source body this call's callee can denote, established from the
+     * ALLOCATION the receiver traces to -- never from a name match on a
+     * candidate body -- or null where that set cannot be closed. This is
+     * `invocationFactOf`'s own target selection, exposed on its own: a caller
+     * that only needs "which bodies can this call enter" (a host-mutation
+     * census asking whether a call can reach anything outside this program)
+     * must not also demand `invocationFactOf`'s stricter promise, a complete
+     * argument-forwarding frame for every one of those bodies. Three's
+     * `properties.get( material )` -- `WebGLProperties()` is a plain factory
+     * function returning `{ get: get, ... }`, so `new WebGLProperties()` types
+     * `any` under the checker's own JS-constructor inference and no checker
+     * declaration ever names this call's callee -- closes here exactly because
+     * target identity is a separate fact from frame modelling.
+     */
+    readonly closedCalleeBodiesOf?: (call: ts.CallExpression) => readonly ts.SignatureDeclaration[] | null;
+}
+export declare const closedCallableAuthorityOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, receiverTypeAt: (expression: ts.Expression) => ts.Type | null, argumentsUsesAt: (declaration: ts.SignatureDeclaration) => readonly ts.Identifier[] | undefined, explicitInvocationIsIntact?: (call: ts.CallExpression) => boolean) => ClosedInvocationAuthority;
+/**
+ * The array-callee extension of `closedCallableAuthorityOf`, for a consumer
+ * that has to pass a real `CallableArrayOriginAuthority` to
+ * `callableArrayTargetsOf` -- three's `EventDispatcher.dispatchEvent` calls
+ * every listener through `array[ i ].call( this, event )`, a computed
+ * element read no symbol names, and closing it needs the same three
+ * collection/protocol queries `closedMemberCallableUses` already builds for
+ * its own local `elementCalleeAuthority` (see the `.call`/`.apply` branch of
+ * `forwardedInvocationUse` above). This is that authority pulled out as a
+ * reusable export, built only from the identical `nativeProtocolClosed`
+ * closure and the base `ClosedCallableAuthority`, so a caller outside this
+ * module's own escape proof -- one with no `member`/`onOpenUse` of its own --
+ * can still ask "every function this array element callee can be".
+ */
+export declare const closedArrayCalleeAuthorityOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, receiverTypeAt: (expression: ts.Expression) => ts.Type | null, argumentsUsesAt: (declaration: ts.SignatureDeclaration) => readonly ts.Identifier[] | undefined) => CallableArrayOriginAuthority;
+/** Follow every use of an explicit value family using the same publication
+ * graph as member closure, with protocol-specific terminal observations. */
+export declare const hasClosedValueUses: (checker: ts.TypeChecker, flow: ValueFlowIndex, roots: readonly ts.Expression[], terminalUse: ClosedValueMode["terminalUse"], receiverTypeAt: (expression: ts.Expression) => ts.Type | null, argumentsUsesAt: (declaration: ts.SignatureDeclaration) => readonly ts.Identifier[] | undefined, onOpenUse?: (reference: ts.Expression, kind: "receiver" | "containing-object" | "member-reference-inventory" | "member-receiver-inventory") => void, identity?: string, ownPark?: object) => boolean;
+export declare const memberProofStats: () => string;
+export declare const hasClosedMemberCallableUses: (...parameters: Parameters<typeof closedMemberCallableUses>) => boolean;
+declare const closedMemberCallableUses: (checker: ts.TypeChecker, flow: ValueFlowIndex, member: ts.Symbol | null, countedCalls: ReadonlySet<ts.CallExpression | ts.NewExpression>, givenReceiverTypeAt: (expression: ts.Expression) => ts.Type | null, argumentsUsesAt: (declaration: ts.SignatureDeclaration) => readonly ts.Identifier[] | undefined, givenOpenUse?: (reference: ts.Expression, kind: "receiver" | "containing-object" | "member-reference-inventory" | "member-receiver-inventory") => void, activeMembers?: ReadonlySet<ts.Symbol>, activeFamilies?: ReadonlySet<SourceClass>, valueMode?: ClosedValueMode) => boolean;
+/**
+ * How a single mention of a cell is classified: it either calls through the
+ * cell, provably does nothing with the value, or hands it somewhere this
+ * layer cannot follow.
+ */
+type Mention = {
+    readonly kind: 'call';
+    readonly call: ts.CallExpression;
+} | {
+    readonly kind: 'inert';
+} | {
+    readonly kind: 'open';
+    readonly reason: string;
+};
+/**
+ * What this mention of a cell does with the cell's value.
+ *
+ * Everything not positively recognised is `open`. That direction matters: an
+ * unrecognised position could be a call this layer never counted, and a
+ * consumer binding a parameter from an incomplete caller set binds it from a
+ * guess. `&&`/`||`/`??` are deliberately NOT inert -- they yield the operand's
+ * own value onward, so `cb || noop` reaches wherever that result goes.
+ */
+declare const classifyMention: (checker: ts.TypeChecker, reference: ts.Expression, declarationName: ts.Node) => Mention;
+export { classifyMention as classifyCallableMention };
+/**
+ * Compose the index's `call-argument` edges with its mention lists into the
+ * two transitive answers above.
+ *
+ * Reads the index and no second walk -- every EDGE this needs is one `flow`
+ * already published. The one checker call it does make is
+ * `classifyMention`'s receiver-is-callable test above, asked at a mention the
+ * index already located rather than a fresh walk of its own, and (like
+ * `flow/value-flow.ts`'s own equivalent addition) a fixed property of the
+ * program: a reference's own static type does not change as any census
+ * composes more evidence.
+ */
+export declare const indexCallableReach: (checker: ts.TypeChecker, flow: ValueFlowIndex) => CallableReachIndex;