@teacss/engine 0.8.5-alpha.4 → 0.9.0-alpha.3

package/dist/facade/select.js

@@ -0,0 +1,680 @@
+// Selects the configurations the Rust engine can serve: the first item it cannot translate comes
+// back as `{ ok: false, reason, path }` (v02.9 §4.1); later cards (F7.07-F7.12) append the rest.
+import { readFile } from "node:fs/promises";
+import { CONFIG_ENTRY_PROVENANCE, CONFIG_SOURCE_DECLARATIONS, ENGINE_COMPAT, ENGINE_PACKAGE_VERSION, PRESET_OPTIONS } from "./constants.js";
+import { TeacssEngineError } from "./errors.js";
+export function fail(reason, path) {
+    return { ok: false, reason, path };
+}
+export function ok(value) {
+    return { ok: true, value };
+}
+/**
+ * Port of core/config.ts:48-59: `defaults` underneath, then the user config's own enumerable keys
+ * whose value is not `undefined`. Only string keys are copied (v02.9 §4.4); values are defined
+ * rather than assigned so a `__proto__` key stays a plain property.
+ */
+export function mergeDefinedConfig(defaults, userConfig) {
+    const merged = { ...defaults };
+    for (const key of Object.keys(userConfig)) {
+        const value = userConfig[key];
+        if (value === undefined)
+            continue;
+        Object.defineProperty(merged, key, { value, configurable: true, enumerable: true, writable: true });
+    }
+    return merged;
+}
+export const KNOWN_KEYS = new Set([
+    "presets",
+    "shortcuts",
+    "safelist",
+    "blocklist",
+    "theme",
+    "layers",
+    "content",
+    "envMode",
+    "unmatched",
+    "shortcutsLayer",
+    "virtualModulePrefix",
+    "outputToCssLayers",
+    "mergeSelectors",
+    "warn",
+    "details",
+    "separators",
+    "transformers",
+    "extractors",
+    "extractorDefault",
+    "rules",
+    "variants",
+    "preflights",
+    "preprocess",
+    "postprocess",
+    "extendTheme",
+    "configResolved",
+    "autocomplete",
+    "sortLayers",
+    "cli",
+    "engine",
+]);
+/** Keys whose presence with a non-empty value means fallback; `transformers` is checked by name (F7.09). */
+export const DYNAMIC_KEYS = Object.freeze(["rules", "variants", "extractors", "extractorDefault", "preflights", "preprocess", "postprocess", "extendTheme", "configResolved", "autocomplete", "cli"]);
+/** A function, a non-empty array or object, or any other defined non-null value. */
+export function isNonEmpty(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === "function")
+        return true;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === "object")
+        return Object.keys(value).length > 0;
+    return true;
+}
+function isDefaultSeparators(separators) {
+    return Array.isArray(separators) && separators.length === 2 && separators[0] === ":" && separators[1] === "-";
+}
+/**
+ * v02.9 §4.2 step 2: unknown keys, then the dynamic keys in order, then the static options only
+ * the TypeScript engine honours. `engine` is a hook option and its value is not checked here.
+ */
+export function checkTopLevelKeys(merged) {
+    for (const key of Object.keys(merged)) {
+        if (!KNOWN_KEYS.has(key))
+            return fail("unknown-key", key);
+    }
+    for (const key of DYNAMIC_KEYS) {
+        if (isNonEmpty(merged[key]))
+            return fail(key, key);
+    }
+    if (merged.separators !== undefined && !isDefaultSeparators(merged.separators))
+        return fail("separators", "separators");
+    if (merged.mergeSelectors === false)
+        return fail("mergeSelectors", "mergeSelectors");
+    if (merged.details !== undefined)
+        return fail("details", "details");
+    if (merged.sortLayers !== undefined)
+        return fail("sortLayers", "sortLayers");
+    return ok(null);
+}
+const isThenable = (value) => value !== null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+/**
+ * The first own accessor property of `object`. Translation reads every field, so a getter would
+ * run before TS reads it again (presets.test.ts "snapshots an own preset name exactly once"); an
+ * object with accessors falls back without invoking them.
+ */
+export function ownAccessor(object) {
+    for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(object))) {
+        if ("get" in descriptor || "set" in descriptor)
+            return key;
+    }
+    return undefined;
+}
+/**
+ * v02.9 §4.2 step 3: nested presets flattened depth first, deduplicated by name keeping the first
+ * (core/config.ts:26-36 — a missing name is a name too), then ordered pre, normal, post
+ * (config.ts:216-220; any other `enforce` value drops the preset, as there).
+ */
+export function flattenPresets(presetsValue) {
+    const list = presetsValue === undefined ? [] : Array.isArray(presetsValue) ? presetsValue : [presetsValue];
+    const flat = [];
+    const visit = (entry, path, ancestors) => {
+        if (Array.isArray(entry)) {
+            for (let index = 0; index < entry.length; index++) {
+                const failure = visit(entry[index], `${path}[${index}]`, ancestors);
+                if (failure)
+                    return failure;
+            }
+            return undefined;
+        }
+        if (typeof entry === "function" || isThenable(entry) || entry === null || typeof entry !== "object")
+            return fail("preset-not-instantiated", path);
+        if (ancestors.has(entry))
+            return fail("preset-cycle", path);
+        const accessor = ownAccessor(entry);
+        if (accessor !== undefined)
+            return fail("accessor", `${path}.${accessor}`);
+        flat.push(entry);
+        const children = Object.hasOwn(entry, "presets") ? entry.presets : undefined;
+        if (children === undefined)
+            return undefined;
+        const nested = Array.isArray(children) ? children : [children];
+        const nextAncestors = new Set([...ancestors, entry]);
+        for (let index = 0; index < nested.length; index++) {
+            const failure = visit(nested[index], `${path}.presets[${index}]`, nextAncestors);
+            if (failure)
+                return failure;
+        }
+        return undefined;
+    };
+    for (let index = 0; index < list.length; index++) {
+        const failure = visit(list[index], `presets[${index}]`, new Set());
+        if (failure)
+            return failure;
+    }
+    const names = new Set();
+    const unique = flat.filter((preset) => {
+        const name = preset.name;
+        if (names.has(name))
+            return false;
+        names.add(name);
+        return true;
+    });
+    const enforce = (preset) => preset.enforce;
+    return ok([...unique.filter((preset) => enforce(preset) === "pre"), ...unique.filter((preset) => enforce(preset) == null), ...unique.filter((preset) => enforce(preset) === "post")]);
+}
+/** The oracle's `PresetOptions` base (types.ts:53) has no named fields, so these five are Standard's whole option set. */
+export const STANDARD_OPTION_KEYS = new Set(["modeSelectors", "containers", "preflight", "variablePrefix", "compileClass"]);
+export const COMPILE_CLASS_KEYS = ["classPrefix", "alwaysHash", "keepUnknown", "layer"];
+export const ICONS_OPTION_KEYS = ["scale", "mode", "extraProperties", "warn", "layer", "unit"];
+export const BUNDLED_ICON_COLLECTIONS = new Set(["carbon", "crypto", "flagpack", "logo", "lucide"]);
+export const ROLE_PALETTES_PRESET = "@teacss/config/role-palettes";
+export function pick(obj, keys) {
+    const out = {};
+    for (const key of keys)
+        if (obj[key] !== undefined)
+            out[key] = obj[key];
+    return out;
+}
+const markedOptions = (preset, marker) => Object.getOwnPropertyDescriptor(preset, marker)?.value ?? {};
+/**
+ * v02.9 §4.2 step 4, first four items: the marked built-in presets and the role-palettes marker.
+ * `ok(null)` means the preset yields no `PresetSpec`; `undefined` means it is not one of these
+ * (unmarked presets go to F7.08's static translation).
+ * such as `presets[1]`
+ */
+export function translateTaggedPreset(preset, path, ctx) {
+    if (Object.getOwnPropertyDescriptor(preset, PRESET_OPTIONS.standard) !== undefined) {
+        const options = markedOptions(preset, PRESET_OPTIONS.standard);
+        for (const key of Object.keys(options)) {
+            if (!STANDARD_OPTION_KEYS.has(key))
+                return fail("standard.unknown-option", `${path}.options.${key}`);
+        }
+        const compileClass = options.compileClass;
+        if (compileClass !== null && typeof compileClass === "object") {
+            if (Object.hasOwn(compileClass, "hashFn"))
+                return fail("standard.compileClass.hashFn", `${path}.options.compileClass.hashFn`);
+            if (Object.hasOwn(compileClass, "trigger"))
+                return fail("standard.compileClass.trigger", `${path}.options.compileClass.trigger`);
+        }
+        const spec = { kind: "standard", options: pick(options, STANDARD_OPTION_KEYS) };
+        if (compileClass !== null && typeof compileClass === "object")
+            spec.options.compileClass = pick(compileClass, COMPILE_CLASS_KEYS);
+        return ok(spec);
+    }
+    if (Object.getOwnPropertyDescriptor(preset, PRESET_OPTIONS.icons) !== undefined) {
+        const options = markedOptions(preset, PRESET_OPTIONS.icons);
+        const collections = Object.keys(options.collections ?? {});
+        for (const key of collections) {
+            if (!BUNDLED_ICON_COLLECTIONS.has(key))
+                return fail("icons.collections", `${path}.options.collections.${key}`);
+        }
+        if (isNonEmpty(options.customizations))
+            return fail("icons.customizations", `${path}.options.customizations`);
+        if (options.processor !== undefined)
+            return fail("icons.processor", `${path}.options.processor`);
+        const spec = { kind: "icons", options: pick(options, ICONS_OPTION_KEYS) };
+        if (options.collections !== undefined)
+            spec.options.collections = collections;
+        return ok(spec);
+    }
+    if (Object.getOwnPropertyDescriptor(preset, PRESET_OPTIONS.official) !== undefined)
+        return ok({ kind: "official" });
+    if (preset.name === ROLE_PALETTES_PRESET)
+        return ctx.hasEntry ? ok(null) : fail("role-palettes-without-entry", path);
+    return undefined;
+}
+/** Keys of an unmarked preset whose non-empty value means fallback. */
+export const PRESET_DYNAMIC_KEYS = Object.freeze(["rules", "variants", "extractors", "preflights", "preprocess", "postprocess", "extendTheme", "configResolved", "transformers", "autocomplete", "extractorDefault", "content"]);
+const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** Values `undefined` are left out. */
+const defined = (entries) => Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined));
+/**
+ * v02.9 §4.5: the static shortcut forms as `[name, expansion]` pairs. A shortcut meta (`[n, e, meta]`)
+ * has no place in `StaticPreset.shortcuts`, so any meta key falls back.
+ *
+ */
+export function translateShortcuts(value, path, reasonOnFail) {
+    if (value === undefined)
+        return ok(undefined);
+    const pairs = [];
+    const fromObject = (object, objectPath) => {
+        for (const [key, expansion] of Object.entries(object)) {
+            if (typeof expansion !== "string")
+                return fail(reasonOnFail, `${objectPath}.${key}`);
+            pairs.push([key, expansion]);
+        }
+        return undefined;
+    };
+    if (isPlainObject(value)) {
+        const failure = fromObject(value, path);
+        if (failure)
+            return failure;
+    }
+    else if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index++) {
+            const item = value[index];
+            const itemPath = `${path}[${index}]`;
+            if (Array.isArray(item)) {
+                if (typeof item[0] !== "string" || typeof item[1] !== "string")
+                    return fail(reasonOnFail, itemPath);
+                if (item.length > 2 && item[2] !== undefined) {
+                    const meta = item[2];
+                    if (!isPlainObject(meta))
+                        return fail(reasonOnFail, `${itemPath}[2]`);
+                    const key = Object.keys(meta)[0];
+                    if (key !== undefined)
+                        return fail(reasonOnFail, `${itemPath}[2].${key}`);
+                }
+                pairs.push([item[0], item[1]]);
+            }
+            else if (isPlainObject(item)) {
+                const failure = fromObject(item, itemPath);
+                if (failure)
+                    return failure;
+            }
+            else {
+                return fail(reasonOnFail, itemPath);
+            }
+        }
+    }
+    else {
+        return fail(reasonOnFail, path);
+    }
+    return ok(pairs.length > 0 ? pairs : undefined);
+}
+/**
+ * v02.9 §4.5: a theme as dotted keys to string leaves (numbers stringified); empty objects vanish.
+ *
+ */
+export function flattenTheme(theme, path, reasonOnFail) {
+    if (theme === undefined)
+        return ok(undefined);
+    if (!isPlainObject(theme))
+        return fail(reasonOnFail, path);
+    // The removed `rolePalettes` theme key is an error in TS (role-palette-snapshot.test.ts).
+    const modes = isPlainObject(theme.modes) ? Object.entries(theme.modes) : [];
+    if (Object.hasOwn(theme, "rolePalettes"))
+        return fail(reasonOnFail, `${path}.rolePalettes`);
+    for (const [mode, values] of modes) {
+        if (isPlainObject(values) && Object.hasOwn(values, "rolePalettes"))
+            return fail(reasonOnFail, `${path}.modes.${mode}.rolePalettes`);
+    }
+    const flat = {};
+    const visit = (object, prefix) => {
+        for (const [key, value] of Object.entries(object)) {
+            const dotted = prefix ? `${prefix}.${key}` : key;
+            if (typeof value === "string")
+                flat[dotted] = value;
+            else if (typeof value === "number")
+                flat[dotted] = String(value);
+            else if (isPlainObject(value)) {
+                const failure = visit(value, dotted);
+                if (failure)
+                    return failure;
+            }
+            else
+                return fail(reasonOnFail, `${path}.${dotted}`);
+        }
+        return undefined;
+    };
+    const failure = visit(theme, "");
+    if (failure)
+        return failure;
+    return ok(Object.keys(flat).length > 0 ? flat : undefined);
+}
+export function translateStringList(list, path, reasonOnFail) {
+    if (list === undefined)
+        return ok(undefined);
+    if (!Array.isArray(list))
+        return fail(reasonOnFail, path);
+    for (let index = 0; index < list.length; index++) {
+        if (typeof list[index] !== "string")
+            return fail(reasonOnFail, `${path}[${index}]`);
+    }
+    return ok(list.length > 0 ? [...list] : undefined);
+}
+export function translateLayers(layers, path, reasonOnFail) {
+    if (layers === undefined)
+        return ok(undefined);
+    if (!isPlainObject(layers))
+        return fail(reasonOnFail, path);
+    for (const [key, order] of Object.entries(layers)) {
+        if (typeof order !== "number")
+            return fail(reasonOnFail, `${path}.${key}`);
+    }
+    return ok({ ...layers });
+}
+/**
+ * v02.9 §4.2 step 4, "other objects": an unmarked preset as a `StaticPreset`.
+ */
+export function translateStaticPreset(preset, path) {
+    if (typeof preset.name !== "string")
+        return fail("preset.name", `${path}.name`);
+    for (const key of PRESET_DYNAMIC_KEYS) {
+        if (isNonEmpty(preset[key]))
+            return fail(`preset.${key}`, `${path}.${key}`);
+    }
+    const shortcuts = translateShortcuts(preset.shortcuts, `${path}.shortcuts`, "preset.shortcuts");
+    if (!shortcuts.ok)
+        return shortcuts;
+    const safelist = translateStringList(preset.safelist, `${path}.safelist`, "preset.safelist");
+    if (!safelist.ok)
+        return safelist;
+    const blocklist = translateStringList(preset.blocklist, `${path}.blocklist`, "preset.blocklist");
+    if (!blocklist.ok)
+        return blocklist;
+    const theme = flattenTheme(preset.theme, `${path}.theme`, "preset.theme");
+    if (!theme.ok)
+        return theme;
+    const layers = translateLayers(preset.layers, `${path}.layers`, "preset.layers");
+    if (!layers.ok)
+        return layers;
+    if (preset.enforce !== undefined && preset.enforce !== "pre" && preset.enforce !== "post")
+        return fail("preset.enforce", `${path}.enforce`);
+    if (preset.layer !== undefined && typeof preset.layer !== "string")
+        return fail("preset.layer", `${path}.layer`);
+    return ok({
+        kind: "static",
+        preset: defined({ name: preset.name, enforce: preset.enforce, layer: preset.layer, layers: layers.value, shortcuts: shortcuts.value, safelist: safelist.value, blocklist: blocklist.value, theme: theme.value }),
+    });
+}
+/**
+ * v02.9 §4.2 step 5: the merged config's static fields as a `StaticConfig` (possibly empty).
+ */
+export function translateInline(merged) {
+    const shortcuts = translateShortcuts(merged.shortcuts, "shortcuts", "shortcuts");
+    if (!shortcuts.ok)
+        return shortcuts;
+    const safelist = translateStringList(merged.safelist, "safelist", "safelist");
+    if (!safelist.ok)
+        return safelist;
+    const blocklist = translateStringList(merged.blocklist, "blocklist", "blocklist");
+    if (!blocklist.ok)
+        return blocklist;
+    const theme = flattenTheme(merged.theme, "theme", "theme");
+    if (!theme.ok)
+        return theme;
+    const layers = translateLayers(merged.layers, "layers", "layers");
+    if (!layers.ok)
+        return layers;
+    let content;
+    if (merged.content !== undefined) {
+        if (!isPlainObject(merged.content))
+            return fail("content", "content");
+        if (Object.hasOwn(merged.content, "pipeline") && merged.content.pipeline !== undefined)
+            return fail("content.pipeline", "content.pipeline");
+        if (isNonEmpty(merged.content.inline))
+            return fail("content.inline", "content.inline");
+        const filesystem = merged.content.filesystem;
+        if (filesystem !== undefined) {
+            if (!Array.isArray(filesystem) || filesystem.some((pattern) => typeof pattern !== "string"))
+                return fail("content", "content.filesystem");
+            content = { filesystem: [...filesystem] };
+        }
+    }
+    return ok(defined({ shortcuts: shortcuts.value, safelist: safelist.value, blocklist: blocklist.value, theme: theme.value, layers: layers.value, content }));
+}
+export const ALLOWED_TRANSFORMER_NAMES = new Set(["@teacss/transformer-compile-class", "@teacss/directives"]);
+/**
+ * v02.2 §4: allow-listed transformers stay with the host (kept in the facade's `config.transformers`)
+ * and never reach Rust; any other name falls back. Repeated names are kept in order; the config view
+ * applies `uniqueNamed` later (F7.20). `@teacss/directives` options live in its closure and are
+ * checked per call (v02.9 §6.3), so none are read here.
+ */
+export function translateTransformers(list) {
+    if (list === undefined || list === null)
+        return ok([]);
+    if (!Array.isArray(list))
+        return fail("transformers", "transformers");
+    const kept = [];
+    for (let index = 0; index < list.length; index++) {
+        const transformer = list[index];
+        if (!transformer || typeof transformer !== "object" || typeof transformer.name !== "string" || !ALLOWED_TRANSFORMER_NAMES.has(transformer.name)) {
+            return fail("transformers", `transformers[${index}]`);
+        }
+        kept.push(transformer);
+    }
+    return ok(kept);
+}
+export const scanners = {
+    load: null,
+};
+async function loadScanner() {
+    if (scanners.load)
+        return scanners.load();
+    // biome-ignore lint/suspicious/noTsIgnore: the optional peer may or may not be installed
+    // @ts-ignore optional peer: @teacss/config may be absent at compile time
+    return import("@teacss/config/internal/source-scan");
+}
+/**
+ * Entry source and declaration files (v02.9 §4.4). The symbols are read from `userConfig`, not
+ * `merged`: `mergeDefinedConfig` copies no symbols.
+ */
+export async function resolveEntrySource(userConfig, merged) {
+    const provenance = userConfig[CONFIG_ENTRY_PROVENANCE];
+    const state = userConfig[CONFIG_SOURCE_DECLARATIONS];
+    if (!provenance || typeof provenance.entryFile !== "string")
+        return ok({ root: process.cwd(), entry: null, declarationFiles: [], derivedKeys: [] });
+    const root = provenance.base;
+    const entry = { path: provenance.entryFile, css: provenance.entryCss ?? null };
+    const derivedKeys = Array.isArray(provenance.derivedKeys) ? [...new Set(provenance.derivedKeys)] : [];
+    let declarationFiles = [];
+    const content = merged.content;
+    if (state?.consumed?.status === "read") {
+        const members = state.consumed.members;
+        // Rust reads declaration files from disk; text resolved from an unsaved override
+        // (`resolveEntryConfig(..., fileContents)`) only the TS engine can serve.
+        for (const member of members) {
+            if (typeof member.contents !== "string")
+                continue;
+            const onDisk = await readFile(member.path, "utf8").catch(() => null);
+            if (onDisk !== member.contents)
+                return fail("declarations-unsaved", member.path);
+        }
+        declarationFiles = members.map((member) => member.path);
+    }
+    else if (content != null && typeof content === "object" && Array.isArray(content.filesystem)) {
+        const filesystem = content.filesystem;
+        const includes = filesystem.filter((glob) => !glob.startsWith("!"));
+        const excludes = filesystem.filter((glob) => glob.startsWith("!")).map((glob) => glob.slice(1));
+        let files;
+        try {
+            const { scanSourceFiles } = await loadScanner();
+            files = await scanSourceFiles(includes, { cwd: root, ignore: excludes, expandDirectories: false });
+        }
+        catch {
+            return fail("declarations-unavailable", "content.filesystem");
+        }
+        declarationFiles = files.filter((file) => file.endsWith(".css") && file !== entry.path).sort();
+    }
+    return ok({ root, entry, declarationFiles, derivedKeys });
+}
+const ENV_MODES = new Set(["dev", "build"]);
+const UNMATCHED_MODES = new Set(["warn", "error", "off"]);
+function translateScalars(merged) {
+    const envMode = merged.envMode ?? "build";
+    if (!ENV_MODES.has(envMode))
+        return fail("envMode", "envMode");
+    const unmatched = merged.unmatched ?? "off";
+    if (!UNMATCHED_MODES.has(unmatched))
+        return fail("unmatched", "unmatched");
+    const layers = merged.outputToCssLayers;
+    let outputToCssLayers;
+    if (layers === undefined)
+        outputToCssLayers = null;
+    else if (typeof layers === "boolean")
+        outputToCssLayers = layers;
+    else if (isPlainObject(layers)) {
+        if (Object.hasOwn(layers, "cssLayerName") && layers.cssLayerName !== undefined)
+            return fail("outputToCssLayers.cssLayerName", "outputToCssLayers.cssLayerName");
+        outputToCssLayers = { allLayers: Boolean(layers.allLayers) };
+    }
+    else
+        return fail("outputToCssLayers", "outputToCssLayers");
+    return ok({
+        envMode,
+        unmatched,
+        outputToCssLayers,
+        shortcutsLayer: typeof merged.shortcutsLayer === "string" ? merged.shortcutsLayer : null,
+        virtualModulePrefix: typeof merged.virtualModulePrefix === "string" ? merged.virtualModulePrefix : null,
+    });
+}
+async function translate(userConfig, defaults) {
+    for (const object of [userConfig, defaults]) {
+        const accessor = object !== null && typeof object === "object" ? ownAccessor(object) : undefined;
+        if (accessor !== undefined)
+            return fail("accessor", accessor);
+    }
+    const merged = mergeDefinedConfig(defaults, userConfig);
+    delete merged.engine;
+    const keys = checkTopLevelKeys(merged);
+    if (!keys.ok)
+        return keys;
+    const source = await resolveEntrySource(userConfig, merged);
+    if (!source.ok)
+        return source;
+    const hasEntry = source.value.entry !== null;
+    const flat = flattenPresets(merged.presets);
+    if (!flat.ok)
+        return flat;
+    const presetSpecs = [];
+    for (let index = 0; index < flat.value.length; index++) {
+        const preset = flat.value[index];
+        const path = `presets[${index}]`;
+        const spec = translateTaggedPreset(preset, path, { hasEntry }) ?? translateStaticPreset(preset, path);
+        if (!spec.ok)
+            return spec;
+        if (spec.value !== null)
+            presetSpecs.push(spec.value);
+    }
+    const presets = flat.value.filter((preset) => preset.name !== ROLE_PALETTES_PRESET);
+    const transformers = translateTransformers(merged.transformers);
+    if (!transformers.ok)
+        return transformers;
+    const inline = translateInline(merged);
+    if (!inline.ok)
+        return inline;
+    for (const key of source.value.derivedKeys)
+        delete inline.value[key];
+    const scalars = translateScalars(merged);
+    if (!scalars.ok)
+        return scalars;
+    const { root, entry, declarationFiles } = source.value;
+    const request = {
+        root,
+        entry,
+        presets: presetSpecs,
+        declarationFiles,
+        inline: Object.keys(inline.value).length === 0 ? null : inline.value,
+        ...scalars.value,
+    };
+    return { ok: true, request, presets, transformers: transformers.value };
+}
+export async function translateConfig(userConfig = {}, defaults = {}) {
+    const outcome = await translate(userConfig, defaults);
+    debugTranslate(outcome, userConfig);
+    // `translate` builds the request field by field; its shape is v02.2 §3 `LoadProjectRequest`.
+    return outcome;
+}
+/**
+ * v02.9 §9: with `TEACSS_ENGINE_DEBUG=1`, the request or the failure goes to stderr.
+ */
+export function debugTranslate(outcome, userConfig) {
+    if (process.env.TEACSS_ENGINE_DEBUG !== "1")
+        return;
+    if (outcome.ok) {
+        process.stderr.write(`[teacss] engine: request for ${outcome.request.entry?.path ?? "<inline>"}\n`);
+        process.stderr.write(`${JSON.stringify(outcome.request, null, 2)}\n`);
+    }
+    else {
+        process.stderr.write(`[teacss] engine: translate failed ${outcome.reason} at ${outcome.path} (keys: ${Object.keys(userConfig).join(", ")})\n`);
+    }
+}
+export const VALID_MODES = new Set(["auto", "rust", "ts"]);
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+function parseSemver(value) {
+    const match = SEMVER_RE.exec(value);
+    if (!match)
+        throw new TypeError(`[@teacss/engine] invalid semver: ${value}`);
+    return { core: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease: match[4] === undefined ? undefined : match[4].split(".") };
+}
+/**
+ * SemVer 2.0 precedence: the numeric triple, then a release above any of its prereleases, then
+ * the prerelease identifiers in order (numeric ones by value and below alphanumeric ones, a shorter
+ * list first when one is a prefix of the other).
+ */
+export function compareSemver(a, b) {
+    const left = parseSemver(a);
+    const right = parseSemver(b);
+    for (let index = 0; index < 3; index++) {
+        if (left.core[index] !== right.core[index])
+            return left.core[index] < right.core[index] ? -1 : 1;
+    }
+    if (!left.prerelease || !right.prerelease)
+        return left.prerelease === right.prerelease ? 0 : left.prerelease ? -1 : 1;
+    const length = Math.min(left.prerelease.length, right.prerelease.length);
+    for (let index = 0; index < length; index++) {
+        const x = left.prerelease[index];
+        const y = right.prerelease[index];
+        if (x === y)
+            continue;
+        const xNumeric = /^\d+$/.test(x);
+        const yNumeric = /^\d+$/.test(y);
+        if (xNumeric && yNumeric)
+            return Number(x) < Number(y) ? -1 : 1;
+        if (xNumeric !== yNumeric)
+            return xNumeric ? -1 : 1;
+        return x < y ? -1 : 1;
+    }
+    if (left.prerelease.length === right.prerelease.length)
+        return 0;
+    return left.prerelease.length < right.prerelease.length ? -1 : 1;
+}
+/** Only the `>=A <B` form `engineCompat.core` uses (v02.11 §7.3). */
+export function satisfiesRange(version, range) {
+    const parts = range.trim().split(/\s+/);
+    const [lower, upper] = parts;
+    if (parts.length !== 2 || !lower?.startsWith(">=") || !upper?.startsWith("<") || upper.startsWith("<="))
+        throw new TypeError(`[@teacss/engine] unsupported engineCompat range: ${range}`);
+    return compareSemver(version, lower.slice(2)) >= 0 && compareSemver(version, upper.slice(1)) < 0;
+}
+/**
+ * v02.9 §8.1: `TEACSS_ENGINE` over the hook option over `"ts"`; an `"auto"` option stays on TS while
+ * `defaultMode` is `"opt-in"`; a host core outside `engineCompat.core` keeps TS, or throws when
+ * Rust was asked for.
+ *
+ */
+export function selectEngineRequest({ hostCoreVersion, option, env, compat = ENGINE_COMPAT }) {
+    let mode;
+    let source;
+    let invalidEnv;
+    if (env !== undefined && env !== "" && VALID_MODES.has(env)) {
+        mode = env;
+        source = "env";
+    }
+    else {
+        if (env !== undefined && env !== "")
+            invalidEnv = env;
+        if (typeof option === "string" && VALID_MODES.has(option)) {
+            mode = option;
+            source = "option";
+        }
+        else {
+            mode = "ts";
+            source = "default";
+        }
+    }
+    const base = invalidEnv === undefined ? { mode, source } : { mode, source, invalidEnv };
+    if (mode === "ts")
+        return { engine: "ts", ...base };
+    if (mode === "auto" && source === "option" && compat.defaultMode === "opt-in")
+        return { engine: "ts", ...base, resolvedBy: "opt-in" };
+    if (compat.core && typeof hostCoreVersion === "string" && !satisfiesRange(hostCoreVersion, compat.core)) {
+        const detail = { hostCoreVersion, engineVersion: ENGINE_PACKAGE_VERSION, range: compat.core };
+        if (mode === "rust")
+            throw new TeacssEngineError("E_ENGINE_COMPAT", `[@teacss/engine] @teacss/core ${hostCoreVersion} is outside engineCompat.core ${compat.core} (engine ${ENGINE_PACKAGE_VERSION})`, detail);
+        return { engine: "ts", ...base, reason: "engine-compat", path: "@teacss/core", detail };
+    }
+    return { engine: "rust", ...base };
+}
+//# sourceMappingURL=select.js.map