@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/compiler/lists.ts

@@ -0,0 +1,202 @@
+import type { ArrayExpression, Expression, Node } from 'estree';
+import { children } from './estree.js';
+import { resolveBinding, resolveExport, type Link, type Resolved } from './link.js';
+import type { Module, ModuleBinding } from './module-scope.js';
+
+/** The keys a list names, each as an expression of the kernel's module; or why the node isn't a list the compiler can read. */
+export type ListNames = readonly string[] | { readonly error: string };
+
+/** How a kernel's module reads its lists of keys, wherever they are declared. */
+export type Lists = {
+    /**
+     * The keys a list names: an array literal of the kernel's module-scope identifiers, or a constant, of the kernel's
+     * module or imported through any re-exports and namespaces, holding an array literal or `Archetype.create` of one.
+     * A key of another module's list is named by the kernel's binding of the same definition, or else by the list
+     * itself, as `List[k]`.
+     */
+    readonly names: (node: Node) => ListNames;
+    /**
+     * What a command's component argument names: a list, or one key by the expression the kernel's module names it with.
+     * A name is one key when its definition is a call of the global `Symbol`, identified or not, or a literal, which
+     * registration rejects for not being a symbol. A name defined in a module the build can't read, such as a package
+     * external to it, is taken as a key, and registration rejects a list there. Anything else fails with the reason.
+     */
+    readonly component: (node: Node) => Named;
+};
+
+/** What a command's component argument names, or why the compiler can't tell. */
+export type Named = { readonly kind: "list" } | { readonly kind: "key"; readonly name: string } | { readonly kind: "error"; readonly error: string };
+
+/** A list's array literal, the module it's written in, and how the kernel's module refers to it. */
+type Found = { readonly literal: ArrayExpression; readonly module: Module; readonly reference: string };
+
+/** What a name is defined as: a list, a key by its definition's identity (null where the build can't read it), or why it's neither. */
+type Followed = Found | { readonly key: string | null } | { readonly error: string };
+
+/** Whether a name may be one key as well as a list, which words the reasons it's neither. */
+type Wanted = "list" | "either";
+
+/** A call of the global `Symbol` in `module`. */
+const isSymbolCall = (node: Expression, module: Module): boolean =>
+    node.type === "CallExpression" && node.callee.type === "Identifier" && node.callee.name === "Symbol" && !module.bindings.has("Symbol");
+
+/** A key's definition: `Symbol(...)`, as the plugin identifies it, `identify$(Symbol(...), id)`, or a literal. */
+const isKey = (node: Expression, module: Module): boolean => {
+    if (node.type === "Literal") return !("regex" in node);
+    if (isSymbolCall(node, module)) return true;
+    if (node.type !== "CallExpression" || node.callee.type !== "Identifier" || !/^identify\$\d*$/.test(node.callee.name)) return false;
+    const [symbol] = node.arguments;
+    return module.bindings.get(node.callee.name)?.kind === "function" && symbol !== undefined && symbol.type !== "SpreadElement" && isSymbolCall(symbol, module);
+};
+
+/** `Archetype.create(<array literal>)`, with `Archetype` imported under any name: its array literal, else null. */
+const createdList = (node: Expression, module: Module): ArrayExpression | null => {
+    if (node.type !== "CallExpression" || node.arguments.length !== 1) return null;
+    const { callee } = node;
+    if (callee.type !== "MemberExpression" || callee.computed || callee.object.type !== "Identifier" || callee.property.type !== "Identifier" || callee.property.name !== "create") return null;
+    const binding = module.bindings.get(callee.object.name);
+    const [list] = node.arguments;
+    return binding?.kind === "import" && binding.imported === "Archetype" && list.type === "ArrayExpression" ? list : null;
+};
+
+const fileOf = (module: Module, kernel: Module): string => module === kernel ? "this module" : module.file;
+
+/** Follows a binding to the array literal or key its constant holds, through imports and constants naming another. */
+const follow = (name: string, binding: ModuleBinding, module: Module, kernel: Module, link: Link | null, reference: string, wanted: Wanted, seen: Set<string>): Followed => {
+    const identity = `${module.file}\0${name}`;
+    if (seen.has(identity)) return { error: `${reference} refers to itself` };
+    seen.add(identity);
+    const unread = wanted === "list" ? "the compiler can't read its components" : "the compiler can't tell whether it's a key or a list";
+    switch (binding.kind) {
+        case "const": {
+            const { init } = binding;
+            if (init.type === "ArrayExpression") return { literal: init, module, reference };
+            const created = createdList(init, module);
+            if (created !== null) return { literal: created, module, reference };
+            if (init.type === "Identifier") {
+                const aliased = module.bindings.get(init.name);
+                if (aliased !== undefined) return follow(init.name, aliased, module, kernel, link, reference, wanted, seen);
+            }
+            if (isKey(init, module)) return { key: identity };
+            const declare = wanted === "list" ? "declare it as an array literal, or Archetype.create of one" : "declare a key as Symbol(...), or a list as an array literal or Archetype.create of one";
+            return { error: `${reference} is computed when ${fileOf(module, kernel)} runs, so ${unread}; ${declare}` };
+        }
+        case "import": case "importNamespace":
+            // Without a linker nothing imported can be read, so a name that may be one key is taken as one.
+            if (link === null) return wanted === "list" ? { error: `${reference} is imported, and this build doesn't link imports` } : { key: null };
+            return followResolved(resolveBinding(link, module, name, binding), kernel, link, reference, wanted, seen);
+        case "function": case "other":
+            return { error: `${reference} isn't a module-scope const, so ${unread}` };
+    }
+};
+
+const followResolved = (resolved: Resolved, kernel: Module, link: Link | null, reference: string, wanted: Wanted, seen: Set<string>): Followed => {
+    switch (resolved.kind) {
+        case "error": return wanted === "either" && resolved.cause === "unreadable" ? { key: null } : { error: resolved.error };
+        case "namespace": return { error: `${reference} is a module namespace, not ${wanted === "list" ? "a list of components" : "a key or a list of components"}` };
+        case "binding": return follow(resolved.name, resolved.binding, resolved.module, kernel, link, reference, wanted, seen);
+    }
+};
+
+/** The names of a member chain of identifiers, `A.B.C`, outermost first; null for any other node. */
+const chain = (node: Node): readonly string[] | null => {
+    if (node.type === "Identifier") return [node.name];
+    if (node.type !== "MemberExpression" || node.computed || node.property.type !== "Identifier") return null;
+    const object = chain(node.object);
+    return object === null ? null : [...object, node.property.name];
+};
+
+/** What a node names: an array literal, or the definition an identifier or a namespace member chain names. */
+const find = (node: Node, kernel: Module, link: Link | null, wanted: Wanted): Followed => {
+    if (node.type === "ArrayExpression") return { literal: node, module: kernel, reference: "" };
+    const names = chain(node);
+    if (names === null) return { error: "commands and kernel declarations name a list as an array literal, or a constant holding one or Archetype.create of one" };
+    const [first, ...members] = names;
+    const reference = names.join(".");
+    const binding = kernel.bindings.get(first);
+    if (binding === undefined) return { error: `${first} isn't bound at module scope` };
+    if (members.length === 0) return follow(first, binding, kernel, kernel, link, reference, wanted, new Set());
+    const what = wanted === "list" ? "a list" : "a key or a list";
+    if (binding.kind !== "importNamespace") return { error: `${first} isn't a module namespace, so ${reference} isn't ${what} the compiler can read` };
+    if (link === null) return wanted === "list" ? { error: `${reference} is imported, and this build doesn't link imports` } : { key: null };
+    let resolved = resolveBinding(link, kernel, first, binding);
+    for (const member of members) {
+        if (resolved.kind === "error") return followResolved(resolved, kernel, link, reference, wanted, new Set());
+        if (resolved.kind !== "namespace") return { error: `${reference} isn't ${what} the compiler can read` };
+        resolved = resolveExport(link, resolved.file, member);
+    }
+    return followResolved(resolved, kernel, link, reference, wanted, new Set());
+};
+
+/** The identity of what a binding of `module` defines: its module and name, through imports; null where it can't be followed. */
+const definition = (module: Module, name: string, binding: ModuleBinding, link: Link | null): string | null => {
+    if (binding.kind !== "import" && binding.kind !== "importNamespace") return `${module.file}\0${name}`;
+    if (link === null) return null;
+    const resolved = resolveBinding(link, module, name, binding);
+    return resolved.kind === "binding" ? `${resolved.module.file}\0${resolved.name}` : null;
+};
+
+/**
+ * Lists as `kernel` reads them. `nodes` are the kernel's declaration and body: the kernel's names for keys of other
+ * modules' lists are found among the module-scope identifiers they use, so only those are followed.
+ */
+export const createLists = (kernel: Module, link: Link | null, nodes: readonly Node[]): Lists => {
+    /** Each key definition's name in the kernel's module, filled from the kernel's identifiers when a list of another module is first read. */
+    let named: Map<string, string> | null = null;
+    const nameOf = (identity: string, fallback: string): string => {
+        if (named === null) {
+            const found = new Map<string, string>();
+            const followed = new Set<string>();
+            const visit = (node: Node): void => {
+                if (node.type === "Identifier" && !followed.has(node.name)) {
+                    followed.add(node.name);
+                    const binding = kernel.bindings.get(node.name);
+                    const defined = binding === undefined ? null : definition(kernel, node.name, binding, link);
+                    if (defined !== null && !found.has(defined)) found.set(defined, node.name);
+                }
+                for (const child of children(node)) visit(child);
+            };
+            for (const node of nodes) visit(node);
+            named = found;
+        }
+        const name = named.get(identity);
+        if (name !== undefined) return name;
+        named.set(identity, fallback);
+        return fallback;
+    };
+    const names = (node: Node): ListNames => {
+        const found = find(node, kernel, link, "list");
+        if ("key" in found) {
+            const reference = chain(node)?.join(".") ?? "";
+            return { error: `${reference} is a key, not a list of components; list it as [${reference}]` };
+        }
+        if (!("literal" in found)) return found;
+        const { literal, module, reference } = found;
+        const result: string[] = [];
+        for (let k = 0; k < literal.elements.length; k++) {
+            const element = literal.elements[k];
+            const binding = element?.type === "Identifier" ? module.bindings.get(element.name) : undefined;
+            if (element?.type !== "Identifier" || binding === undefined) {
+                return { error: module === kernel ? "lists name keys by identifiers bound at module scope" : `${reference} names a key by something other than an identifier bound at the scope of ${module.file}` };
+            }
+            if (module === kernel) {
+                result.push(element.name);
+                continue;
+            }
+            const fallback = `${reference}[${k}]`;
+            const identity = definition(module, element.name, binding, link);
+            result.push(identity === null ? fallback : nameOf(identity, fallback));
+        }
+        return result;
+    };
+    const component = (node: Node): Named => {
+        const found = find(node, kernel, link, "either");
+        if ("literal" in found) return { kind: "list" };
+        if ("error" in found) return { kind: "error", error: found.error };
+        const reference = chain(node)?.join(".") ?? "";
+        // A key named by an identifier is that identifier; one named through a namespace is the kernel's own binding of
+        // its definition where it has one.
+        return { kind: "key", name: node.type === "Identifier" || found.key === null ? reference : nameOf(found.key, reference) };
+    };
+    return { names, component };
+};

