monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/analysis/lib/scope.js

@@ -0,0 +1,443 @@
+// monkeypatchlist's scope post-passes (§5 Parsing and scope), which run above the binding-resolution seam (§19). The seam
+// resolves names under standard ES2015+ block scoping; these passes correct it for how browsers run the code:
+//
+// 1. In a classic script, global-scope `var` and `function` declarations bind properties of the global object, and
+//    `let`, `const` and `class` do not.
+// 2. Annex B block-function hoisting: in sloppy code, a plain function declared in a block also gets a var binding in
+//    its function, or in a classic script's global object (ECMA-262 B.3.2).
+// 3. `with` and direct-`eval` taint: a `with` block on a name's resolution path could redirect it to an object
+//    property, and a direct `eval` in a sloppy function on it could declare a shadowing `var`. Both lower target
+//    confidence (§9) rather than change the resolution.
+// 4. An unqualified `delete x` of a name these rules bind on the global object is a global delete. The resolver reports
+//    it, and `isStrict` rules out strict code, where it is a SyntaxError.
+//
+// For constant propagation (§5 Resolver capabilities 1), `constant` gives the `const` declaration a local name resolves
+// to after these passes, with the taint between the two.
+//
+// They also place the declarations of nested code (§2): a literal direct eval's code, grafted in place of its literal
+// as an arrow function (`ScopeOptions.directEvals`), declares its top-level `var`s and functions in its caller's var
+// scope when it is sloppy, and in a var scope of its own when it is strict. Global code resolves a name the host
+// script declares lexically at its top level to that declaration (`ScopeOptions.lexicalGlobals`), and strict eval code
+// keeps its top-level `var`s to itself (`ScopeOptions.evalCode`).
+import { isEvalCall, walkTree } from "./ast.js";
+export function scopeRules(program, sourceType, bindings, options = {}) {
+    const { directEvals = new Set(), lexicalGlobals = new Set(), evalCode = false, imports } = options;
+    const resolution = bindings.resolve(program, sourceType);
+    const regions = collectRegions(program, sourceType, directEvals);
+    let declarations;
+    /**
+     * Whether a region's top-level `var`s and functions bind the global object's properties: a classic script's, unless
+     * it is strict eval code, and sloppy direct-eval code's whose caller's var scope does.
+     */
+    const bindsGlobals = (region) => {
+        if (region.kind === 'eval')
+            return !region.strict && bindsGlobals(varScopeAround(region));
+        return region.kind === 'program' && sourceType === 'script' && !(evalCode && region.strict);
+    };
+    /**
+     * Post-pass 2: an Annex B var binding in a function the reference sits in hides whatever the seam found outside it.
+     * Returns the var scope with that binding, if there is one, or else the var scope the seam's declaration is in.
+     */
+    const varScopeOf = (id, resolved) => {
+        const name = id['name'];
+        for (let region = innermost(regions, id.start); region !== null; region = region.parent) {
+            if (!isVarScope(region))
+                continue;
+            if (resolved !== 'unresolved' && declaredWithin(resolved, region))
+                return { scope: region };
+            const hoisted = region.annexB.get(name);
+            if (hoisted !== undefined)
+                return { hoisted, region };
+        }
+        return {};
+    };
+    /** What a reference resolves to: a declaration that binds the global object's property, none at all, or a local. */
+    const bind = (id) => {
+        const name = id['name'];
+        const resolved = resolution.reference(id);
+        const found = varScopeOf(id, resolved);
+        if ('hoisted' in found)
+            return bindsGlobals(found.region) ? { kind: 'block-function', node: found.hoisted } : 'local';
+        const { scope } = found;
+        // Global code sees the host script's top-level lexical declarations before the global object's properties.
+        if (resolved === 'unresolved')
+            return lexicalGlobals.has(name) ? 'local' : undefined;
+        const declaration = resolved.declaration;
+        const kind = declaration.type === 'FunctionDeclaration' ? 'function' : 'var';
+        const varScoped = kind === 'function' || (declaration.type === 'VariableDeclaration' && declaration['kind'] === 'var');
+        // A top-level var or function of direct-eval code is declared in the var scope that code's declarations go to.
+        if (scope?.kind === 'eval' && resolved.scopeKind === 'function' && varScoped && declaration !== scope.node) {
+            return bindsGlobals(scope) ? { kind, node: declaration } : 'local';
+        }
+        // Post-pass 1: a classic script's global-scope var and function bind the global object's property.
+        if (resolved.scopeKind !== 'global' || !varScoped || !bindsGlobals(regions[0]))
+            return 'local';
+        return { kind, node: declaration };
+    };
+    /**
+     * Post-pass 3: the `with` blocks and the functions around a reference, out to the first region that holds `until`,
+     * are on its resolution path. A `with` block could redirect the name to an object property, and a direct eval in one
+     * of those functions, in sloppy code, could declare a `var` there that shadows it.
+     */
+    const taintOf = (id, until) => {
+        const withs = [];
+        const evals = [];
+        for (let region = innermost(regions, id.start); region !== null; region = region.parent) {
+            if (until !== undefined && region.start <= until.start && until.end <= region.end)
+                break;
+            if (region.kind === 'with')
+                withs.unshift(region.site);
+            if (region.kind === 'function')
+                evals.push(...region.evals.filter((call) => bind(call['callee']) !== 'local'));
+        }
+        evals.sort((a, b) => a.start - b.start);
+        return { withs, evals };
+    };
+    /** The variable an import binding of a link group is, when `id` reads one (`ScopeOptions.imports`). */
+    const linked = (id, resolved) => {
+        if (imports === undefined || resolved === 'unresolved')
+            return undefined;
+        return imports(resolved.declaration, id['name']);
+    };
+    return {
+        resolve(id) {
+            const declaration = bind(id);
+            if (declaration === 'local')
+                return 'local';
+            // A name bound on the global object has the whole scope chain on its path. At the top of a classic script, a var
+            // a direct eval declares is the global object's property itself.
+            return { ...(declaration === undefined ? {} : { declaration }), ...taintOf(id) };
+        },
+        constant(id) {
+            const resolved = resolution.reference(id);
+            if (resolved === 'unresolved')
+                return undefined;
+            const import_ = linked(id, resolved);
+            const declaration = import_?.declaration ?? resolved.declaration;
+            if (declaration.type !== 'VariableDeclaration' || declaration['kind'] !== 'const')
+                return undefined;
+            // An import's variable is in another module: nothing between the two can shadow it.
+            if (import_ !== undefined)
+                return { declaration, withs: [], evals: [] };
+            if ('hoisted' in varScopeOf(id, resolved))
+                return undefined;
+            // A constant's path ends at the region it is declared in. A direct eval in the constant's own var scope can't
+            // shadow it: its `var` would clash with the `const`, a SyntaxError.
+            return { declaration, ...taintOf(id, declaration) };
+        },
+        declaration(id) {
+            const resolved = resolution.reference(id);
+            if (resolved === 'unresolved' || 'hoisted' in varScopeOf(id, resolved))
+                return undefined;
+            return linked(id, resolved)?.declaration ?? resolved.declaration;
+        },
+        nameOf(id) {
+            if (imports === undefined)
+                return id['name'];
+            const resolved = resolution.reference(id);
+            return linked(id, resolved)?.name ?? id['name'];
+        },
+        isStrict: (offset) => innermost(regions, offset).strict,
+        declared: (node) => (declarations ??= globalDeclarations()).get(node),
+    };
+    /** The declarations that bind names of the global object's, by node (`declared`). */
+    function globalDeclarations() {
+        const found = new Map();
+        const regionOf = new Map(regions.map((region) => [region.node, region]));
+        // The var scopes the walk is in: the program, and the direct-eval code grafted in it. It never enters a function.
+        const scopes = [];
+        const lexical = sourceType === 'script' && !evalCode;
+        const configurableIn = (region) => region.kind === 'eval' || evalCode;
+        walkTree(program, {
+            enter(node, parent) {
+                const region = regionOf.get(node);
+                const opens = region !== undefined && (region.kind === 'program' || region.kind === 'eval');
+                if (!opens && (functionTypes.has(node.type) || node.type === 'StaticBlock' || node.type === 'ClassExpression')) {
+                    if (node.type === 'FunctionDeclaration')
+                        functionDeclaration(node, parent);
+                    return false;
+                }
+                if (node.type === 'ClassDeclaration') {
+                    if (lexical && parent === program)
+                        found.set(node, { kind: 'class', configurable: false });
+                    return false;
+                }
+                if (opens)
+                    scopes.push(region);
+                if (node.type === 'VariableDeclaration') {
+                    const scope = scopes.at(-1);
+                    if (node['kind'] === 'var') {
+                        const loop = (parent?.type === 'ForInStatement' || parent?.type === 'ForOfStatement') && parent['left'] === node;
+                        if (bindsGlobals(scope))
+                            found.set(node, { kind: 'var', configurable: configurableIn(scope), ...(loop ? { loop } : {}) });
+                    }
+                    else if (lexical && parent === program && (node['kind'] === 'let' || node['kind'] === 'const')) {
+                        found.set(node, { kind: node['kind'], configurable: false });
+                    }
+                }
+            },
+            leave(node) {
+                if (scopes.at(-1)?.node === node)
+                    scopes.pop();
+            },
+        });
+        return found;
+        /** A function declaration: at the top level of the var scope, or a block-level one Annex B hoists there. */
+        function functionDeclaration(node, parent) {
+            const scope = scopes.at(-1);
+            const name = node['id']?.['name'];
+            if (name === undefined || !bindsGlobals(scope))
+                return;
+            // The top level of eval code is the body of the arrow function grafted in place of its literal.
+            const topLevel = scope.kind === 'eval' ? parent === scope.node['body'] : parent === program;
+            if (topLevel)
+                found.set(node, { kind: 'function', configurable: configurableIn(scope) });
+            else if (scope.annexB.get(name) === node)
+                found.set(node, { kind: 'block-function', configurable: configurableIn(scope) });
+        }
+    }
+}
+/**
+ * The names a classic script declares lexically at its top level (`let`, `const`, `using`, `class`). They are global
+ * bindings that are not properties of the global object, and global code sees them. A module's are its own.
+ */
+export function globalLexicalNames(program, sourceType) {
+    return sourceType === 'module' ? new Set() : lexicallyDeclared(program['body'], true);
+}
+/**
+ * A classic script's top-level `let`, `const` and `class` declarations, in document order, each with the identifier it
+ * binds: the names the scan-wide lexical-name check collects (§3 Declarations in classic scripts). A module's are its
+ * own, so it has none.
+ */
+export function globalLexicalDeclarations(program, sourceType) {
+    if (sourceType === 'module')
+        return [];
+    return program['body'].flatMap((statement) => {
+        if (statement.type === 'ClassDeclaration') {
+            const id = statement['id'];
+            return id === null ? [] : [{ name: id['name'], kind: 'class', id }];
+        }
+        if (statement.type !== 'VariableDeclaration')
+            return [];
+        const kind = statement['kind'];
+        if (kind !== 'let' && kind !== 'const')
+            return [];
+        return statement['declarations'].flatMap((declarator) => boundIdentifiers(declarator['id']).map((id) => ({ name: id['name'], kind, id })));
+    });
+}
+/** Whether a region is a var scope for the names in it: the program, a function, or grafted direct-eval code. */
+const isVarScope = (region) => region.kind === 'program' || region.kind === 'function' || region.kind === 'eval';
+/**
+ * Whether a region is the var scope its code's `var`s and direct evals go to: sloppy direct-eval code declares them
+ * in its caller's var scope (ECMA-262 EvalDeclarationInstantiation), and strict eval code in its own.
+ */
+const declaresVars = (region) => isVarScope(region) && !(region.kind === 'eval' && !region.strict);
+/** The var scope that code in `region`, but outside any var scope in it, declares its `var`s in. */
+function varScopeAround(region) {
+    let around = region.parent;
+    while (!declaresVars(around))
+        around = around.parent;
+    return around;
+}
+/**
+ * Whether the seam's declaration lies in `region`'s var scope or a scope inside it. A function's parameters and its
+ * `arguments` are declared by the function node in its own `function` scope; its name is declared outside it.
+ */
+function declaredWithin(resolved, region) {
+    const declaration = resolved.declaration;
+    if (declaration === region.node)
+        return resolved.scopeKind === 'function';
+    return region.start <= declaration.start && declaration.end <= region.end;
+}
+/** The innermost region that contains `offset`. Regions are in document order, each after the regions around it. */
+function innermost(regions, offset) {
+    let low = 0;
+    let high = regions.length - 1;
+    while (low < high) {
+        const middle = (low + high + 1) >> 1;
+        if (regions[middle].start <= offset)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    let region = regions[low];
+    while (region !== null && !(region.start <= offset && offset < region.end))
+        region = region.parent;
+    return region ?? regions[0];
+}
+const functionTypes = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression']);
+/**
+ * Walks the program once, and returns its regions in document order, with their strictness, parameters and Annex B
+ * bindings.
+ */
+function collectRegions(program, sourceType, directEvals) {
+    const regions = [];
+    const open = [];
+    // The names each enclosing block-like scope declares lexically, with the node that opened it. A function or the
+    // program opens a var scope's entry: the names at its top level.
+    const lexical = [];
+    const openRegion = (kind, node, strict, params = new Set(), site) => {
+        const region = {
+            kind,
+            node,
+            ...(site === undefined ? {} : { site }),
+            start: node.start,
+            end: node.end,
+            parent: open.at(-1) ?? null,
+            strict,
+            params,
+            annexB: new Map(),
+            evals: [],
+        };
+        regions.push(region);
+        open.push(region);
+    };
+    const strict = () => open.at(-1).strict;
+    walkTree(program, {
+        enter(node, parent) {
+            if (parent?.type === 'WithStatement' && parent['body'] === node)
+                openRegion('with', node, strict(), new Set(), parent);
+            if (node.type === 'Program') {
+                const body = node['body'];
+                openRegion('program', node, sourceType === 'module' || hasUseStrict(body));
+                lexical.push({ owner: node, names: lexicallyDeclared(body, true), varScope: true });
+            }
+            else if (functionTypes.has(node.type)) {
+                const body = node['body'];
+                const statements = body.type === 'BlockStatement' ? body['body'] : [];
+                const params = new Set(node['params'].flatMap(boundNames));
+                openRegion(directEvals.has(node) ? 'eval' : 'function', node, strict() || hasUseStrict(statements), params);
+                lexical.push({ owner: node, names: lexicallyDeclared(statements, true), varScope: true });
+            }
+            else if (node.type === 'ClassDeclaration' || node.type === 'ClassExpression') {
+                openRegion('class', node, true);
+            }
+            else if (node.type === 'BlockStatement' && !(parent !== null && functionTypes.has(parent.type))) {
+                // A function's body is a BlockStatement too, but it belongs to the function's var scope.
+                const statements = node['body'];
+                lexical.push({ owner: node, names: lexicallyDeclared(statements, false), varScope: false });
+                hoistBlockFunctions(statements);
+            }
+            else if (node.type === 'SwitchStatement') {
+                const statements = node['cases'].flatMap((clause) => clause['consequent']);
+                lexical.push({ owner: node, names: lexicallyDeclared(statements, false), varScope: false });
+                hoistBlockFunctions(statements);
+            }
+            else if (isEvalCall(node)) {
+                if (!strict())
+                    open.findLast(declaresVars).evals.push(node);
+            }
+            else {
+                const names = lexicalHead(node);
+                if (names.length > 0)
+                    lexical.push({ owner: node, names: new Set(names), varScope: false });
+            }
+        },
+        leave(node) {
+            if (open.at(-1)?.node === node)
+                open.pop();
+            if (lexical.at(-1)?.owner === node)
+                lexical.pop();
+        },
+    });
+    return regions;
+    /**
+     * Annex B (B.3.2.1, B.3.2.2): in sloppy code, each plain function declared directly in a block or case clause gets a
+     * var binding in its var scope, unless its name is a parameter, or declaring `var` of it there would clash with a
+     * lexical declaration in an enclosing block or at the top of the var scope.
+     */
+    function hoistBlockFunctions(statements) {
+        if (strict())
+            return;
+        const region = open.findLast(isVarScope);
+        for (const statement of statements) {
+            if (statement.type !== 'FunctionDeclaration' || statement['async'] === true || statement['generator'] === true) {
+                continue;
+            }
+            const name = statement['id']['name'];
+            if (region.params.has(name) || clashes(name))
+                continue;
+            if (!region.annexB.has(name))
+                region.annexB.set(name, statement);
+        }
+    }
+    /** Whether an enclosing block, below the one just entered, or the var scope's top level declares `name` lexically. */
+    function clashes(name) {
+        for (let i = lexical.length - 2; i >= 0; i--) {
+            if (lexical[i].names.has(name))
+                return true;
+            if (lexical[i].varScope)
+                return false;
+        }
+        return false;
+    }
+}
+/**
+ * The names a `for` head declares lexically, or a catch clause whose parameter is a pattern. A catch parameter that is
+ * a plain identifier doesn't clash with a `var` of its name in the clause (B.3.4).
+ */
+function lexicalHead(node) {
+    if (node.type === 'ForStatement' || node.type === 'ForInStatement' || node.type === 'ForOfStatement') {
+        const head = (node.type === 'ForStatement' ? node['init'] : node['left']);
+        if (head?.type !== 'VariableDeclaration' || head['kind'] === 'var')
+            return [];
+        return head['declarations'].flatMap((declarator) => boundNames(declarator['id']));
+    }
+    if (node.type === 'CatchClause') {
+        const param = node['param'];
+        return param === null || param.type === 'Identifier' ? [] : boundNames(param);
+    }
+    return [];
+}
+/**
+ * The names a statement list declares lexically: `let`, `const`, `using` and `class`, and in a block (not at the top of
+ * a function or script, where they are var-scoped) function declarations.
+ */
+function lexicallyDeclared(statements, topLevel) {
+    const names = new Set();
+    for (const statement of statements) {
+        if (statement.type === 'VariableDeclaration' && statement['kind'] !== 'var') {
+            for (const declarator of statement['declarations']) {
+                for (const name of boundNames(declarator['id']))
+                    names.add(name);
+            }
+        }
+        else if (statement.type === 'ClassDeclaration' || (!topLevel && statement.type === 'FunctionDeclaration')) {
+            const id = statement['id'];
+            if (id !== null)
+                names.add(id['name']);
+        }
+    }
+    return names;
+}
+/** The names a binding pattern binds. */
+export function boundNames(pattern) {
+    return boundIdentifiers(pattern).map((id) => id['name']);
+}
+/** The identifiers a binding pattern binds, in document order. */
+export function boundIdentifiers(pattern) {
+    switch (pattern.type) {
+        case 'Identifier':
+            return [pattern];
+        case 'ObjectPattern':
+            return pattern['properties'].flatMap((property) => boundIdentifiers((property.type === 'RestElement' ? property['argument'] : property['value'])));
+        case 'ArrayPattern':
+            return pattern['elements'].flatMap((element) => (element === null ? [] : boundIdentifiers(element)));
+        case 'AssignmentPattern':
+            return boundIdentifiers(pattern['left']);
+        case 'RestElement':
+            return boundIdentifiers(pattern['argument']);
+        default:
+            return [];
+    }
+}
+/** Whether a directive prologue holds a Use Strict Directive: exactly `"use strict"` or `'use strict'`. */
+function hasUseStrict(statements) {
+    for (const statement of statements) {
+        if (typeof statement['directive'] !== 'string')
+            return false;
+        if (statement['directive'] === 'use strict')
+            return true;
+    }
+    return false;
+}

package/dist/packages/analysis/lib/script-loads.d.ts

@@ -0,0 +1,56 @@
+import { type AstNode } from './ast.ts';
+import type { BindingResolver } from './binding.ts';
+import { Folder, type ChunkLoadSite } from './chunk-loads.ts';
+import type { GeneratedLocation } from './types.ts';
+/**
+ * An injected script's `src` write (above): where its value is, the URLs it folds to, where each alternative that
+ * doesn't fold is, and the element's `type` alternatives (undefined: no `type` is set; null: one that doesn't fold)
+ * the constants its `integrity` may be (none when it has no write, or one that doesn't fold), and whether its
+ * `noModule` is set: every write is truthy, or every one is falsy or there is none, or the writes differ or one doesn't
+ * fold.
+ */
+export interface InjectedSite {
+    location: GeneratedLocation;
+    urls: string[];
+    unknown: GeneratedLocation[];
+    types: (string | null | undefined)[];
+    integrity: string[];
+    noModule: 'no' | 'yes' | 'maybe';
+}
+/** A worker URL that isn't a literal: where it is, the URLs it folds to, and where each unknown alternative is. */
+export interface WorkerSite {
+    location: GeneratedLocation;
+    urls: string[];
+    unknown: GeneratedLocation[];
+}
+/** What an artifact's code loads that only the resolver can see. */
+export interface ScriptLoads {
+    chunks: ChunkLoadSite[];
+    injected: InjectedSite[];
+    workers: WorkerSite[];
+}
+/**
+ * The script loads of an artifact's code at `url` (its own URL, for `import.meta.url`). None when it doesn't parse.
+ */
+export declare function scriptLoads(text: string, sourceType: 'script' | 'module', bindings: BindingResolver, url: string): ScriptLoads;
+/** What code does to one script element it creates. */
+interface Element {
+    src: AstNode[];
+    type: AstNode[];
+    integrity: AstNode[];
+    /** Each `noModule` write: the value assigned, or whether `setAttribute` sets it (any value) or `removeAttribute` clears it. */
+    noModule: (AstNode | boolean)[];
+    text: AstNode[];
+    inserts: AstNode[];
+}
+/**
+ * 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 declare function scriptElements(program: AstNode, folder: Folder): Map<AstNode, Element>;
+/**
+ * The code an injected element with no `src` carries, by the call that first inserts it: the expressions its
+ * text is set to.
+ */
+export declare function scriptTexts(program: AstNode, folder: Folder): Map<AstNode, AstNode[]>;
+export {};