@adobe/ecs 0.1.0 → 0.2.1

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

@@ -1,15 +1,20 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 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 { identify as identifyModule, moduleIdOf, moduleLabelOf } from './identify.js';
+import { nodeCopies, ownCopy } 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);
+const identify = async (code: string) => {
+    const result = await identifyModule(code, "src/keys.ts", parse, resolve, nodeCopies);
+    if (result !== null && "failure" in result) throw new Error(result.failure);
+    return result;
+};
 
 /** The calls the rewrite wraps around each identified `Symbol(...)`, as `[symbol source, id]`. */
 const wrapped = (code: string | undefined): readonly (readonly [string, string])[] =>
@@ -55,7 +60,7 @@ describe("identify, for symbols", () => {
         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);
+        expect(await identifyModule(`const a = 1;`, "src/keys.ts", () => { throw new Error("parsed"); }, resolve, nodeCopies)).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;`;
@@ -81,75 +86,124 @@ 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 move = S.create({ tag: "move" }, () => {});`,
+            `export const grid = Index.create({ tag: "grid" });`,
+            `export const draw = S.render({ tag: "draw" }, () => {}), main = S.create({ tag: "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" }, () => {});`,
+            `let shown = Rule.create({ tag: "shown" });`,
+            `var release = Finalizer.create({ tag: "release" }, () => {});`,
+            `export default Finalizer.changes({ tag: "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"],
+            [`{ tag: "move" }`, "src/keys.ts#move"], [`{ tag: "grid" }`, "src/keys.ts#grid"], [`{ tag: "draw" }`, "src/keys.ts#draw"], [`{ tag: "main", systems: [move] }`, "src/keys.ts#main"],
+            [`{ tag: "shown" }`, "src/keys.ts#shown"], [`{ tag: "release" }`, "src/keys.ts#release"], [`{ tag: "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 result = await identify(`import { System } from "@adobe/ecs";\nconst move = System.create({ tag: "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]);
+        expect(typeof declaration === "object" && declaration !== null ? [Reflect.get(declaration, "tag"), 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"]]);
+        const result = await identify(`import { attachKernel as attachKernel$ } from ${JSON.stringify(ownCopy.attachKernel)};\nimport { System } from "@adobe/ecs";\nconst grow = attachKernel$(System.create({ tag: "grow", kernel: true }, () => {}), {});`);
+        expect(declared(result?.code)).toEqual([[`{ tag: "grow", kernel: true }`, "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"]]);
+        const result = await identify(`import { System as Systems, Rule } from "./system.js";\nconst a = Systems.create({ tag: "a" });\nconst b = Rule.create({});`);
+        expect(declared(result?.code)).toEqual([[`{ tag: "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([
+    test("labels a call that isn't a top-level binding's by the binding, function, property or method it's in, and leaves other namespaces and methods", async () => {
+        const result = 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);
+            `function make() { return System.create({ tag: "make" }); }`,
+            `const mover = (speed) => { const inner = System.create({ tag: "inner" }); return inner; };`,
+            `const systems = { move: System.create({ tag: "move" }) };`,
+            `System.create({ tag: "alone" });`,
+            `const wrapped = [System.create({ tag: "wrapped" })];`,
+            `const other = Other.create({ tag: "other" });`,
+            `const registered = Component.register({ tag: "registered" });`,
+            `const spread = System.create(...[{ tag: "spread" }]);`,
+            `const computed = System["create"]({ tag: "computed" });`,
+        ].join("\n"));
+        expect([...(result?.code ?? "").matchAll(/label\$\((\{[^}]*\}), "(\w+)"\)/g)].map(match => [match[1], match[2]])).toEqual([
+            [`{ tag: "make" }`, "make"], [`{ tag: "inner" }`, "inner"], [`{ tag: "move" }`, "move"], [`{ tag: "wrapped" }`, "wrapped"],
+        ]);
+        expect(result?.code).not.toContain("identify$");
+    });
+    test("labels a call made in another's arguments by the name nearest it", async () => {
+        const result = await identify(`import { System } from "@adobe/ecs";\nfunction make() { return System.create({ systems: [System.create({ tag: "nested" })] }); }`);
+        expect([...(result?.code ?? "").matchAll(/label\$\((\{ tag[^}]*\}), "(\w+)"\)/g)].map(match => [match[1], match[2]])).toEqual([[`{ tag: "nested" }`, "systems"]]);
+    });
+    test("keeps a label already given, as an internal factory gives its own, in a map holding declarations weakly", async () => {
+        const result = await identify(`import { System } from "@adobe/ecs";\nfunction make(given) { return System.create(given); }\nfunction fresh() { return System.create({}); }`);
+        const evaluated = (result?.code ?? "").replace(/^import .*$/m, "const System = { create: (declaration) => declaration };");
+        const declaration = {};
+        const labels = new WeakMap([[declaration, "given"]]);
+        Reflect.set(globalThis, Symbol.for("@adobe/ecs/labels@1"), labels);
+        const [make] = new Function(`${evaluated}\nreturn [make, fresh];`)();
+        make(declaration);
+        expect(labels.get(declaration)).toBe("given");
+        // A declaration whose constructor throws before taking its label isn't kept alive by it.
+        Reflect.deleteProperty(globalThis, Symbol.for("@adobe/ecs/labels@1"));
+        new Function(`${evaluated}\nreturn fresh;`)()();
+        expect(Reflect.get(globalThis, Symbol.for("@adobe/ecs/labels@1"))).toBeInstanceOf(WeakMap);
+    });
+    test("fails for a module outside a named package, which has nothing to name its ids by", async () => {
+        const result = await identifyModule(`export const position = Symbol();`, null, parse, resolve, nodeCopies);
+        expect(result !== null && "failure" in result ? result.failure : result).toContain("package.json");
+        expect(await identifyModule(`export const two = 2;`, null, parse, resolve, nodeCopies)).toBe(null);
+    });
+});
+
+describe("moduleLabelOf", () => {
+    test("is the module's package and path in it, else a dependency's package and subpath, else its file's name", () => {
+        const app = (directory: string) => directory === "/repo/app" ? { name: "@scope/app", version: "1.0.0" } : undefined;
+        expect(moduleLabelOf("/repo/app/src/features/a/model.ts?t=1", app)).toBe("@scope/app/src/features/a/model.ts");
+        expect(moduleLabelOf("/x/node_modules/keys/index.js", () => undefined)).toBe("keys/index.js");
+        expect(moduleLabelOf("/loose/model.ts", () => undefined)).toBe("model.ts");
     });
 });
 
 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;
+    /** Packages by directory, as their package.json files name and version them. */
+    const packages = (named: { readonly [directory: string]: { readonly name: string; readonly version?: string } | null }) => (directory: string) => {
+        const found = named[directory];
+        return found === undefined ? undefined : found;
     };
     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");
+    test("is the nearest package's name, its version and the path in it, without a query", async () => {
+        const app = packages({ "/app": { name: "app", version: "1.2.0" }, "/repo/packages/shared": { name: "@scope/shared", version: "0.3.1" }, "/repo/packages/shared/src/nested": null });
+        expect(moduleIdOf("/app/src/keys.ts?t=1712", app)).toBe("app@1.2.0/src/keys.ts");
+        expect(moduleIdOf("/app/src/worker.ts?worker_file&type=module", app)).toBe("app@1.2.0/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");
+        expect(moduleIdOf("/repo/packages/shared/src/nested/keys.ts", app)).toBe("@scope/shared@0.3.1/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("leaves out a version the package doesn't give", async () => {
+        expect(moduleIdOf("/app/src/keys.ts", packages({ "/app": { name: "app" } }))).toBe("app/src/keys.ts");
     });
-    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("is a dependency's package name, version and subpath", async () => {
+        const scoped = packages({ "/app/node_modules/.pnpm/@scope+keys@1.2.0/node_modules/@scope/keys": { name: "@scope/keys", version: "1.2.0" } });
+        expect(moduleIdOf("/app/node_modules/.pnpm/@scope+keys@1.2.0/node_modules/@scope/keys/dist/keys.js?v=3f2a", scoped)).toBe("@scope/keys@1.2.0/dist/keys.js");
+        expect(moduleIdOf("/elsewhere/node_modules/keys/index.js", none)).toBe("keys/index.js");
+    });
+    test("is null outside a named package", async () => {
+        expect(moduleIdOf("/app/src/keys.ts?t=1712", none)).toBe(null);
+        expect(moduleIdOf("/libraries/shared/keys.ts", packages({ "/libraries": null }))).toBe(null);
+    });
+    test("stops at a drive's root, never reading the working directory's package", async () => {
+        const read: string[] = [];
+        const cwd = (directory: string) => {
+            read.push(directory);
+            return directory === "." ? { name: "cwd", version: "1.0.0" } : undefined;
+        };
+        expect(moduleIdOf("C:\\elsewhere\\keys.ts", cwd)).toBe(null);
+        expect(read).toEqual(["C:/elsewhere", "C:"]);
     });
     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");
+        expect(moduleIdOf("C:\\app\\src\\keys.ts", packages({ "C:/app": { name: "app", version: "1.0.0" } }))).toBe("app@1.0.0/src/keys.ts");
     });
 });

package/src/implementation/compiler/identify.ts

@@ -1,10 +1,10 @@
-/// <reference types="node" />
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Expression, Node, Program } from 'estree';
-import { posix } from 'node:path';
-import { idsName } from '../../interface/registry/ids.js';
+import { idsName, labelsName } from '../../interface/registry/ids.js';
 import { children, isFunction } from './estree.js';
 import { moduleScope } from './module-scope.js';
-import { attachKernelPath } from './paths.js';
+import type { PackageCopies } from './package-copies.js';
+import * as posix from './posix.js';
 import { insertInto, type Insertion, type SourceMap } from './source-map.js';
 
 export type Parse = (code: string) => Program;
@@ -15,25 +15,40 @@ export type Identified = { readonly code: string; readonly map: SourceMap };
 /** A dependency's path inside the last `node_modules`: its package name and subpath. */
 const dependency = /\/node_modules\/(?!.*\/node_modules\/)(.+)$/;
 
-/** The name a directory's package.json gives: undefined without one, null for one without a name. */
-export type PackageNameOf = (directory: string) => string | null | undefined;
+/** What a directory's package.json gives: undefined without one, null for one without a name. */
+export type PackageOf = (directory: string) => { readonly name: string; readonly version?: string } | null | undefined;
 
-/**
- * A module's id: the name of the nearest package.json above it that has one and its path in that package, else for a
- * dependency its package name and subpath, else its path from `root`. Without a query and with forward slashes, so it's
- * the same on every machine and names no directory outside its package.
- */
-export const moduleIdOf = (file: string, root: string, packageNameOf: PackageNameOf): string => {
-    const path = (file.split("?")[0] ?? file).replace(/\\/g, "/");
+/** A module's file without a query, with forward slashes. */
+const pathOf = (file: string): string => (file.split("?")[0] ?? file).replace(/\\/g, "/");
+
+/** The nearest package.json above a module that has a name, with the module's path in it. */
+const packageAbove = (file: string, packageOf: PackageOf): { readonly name: string; readonly version?: string; readonly path: string } | null => {
+    const path = pathOf(file);
     for (let directory = posix.dirname(path); ; directory = posix.dirname(directory)) {
-        const name = packageNameOf(directory);
-        if (typeof name === "string") return `${name}/${posix.relative(directory, path)}`;
-        if (posix.dirname(directory) === directory) break;
+        const found = packageOf(directory);
+        if (found !== null && found !== undefined) return { ...found, path: posix.relative(directory, path) };
+        // A filesystem's root, `/` or a drive's `C:`, whose parent posix paths give as itself or as `.`.
+        const parent = posix.dirname(directory);
+        if (parent === directory || parent === ".") return null;
     }
-    const found = dependency.exec(path)?.[1];
-    if (found !== undefined) return found;
-    const relative = posix.relative(root.replace(/\\/g, "/"), path);
-    return posix.isAbsolute(relative) ? posix.basename(path) : relative;
+};
+
+/**
+ * A module's id: the name and version of the nearest package.json above it that has a name, and its path in that
+ * package, else for a dependency its package name and subpath; null outside both. Without a query and with forward
+ * slashes, so it's the same on every machine and names no directory outside its package. Copies of one package at
+ * different versions have different ids.
+ */
+export const moduleIdOf = (file: string, packageOf: PackageOf): string | null => {
+    const found = packageAbove(file, packageOf);
+    if (found !== null) return `${found.name}${found.version === undefined ? "" : `@${found.version}`}/${found.path}`;
+    return dependency.exec(pathOf(file))?.[1] ?? null;
+};
+
+/** How messages name a module: its package's name and its path there, as its id has them, else the file's name. */
+export const moduleLabelOf = (file: string, packageOf: PackageOf): string => {
+    const found = packageAbove(file, packageOf);
+    return found !== null ? `${found.name}/${found.path}` : dependency.exec(pathOf(file))?.[1] ?? posix.basename(pathOf(file));
 };
 
 /** Whether a binding named `name` is declared in the module's scope: at top level, or as a `var` in any of its blocks. */
@@ -67,7 +82,7 @@ const isNamespace = (name: string): name is Namespace => name === "System" || na
 export type ResolveNamespace = (source: string, namespace: Namespace) => Promise<boolean>;
 
 /** The module's local names of the package's namespaces, and of the kernel transform's `attachKernel`. */
-const localsOf = async (program: Program, resolve: ResolveNamespace): Promise<{ readonly namespaces: ReadonlyMap<string, Namespace>; readonly attach: ReadonlySet<string> }> => {
+const localsOf = async (program: Program, resolve: ResolveNamespace, packages: PackageCopies): Promise<{ readonly namespaces: ReadonlyMap<string, Namespace>; readonly attach: ReadonlySet<string> }> => {
     const namespaces = new Map<string, Namespace>();
     const attach = new Set<string>();
     for (const statement of program.body) {
@@ -75,7 +90,7 @@ const localsOf = async (program: Program, resolve: ResolveNamespace): Promise<{
         for (const specifier of statement.specifiers) {
             if (specifier.type !== "ImportSpecifier" || specifier.imported.type !== "Identifier") continue;
             const imported = specifier.imported.name;
-            if (statement.source.value === attachKernelPath && imported === "attachKernel") attach.add(specifier.local.name);
+            if (imported === "attachKernel" && packages.isAttachKernelModule(statement.source.value)) attach.add(specifier.local.name);
             else if (isNamespace(imported) && await resolve(statement.source.value, imported)) namespaces.set(specifier.local.name, imported);
         }
     }
@@ -119,14 +134,15 @@ const mayDeclare = /\.(create|render|changes)\(/;
  *
  * The same bindings initialized by a constructor call of the package's `System`, `Rule`, `Finalizer` or `Index`, imported under
  * any local name, give the call's declaration their id, which the constructor takes from the map: a kernel's call as
- * the kernel transform wrapped it too. Returns null when nothing is identified.
+ * the kernel transform wrapped it too. Returns null when nothing is identified, and a failure when something is but the
+ * module has no id (`moduleIdOf`). `packages` tells the kernel transform's hook from other imports.
  */
-export const identify = async (code: string, id: string, parse: Parse, resolve: ResolveNamespace): Promise<Identified | null> => {
+export const identify = async (code: string, id: string | null, parse: Parse, resolve: ResolveNamespace, packages: PackageCopies): Promise<Identified | { readonly failure: string } | null> => {
     const symbols = code.includes("Symbol(");
     const items = mayDeclare.test(code);
     if (!symbols && !items) return null;
     const program = parse(code);
-    const { namespaces, attach } = items ? await localsOf(program, resolve) : { namespaces: new Map<string, Namespace>(), attach: new Set<string>() };
+    const { namespaces, attach } = items ? await localsOf(program, resolve, packages) : { namespaces: new Map<string, Namespace>(), attach: new Set<string>() };
     const found: { readonly value: Expression; readonly binding: string }[] = [];
     const consider = (init: Expression | null | undefined, binding: string): void => {
         if (isSymbolCall(init)) found.push({ value: init, binding });
@@ -143,13 +159,54 @@ export const identify = async (code: string, id: string, parse: Parse, resolve:
             consider(statement.declaration, "default");
         }
     }
-    if (found.length === 0 || declaresInModule(program, "Symbol") || declaresInModule(program, "globalThis")) return null;
-    const identifier = uniqueName(code, "identify$");
+    const labeled = namespaces.size > 0 ? labelsOf(program, namespaces, attach, new Set(found.map(({ value }) => value))) : [];
+    if ((found.length === 0 && labeled.length === 0) || declaresInModule(program, "Symbol") || declaresInModule(program, "globalThis")) return null;
     const insertions: Insertion[] = [];
-    for (const { value, binding } of found) {
-        insertions.push({ at: value.start, text: `${identifier}(` }, { at: value.end, text: `, ${JSON.stringify(`${id}#${binding}`)})` });
+    if (found.length > 0) {
+        if (id === null) return { failure: "this module's keys and systems need ids, which name its package, but no package.json above it gives a name: give its package one" };
+        const identifier = uniqueName(code, "identify$");
+        for (const { value, binding } of found) {
+            insertions.push({ at: value.start, text: `${identifier}(` }, { at: value.end, text: `, ${JSON.stringify(`${id}#${binding}`)})` });
+        }
+        const ids = JSON.stringify(idsName);
+        insertions.push({ at: code.length, text: `\nfunction ${identifier}(value, id) { const ids = Symbol.for(${ids}); (globalThis[ids] || (globalThis[ids] = new Map())).set(value, id); return value; }\n` });
     }
-    const ids = JSON.stringify(idsName);
-    insertions.push({ at: code.length, text: `\nfunction ${identifier}(value, id) { const ids = Symbol.for(${ids}); (globalThis[ids] || (globalThis[ids] = new Map())).set(value, id); return value; }\n` });
-    return insertInto(code, insertions, id);
+    if (labeled.length > 0) {
+        const identifier = uniqueName(code, "label$");
+        for (const { value, label } of labeled) insertions.push({ at: value.start, text: `${identifier}(` }, { at: value.end, text: `, ${JSON.stringify(label)})` });
+        const labels = JSON.stringify(labelsName);
+        // A label already given, as an internal factory gives its own, stands.
+        insertions.push({ at: code.length, text: `\nfunction ${identifier}(value, label) { const labels = Symbol.for(${labels}); const map = globalThis[labels] || (globalThis[labels] = new WeakMap()); if (!map.has(value)) map.set(value, label); return value; }\n` });
+    }
+    return insertInto(code, insertions, id ?? "");
+};
+
+/** The name a node gives what's declared in it: a variable's, a function's, a property's or a method's. */
+const nameIn = (node: Node): string | null => {
+    switch (node.type) {
+        case "VariableDeclarator": return node.id.type === "Identifier" ? node.id.name : null;
+        case "FunctionDeclaration": case "FunctionExpression": return node.id?.name ?? null;
+        case "Property": case "MethodDefinition": case "PropertyDefinition": return !node.computed && node.key.type === "Identifier" ? node.key.name : null;
+        case "AssignmentExpression": return node.left.type === "Identifier" ? node.left.name : null;
+        default: return null;
+    }
+};
+
+/**
+ * The declarations of constructor calls that `identified` leaves out, each with a label: the name of the nearest
+ * variable, function, property or method it's made in, as `mover` for one made in `const mover = (speed) => ...`.
+ */
+const labelsOf = (program: Program, namespaces: ReadonlyMap<string, Namespace>, attach: ReadonlySet<string>, identified: ReadonlySet<Expression>): readonly { readonly value: Expression; readonly label: string }[] => {
+    const labeled: { readonly value: Expression; readonly label: string }[] = [];
+    const visit = (node: Node, names: readonly string[]): void => {
+        const declaration = declarationOf(node, namespaces, attach);
+        const label = names.at(-1);
+        // Calls in its arguments are labeled too, by the names nearest them.
+        if (declaration !== undefined && !identified.has(declaration) && label !== undefined) labeled.push({ value: declaration, label });
+        const name = nameIn(node);
+        const inner = name === null ? names : [...names, name];
+        for (const child of children(node)) visit(child, inner);
+    };
+    visit(program, []);
+    return labeled;
 };

package/src/implementation/compiler/index.ts

@@ -1 +1,6 @@
-export * from './plugin.js';
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * The build plugin, which every application and library using the ECS builds with.
+ * @module @adobe/ecs/compiler
+ */
+export { Compiler } from './compiler.js';

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

@@ -0,0 +1,32 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, test } from "vitest";
+import { parseAst } from "vite";
+import type { ObjectExpression } from "estree";
+import { estreeOf } from "./estree.js";
+import { resolvedDeclaration } from "./inferred.js";
+
+/** The declaration written as `source`, an object literal. */
+const declarationOf = (source: string): ObjectExpression => {
+    const statement = estreeOf(parseAst(`(${source});`)).body[0];
+    if (statement?.type !== "ExpressionStatement" || statement.expression.type !== "ObjectExpression") throw new Error("not an object literal");
+    return statement.expression;
+};
+
+/** The names a resolved declaration's lookup `name` reads, or null without a `read` list. */
+const readOf = (declaration: ObjectExpression, name: string): readonly string[] | null => {
+    const field = (object: ObjectExpression, key: string) => object.properties.find(property =>
+        property.type === "Property" && property.key.type === "Identifier" && property.key.name === key);
+    const lookup = field(declaration, "lookup");
+    const entry = lookup?.type === "Property" && lookup.value.type === "ObjectExpression" ? field(lookup.value, name) : undefined;
+    const read = entry?.type === "Property" && entry.value.type === "ObjectExpression" ? field(entry.value, "read") : undefined;
+    if (read?.type !== "Property" || read.value.type !== "ArrayExpression") return null;
+    return read.value.elements.map(element => element?.type === "Identifier" ? element.name : "?");
+};
+
+describe("resolvedDeclaration", () => {
+    test("takes a lookup by entity whose rows the build didn't follow as reading all it requires", () => {
+        const declaration = declarationOf("{ lookup: { targets: { with: [mass, position] } } }");
+        const resolved = resolvedDeclaration(declaration, { query: null, resources: null, lookups: new Map([["targets", null]]), up: null });
+        expect(readOf(resolved, "targets")).toEqual(["mass", "position"]);
+    });
+});