monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/analysis/lib/reachability.d.ts

@@ -0,0 +1,137 @@
+import type { Realm, SerializedCatalog } from '../../../catalog.ts';
+import { type AstNode } from './ast.ts';
+import type { Caps } from './budget.ts';
+import { type GlobalResolution, type Position } from './global-object.ts';
+import { type Starts } from './line-starts.ts';
+import { type ScopeRules } from './scope.ts';
+import { type Binding } from './summaries.ts';
+import type { CreationSiteStep, GeneratedLocation, GuardStep, Reachability, ReachabilityBasis } from './types.ts';
+/** Two guards on one path (AND): `config.polyfill && !window.fetch` is `guarded-native-absence` (§7). */
+export declare function along(a: Reachability, b: Reachability): Reachability;
+/** Two alternatives (OR): the most-reaching, so `!window.fetch || force` is `conditional` (§7). */
+export declare function across(a: Reachability, b: Reachability): Reachability;
+export interface GuardContext {
+    resolution: GlobalResolution;
+    scope: ScopeRules;
+    catalog: SerializedCatalog;
+    realm: Realm;
+    /** The realm's global holder, e.g. `Window`. */
+    global: string;
+    /** The host artifact's text and line-start table. */
+    text: string;
+    starts: Starts;
+    /** The node a node is a child of, to judge a test that reads a parameter with the arguments of its call. */
+    parentOf?: (node: AstNode) => AstNode | undefined;
+    /**
+     * The resolved call the function the path is in is judged under, when it has no frame: a test of one of its
+     * parameters is judged as the argument this call passes (§7).
+     */
+    call?: Binding | undefined;
+    /** The caps (§18): `testReads` and `throwDepth` here. */
+    caps: Pick<Caps, 'testReads' | 'throwDepth'>;
+    /** Counts a hit of one of them, at the node where it cut (§18). */
+    capHit(name: 'testReads' | 'throwDepth', node: AstNode): void;
+}
+/**
+ * The write a reachability is judged for: its site, its target, and the `with` statements and direct `eval` calls on
+ * the resolution paths of its names (§5 post-pass 3), whose taint makes it `unknown` (§7).
+ */
+export interface Judged {
+    site: AstNode;
+    target: {
+        name: string;
+        shadows?: string;
+    };
+    taints: readonly GeneratedLocation[];
+}
+/**
+ * A write's reachability, and the `guard` steps (§14) of the guards on its path, outermost first, with a `creation-site`
+ * step where the path goes out through where a caller-less function was created. `tests` maps each test a guard step
+ * was made for to its step. `dead` is set when a statically false catalog check on the path means the write never runs
+ * (§7 Checking guards against the catalog): the test that decides it. `basis` is how it was judged (§7), `call-path`
+ * when left out.
+ */
+export interface Judgement {
+    reachability: Reachability;
+    steps: (GuardStep | CreationSiteStep)[];
+    tests: ReadonlyMap<AstNode, GuardStep>;
+    dead?: AstNode;
+    /** For a `dead` test a call argument literal's field settled: that literal, which a `prune` step names. */
+    by?: AstNode;
+    /**
+     * The install entry the write waits on when it is `deferred` (§7 Install context): the function with no resolved
+     * caller that every live chain out from the write ends at. Absent when a chain reaches top-level code (`load`).
+     */
+    entry?: AstNode;
+    basis?: ReachabilityBasis;
+}
+/**
+ * The reachability of a write, judged from the guards between it and the start of its function (§7). `path` is the
+ * walk's ancestors of the node that makes the write, outermost first, ending with that node.
+ */
+export declare function judge(path: readonly AstNode[], write: Judged, at: Position, context: GuardContext): Judgement;
+/**
+ * The `catch` arms whose `try` block can't throw (§5 Resolver capabilities 9): a
+ * write only such an arm reaches never happens, so it gives nothing, but the resolver counts it as a `prune`.
+ */
+export declare const unreachedArms: WeakSet<AstNode>;
+/**
+ * The tests that are filters on a swept key (§5 Resolver capabilities 9): a write such a test drops is no write of
+ * that key at all, so it gives nothing, and no `prune` counts it.
+ */
+export declare const sweepFilters: WeakSet<AstNode>;
+/**
+ * The tests a call argument literal's field decides against the path (§5 Resolver capabilities 5): the arm they
+ * rule out is not reached, so a write there gives nothing, but the resolver counts it as a `prune`.
+ */
+export declare const ruledOutTests: WeakSet<AstNode>;
+/**
+ * The `guard` steps of tests a call argument literal's field settled the way the path needs, each with the test
+ * and that literal: a write that only the arm the test rules out reaches leaves a `prune` step after it.
+ */
+export declare const argumentGuards: WeakMap<GuardStep, {
+    test: AstNode;
+    literal: AstNode | undefined;
+}>;
+/** The tests that are filters on a swept key, which the sweep's `enumeration` step records (§14). */
+export declare const sweepTests: WeakSet<AstNode>;
+/** The path from the top of the function a node is in down to the node, outermost first. */
+export declare function functionPath(node: AstNode, parentOf: (node: AstNode) => AstNode | undefined): AstNode[];
+/** What judging along call chains needs besides the guards' context: the resolved calls of a function. */
+export interface ChainContext extends GuardContext {
+    /** The resolved calls of a function, each with its caller's frame when the resolver has one. */
+    callers(fn: AstNode): readonly Binding[];
+    parentOf(node: AstNode): AstNode | undefined;
+    /** For the function a direct eval's code is grafted in as, the eval call that runs it where the call is (§2). */
+    runBy?(fn: AstNode): AstNode | undefined;
+    /**
+     * For the function a link group's member runs in, the dynamic imports that load it, when only they do (§6 Link
+     * groups): the code runs where an import is, after its guards, but never at load.
+     */
+    loadedBy?(fn: AstNode): readonly AstNode[] | undefined;
+    /**
+     * For a factory a lazy chunk pushes into a chunk registry, the function its chunk runs in (§6 idiom 6): code reached
+     * only through a chunk load waits on it, even when its module is required at top level.
+     */
+    chunkOf?(fn: AstNode): AstNode | undefined;
+}
+/**
+ * Judges writes along their call chains (§7): the guards on a write's path in the function it is in, AND the chain out
+ * from there, with the `guard` steps of the alternative that gives it, outermost first. The chain ends at top-level
+ * code, the install entry, with basis `call-path`.
+ *
+ * A function with no resolved caller, or one reached only through itself, is no install entry: it is judged from its
+ * **creation site** (ADR 0013), the reachability of the code that created it AND the guards in force where it was
+ * created, then its own guards, with basis `creation-site` and a `creation-site` step after the creation path's guards.
+ * A creation that no code reaches (after an unconditional `return` or `throw`), or that only the function itself
+ * creates, was never evaluated, and gives `unknown`.
+ *
+ * The guards in a function are judged in its frame when the write is instantiated in one. Otherwise each resolved call
+ * of the function is an alternative of its own, and a test of a parameter is judged as the argument that call passes.
+ */
+export declare function chainJudge(context: ChainContext): (path: readonly AstNode[], write: Judged, at: Position, fn: AstNode | undefined) => Judgement;
+/**
+ * The name of an install entry (§7 Install context): the function's own name, else the name it is bound to where it is
+ * created (a variable, an assigned member, an object's property or a class's method), else null.
+ */
+export declare function entryName(fn: AstNode, parentOf: (node: AstNode) => AstNode | undefined): string | null;