monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/analysis/lib/script-loads.js

@@ -0,0 +1,359 @@
+// Script loads only the resolver can see (§2 Discovery, §19 References only the resolver can see): the chunk URLs a
+// chunk loader builds (`chunk-loads.ts`), the scripts code injects, and worker URLs that aren't literals.
+//
+// - An **injected script** is a script element the code creates (`X.createElement("script")`), gives a `src` and
+//   inserts: any Node or Element insertion method, on any receiver, with the element as a node argument, inserts
+//   it, and `src` counts whether it is set before or after. Writes are followed flow-insensitively, per element: every
+//   `src` write is an alternative, as is every `type`. A `setAttribute` whose key doesn't fold touches neither.
+// - Its `src` alternatives that fold are its URLs, each unresolved: discovery resolves them against each document's
+//   base URL. An alternative that doesn't fold is one `unresolved-reference`. Its `type` is passed on as
+//   folded, for discovery to judge as it judges an element's; an `integrity` that folds is carried, with each
+//   constant it may be, for verification (§17). Its `noModule` is passed on as `no`, `yes` or, when the
+//   writes differ or one doesn't fold, `maybe`: discovery judges what it does to a classic script.
+// - **Literal code** an injected element carries, with no `src` (`s.text`, `.textContent`, `.innerText`, or an
+//   appended `X.createTextNode(code)`), is nested code, compiled where the element is inserted.
+// - A **worker URL** that isn't a literal (`new Worker`, `new SharedWorker`, `navigator.serviceWorker.register`,
+//   `importScripts`) folds as `Folder` folds it; each constant alternative is a reference, and each alternative
+//   that doesn't fold is one `unresolved-reference` at that alternative. Discovery owns what a worker call
+//   is: which realm can make it, and whether its callee is the native.
+//
+// A URL expression that calls a chunk loader's URL function is a chunk load, not one of these.
+import { walkTree } from "./ast.js";
+import { chunkCandidates, Folder, foldChunkSites, isScriptCreation, mayLoadChunks, propertyName, } from "./chunk-loads.js";
+import { definitionsOf } from "./definitions.js";
+import { lineStarts, locate } from "./line-starts.js";
+import { parse } from "./parse.js";
+import { scopeRules } from "./scope.js";
+const none = { chunks: [], injected: [], workers: [] };
+/**
+ * The script loads of an artifact's code at `url` (its own URL, for `import.meta.url`). None when it doesn't parse.
+ */
+export function scriptLoads(text, sourceType, bindings, url) {
+    const chunks = mayLoadChunks(text);
+    const elements = /createElement/.test(text);
+    const workers = /Worker|importScripts/.test(text);
+    if (!chunks && !elements && !workers)
+        return none;
+    const parsed = parse(text, sourceType);
+    if ('error' in parsed)
+        return none;
+    const { program } = parsed;
+    const candidates = chunkCandidates(program);
+    const loadsChunks = chunks && candidates.functions.size > 0 && candidates.sites.length > 0;
+    // Only code that creates a script element, or calls a worker function with a URL that isn't a literal, needs folding.
+    const needed = syntaxNeeds(program, elements, workers);
+    if (!loadsChunks && !needed.elements && !needed.workers)
+        return none;
+    const definitions = definitionsOf(program, scopeRules(program, sourceType, bindings));
+    const folder = new Folder(program, definitions, candidates.functions, url);
+    const starts = lineStarts(text);
+    const at = (node) => locate(starts, node.start, node.end);
+    return {
+        chunks: loadsChunks ? foldChunkSites(candidates, folder, starts) : [],
+        injected: needed.elements ? injectedSites(program, folder, at) : [],
+        workers: needed.workers ? workerSites(program, folder, at) : [],
+    };
+}
+/** Whether a program creates a script element, and calls a worker function with a URL that isn't a literal. */
+function syntaxNeeds(program, elements, workers) {
+    const found = { elements: false, workers: false };
+    if (!elements && !workers)
+        return found;
+    walkTree(program, {
+        enter(node) {
+            if (found.elements === elements && found.workers === workers)
+                return false;
+            if (elements && node.type === 'CallExpression' && isScriptCreation(node))
+                found.elements = true;
+            if (workers && (node.type === 'NewExpression' || node.type === 'CallExpression') && isWorkerCall(node)) {
+                if (node['arguments'].some((arg) => arg.type !== 'SpreadElement' && !isLiteral(arg)))
+                    found.workers = true;
+            }
+            return undefined;
+        },
+    });
+    return found;
+}
+/** The insertion methods of Node and Element, and which of their arguments are nodes: all, or one index. */
+const insertions = new Map([
+    ['appendChild', 0],
+    ['insertBefore', 0],
+    ['replaceChild', 0],
+    ['insertAdjacentElement', 1],
+    ['append', 'all'],
+    ['prepend', 'all'],
+    ['before', 'all'],
+    ['after', 'all'],
+    ['replaceWith', 'all'],
+]);
+/** The members that set a script element's code, as text. */
+const textMembers = new Set(['text', 'textContent', 'innerText']);
+/**
+ * The script elements a program creates, each by its creation call, with what the program sets on them and the
+ * insertion calls that insert them, in document order.
+ */
+export function scriptElements(program, folder) {
+    const elements = new Map();
+    if (!syntaxNeeds(program, true, false).elements)
+        return elements;
+    const of = (node) => [...folder.elementsOf(node)].map((call) => {
+        let element = elements.get(call);
+        if (element === undefined)
+            elements.set(call, (element = { src: [], type: [], integrity: [], noModule: [], text: [], inserts: [] }));
+        return element;
+    });
+    walkTree(program, {
+        enter(node) {
+            if (node.type === 'AssignmentExpression' && node['operator'] === '=') {
+                const left = node['left'];
+                if (left.type !== 'MemberExpression')
+                    return;
+                const name = propertyName(left);
+                const value = node['right'];
+                if (name === 'src' || name === 'type' || name === 'integrity')
+                    for (const element of of(left['object']))
+                        element[name].push(value);
+                else if (name === 'noModule')
+                    for (const element of of(left['object']))
+                        element.noModule.push(value);
+                else if (name !== undefined && textMembers.has(name))
+                    for (const element of of(left['object']))
+                        element.text.push(value);
+                return;
+            }
+            if (node.type !== 'CallExpression')
+                return;
+            const callee = node['callee'];
+            if (callee.type !== 'MemberExpression')
+                return;
+            const method = propertyName(callee);
+            if (method === undefined)
+                return;
+            const args = node['arguments'];
+            const receiver = callee['object'];
+            if (method === 'removeAttribute' && args.length >= 1 && args[0].type !== 'SpreadElement') {
+                const key = folder.strings(args[0]);
+                if (!key.unknown && key.values.length === 1 && key.values[0].toLowerCase() === 'nomodule')
+                    for (const element of of(receiver))
+                        element.noModule.push(false);
+                return;
+            }
+            if (method === 'setAttribute' && args.length >= 2 && args[0].type !== 'SpreadElement') {
+                // An attribute name is lowercased on an HTML element. A name that doesn't fold touches neither.
+                const key = folder.strings(args[0]);
+                if (key.unknown || key.values.length !== 1)
+                    return;
+                const name = key.values[0].toLowerCase();
+                if (name === 'src' || name === 'type' || name === 'integrity')
+                    for (const element of of(receiver))
+                        element[name].push(args[1]);
+                // A boolean attribute is set whatever its value (HTML § Boolean attributes).
+                else if (name === 'nomodule')
+                    for (const element of of(receiver))
+                        element.noModule.push(true);
+                return;
+            }
+            const nodes = insertions.get(method);
+            if (nodes === undefined)
+                return;
+            const inserted = nodes === 'all' ? args : args.slice(nodes, nodes + 1);
+            for (const arg of inserted) {
+                if (arg.type === 'SpreadElement')
+                    continue;
+                for (const element of of(arg))
+                    element.inserts.push(node);
+                // A text node appended to a script element is its code.
+                const text = textNodeCode(arg);
+                if (text !== undefined && (method === 'appendChild' || method === 'append'))
+                    for (const element of of(receiver))
+                        element.text.push(text);
+            }
+        },
+    });
+    return elements;
+}
+/** The code of `X.createTextNode(code)`. */
+function textNodeCode(node) {
+    if (node.type !== 'CallExpression')
+        return undefined;
+    const callee = node['callee'];
+    const [code] = node['arguments'];
+    if (callee.type !== 'MemberExpression' || propertyName(callee) !== 'createTextNode' || code === undefined)
+        return undefined;
+    return code.type === 'SpreadElement' ? undefined : code;
+}
+/**
+ * The code an injected element with no `src` carries, by the call that first inserts it: the expressions its
+ * text is set to.
+ */
+export function scriptTexts(program, folder) {
+    const texts = new Map();
+    for (const element of scriptElements(program, folder).values()) {
+        if (element.src.length > 0 || element.text.length === 0)
+            continue;
+        const [insert] = element.inserts;
+        if (insert === undefined)
+            continue;
+        texts.set(insert, [...(texts.get(insert) ?? []), ...element.text]);
+    }
+    return texts;
+}
+/** The injected scripts of a program (above), by `src` write, in document order. */
+function injectedSites(program, folder, at) {
+    const sites = [];
+    for (const element of scriptElements(program, folder).values()) {
+        if (element.inserts.length === 0 || element.src.length === 0)
+            continue;
+        const types = [];
+        if (element.type.length === 0)
+            types.push(undefined);
+        for (const type of element.type) {
+            const folded = folder.strings(type);
+            types.push(...folded.values);
+            if (folded.unknown)
+                types.push(null);
+        }
+        const integrities = element.integrity.map((value) => folder.strings(value));
+        // Every write's constants are the alternatives; a write that doesn't fold makes the value none.
+        const integrity = integrities.some((each) => each.unknown) ? [] : [...new Set(integrities.flatMap((each) => each.values))].sort();
+        const noModule = noModuleOf(element.noModule);
+        for (const src of element.src) {
+            const folded = alternatives(src, folder, at);
+            if (folded === undefined)
+                continue;
+            sites.push({ location: at(src), ...folded, types: [...new Set(types)], integrity, noModule });
+        }
+    }
+    return sites.sort((a, b) => a.location.start - b.location.start);
+}
+/** Whether an expression is truthy, when it is a constant: a literal, `!`, `void` or `undefined`. */
+function truthiness(node) {
+    switch (node.type) {
+        case 'Literal':
+            return Boolean(node['value']);
+        case 'ParenthesizedExpression':
+            return truthiness(node['expression']);
+        case 'Identifier':
+            return node['name'] === 'undefined' ? false : undefined;
+        case 'UnaryExpression': {
+            if (node['operator'] === 'void')
+                return false;
+            const argument = node['operator'] === '!' ? truthiness(node['argument']) : undefined;
+            return argument === undefined ? undefined : !argument;
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * Whether an element's `noModule` is set: every write is an alternative, as `src`'s are. `yes` when each is
+ * truthy, `no` when each is falsy or there is none, and `maybe` when they differ or one doesn't fold.
+ */
+function noModuleOf(writes) {
+    const values = new Set();
+    for (const write of writes) {
+        if (typeof write === 'boolean')
+            values.add(write);
+        else
+            for (const alternative of branches(write))
+                values.add(truthiness(alternative));
+    }
+    if (values.size === 0 || (values.size === 1 && values.has(false)))
+        return 'no';
+    return values.size === 1 && values.has(true) ? 'yes' : 'maybe';
+}
+/** The worker functions a callee path names (`new` or a call), without the global object's names before it. */
+function isWorkerCall(node) {
+    const path = [];
+    let at = node['callee'];
+    for (;;) {
+        if (at.type === 'ChainExpression' || at.type === 'ParenthesizedExpression')
+            at = at['expression'];
+        else if (at.type === 'SequenceExpression')
+            at = at['expressions'].at(-1);
+        else
+            break;
+    }
+    while (at.type === 'MemberExpression') {
+        const name = propertyName(at);
+        if (name === undefined)
+            return false;
+        path.unshift(name);
+        at = at['object'];
+    }
+    if (at.type !== 'Identifier')
+        return false;
+    path.unshift(at['name']);
+    while (path.length > 1 && ['window', 'self', 'globalThis'].includes(path[0]))
+        path.shift();
+    const spelt = path.join('.');
+    if (node.type === 'NewExpression')
+        return spelt === 'Worker' || spelt === 'SharedWorker';
+    return spelt === 'navigator.serviceWorker.register' || spelt === 'importScripts';
+}
+/** The worker URLs of a program that aren't literals (above), in document order. */
+function workerSites(program, folder, at) {
+    const sites = [];
+    walkTree(program, {
+        enter(node) {
+            if ((node.type !== 'NewExpression' && node.type !== 'CallExpression') || !isWorkerCall(node))
+                return;
+            const args = node['arguments'];
+            const importScripts = node.type === 'CallExpression' && !/register$/.test(calleeName(node));
+            for (const url of importScripts ? args : args.slice(0, 1)) {
+                if (url.type === 'SpreadElement' || isLiteral(url))
+                    continue;
+                // Only `importScripts` loads chunks: another worker call's URL is its worker's however it is built.
+                const folded = alternatives(url, folder, at, importScripts);
+                if (folded !== undefined)
+                    sites.push({ location: at(url), ...folded });
+            }
+        },
+    });
+    return sites;
+}
+/** The last name a callee spells. */
+function calleeName(call) {
+    let at = call['callee'];
+    while (at.type === 'ChainExpression' || at.type === 'ParenthesizedExpression')
+        at = at['expression'];
+    if (at.type === 'SequenceExpression')
+        at = at['expressions'].at(-1);
+    if (at.type === 'Identifier')
+        return at['name'];
+    return at.type === 'MemberExpression' ? (propertyName(at) ?? '') : '';
+}
+const isLiteral = (node) => (node.type === 'Literal' && typeof node['value'] === 'string') ||
+    (node.type === 'TemplateLiteral' && node['expressions'].length === 0);
+/**
+ * A URL expression's alternatives: the branches of a conditional and both sides of `||`, `??` and `&&`, each
+ * folded. The URLs they fold to, and where each alternative that doesn't is. Undefined, when the site `loadsChunks`,
+ * if it calls a chunk loader's URL function, which makes it a chunk load.
+ */
+function alternatives(node, folder, at, loadsChunks = true) {
+    const urls = new Set();
+    const unknown = [];
+    for (const alternative of branches(node)) {
+        const folded = folder.strings(alternative);
+        if (folded.chunk && loadsChunks)
+            return undefined;
+        for (const value of folded.values)
+            urls.add(value);
+        if (folded.unknown)
+            unknown.push(at(alternative));
+    }
+    return { urls: [...urls].sort(), unknown };
+}
+function branches(node) {
+    switch (node.type) {
+        case 'ParenthesizedExpression':
+            return branches(node['expression']);
+        case 'ConditionalExpression':
+            return [...branches(node['consequent']), ...branches(node['alternate'])];
+        case 'LogicalExpression':
+            // Either side may be the value: the left one when it decides the operator, the right one otherwise.
+            return [...branches(node['left']), ...branches(node['right'])];
+        default:
+            return [node];
+    }
+}

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

@@ -0,0 +1,177 @@
+import { type AstNode } from './ast.ts';
+import type { Definitions } from './definitions.ts';
+import type { ModuleLink } from './module-links.ts';
+import type { ScopeRules } from './scope.ts';
+/** Free names a `typeof` test shows are defined, each with the test. */
+type Guards = ReadonlyMap<string, AstNode>;
+/** A call of a known function, where its arguments are. */
+export interface CallSite {
+    /** The call or `new` expression. */
+    call: AstNode;
+    /** The function called. */
+    fn: AstNode;
+    /** The arguments, from the first one bound to the first parameter (after `.call`'s or `.apply`'s `this`). */
+    args: readonly AstNode[];
+    /** The index from which the arguments can't be listed: a spread, or `.apply` of anything but an array literal. */
+    unlisted?: number;
+    /** Whether `this` at the call is the script's top-level `this`. */
+    topLevel: boolean;
+    /** The `typeof` guards around the call, which show a free name is defined there. */
+    guards: Guards;
+    /** The function whose own code holds the call, if any. */
+    within: AstNode | undefined;
+    /** The loops and the function around the call, innermost first, out to the function whose own code holds it. */
+    contexts: readonly AstNode[];
+    /**
+     * For a callback an iteration native calls (§5 Resolver capabilities 4), the native and the collection it visits:
+     * `names` in `names.forEach(cb)`, `names` in `Array.from(names, cb)`. Its arguments are the elements' (`Binding`).
+     */
+    iterates?: {
+        native: string;
+        collection: AstNode;
+    };
+    /**
+     * What `this` is in the call (§5 Resolver capabilities 3): the instance a `new` makes (`new`), or an expression
+     * evaluated where the call is: the object a method is read from (`o` in `o.m()`), or a `thisArg` (`f.call(t)`), or
+     * `none` for a call that passes no `this`: a plain call `f()`, `f.call()`, or an iteration native's callback with no
+     * `thisArg`. ECMA-262 binds the global object as a sloppy function's `this` there, and `undefined` as a strict
+     * one's. Left out when the call's `this` is unknown, as a spread `thisArg` is.
+     */
+    receiver?: 'new' | 'none' | AstNode;
+    /**
+     * For a call the syntax doesn't name, the module links its callee's value came through (§6): `(0, o.H7)(…)` calls
+     * module 8974's export `H7`. The trace records each as a `module-link` step before the call's.
+     */
+    links?: {
+        node: AstNode;
+        link: ModuleLink;
+    }[];
+}
+/** Where a call is: what a call site needs, whichever function it turns out to call. */
+export interface CallInfo {
+    topLevel: boolean;
+    guards: Guards;
+    within: AstNode | undefined;
+    contexts: readonly AstNode[];
+}
+/** A call site, with the frame its arguments are evaluated in: none for a call no function around it needs. */
+export interface Binding {
+    site: CallSite;
+    caller: Frame | undefined;
+    /** For an iteration native's callback, the index of the element this call visits. */
+    element?: number;
+    /**
+     * For a call of a function value (§5 Resolver capabilities 3), the frame the function was created in: its closure,
+     * whose bindings the function reads. For a call by name, the frame of the code the call is in that holds the function.
+     */
+    closure?: Frame | undefined;
+    /** A key for the receiver when the binding has a precomputed one, so that two receivers make two frames. */
+    receiverKey?: string;
+}
+/** An instantiation of a function (above). */
+export interface Frame {
+    fn: AstNode;
+    bindings: readonly Binding[];
+    /** A key that two instantiations of the same function in the same context share. */
+    id: string;
+    /** How many frames the chain out from this one holds. */
+    depth: number;
+    /**
+     * How the frame came about: one call, several merged by the context cap, every call, widened, or none: a function
+     * object that no resolved call reaches, judged from where it was created (`creation`, §5, §7).
+     */
+    how: 'call' | 'merged' | 'widened' | 'creation';
+    /**
+     * For a loop's iteration, or an iteration native's callback, the frame of the code it runs within: the function or
+     * loop around the loop, or the code that calls the native. Its parameters and loop variables are read through it.
+     */
+    outer?: Frame | undefined;
+    /** For a loop's iteration, its index. */
+    iteration?: number;
+    /** The loop or call whose iterations the iteration cap cut, when this frame is one of the iterations done. */
+    cut?: AstNode;
+    /**
+     * For an iteration over a catalog-bounded list (§5 Resolver capabilities 9): no cap bounds its iterations, nor
+     * the frames of the calls made in them, and only the step budget bounds them.
+     */
+    bounded?: true;
+    /** For a `creation` frame, the node its function object was created or assumed to be held at, for the trace. */
+    created?: AstNode;
+    /**
+     * For a `creation` frame whose function has a `this` of its own, the object it is shown to be held on (a value of the
+     * resolution's), and the node that made that object.
+     */
+    receiver?: unknown;
+    receiverNode?: AstNode;
+}
+export interface CallGraph {
+    /** The calls of known functions a call expression is: one per function its callee can be. */
+    sitesOf(call: AstNode): readonly CallSite[];
+    /** Whether the callee of a call can be something other than the functions `sitesOf` lists. */
+    open(call: AstNode): boolean;
+    /** Every call of a function, in document order. */
+    callsOf(fn: AstNode): readonly CallSite[];
+    /** The function whose own code holds `node`, if any. */
+    functionOf(node: AstNode): AstNode | undefined;
+    /** Where a call or `new` expression is. */
+    infoOf(call: AstNode): CallInfo | undefined;
+    /** Every call and `new` expression of the program, in document order. */
+    allCalls(): readonly AstNode[];
+}
+export declare const isFunction: (node: AstNode) => boolean;
+/** A loop statement, which may be unrolled (§5 Resolver capabilities 4). */
+export declare const isLoop: (node: AstNode) => boolean;
+/**
+ * The natives that call a callback once per element of an array (ECMA-262), by method name, with the index of the
+ * callback's parameter that takes the element. `from` is `Array.from(items, mapfn)`.
+ */
+export declare const iterationNatives: ReadonlyMap<string, {
+    element: number;
+}>;
+/**
+ * The calls in a program, and the functions they call. `guardsAt(parent, child)` gives the `typeof` guards a branch
+ * adds, as the resolver's walk takes them.
+ */
+export declare function callGraph(program: AstNode, scope: ScopeRules, definitions: Definitions, guardsAt: (parent: AstNode, child: AstNode) => Guards): CallGraph;
+export declare const isClass: (node: AstNode) => boolean;
+/**
+ * The code a `new` of a class runs as its constructor: its `constructor` method's function, or the class itself when it
+ * has none. Its frames are the class's constructions, whose `this` is the instance made.
+ */
+export declare function constructorOf(cls: AstNode): AstNode;
+/**
+ * A frame id that stays bounded. A merged frame's id names every frame it merges, and a call's names its caller and
+ * closure, so under raised caps ids grew geometrically with the depth of the chain, until a join exceeded the maximum
+ * string length and threw `RangeError: Invalid string length`. Past `maxFrameIdLength` an id is replaced
+ * by its leading characters and a digest of the whole, which is as deterministic as the id, and tells frames apart as
+ * well (128 bits).
+ */
+export declare function frameId(id: string): string;
+/**
+ * A frame for one call of `site.fn`, with the frame its arguments are evaluated in. `closure` is the frame the function
+ * was created in, which it reads its free variables through (`outer`), and `receiverKey` tells apart the frames of one
+ * call whose receivers differ: a method is instantiated once per receiver object (§5 Resolver capabilities 5).
+ */
+export declare function callFrame(site: CallSite, caller: Frame | undefined, closure?: Frame, receiverKey?: string): Frame;
+/**
+ * Frames in document order: by where their first call is, then the function called, then their ids, which name the
+ * positions of the calls out along their chains. Whatever order the resolver found them in, the order it works through
+ * them in is this one, so results are independent of visit order (§18 Context policy).
+ */
+export declare function framesInDocumentOrder<T extends Frame>(frames: readonly T[]): T[];
+/** Call sites in document order: by where the call is, then the function called. */
+export declare const sitesInDocumentOrder: (sites: readonly CallSite[]) => CallSite[];
+/** The widened frame of a function: every call of it, with the arguments evaluated in no frame (above). */
+export declare function widenedFrame(fn: AstNode, calls: readonly CallSite[]): Frame;
+/** Frames of one function merged into one, whose parameters take the arguments of every one of their calls. */
+export declare function mergedFrame(fn: AstNode, unordered: readonly Frame[]): Frame;
+/** Whether `fn` is instantiated in `frame` or a frame out from it. */
+export declare function onChain(frame: Frame | undefined, fn: AstNode): boolean;
+/**
+ * The frame `frame` runs `code` in: `frame` itself or one it runs within (`outer`), out through loops and iteration
+ * natives' callbacks. Undefined when none of them instantiates `code`.
+ */
+export declare function frameOf(frame: Frame | undefined, code: AstNode): Frame | undefined;
+/** The loop or call whose iterations the iteration cap cut, when `frame` is one of the iterations done, or runs in one. */
+export declare function cutIn(frame: Frame | undefined): AstNode | undefined;
+export {};