@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/compiler/data.ts

@@ -0,0 +1,94 @@
+import type { Node } from 'estree';
+import type { Path } from '../world/kernel.js';
+import { fail } from './failure.js';
+import type { Expression } from './ir.js';
+import { scalar } from './scalar.js';
+import type { Scope } from './scope.js';
+import { local } from './ir.js';
+import { snapshotLeaf, type Snapshot } from './snapshot.js';
+import type { Value } from './value.js';
+
+/** A value with a statically known shape: scalar leaves as expressions. */
+export type Data =
+    | { readonly kind: "leaf"; readonly expression: Expression }
+    | { readonly kind: "tuple"; readonly items: readonly Data[] }
+    | { readonly kind: "struct"; readonly fields: readonly (readonly [string, Data])[] };
+
+/**
+ * A snapshot's value at `path`, shaped by the leaves below it the body has used or assigned: a tuple up to the highest
+ * element used, or a struct of the fields used. With none, it is one leaf.
+ */
+const snapshotData = (unit: Scope["unit"], snapshot: Snapshot, path: Path): Data => {
+    const below = [...snapshot.leaves.keys()].flatMap((identity): Path[] => {
+        const leafPath: unknown = JSON.parse(identity);
+        if (!Array.isArray(leafPath) || leafPath.length <= path.length || !path.every((item, index) => leafPath[index] === item)) return [];
+        return [leafPath.filter((item): item is number | string => typeof item === "number" || typeof item === "string")];
+    });
+    const next = below.map(item => item[path.length]);
+    if (next.length === 0) return { kind: "leaf", expression: local(snapshotLeaf(unit, snapshot, path)) };
+    if (next.every(item => typeof item === "number")) {
+        const length = Math.max(...next.filter((item): item is number => typeof item === "number")) + 1;
+        return { kind: "tuple", items: Array.from({ length }, (_, index) => snapshotData(unit, snapshot, [...path, index])) };
+    }
+    const names = [...new Set(next.filter((item): item is string => typeof item === "string"))];
+    return { kind: "struct", fields: names.map(name => [name, snapshotData(unit, snapshot, [...path, name])]) };
+};
+
+/** Converts a value to data. Values of unknown shape become one leaf; a snapshot takes the shape its leaves show. */
+export const toData = (value: Value, node: Node, scope: Scope): Data => {
+    switch (value.kind) {
+        case "tuple": return { kind: "tuple", items: value.items.map(item => toData(item, node, scope)) };
+        case "struct": return { kind: "struct", fields: value.fields.map(([name, field]) => [name, toData(field, node, scope)]) };
+        case "snapshot": return snapshotData(scope.unit, value.snapshot, value.path);
+        default: return { kind: "leaf", expression: scalar(value, node, scope) };
+    }
+};
+
+export type Leaf = { readonly path: Path; readonly expression: Expression };
+
+export const leavesOf = (data: Data, prefix: Path = []): readonly Leaf[] => {
+    switch (data.kind) {
+        case "leaf": return [{ path: prefix, expression: data.expression }];
+        case "tuple": return data.items.flatMap((item, index) => leavesOf(item, [...prefix, index]));
+        case "struct": return data.fields.flatMap(([name, field]) => leavesOf(field, [...prefix, name]));
+    }
+};
+
+export const sameShape = (a: Data, b: Data): boolean => {
+    switch (a.kind) {
+        case "leaf": return b.kind === "leaf";
+        case "tuple": return b.kind === "tuple" && a.items.length === b.items.length && a.items.every((item, index) => sameShape(item, b.items[index]));
+        case "struct": return b.kind === "struct" && a.fields.length === b.fields.length
+            && a.fields.every(([name, field], index) => b.fields[index][0] === name && sameShape(field, b.fields[index][1]));
+    }
+};
+
+/** Rebuilds data with each leaf replaced. */
+export const mapLeaves = (data: Data, map: (expression: Expression, path: Path) => Expression, prefix: Path = []): Data => {
+    switch (data.kind) {
+        case "leaf": return { kind: "leaf", expression: map(data.expression, prefix) };
+        case "tuple": return { kind: "tuple", items: data.items.map((item, index) => mapLeaves(item, map, [...prefix, index])) };
+        case "struct": return { kind: "struct", fields: data.fields.map(([name, field]) => [name, mapLeaves(field, map, [...prefix, name])]) };
+    }
+};
+
+export const dataValue = (data: Data): Value => {
+    switch (data.kind) {
+        case "leaf": return { kind: "scalar", expression: data.expression };
+        case "tuple": return { kind: "tuple", items: data.items.map(dataValue) };
+        case "struct": return { kind: "struct", fields: data.fields.map(([name, field]) => [name, dataValue(field)]) };
+    }
+};
+
+/** Data as a JS value, for command arguments. */
+export const materialize = (data: Data): Expression => {
+    switch (data.kind) {
+        case "leaf": return data.expression;
+        case "tuple": return { kind: "array", items: data.items.map(materialize) };
+        case "struct": return { kind: "record", fields: data.fields.map(([name, field]) => [name, materialize(field)]) };
+    }
+};
+
+export const requireSameShape = (node: Node, a: Data, b: Data): void => {
+    if (!sameShape(a, b)) fail(node, "both values must have the same shape");
+};

