monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/analysis/lib/early-exits.d.ts

@@ -0,0 +1,39 @@
+import type { AstNode } from './ast.ts';
+/** A guard an early exit makes: the code after it runs when `test` is `outcome`. */
+export interface ExitGuard {
+    test: AstNode;
+    outcome: boolean;
+}
+/** The statement lists whose earlier `if (…) return` or `throw` guards the statements after it (§5, §7). */
+export declare const statementLists: Readonly<Record<string, string>>;
+export declare function earlyExits(list: AstNode): {
+    index: number;
+    guard: ExitGuard;
+}[];
+/** Whether a statement always leaves its function: a `return` or `throw`, a block with one, or an `if` both arms do. */
+export declare function alwaysExits(statement: AstNode): boolean;
+/** The guards of the early exits before `child` in the statement list `list`, first first. None for any other edge. */
+export declare function exitsBefore(list: AstNode, child: AstNode): ExitGuard[];
+/**
+ * A condition on a statement's tests, under which control reaches a point: `true`, `false` (it never does), a test
+ * with the outcome it takes, or all or any of several conditions.
+ */
+export type Condition = boolean | ExitGuard | {
+    all: Condition[];
+} | {
+    any: Condition[];
+};
+/**
+ * When control leaves a statement at its end rather than by a `return` or `throw` in it (§7 early returns): `if (t)
+ * return` falls through when `t` is false, and `if (p) { …; if (q) return }` when `p` is false or `q` is. A `continue`
+ * leaves too: it ends its loop's iteration, and the loop holds every statement list this walks into, so `if (typeof
+ * proto[k] !== 'function') continue` filters a swept key (§5 Resolver capabilities 9). Loops,
+ * `switch`, `try` and labelled statements are taken to fall through, and the functions a statement creates are not
+ * entered.
+ */
+export declare function fallsThrough(statement: AstNode): Condition;
+/**
+ * The condition under which control reaches `child` from the start of the statement list `list`: every statement before
+ * it fell through. `true` for any other edge.
+ */
+export declare function reachedAfter(list: AstNode, child: AstNode): Condition;

package/dist/packages/analysis/lib/early-exits.js

