@adobe/ecs 0.1.0 → 0.2.1

package/src/implementation/compiler/memory-compiler.ts

@@ -0,0 +1,307 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { reductionsIn, registeredReductionsIn, registeredSharedIn, sharedIn, type AugmentationHost } from './augmentations.js';
+import { estreeOf } from './estree.js';
+import { describeSystems, type DescribedSystem } from './describe.js';
+import { describeFailure } from './failure.js';
+import { identify, moduleIdOf, moduleLabelOf, type PackageOf } from './identify.js';
+import type { InputHost } from './input-schemas.js';
+import { createLinker, type LinkHost } from './link.js';
+import { locateIn } from './module-scope.js';
+import { createPackageCopies, type PackageCopies } from './package-copies.js';
+import { inputPass, mayHaveInput } from './passes.js';
+import * as posix from './posix.js';
+import { locateThroughMap } from './source-map.js';
+import { transformKernels, type KernelUrl } from './transform.js';
+import type { TypedProgram } from './type-schemas.js';
+
+/**
+ * The compiler's core without node or a bundler: a module compiled as the plugin compiles it (`plugin.ts`), its
+ * imports resolved among files held in memory. A browser runs it with a parser and a type stripper of its own that give
+ * what the bundler's do.
+ */
+
+/** Parses a module as the bundler's `parseAst` does: JavaScript, or TypeScript with its types. */
+export type ParseModule = (code: string, options: { readonly lang: "js" | "ts" | "tsx" }, file?: string) => TypedProgram;
+
+/** Strips a TypeScript module's types as the bundler does: its JavaScript and the mappings of its map back. */
+export type StripTypes = (code: string, file: string, lang: "ts" | "tsx") => { readonly code: string; readonly mappings: string } | { readonly error: string; readonly position?: number };
+
+export type MemoryHost = {
+    /** Every file by its absolute path: packages, with their package.json files, and modules the compiled ones import. */
+    readonly files: ReadonlyMap<string, string>;
+    readonly parse: ParseModule;
+    readonly strip: StripTypes;
+    /** The root of the copy of the package the compiled code runs with, as installed: its `dist` is what it imports. */
+    readonly packageRoot: string;
+};
+
+/** Where a failure is in the module compiled, counted from 1. */
+export type Location = { readonly line: number; readonly column: number };
+
+/**
+ * A system of the module compiled (`describe.ts`), located in the source: its `System.create` or `System.render` call's
+ * start and end offsets, and the line and column of its start, counted from 1.
+ */
+export type SystemDescription = DescribedSystem & Location;
+
+/**
+ * A module compiled: its code, each kernel's module, the build's warnings, and when asked what each system compiled
+ * to; or why it failed, located in the source when the build can tell where.
+ */
+export type MemoryCompiled =
+    | { readonly code: string; readonly kernels: readonly string[]; readonly warnings: readonly string[]; readonly systems?: readonly SystemDescription[] }
+    | { readonly failure: string; readonly location: Location | null };
+
+export type MemoryCompiler = {
+    /**
+     * Compiles `code` as the module at `file`, its kernels' modules at the urls `kernelUrl` gives; with `describe`, also
+     * describes each system, which costs more compiling.
+     */
+    readonly compile: (file: string, code: string, kernelUrl: KernelUrl, options?: { readonly describe?: boolean }) => Promise<MemoryCompiled>;
+};
+
+
+/** The language a file's extension gives its module, null for a file that isn't one. */
+const languageOf = (file: string): "js" | "ts" | "tsx" | null =>
+    /\.[cm]?ts$/.test(file) ? "ts" : file.endsWith(".tsx") ? "tsx" : /\.([cm]?js|jsx)$/.test(file) ? "js" : null;
+
+/** A failure's position in the code it was found in, at the line and column of the source the maps lead back to. */
+type Locate = (offset: number) => Location;
+
+/** Locates through `locate`, into the code before, and on through `earlier`, that code's own locator. */
+const through = (locate: Locate, earlier: { readonly code: string; readonly locate: Locate }): Locate => {
+    const starts = [0];
+    for (let index = earlier.code.indexOf("\n"); index >= 0; index = earlier.code.indexOf("\n", index + 1)) starts.push(index + 1);
+    return offset => {
+        const { line, column } = locate(offset);
+        return earlier.locate((starts[line - 1] ?? 0) + column - 1);
+    };
+};
+
+export const createMemoryCompiler = (host: MemoryHost): MemoryCompiler => {
+    const { parse } = host;
+    /** The code each module was last compiled from, which its compile reads in place of its file's. */
+    const compiled = new Map<string, string>();
+    const files = {
+        get: (file: string): string | undefined => compiled.get(file) ?? host.files.get(file),
+        has: (file: string): boolean => compiled.has(file) || host.files.has(file),
+    };
+    const read = (file: string): string => {
+        const text = files.get(file);
+        if (text === undefined) throw new Error(`${file} doesn't exist`);
+        return text;
+    };
+    const packages: PackageCopies = createPackageCopies({
+        read,
+        exists: file => files.has(file),
+        realpath: path => path,
+        dirname: posix.dirname,
+        extname: posix.extname,
+        isAbsolute: posix.isAbsolute,
+        ownRoot: host.packageRoot,
+        ownModule: `${host.packageRoot}/dist/implementation/compiler/memory-compiler.js`,
+    });
+
+    /** The name and version each directory's package.json gives, as the plugin reads them. */
+    const found = new Map<string, ReturnType<PackageOf>>();
+    const packageOf: PackageOf = directory => {
+        if (found.has(directory)) return found.get(directory);
+        let entry: ReturnType<PackageOf>;
+        try {
+            const json: unknown = JSON.parse(read(`${directory}/package.json`));
+            const name: unknown = typeof json === "object" && json !== null ? Reflect.get(json, "name") : undefined;
+            const version: unknown = typeof json === "object" && json !== null ? Reflect.get(json, "version") : undefined;
+            entry = typeof name !== "string" || name === "" ? null : typeof version === "string" && version !== "" ? { name, version } : { name };
+        }
+        catch {
+            // No package.json here, or none that parses.
+            entry = undefined;
+        }
+        found.set(directory, entry);
+        return entry;
+    };
+
+    /** A file, or the file a path without its extension names, as the bundler finds a TypeScript importer's imports. */
+    const fileAt = (path: string): string | null => {
+        if (files.has(path)) return path;
+        const typescript = path.replace(/\.([cm]?)js$/, ".$1ts");
+        if (typescript !== path && files.has(typescript)) return typescript;
+        for (const extension of [".ts", ".js", "/index.ts", "/index.js"]) if (files.has(`${path}${extension}`)) return `${path}${extension}`;
+        return null;
+    };
+
+    /** The target a package.json's `exports` gives a subpath, under the conditions the bundler resolves imports with. */
+    const exported = (exports: unknown, subpath: string): string | null => {
+        const entry: unknown = typeof exports === "string" ? (subpath === "." ? exports : null)
+            : typeof exports === "object" && exports !== null ? Reflect.get(exports, subpath) : null;
+        const pick = (value: unknown): string | null => {
+            if (typeof value === "string") return value;
+            if (typeof value !== "object" || value === null) return null;
+            for (const condition of ["browser", "import", "default"]) {
+                const chosen = pick(Reflect.get(value, condition));
+                if (chosen !== null) return chosen;
+            }
+            return null;
+        };
+        return pick(entry);
+    };
+
+    /** The file an import resolves to: a relative or absolute path, or a package installed above the importer. */
+    const resolveFile = (specifier: string, importer: string): string | null => {
+        if (specifier.startsWith(".") || specifier.startsWith("/")) return fileAt(posix.resolve(posix.dirname(importer), specifier));
+        const parts = specifier.split("/");
+        const name = specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0] ?? specifier;
+        const subpath = specifier === name ? "." : `.${specifier.slice(name.length)}`;
+        for (let directory = posix.dirname(importer); ; directory = posix.dirname(directory)) {
+            const root = `${directory === "/" ? "" : directory}/node_modules/${name}`;
+            const manifest = files.get(`${root}/package.json`);
+            if (manifest !== undefined) {
+                const json: unknown = JSON.parse(manifest);
+                const exports: unknown = typeof json === "object" && json !== null ? Reflect.get(json, "exports") : undefined;
+                const target = exports === undefined ? (subpath === "." ? "index.js" : subpath) : exported(exports, subpath);
+                return target === null ? null : fileAt(posix.resolve(root, target));
+            }
+            if (directory === "/" || directory === ".") return null;
+        }
+    };
+
+    /** A file's code as JavaScript, with types stripped and lines mapped back to the source. */
+    const load: LinkHost["load"] = async file => {
+        const code = files.get(file);
+        if (code === undefined) return { error: `${file} doesn't exist` };
+        const lang = languageOf(file);
+        if (lang === null || lang === "js") return { code };
+        const stripped = host.strip(code, file, lang);
+        if ("error" in stripped) return { error: stripped.error };
+        return { code: stripped.code, locate: locateThroughMap(stripped.code, stripped.mappings) };
+    };
+
+    const noReductions: ReadonlyMap<string, string> = new Map();
+    /** The `reduce` traits a file's declarations give, as the plugin reads them (`reductionsOf` in `plugin.ts`). */
+    const reductions = (file: string): ReadonlyMap<string, string> => {
+        const lang = languageOf(file);
+        const code = files.get(file);
+        if (lang === null || code === undefined || !code.includes("reduce")) return noReductions;
+        if (lang !== "js") return code.includes("declare module") ? reductionsIn(parse(code, { lang }, file)) : noReductions;
+        return registeredReductionsIn(parse(code, { lang }, file));
+    };
+
+    const noShared: ReadonlySet<string> = new Set();
+    /** The components a file declares `shared`, as the plugin reads them (`sharedOfFile` in `plugin.ts`). */
+    const shared = (file: string): ReadonlySet<string> => {
+        const lang = languageOf(file);
+        const code = files.get(file);
+        if (lang === null || code === undefined || !code.includes("shared")) return noShared;
+        if (lang !== "js") return code.includes("declare module") ? sharedIn(parse(code, { lang }, file)) : noShared;
+        return registeredSharedIn(parse(code, { lang }, file));
+    };
+
+    const linker = createLinker({
+        packages,
+        reductions,
+        shared,
+        load,
+        resolve: async (specifier, importer) => resolveFile(specifier, importer) ?? { error: `${specifier} can't be resolved from ${importer}` },
+    }, input => estreeOf(parse(input, { lang: "js" })));
+
+    /** The package's own files' syntax as last parsed, which every module reading the package's types shares. */
+    const parsed = new Map<string, { readonly code: string; readonly program: TypedProgram }>();
+    const typeHost: InputHost & AugmentationHost = {
+        parse: (source, path) => {
+            const known = parsed.get(path);
+            if (known !== undefined && known.code === source) return known.program;
+            const program = parse(source, { lang: path.endsWith("x") ? "tsx" : "ts" }, path);
+            if (packages.packagePathOf(path) !== null) parsed.set(path, { code: source, program });
+            return program;
+        },
+        resolve: async (specifier, importer) => {
+            const path = resolveFile(specifier, importer);
+            return path === null ? null : packages.typesFileOf(path);
+        },
+        load: async file => read(file),
+        packagePath: packages.packagePathOf,
+        isSystem: async (specifier, importer) => {
+            const path = resolveFile(specifier, importer);
+            return path !== null && packages.namespaceCopyOf(path, "System") !== null;
+        },
+    };
+
+    /** A parse error's message and position, as the parsers report them. */
+    const parseFailure = (error: unknown, locate: Locate): MemoryCompiled => {
+        const message = error instanceof Error ? error.message : String(error);
+        const position: unknown = typeof error === "object" && error !== null ? Reflect.get(error, "pos") : undefined;
+        return { failure: message, location: typeof position === "number" ? locate(position) : null };
+    };
+
+    /** Compiles a module, or says why it can't be: a failure the hosts throw is one too. */
+    /** JavaScript printed readably, as the type stripper prints what it strips; as given when it can't. */
+    const format = (code: string): string => {
+        const printed = host.strip(code, "/format.ts", "ts");
+        return "error" in printed ? code : printed.code;
+    };
+
+    const compile = async (file: string, source: string, kernelUrl: KernelUrl, describe: boolean): Promise<MemoryCompiled> => {
+        compiled.set(file, source);
+        linker.forget(file, false);
+        let code = source;
+        let locate: Locate = locateIn(source);
+        const lang = languageOf(file);
+        if (lang === null) return { code: source, kernels: [], warnings: [], ...describe ? { systems: [] } : {} };
+        if (lang !== "js") {
+            if (mayHaveInput(code)) {
+                let pass: Awaited<ReturnType<typeof inputPass>>;
+                try {
+                    pass = await inputPass(code, file, typeHost);
+                } catch (error) {
+                    return parseFailure(error, locate);
+                }
+                if (pass.result !== null && "failure" in pass.result) return { failure: describeFailure(pass.result.failure), location: locate(pass.result.failure.position) };
+                if (pass.result !== null) {
+                    locate = through(locateThroughMap(pass.result.code, pass.result.map.mappings), { code, locate });
+                    code = pass.result.code;
+                }
+            }
+            const stripped = host.strip(code, file, lang);
+            if ("error" in stripped) return { failure: stripped.error, location: stripped.position === undefined ? null : locate(stripped.position) };
+            locate = through(locateThroughMap(stripped.code, stripped.mappings), { code, locate });
+            code = stripped.code;
+        }
+        const parseJs = (input: string) => estreeOf(parse(input, { lang: "js" }));
+        let transformed: Awaited<ReturnType<typeof transformKernels>>;
+        let described: readonly DescribedSystem[] = [];
+        try {
+            transformed = await transformKernels(code, file, parseJs, async (specifier, namespace) => {
+                const path = resolveFile(specifier, file);
+                return path === null ? null : packages.namespaceCopyOf(path, namespace);
+            }, kernelUrl, linker, true, moduleLabelOf(file, packageOf), undefined, describe ? async sites => { described = await describeSystems(sites, format); } : undefined);
+        } catch (error) {
+            return parseFailure(error, locate);
+        }
+        if (transformed !== null && "failure" in transformed) return { failure: describeFailure(transformed.failure), location: locate(transformed.failure.position) };
+        const kernelCode = transformed?.code ?? code;
+        const identified = await identify(kernelCode, moduleIdOf(file, packageOf), parseJs, async (specifier, namespace) => {
+            const path = resolveFile(specifier, file);
+            return path !== null && packages.namespaceCopyOf(path, namespace) !== null;
+        }, packages);
+        if (identified !== null && "failure" in identified) return { failure: identified.failure, location: null };
+        const result = { code: identified?.code ?? kernelCode, kernels: transformed?.kernels ?? [], warnings: transformed?.warnings ?? [] };
+        if (!describe) return result;
+        const starts = [0];
+        for (let index = source.indexOf("\n"); index >= 0; index = source.indexOf("\n", index + 1)) starts.push(index + 1);
+        const offsetOf = ({ line, column }: Location): number => (starts[line - 1] ?? 0) + column - 1;
+        const systems = described.map((system): SystemDescription => {
+            const at = locate(system.start);
+            return { ...system, ...at, start: offsetOf(at), end: offsetOf(locate(system.end - 1)) + 1 };
+        });
+        return { ...result, systems };
+    };
+    return {
+        compile: async (file, source, kernelUrl, options) => {
+            try {
+                return await compile(file, source, kernelUrl, options?.describe === true);
+            } catch (error) {
+                return { failure: `The compiler failed: ${error instanceof Error ? error.message : String(error)}`, location: null };
+            }
+        },
+    };
+};

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

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Directive, Expression, FunctionDeclaration, MaybeNamedFunctionDeclaration, ModuleDeclaration, Pattern, Program, Statement } from 'estree';
 import { patternNames } from './estree.js';
 

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