package/src/implementation/compiler/lookups.ts

@@ -0,0 +1,120 @@
+import type { Expression, Node, ObjectExpression, Pattern, SpreadElement } from 'estree';
+import { children, declaredIn } from './estree.js';
+
+type Range = { readonly start: number; readonly end: number };
+
+/** How a call passes a key part: as in `world/index-lookups.ts`'s `Shape`, `0` whole, `n` a tuple of `n` scalars, or a comparison's operators. */
+type Form = number | readonly (readonly [string, number])[];
+
+/**
+ * A call of an index lookup in a main-thread body: its callee's source, its key's shape, and the source ranges of the
+ * values it passes, literals flattened.
+ */
+export type LookupSite = Range & { readonly callee: Range; readonly shape: readonly Form[]; readonly values: readonly Range[] };
+
+/** Arguments a site passes at most (`world/prepared-lookup.ts`). */
+const maximumArguments = 16;
+
+const operators: ReadonlySet<string> = new Set(["==", "!=", "<", ">", "<=", ">="]);
+
+/** A property's plain name: an identifier or a string literal, not computed. */
+const nameOf = (key: Node, computed: boolean): string | null =>
+    !computed && key.type === "Identifier" ? key.name : key.type === "Literal" && typeof key.value === "string" ? key.value : null;
+
+/** The names of a declaration's lookups that go through an index: those declared as an object literal with `index`. */
+const indexLookupsOf = (declaration: ObjectExpression): ReadonlySet<string> => {
+    const names = new Set<string>();
+    for (const property of declaration.properties) {
+        if (property.type !== "Property" || nameOf(property.key, property.computed) !== "lookup" || property.value.type !== "ObjectExpression") continue;
+        for (const lookup of property.value.properties) {
+            if (lookup.type !== "Property" || lookup.value.type !== "ObjectExpression") continue;
+            const name = nameOf(lookup.key, lookup.computed);
+            const indexed = lookup.value.properties.some(field => field.type === "Property" && nameOf(field.key, field.computed) === "index");
+            if (name !== null && indexed) names.add(name);
+        }
+    }
+    return names;
+};
+
+/** How a body reaches its lookups: the context's name, a name bound to `lookup`, and names bound to lookups themselves. */
+type Reach = { readonly context: string | null; readonly lookup: string | null; readonly direct: ReadonlyMap<string, string> };
+
+const reachOf = (parameter: Pattern | undefined, names: ReadonlySet<string>): Reach | null => {
+    if (parameter?.type === "Identifier") return { context: parameter.name, lookup: null, direct: new Map() };
+    if (parameter?.type !== "ObjectPattern") return null;
+    for (const property of parameter.properties) {
+        if (property.type !== "Property" || nameOf(property.key, property.computed) !== "lookup") continue;
+        if (property.value.type === "Identifier") return { context: null, lookup: property.value.name, direct: new Map() };
+        if (property.value.type !== "ObjectPattern") return null;
+        const direct = new Map<string, string>();
+        for (const inner of property.value.properties) {
+            if (inner.type !== "Property" || inner.value.type !== "Identifier") continue;
+            const name = nameOf(inner.key, inner.computed);
+            if (name !== null && names.has(name)) direct.set(inner.value.name, name);
+        }
+        return { context: null, lookup: null, direct };
+    }
+    return null;
+};
+
+/** The form and values of one argument: a tuple or comparison literal flattened, anything else whole. */
+const formOf = (argument: Expression): { readonly form: Form; readonly values: readonly Range[] } => {
+    if (argument.type === "ArrayExpression" && argument.elements.length > 0 && argument.elements.every(element => element !== null && element.type !== "SpreadElement")) {
+        return { form: argument.elements.length, values: argument.elements.flatMap(element => element === null ? [] : [{ start: element.start, end: element.end }]) };
+    }
+    if (argument.type === "ObjectExpression" && argument.properties.length > 0) {
+        const entries: [string, number][] = [];
+        const values: Range[] = [];
+        for (const property of argument.properties) {
+            if (property.type !== "Property" || property.kind !== "init" || property.method || property.computed) return { form: 0, values: [argument] };
+            const operator = nameOf(property.key, false);
+            if (operator === null || !operators.has(operator) || property.value.type === "AssignmentPattern" || property.value.type === "ObjectPattern"
+                || property.value.type === "ArrayPattern" || property.value.type === "RestElement") return { form: 0, values: [argument] };
+            const operand = formOf(property.value);
+            entries.push([operator, typeof operand.form === "number" ? operand.form : 0]);
+            values.push(...typeof operand.form === "number" ? operand.values : [property.value]);
+        }
+        return { form: entries, values };
+    }
+    return { form: 0, values: [argument] };
+};
+
+/**
+ * The index lookup calls in a main-thread body, whose context is its parameter at `context`: `context.lookup.name(key)`,
+ * `lookup.name(key)` and `name(key)` as the parameter's pattern binds them, for lookups the declaration declares with
+ * `index` in an object literal. A body that redeclares the names it reaches them by is left alone, and so is a call
+ * with a spread argument or more than `maximumArguments` values, or one inside another's arguments.
+ */
+export const lookupSites = (body: Node, declaration: ObjectExpression, context: number): readonly LookupSite[] => {
+    if (body.type !== "ArrowFunctionExpression" && body.type !== "FunctionExpression") return [];
+    const names = indexLookupsOf(declaration);
+    if (names.size === 0) return [];
+    const reach = reachOf(body.params[context], names);
+    if (reach === null) return [];
+    const declared = new Set<string>();
+    declaredIn(body.body, name => declared.add(name));
+    if ((reach.context !== null && declared.has(reach.context)) || (reach.lookup !== null && declared.has(reach.lookup))) return [];
+    /** Whether a callee is one of the declaration's index lookups, as the body reaches it. */
+    const isLookup = (callee: Node): boolean => {
+        if (callee.type === "Identifier") return reach.direct.has(callee.name) && !declared.has(callee.name);
+        if (callee.type !== "MemberExpression" || callee.computed || callee.optional || callee.property.type !== "Identifier" || !names.has(callee.property.name)) return false;
+        const { object } = callee;
+        if (object.type === "Identifier") return reach.lookup !== null && object.name === reach.lookup;
+        return reach.context !== null && object.type === "MemberExpression" && !object.computed && !object.optional && object.object.type === "Identifier"
+            && object.object.name === reach.context && object.property.type === "Identifier" && object.property.name === "lookup";
+    };
+    const sites: LookupSite[] = [];
+    const visit = (node: Node): void => {
+        if (node.type === "CallExpression" && !node.optional && isLookup(node.callee) && node.arguments.every((argument): argument is Expression => argument.type !== "SpreadElement")) {
+            const forms = node.arguments.map((argument: Expression | SpreadElement) => argument.type === "SpreadElement" ? { form: 0, values: [] } : formOf(argument));
+            const values = forms.flatMap(form => form.values);
+            if (values.length <= maximumArguments) {
+                sites.push({ start: node.start, end: node.end, callee: { start: node.callee.start, end: node.callee.end }, shape: forms.map(form => form.form), values });
+                return;
+            }
+        }
+        for (const child of children(node)) visit(child);
+    };
+    visit(body.body);
+    return sites;
+};