@@ -0,0 +1,161 @@
+// Early exits (§5 Global resolution, §7): an `if` whose one arm always returns or throws guards every statement after
+// it in its statement list, nested blocks and the functions created there included, with its test's other outcome. A
+// script's or module's top-level body counts like a function body.
+/** The statement lists whose earlier `if (…) return` or `throw` guards the statements after it (§5, §7). */
+export const statementLists = {
+    Program: 'body',
+    BlockStatement: 'body',
+    StaticBlock: 'body',
+    SwitchCase: 'consequent',
+};
+/**
+ * The early exits of each statement list, by the index of the statement they guard from: an `if` whose one arm always
+ * returns or throws guards every statement after it in its list with its test's other outcome (§7 early returns).
+ */
+const exitsOf = new WeakMap();
+export function earlyExits(list) {
+    let found = exitsOf.get(list);
+    if (found !== undefined)
+        return found;
+    found = [];
+    const key = statementLists[list.type];
+    const body = key === undefined ? [] : (list[key] ?? []);
+    body.forEach((statement, index) => {
+        if (statement.type !== 'IfStatement')
+            return;
+        const consequent = statement['consequent'];
+        const alternate = statement['alternate'];
+        const test = statement['test'];
+        if (alwaysExits(consequent) && (alternate === null || !alwaysExits(alternate))) {
+            found.push({ index, guard: { test, outcome: false } });
+        }
+        else if (alternate !== null && alwaysExits(alternate) && !alwaysExits(consequent)) {
+            found.push({ index, guard: { test, outcome: true } });
+        }
+    });
+    exitsOf.set(list, found);
+    return found;
+}
+/** Whether a statement always leaves its function: a `return` or `throw`, a block with one, or an `if` both arms do. */
+export function alwaysExits(statement) {
+    switch (statement.type) {
+        case 'ReturnStatement':
+        case 'ThrowStatement':
+            return true;
+        case 'BlockStatement':
+            return statement['body'].some(alwaysExits);
+        case 'IfStatement': {
+            const alternate = statement['alternate'];
+            return alternate !== null && alwaysExits(statement['consequent']) && alwaysExits(alternate);
+        }
+        default:
+            return false;
+    }
+}
+/** The positions of each statement list's statements, for `exitsBefore` and `reachedAfter`. */
+const positionsOf = new WeakMap();
+/** The index of `child` in the statement list `list[key]`, or undefined when it is not one of its statements. */
+function positionIn(list, key, child) {
+    let positions = positionsOf.get(list);
+    if (positions === undefined) {
+        positions = new Map((list[key] ?? []).map((statement, index) => [statement, index]));
+        positionsOf.set(list, positions);
+    }
+    return positions.get(child);
+}
+/** The guards of the early exits before `child` in the statement list `list`, first first. None for any other edge. */
+export function exitsBefore(list, child) {
+    const key = statementLists[list.type];
+    if (key === undefined)
+        return [];
+    const exits = earlyExits(list);
+    if (exits.length === 0)
+        return [];
+    const index = positionIn(list, key, child);
+    if (index === undefined)
+        return [];
+    return exits.filter((exit) => exit.index < index).map((exit) => exit.guard);
+}
+function all(conditions) {
+    const kept = [];
+    for (const each of conditions) {
+        if (each === false)
+            return false;
+        if (each !== true)
+            kept.push(each);
+    }
+    return kept.length === 0 ? true : kept.length === 1 ? kept[0] : { all: kept };
+}
+function any(conditions) {
+    const kept = [];
+    for (const each of conditions) {
+        if (each === true)
+            return true;
+        if (each !== false)
+            kept.push(each);
+    }
+    return kept.length === 0 ? false : kept.length === 1 ? kept[0] : { any: kept };
+}
+const fallsThroughWhen = new WeakMap();
+/**
+ * When control leaves a statement at its end rather than by a `return` or `throw` in it (§7 early returns): `if (t)
+ * return` falls through when `t` is false, and `if (p) { …; if (q) return }` when `p` is false or `q` is. A `continue`
+ * leaves too: it ends its loop's iteration, and the loop holds every statement list this walks into, so `if (typeof
+ * proto[k] !== 'function') continue` filters a swept key (§5 Resolver capabilities 9). Loops,
+ * `switch`, `try` and labelled statements are taken to fall through, and the functions a statement creates are not
+ * entered.
+ */
+export function fallsThrough(statement) {
+    let found = fallsThroughWhen.get(statement);
+    if (found !== undefined)
+        return found;
+    switch (statement.type) {
+        case 'ReturnStatement':
+        case 'ThrowStatement':
+        case 'ContinueStatement':
+            found = false;
+            break;
+        case 'BlockStatement':
+            found = all(statement['body'].map(fallsThrough));
+            break;
+        case 'IfStatement': {
+            const test = statement['test'];
+            const alternate = statement['alternate'];
+            const consequent = fallsThrough(statement['consequent']);
+            const otherwise = alternate === null ? true : fallsThrough(alternate);
+            // When both arms fall through, the test decides nothing: `t || !t` always holds.
+            found =
+                consequent === true && otherwise === true
+                    ? true
+                    : any([all([{ test, outcome: true }, consequent]), all([{ test, outcome: false }, otherwise])]);
+            break;
+        }
+        default:
+            found = true;
+    }
+    fallsThroughWhen.set(statement, found);
+    return found;
+}
+/** The conditions under which each statement of a list is reached from the list's start, by index. */
+const reachedWhen = new WeakMap();
+/**
+ * The condition under which control reaches `child` from the start of the statement list `list`: every statement before
+ * it fell through. `true` for any other edge.
+ */
+export function reachedAfter(list, child) {
+    const key = statementLists[list.type];
+    if (key === undefined)
+        return true;
+    let conditions = reachedWhen.get(list);
+    if (conditions === undefined) {
+        conditions = [];
+        let sofar = true;
+        for (const statement of list[key] ?? []) {
+            conditions.push(sofar);
+            sofar = all([sofar, fallsThrough(statement)]);
+        }
+        reachedWhen.set(list, conditions);
+    }
+    const index = positionIn(list, key, child);
+    return index === undefined ? true : conditions[index];
+}

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

