monkeypatchlist 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,358 @@
+import { type AstNode } from './ast.ts';
+import type { Fold, GlobalResolution, Leaf, Position, Value } from './global-object.ts';
+import { type Key as MemberKey } from './keys.ts';
+import { type Declared, type ScopeRules } from './scope.ts';
+import type { Caps } from './budget.ts';
+import type { Mechanism, RealmInstance } from './types.ts';
+/** A native member written, and how: the syntax's reading of the change, before the catalog decides its effect. */
+export interface Write {
+    /** The write site: the assignment, the `delete`, the call, or for a bulk mechanism the property of its object. */
+    site: AstNode;
+    /** The native holder written, e.g. `Window` or `Array.prototype`. */
+    holder: string;
+    /** The leaves the holder, and the native function a call mechanism uses, were reached from, in document order. */
+    leaves: Leaf[];
+    /** The window the holder written belongs to (§4 Other windows), from the leaves it was reached from. */
+    realmInstance: RealmInstance;
+    mechanism: Mechanism;
+    /**
+     * The native function that makes the write, by catalog name (`Object.defineProperty`, `Reflect.set`), or its legacy
+     * method name (`__defineGetter__`); absent for syntax (`=`, `delete`). It decides whether a write that can't change
+     * its target throws (§3 Ineffective writes).
+     */
+    writer?: string;
+    change: Change;
+    /**
+     * The folds (§14) the native writer function, the holder, the member and the descriptor's fields come from, in that
+     * order, each after the folds it folds.
+     */
+    folds: Fold[];
+    /**
+     * The folds the holder written and the member come from, apart: a write inside a helper is looked up at the outermost
+     * call whose arguments carry both (§10).
+     */
+    parts: Parts;
+    /** Where attribution looks the write up, and its token (§10 lookup point). */
+    lookup: WriteLookup;
+    /** For mechanism `declare`, the declaration that makes the write (§3 Declarations in classic scripts). */
+    declaration?: Declaration;
+    /** For one candidate of a site's candidate set (§5 Candidate sets), the set and the branches it comes from. */
+    alternatives?: Alternatives;
+}
+/**
+ * A write site's candidate set (§5 Candidate sets, ADR 0019): the holders or members a branch that neither folding nor
+ * the catalog settles gives, and the targets they make, each of which is its own finding.
+ */
+export interface Alternatives {
+    /** When the candidates are several holders, the expression whose branches give them, and the holders. */
+    holders?: {
+        node: AstNode;
+        names: string[];
+    };
+    /**
+     * When the candidates are several members, or come from a key whose other alternatives the analyzer can't resolve,
+     * the key whose branches give them, the members, the prefixes of its pattern wildcards (§5 Pattern wildcards), and
+     * whether it had such other alternatives (`unresolved`) or a heap-read or once-flag boolean, `null` or `undefined` an
+     * undecided test gave back, which is never a key (`tested`).
+     */
+    members?: {
+        node: AstNode;
+        keys: MemberKey[];
+        prefixes?: string[];
+        unresolved?: true;
+        tested?: true;
+    };
+    /** The site's candidate targets, by name: `<holder>.<member>`, or `<holder>.*` for wildcards, in source order. */
+    targets: string[];
+}
+/** The most candidates a site's candidate set gives findings for (§5 Candidate sets, ADR 0019). */
+export declare const maxCandidates = 4;
+/**
+ * A write site whose candidate set has more than `maxCandidates` targets, holders only (§5 Candidate sets): with one
+ * member that folds, the candidate `writes` and the `open` write site the patch-shape test reads; with a member that
+ * doesn't, the candidate wildcard writes, one per holder. Either gives an `unresolved-holder` limitation at most.
+ */
+export type WideSite = {
+    site: AstNode;
+    open: OpenWrite;
+    writes: Write[];
+} | {
+    site: AstNode;
+    wild: WildWrite[];
+};
+/**
+ * A declaration that writes a global object's member (§3): how it binds the name (`Declared`), and for a `var`,
+ * whether it only binds it, with no initializer and no loop to assign it (`var x;`).
+ */
+export type Declaration = Declared & {
+    bare?: true;
+};
+/**
+ * A write site whose member folds to a constant but whose holder may be an object the analyzer can't resolve: one
+ * alternative of it, at least, is unknown (§5 Partially resolved writes). Whether it is an `unresolved-holder`
+ * limitation is for the site's patch shape and the catalog to decide (`partial.ts`).
+ */
+export interface OpenWrite {
+    /** The write site, as a `Write` of it would give it. */
+    site: AstNode;
+    /** The expression that gives the holder written. */
+    holder: AstNode;
+    mechanism: Mechanism;
+    change: Exclude<Change, {
+        kind: 'prototype';
+    }>;
+    /** For an assign, the value written. */
+    value?: AstNode;
+    /** For an assign, the member expression written, which is no read of the original. */
+    target?: AstNode;
+    /** Whether the write is a logical assignment that keeps the member when present (`o.m ||= p`, `o.m ??= p`). */
+    keepsPresent?: boolean;
+}
+/**
+ * The member of a wildcard write (§5 Partially resolved writes): a key the analyzer can't fold. It names no member, so
+ * each member the wildcard matches takes its place when the outcome is judged (`effect.ts`).
+ */
+export declare const unknownMember: unique symbol;
+/**
+ * A write site whose holder resolves to one native holder but whose key folds to nothing the analyzer knows (§5
+ * Partially resolved writes): a wildcard target `<holder>.*` when the same key is reused (`partial.ts`). Its change
+ * has `unknownMember` for its member.
+ */
+export interface WildWrite extends Write {
+    /** The expression that gives the key. */
+    key: AstNode;
+    /** The expression that gives the holder written. */
+    object: AstNode;
+    /** For an assign or a delete, the member expression written, which is no read of the original. */
+    target?: AstNode;
+    /** For an assign, the value written. */
+    value?: AstNode;
+    /** Whether the write is a logical assignment that keeps the member when present (`o[k] ||= p`, `o[k] ??= p`). */
+    keepsPresent?: boolean;
+    /**
+     * When the key is a candidate set of more than `maxCandidates` members, the members the wildcard's matched set is
+     * narrowed to (§5).
+     */
+    members?: MemberKey[];
+    /**
+     * When the key folds to a constant prefix that no catalog member of the holder or its catalog prototype chain starts
+     * with, the prefix: the write is a pattern wildcard `<holder>.<prefix>*`, a non-native `add` (§5 Pattern wildcards).
+     */
+    pattern?: string;
+    /**
+     * When the key folds to constant prefixes some catalog member of the holder or its chain starts with, the prefixes:
+     * the write is `<holder>.*` under the reuse rule, its matched set narrowed to the members that start with one of
+     * them, together with `members` when both are set. Several prefixes at one site give one `<holder>.*`, whose
+     * matched set is the members that start with any of them (Principle 3).
+     */
+    prefixes?: string[];
+    /**
+     * Whether the prefix is configurable: the key's other alternatives are values the analyzer can't resolve, which give
+     * nothing.
+     */
+    configurable?: true;
+}
+/** The folds the holder written and the member come from. */
+export interface Parts {
+    holder: readonly Fold[];
+    member: readonly Fold[];
+}
+/**
+ * Where attribution looks a write up (§10): the member token written at the site, or else the holder argument, with the
+ * token the token check looks for, or null when there is none.
+ */
+export interface WriteLookup {
+    node: AstNode;
+    token: string | null;
+}
+/**
+ * The change a write makes:
+ * - `set`: a [[Set]] of a value (`assign`, `bulk-assign`). `same` says the value is a read of the same slot, which
+ *   writes back what is there. `through` is the object the member is looked up on when it isn't the one written, as
+ *   `Reflect.set(t, k, v, r)` looks k up on t and writes its receiver r (§3).
+ * - `define`: a [[DefineOwnProperty]] with a descriptor, as far as the syntax shows it. `via` names the method of the
+ *   holder that makes it (`__defineGetter__`), which must be the one `Object.prototype` gives.
+ * - `delete`
+ * - `prototype`: a new [[Prototype]], with the values it can be. `setter` says it is set through `__proto__`, whose
+ *   setter must be the one the prototype chain reaches: `through`'s, when the holder is a `Reflect.set` receiver.
+ *   `sameWindow` says the new prototype is one native holder, reached through the same window expression as the holder
+ *   written, with nothing between the reads that could change which window that is (§3 Undecidable outcomes): the two
+ *   belong to one window.
+ */
+export type Change = {
+    kind: 'set';
+    member: MemberKey;
+    same: boolean;
+    /**
+     * Set when `same` holds only because a heap field carries the read of the slot (`s.orig = window.fetch;
+     * window.fetch = s.orig`): the value may be the native saved before an install, so the write is judged as a restore
+     * too (§3 Restores).
+     */
+    throughHeap?: true;
+    through?: Through | undefined;
+    value?: WrittenValue;
+    /** The expression the new value comes from, where it is evaluated, for wrap evidence (§5 capability 10). */
+    sources?: Source[];
+} | {
+    kind: 'define';
+    member: MemberKey;
+    descriptor: DescriptorLiteral;
+    /**
+     * When the descriptor can be several objects the heap holds, or has fields that may be absent (§3, §5 Resolver
+     * capabilities 5), every descriptor it can be, the first of which is `descriptor`: `refused` for one that
+     * ToPropertyDescriptor refuses, so that nothing is written.
+     */
+    alternatives?: (DescriptorLiteral | 'refused')[];
+    via?: AccessorDefiner;
+    /** The expression that gives the descriptor, where it is evaluated, for descriptor restores (§3 Restores). */
+    source?: Source;
+} | {
+    kind: 'delete';
+    member: MemberKey;
+} | {
+    kind: 'prototype';
+    proto: Value[];
+    setter: boolean;
+    sameWindow: boolean;
+    through?: string | undefined;
+};
+/** An expression that gives a written value, and where it is evaluated. */
+export interface Source {
+    node: AstNode;
+    at: Position;
+}
+/**
+ * What the syntax shows of the value a [[Set]] writes, where its outcome follows the value: `opener`, whose setter
+ * redefines it as an own data property for any value but `null` (§3). `isNull` says whether the value is `null`, or
+ * `unknown` when the analyzer can't decide it, as for a write-back of what the getter returns, which may be `null`.
+ * `site` is the value, or the getter or missing argument that gives it.
+ */
+export interface WrittenValue {
+    isNull: Attribute;
+    site: AstNode;
+}
+/**
+ * The object a `Reflect.set` looks its member up on when it isn't the receiver written (§3): a native holder, or
+ * `unresolved`, the argument that denotes no native holder and may be any object.
+ */
+export type Through = {
+    holder: string;
+} | {
+    unresolved: AstNode;
+};
+/** An attribute's value in a descriptor: a boolean, or `unknown` when it can't be decided. */
+export type Attribute = boolean | 'unknown';
+/**
+ * A descriptor as the syntax shows it: the fields an object literal gives it (ECMA-262 ToPropertyDescriptor), and the
+ * parts the analyzer can't see (§3 Undecidable outcomes). `value.same` says the value is a read of the slot being
+ * defined, and `value.fresh` that it is a new object. `get` and `set` say the literal has the field, whatever value a later part gives it. It never shows both
+ * accessor and data fields, which ToPropertyDescriptor refuses.
+ */
+export interface DescriptorLiteral {
+    /**
+     * `fresh` says every value it can be is an object or function the code creates, which differs from any value the
+     * member holds already.
+     */
+    value?: {
+        same: boolean;
+        fresh: boolean;
+        sources?: Source[];
+        throughHeap?: true;
+    };
+    get: boolean;
+    set: boolean;
+    writable?: Attribute;
+    enumerable?: Attribute;
+    configurable?: Attribute;
+    /**
+     * The parts that may give the descriptor any field it doesn't have itself, in source order: the descriptor, when it is
+     * no object the heap holds; an object's unseen base fields (a `new`, or a native's result such as
+     * `getOwnPropertyDescriptor`'s); a spread or a key that doesn't fold, which may also replace the values of the fields before it,
+     * so those values are not kept; and a `__proto__: p` field, whose object ToPropertyDescriptor reads for the fields
+     * the literal lacks. Empty when every field is seen.
+     */
+    unseen: AstNode[];
+    /** The fields whose attribute can't be decided (`{ enumerable: flag }`, `{ get configurable(){…} }`), in source order. */
+    undecided: AstNode[];
+    /**
+     * For one of several descriptors a define can have, what makes it one: the objects the descriptor can be, when it can
+     * be several, and the writes of the fields that may be absent (§3).
+     */
+    evidence?: AstNode[];
+}
+/** The legacy methods that define an accessor on their `this` (§3), with the accessor field each gives. */
+declare const accessorDefiners: {
+    readonly __defineGetter__: "get";
+    readonly __defineSetter__: "set";
+};
+export type AccessorDefiner = keyof typeof accessorDefiners;
+export interface WriteContext {
+    scope: ScopeRules;
+    resolution: GlobalResolution;
+    /** The realm's global holder, e.g. `Window`. */
+    global: string;
+    /** The window whose global object the code's free names are properties of (§4 Other windows). */
+    instance: RealmInstance;
+    /**
+     * Raises `analysis-budget` for folds that passed the `fold-length` cap in the key, holder or descriptor of a write
+     * that reaches the global object or a native holder, any alternative counting (Principle 5, §13).
+     */
+    budget(folds: readonly AstNode[]): void;
+    /**
+     * Counts the descriptor-alternatives cap for defines whose descriptor objects have more combinations of maybe-absent
+     * fields than it allows, so those fields were read as parts the analyzer can't see, and raises `analysis-budget` when
+     * the write reaches the global object or a native holder (Principle 5, §18).
+     */
+    descriptorsCut(sites: readonly AstNode[], native: boolean): void;
+    /**
+     * Counts the `candidateRuns` cap for a node whose candidate sites it cut, so they give nothing, and raises
+     * `analysis-budget` when a holder they write can be the global object or a native holder, any alternative counting
+     * (Principle 5, §18).
+     */
+    candidatesCut(node: AstNode, native: boolean): void;
+    /**
+     * The descriptor fields a native holder supplies as a descriptor's prototype, read through its chain in the unmutated
+     * catalog (§3 Undecidable outcomes); undefined when the analyzer can't read them.
+     */
+    descriptorFields(holder: string): DescriptorFields | undefined;
+    /** The caps (§18): `heapDepth`, `descriptorAlternatives` and `candidateRuns` here. */
+    caps: Pick<Caps, 'heapDepth' | 'descriptorAlternatives' | 'candidateRuns'>;
+    /** Counts a hit of the `heapDepth` cap at the heap field read it keeps a write-back from being followed through. */
+    capHit(name: 'heapDepth', node: AstNode): void;
+    /**
+     * Whether a write of `holder` whose key starts with `prefix` is a pattern wildcard: no catalog member of the holder or
+     * its catalog prototype chain starts with it, so it can name or shadow none (§5 Pattern wildcards).
+     */
+    patternPrefix(holder: string, prefix: string): boolean;
+}
+/**
+ * The native members `node` writes directly, in source order. When a fold in the key, holder or descriptor of the write
+ * passed the `fold-length` cap, and its holder can be the global object or a native holder, it goes to `budget`, whether
+ * or not the write resolves (Principle 5, §13): the value written, and a call's native function, are no part of it.
+ */
+export declare function writesAt(node: AstNode, at: Position, context: WriteContext): Write[];
+/**
+ * The native members `node` writes directly, as `writesAt` gives them, and the write sites in it whose member folds
+ * but whose holder may be an object the analyzer can't resolve (§5 Partially resolved writes).
+ */
+export declare function sitesAt(node: AstNode, where: Position, context: WriteContext): Sites;
+/** The write sites at a node (`sitesAt`). */
+export interface Sites {
+    writes: Write[];
+    open: OpenWrite[];
+    wild: WildWrite[];
+    wide: WideSite[];
+}
+/** The name of the target a write names, before the catalog decides its outcome. */
+export declare function candidateName(write: Write): string;
+/** The fields ECMA-262 ToPropertyDescriptor reads. */
+export declare const descriptorFields: ReadonlySet<string>;
+/**
+ * The descriptor fields a native holder supplies as a descriptor's prototype (§3 Undecidable outcomes): `functions`, whose
+ * value is a function, and `throwing`, whose getter throws when ToPropertyDescriptor reads it.
+ */
+export interface DescriptorFields {
+    readonly functions: ReadonlySet<string>;
+    readonly throwing: ReadonlySet<string>;
+}
+export {};