package/src/implementation/compiler/estree.ts

@@ -0,0 +1,63 @@
+import type { Node, Pattern, Program } from 'estree';
+import type { parseAst } from 'vite';
+
+declare module 'estree' {
+    interface BaseNode {
+        /** Source offsets; the bundler's parser sets them on every node. */
+        start: number;
+        end: number;
+    }
+}
+
+/** A program from the bundler's parser, as the ESTree program the compiler reads. */
+export const estreeOf = (program: ReturnType<typeof parseAst>): Program =>
+    // The bundler's parser emits ESTree for JavaScript; its own AST types model some nodes differently, such as a directive's literal.
+    program as Program;
+
+export const isNode = (value: unknown): value is Node =>
+    typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
+
+/** The direct child nodes of `node`, in source order. */
+export const children = (node: Node): readonly Node[] => {
+    const result: Node[] = [];
+    for (const value of Object.values(node)) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (isNode(item)) result.push(item);
+            }
+        } else if (isNode(value)) {
+            result.push(value);
+        }
+    }
+    return result;
+};
+
+export const isFunction = (node: Node): boolean =>
+    node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression" || node.type === "FunctionDeclaration";
+
+export const patternNames = (pattern: Pattern): readonly string[] => {
+    switch (pattern.type) {
+        case "Identifier": return [pattern.name];
+        case "ArrayPattern": return pattern.elements.flatMap(element => element === null ? [] : patternNames(element));
+        case "ObjectPattern": return pattern.properties.flatMap(property => patternNames(property.type === "RestElement" ? property.argument : property.value));
+        case "RestElement": return patternNames(pattern.argument);
+        case "AssignmentPattern": return patternNames(pattern.left);
+        case "MemberExpression": return [];
+    }
+};
+
+/** Calls `declare` for each name declared anywhere inside `node`, once per declaration: variables, parameters, functions, classes and catch parameters. */
+export const declaredIn = (node: Node, declare: (name: string) => void): void => {
+    switch (node.type) {
+        case "VariableDeclarator": for (const name of patternNames(node.id)) declare(name); break;
+        case "FunctionDeclaration": case "FunctionExpression": case "ClassDeclaration": case "ClassExpression":
+            if (node.id) declare(node.id.name);
+            break;
+        case "CatchClause": if (node.param) for (const name of patternNames(node.param)) declare(name); break;
+        default: break;
+    }
+    if (node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression" || node.type === "FunctionDeclaration") {
+        for (const param of node.params) for (const name of patternNames(param)) declare(name);
+    }
+    for (const child of children(node)) declaredIn(child, declare);
+};

package/src/implementation/compiler/exact.ts