@@ -0,0 +1,138 @@
+import { type Holder, type Realm, type SerializedCatalog } from '../../../catalog.ts';
+import type { AstNode } from './ast.ts';
+import { type Key as MemberKey } from './keys.ts';
+import type { Effect, IneffectiveReason, Locks, Throws } from './types.ts';
+import { type Change, type DescriptorFields, type Write } from './writes.ts';
+/** A write that is a platform mutation: the target it names, its effect, and what the outcome table decides of it. */
+export interface Mutation extends Outcome {
+    /** The target's name, e.g. `Window.fetch`. */
+    name: string;
+    /** The kind of holder the target is on. */
+    holder: Holder;
+    /** For a shadowing write, the inherited member it shadows (§4): derived, and not identity. */
+    shadows?: string;
+}
+/**
+ * A write that can't change its target (§3 Ineffective writes): the target it would have changed, the effect it
+ * intended, why it can't, and whether it throws. `mayChangeNothing` says that on a value the analyzer can't see the
+ * write could instead change nothing (§3 No-op or ineffective).
+ */
+export interface Ineffective {
+    name: string;
+    holder: Holder;
+    shadows?: string;
+    effect: Effect;
+    reason: IneffectiveReason;
+    throws: Throws;
+    mayChangeNothing: boolean;
+}
+/** Whether an outcome is an ineffective write. */
+export declare const isIneffective: (outcome: Mutation | Ineffective) => outcome is Ineffective;
+/** What a write does to a member it plainly mutates. */
+interface Outcome {
+    effect: Effect;
+    /**
+     * Whether the mutation leaves the target non-configurable or non-writable (§8): `unknown` when that depends on what
+     * the analyzer can't see or decide.
+     */
+    locks: Locks;
+    /**
+     * When the outcome table can't decide whether the write takes effect (§3 Undecidable outcomes), what the outcome
+     * depends on and the analyzer can't see or decide, in source order: the evidence for the mutation-confidence reason
+     * `outcome-undecidable` (§9). For a `descriptor`, the parts of a define's descriptor. For a `lookup`, the object a
+     * `Reflect.set` looks its member up on, which denotes no native holder. For a `value`, the value an assign of
+     * `Window.opener` writes, which may be `null`.
+     */
+    undecidable?: {
+        on: 'descriptor' | 'lookup' | 'value';
+        sites: AstNode[];
+    };
+}
+/**
+ * The descriptor fields (`value`, `get`, `set`, `writable`, `enumerable`, `configurable`) a native holder supplies when
+ * it is a descriptor's prototype, as ECMA-262 ToPropertyDescriptor reads them through its chain in the unmutated catalog
+ * (§3 Undecidable outcomes). `functions` are the fields whose value is a function. `throwing` are the fields that are a
+ * Web IDL attribute: its getter runs on the descriptor, which implements no interface, so it throws a TypeError.
+ * `Object.prototype` supplies none. Undefined when the analyzer can't read them: a field that is any other accessor, or
+ * a data property that isn't a function.
+ */
+export declare function descriptorFieldsOf(holder: string, catalog: SerializedCatalog, realm: Realm): DescriptorFields | undefined;
+/**
+ * The outcomes of a write (§3): the platform mutations it makes, or the ineffective writes it is. A define whose
+ * descriptor can be several descriptors (several objects the heap holds, or fields that may be absent, §5 Resolver
+ * capabilities 5) is judged per descriptor:
+ * - When some can change the target, the write can, so it is no ineffective write (§3): it gives one mutation per
+ *   effect they give. When they don't all give the same effect, or some give none or are ineffective, each has
+ *   `outcome-undecidable`, with what the outcome depends on as its evidence, and `locks` from the descriptors that give
+ *   its effect.
+ * - When none can, and some are ineffective, the write is ineffective (§3 No-op or ineffective): one ineffective
+ *   outcome per effect they intend, which may change nothing when any descriptor changes nothing.
+ */
+export declare function outcomesOf(write: Write, catalog: SerializedCatalog, realm: Realm): (Mutation | Ineffective)[];
+/**
+ * The outcome of a write with one descriptor (§3): the platform mutation it makes, if §3 plainly makes it one, or the
+ * ineffective write it is, when it can't change its target. Undefined when it is neither.
+ */
+export declare function mutationOf(write: Write, catalog: SerializedCatalog, realm: Realm): Mutation | Ineffective | undefined;
+/**
+ * The catalog targets a write of a member on an object the analyzer can't resolve could mutate (§5 Partially resolved
+ * writes): every target of the realm with that member whose outcome §3's table could make a mutation, taking the object
+ * written to be one that implements the member's interface. API use, a constant member, a define that changes
+ * nothing and an ineffective write are left out. Sorted by name.
+ */
+export declare function candidateTargets(change: Exclude<Change, {
+    kind: 'prototype';
+}>, catalog: SerializedCatalog, realm: Realm): string[];
+/**
+ * The outcome of a wildcard write (§3, §5 Partially resolved writes) with the effect its value gives, judged
+ * over every catalog member it matches (`wildcardMembers`) as a write of that member would be:
+ * - `finding`: some member it matches is changed. `mixed` says others are ineffective (`wildcard-outcome-mixed`, §9).
+ *   An `add` changes only members the holder lacks, so it is one whenever the holder takes an add.
+ * - `ineffective`: every member it matches that the write could change is ineffective, one outcome per reason.
+ *
+ * Undefined when the write changes none: every member is API use, or changes nothing (a delete through an object that
+ * only inherits it), or an `add` on a holder that takes none.
+ */
+export type WildcardOutcome = {
+    kind: 'finding';
+    holder: Holder;
+    locks: Locks;
+    mixed: boolean;
+    undecidable?: Mutation['undecidable'];
+} | {
+    kind: 'ineffective';
+    holder: Holder;
+    refused: Ineffective[];
+};
+export declare function wildcardOutcome(write: Write, effect: Effect, catalog: SerializedCatalog, realm: Realm, members?: readonly MemberKey[], prefixes?: readonly string[]): WildcardOutcome | undefined;
+/**
+ * The catalog members a wildcard over `holder` matches (§3): the holder's own members. A singleton instance also
+ * matches its interface's members, those of its interface prototype object (`History.prototype` for `history`,
+ * `Storage.prototype` for `localStorage`, `Navigator.prototype` with its mixins for `navigator`), without the structural
+ * `constructor` and `@@toStringTag`, which are no members of the interface, and not those of shared ancestors.
+ */
+export declare function wildcardMembers(holder: string, catalog: SerializedCatalog, realm: Realm): MemberKey[];
+/**
+ * The catalog targets a wildcard over `holder` matches among `members` (§5), by name: the holder's own, and for a
+ * singleton instance, its interface prototype's.
+ */
+export declare function wildcardTargets(holder: string, members: readonly MemberKey[], catalog: SerializedCatalog, realm: Realm): string[];
+/**
+ * The catalog members a wildcard over `holder` narrowed to a candidate set matches (§5), each once with its
+ * target: those among `members` (`wildcardTargets`), and those of the holder and its chain that start with one of
+ * `prefixes` (`prefixMembers`).
+ */
+export declare function narrowedMatches(holder: string, members: readonly MemberKey[] | undefined, prefixes: readonly string[], catalog: SerializedCatalog, realm: Realm): {
+    member: MemberKey;
+    target: string;
+}[];
+/**
+ * The catalog members of `holder` and its catalog prototype chain whose key is a string that starts with `prefix`, each
+ * once, on its nearest owner, with the target that owner has: what a write there whose key starts with the prefix could
+ * name or shadow (§5 Pattern wildcards, ADR 0002). A well-known symbol member starts with no string.
+ */
+export declare function prefixMembers(holder: string, prefix: string, catalog: SerializedCatalog, realm: Realm): {
+    member: string;
+    target: string;
+}[];
+export {};