@adobe/ecs 0.0.0-stage → 0.2.0

package/dist/implementation/compiler/signature.js

@@ -0,0 +1,188 @@
+import { isReduction, reductionOperators } from '../../interface/registry/reduction.js';
+import { fail } from './failure.js';
+const entry = (name, value) => [name, value];
+const propertyName = (property) => {
+    if (!property.computed && property.key.type === "Identifier")
+        return property.key.name;
+    if (property.key.type === "Literal" && typeof property.key.value === "string")
+        return property.key.value;
+    return fail(property.key, "kernel declaration keys must be plain names");
+};
+const properties = (node, what) => {
+    if (node.type !== "ObjectExpression")
+        return fail(node, `${what} must be an object literal in a kernel declaration`);
+    return node.properties.map((property) => property.type === "SpreadElement"
+        ? fail(property, `${what} can't use spread in a kernel declaration`)
+        : entry(propertyName(property), property));
+};
+/** Keys a kernel declaration lists, as `Lists.names` reads them; `what` names the list in a failure. */
+const identifiers = (node, what, lists) => {
+    const names = lists.names(node);
+    return "error" in names ? fail(node, `${what}: ${names.error}`) : names;
+};
+const keyLists = (node, what, allowed, lists) => new Map(properties(node, what).map(([name, property]) => allowed.includes(name)
+    ? entry(name, identifiers(property.value, `${what}.${name}`, lists))
+    : fail(property, `${what}.${name} is not allowed in a kernel declaration`)));
+/** `resources: { reduce: [resource, ...] }`, each folded with its declaration's `reduce` trait. */
+const reductions = (node, lists) => {
+    const names = identifiers(node, "resources.reduce", lists);
+    return names.map((resource) => {
+        const found = lists.reduction(resource);
+        const operator = found?.operator;
+        if (!isReduction(operator)) {
+            const missing = found !== null && /\.m?js$/.test(found.file)
+                ? `which its module's JavaScript doesn't register: declare it in TypeScript, and build a library declaring it with Compiler.plugin({ library: true })`
+                : "which it can't find: declare the resource with reduce in the module that makes its key";
+            return fail(node, `${resource} is reduced, so the build reads its operator from its declaration's reduce trait, ${operator === undefined ? missing : `"${operator}", which isn't one of ${reductionOperators.map(item => JSON.stringify(item)).join(", ")}`}`);
+        }
+        return { resource, operator };
+    }).map((entry, index, all) => all.findIndex(other => other.resource === entry.resource) === index ? entry : fail(node, `${entry.resource} is reduced twice`));
+};
+/** Whether a declaration has property `name`, written out. */
+const declares = (declaration, name) => declaration.properties.some(property => property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === name);
+/** A declaration's `components.optional` property, or null without one. */
+const hasOptional = (declaration) => {
+    for (const property of declaration.properties) {
+        if (property.type !== "Property" || property.computed || property.key.type !== "Identifier" || property.key.name !== "components")
+            continue;
+        if (property.value.type !== "ObjectExpression")
+            return null;
+        for (const field of property.value.properties) {
+            if (field.type === "Property" && !field.computed && field.key.type === "Identifier" && field.key.name === "optional")
+                return field;
+        }
+    }
+    return null;
+};
+/**
+ * How a `System.create` declaration compiles to a kernel, or null when it doesn't: `kernel: true` or `"gpu"` requires
+ * it, `false` rules it out, and without it a system with components is tried, unless it observes, runs on one entity
+ * or spreads what the build can't read.
+ */
+export const kernelOf = (declaration) => {
+    const optional = hasOptional(declaration);
+    for (const property of declaration.properties) {
+        if (property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === "kernel") {
+            const { value } = property;
+            if (value.type === "Literal" && value.value === "gpu" && optional !== null)
+                return fail(optional, "a GPU kernel can't have optional components: WGSL has no undefined to read where an archetype lacks one, and a GPU kernel can't fail its system for one row; list them in with, or use kernel: true to run it on the CPU");
+            if (value.type === "Literal" && value.value === true)
+                return { target: "cpu", required: true };
+            if (value.type === "Literal" && value.value === "gpu")
+                return { target: "gpu", required: true };
+            if (value.type === "Literal" && value.value === false)
+                return null;
+            return fail(value, `kernel must be the literal true, false or "gpu"`);
+        }
+    }
+    if (declaration.properties.some(property => property.type === "SpreadElement"))
+        return null;
+    if (!declares(declaration, "components") || declares(declaration, "observer") || declares(declaration, "target"))
+        return null;
+    return { target: "cpu", required: false };
+};
+/** Reads and validates a kernel declaration; `lists` reads its lists of keys. */
+export const signature = (declaration, module, lists) => {
+    let components;
+    let resources = [];
+    let reduced = [];
+    let changedResources = [];
+    let up = null;
+    let ordered = false;
+    const lookups = [];
+    for (const [name, property] of properties(declaration, "a kernel declaration")) {
+        switch (name) {
+            case "components":
+                components = keyLists(property.value, "components", ["read", "write", "with", "optional", "not", "added", "changed"], lists);
+                break;
+            case "resources":
+                for (const [list, value] of properties(property.value, "resources")) {
+                    // A condition in `is` is readable too; one in `not` is only checked before the kernel runs.
+                    if (list === "read" || list === "is")
+                        resources = [...resources, ...identifiers(value.value, `resources.${list}`, lists)];
+                    else if (list === "changed")
+                        changedResources = identifiers(value.value, "resources.changed", lists);
+                    else if (list === "reduce")
+                        reduced = reductions(value.value, lists);
+                    else if (list === "not")
+                        continue;
+                    else if (list === "write")
+                        fail(value, "a kernel can't write resources: write them from a system that runs as written, or reduce into them");
+                    else
+                        fail(value, `resources.${list} is not allowed in a kernel declaration`);
+                }
+                break;
+            case "lookup":
+                for (const [lookup, value] of properties(property.value, "lookup")) {
+                    // The index is a value the world resolves; only that a lookup goes through one changes how it compiles.
+                    const fields = properties(value.value, `lookup.${lookup}`);
+                    const index = fields.some(([field]) => field === "index");
+                    const listed = fields.filter(([field]) => field !== "index");
+                    const read = listed.flatMap(([field, item]) => {
+                        if (index ? field !== "read" && field !== "changed" : field !== "read" && field !== "with" && field !== "optional" && field !== "not" && field !== "changed")
+                            return fail(item, `lookup.${lookup}.${field} is not allowed in a kernel declaration`);
+                        // An index lookup's `changed: true` filters the system's runs, which the world does before calling it.
+                        if (index && field === "changed" && item.value.type === "Literal" && item.value.value === true)
+                            return [];
+                        const names = identifiers(item.value, `lookup.${lookup}.${field}`, lists);
+                        return field === "read" ? names : [];
+                    });
+                    lookups.push({ name: lookup, read, index, watches: !index && listed.some(([field]) => field === "changed"), optional: listed.some(([field]) => field === "optional") });
+                }
+                break;
+            case "up": {
+                let through;
+                let read = [];
+                for (const [field, value] of properties(property.value, "up")) {
+                    if (field === "through") {
+                        const node = value.value;
+                        through = node.type === "Identifier" && module.has(node.name) ? node.name : fail(node, "up.through is an identifier bound at module scope");
+                    }
+                    else if (field === "read")
+                        read = identifiers(value.value, "up.read", lists);
+                    else
+                        fail(value, `up.${field} is not allowed in a kernel declaration`);
+                }
+                up = { through: through ?? fail(property, "up needs through"), read };
+                break;
+            }
+            // The index is a value the world resolves; only that rows run as a list changes how it compiles.
+            case "order":
+                ordered = true;
+                break;
+            case "kernel":
+            case "before":
+            case "after":
+            case "during":
+                break;
+            default:
+                fail(property, `${name} is not allowed in a kernel declaration`);
+        }
+    }
+    if (components === undefined)
+        return fail(declaration, "a system without components runs once, so there's nothing to compile");
+    for (const { resource } of reduced) {
+        if (resources.includes(resource) || changedResources.includes(resource))
+            fail(declaration, `${resource} is reduced, so it can't also be read or filtered on`);
+    }
+    const write = components.get("write") ?? [];
+    const both = (components.get("read") ?? []).find(key => write.includes(key));
+    if (both !== undefined)
+        fail(declaration, `${both} is in both components read and write; write already makes it readable`);
+    const rowFiltered = (components.get("added")?.length ?? 0) + (components.get("changed")?.length ?? 0) > 0;
+    // A shared component's value is its archetype's: a call reads it once, as a parameter, and never writes it.
+    const writtenShared = write.find(lists.shared);
+    if (writtenShared !== undefined)
+        fail(declaration, `${writtenShared} is shared: its value is its archetype's, so a kernel reads it and never writes it; give it another with commands.add`);
+    const shared = (components.get("read") ?? []).filter(lists.shared);
+    const optionalShared = shared.find(key => components?.get("optional")?.includes(key) === true);
+    if (optionalShared !== undefined)
+        fail(declaration, `${optionalShared} is shared and optional, which kernels don't read yet; list it in with, or run the system as written`);
+    const looked = [...lookups.flatMap(lookup => lookup.read), ...up?.read ?? []].find(lists.shared);
+    if (looked !== undefined)
+        fail(declaration, `${looked} is shared, which a kernel reads only of its own rows, not through a lookup or up; run the system as written`);
+    if (up !== null && ordered)
+        fail(declaration, "a kernel can't use both up and order, which both decide the order of its rows");
+    return { read: new Set(components.get("read")), write: new Set(write), has: new Set(components.get("with")), optional: new Set(components.get("optional")), shared, resources, reduced, lookups, up, ordered, filtered: changedResources.length > 0 || rowFiltered };
+};
+//# sourceMappingURL=signature.js.map

package/dist/implementation/compiler/signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.js","sourceRoot":"","sources":["../../../src/implementation/compiler/signature.ts"],"names":[],"mappings":"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"}

package/dist/implementation/compiler/snapshot.d.ts

@@ -0,0 +1,23 @@
+import type { Path } from '../world/kernel.js';
+import type { Expression, Statement } from './ir.js';
+import { type Unit } from './unit.js';
+/**
+ * A local bound to a component value of unknown shape. Each leaf the body uses becomes its own local,
+ * set where the snapshot was bound, so later writes to the component don't change it.
+ */
+export type Snapshot = {
+    readonly keyword: "const" | "let";
+    readonly hint: string;
+    readonly read: (path: Path) => Expression;
+    readonly leaves: Map<string, {
+        readonly local: number;
+        readonly value: Expression;
+    }>;
+    /** Of an optional component's whole value: whether the call's archetype has it, which tests for undefined read. */
+    readonly presence: Expression | null;
+};
+export declare const createSnapshot: (keyword: "const" | "let", hint: string, read: (path: Path) => Expression, presence?: Expression | null) => Snapshot;
+/** The local holding one leaf of `snapshot`. */
+export declare const snapshotLeaf: (unit: Unit, snapshot: Snapshot, path: Path) => number;
+/** The leaves the body used, resolved after the body is compiled. */
+export declare const snapshotDeclaration: (snapshot: Snapshot) => () => readonly Statement[];

package/dist/implementation/compiler/snapshot.js

@@ -0,0 +1,18 @@
+import { record } from './booleans.js';
+import { fresh } from './unit.js';
+export const createSnapshot = (keyword, hint, read, presence = null) => ({ keyword, hint, read, leaves: new Map(), presence });
+/** The local holding one leaf of `snapshot`. */
+export const snapshotLeaf = (unit, snapshot, path) => {
+    const identity = JSON.stringify(path);
+    const existing = snapshot.leaves.get(identity);
+    if (existing !== undefined)
+        return existing.local;
+    const local = fresh(unit, snapshot.hint);
+    const value = snapshot.read(path);
+    record(unit, local, value);
+    snapshot.leaves.set(identity, { local, value });
+    return local;
+};
+/** The leaves the body used, resolved after the body is compiled. */
+export const snapshotDeclaration = (snapshot) => () => [...snapshot.leaves.values()].map(leaf => ({ kind: "set", local: leaf.local, value: leaf.value, declare: snapshot.keyword }));
+//# sourceMappingURL=snapshot.js.map

package/dist/implementation/compiler/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../../src/implementation/compiler/snapshot.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvC,OAAO,EAAE,KAAK,EAAa,MAAM,WAAW,CAAC;AAe7C,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAwB,EAAE,IAAY,EAAE,IAAgC,EAAE,WAA8B,IAAI,EAAY,EAAE,CACrJ,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAG,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;AAE3D,gDAAgD;AAChD,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAU,EAAE,QAAkB,EAAE,IAAU,EAAU,EAAE;IAC/E,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/C,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC,KAAK,CAAC;IAClD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAChD,OAAO,KAAK,CAAC;AACjB,CAAC,CAAC;AAEF,qEAAqE;AACrE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,QAAkB,EAAE,EAAE,CAAC,GAAyB,EAAE,CAClF,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC"}

package/dist/implementation/compiler/source-map.d.ts

@@ -0,0 +1,34 @@
+import { type Module } from './module-scope.js';
+/** One mapping: a generated column and the source line and column it came from, all counted from 0. */
+type Segment = {
+    readonly column: number;
+    readonly sourceLine: number;
+    readonly sourceColumn: number;
+};
+/** Decodes a source map's `mappings` into each generated line's segments that name a source position. */
+export declare const decodeMappings: (mappings: string) => readonly (readonly Segment[])[];
+/** Locates offsets in `code` at the source positions its map's `mappings` give: the nearest mapping at or before each. */
+export declare const locateThroughMap: (code: string, mappings: string) => Module["locate"];
+/** A source map of one source, version 3, as a bundler takes one from a transform. */
+export type SourceMap = {
+    readonly version: 3;
+    readonly sources: string[];
+    readonly sourcesContent: string[];
+    readonly names: string[];
+    readonly mappings: string;
+};
+/** Text inserted before the character at offset `at`; insertions at one offset keep their order. */
+export type Insertion = {
+    readonly at: number;
+    readonly text: string;
+};
+/**
+ * `code` with `insertions` made, and its map back to `code` named `source`. Every character of `code` keeps its source
+ * position: a segment starts each line, each word or run of other characters, and what follows an insertion, so a
+ * position maps to its own column without interpolating. Inserted text maps to nothing of its own.
+ */
+export declare const insertInto: (code: string, insertions: readonly Insertion[], source: string) => {
+    readonly code: string;
+    readonly map: SourceMap;
+};
+export {};

package/dist/implementation/compiler/source-map.js

@@ -0,0 +1,131 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { locateIn } from './module-scope.js';
+const base64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/** Decodes a source map's `mappings` into each generated line's segments that name a source position. */
+export const decodeMappings = (mappings) => {
+    const lines = [];
+    let sourceLine = 0;
+    let sourceColumn = 0;
+    for (const line of mappings.split(";")) {
+        const segments = [];
+        let column = 0;
+        for (const text of line.split(",")) {
+            if (text === "")
+                continue;
+            const values = [];
+            let value = 0;
+            let shift = 0;
+            for (const character of text) {
+                const digit = base64.indexOf(character);
+                value += (digit & 31) << shift;
+                if (digit & 32)
+                    shift += 5;
+                else {
+                    values.push(value & 1 ? -(value >>> 1) : value >>> 1);
+                    value = 0;
+                    shift = 0;
+                }
+            }
+            column += values[0] ?? 0;
+            if (values.length < 4)
+                continue;
+            sourceLine += values[2] ?? 0;
+            sourceColumn += values[3] ?? 0;
+            segments.push({ column, sourceLine, sourceColumn });
+        }
+        lines.push(segments);
+    }
+    return lines;
+};
+/** Locates offsets in `code` at the source positions its map's `mappings` give: the nearest mapping at or before each. */
+export const locateThroughMap = (code, mappings) => {
+    const generated = locateIn(code);
+    const lines = decodeMappings(mappings);
+    return offset => {
+        const { line, column } = generated(offset);
+        for (let index = line - 1; index >= 0; index--) {
+            const segments = lines[index] ?? [];
+            const found = [...segments].reverse().find(segment => index < line - 1 || segment.column <= column - 1);
+            if (found !== undefined)
+                return { line: found.sourceLine + 1, column: found.sourceColumn + 1 + (index === line - 1 ? column - 1 - found.column : 0) };
+        }
+        return { line, column };
+    };
+};
+/** Appends `value` as a base64 VLQ, the sign in its lowest bit. */
+const encode = (value, into) => {
+    let rest = value < 0 ? (-value << 1) | 1 : value << 1;
+    do {
+        let digit = rest & 31;
+        rest >>>= 5;
+        if (rest > 0)
+            digit |= 32;
+        into.push(base64[digit] ?? "");
+    } while (rest > 0);
+};
+const word = /[\w$]/;
+/**
+ * `code` with `insertions` made, and its map back to `code` named `source`. Every character of `code` keeps its source
+ * position: a segment starts each line, each word or run of other characters, and what follows an insertion, so a
+ * position maps to its own column without interpolating. Inserted text maps to nothing of its own.
+ */
+export const insertInto = (code, insertions, source) => {
+    const ordered = insertions.map((insertion, order) => ({ insertion, order })).sort((a, b) => a.insertion.at - b.insertion.at || a.order - b.order);
+    const output = [];
+    const mappings = [];
+    let generatedColumn = 0;
+    let lineHasSegment = false;
+    let lastGeneratedColumn = 0;
+    let lastSourceLine = 0;
+    let lastSourceColumn = 0;
+    let sourceLine = 0;
+    let sourceColumn = 0;
+    let next = 0;
+    let inserted = true;
+    const newLine = () => {
+        mappings.push(";");
+        generatedColumn = 0;
+        lastGeneratedColumn = 0;
+        lineHasSegment = false;
+    };
+    const write = (text) => {
+        output.push(text);
+        for (let k = 0; k < text.length; k++) {
+            if (text[k] === "\n")
+                newLine();
+            else
+                generatedColumn++;
+        }
+    };
+    for (let at = 0; at <= code.length; at++) {
+        while (next < ordered.length && ordered[next].insertion.at === at) {
+            write(ordered[next++].insertion.text);
+            inserted = true;
+        }
+        if (at === code.length)
+            break;
+        const character = code[at] ?? "";
+        if (character !== "\n" && (inserted || sourceColumn === 0 || word.test(character) !== word.test(code[at - 1] ?? ""))) {
+            if (lineHasSegment)
+                mappings.push(",");
+            encode(generatedColumn - lastGeneratedColumn, mappings);
+            encode(0, mappings);
+            encode(sourceLine - lastSourceLine, mappings);
+            encode(sourceColumn - lastSourceColumn, mappings);
+            lastGeneratedColumn = generatedColumn;
+            lastSourceLine = sourceLine;
+            lastSourceColumn = sourceColumn;
+            lineHasSegment = true;
+        }
+        inserted = false;
+        write(character);
+        if (character === "\n") {
+            sourceLine++;
+            sourceColumn = 0;
+        }
+        else
+            sourceColumn++;
+    }
+    return { code: output.join(""), map: { version: 3, sources: [source], sourcesContent: [code], names: [], mappings: mappings.join("") } };
+};
+//# sourceMappingURL=source-map.js.map

package/dist/implementation/compiler/source-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-map.js","sourceRoot":"","sources":["../../../src/implementation/compiler/source-map.ts"],"names":[],"mappings":"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"}

package/dist/implementation/compiler/spawns.d.ts

@@ -0,0 +1,41 @@
+import type { Node } from 'estree';
+import type { ModuleScope } from './module-scope.js';
+type Range = {
+    readonly start: number;
+    readonly end: number;
+};
+/**
+ * A `commands.spawn(components)({ ... })` or `commands.add(entity, components, { ... })` call with literal keys: key
+ * expressions as module-scope source, and source ranges of the entity, for an add, of the components and of the values
+ * in order.
+ */
+export type SpawnSite = Range & {
+    readonly kind: "spawn" | "add";
+    readonly entity: Range | null;
+    readonly components: Range;
+    readonly keys: readonly string[];
+    readonly values: readonly Range[];
+};
+/**
+ * The spawn and add sites in a main-thread system body whose values can pass positionally: `spawn(components)(values)`
+ * and `add(entity, components, values)` on the commands of the body's own context parameter, at index `context`, with
+ * an object literal of computed keys, each a module-scope constant. A body that redeclares the context or its commands anywhere is left alone, and so is a
+ * key it shadows.
+ */
+export declare const spawnSites: (body: Node, module: ModuleScope, context: number, shadowed?: ReadonlySet<string>) => {
+    readonly commands: string;
+    readonly sites: readonly SpawnSite[];
+} | null;
+/** An array literal of keys a command takes as its components, and the keys' names. */
+export type ListSite = {
+    readonly start: number;
+    readonly end: number;
+    readonly names: readonly string[];
+};
+/**
+ * The array literals of keys a main-thread system body passes its own commands as components, `spawn([...])`,
+ * `add(entity, [...], ...)` and `remove(entity, [...])`, which the transform makes once, with an index, rather than on
+ * every call. A list naming a key twice fails.
+ */
+export declare const listSites: (body: Node, module: ModuleScope, context: number, shadowed?: ReadonlySet<string>) => readonly ListSite[];
+export {};

package/dist/implementation/compiler/spawns.js

@@ -0,0 +1,164 @@
+import { children, declaredIn, patternNames } from './estree.js';
+import { fail } from './failure.js';
+/** A plain, string or number key, which is never a component's, since component keys are symbols. */
+const plainKey = (property) => property.type === "Property" && property.kind === "init" && !property.method && (!property.computed || property.key.type === "Literal");
+/** A key as a module-scope expression, or null when the property isn't a module constant's computed key. */
+const keyOf = (property, module, declared) => {
+    if (property.type !== "Property" || property.kind !== "init" || property.method || !property.computed)
+        return null;
+    const { key } = property;
+    if (key.type !== "Identifier")
+        return null;
+    return module.has(key.name) && !declared.has(key.name) ? key.name : null;
+};
+/** Whether an add's components are a list as written: an array literal, or a module constant of one, as the plugin may give it an index. */
+const listed = (components, module, declared) => {
+    if (components.type === "ArrayExpression")
+        return true;
+    if (components.type !== "Identifier" || declared.has(components.name))
+        return false;
+    const binding = module.get(components.name);
+    if (binding?.kind !== "const")
+        return false;
+    const { init } = binding;
+    return init.type === "ArrayExpression" || (init.type === "CallExpression" && init.callee.type === "Identifier" && /^archetype\$\d*$/.test(init.callee.name)
+        && init.arguments[0]?.type === "ArrayExpression");
+};
+const plainKeyFailure = "a command's keys are its components' symbols, as [key]; a plain or string key is never a component's";
+/** Where a body reaches its commands: a name bound to them, or a context parameter's `commands`. */
+const commandsOf = (parameter) => {
+    if (parameter?.type === "Identifier")
+        return { name: parameter.name, viaContext: true };
+    if (parameter?.type !== "ObjectPattern")
+        return null;
+    for (const property of parameter.properties) {
+        if (property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === "commands") {
+            return property.value.type === "Identifier" ? { name: property.value.name, viaContext: false } : null;
+        }
+    }
+    return null;
+};
+/**
+ * The spawn and add sites in a main-thread system body whose values can pass positionally: `spawn(components)(values)`
+ * and `add(entity, components, values)` on the commands of the body's own context parameter, at index `context`, with
+ * an object literal of computed keys, each a module-scope constant. A body that redeclares the context or its commands anywhere is left alone, and so is a
+ * key it shadows.
+ */
+export const spawnSites = (body, module, context, shadowed = new Set()) => {
+    if (body.type !== "ArrowFunctionExpression" && body.type !== "FunctionExpression")
+        return null;
+    const reached = commandsOf(body.params[context]);
+    if (reached === null)
+        return null;
+    const declared = new Set();
+    declaredIn(body.body, name => declared.add(name));
+    if (declared.has(reached.name))
+        return null;
+    // Names declared around the body, and its other parameters, shadow a module's keys too.
+    for (const name of shadowed)
+        declared.add(name);
+    for (const name of body.params.flatMap(parameter => parameter === body.params[context] ? [] : patternNames(parameter)))
+        declared.add(name);
+    const isCommands = (node) => reached.viaContext
+        ? node.type === "MemberExpression" && !node.computed && !node.optional && node.object.type === "Identifier" && node.object.name === reached.name
+            && node.property.type === "Identifier" && node.property.name === "commands"
+        : node.type === "Identifier" && node.name === reached.name;
+    const sites = [];
+    /** The method a call makes on the commands, and its arguments, or null. */
+    const method = (node) => node.type === "CallExpression" && node.callee.type === "MemberExpression" && !node.callee.computed && !node.optional
+        && isCommands(node.callee.object) && node.callee.property.type === "Identifier"
+        ? { name: node.callee.property.name, arguments: node.arguments }
+        : null;
+    const visit = (node) => {
+        if (node.type === "CallExpression" && !node.optional) {
+            const spawned = method(node.callee);
+            const called = method(node);
+            const spawn = spawned?.name === "spawn" && spawned.arguments.length === 1 && node.arguments.length === 1 ? spawned.arguments[0] : null;
+            const add = called?.name === "add" && called.arguments.length === 3 ? called.arguments : null;
+            const components = spawn ?? add?.[1] ?? null;
+            const values = spawn !== null ? node.arguments[0] : add?.[2];
+            const entity = add?.[0] ?? null;
+            if (components !== null && components.type !== "SpreadElement" && entity?.type !== "SpreadElement" && values?.type === "ObjectExpression") {
+                // A spawn's values, or a list add's, are keyed by components; one component's object value has keys of its own.
+                const plain = values.properties.find(plainKey);
+                if (plain !== undefined && (spawn !== null || listed(components, module, declared)))
+                    return fail(plain.type === "Property" ? plain.key : plain, plainKeyFailure);
+                const keys = plain === undefined ? values.properties.map(property => keyOf(property, module, declared)) : [null];
+                if (keys.every((key) => key !== null)) {
+                    sites.push({
+                        kind: spawn !== null ? "spawn" : "add",
+                        start: node.start,
+                        end: node.end,
+                        entity: entity === null ? null : { start: entity.start, end: entity.end },
+                        components: { start: components.start, end: components.end },
+                        keys,
+                        values: values.properties.flatMap(property => property.type === "Property" ? [{ start: property.value.start, end: property.value.end }] : []),
+                    });
+                    return;
+                }
+            }
+        }
+        for (const child of children(node))
+            visit(child);
+    };
+    visit(body.body);
+    return { commands: reached.viaContext ? `${reached.name}.commands` : reached.name, sites };
+};
+/** Whether a module-scope name is a key: a constant of `Symbol(...)`, or an import, which the appended function checks. */
+const isKeyName = (name, module, declared) => {
+    if (declared.has(name))
+        return false;
+    const binding = module.get(name);
+    if (binding?.kind === "import")
+        return true;
+    return binding?.kind === "const" && binding.init.type === "CallExpression" && binding.init.callee.type === "Identifier" && binding.init.callee.name === "Symbol";
+};
+/**
+ * The array literals of keys a main-thread system body passes its own commands as components, `spawn([...])`,
+ * `add(entity, [...], ...)` and `remove(entity, [...])`, which the transform makes once, with an index, rather than on
+ * every call. A list naming a key twice fails.
+ */
+export const listSites = (body, module, context, shadowed = new Set()) => {
+    if (body.type !== "ArrowFunctionExpression" && body.type !== "FunctionExpression")
+        return [];
+    const reached = commandsOf(body.params[context]);
+    if (reached === null)
+        return [];
+    const declared = new Set();
+    declaredIn(body.body, name => declared.add(name));
+    if (declared.has(reached.name))
+        return [];
+    // Names declared around the body, and its other parameters, shadow a module's keys too.
+    for (const name of shadowed)
+        declared.add(name);
+    for (const name of body.params.flatMap(parameter => parameter === body.params[context] ? [] : patternNames(parameter)))
+        declared.add(name);
+    const isCommands = (node) => reached.viaContext
+        ? node.type === "MemberExpression" && !node.computed && !node.optional && node.object.type === "Identifier" && node.object.name === reached.name
+            && node.property.type === "Identifier" && node.property.name === "commands"
+        : node.type === "Identifier" && node.name === reached.name;
+    const sites = [];
+    const visit = (node) => {
+        if (node.type === "CallExpression" && !node.optional && node.callee.type === "MemberExpression" && !node.callee.computed && !node.callee.optional
+            && isCommands(node.callee.object) && node.callee.property.type === "Identifier") {
+            const { name } = node.callee.property;
+            const list = name === "spawn" && node.arguments.length === 1 ? node.arguments[0]
+                : (name === "add" || name === "remove") && node.arguments.length >= 2 ? node.arguments[1]
+                    : undefined;
+            if (list?.type === "ArrayExpression" && list.elements.length > 0) {
+                const names = list.elements.map(element => element?.type === "Identifier" && isKeyName(element.name, module, declared) ? element.name : null);
+                if (names.every((key) => key !== null)) {
+                    const repeated = names.find((key, k) => names.indexOf(key) < k);
+                    if (repeated !== undefined)
+                        return fail(list, `this list names ${repeated} twice; a list of components names each once`);
+                    sites.push({ start: list.start, end: list.end, names });
+                }
+            }
+        }
+        for (const child of children(node))
+            visit(child);
+    };
+    visit(body.body);
+    return sites;
+};
+//# sourceMappingURL=spawns.js.map