monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/analysis/lib/global-object.d.ts

@@ -0,0 +1,581 @@
+import type { Realm, SerializedCatalog } from '../../../catalog.ts';
+import { type AstNode } from './ast.ts';
+import { type Key } from './keys.ts';
+import { type Definitions } from './definitions.ts';
+import type { ModuleLink, ModuleLinks } from './module-links.ts';
+import { type GlobalBinding, type ScopeRules, type Taint } from './scope.ts';
+import { type Binding, type CallGraph, type Frame } from './summaries.ts';
+import type { Caps } from './budget.ts';
+import type { GlobalForm, RealmInstance } from './types.ts';
+/**
+ * How an expression reached a native holder (§14): where the global object was recognized, and in which form, or the
+ * step from another value that reached it (a singleton, or another window), after that value's own leaves.
+ */
+export interface Leaf {
+    /**
+     * How the holder was reached: one of the global forms (§5), or `prototype-of`, `Object.getPrototypeOf(h)` of a native
+     * holder, which the unmutated catalog decides (§4).
+     */
+    form: GlobalForm | 'prototype-of';
+    /** The node recognized: an identifier, a `this`, or the `Function('return this')()` call. */
+    node: AstNode;
+    /** The name the form starts from: `window`, `global`, `this`, `Function`, `XMLHttpRequest`; `[0]` for an index read. */
+    name: string;
+    /** For a name, how it resolved: to no declaration, or to one that binds the global object's property (§5). */
+    binding?: GlobalBinding;
+    /** For a global property, the holder the catalog says its value is; for a singleton, the singleton. */
+    holds?: string;
+    /** For a singleton, the access path from the global object its alias group lists (`document.location`). */
+    path?: string;
+    /** For a `typeof`-guarded `global`, the test that guards it. */
+    guard?: AstNode;
+    /** The outermost `?:`, `||`, `&&` or `??` chain the leaf was selected through. */
+    chain?: AstNode;
+    /** The window the value belongs to: the artifact's own (`current`), another (`other`), or either (`unknown`). */
+    instance: RealmInstance;
+    /** For a step from another value (`window.parent`), the leaves that value was reached from. */
+    base?: Leaf[];
+    /**
+     * For another window, the window expression it is (§3 Undecidable outcomes), as a key: `~.parent`, `~[0]`,
+     * `(#x).contentWindow`. It is undefined when the analyzer can't show that two reads of it reach one window.
+     */
+    window?: string;
+    /** For a child window (an index read on a window), the window expression of the window it is a child of. */
+    childOf?: string;
+    /**
+     * Whether the window was read as the frames collection (§5 Other windows): a bare `frames`, `.frames`, or a constant
+     * `["frames"]`. The mark travels with the value, and reading any other member drops it. Only a window spelled so takes
+     * an unresolved key as a child window.
+     */
+    frames?: true;
+    /**
+     * For `Object.getPrototypeOf(h)`, the holder `h` whose prototype it is. Its `holds` is that prototype, and `base` the
+     * leaves `h` was reached from.
+     */
+    prototypeOf?: string;
+    /** For `Object.getPrototypeOf(h)`, the leaves the native `Object` it calls was reached from. */
+    callee?: Leaf[];
+}
+/**
+ * The window expression a value was reached through (§3 Undecidable outcomes): the window it belongs to, as a key that
+ * two reads of the same window expression share. It is undefined when its leaves disagree, or one reaches a window the
+ * analyzer can't name.
+ */
+export declare function windowOf(leaves: readonly Leaf[]): string | undefined;
+/**
+ * Whether two values were reached through the same window (§3 Undecidable outcomes): the same window expression, which
+ * the analyzer can show reaches one window both times. Only this window stays the same whatever the code does. Another
+ * window expression can reach another window once the program's state changes (`x`, `i` or the frames in
+ * `x.contentWindow` or `frames[i]`, or a replaced `parent`), so it is the same only when nothing `evaluated` around the
+ * two reads can change that state.
+ */
+export declare function sameWindow(a: readonly Leaf[], b: readonly Leaf[], evaluated: readonly AstNode[]): boolean;
+/** The name of the realm's global object holder, e.g. `Window`. */
+export declare function globalHolder(catalog: SerializedCatalog, realm: Realm): string;
+/** Leaves in document order, as a trace lists their binding steps. */
+export declare const inDocumentOrder: (leaves: readonly Leaf[]) => Leaf[];
+/** A primitive constant the analyzer knows: a well-known symbol is one too (§4 Property keys, `keys.ts`). */
+export type Primitive = string | number | bigint | boolean | null | undefined | symbol;
+/**
+ * A fold (§14): an expression the analyzer folded to a constant. It is a `+` or a template literal with constant parts,
+ * or a `const` read through its `name`, whose value comes from `node`: its initializer, the element or property it
+ * destructures, or a default. `taint` is what lies between the name and its declaration (§5 post-pass 3). The trace
+ * records a fold only when JSON can carry its value, but it records a fold's taint whatever the value.
+ */
+export interface Fold {
+    node: AstNode;
+    name?: string;
+    value: Primitive;
+    taint?: Taint;
+    /** For a well-known symbol, the leaves of the `Symbol` holder it was read from, whose steps come before the fold's. */
+    via?: Leaf[];
+    /**
+     * For an alias (§5 Resolver capabilities 2): the value was read through the variable `name`, from its definition
+     * `node` (a declarator, an assignment, an update or a loop head). Its `value` is undefined, and the trace records it as
+     * an `alias` step.
+     */
+    alias?: true;
+    /**
+     * For a summarized call (§5 Resolver capabilities 3): the value was bound to a parameter, or returned, by the call
+     * `node`, whose site and frame this is. Its `name` is `()` and its `value` undefined, and the trace records it as a
+     * `call` step.
+     */
+    call?: Binding;
+    /** For a summarized call's parameter, the index of the argument the value came in through. */
+    argument?: number;
+    /** For a summarized call, that the value is the call's `this`: the receiver of a method, a `new`'s instance. */
+    receiver?: true;
+    /**
+     * For a value read from the heap (§5 Resolver capabilities 5): `node` is the expression that gave the field its value
+     * (a literal's property value, or the value a write assigns). A value that carries one never decides a test. Its
+     * `name` is `.` and its `value` undefined, and the trace records no step for it.
+     */
+    heap?: true;
+    /**
+     * For a heap fold: the value is a field of an object literal passed directly as a call argument, read inside that
+     * call's summary instance (§5 Resolver capabilities 5): the literal, `decides`, whose
+     * field it is. Such a value still decides no test until a test settles it (`settled`): an arm's test, or a `?:`,
+     * `&&`, `||` or `??` selection, once nothing writes to the literal.
+     */
+    decides?: Allocation;
+    /** For a heap fold with `decides`: a test settled it, so the value decides that test. */
+    settled?: true;
+    /**
+     * For a value read through a once-flag (§5 Resolver capabilities 6): `node` is the read. A value that carries one never
+     * decides a test. Its `name` is `?` and its `value` undefined, and the trace records no step for it.
+     */
+    flag?: true;
+    /**
+     * For an own-property test the unmutated catalog decided (§4 A holder chosen at runtime, §5 Resolver capabilities 8):
+     * `node` is the test, and `value` whether the holder owns the member. The trace records it as a `catalog-holder` step.
+     */
+    catalog?: OwnTest;
+    /**
+     * For a prototype walk the unmutated catalog simulated (§4 A holder chosen at runtime): `node` is the loop, and the
+     * walk's holders, in order, end in the one the value is. The trace records it as a `catalog-holder` step.
+     */
+    walked?: WalkChoice;
+    /**
+     * For a module link (§6): the value came through a require call or a module's export, which `node` is. Its `name` is
+     * `module-link` and its `value` undefined, and the trace records it as a `module-link` step.
+     */
+    link?: ModuleLink;
+    /**
+     * For a key a member sweep gave (§5 Resolver capabilities 9): `node` is the enumeration (the call, or the `for…in`
+     * loop's object), and the sweep says which holder, how, which member, and the filters the key went through. Its
+     * `name` is `#` and its `value` the key, and the trace records it as an `enumeration` step.
+     */
+    sweep?: Sweep;
+}
+/** How a member sweep enumerates a native holder's keys (§5 Resolver capabilities 9). */
+export declare const sweepForms: readonly ["for-in", "Object.keys", "Object.getOwnPropertyNames", "Object.entries", "Object.getOwnPropertyDescriptors", "Reflect.ownKeys", "Object.getOwnPropertySymbols"];
+export type SweepForm = (typeof sweepForms)[number];
+/**
+ * A key a member sweep gave (§5 Resolver capabilities 9): the native `holder` swept, the enumeration `form`, the
+ * catalog `member` the key is, as the catalog spells it, and each filter the key went through, in order: `kept` when
+ * the filter keeps it, `undecided` when the analyzer can't tell, which makes reachability `conditional`.
+ */
+export interface Sweep {
+    holder: string;
+    form: SweepForm;
+    member: string;
+    filters: readonly {
+        node: AstNode;
+        result: 'kept' | 'undecided';
+    }[];
+}
+/** The sweeps a value's key came from (§5 Resolver capabilities 9). */
+export declare function sweepsOf(value: Value): Sweep[];
+/** Whether a value carries a key a member sweep gave. */
+export declare const isSwept: (value: Value) => boolean;
+/** A prototype walk's holders from its start value, in order, the `holder` it stops at, and the `member` it looks for. */
+export interface WalkChoice {
+    walk: string[];
+    holder: string;
+    member?: string;
+}
+/**
+ * An own-property test the unmutated catalog decided (§4): whether the native holder `tested` owns `member`, a catalog
+ * member spelt as the catalog spells it (`pushState`, `@@iterator`). With no `member`, the key didn't fold, and the
+ * holder owns no catalog member other than the structural `constructor`, `@@toStringTag` and `prototype`, so it owns
+ * none that counts.
+ */
+export interface OwnTest {
+    tested: string;
+    member?: string;
+    owns: boolean;
+}
+/**
+ * An abstract value: a native holder reached from the global object, with every leaf it was reached from; a primitive
+ * constant; an object the analyzer knows is no native holder (a literal, a function, an instance); or unknown. A holder
+ * or constant carries the folds it comes from, in the order they were made: each after those it folds. A value a
+ * constant decided, such as the branch a `?:` with a constant test takes, carries that constant's folds too.
+ */
+export type Value = 
+/**
+ * `absent`: a native holder read as a property of the global object (`window.EventTarget`, `self.document`), which
+ * may be missing, so a test on it may be falsy (§7). The global object, a bare global
+ * name and a holder read from any other holder are always present.
+ */
+{
+    kind: 'holder';
+    holder: string;
+    leaves: Leaf[];
+    folds?: Fold[];
+    absent?: true;
+}
+/**
+ * `tested`: a heap-read or once-flag boolean, `null` or `undefined` that `&&`, `||` or `??` gives back from its
+ * undecided test operand. It is never a key (§5 Candidate sets).
+ */
+ | {
+    kind: 'constant';
+    value: Primitive;
+    folds?: Fold[];
+    tested?: true;
+} | {
+    kind: 'native';
+    name: NativeName;
+    leaves: Leaf[];
+    folds?: Fold[];
+    sites?: AstNode[];
+}
+/**
+ * `assumed`: an object that is only a caller-less function's assumed `this` (§5 Resolver capabilities 3), the object
+ * it is held on, and whatever reached it only from there. A write through it makes no literal non-constant (§5
+ * Resolver capabilities 4).
+ */
+ | {
+    kind: 'object';
+    heap?: Allocation;
+    folds?: Fold[];
+    assumed?: true;
+} | {
+    kind: 'member';
+    target: string;
+    holder: string;
+    sites: AstNode[];
+    leaves: Leaf[];
+    folds?: Fold[];
+}
+/**
+ * `prefix`: a string the analyzer can't fold whole, but whose start a `+` or a template folds to this non-empty
+ * constant (`'__zone_symbol__' + name`). Everything but a write's key takes it as unknown (§5 Pattern wildcards).
+ */
+ | {
+    kind: 'unknown';
+    prefix?: string;
+};
+export type HolderValue = Extract<Value, {
+    kind: 'holder';
+}>;
+/**
+ * A catalog function read from a native holder (§5 Resolver capabilities 10): `window.fetch`, a bare `fetch`,
+ * `EventTarget.prototype.addEventListener`, as the unmutated catalog has it. `target` is the catalog target the read
+ * reaches on `holder`'s chain, and `sites` the reads that gave it. Only wrap evidence tells it from an unknown value:
+ * everything else treats it as unknown (`opaque`), so it never decides a test.
+ */
+export type MemberValue = Extract<Value, {
+    kind: 'member';
+}>;
+/** Whether a value is one the analyzer treats as unknown: unknown, or a catalog function (`MemberValue`). */
+export declare const opaque: (value: Value) => boolean;
+export type ObjectValue = Extract<Value, {
+    kind: 'object';
+}>;
+export type HeapValue = ObjectValue & {
+    heap: Allocation;
+};
+/**
+ * An allocation site (§5 Resolver capabilities 5): a syntactic site that makes an object, in one summary instantiation
+ * or unrolled loop iteration, `frame`. Its fields are evaluated where it is, at `at`.
+ * - `literal`: an object literal, or `Object.create(null)`, which is treated like `{}`
+ * - `array`: an array literal, whose elements are capability 4's (§5), so only its expandos are heap fields
+ * - `instance`: a `new` expression, whose constructor may give it fields the analyzer doesn't see
+ * - `returned`: an object a native returns (`Object.getOwnPropertyDescriptor`), with unseen base fields
+ * - `copy`: `Object.assign(literal, …sources)`, which copies each source's seen fields into the literal as a spread does
+ * - `function`: a function or class, created in the frame `at.frame`, whose free variables it reads there (its closure)
+ * - `prototype`: the object a function's or class's `prototype` holds, made with it
+ * - `bound`: what `f.bind(t, …args)` returns
+ *
+ * An `instance` whose node is a class is the class's generic instance: the one its members run with when no `new` of it
+ * was analyzed (§5 Resolver capabilities 3).
+ */
+export interface Allocation {
+    id: string;
+    node: AstNode;
+    at: Position;
+    frame: string | undefined;
+    kind: 'literal' | 'array' | 'instance' | 'returned' | 'copy' | 'function' | 'prototype' | 'bound';
+}
+/** Whether a value is an object the heap holds. */
+export declare const isHeap: (value: Value) => value is HeapValue;
+/**
+ * A part of an object as a descriptor reads it (§3 Undecidable outcomes, §5 Resolver capabilities 5), in the order
+ * ToPropertyDescriptor's view of it is built:
+ * - `field`: a field the object has, with its key, the property or write that gives it, and whether that is a getter or
+ *   setter. `sources` are the expressions that give its value, each where it is evaluated. `maybe` is the write that
+ *   gives a field written after allocation, which may be absent.
+ * - `unseen`: a part that may give any field: a spread or key that doesn't fold, an object's unseen base fields.
+ * - `proto`: a literal's `__proto__: p`, whose object supplies the fields the literal lacks.
+ */
+export type ObjectPart = {
+    kind: 'field';
+    key: Key;
+    site: AstNode;
+    accessor?: 'get' | 'set';
+    sources: {
+        node: AstNode;
+        at: Position;
+    }[];
+    values: Value[];
+    folds: Fold[];
+    maybe?: AstNode;
+} | {
+    kind: 'unseen';
+    node: AstNode;
+} | {
+    kind: 'proto';
+    site: AstNode;
+    values: Value[];
+};
+/** One object a descriptor can be: its allocation site and its parts. */
+export interface ObjectParts {
+    node: AstNode;
+    parts: ObjectPart[];
+}
+export type NativeValue = Extract<Value, {
+    kind: 'native';
+}>;
+/**
+ * The native functions a value can be, so that an alias of one is followed (§5 Resolver capabilities 2): the writer
+ * functions (by catalog name, `Object.defineProperty`); the functions a route to a native that compiles code goes
+ * through (`Function.prototype.call`, `Reflect.apply`, `Object.getOwnPropertyDescriptor`, `code-routes.ts`), of which
+ * `Object.getPrototypeOf` also chooses a holder against the catalog; and the global object's functions that compile
+ * code from strings (`eval`, `setTimeout`, `setInterval`). The `Function` constructor is a holder.
+ */
+declare const nativeReaderNames: readonly ["Object.hasOwn", "Object.prototype.hasOwnProperty", "Object.getPrototypeOf", "Reflect.getPrototypeOf", "Reflect.get", "Object.getOwnPropertyDescriptor", "Reflect.getOwnPropertyDescriptor", "Reflect.apply", "Reflect.construct", "Function.prototype.call", "Function.prototype.apply", "Function.prototype.bind"];
+export declare const nativeWriterNames: readonly ["Object.defineProperty", "Reflect.defineProperty", "Object.defineProperties", "Object.assign", "Object.setPrototypeOf", "Reflect.setPrototypeOf", "Reflect.set", "Reflect.deleteProperty"];
+declare const nativeCompilerNames: readonly ["eval", "setTimeout", "setInterval"];
+export type NativeName = (typeof nativeWriterNames)[number] | (typeof nativeCompilerNames)[number] | (typeof nativeReaderNames)[number];
+/** The realm instance of a value reached from several leaves: theirs when they agree, otherwise `unknown`. */
+export declare function instanceOf(leaves: readonly Leaf[]): RealmInstance;
+/** What is known at a position in the program. */
+export interface Position {
+    /** The `typeof` test around the position that shows the free name is defined, if there is one. */
+    guard(name: string): AstNode | undefined;
+    /** Whether `this` at the position is the script's top-level `this` (no function, field or static block around it). */
+    topLevel: boolean;
+    /**
+     * The instantiation of the function the position is in (§5 Resolver capabilities 3): its parameters take the
+     * arguments of the frame's calls. None when the function runs with unknown arguments.
+     */
+    frame?: Frame | undefined;
+}
+export interface GlobalResolution {
+    /** The values an expression can have at a position. */
+    evaluate(node: AstNode, at: Position): Value[];
+    /**
+     * The object and key of an own-property test call, by any route (§4 A holder chosen at runtime): `Object.hasOwn(h,
+     * k)`, `h.hasOwnProperty(k)`, through `.call`, `.apply` or `Reflect.apply`. The key is `null` when the call passes
+     * none. Undefined for a call that is no such test.
+     */
+    ownTestParts(call: AstNode, at: Position): {
+        object: AstNode;
+        key: AstNode | null;
+    } | undefined;
+    /**
+     * Finds the calls whose callees the syntax doesn't name (§5 Resolver capabilities 3), before any other evaluation,
+     * so that it starts with nothing else on the stack.
+     */
+    prepare(): void;
+    /**
+     * The values a called name can have when it may be an alias of a native function or holder (§5 Resolver capabilities
+     * 2): a variable one of whose definitions reads a name or a member, or destructures one. None for any other name, so
+     * that the many calls of local functions cost nothing.
+     */
+    aliasCallee(id: AstNode, at: Position): Value[];
+    /**
+     * The free names a `typeof` guard shows are defined when control enters `child` of `parent`, each with the `typeof`
+     * test that shows it: in the consequent or alternate of an `if` or `?:`, or the right side of `&&` or `||`.
+     */
+    guards(parent: AstNode, child: AstNode): Guards;
+    /**
+     * Runs `run`, and gives with its result the folds that passed the `fold-length` cap in what it evaluated (§13
+     * `analysis-budget`), each once: those it hit, and those of the constants it read, whether their hits were counted
+     * then or before. They count for any `tracked` run around this one too, unless this one is `apart`.
+     */
+    tracked<T>(run: () => T, apart?: boolean): {
+        value: T;
+        capped: AstNode[];
+    };
+    /**
+     * Runs `run`, and gives with its result the functions whose parameters it read with no frame to bind them (§5
+     * Resolver capabilities 3): a write that reads them is instantiated in each frame of its function.
+     */
+    contextual<T>(run: () => T): {
+        value: T;
+        functions: ReadonlySet<AstNode>;
+    };
+    /**
+     * The frames a function is instantiated in for the writes in it (§5 Resolver capabilities 3), out along its calls:
+     * none when no call of it is known.
+     */
+    framesOf(fn: AstNode, deep?: boolean): Frame[];
+    /**
+     * The resolved calls of a function (§7 Where reachability is judged from), each with the frame of its caller when the
+     * resolver has one: the calls the syntax names, in document order, then those it doesn't (methods, callbacks,
+     * closures, the call natives), as the dynamic-call index found them. A module's factory is called by the require calls
+     * that link its module (§6). Finding them counts no cap hit: it reads only what the resolver has found.
+     */
+    callersOf(fn: AstNode): Binding[];
+    /**
+     * Whether a call argument literal may decide a test in `fn`'s own code (§5 Resolver capabilities 5): some call
+     * passes `fn` an object literal directly, and the test reads a field of one of `fn`'s parameters. Only such a test is
+     * evaluated in a call's frame for it.
+     */
+    argumentTest(test: AstNode, fn: AstNode): boolean;
+    /** A test's values, with each call argument literal's field that nothing writes to settled, to decide it. */
+    settled(values: Value[]): Value[];
+    /**
+     * Runs `run`, and gives with its result the tests a call argument literal's field decided in what it evaluated,
+     * each with that literal, once: those it settled, and those settled while finding the values it read.
+     */
+    decided<T>(run: () => T): {
+        value: T;
+        decisions: Decision[];
+    };
+    /**
+     * Runs `run` as the evaluation would be without some of the argument-literal rule's decisions: no test
+     * `unsettles` holds for is settled. What it evaluates is memoized apart, under `variant`, and its steps and cap hits
+     * count as any evaluation's do, so a caller that only compares results undoes them.
+     */
+    counterfactual<T>(variant: string, unsettles: (decision: Decision) => boolean, run: () => T): T;
+    /** The node a node is a child of. */
+    parentOf(node: AstNode): AstNode | undefined;
+    /** Whether a member sweep has given keys yet (§5 Resolver capabilities 9): no value is a swept key before one has. */
+    swept(): boolean;
+    /**
+     * Whether a read names a once-flag by use (§5 Resolver capabilities 6): a variable or parameter some function tests and
+     * then assigns on the path the test lets through, whatever it reads.
+     */
+    onceFlag(id: AstNode): boolean;
+    /**
+     * The frame a function or class runs in with no call known: the closure it was made in, with unknown parameters
+     * and no `this` of its own. A function object's body is read in it for wrap evidence (§5 Resolver capabilities 10).
+     */
+    closureFrame(fn: AstNode, closure: Frame | undefined): Frame;
+    /**
+     * The argument values a call site passes, evaluated in `caller`, one list per argument bound to a parameter (for the
+     * lookup of a write inside a helper, §10).
+     */
+    argumentValues(binding: Binding): Value[][];
+    /**
+     * Whether the argument `index` of a call carries the member `key` that came in through it (§10): it is the key,
+     * or holds it as an element of a constant collection, or is a string the helper splits into it (`member` has that
+     * split's fold), or an object the member was read out of through heap fields (`member` has a heap fold).
+     */
+    argumentCarries(binding: Binding, index: number, key: Key, member: readonly Fold[]): boolean;
+    /**
+     * The objects a descriptor expression can be, each with its parts as ToPropertyDescriptor reads them (§3, §5 Resolver
+     * capabilities 5): undefined unless every value it can have is an object the heap holds.
+     */
+    objectParts(node: AstNode, at: Position): ObjectParts[] | undefined;
+    /**
+     * The values a descriptor expression can be, as alternatives (§3 Undecidable outcomes, Principle 3): the
+     * objects the heap holds, each with its parts as ToPropertyDescriptor reads them; whether it can be a primitive,
+     * which ToPropertyDescriptor refuses; and whether it can be anything else, which the analyzer can't see.
+     */
+    descriptorValues(node: AstNode, at: Position): {
+        objects: ObjectParts[];
+        primitive: boolean;
+        unseen: boolean;
+    };
+    /**
+     * The expressions that give a member read's value when it reads a field of objects the heap holds, each where it is
+     * evaluated: undefined unless every value comes from one, with no part the analyzer can't see.
+     */
+    fieldSources(member: AstNode, at: Position): {
+        node: AstNode;
+        at: Position;
+    }[] | undefined;
+    /**
+     * The expression an iteration native's callback is passed as its parameter `index` by `binding` (§5 Resolver
+     * capabilities 4), where it is evaluated: an array literal's element. Undefined for any other binding or parameter.
+     */
+    givenSource(binding: Binding, index: number): {
+        node: AstNode;
+        at: Position;
+    } | undefined;
+}
+/** Free names a `typeof` test shows are defined, each with the test. */
+export type Guards = ReadonlyMap<string, AstNode>;
+export declare function globalResolution(context: {
+    /** The program analyzed, whose loops may be unrolled (§5 Resolver capabilities 4). */
+    program: AstNode;
+    catalog: SerializedCatalog;
+    realm: Realm;
+    /** The realm's global holder, e.g. `Window`. */
+    global: string;
+    sourceType: 'script' | 'module';
+    scope: ScopeRules;
+    /** The definitions of the program's variables, and those that reach each read (§5 Resolver capabilities 2). */
+    definitions: Definitions;
+    /**
+     * The window whose global object the code's free names are properties of: the artifact's own, or, for code another
+     * window's `eval`, `Function` or timer compiles, that window.
+     */
+    instance: RealmInstance;
+    /**
+     * Counts a cap that changed a value at `node` (§18 Context policy): `alternatives`, or `fold-length`. Whether a
+     * `fold-length` hit also raises `analysis-budget` depends on what it cuts (§13, `tracked`).
+     */
+    cap(name: CapHit['name'], node: AstNode): void;
+    /**
+     * Counts a hit of a cap that bounds no value, once for the node where it cut (§18): `flagDepth`, at a function
+     * a once-flag's assignment isn't followed into, and `nesting`, at a constant read too deep within others.
+     */
+    capHit(name: 'flagDepth' | 'nesting', node: AstNode): void;
+    /** The calls of the program's functions (§5 Resolver capabilities 3). */
+    calls: CallGraph;
+    /**
+     * Raises `analysis-budget` for the call `site`, which a recursion or context cap widened or merged while it carries
+     * the global object, a native holder or a native member (Principle 5).
+     */
+    budget(site: AstNode, cap: 'recursion' | 'contexts'): void;
+    /** The caps (§18 Context policy). */
+    caps: Caps;
+    /**
+     * Counts one step of the link group's step budget (§18): each value evaluated. It throws once the budget is
+     * exhausted, which abandons the group's analysis where it is.
+     */
+    step(): void;
+    /** The artifact's module links (§6): the definer's modeled defines, and the require calls. */
+    links: ModuleLinks;
+}): GlobalResolution;
+/**
+ * The values a `const` gives a name, with the expression they come from, for its fold (§14), and the folds that passed
+ * the `fold-length` cap while they were found.
+ */
+/** A test a call argument literal's field decided, with that literal. */
+export interface Decision {
+    test: AstNode;
+    literal: AstNode;
+}
+/**
+ * A cap that changed a value (§18), at the node where it applied: `alternatives`, a value with too many alternatives,
+ * or `fold-length`, a string fold too long.
+ */
+export interface CapHit {
+    name: 'alternatives' | 'fold-length' | 'recursion' | 'contexts' | 'iterations';
+    node: AstNode;
+}
+/** Whether a fold's value can be recorded in the trace, which is JSON: a string, a finite number, a boolean or `null`. */
+export declare const recordable: (value: Primitive) => value is string | number | boolean | null;
+/** Whether a call's arguments include an object literal passed directly, whose fields may decide tests. */
+export declare const passesLiteral: (args: readonly AstNode[]) => boolean;
+/**
+ * Two lists of folds, each fold once, in order. A call's folds stay apart by what came through the call: each argument,
+ * its `this`, and what it returns, so that a lookup finds the argument a member came in through (§10).
+ */
+export declare function mergedFolds(a: readonly Fold[], b: readonly Fold[]): Fold[];
+/**
+ * How a test whose values a call argument literal's field decides comes out (§5 Resolver capabilities 5): every
+ * value a constant that decides, at least one read through such a field. Undefined for any other test, which this
+ * rule leaves as it was.
+ */
+export declare function argumentDecided(values: readonly Value[]): boolean | undefined;
+/**
+ * The call argument literals whose fields settled a test's values, in document order: what a `prune` step names
+ * as having settled the test.
+ */
+export declare function settlingLiterals(values: readonly Value[]): AstNode[];
+/** Whether a value is truthy whichever of `values` it is: `true` or `false` when every one agrees, else undefined. */
+export declare function truthiness(values: readonly Value[]): boolean | undefined;
+/**
+ * The leaves without a twin: a leaf of the same node as an earlier one, that differs from it only in the frames mark. A
+ * marked and an unmarked read of one node stay two leaves only while the mark tells them apart (`union`); once both
+ * carry it or neither does, or once a trace lists their steps, they are one read.
+ */
+export declare const onePerNode: (leaves: readonly Leaf[]) => Leaf[];
+export {};