@@ -0,0 +1,77 @@
+import type { Expression, ObjectExpression, Pattern } from 'estree';
+import { fail } from './failure.js';
+import type { Lists } from './lists.js';
+import type { ModuleScope } from './module-scope.js';
+
+type Access = { readonly read: ReadonlySet<string>; readonly write: ReadonlySet<string> };
+
+/** The keys a body reads, writes and contributes to, by module-scope binding name; null where the body doesn't show every use. */
+export type Used = {
+    readonly query: Access | null;
+    readonly resources: (Access & { readonly reduce: ReadonlySet<string> }) | null;
+    /** The components read from each lookup's results, by lookup name: null for one whose results aren't followed. */
+    readonly lookups: ReadonlyMap<string, ReadonlySet<string> | null> | null;
+    /** The components read from `up`, when the body's uses are all known. */
+    readonly up?: ReadonlySet<string>;
+};
+
+/** An object literal's plain-named properties; none for anything else. */
+const fields = (node: Expression | Pattern | undefined): ReadonlyMap<string, Expression | Pattern> => new Map(node?.type !== "ObjectExpression" ? [] :
+    node.properties.flatMap((property): (readonly [string, Expression | Pattern])[] =>
+        property.type === "Property" && !property.computed && property.key.type === "Identifier" ? [[property.key.name, property.value]] : []));
+
+/**
+ * Requires a list to name only keys in `used`. A list `lists` can't read isn't checked, since its keys can't be matched
+ * to the body's.
+ */
+const requireUsed = (node: Expression | Pattern | undefined, used: ReadonlySet<string>, lists: Lists, message: (name: string) => string): void => {
+    const names = node === undefined ? null : lists.names(node);
+    if (node === undefined || names === null || "error" in names) return;
+    // A key of an array literal is reported where it's listed, and one of a list declared elsewhere where the system names the list.
+    names.forEach((name, k) => {
+        const element = node.type === "ArrayExpression" ? node.elements[k] : null;
+        if (!used.has(name)) fail(element ?? node, message(name));
+    });
+};
+
+/** Requires `reduce` to name only resources in `contributed`, when it names each by a computed module-scope key. */
+const requireContributed = (reduce: Expression | Pattern | undefined, contributed: ReadonlySet<string>, module: ModuleScope): void => {
+    if (reduce?.type !== "ObjectExpression") return;
+    const keys = reduce.properties.map(property =>
+        property.type === "Property" && property.computed && property.key.type === "Identifier" && module.has(property.key.name) ? property.key : null);
+    for (const key of keys) if (key === null) return;
+    for (const key of keys) if (key !== null && !contributed.has(key.name)) fail(key, `${key.name} is in reduce but never contributed to; remove it`);
+};
+
+/**
+ * Requires a system's declared `read`, `write` and `reduce` to be exactly what its body uses: a key it never uses
+ * would still narrow which entities match, and hold back systems that could otherwise run alongside it.
+ */
+export const requireExact = (declaration: ObjectExpression, used: Used, module: ModuleScope, lists: Lists): void => {
+    const declared = fields(declaration);
+    const components = fields(declared.get("components"));
+    const resources = fields(declared.get("resources"));
+    if (used.query !== null) {
+        requireUsed(components.get("read"), used.query.read, lists, name => `${name} is in components read but never read; remove it, or move it to components has to keep requiring it`);
+        requireUsed(components.get("write"), used.query.write, lists, name => `${name} is in components write but never written; remove it, or move it to components read if it's only read`);
+    }
+    if (used.resources !== null) {
+        requireUsed(resources.get("read"), used.resources.read, lists, name => `${name} is in resources read but never read; remove it`);
+        requireUsed(resources.get("write"), used.resources.write, lists, name => `${name} is in resources write but never written; remove it, or move it to resources read if it's only read`);
+        requireContributed(declared.get("reduce"), used.resources.reduce, module);
+    }
+    if (used.up !== undefined) {
+        requireUsed(fields(declared.get("up")).get("read"), used.up, lists,
+            name => `${name} is in up.read but never read; remove it`);
+    }
+    if (used.lookups !== null) {
+        for (const [lookup, value] of fields(declared.get("lookup"))) {
+            const read = used.lookups.get(lookup);
+            if (read === null) continue;
+            const index = fields(value).has("index");
+            requireUsed(fields(value).get("read"), read ?? new Set(), lists, name => index
+                ? `${name} is in lookup.${lookup} read but never read; remove it`
+                : `${name} is in lookup.${lookup} read but never read; remove it, or move it to lookup.${lookup} has to keep requiring it`);
+        }
+    }
+};

package/src/implementation/compiler/expression.ts