package/src/implementation/compiler/math.ts

@@ -0,0 +1,9 @@
+/** The `Math` functions allowed in kernels: pure and deterministic. */
+export const mathFunctions: ReadonlySet<string> = new Set([
+    "abs", "sign", "floor", "ceil", "round", "trunc", "min", "max", "sqrt", "cbrt", "hypot",
+    "exp", "expm1", "log", "log1p", "log2", "log10", "pow",
+    "sin", "cos", "tan", "asin", "acos", "atan", "atan2", "sinh", "cosh", "tanh", "asinh", "acosh", "atanh",
+    "fround", "imul", "clz32",
+]);
+
+export const mathConstants: ReadonlySet<string> = new Set(["PI", "E", "LN2", "LN10", "LOG2E", "LOG10E", "SQRT2", "SQRT1_2"]);

package/src/implementation/compiler/module-scope.ts

@@ -0,0 +1,140 @@
+import type { Directive, Expression, FunctionDeclaration, MaybeNamedFunctionDeclaration, ModuleDeclaration, Pattern, Program, Statement } from 'estree';
+import { patternNames } from './estree.js';
+
+/**
+ * A module-scope binding. Only `const` initializers and function declarations can be inlined into kernels, and imports
+ * of them, which the linker follows (`link.ts`).
+ */
+export type ModuleBinding =
+    | { readonly kind: "const"; readonly init: Expression }
+    | { readonly kind: "function"; readonly node: FunctionDeclaration | MaybeNamedFunctionDeclaration }
+    /** `import { imported as local } from specifier`; a default import imports `default`. */
+    | { readonly kind: "import"; readonly specifier: string; readonly imported: string }
+    | { readonly kind: "importNamespace"; readonly specifier: string }
+    | { readonly kind: "other" };
+
+export type ModuleScope = ReadonlyMap<string, ModuleBinding>;
+
+/** What a module exports under one name. */
+export type Export =
+    | { readonly kind: "local"; readonly local: string }
+    | { readonly kind: "reexport"; readonly specifier: string; readonly imported: string }
+    | { readonly kind: "namespace"; readonly specifier: string };
+
+/** A parsed module: its bindings, its exports, and the modules `export *` re-exports, by specifier. */
+export type Module = {
+    readonly file: string;
+    readonly bindings: ModuleScope;
+    readonly exports: ReadonlyMap<string, Export>;
+    readonly stars: readonly string[];
+    /** The source line and column of an offset in the parsed code, both counted from 1. */
+    readonly locate: (offset: number) => { readonly line: number; readonly column: number };
+};
+
+/** The binding an `export default <expression>` declares. Not a valid identifier, so it can't be shadowed. */
+const defaultBinding = "*default*";
+
+const nameOf = (node: { readonly type: string; readonly name?: string; readonly value?: unknown }): string | undefined =>
+    node.type === "Identifier" ? node.name : typeof node.value === "string" ? node.value : undefined;
+
+const declare = (scope: Map<string, ModuleBinding>, statement: Statement | ModuleDeclaration | Directive): void => {
+    switch (statement.type) {
+        case "ImportDeclaration": {
+            const specifier = statement.source.value;
+            if (typeof specifier !== "string") return;
+            for (const item of statement.specifiers) {
+                if (item.type === "ImportNamespaceSpecifier") scope.set(item.local.name, { kind: "importNamespace", specifier });
+                else scope.set(item.local.name, { kind: "import", specifier, imported: item.type === "ImportDefaultSpecifier" ? "default" : nameOf(item.imported) ?? "" });
+            }
+            return;
+        }
+        case "ExportNamedDeclaration":
+            if (statement.declaration) declare(scope, statement.declaration);
+            return;
+        case "ExportDefaultDeclaration": {
+            const declaration = statement.declaration;
+            if (declaration.type === "FunctionDeclaration") scope.set(declaration.id?.name ?? defaultBinding, { kind: "function", node: declaration });
+            else if (declaration.type === "ClassDeclaration") scope.set(declaration.id?.name ?? defaultBinding, { kind: "other" });
+            else scope.set(defaultBinding, { kind: "const", init: declaration });
+            return;
+        }
+        case "VariableDeclaration":
+            for (const declarator of statement.declarations) {
+                if (statement.kind === "const" && declarator.id.type === "Identifier" && declarator.init) {
+                    scope.set(declarator.id.name, { kind: "const", init: declarator.init });
+                } else {
+                    for (const name of patternNames(declarator.id)) scope.set(name, { kind: "other" });
+                }
+            }
+            return;
+        case "FunctionDeclaration":
+            if (statement.id) scope.set(statement.id.name, { kind: "function", node: statement });
+            return;
+        case "ClassDeclaration":
+            if (statement.id) scope.set(statement.id.name, { kind: "other" });
+            return;
+        default:
+            return;
+    }
+};
+
+/** Collects the bindings declared at the top level of `program`. */
+export const moduleScope = (program: Program): ModuleScope => {
+    const scope = new Map<string, ModuleBinding>();
+    for (const statement of program.body) declare(scope, statement);
+    return scope;
+};
+
+const exportsOf = (program: Program): { readonly exports: Map<string, Export>; readonly stars: string[] } => {
+    const exports = new Map<string, Export>();
+    const stars: string[] = [];
+    for (const statement of program.body) {
+        if (statement.type === "ExportAllDeclaration" && typeof statement.source.value === "string") {
+            const exported = statement.exported === null || statement.exported === undefined ? undefined : nameOf(statement.exported);
+            if (exported === undefined) stars.push(statement.source.value);
+            else exports.set(exported, { kind: "namespace", specifier: statement.source.value });
+        }
+        else if (statement.type === "ExportDefaultDeclaration") {
+            const declaration = statement.declaration;
+            const named = declaration.type === "FunctionDeclaration" || declaration.type === "ClassDeclaration" ? declaration.id?.name
+                : declaration.type === "Identifier" ? declaration.name : undefined;
+            exports.set("default", { kind: "local", local: named ?? defaultBinding });
+        }
+        else if (statement.type === "ExportNamedDeclaration") {
+            const declaration = statement.declaration;
+            if (declaration?.type === "VariableDeclaration") {
+                for (const declarator of declaration.declarations) {
+                    for (const name of patternNames(declarator.id)) exports.set(name, { kind: "local", local: name });
+                }
+            }
+            else if (declaration?.type === "FunctionDeclaration" && declaration.id) exports.set(declaration.id.name, { kind: "local", local: declaration.id.name });
+            const source = statement.source?.value;
+            for (const specifier of statement.specifiers) {
+                const exported = nameOf(specifier.exported);
+                const local = nameOf(specifier.local);
+                if (exported === undefined || local === undefined) continue;
+                exports.set(exported, typeof source === "string" ? { kind: "reexport", specifier: source, imported: local } : { kind: "local", local });
+            }
+        }
+    }
+    return { exports, stars };
+};
+
+/** Lines and columns by counting newlines in `code`. */
+export const locateIn = (code: string): Module["locate"] => {
+    const starts = [0];
+    for (let index = code.indexOf("\n"); index >= 0; index = code.indexOf("\n", index + 1)) starts.push(index + 1);
+    return offset => {
+        let low = 0;
+        let high = starts.length - 1;
+        while (low < high) {
+            const middle = (low + high + 1) >> 1;
+            if (starts[middle] <= offset) low = middle;
+            else high = middle - 1;
+        }
+        return { line: low + 1, column: offset - starts[low] + 1 };
+    };
+};
+
+export const createModule = (file: string, program: Program, locate: Module["locate"]): Module =>
+    ({ file, bindings: moduleScope(program), ...exportsOf(program), locate });