@@ -1,9 +1,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Expression as SourceExpression, Node } from 'estree';
 import type { Program } from '../world/kernel.js';
 import { isValueType } from '../world/intrinsics.js';
 import { fail, within, type Frame } from './failure.js';
 import { resolveBinding, type Resolved } from './link.js';
-import { isIntrinsicModule } from './paths.js';
 import type { Module, ModuleBinding } from './module-scope.js';
 import type { Out } from './out.js';
 import { rootScope, type Scope } from './scope.js';
@@ -12,7 +12,7 @@ import type { Value } from './value.js';
 /** Whether `name` is one of the kernel's component or resource keys. */
 export const isKey = (scope: Scope, name: string): boolean => {
     const signature = scope.unit.signature;
-    return signature.read.has(name) || signature.write.has(name) || signature.resources.includes(name)
+    return signature.read.has(name) || signature.write.has(name) || signature.has.has(name) || signature.resources.includes(name)
         || signature.lookups.some(lookup => lookup.read.includes(name));
 };
 
@@ -62,7 +62,7 @@ const intrinsicDefinition = (init: SourceExpression, module: Module, scope: Scop
     const binding = module.bindings.get(init.callee.name);
     if (binding?.kind !== "import") return null;
     const resolved = resolveBinding(link, module, init.callee.name, binding);
-    if (resolved.kind !== "binding" || resolved.name !== "intrinsic" || !isIntrinsicModule(resolved.module.file)) return null;
+    if (resolved.kind !== "binding" || resolved.name !== "intrinsic" || !link.packages.isIntrinsicModule(resolved.module.file)) return null;
     const [declaration, implementation] = init.arguments;
     if (declaration === undefined || declaration.type === "SpreadElement" || implementation === undefined || implementation.type === "SpreadElement") {
         return fail(init, "intrinsic takes a declaration and an implementation");
@@ -70,6 +70,16 @@ const intrinsicDefinition = (init: SourceExpression, module: Module, scope: Scop
     return { implementation, intrinsic: intrinsicDeclaration(declaration) };
 };
 
+/** Whether a value holds data rather than only functions and namespaces. */
+const holdsData = (value: Value): boolean => {
+    switch (value.kind) {
+        case "tuple": return value.items.some(holdsData);
+        case "struct": return value.fields.some(([, field]) => holdsData(field));
+        case "function": case "namespace": case "method": return false;
+        default: return true;
+    }
+};
+
 /** A definition in `module`: a function to inline, or a constant compiled in its own module. */
 const definition = (node: Node, name: string, binding: ModuleBinding, module: Module, scope: Scope, out: Out): Value => {
     const unit = scope.unit;
@@ -93,6 +103,11 @@ const definition = (node: Node, name: string, binding: ModuleBinding, module: Mo
             const compile = (): Value => unit.expression(init, rootScope(unit, true, module), out);
             const value = module === unit.module ? compile() : within(node, frameIn(module, display), compile);
             unit.active.delete(identity);
+            // An object or array holding data may be written after the build, whatever made it, and a kernel would have
+            // inlined it; a primitive const can't change, and the interface's own objects are fixed.
+            if (unit.tried && value.kind !== "scalar" && holdsData(value) && unit.packages?.packagePathOf(module.file)?.startsWith("interface/") !== true) {
+                return fail(node, `${display} holds values that may change, which a kernel would inline`);
+            }
             return value;
         }
         case "import": case "importNamespace":

package/src/implementation/compiler/out.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Statement } from './ir.js';
 
 /** Emitted statements. A function is resolved last, so it can see what the rest of the body needed. */

package/src/implementation/compiler/oxc.test-helper.ts

@@ -0,0 +1,20 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/// <reference types="node" />
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { instantiate as instantiateParser } from '@oxc-parser/binding-wasm32-wasip1/workerd';
+import { instantiate as instantiateTransformer } from '@oxc-transform/binding-wasm32-wasip1/workerd';
+import { oxcParse, oxcStrip } from './oxc.js';
+
+const require = createRequire(import.meta.url);
+
+type WasmHost = { readonly parse: ReturnType<typeof oxcParse>; readonly strip: ReturnType<typeof oxcStrip> };
+
+/** Each binding instantiates once per thread. */
+let loading: Promise<WasmHost> | null = null;
+
+/** The memory compiler's parser and type stripper over oxc's WASM bindings, as a browser loads them, in node. */
+export const wasmHost = (): Promise<WasmHost> => loading ??= Promise.all([
+    readFile(require.resolve("@oxc-parser/binding-wasm32-wasip1/wasm")).then(bytes => WebAssembly.compile(bytes)).then(instantiateParser),
+    readFile(require.resolve("@oxc-transform/binding-wasm32-wasip1/wasm")).then(bytes => WebAssembly.compile(bytes)).then(instantiateTransformer),
+]).then(([parser, transformer]) => ({ parse: oxcParse(parser), strip: oxcStrip(transformer) }));

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

@@ -0,0 +1,69 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/// <reference types="node" />
+import { readdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { expect, test } from 'vitest';
+import { parseAst, transformWithOxc } from 'vite';
+import { wasmHost } from './oxc.test-helper.js';
+
+const root = fileURLToPath(new URL("../../..", import.meta.url));
+const filesIn = (folder: string, extension: string): readonly string[] =>
+    readdirSync(`${root}${folder}`, { recursive: true, encoding: "utf8" }).filter(file => file.endsWith(extension)).map(file => `${root}${folder}/${file}`);
+
+/** A program as JSON, its BigInt and RegExp values written out. */
+const json = (value: unknown): string => JSON.stringify(value, (_key, item: unknown) => typeof item === "bigint" ? `${item}n` : item instanceof RegExp ? String(item) : item);
+
+test("oxc's WASM parser gives the programs the bundler's parseAst does, for every source and built module of the package", async () => {
+    const host = await wasmHost();
+    const files = [...filesIn("src", ".ts"), ...filesIn("dist", ".js")];
+    expect(files.length).toBeGreaterThan(1000);
+    for (const file of files) {
+        const code = readFileSync(file, "utf8");
+        const options = { lang: file.endsWith(".ts") ? "ts" : "js" } as const;
+        expect(json(host.parse(code, options, file)), file).toBe(json(parseAst(code, options, file)));
+    }
+}, 120000);
+
+test("oxc's WASM transformer strips types to the JavaScript the bundler's does, which parses alike", async () => {
+    const host = await wasmHost();
+    for (const file of filesIn("src", ".ts")) {
+        const code = readFileSync(file, "utf8");
+        const stripped = host.strip(code, file, "ts");
+        const expected = await transformWithOxc(code, file, { lang: "ts", sourcemap: true });
+        expect("code" in stripped ? stripped.code : stripped.error, file).toBe(expected.code);
+        if ("code" in stripped) expect(json(host.parse(stripped.code, { lang: "js" })), file).toBe(json(parseAst(expected.code)));
+    }
+}, 120000);
+
+test("a parse failure throws as the bundler's does, at its position", async () => {
+    const host = await wasmHost();
+    const code = "const a = ;";
+    const thrown = (parse: () => unknown): unknown => {
+        try {
+            parse();
+        } catch (error) {
+            return error;
+        }
+        return null;
+    };
+    const ours = thrown(() => host.parse(code, { lang: "ts" }));
+    const theirs = thrown(() => parseAst(code, { lang: "ts" }));
+    expect(ours).toBeInstanceOf(Error);
+    expect(Reflect.get(Object(ours), "pos")).toBe(Reflect.get(Object(theirs), "pos"));
+    expect(String(Reflect.get(Object(ours), "message")).split("\n")[0]).toBe(String(Reflect.get(Object(theirs), "message")).split("\n")[0]);
+    expect(host.strip(code, "broken.ts", "ts")).toMatchObject({ position: 10 });
+});
+
+test("a failure after text beyond ASCII is at its place in the code, as the parser counts it, not in UTF-8 bytes", async () => {
+    const host = await wasmHost();
+    const code = "// résumé — naïve 😀\nconst a: = 1;";
+    const at = code.indexOf("= 1");
+    expect(host.strip(code, "text.ts", "ts")).toMatchObject({ position: at });
+    let position: unknown = null;
+    try {
+        host.parse(code, { lang: "ts" });
+    } catch (error) {
+        position = Reflect.get(Object(error), "pos");
+    }
+    expect(position).toBe(at);
+});

package/src/implementation/compiler/oxc.ts

@@ -0,0 +1,90 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { ParseModule, StripTypes } from './memory-compiler.js';
+import type { TypedProgram } from './type-schemas.js';
+
+/** An error oxc reports, by the fields read here. */
+type OxcError = { readonly message: string; readonly labels: readonly { readonly start: number }[] };
+
+/** What oxc's parser binding gives: its parse, with the program as ESTree JSON, as its WASM build exports it too. */
+export type OxcParser = {
+    readonly parseSync: (filename: string, source: string, options: { readonly lang: "js" | "ts" | "tsx"; readonly preserveParens: boolean }) => { readonly program: unknown; readonly errors: readonly OxcError[] };
+};
+
+/** What oxc's transformer binding gives, by the fields read here. */
+export type OxcTransformer = {
+    readonly transformSync: (filename: string, source: string, options: { readonly lang: "js" | "ts" | "tsx"; readonly sourcemap: boolean }) => {
+        readonly code: string; readonly map?: { readonly mappings: string }; readonly errors: readonly OxcError[];
+    };
+};
+
+/** Whether a value is a program as the parser gives one, by the fields every program has. */
+const isProgram = (value: unknown): value is TypedProgram =>
+    typeof value === "object" && value !== null && Reflect.get(value, "type") === "Program" && Array.isArray(Reflect.get(value, "body"));
+
+/** A literal's value JSON can't hold: a BigInt's, or a regular expression's, at a path the parser lists. */
+const fixLiteral = (program: TypedProgram, path: readonly (string | number)[]): void => {
+    let node: unknown = program;
+    for (const key of path) node = typeof node === "object" && node !== null ? Reflect.get(node, key) : undefined;
+    if (typeof node !== "object" || node === null) return;
+    const bigint: unknown = Reflect.get(node, "bigint");
+    if (typeof bigint === "string") {
+        Reflect.set(node, "value", BigInt(bigint));
+        return;
+    }
+    const regex: unknown = Reflect.get(node, "regex");
+    if (typeof regex !== "object" || regex === null) return;
+    try {
+        Reflect.set(node, "value", new RegExp(String(Reflect.get(regex, "pattern")), String(Reflect.get(regex, "flags"))));
+    } catch {
+        // A pattern this engine can't compile keeps no value, as the bundler's parser leaves it.
+    }
+};
+
+/** A parse failure as the bundler's `parseAst` throws one: its errors' messages, at the first one's position. */
+const parseError = (errors: readonly OxcError[]): Error => {
+    const error = new Error(`Parse failed with ${errors.length} error${errors.length < 2 ? "" : "s"}:\n${errors.slice(0, 5).map(item => item.message).join("\n")}`);
+    const position = errors[0]?.labels[0]?.start;
+    if (position !== undefined) Reflect.set(error, "pos", position);
+    return error;
+};
+
+/**
+ * The bundler's `parseAst`, over oxc's parser binding: the same parser, the same options and the same ESTree JSON it
+ * reads back, so a program is the one the plugin reads (`oxc.test.ts`).
+ */
+export const oxcParse = (parser: OxcParser): ParseModule => (code, options, file) => {
+    // A result's fields move out of the binding when read, so each is read once.
+    const { errors, program: text } = parser.parseSync(file ?? "file.js", code, { lang: options.lang, preserveParens: false });
+    if (errors.length > 0) throw parseError(errors);
+    // The binding's declarations type the program as a node, but it's the JSON its wrapper parses.
+    if (typeof text !== "string") throw new Error(`the parser gave no program JSON for ${file ?? "file.js"}`);
+    const parsed: unknown = JSON.parse(text);
+    const program: unknown = typeof parsed === "object" && parsed !== null ? Reflect.get(parsed, "node") : undefined;
+    const fixes: unknown = typeof parsed === "object" && parsed !== null ? Reflect.get(parsed, "fixes") : undefined;
+    if (!isProgram(program)) throw new Error(`the parser gave no program for ${file ?? "file.js"}`);
+    if (Array.isArray(fixes)) for (const path of fixes) if (Array.isArray(path)) fixLiteral(program, path);
+    return program;
+};
+
+/** The offset in a string, counted in UTF-16 code units as JavaScript counts them, of a UTF-8 byte offset in it. */
+export const utf16Offset = (code: string, bytes: number): number => {
+    let counted = 0;
+    for (let index = 0; index < code.length; index++) {
+        if (counted >= bytes) return index;
+        const point = code.codePointAt(index) ?? 0;
+        counted += point < 0x80 ? 1 : point < 0x800 ? 2 : point < 0x10000 ? 3 : 4;
+        // A code point beyond the basic plane takes two code units.
+        if (point >= 0x10000) index++;
+    }
+    return code.length;
+};
+
+/** The bundler's `transformWithOxc` stripping types, over oxc's transformer binding: the same JavaScript (`oxc.test.ts`). */
+export const oxcStrip = (transformer: OxcTransformer): StripTypes => (code, file, lang) => {
+    const { code: stripped, map, errors } = transformer.transformSync(file, code, { lang, sourcemap: true });
+    const [first] = errors;
+    // The transformer's labels count UTF-8 bytes, where the parser's count UTF-16 code units.
+    const start = first?.labels[0]?.start;
+    if (first !== undefined) return { error: `Transform failed: ${first.message}`, position: start === undefined ? undefined : utf16Offset(code, start) };
+    return { code: stripped, mappings: map?.mappings ?? "" };
+};