@@ -0,0 +1,124 @@
+import type { ConditionalExpression, Identifier, LogicalExpression, Node } from 'estree';
+import { access } from './access.js';
+import { observe, set } from './booleans.js';
+import { mergeBranches } from './branches.js';
+import { call } from './calls.js';
+import { dataValue, leavesOf, mapLeaves, sameShape, toData, type Data } from './data.js';
+import { fail } from './failure.js';
+import { isBinary, isUnary, local, not, number, type Expression } from './ir.js';
+import { memberKey } from './key.js';
+import { moduleValue } from './module-value.js';
+import type { Out } from './out.js';
+import { scalar } from './scalar.js';
+import { findLocal, rootScope, type Scope } from './scope.js';
+import { fresh } from './unit.js';
+import { scalarValue, type Value } from './value.js';
+
+const isTrivial = (expression: Expression): boolean =>
+    expression.kind === "local" || expression.kind === "number" || expression.kind === "boolean";
+
+const identifier = (node: Identifier, scope: Scope, out: Out): Value => {
+    const local = findLocal(scope, node.name);
+    if (local !== undefined) return local.value;
+    const binding = scope.module.bindings.get(node.name);
+    if (binding !== undefined) return moduleValue(node, node.name, binding, scope.module, scope, out);
+    switch (node.name) {
+        case "Math": return { kind: "math" };
+        case "Infinity": return scalarValue(number(Infinity));
+        case "NaN": return scalarValue(number(NaN));
+        case "undefined": return scalarValue({ kind: "nullish", value: "undefined" });
+        default: return fail(node, `${node.name} is not defined in the kernel`);
+    }
+};
+
+/** `test ? a : b` over any matching shapes. Branches that emit statements become an `if`. */
+const conditional = (node: ConditionalExpression, scope: Scope, out: Out): Value => {
+    const unit = scope.unit;
+    const test = scalar(unit.expression(node.test, scope, out), node.test, scope);
+    const consequentOut: Out = [];
+    const alternateOut: Out = [];
+    const consequent = toData(unit.expression(node.consequent, scope, consequentOut), node.consequent, scope);
+    const alternate = toData(unit.expression(node.alternate, scope, alternateOut), node.alternate, scope);
+    return mergeBranches(node, test, consequent, consequentOut, alternate, alternateOut, scope, out);
+};
+
+/** `a && b`, `a || b`, `a ?? b`. A right side that emits statements runs only when needed. */
+const logical = (node: LogicalExpression, scope: Scope, out: Out): Value => {
+    const unit = scope.unit;
+    const left = scalar(unit.expression(node.left, scope, out), node.left, scope);
+    const rightOut: Out = [];
+    const right = scalar(unit.expression(node.right, scope, rightOut), node.right, scope);
+    if (rightOut.length === 0) return scalarValue({ kind: "logical", operator: node.operator, left, right });
+    const name = fresh(unit, "t");
+    const current = local(name);
+    const condition: Expression = node.operator === "&&" ? current : node.operator === "||" ? not(current)
+        : { kind: "binary", operator: "==", left: current, right: { kind: "nullish", value: "null" } };
+    out.push(set(unit, name, left, "let"), { kind: "if", test: condition, consequent: [...rightOut, set(unit, name, right, undefined)], alternate: [] });
+    return scalarValue(current);
+};
+
+const literal = (node: Extract<Node, { type: "Literal" }>): Value => {
+    if (typeof node.value === "number") return scalarValue(number(node.value));
+    if (typeof node.value === "boolean") return scalarValue({ kind: "boolean", value: node.value });
+    if (node.value === null) return scalarValue({ kind: "nullish", value: "null" });
+    return fail(node, "only number, boolean and null literals are in the kernel subset");
+};
+
+/** Compiles an expression to a value, emitting any statements it needs into `out`. */
+export const expression = (node: Node, scope: Scope, out: Out): Value => {
+    switch (node.type) {
+        case "Literal":
+            return literal(node);
+        case "Identifier":
+            return identifier(node, scope, out);
+        case "ArrayExpression":
+            return {
+                kind: "tuple", items: node.elements.map(element => element === null ? fail(node, "holes are not in the kernel subset")
+                    : element.type === "SpreadElement" ? fail(element, "spread is not in the kernel subset")
+                    : expression(element, scope, out)),
+            };
+        case "ObjectExpression":
+            return {
+                kind: "struct", fields: node.properties.map(property => {
+                    if (property.type === "SpreadElement") return fail(property, "spread is not in the kernel subset");
+                    if (property.kind !== "init" || property.method || property.computed) return fail(property, "struct literals use plain field names");
+                    const name = property.key.type === "Identifier" ? property.key.name
+                        : property.key.type === "Literal" && typeof property.key.value === "string" ? property.key.value
+                        : fail(property.key, "struct literals use plain field names");
+                    const value = expression(property.value, scope, out);
+                    return [name, value] satisfies readonly [string, Value];
+                }),
+            };
+        case "UnaryExpression":
+            if (!isUnary(node.operator)) return fail(node, `${node.operator} is not in the kernel subset`);
+            return scalarValue({ kind: "unary", operator: node.operator, operand: scalar(expression(node.argument, scope, out), node.argument, scope) });
+        case "BinaryExpression": {
+            const operator = node.operator;
+            if (!isBinary(operator) || node.left.type === "PrivateIdentifier") return fail(node, `${node.operator} is not in the kernel subset`);
+            const left = scalar(expression(node.left, scope, out), node.left, scope);
+            const right = scalar(expression(node.right, scope, out), node.right, scope);
+            // Strict equality tells true from 1, so boolean reads are converted here.
+            const strict = operator === "===" || operator === "!==";
+            return scalarValue(strict
+                ? { kind: "binary", operator, left: observe(scope.unit, left), right: observe(scope.unit, right) }
+                : { kind: "binary", operator, left, right });
+        }
+        case "LogicalExpression":
+            return logical(node, scope, out);
+        case "ConditionalExpression":
+            return conditional(node, scope, out);
+        case "MemberExpression":
+            if (node.object.type === "Super") return fail(node, "super is not in the kernel subset");
+            return access(expression(node.object, scope, out), memberKey(node, scope, out), node, scope, node.optional);
+        case "ChainExpression":
+            return expression(node.expression, scope, out);
+        case "CallExpression":
+            return call(node, scope, out);
+        case "AssignmentExpression": case "UpdateExpression":
+            return fail(node, "assignments must be statements in a kernel");
+        case "ArrowFunctionExpression": case "FunctionExpression":
+            return fail(node, "functions can't be created in a kernel; define helpers at module scope");
+        default:
+            return fail(node, `${node.type} is not in the kernel subset`);
+    }
+};

