monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/analysis/lib/link-group.js

@@ -0,0 +1,487 @@
+// Link groups (§6 Link groups, §19, ADR 0010): an entry artifact plus every artifact reachable from it through its
+// static and dynamic imports, analyzed as one program with one heap and one realm.
+//
+// The group's members are joined into one program, so that the rest of the resolver sees one AST, as it would for a
+// scope-hoisted single-file build:
+//
+// - The group's text is its members' texts one after another, each starting on a line of its own, and every node's
+//   offsets are shifted into it. `GroupLines` gives each location back in the coordinates of its own artifact.
+// - The entry's code stays at the top level, as it runs. Every other member's code is the body of a function of its
+//   own, which gives it a module scope of its own. A member the entry's static imports reach runs at load, before the
+//   code that imports it: its function is called at the top level, in evaluation order. A member only dynamic imports
+//   reach runs when one of them does (`loadedBy`), never at load (§6, §7 Install context).
+// - An import binding is the variable the module it names exports (`bound`), followed through re-exports, so a read
+//   or call of it is a read or call of that variable. An import whose module isn't in the group is a broken link
+//   (`unlinked`).
+// - A member that doesn't parse fails every module graph that holds it, which gives nothing (Principle 1), and is
+//   recorded (§13 `parse-failure`).
+import { walkTree } from "./ast.js";
+import { registriesOf } from "./chunk-registry.js";
+import { GroupLines, lineStarts } from "./line-starts.js";
+import { parse } from "./parse.js";
+import { boundNames } from "./scope.js";
+/**
+ * The link group of `entry`: its members, pulled in through the module requests `resolveImport` resolves, and joined
+ * into one program. A group of one artifact is that artifact's program, unchanged. Undefined when the entry's own
+ * module graph fails; `failures` then says why.
+ */
+export function linkGroup(entry, { artifact, resolveImport, chunks, initialChunks }) {
+    const byUrl = new Map();
+    const queue = [];
+    const add = (source, sourceType) => {
+        const parsed = parse(source.text, sourceType);
+        const member = 'error' in parsed
+            ? { source, statements: [], error: parsed.error, requests: [] }
+            : { source, program: parsed.program, statements: [...parsed.program['body']], requests: [] };
+        byUrl.set(source.url, member);
+        queue.push(member);
+        return member;
+    };
+    add(entry, entry.sourceType);
+    for (let next = 0; next < queue.length; next++) {
+        const member = queue[next];
+        if (member.program === undefined)
+            continue;
+        member.requests = requestsOf(member.program);
+        for (const request of member.requests) {
+            const url = resolveImport?.(member.source.url, request.specifier);
+            const found = url === undefined ? undefined : (byUrl.get(url)?.source ?? artifact(url));
+            if (found === undefined)
+                continue;
+            // An import always loads a module (HTML § Fetch a single module script).
+            request.target = byUrl.get(found.url) ?? add({ ...found, sourceType: 'module' }, 'module');
+        }
+        // The chunks a loader of the member's code loads (§6 idiom 6): every build-directory artifact that pushes an
+        // id its id table maps into the registry it reads, each with its own source type. A stale copy pushing the same id
+        // joins too, as an alternative (Principle 3).
+        // The page's initial chunks join too.
+        for (const load of registriesOf(member.program).loads) {
+            const pull = (url, kind) => {
+                if (byUrl.has(url))
+                    return;
+                const found = artifact(url);
+                if (found !== undefined)
+                    add(found, found.sourceType).chunk = kind;
+            };
+            for (const url of initialChunks?.(load.registry) ?? [])
+                pull(url, 'initial');
+            if (chunks === undefined)
+                continue;
+            for (const id of load.ids === 'any' ? [null] : [...load.ids].sort()) {
+                for (const url of chunks(load.registry, id))
+                    pull(url, 'lazy');
+            }
+        }
+    }
+    const failures = queue.flatMap(({ source, error }) => (error === undefined ? [] : [{ source, error }]));
+    // A module graph fails when a module its static imports reach doesn't parse (Principle 1).
+    const failed = new Map();
+    const fails = (member) => {
+        const known = failed.get(member);
+        if (known !== undefined)
+            return known;
+        failed.set(member, false);
+        const result = member.error !== undefined ||
+            member.requests.some((request) => !request.dynamic && request.target !== undefined && fails(request.target));
+        failed.set(member, result);
+        return result;
+    };
+    const first = queue[0];
+    const pulled = queue.map((member) => member.source);
+    if (fails(first))
+        return { failures, pulled };
+    // The members the entry's static imports reach run at load, each after the modules it imports (ECMA-262
+    // InnerModuleEvaluation), the entry last. The others run only when a dynamic import does.
+    const loaded = [];
+    const visiting = new Set();
+    const visit = (member) => {
+        if (visiting.has(member))
+            return;
+        visiting.add(member);
+        for (const request of member.requests) {
+            if (!request.dynamic && request.target !== undefined)
+                visit(request.target);
+        }
+        loaded.push(member);
+    };
+    visit(first);
+    // A page's initial chunks run at load, after its entry, in URL order.
+    for (const member of queue)
+        if (member.chunk === 'initial' && member.error === undefined)
+            visit(member);
+    const isLoaded = new Set(loaded);
+    const included = queue.filter((member) => !fails(member));
+    const order = [...loaded, ...included.filter((member) => !isLoaded.has(member))];
+    // The group's text, and each member's code shifted into it.
+    let text = '';
+    const bases = new Map();
+    for (const member of order) {
+        bases.set(member, text.length);
+        if (text.length > 0)
+            shift(member.program, text.length);
+        text += member.source.text;
+        if (member !== order.at(-1))
+            text += '\n';
+    }
+    const lines = new GroupLines(order.map((member) => {
+        const { url, hash, origin } = member.source;
+        const base = bases.get(member);
+        const starts = lineStarts(member.source.text);
+        return { url, hash, ...(origin === undefined ? {} : { origin }), base, length: member.source.text.length, starts };
+    }));
+    const members = [first, ...order.filter((member) => member !== first)].map((member) => member.source);
+    const unlinked = new Map();
+    for (const member of order) {
+        const count = member.requests.filter((request) => request.target === undefined).length;
+        if (count > 0)
+            unlinked.set(member.source.url, count);
+    }
+    if (order.length === 1) {
+        const { program } = first;
+        return {
+            group: {
+                text,
+                program: program,
+                sourceType: entry.sourceType,
+                lines,
+                members,
+                failures,
+                bound: () => undefined,
+                wrappers: new Map(),
+                loadedBy: new Map(),
+                chunks: new Set(),
+                unlinked,
+                unlinkedBindings: unlinkedBindingsOf(order),
+            },
+            failures,
+            pulled,
+        };
+    }
+    // Each member other than the entry runs in a function of its own; its imports become declarations of that function.
+    const sourceType = entry.sourceType;
+    const declarationOf = new Map();
+    const wrappers = new Map();
+    const wrapperOf = new Map();
+    const body = [];
+    for (const member of order) {
+        if (member === first) {
+            body.push(...member.statements);
+            continue;
+        }
+        const base = bases.get(member);
+        const end = base + member.source.text.length;
+        const span = { start: base, end, range: [base, end] };
+        const statements = member.statements.map((statement) => {
+            if (statement.type !== 'ImportDeclaration')
+                return statement;
+            const specifiers = statement['specifiers'];
+            const at = { start: statement.start, end: statement.end, range: [statement.start, statement.end] };
+            if (specifiers.length === 0)
+                return { type: 'EmptyStatement', ...at };
+            const declaration = {
+                type: 'VariableDeclaration',
+                kind: 'let',
+                declare: false,
+                declarations: specifiers.map((specifier) => ({
+                    type: 'VariableDeclarator',
+                    id: specifier['local'],
+                    init: null,
+                    definite: false,
+                    start: specifier.start,
+                    end: specifier.end,
+                    range: [specifier.start, specifier.end],
+                })),
+                ...at,
+            };
+            declarationOf.set(statement, declaration);
+            return declaration;
+        });
+        // A module's code is strict mode code, wherever it sits.
+        if (sourceType === 'script' && member.source.sourceType === 'module') {
+            const at = { start: base, end: base, range: [base, base] };
+            const literal = { type: 'Literal', value: 'use strict', raw: '"use strict"', ...at };
+            statements.unshift({ type: 'ExpressionStatement', expression: literal, directive: 'use strict', ...at });
+        }
+        const wrapper = {
+            type: 'FunctionExpression',
+            id: null,
+            generator: false,
+            async: false,
+            params: [],
+            body: { type: 'BlockStatement', body: statements, ...span },
+            expression: false,
+            ...span,
+        };
+        wrappers.set(wrapper, member.source);
+        wrapperOf.set(member, wrapper);
+        const expression = isLoaded.has(member)
+            ? { type: 'CallExpression', callee: wrapper, arguments: [], optional: false, ...span }
+            : wrapper;
+        body.push({ type: 'ExpressionStatement', expression, ...span });
+    }
+    const entryProgram = first.program;
+    const program = {
+        ...entryProgram,
+        body,
+        start: 0,
+        end: text.length,
+        range: [0, text.length],
+    };
+    // The `import(…)` calls that run each member only dynamic imports reach: those whose static graph holds it.
+    const loadedBy = new Map();
+    for (const member of included) {
+        for (const request of member.requests) {
+            if (!request.dynamic || request.target === undefined || fails(request.target))
+                continue;
+            for (const runs of staticGraph(request.target)) {
+                if (isLoaded.has(runs))
+                    continue;
+                const wrapper = wrapperOf.get(runs);
+                const calls = loadedBy.get(wrapper);
+                if (calls === undefined)
+                    loadedBy.set(wrapper, [request.node]);
+                else if (!calls.includes(request.node))
+                    calls.push(request.node);
+            }
+        }
+    }
+    // Each import binding, by the declaration the binding-resolution seam gives it: the entry's import declaration, or the
+    // declaration a member's import became.
+    const bindings = new Map();
+    for (const member of included) {
+        for (const statement of member.statements) {
+            if (statement.type !== 'ImportDeclaration')
+                continue;
+            const request = member.requests.find((each) => each.node === statement);
+            const names = new Map();
+            for (const specifier of statement['specifiers']) {
+                const local = specifier['local']['name'];
+                const imported = importedName(specifier);
+                const target = request?.target;
+                const found = target === undefined || imported === undefined || fails(target) ? undefined : exported(target, imported, new Set());
+                names.set(local, found ?? { declaration: statement, name: local });
+            }
+            bindings.set(member === first ? statement : (declarationOf.get(statement) ?? statement), names);
+        }
+    }
+    return {
+        group: {
+            text,
+            program,
+            sourceType,
+            lines,
+            members,
+            failures,
+            bound: (declaration, name) => bindings.get(declaration)?.get(name),
+            wrappers,
+            loadedBy,
+            chunks: new Set(order.filter((member) => member.chunk === 'lazy').map((member) => member.source.url)),
+            unlinked,
+            unlinkedBindings: unlinkedBindingsOf(order),
+        },
+        failures,
+        pulled,
+    };
+    /** The included members a member's static imports reach, itself first. */
+    function staticGraph(start) {
+        const seen = new Set([start]);
+        const list = [start];
+        for (let index = 0; index < list.length; index++) {
+            for (const request of list[index].requests) {
+                const target = request.target;
+                if (request.dynamic || target === undefined || seen.has(target) || fails(target))
+                    continue;
+                seen.add(target);
+                list.push(target);
+            }
+        }
+        return list;
+    }
+    /** The variable a module exports as `name`, followed through re-exports (ECMA-262 ResolveExport). */
+    function exported(module, name, seen) {
+        const key = `${module.source.url} ${name}`;
+        if (seen.has(key))
+            return undefined;
+        seen.add(key);
+        const targetOf = (statement) => {
+            const target = module.requests.find((request) => request.node === statement)?.target;
+            return target === undefined || fails(target) ? undefined : target;
+        };
+        for (const statement of module.statements) {
+            if (statement.type === 'ExportNamedDeclaration') {
+                const declaration = statement['declaration'];
+                if (declaration !== null) {
+                    if (declares(declaration, name))
+                        return { declaration, name };
+                    continue;
+                }
+                for (const specifier of statement['specifiers']) {
+                    if (moduleExportName(specifier['exported']) !== name)
+                        continue;
+                    const local = moduleExportName(specifier['local']);
+                    if (statement['source'] === null)
+                        return local === undefined ? undefined : declared(module, local, seen);
+                    const target = targetOf(statement);
+                    return target === undefined || local === undefined ? undefined : exported(target, local, seen);
+                }
+            }
+            else if (statement.type === 'ExportDefaultDeclaration' && name === 'default') {
+                const declaration = statement['declaration'];
+                if (declaration.type === 'FunctionDeclaration' || declaration.type === 'ClassDeclaration') {
+                    const id = declaration['id'];
+                    return { declaration, name: id === null ? 'default' : id['name'] };
+                }
+                return declaration.type === 'Identifier' ? declared(module, declaration['name'], seen) : undefined;
+            }
+        }
+        // `export *` re-exports every name but `default` (ECMA-262 GetExportedNames).
+        if (name === 'default')
+            return undefined;
+        for (const statement of module.statements) {
+            if (statement.type !== 'ExportAllDeclaration' || statement['exported'] !== null)
+                continue;
+            const target = targetOf(statement);
+            const found = target === undefined ? undefined : exported(target, name, seen);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    }
+    /** The variable a module's top level declares as `name`, or the one its import of that name is. */
+    function declared(module, name, seen) {
+        for (const statement of module.statements) {
+            const declaration = statement.type === 'ExportNamedDeclaration' || statement.type === 'ExportDefaultDeclaration'
+                ? statement['declaration']
+                : statement;
+            if (declaration === null)
+                continue;
+            if (declaration.type === 'ImportDeclaration') {
+                for (const specifier of declaration['specifiers']) {
+                    if (specifier['local']['name'] !== name)
+                        continue;
+                    const target = module.requests.find((request) => request.node === declaration)?.target;
+                    const imported = importedName(specifier);
+                    if (target === undefined || fails(target) || imported === undefined)
+                        return undefined;
+                    return exported(target, imported, seen);
+                }
+            }
+            else if (declares(declaration, name))
+                return { declaration, name };
+        }
+        return undefined;
+    }
+}
+/** Whether a declaration statement declares `name`. */
+function declares(declaration, name) {
+    switch (declaration.type) {
+        case 'FunctionDeclaration':
+        case 'ClassDeclaration':
+            return declaration['id']?.['name'] === name;
+        case 'VariableDeclaration':
+            return declaration['declarations'].some((declarator) => boundNames(declarator['id']).includes(name));
+        default:
+            return false;
+    }
+}
+/** The name an import specifier imports: `default` for a default import, none for a namespace import. */
+function importedName(specifier) {
+    if (specifier.type === 'ImportDefaultSpecifier')
+        return 'default';
+    if (specifier.type !== 'ImportSpecifier')
+        return undefined;
+    return moduleExportName(specifier['imported']);
+}
+/** A ModuleExportName: an identifier, or a string literal. */
+function moduleExportName(node) {
+    if (node.type === 'Identifier')
+        return node['name'];
+    return node.type === 'Literal' && typeof node['value'] === 'string' ? node['value'] : undefined;
+}
+/**
+ * The module requests of a program (§6 Module links): its static imports and re-exports, and its dynamic imports with a
+ * literal specifier, in document order. A static request with a `type` attribute names a module that isn't JavaScript,
+ * which is no link.
+ */
+function requestsOf(program) {
+    const requests = [];
+    for (const statement of program['body']) {
+        if (statement.type !== 'ImportDeclaration' &&
+            statement.type !== 'ExportAllDeclaration' &&
+            !(statement.type === 'ExportNamedDeclaration' && statement['source'] !== null)) {
+            continue;
+        }
+        const attributes = statement['attributes'] ?? [];
+        if (attributes.some((attribute) => moduleExportName(attribute['key']) === 'type'))
+            continue;
+        const specifier = statement['source']['value'];
+        requests.push({ node: statement, specifier, dynamic: false });
+    }
+    walkTree(program, {
+        enter(node) {
+            if (node.type !== 'ImportExpression')
+                return;
+            const specifier = literalString(node['source']);
+            if (specifier !== undefined)
+                requests.push({ node, specifier, dynamic: true });
+        },
+    });
+    return requests.sort((a, b) => a.node.start - b.node.start);
+}
+/** A string literal's value, or a template literal's with no substitutions. */
+function literalString(node) {
+    if (node.type === 'Literal')
+        return typeof node['value'] === 'string' ? node['value'] : undefined;
+    if (node.type !== 'TemplateLiteral' || node['expressions'].length > 0)
+        return undefined;
+    return node['quasis'][0]['value'].cooked ?? undefined;
+}
+/**
+ * The import bindings of each member whose static import names no member of the group, by their import declaration and
+ * name, each with the import declaration.
+ */
+function unlinkedBindingsOf(order) {
+    const found = new Map();
+    for (const member of order) {
+        for (const request of member.requests) {
+            if (request.target !== undefined || request.node.type !== 'ImportDeclaration')
+                continue;
+            const names = new Map();
+            for (const specifier of request.node['specifiers']) {
+                names.set(specifier['local']['name'], request.node);
+            }
+            found.set(request.node, names);
+        }
+    }
+    return found;
+}
+/** Shifts every offset in a parsed tree by `by`: each object's `start`, `end` and `range`, once each. */
+function shift(root, by) {
+    const seen = new Set();
+    const stack = [root];
+    while (stack.length > 0) {
+        const value = stack.pop();
+        if (typeof value !== 'object' || value === null || seen.has(value))
+            continue;
+        seen.add(value);
+        if (Array.isArray(value)) {
+            stack.push(...value);
+            continue;
+        }
+        if (value instanceof RegExp)
+            continue;
+        const node = value;
+        if (typeof node['start'] === 'number')
+            node['start'] = node['start'] + by;
+        if (typeof node['end'] === 'number')
+            node['end'] = node['end'] + by;
+        const range = node['range'];
+        if (Array.isArray(range) && range.length === 2 && typeof range[0] === 'number') {
+            node['range'] = [range[0] + by, range[1] + by];
+            seen.add(node['range']);
+        }
+        for (const key of Object.keys(node))
+            if (key !== 'range')
+                stack.push(node[key]);
+    }
+}

package/dist/packages/analysis/lib/module-links.d.ts

@@ -0,0 +1,117 @@
+import { type AstNode } from './ast.ts';
+import { type Definitions } from './definitions.ts';
+/** The idioms R1 promises to link (§6), as the report names them. */
+export type Idiom = 'chunk-loader' | 'factory-table' | 'getter-export' | 'interop' | 'lazy-thunk' | 'memoized-getter';
+/** Where a value came through a module link: the idiom, the module's id, and the export's name. */
+export interface ModuleLink {
+    idiom: Exclude<Idiom, 'chunk-loader'>;
+    module: string;
+    export?: string;
+}
+/**
+ * A field of a module's exports the definer defines (above): its getter, an expression whose value is the getter
+ * function, or its value. `site` is the definer's call, `object` the exports expression, and `node` the expression
+ * that gives the field.
+ */
+export interface ExportDefine {
+    site: AstNode;
+    object: AstNode;
+    key: string;
+    getter?: AstNode;
+    value?: AstNode;
+    /** The module the define is in, with the export's name, when the define is in a factory. */
+    link?: ModuleLink;
+}
+/**
+ * A broken link: a require call whose id isn't a constant, or names no factory, or an import whose module isn't in the
+ * link group (§6 Degradation), whose `call` is its import declaration.
+ */
+export interface BrokenLink {
+    call: AstNode;
+    why: 'non-constant' | 'missing' | 'import';
+}
+/**
+ * A lazy module thunk's call of its factory: the module object literal it makes (`{ exports: {} }`), and the index of
+ * the factory's parameter that takes that object. An init-only thunk (`__esm`) makes none.
+ */
+export interface FactoryCall {
+    object?: AstNode;
+    module?: number;
+}
+export interface ModuleLinks {
+    /** The idioms the artifact uses. */
+    idioms: ReadonlySet<Idiom>;
+    /**
+     * Whether the artifact links modules through a factory table's idioms, whose exports are all read through calls the
+     * syntax names no function for, and computed heap reads: there the evaluator follows calls and heap reads further.
+     */
+    tables: boolean;
+    /** How many factories the artifact's tables hold. */
+    modules: number;
+    /** The definer's calls' defines, in document order. */
+    defines: readonly ExportDefine[];
+    /** The definer functions, whose own defines the model stands for. */
+    definers: ReadonlySet<AstNode>;
+    /** The require calls that link, each with the module it links. */
+    links: ReadonlyMap<AstNode, ModuleLink>;
+    /**
+     * Each require function's linked modules, each with its first require call in document order, which stands for every
+     * require of it by that require function. Keyed by require first, since two runtimes in one artifact may reuse ids.
+     */
+    firsts: ReadonlyMap<AstNode, ReadonlyMap<string, AstNode>>;
+    /**
+     * Each factory in a table: its module's id, the require function that runs it, and the require's call of the table
+     * (`t[r](…)`, `e[r].call(…)`) that runs it.
+     */
+    factories: ReadonlyMap<AstNode, {
+        module: string;
+        require: AstNode;
+        call: AstNode;
+    }>;
+    /** The broken links. */
+    broken: readonly BrokenLink[];
+    /** The calls through what a broken link returns, each with the broken link. */
+    unlinkedCalls: ReadonlyMap<AstNode, BrokenLink>;
+    /**
+     * The calls that run a module and give its exports, other than a require's: a lazy module thunk's or a memoized
+     * getter's call (`require_x()`, `requireX()`), and an interop wrapper's call over one (`__toESM(require_x())`), each
+     * with the module it links.
+     */
+    moduleCalls: ReadonlyMap<AstNode, ModuleLink>;
+    /**
+     * The interop wrappers' calls that make a namespace object of a CommonJS module (`__toESM(m)`), each with the
+     * expression whose value is the module's exports: the namespace's `default` is that value, and its other keys are
+     * that value's own.
+     */
+    namespaces: ReadonlyMap<AstNode, AstNode>;
+    /**
+     * The lazy module thunks' calls of their factories (`cb(…)`, `r.call(…)` in a thunk), which read only what the thunk
+     * closes over, each with the module object the thunk makes, if any.
+     */
+    factoryCalls: ReadonlyMap<AstNode, FactoryCall>;
+    /** The thunk makers' calls that make a module (`maker(factory)`, `R.cw(factory)`), each with its thunk maker. */
+    makes: ReadonlyMap<AstNode, AstNode>;
+    /**
+     * The factories chunks push into a chunk registry that a loader of the program reads (§6 idiom 6), by the literal of
+     * the table its require reads and module id: the table holds them as well as its own. Several chunks can push the same
+     * id, and each is an alternative (Principle 3).
+     */
+    chunkFactories: ReadonlyMap<AstNode, ReadonlyMap<string, readonly AstNode[]>>;
+    /**
+     * The callbacks chunks push with their factories, each with its push: the loader calls one with its require where the
+     * chunk pushes it (§6 idiom 6), which starts the chunk's entry modules.
+     */
+    pushCallbacks: ReadonlyMap<AstNode, AstNode>;
+    /**
+     * The require calls a pushed callback makes through its require parameter, which start a chunk's entry modules
+     * (`t => t(t.s = 4429)`), each with the require function: each is a resolved call of its module's factory.
+     */
+    starts: ReadonlyMap<AstNode, AstNode>;
+    /** The constant names of the chunk registries the program reads or pushes into, each a known non-native array (§6). */
+    registries: ReadonlySet<string>;
+    /** For the report alone: how many factories the program's own chunk pushes hold, and whether it has a loader. */
+    pushed: number;
+    loader: boolean;
+}
+/** The module-linking idioms of a program (above). */
+export declare function moduleLinks(program: AstNode, definitions: Definitions): ModuleLinks;