@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/compiler/identify.ts

@@ -0,0 +1,155 @@
+/// <reference types="node" />
+import type { Expression, Node, Program } from 'estree';
+import { posix } from 'node:path';
+import { idsName } from '../../interface/registry/ids.js';
+import { children, isFunction } from './estree.js';
+import { moduleScope } from './module-scope.js';
+import { attachKernelPath } from './paths.js';
+import { insertInto, type Insertion, type SourceMap } from './source-map.js';
+
+export type Parse = (code: string) => Program;
+
+/** Code with its top-level symbols identified, and its map back to the code given. */
+export type Identified = { readonly code: string; readonly map: SourceMap };
+
+/** A dependency's path inside the last `node_modules`: its package name and subpath. */
+const dependency = /\/node_modules\/(?!.*\/node_modules\/)(.+)$/;
+
+/** The name a directory's package.json gives: undefined without one, null for one without a name. */
+export type PackageNameOf = (directory: string) => string | null | undefined;
+
+/**
+ * A module's id: the name of the nearest package.json above it that has one and its path in that package, else for a
+ * dependency its package name and subpath, else its path from `root`. Without a query and with forward slashes, so it's
+ * the same on every machine and names no directory outside its package.
+ */
+export const moduleIdOf = (file: string, root: string, packageNameOf: PackageNameOf): string => {
+    const path = (file.split("?")[0] ?? file).replace(/\\/g, "/");
+    for (let directory = posix.dirname(path); ; directory = posix.dirname(directory)) {
+        const name = packageNameOf(directory);
+        if (typeof name === "string") return `${name}/${posix.relative(directory, path)}`;
+        if (posix.dirname(directory) === directory) break;
+    }
+    const found = dependency.exec(path)?.[1];
+    if (found !== undefined) return found;
+    const relative = posix.relative(root.replace(/\\/g, "/"), path);
+    return posix.isAbsolute(relative) ? posix.basename(path) : relative;
+};
+
+/** Whether a binding named `name` is declared in the module's scope: at top level, or as a `var` in any of its blocks. */
+const declaresInModule = (program: Program, name: string): boolean => {
+    if (moduleScope(program).has(name)) return true;
+    const hoists = (node: Node): boolean => {
+        if (isFunction(node)) return false;
+        if (node.type === "VariableDeclaration" && node.kind === "var" && node.declarations.some(declarator => declarator.id.type === "Identifier" && declarator.id.name === name)) return true;
+        return children(node).some(hoists);
+    };
+    return hoists(program);
+};
+
+/** A call of the global `Symbol`. */
+const isSymbolCall = (node: Expression | null | undefined): node is Expression =>
+    node?.type === "CallExpression" && node.callee.type === "Identifier" && node.callee.name === "Symbol";
+
+/** The package's namespaces whose constructors declare systems, rules, finalizers and indexes. */
+export type Namespace = "System" | "Rule" | "Finalizer" | "Index";
+
+const constructors: { readonly [N in Namespace]: ReadonlySet<string> } = {
+    System: new Set(["create", "render"]),
+    Rule: new Set(["create"]),
+    Finalizer: new Set(["create", "changes"]),
+    Index: new Set(["create"]),
+};
+
+const isNamespace = (name: string): name is Namespace => name === "System" || name === "Rule" || name === "Finalizer" || name === "Index";
+
+/** Whether an import specifier, resolved from the module being transformed, is a module of the package exporting `namespace`. */
+export type ResolveNamespace = (source: string, namespace: Namespace) => Promise<boolean>;
+
+/** The module's local names of the package's namespaces, and of the kernel transform's `attachKernel`. */
+const localsOf = async (program: Program, resolve: ResolveNamespace): Promise<{ readonly namespaces: ReadonlyMap<string, Namespace>; readonly attach: ReadonlySet<string> }> => {
+    const namespaces = new Map<string, Namespace>();
+    const attach = new Set<string>();
+    for (const statement of program.body) {
+        if (statement.type !== "ImportDeclaration" || typeof statement.source.value !== "string") continue;
+        for (const specifier of statement.specifiers) {
+            if (specifier.type !== "ImportSpecifier" || specifier.imported.type !== "Identifier") continue;
+            const imported = specifier.imported.name;
+            if (statement.source.value === attachKernelPath && imported === "attachKernel") attach.add(specifier.local.name);
+            else if (isNamespace(imported) && await resolve(statement.source.value, imported)) namespaces.set(specifier.local.name, imported);
+        }
+    }
+    return { namespaces, attach };
+};
+
+/**
+ * The declaration a constructor call of a namespace passes, the call possibly wrapped by the kernel transform as
+ * `attachKernel$(call, description)`; undefined for any other expression.
+ */
+const declarationOf = (node: Node | null | undefined, namespaces: ReadonlyMap<string, Namespace>, attach: ReadonlySet<string>): Expression | undefined => {
+    if (node?.type !== "CallExpression") return undefined;
+    const { callee } = node;
+    if (callee.type === "Identifier" && attach.has(callee.name)) {
+        const [call] = node.arguments;
+        return call === undefined || call.type === "SpreadElement" ? undefined : declarationOf(call, namespaces, new Set());
+    }
+    if (callee.type !== "MemberExpression" || callee.computed || callee.object.type !== "Identifier" || callee.property.type !== "Identifier") return undefined;
+    const namespace = namespaces.get(callee.object.name);
+    if (namespace === undefined || !constructors[namespace].has(callee.property.name)) return undefined;
+    const [declaration] = node.arguments;
+    return declaration === undefined || declaration.type === "SpreadElement" ? undefined : declaration;
+};
+
+const uniqueName = (code: string, base: string): string => {
+    let name = base;
+    for (let n = 1; code.includes(name); n++) name = `${base}${n}`;
+    return name;
+};
+
+/** Whether code may hold a constructor call worth resolving its imports for. */
+const mayDeclare = /\.(create|render|changes)\(/;
+
+/**
+ * Gives each top-level `Symbol(...)` declaration an id, its module's id and its binding (`src/keys.ts#position`, or
+ * `#default` for `export default Symbol(...)`): `const`, `let` and `var`, each of several declarators, and their
+ * exports. The symbol is still the one `Symbol(...)` makes; a function appended to the module records its id in the
+ * global map the registry reads, so the code imports nothing. Symbols made anywhere else, such as in functions, blocks,
+ * TypeScript namespaces, class fields or CommonJS exports, have no id, nor does any symbol where `Symbol` or
+ * `globalThis` isn't the global.
+ *
+ * The same bindings initialized by a constructor call of the package's `System`, `Rule`, `Finalizer` or `Index`, imported under
+ * any local name, give the call's declaration their id, which the constructor takes from the map: a kernel's call as
+ * the kernel transform wrapped it too. Returns null when nothing is identified.
+ */
+export const identify = async (code: string, id: string, parse: Parse, resolve: ResolveNamespace): Promise<Identified | null> => {
+    const symbols = code.includes("Symbol(");
+    const items = mayDeclare.test(code);
+    if (!symbols && !items) return null;
+    const program = parse(code);
+    const { namespaces, attach } = items ? await localsOf(program, resolve) : { namespaces: new Map<string, Namespace>(), attach: new Set<string>() };
+    const found: { readonly value: Expression; readonly binding: string }[] = [];
+    const consider = (init: Expression | null | undefined, binding: string): void => {
+        if (isSymbolCall(init)) found.push({ value: init, binding });
+        else if (namespaces.size > 0) {
+            const declaration = declarationOf(init, namespaces, attach);
+            if (declaration !== undefined) found.push({ value: declaration, binding });
+        }
+    };
+    for (const statement of program.body) {
+        const declaration = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+        if (declaration?.type === "VariableDeclaration") {
+            for (const declarator of declaration.declarations) if (declarator.id.type === "Identifier") consider(declarator.init, declarator.id.name);
+        } else if (statement.type === "ExportDefaultDeclaration" && statement.declaration.type === "CallExpression") {
+            consider(statement.declaration, "default");
+        }
+    }
+    if (found.length === 0 || declaresInModule(program, "Symbol") || declaresInModule(program, "globalThis")) return null;
+    const identifier = uniqueName(code, "identify$");
+    const insertions: Insertion[] = [];
+    for (const { value, binding } of found) {
+        insertions.push({ at: value.start, text: `${identifier}(` }, { at: value.end, text: `, ${JSON.stringify(`${id}#${binding}`)})` });
+    }
+    const ids = JSON.stringify(idsName);
+    insertions.push({ at: code.length, text: `\nfunction ${identifier}(value, id) { const ids = Symbol.for(${ids}); (globalThis[ids] || (globalThis[ids] = new Map())).set(value, id); return value; }\n` });
+    return insertInto(code, insertions, id);
+};

package/src/implementation/compiler/index.ts

@@ -0,0 +1 @@
+export * from './plugin.js';

package/src/implementation/compiler/ir.ts

@@ -0,0 +1,101 @@
+import type { BinaryOperator } from 'estree';
+import type { Path, Program } from '../world/kernel.js';
+import type { Out } from './out.js';
+
+export type Binary = Exclude<BinaryOperator, "in" | "instanceof">;
+export type Unary = "-" | "+" | "!" | "~";
+
+const unaryOperators: ReadonlySet<string> = new Set(["-", "+", "!", "~"]);
+const binaryOperators: ReadonlySet<string> = new Set([
+    "+", "-", "*", "/", "%", "**", "<", ">", "<=", ">=", "==", "!=", "===", "!==", "&", "|", "^", "<<", ">>", ">>>",
+]);
+
+export const isUnary = (operator: string): operator is Unary => unaryOperators.has(operator);
+export const isBinary = (operator: string): operator is Binary => binaryOperators.has(operator);
+
+/**
+ * The lowered kernel body: the `Program` subset plus JS-only nodes (lookups, commands, nullish values, runtime
+ * indexing, JS values). JS is printed from it; a `Program` is derived from it when it has no JS-only nodes.
+ * Locals and labels are unit-unique numbers.
+ */
+export type Expression =
+    | { readonly kind: "number"; readonly value: number }
+    | { readonly kind: "boolean"; readonly value: boolean }
+    | { readonly kind: "column"; readonly column: number }
+    /** A column of the row's parent, at the parent's row: `Unit.upColumns`. */
+    | { readonly kind: "upColumn"; readonly column: number }
+    | { readonly kind: "resource"; readonly index: number; readonly path: Path }
+    | { readonly kind: "args"; readonly path: Path }
+    | { readonly kind: "local"; readonly local: number }
+    | { readonly kind: "unary"; readonly operator: Unary; readonly operand: Expression }
+    | { readonly kind: "binary"; readonly operator: Binary; readonly left: Expression; readonly right: Expression }
+    | { readonly kind: "logical"; readonly operator: "&&" | "||" | "??"; readonly left: Expression; readonly right: Expression }
+    | { readonly kind: "conditional"; readonly test: Expression; readonly consequent: Expression; readonly alternate: Expression }
+    | { readonly kind: "math"; readonly name: string; readonly arguments: readonly Expression[] }
+    /** Reads inside convert boolean columns to booleans: a position where `true` and `1` differ. */
+    | { readonly kind: "observe"; readonly value: Expression }
+    | { readonly kind: "lane"; readonly intrinsic: number; readonly lane: number; readonly value: Expression }
+    /** A lookup through an index's list, in the local `list` holds, and its rows, in the locals `row` holds: as in `Program`. */
+    | { readonly kind: "listLength"; readonly list: number; readonly lookup: number }
+    | { readonly kind: "listChanged"; readonly list: number; readonly lookup: number }
+    | { readonly kind: "rowLeaf"; readonly row: number; readonly lookup: number; readonly leaf: number }
+    | { readonly kind: "rowEntity"; readonly row: number; readonly lookup: number }
+    /** Whether the row in `row` was found: `true` or `null` in JS, so it tests as a lookup's result does. */
+    | { readonly kind: "rowFound"; readonly row: number; readonly lookup: number }
+    // JS only:
+    | { readonly kind: "nullish"; readonly value: "null" | "undefined" }
+    | { readonly kind: "string"; readonly value: string }
+    | { readonly kind: "element"; readonly object: Expression; readonly index: Expression; readonly optional: boolean }
+    | { readonly kind: "array"; readonly items: readonly Expression[] }
+    | { readonly kind: "record"; readonly fields: readonly (readonly [string, Expression])[] };
+
+export type Statement =
+    | { readonly kind: "set"; readonly local: number; readonly value: Expression; readonly declare: "const" | "let" | undefined }
+    /** Declares `let` locals that every path assigns before reading. */
+    | { readonly kind: "declare"; readonly locals: readonly number[] }
+    | { readonly kind: "store"; readonly column: number; readonly value: Expression }
+    /** Stamps a changed column at the row and its chunk column at the row's chunk. */
+    | { readonly kind: "stamp"; readonly column: number; readonly chunks: number }
+    | { readonly kind: "if"; readonly test: Expression; readonly consequent: Out; readonly alternate: Out }
+    | { readonly kind: "block"; readonly label: number; readonly body: Out }
+    | { readonly kind: "loop"; readonly label: number; readonly body: Out }
+    | { readonly kind: "branch"; readonly label: number }
+    | { readonly kind: "branchIf"; readonly label: number; readonly test: Expression }
+    | { readonly kind: "next" }
+    /** An intrinsic region, as in `Program`; only GPU kernels have them. */
+    | { readonly kind: "intrinsic"; readonly id: number; readonly name: string; readonly intrinsic: Program.Intrinsic; readonly operands: readonly (readonly Expression[])[]; readonly body: Out }
+    /** A lookup through an index, as in `Program`, by `probe`, into the locals `list` and `first` hold. */
+    | { readonly kind: "probe"; readonly list: number; readonly first: number; readonly lookup: number; readonly probe: number; readonly values: readonly Expression[] }
+    | { readonly kind: "listRow"; readonly row: number; readonly list: number; readonly lookup: number; readonly index: Expression }
+    // JS only:
+    | { readonly kind: "lookup"; readonly local: number; readonly lookup: number; readonly entity: Expression }
+    /**
+     * `KernelCommands`: `spawn` stages a spawn through spawner `list`, an index into `Unit.spawns`, with one value per
+     * component of the list, into `local`; `begin` starts a despawn (1), add (2) or remove (3).
+     */
+    | { readonly kind: "spawn"; readonly local: number; readonly list: number; readonly values: readonly Expression[] }
+    | { readonly kind: "begin"; readonly command: 1 | 2 | 3; readonly entity: Expression }
+    /** A component (index into `keys`) and its value for the current spawn or add. */
+    | { readonly kind: "value"; readonly key: number; readonly value: Expression }
+    /** A component (index into `keys`) for the current remove. */
+    | { readonly kind: "component"; readonly key: number };
+
+export const number = (value: number): Expression => ({ kind: "number", value });
+export const local = (index: number): Expression => ({ kind: "local", local: index });
+export const not = (operand: Expression): Expression => ({ kind: "unary", operator: "!", operand });
+
+/** Whether `expression` reads anything `matches`. */
+export const references = (expression: Expression, matches: (node: Expression) => boolean): boolean => {
+    if (matches(expression)) return true;
+    switch (expression.kind) {
+        case "unary": return references(expression.operand, matches);
+        case "binary": case "logical": return references(expression.left, matches) || references(expression.right, matches);
+        case "conditional": return [expression.test, expression.consequent, expression.alternate].some(item => references(item, matches));
+        case "math": return expression.arguments.some(item => references(item, matches));
+        case "observe": case "lane": return references(expression.value, matches);
+        case "element": return references(expression.object, matches) || references(expression.index, matches);
+        case "array": return expression.items.some(item => references(item, matches));
+        case "record": return expression.fields.some(([, item]) => references(item, matches));
+        default: return false;
+    }
+};

package/src/implementation/compiler/kernel-id.ts

@@ -0,0 +1,33 @@
+/// <reference types="node" />
+import { createHash } from 'node:crypto';
+
+const servePrefix = "/@ecs-kernel/";
+const buildPrefix = "\0ecs-kernel:";
+
+/** `hash` is set for serve urls: the version of the kernel the description was compiled against. */
+export type KernelId = { readonly parent: string; readonly index: number; readonly hash: string | undefined };
+
+const encode = (parent: string, index: number): string => `${Buffer.from(parent).toString("base64url")}/${index}.js`;
+
+/** A short hash of a kernel's identity (its description and module source). */
+export const kernelHash = (identity: string): string => createHash("sha256").update(identity).digest("base64url").slice(0, 10);
+
+/**
+ * The root-absolute url of a kernel module on the dev server, which a page and its module workers import from it. The
+ * hash makes an edited kernel a new module, and lets `load` reject a stale url.
+ */
+export const serveUrl = (parent: string, index: number, hash: string): string => `${servePrefix}${encode(parent, index)}?h=${hash}`;
+
+/** The virtual id of a kernel module emitted as a chunk in a build. */
+export const buildId = (parent: string, index: number): string => `${buildPrefix}${encode(parent, index)}`;
+
+/** Parses a serve url or build id. */
+export const parseKernelId = (id: string): KernelId | undefined => {
+    const prefix = id.startsWith(servePrefix) ? servePrefix : id.startsWith(buildPrefix) ? buildPrefix : undefined;
+    if (prefix === undefined) return undefined;
+    const [path = "", query = ""] = id.slice(prefix.length).split("?");
+    const match = /^([\w-]+)\/(\d+)\.js$/.exec(path);
+    if (match === null) return undefined;
+    const hash = new URLSearchParams(query).get("h") ?? undefined;
+    return { parent: Buffer.from(match[1] ?? "", "base64url").toString(), index: Number(match[2]), hash };
+};

package/src/implementation/compiler/key.ts

@@ -0,0 +1,32 @@
+import type { AssignmentProperty, MemberExpression, Node, Property } from 'estree';
+import { fail } from './failure.js';
+import type { Out } from './out.js';
+import { findLocal, type Scope } from './scope.js';
+import type { Value } from './value.js';
+
+/**
+ * An index into a value: a static name or element, a binding of the kernel's own module (a component, resource or
+ * command key), or a runtime value. Other values that are number or string literals, such as constants of other
+ * modules and locals, fold to static indices.
+ */
+export type Key =
+    | { readonly kind: "static"; readonly name: number | string }
+    | { readonly kind: "binding"; readonly name: string }
+    | { readonly kind: "value"; readonly value: Value };
+
+const keyOf = (node: Node, computed: boolean, scope: Scope, out: Out): Key => {
+    if (!computed && node.type === "Identifier") return { kind: "static", name: node.name };
+    if (node.type === "Literal" && (typeof node.value === "number" || typeof node.value === "string")) return { kind: "static", name: node.value };
+    if (node.type === "Identifier" && findLocal(scope, node.name) === undefined && scope.module === scope.unit.module && scope.module.bindings.has(node.name)) {
+        return { kind: "binding", name: node.name };
+    }
+    if (node.type === "PrivateIdentifier") return fail(node, "private names are not in the kernel subset");
+    const value = scope.unit.expression(node, scope, out);
+    const expression = value.kind === "scalar" ? value.expression : undefined;
+    if (expression?.kind === "number" || expression?.kind === "string") return { kind: "static", name: expression.value };
+    return { kind: "value", value };
+};
+
+export const memberKey = (node: MemberExpression, scope: Scope, out: Out): Key => keyOf(node.property, node.computed, scope, out);
+
+export const propertyKey = (property: Property | AssignmentProperty, scope: Scope, out: Out): Key => keyOf(property.key, property.computed, scope, out);

package/src/implementation/compiler/link.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from 'vitest';
+import { parseAst } from 'vite';
+import { createLinker, isPending, resolveExport, type Link, type LinkHost } from './link.js';
+import { estreeOf } from './estree.js';
+
+const parse = (code: string) => estreeOf(parseAst(code));
+
+/** Resolves `./name.js` to `/name.js`, and loads from `files`, which tests may change. */
+const host = (files: Map<string, string>, gate: Promise<void> = Promise.resolve()): LinkHost => ({
+    resolve: async specifier => `/${specifier.replace(/^\.\//, "")}`,
+    load: async file => {
+        const code = files.get(file);
+        await gate;
+        return code === undefined ? { error: `${file} can't be read` } : { code };
+    },
+});
+
+/** Resolves an export, loading what it needs. */
+const resolved = async (link: Link, file: string, name: string) => {
+    for (;;) {
+        try {
+            return resolveExport(link, file, name);
+        } catch (error) {
+            if (!isPending(error)) throw error;
+            await error.pending;
+        }
+    }
+};
+
+describe("linker", () => {
+    test("reports why an export * target failed when nothing else exports the name", async () => {
+        const files = new Map([["/barrel.js", "export * from './missing.js';"]]);
+        expect(await resolved(createLinker(host(files), parse), "/barrel.js", "f")).toEqual({ kind: "error", error: "/missing.js can't be read" });
+    });
+
+    test("an ambiguous export * deeper down is ambiguous", async () => {
+        const files = new Map([
+            ["/top.js", "export * from './both.js';\nexport * from './c.js';"],
+            ["/c.js", "export const f = 3;"],
+            ["/both.js", "export * from './a.js';\nexport * from './b.js';"],
+            ["/a.js", "export const f = 1;"],
+            ["/b.js", "export const f = 2;"],
+        ]);
+        expect(await resolved(createLinker(host(files), parse), "/top.js", "f")).toMatchObject({ kind: "error", error: "f is exported by more than one export * of /both.js" });
+    });
+
+    test("a default class export is a class, not a missing export", async () => {
+        const files = new Map([["/shape.js", "export default class Shape {}"]]);
+        const result = await resolved(createLinker(host(files), parse), "/shape.js", "default");
+        expect(result.kind === "binding" ? result.binding.kind : result.kind).toBe("other");
+    });
+
+    test("a file changed while loading is loaded again", async () => {
+        const files = new Map([["/value.js", "export const v = 1;"]]);
+        let open = (): void => {};
+        const gate = new Promise<void>(resolve => { open = resolve; });
+        const linker = createLinker(host(files, gate), parse);
+        let first: unknown;
+        try {
+            linker.module("/value.js");
+        } catch (error) {
+            first = error;
+        }
+        files.set("/value.js", "export const w = 2;");
+        linker.forget("/value.js", false);
+        open();
+        if (isPending(first)) await first.pending;
+        expect(await resolved(linker, "/value.js", "w")).toMatchObject({ kind: "binding", name: "w" });
+    });
+});

package/src/implementation/compiler/link.ts

@@ -0,0 +1,202 @@
+import type { Program } from 'estree';
+import { createModule, locateIn, type Module, type ModuleBinding } from './module-scope.js';
+
+/**
+ * Why a specifier names no file the linker can read. `unreadable` marks one the build leaves unread, such as a package
+ * external to it, rather than one that fails to resolve.
+ */
+export type Unresolved = { readonly error: string; readonly unreadable?: boolean };
+
+/** How the linker reaches other modules. Errors are reasons, reported only if a kernel uses what failed. */
+export type LinkHost = {
+    /** The file an import specifier names from `importer`. */
+    readonly resolve: (specifier: string, importer: string) => Promise<string | Unresolved>;
+    /** A file's code as JavaScript, and how offsets in it map to source lines when it was compiled from another language. */
+    readonly load: (file: string) => Promise<{ readonly code: string; readonly locate?: Module["locate"] } | { readonly error: string }>;
+};
+
+/**
+ * Modules as the compiler sees them. Both answer from what the linker has loaded, and when it hasn't loaded something
+ * yet they throw a `Pending`, which `transformKernels` awaits before compiling the kernel again.
+ */
+export type Link = {
+    readonly module: (file: string) => Module | { readonly error: string };
+    readonly resolve: (specifier: string, importer: string) => string | Unresolved;
+};
+
+/** A cache of modules and resolutions shared across transforms. */
+export type Linker = Link & {
+    /** Adds the module being transformed, so imports back into it resolve to the same module. */
+    readonly add: (module: Module) => void;
+    /** Drops a changed file, and with `resolutions` every resolution, for files that were created or deleted. */
+    readonly forget: (file: string, resolutions: boolean) => void;
+};
+
+type Pending = { readonly pending: Promise<void> };
+
+const reason = (error: unknown): string => error instanceof Error ? error.message : String(error);
+
+const pending = (promise: Promise<void>): never => {
+    const signal: Pending = { pending: promise };
+    throw signal;
+};
+
+export const isPending = (error: unknown): error is Pending =>
+    typeof error === "object" && error !== null && "pending" in error && error.pending instanceof Promise;
+
+type Loaded = Module | { readonly error: string };
+type Resolution = string | Unresolved;
+
+export const createLinker = (host: LinkHost, parse: (code: string) => Program): Linker => {
+    const modules = new Map<string, Loaded>();
+    const loading = new Map<string, Promise<void>>();
+    const resolutions = new Map<string, Resolution>();
+    const resolving = new Map<string, Promise<void>>();
+    /** Bumped when a file changes, or every resolution is dropped, so loads and resolutions in flight are discarded. */
+    const versions = new Map<string, number>();
+    let resolutionVersion = 0;
+    /** Starts resolving `specifier` and loading its file, unless either is known or in flight. */
+    const prefetch = (specifier: string, importer: string): Promise<void> => {
+        const key = `${importer}\0${specifier}`;
+        const resolved = resolutions.get(key);
+        if (resolved !== undefined) return typeof resolved === "string" ? startLoad(resolved) : Promise.resolve();
+        let promise = resolving.get(key);
+        if (promise === undefined) {
+            const version = resolutionVersion;
+            promise = host.resolve(specifier, importer)
+                .catch((error: unknown) => ({ error: `${specifier} can't be resolved from ${importer}: ${reason(error)}` }))
+                .then(result => {
+                    if (version !== resolutionVersion) return;
+                    resolutions.set(key, result);
+                    if (typeof result === "string") void startLoad(result);
+                })
+                .finally(() => resolving.delete(key));
+            resolving.set(key, promise);
+        }
+        return promise;
+    };
+    const startLoad = (file: string): Promise<void> => {
+        if (modules.has(file)) return Promise.resolve();
+        let promise = loading.get(file);
+        if (promise === undefined) {
+            promise = load(file).finally(() => loading.delete(file));
+            loading.set(file, promise);
+        }
+        return promise;
+    };
+    /**
+     * Loads a module, then starts on the modules it re-exports: compiling stops at each module it doesn't have yet,
+     * and a namespace's members are usually found through re-exports.
+     */
+    const load = async (file: string): Promise<void> => {
+        const version = versions.get(file) ?? 0;
+        const loaded = await host.load(file).catch((error: unknown) => ({ error: `${file} can't be read: ${reason(error)}` }));
+        if (version !== (versions.get(file) ?? 0)) return;
+        if ("error" in loaded) {
+            modules.set(file, loaded);
+            return;
+        }
+        let module: Module;
+        try {
+            module = createModule(file, parse(loaded.code), loaded.locate ?? locateIn(loaded.code));
+        } catch (error) {
+            modules.set(file, { error: `${file} can't be parsed: ${reason(error)}` });
+            return;
+        }
+        modules.set(file, module);
+        for (const exported of module.exports.values()) if (exported.kind !== "local") void prefetch(exported.specifier, file);
+        for (const star of module.stars) void prefetch(star, file);
+    };
+    return {
+        module: file => modules.get(file) ?? pending(startLoad(file)),
+        resolve: (specifier, importer) => resolutions.get(`${importer}\0${specifier}`) ?? pending(prefetch(specifier, importer)),
+        add: module => { modules.set(module.file, module); },
+        forget: (file, all) => {
+            modules.delete(file);
+            loading.delete(file);
+            versions.set(file, (versions.get(file) ?? 0) + 1);
+            if (all) {
+                resolutions.clear();
+                resolving.clear();
+                resolutionVersion++;
+            }
+        },
+    };
+};
+
+/** A name as the linker resolves it: a definition in its module, a module namespace, or why it isn't one. */
+export type Resolved =
+    | { readonly kind: "binding"; readonly module: Module; readonly name: string; readonly binding: Exclude<ModuleBinding, { kind: "import" | "importNamespace" }> }
+    | { readonly kind: "namespace"; readonly file: string }
+    /**
+     * `cause` tells a name a module doesn't export, one several `export *` provide, and one in a module the build leaves
+     * unread, from failing to tell.
+     */
+    | { readonly kind: "error"; readonly error: string; readonly cause?: "missing" | "ambiguous" | "unreadable" };
+
+/** A resolution that names no file, as a `Resolved`. */
+const unresolved = ({ error, unreadable }: Unresolved): Resolved => unreadable === true ? { kind: "error", error, cause: "unreadable" } : { kind: "error", error };
+
+const sameResolution = (a: Resolved, b: Resolved): boolean =>
+    a.kind === "binding" && b.kind === "binding" ? a.module === b.module && a.name === b.name
+        : a.kind === "namespace" && b.kind === "namespace" && a.file === b.file;
+
+/** Follows a binding of `module` through imports to its definition. */
+export const resolveBinding = (link: Link, module: Module, name: string, binding: ModuleBinding, seen: Set<string> = new Set()): Resolved => {
+    switch (binding.kind) {
+        case "import": case "importNamespace": {
+            const file = link.resolve(binding.specifier, module.file);
+            if (typeof file !== "string") return unresolved(file);
+            return binding.kind === "importNamespace" ? { kind: "namespace", file } : resolveExport(link, file, binding.imported, seen);
+        }
+        default:
+            return { kind: "binding", module, name, binding };
+    }
+};
+
+/** What `file` exports as `name`, following re-exports and `export *`. */
+export const resolveExport = (link: Link, file: string, name: string, seen: Set<string> = new Set()): Resolved => {
+    const module = link.module(file);
+    if ("error" in module) return { kind: "error", error: module.error };
+    const missing: Resolved = { kind: "error", error: `${name} isn't exported by ${file}`, cause: "missing" };
+    const key = `${file}\0${name}`;
+    if (seen.has(key)) return missing;
+    seen.add(key);
+    const exported = module.exports.get(name);
+    if (exported !== undefined) {
+        switch (exported.kind) {
+            case "local": {
+                const binding = module.bindings.get(exported.local);
+                return binding === undefined ? missing : resolveBinding(link, module, exported.local, binding, seen);
+            }
+            case "reexport": case "namespace": {
+                const target = link.resolve(exported.specifier, file);
+                if (typeof target !== "string") return unresolved(target);
+                return exported.kind === "namespace" ? { kind: "namespace", file: target } : resolveExport(link, target, exported.imported, seen);
+            }
+        }
+    }
+    if (name === "default") return missing;
+    // Every star is searched, to find ambiguity; what isn't loaded yet is waited for together. A star that is
+    // ambiguous itself makes the name ambiguous, and one that fails is the reason when no other star exports it.
+    const found: Resolved[] = [];
+    const failures: Resolved[] = [];
+    const waiting: Promise<void>[] = [];
+    for (const star of module.stars) {
+        try {
+            const target = link.resolve(star, file);
+            const result: Resolved = typeof target === "string" ? resolveExport(link, target, name, new Set(seen)) : unresolved(target);
+            if (result.kind !== "error") {
+                if (!found.some(item => sameResolution(item, result))) found.push(result);
+            }
+            else if (result.cause === "ambiguous") return result;
+            else if (result.cause !== "missing") failures.push(result);
+        } catch (error) {
+            if (!isPending(error)) throw error;
+            waiting.push(error.pending);
+        }
+    }
+    if (waiting.length > 0) pending(Promise.all(waiting).then(() => undefined));
+    if (found.length > 1) return { kind: "error", error: `${name} is exported by more than one export * of ${file}`, cause: "ambiguous" };
+    return found[0] ?? failures[0] ?? missing;
+};