package/src/implementation/compiler/failure.ts

@@ -0,0 +1,37 @@
+/** Where an inlined function failed: the function, and the failing line in its file. */
+export type Frame = { readonly name: string; readonly file: string; readonly line: number; readonly column: number };
+
+/**
+ * A build error at a source offset in the module being transformed. When it is inside functions inlined from other
+ * modules, `position` is the call in that module and `frames` lead to the failure, innermost first.
+ */
+export type Failure = { readonly message: string; readonly position: number; readonly frames: readonly Frame[] };
+
+const failures = new WeakMap<object, Failure>();
+
+const abort = (failure: Failure): never => {
+    const error = new Error(failure.message);
+    failures.set(error, failure);
+    throw error;
+};
+
+/** Aborts compiling the current module; `transformKernels` returns it as a `Failure`. */
+export const fail = (node: { readonly start: number }, message: string): never => abort({ message, position: node.start, frames: [] });
+
+export const failureOf = (error: unknown): Failure | undefined =>
+    typeof error === "object" && error !== null ? failures.get(error) : undefined;
+
+/** Runs `compile`; a failure inside it moves to `node`, recording `frame` for where it was. */
+export const within = <T>(node: { readonly start: number }, frame: (position: number) => Frame, compile: () => T): T => {
+    try {
+        return compile();
+    } catch (error) {
+        const failure = failureOf(error);
+        if (failure === undefined) throw error;
+        return abort({ message: failure.message, position: node.start, frames: [...failure.frames, frame(failure.position)] });
+    }
+};
+
+/** A failure's message followed by its frames, as a stack trace shows them. */
+export const describeFailure = (failure: Failure): string =>
+    [failure.message, ...failure.frames.map(frame => `    at ${frame.name} (${frame.file}:${frame.line}:${frame.column})`)].join("\n");

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