package/src/implementation/compiler/module-value.ts

@@ -0,0 +1,121 @@
+import type { Expression as SourceExpression, Node } from 'estree';
+import type { Program } from '../world/kernel.js';
+import { isValueType } from '../world/intrinsics.js';
+import { fail, within, type Frame } from './failure.js';
+import { resolveBinding, type Resolved } from './link.js';
+import { isIntrinsicModule } from './paths.js';
+import type { Module, ModuleBinding } from './module-scope.js';
+import type { Out } from './out.js';
+import { rootScope, type Scope } from './scope.js';
+import type { Value } from './value.js';
+
+/** Whether `name` is one of the kernel's component or resource keys. */
+export const isKey = (scope: Scope, name: string): boolean => {
+    const signature = scope.unit.signature;
+    return signature.read.has(name) || signature.write.has(name) || signature.resources.includes(name)
+        || signature.lookups.some(lookup => lookup.read.includes(name));
+};
+
+/** Records a failure at `position` in `module` as a frame of `name`. */
+export const frameIn = (module: Module, name: string) => (position: number): Frame => ({ name, file: module.file, ...module.locate(position) });
+
+const displayName = (name: string): string => name === "*default*" ? "default export" : name;
+
+
+/** An `intrinsic(declaration, implementation)` call's declaration, read from its literals. */
+const intrinsicDeclaration = (node: SourceExpression): Program.Intrinsic => {
+    if (node.type !== "ObjectExpression") return fail(node, "an intrinsic is declared with an object literal");
+    let operation: string | undefined;
+    let form: Program.Intrinsic["form"] = "call";
+    let parameters: Program.ValueType[] = [];
+    let result: Program.ValueType | undefined;
+    const text = (value: Node): string => value.type === "Literal" && typeof value.value === "string" ? value.value : fail(value, "intrinsic fields are string literals");
+    const type = (value: Node): Program.ValueType => {
+        const name = text(value);
+        return isValueType(name) ? name : fail(value, `${name} isn't a WGSL type intrinsics take`);
+    };
+    for (const property of node.properties) {
+        if (property.type !== "Property" || property.computed || property.key.type !== "Identifier") return fail(property, "intrinsic fields are named literals");
+        const value = property.value;
+        switch (property.key.name) {
+            case "wgsl": operation = text(value); break;
+            case "form": {
+                const name = text(value);
+                form = name === "infix" || name === "prefix" ? name : fail(value, "an intrinsic's form is infix or prefix");
+                break;
+            }
+            case "parameters":
+                parameters = value.type === "ArrayExpression" ? value.elements.map(element => element === null || element.type === "SpreadElement" ? fail(value, "intrinsic parameters are type names") : type(element)) : fail(value, "intrinsic parameters are an array literal");
+                break;
+            case "result": result = type(value); break;
+            default: return fail(property, `intrinsics have no field ${property.key.name}`);
+        }
+    }
+    if (operation === undefined || result === undefined) return fail(node, "an intrinsic names its wgsl operation and result");
+    return { operation, form, parameters, result };
+};
+
+/** The implementation of `intrinsic(declaration, implementation)`, and its declaration; null for any other initializer. */
+const intrinsicDefinition = (init: SourceExpression, module: Module, scope: Scope): { readonly implementation: SourceExpression; readonly intrinsic: Program.Intrinsic } | null => {
+    const link = scope.unit.link;
+    if (init.type !== "CallExpression" || init.callee.type !== "Identifier" || link === null) return null;
+    const binding = module.bindings.get(init.callee.name);
+    if (binding?.kind !== "import") return null;
+    const resolved = resolveBinding(link, module, init.callee.name, binding);
+    if (resolved.kind !== "binding" || resolved.name !== "intrinsic" || !isIntrinsicModule(resolved.module.file)) return null;
+    const [declaration, implementation] = init.arguments;
+    if (declaration === undefined || declaration.type === "SpreadElement" || implementation === undefined || implementation.type === "SpreadElement") {
+        return fail(init, "intrinsic takes a declaration and an implementation");
+    }
+    return { implementation, intrinsic: intrinsicDeclaration(declaration) };
+};
+
+/** A definition in `module`: a function to inline, or a constant compiled in its own module. */
+const definition = (node: Node, name: string, binding: ModuleBinding, module: Module, scope: Scope, out: Out): Value => {
+    const unit = scope.unit;
+    const identity = `${module.file}\0${name}`;
+    const display = displayName(name);
+    switch (binding.kind) {
+        case "function":
+            return { kind: "function", name: display, identity, params: binding.node.params, body: binding.node.body, module };
+        case "const": {
+            const declared = module === unit.module
+                ? intrinsicDefinition(binding.init, module, scope)
+                : within(node, frameIn(module, display), () => intrinsicDefinition(binding.init, module, scope));
+            const init = declared?.implementation ?? binding.init;
+            if (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression") {
+                if (init.async || init.generator) return fail(init, `${display} must be a plain function to be inlined`);
+                const intrinsic = declared === null ? {} : { intrinsic: declared.intrinsic };
+                return { kind: "function", name: display, identity, params: init.params, body: init.body, module, ...intrinsic };
+            }
+            if (unit.active.has(identity)) return fail(node, `${display} refers to itself`);
+            unit.active.add(identity);
+            const compile = (): Value => unit.expression(init, rootScope(unit, true, module), out);
+            const value = module === unit.module ? compile() : within(node, frameIn(module, display), compile);
+            unit.active.delete(identity);
+            return value;
+        }
+        case "import": case "importNamespace":
+            return moduleValue(node, name, binding, module, scope, out);
+        case "other":
+            return fail(node, `${display} is not a module-scope const`);
+    }
+};
+
+/** A name the linker resolved. */
+export const resolvedValue = (node: Node, resolved: Resolved, scope: Scope, out: Out): Value => {
+    switch (resolved.kind) {
+        case "error": return fail(node, resolved.error);
+        case "namespace": return { kind: "namespace", file: resolved.file };
+        case "binding": return definition(node, resolved.name, resolved.binding, resolved.module, scope, out);
+    }
+};
+
+/** A binding of `module`, followed through imports to the module that defines it. */
+export const moduleValue = (node: Node, name: string, binding: ModuleBinding, module: Module, scope: Scope, out: Out): Value => {
+    const unit = scope.unit;
+    if (module === unit.module && isKey(scope, name)) return fail(node, `${name} is a key; use it to index, as in row[${name}]`);
+    if (binding.kind !== "import" && binding.kind !== "importNamespace") return definition(node, name, binding, module, scope, out);
+    if (unit.link === null) return fail(node, `${name} is imported, and this build doesn't link imports`);
+    return resolvedValue(node, resolveBinding(unit.link, module, name, binding), scope, out);
+};

package/src/implementation/compiler/out.ts

@@ -0,0 +1,6 @@
+import type { Statement } from './ir.js';
+
+/** Emitted statements. A function is resolved last, so it can see what the rest of the body needed. */
+export type Out = (Statement | (() => readonly Statement[]))[];
+
+export const resolve = (out: Out): readonly Statement[] => out.flatMap(item => typeof item === "function" ? item() : [item]);