@@ -0,0 +1,73 @@
+import { expect, it } from "vitest";
+import { Component, System } from "../../index.js";
+import { workers } from "../../interface/resources/workers.js";
+import { createWorld } from "../index.js";
+
+// Keys named as the generated spawn and add functions name their own bindings: none may capture them.
+const p = Symbol("p");
+const c = Symbol("c");
+const l = Symbol("l");
+const s = Symbol("s");
+const e = Symbol("e");
+const v0 = Symbol("v0");
+const v1 = Symbol("v1");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [p]: { type: number };
+        [c]: { type: number };
+        [l]: { type: number };
+        [s]: { type: number };
+        [e]: { type: number };
+        [v0]: { type: number };
+        [v1]: { type: number };
+    }
+}
+
+const number = { type: { type: "number" } } as const;
+Component.register(p, number);
+Component.register(c, number);
+Component.register(l, number);
+Component.register(s, number);
+Component.register(e, number);
+Component.register(v0, number);
+Component.register(v1, number);
+
+const spawn = System.create(({ commands }) => {
+    const spawned = commands.spawn([p, c, l, s])({ [p]: 1, [c]: 2, [l]: 3, [s]: 4 });
+    commands.add(spawned, [e, v0, v1], { [e]: 5, [v0]: 6, [v1]: 7 });
+    const added = commands.spawn([c, l, s, e, v0, v1])({ [c]: 12, [l]: 13, [s]: 14, [e]: 15, [v0]: 16, [v1]: 17 });
+    commands.add(added, [p], { [p]: 11 });
+});
+
+const read: number[][] = [];
+const readAll = System.create({ observer: true, components: { read: [p, c, l, s, e, v0, v1] } }, row => {
+    read.push([row[p], row[c], row[l], row[s], row[e], row[v0], row[v1]]);
+});
+
+// A kernel whose module constant and locals are named as the kernel emitter's bindings.
+const i = 100;
+const grow = System.create({ kernel: "cpu", components: { read: [c, l], write: [p, s] } }, row => {
+    const n = row[c];
+    const x0 = row[l];
+    const s0 = n + x0;
+    row[p] = s0 + i;
+    row[s] = row[p] - n;
+});
+
+it("runs a kernel whose names are the kernel emitter's", async () => {
+    await using world = createWorld({ [workers]: 0 });
+    await world.run(spawn);
+    await world.run(grow);
+    read.length = 0;
+    await world.run(readAll);
+    expect(read.sort((a, b) => (a[0] ?? 0) - (b[0] ?? 0))).toEqual([[105, 2, 3, 103, 5, 6, 7], [125, 12, 13, 113, 15, 16, 17]]);
+});
+
+it("spawns and adds through keys named as the generated code's bindings", async () => {
+    await using world = createWorld({ [workers]: 0 });
+    await world.run(spawn);
+    read.length = 0;
+    await world.run(readAll);
+    expect(read.sort((a, b) => (a[0] ?? 0) - (b[0] ?? 0))).toEqual([[1, 2, 3, 4, 5, 6, 7], [11, 12, 13, 14, 15, 16, 17]]);
+});

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

@@ -0,0 +1,155 @@
+import { describe, expect, test } from 'vitest';
+import { parseAst } from 'vite';
+import { idOfKey, takeIdOfDeclaration } from '../../interface/registry/ids.js';
+import { estreeOf } from './estree.js';
+import { identify as identifyModule, moduleIdOf } from './identify.js';
+import { attachKernelPath } from './paths.js';
+import { decodeMappings } from './source-map.js';
+
+const parse = (code: string) => estreeOf(parseAst(code));
+/** Imports from the package, and from `./system.js` for `System` alone, are the package's namespaces. */
+const resolve = async (source: string, namespace: string) => source === "@adobe/ecs" || (source === "./system.js" && namespace === "System");
+const identify = (code: string) => identifyModule(code, "src/keys.ts", parse, resolve);
+
+/** The calls the rewrite wraps around each identified `Symbol(...)`, as `[symbol source, id]`. */
+const wrapped = (code: string | undefined): readonly (readonly [string, string])[] =>
+    [...(code ?? "").matchAll(/identify\$\((Symbol\([^)]*\)), "([^"]*)"\)/g)].map(match => [match[1] ?? "", match[2] ?? ""]);
+
+describe("identify, for symbols", () => {
+    test("gives each top-level Symbol(...) declaration its module's id and binding", async () => {
+        const result = await identify([
+            `const a = Symbol("a");`,
+            `let b = Symbol(), c = 1, d = Symbol("d");`,
+            `var e = Symbol("e");`,
+            `export const f = Symbol("f"), g = Symbol();`,
+            `export default Symbol("h");`,
+        ].join("\n"));
+        expect(wrapped(result?.code)).toEqual([
+            [`Symbol("a")`, "src/keys.ts#a"], [`Symbol()`, "src/keys.ts#b"], [`Symbol("d")`, "src/keys.ts#d"], [`Symbol("e")`, "src/keys.ts#e"],
+            [`Symbol("f")`, "src/keys.ts#f"], [`Symbol()`, "src/keys.ts#g"], [`Symbol("h")`, "src/keys.ts#default"],
+        ]);
+        expect(result?.code).toContain("c = 1");
+    });
+    test("records each id where the registry reads it, returning the same symbol", async () => {
+        const result = await identify(`const a = Symbol("a");\nlet b = Symbol();`);
+        const [a, b]: unknown[] = new Function(`${result?.code}\nreturn [a, b];`)();
+        expect([typeof a === "symbol" ? idOfKey(a) : a, typeof b === "symbol" ? idOfKey(b) : b]).toEqual(["src/keys.ts#a", "src/keys.ts#b"]);
+        expect(typeof a === "symbol" ? a.description : a).toBe("a");
+    });
+    test("leaves symbols made in functions, blocks and other expressions", async () => {
+        expect(await identify([
+            `function make() { const inner = Symbol("inner"); return inner; }`,
+            `const arrow = () => Symbol("arrow");`,
+            `{ const block = Symbol("block"); }`,
+            `if (true) var conditional = Symbol("conditional");`,
+            `const [first] = [Symbol("first")];`,
+            `const shared = Symbol.for("shared");`,
+            `const wrapped = Object(Symbol("wrapped"));`,
+            `export const later = make();`,
+        ].join("\n"))).toBe(null);
+    });
+    test("leaves a module where Symbol isn't the global", async () => {
+        for (const shadow of [`import { Symbol } from "elsewhere";`, `const Symbol = (name) => name;`, `function Symbol() {}`, `class Symbol {}`, `var Symbol;`, `import Symbol from "elsewhere";`, `import * as Symbol from "elsewhere";`]) {
+            expect(await identify(`${shadow}\nconst a = Symbol("a");`)).toBe(null);
+        }
+        expect(await identify(`const globalThis = {};\nconst a = Symbol("a");`)).toBe(null);
+    });
+    test("doesn't parse code without Symbol(", async () => {
+        expect(await identifyModule(`const a = 1;`, "src/keys.ts", () => { throw new Error("parsed"); }, resolve)).toBe(null);
+    });
+    test("maps the code it returns back to the source", async () => {
+        const source = `const a = Symbol("a");\nexport const b = Symbol("b"); const after = 2;`;
+        const result = await identify(source);
+        const lines = result?.code.split("\n") ?? [];
+        const segments = decodeMappings(result?.map.mappings ?? "");
+        const at = (line: number, text: string) => {
+            const column = lines[line]?.indexOf(text) ?? -1;
+            const segment = [...segments[line] ?? []].reverse().find(candidate => candidate.column <= column);
+            return segment === undefined ? null : [segment.sourceLine, segment.sourceColumn + column - segment.column];
+        };
+        expect(at(1, "const after")).toEqual([1, source.split("\n")[1]?.indexOf("const after")]);
+        expect(at(1, `Symbol("b")`)).toEqual([1, source.split("\n")[1]?.indexOf(`Symbol("b")`)]);
+        expect(result?.map.sources).toEqual(["src/keys.ts"]);
+    });
+});
+
+/** The declarations the rewrite wraps, as `[declaration source, id]`. */
+const declared = (code: string | undefined): readonly (readonly [string, string])[] =>
+    [...(code ?? "").matchAll(/identify\$\((\{[^}]*\}), "([^"]*)"\)/g)].map(match => [match[1] ?? "", match[2] ?? ""]);
+
+describe("identify, for systems, rules and finalizers", () => {
+    test("gives the declaration of each top-level binding's constructor call its module's id and binding", async () => {
+        const result = await identify([
+            `import { System as S, Rule, Finalizer, Index } from "@adobe/ecs";`,
+            `const move = S.create({ name: "move" }, () => {});`,
+            `export const grid = Index.create({ name: "grid" });`,
+            `export const draw = S.render({ name: "draw" }, () => {}), main = S.create({ name: "main", systems: [move] });`,
+            `const all = S.create([move]);`,
+            `let shown = Rule.create({ name: "shown" });`,
+            `var release = Finalizer.create({ name: "release" }, () => {});`,
+            `export default Finalizer.changes({ name: "save" }, () => {});`,
+        ].join("\n"));
+        expect(declared(result?.code)).toEqual([
+            [`{ name: "move" }`, "src/keys.ts#move"], [`{ name: "grid" }`, "src/keys.ts#grid"], [`{ name: "draw" }`, "src/keys.ts#draw"], [`{ name: "main", systems: [move] }`, "src/keys.ts#main"],
+            [`{ name: "shown" }`, "src/keys.ts#shown"], [`{ name: "release" }`, "src/keys.ts#release"], [`{ name: "save" }`, "src/keys.ts#default"],
+        ]);
+        // A composite's list of members takes its id as a declaration does.
+        expect(result?.code).toContain(`identify$([move], "src/keys.ts#all")`);
+    });
+    test("records each id where the registry takes it, passing the same declaration", async () => {
+        const result = await identify(`import { System } from "@adobe/ecs";\nconst move = System.create({ name: "move" });`);
+        const evaluated = (result?.code ?? "").replace(/^import .*$/m, "const System = { create: (declaration) => declaration };");
+        const declaration: unknown = new Function(`${evaluated}\nreturn move;`)();
+        expect(typeof declaration === "object" && declaration !== null ? [Reflect.get(declaration, "name"), takeIdOfDeclaration(declaration), takeIdOfDeclaration(declaration)] : declaration).toEqual(["move", "src/keys.ts#move", undefined]);
+    });
+    test("identifies a kernel's call the kernel transform wrapped", async () => {
+        const result = await identify(`import { attachKernel as attachKernel$ } from ${JSON.stringify(attachKernelPath)};\nimport { System } from "@adobe/ecs";\nconst grow = attachKernel$(System.create({ name: "grow", kernel: "cpu" }, () => {}), {});`);
+        expect(declared(result?.code)).toEqual([[`{ name: "grow", kernel: "cpu" }`, "src/keys.ts#grow"]]);
+    });
+    test("follows the namespace to the module that exports it, under any local name", async () => {
+        const result = await identify(`import { System as Systems, Rule } from "./system.js";\nconst a = Systems.create({ name: "a" });\nconst b = Rule.create({ name: "b" });`);
+        expect(declared(result?.code)).toEqual([[`{ name: "a" }`, "src/keys.ts#a"]]);
+    });
+    test("leaves calls that aren't a top-level binding's, other namespaces and other methods", async () => {
+        expect(await identify([
+            `import { System, Component } from "@adobe/ecs";`,
+            `import { System as Other } from "elsewhere";`,
+            `function make() { const inner = System.create({ name: "inner" }); return inner; }`,
+            `System.create({ name: "statement" });`,
+            `const wrapped = [System.create({ name: "wrapped" })];`,
+            `const other = Other.create({ name: "other" });`,
+            `const registered = Component.register({ name: "registered" });`,
+            `const spread = System.create(...[{ name: "spread" }]);`,
+            `const computed = System["create"]({ name: "computed" });`,
+        ].join("\n"))).toBe(null);
+    });
+});
+
+describe("moduleIdOf", () => {
+    /** Packages by directory, as their package.json files name them. */
+    const packages = (named: { readonly [directory: string]: string | null }) => (directory: string) => {
+        const name = named[directory];
+        return name === undefined ? undefined : name;
+    };
+    const none = packages({});
+    test("is the nearest package's name and the path in it, without a query", async () => {
+        const app = packages({ "/app": "app", "/repo/packages/shared": "@scope/shared", "/repo/packages/shared/src/nested": null });
+        expect(moduleIdOf("/app/src/keys.ts?t=1712", "/app", app)).toBe("app/src/keys.ts");
+        expect(moduleIdOf("/app/src/worker.ts?worker_file&type=module", "/app/", app)).toBe("app/src/worker.ts");
+        // A workspace package linked from outside the root is named by its package, not its directories.
+        expect(moduleIdOf("/repo/packages/shared/src/nested/keys.ts", "/repo/apps/web", app)).toBe("@scope/shared/src/nested/keys.ts");
+    });
+    test("is a dependency's package name and subpath", async () => {
+        const scoped = packages({ "/app/node_modules/.pnpm/@scope+keys@1.2.0/node_modules/@scope/keys": "@scope/keys" });
+        expect(moduleIdOf("/app/node_modules/.pnpm/@scope+keys@1.2.0/node_modules/@scope/keys/dist/keys.js?v=3f2a", "/app", scoped)).toBe("@scope/keys/dist/keys.js");
+        expect(moduleIdOf("/elsewhere/node_modules/keys/index.js", "/app", none)).toBe("keys/index.js");
+    });
+    test("is the path from the root without a named package", async () => {
+        expect(moduleIdOf("/app/src/keys.ts?t=1712", "/app", none)).toBe("src/keys.ts");
+        expect(moduleIdOf("/libraries/shared/keys.ts?import", "/app", none)).toBe("../libraries/shared/keys.ts");
+    });
+    test("uses forward slashes", async () => {
+        expect(moduleIdOf("C:\\app\\src\\keys.ts", "C:\\app", none)).toBe("src/keys.ts");
+        expect(moduleIdOf("C:\\app\\src\\keys.ts", "C:\\app", packages({ "C:/app": "app" }))).toBe("app/src/keys.ts");
+    });
+});