mage-obsidian 1.1.2 → 2.0.0

package/src/utils/{findComponents.js → findComponents.ts}

@@ -2,8 +2,9 @@ import fs from "fs";
 import path from "path";
 
 /**
- * Recursively searches for `.vue` and `.js` files in the `components` directory
- * of a given module and organizes them into an object.
+ * Recursively searches a module's source folders for component files — matched by
+ * the extensions each folder declares (`directory.ext`) — and organizes them into
+ * an object.
  *
  * @param {string} moduleName - The name of the module to associate the files with.
  * @param moduleDir
@@ -14,12 +15,9 @@ import path from "path";
  *   - The values are the full relative paths to the files within the `components` folder.
  * @throws {Error} - Throws an error if duplicate file names (with different extensions) are found.
  */
-async function getFilesFromFolders(
-    moduleName,
-    moduleDir,
-    directories
-) {
+async function getFilesFromFolders(moduleName, moduleDir, directories) {
     const componentsDir = path.resolve(moduleDir);
+    // oxlint-disable-next-line only-used-in-recursion
     const getFilesFromFolderWithExt = async (dir, folderToSearch, extArr, baseDir = "") => {
         // console.log(moduleName, dir, folderToSearch, extArr, baseDir = "");
         if (!fs.existsSync(dir)) return [];
@@ -31,13 +29,21 @@ async function getFilesFromFolders(
                 const fullPath = path.join(dir, entry.name);
                 const relativePath = path.join(baseDir, entry.name);
                 if (entry.isDirectory()) {
-                    return await getFilesFromFolderWithExt(fullPath, folderToSearch, extArr, relativePath);
-                } else if (entry.isFile() && (entry.name.endsWith(".vue") || entry.name.endsWith(".js"))) {
+                    return await getFilesFromFolderWithExt(
+                        fullPath,
+                        folderToSearch,
+                        extArr,
+                        relativePath,
+                    );
+                } else if (
+                    entry.isFile() &&
+                    extArr.some((ext) => entry.name.endsWith(`.${ext}`)) &&
+                    // Skip co-located unit tests/specs so test-only deps
+                    // (e.g. @vue/test-utils) never leak into the build.
+                    !/\.(test|spec)\.[jt]sx?$/.test(entry.name)
+                ) {
                     const fileName = path.parse(entry.name).name;
-                    let key =
-                        baseDir === ""
-                            ? fileName
-                            : `${baseDir}/${fileName}`;
+                    let key = baseDir === "" ? fileName : `${baseDir}/${fileName}`;
                     key = `${moduleName}/${folderToSearch}/${key}`;
                     const filePath = path.join(dir, entry.name);
                     if (keyRegistered.includes(key)) {
@@ -47,7 +53,7 @@ async function getFilesFromFolders(
                     return { [key]: filePath };
                 }
                 return null;
-            })
+            }),
         );
         return files.filter(Boolean).flat();
     };
@@ -56,14 +62,21 @@ async function getFilesFromFolders(
         let result = [];
         for (const directory of directories) {
             const folderPath = path.resolve(componentsDir, directory.src);
-            const filesArray = await getFilesFromFolderWithExt(folderPath, directory.src, directory.ext);
+            const filesArray = await getFilesFromFolderWithExt(
+                folderPath,
+                directory.src,
+                directory.ext,
+            );
             result.push(...filesArray);
         }
         result = result.reduce((acc, item) => Object.assign(acc, item), {});
 
         return result;
     } catch (err) {
-        throw new Error(`Error while processing JavaScript or Vue files in the components folder of module "${moduleName}": ${err.message}`);
+        throw new Error(
+            `Error while processing JavaScript or Vue files in the components folder of module "${moduleName}": ${err.message}`,
+            { cause: err },
+        );
     }
 }
 

package/src/utils/runWithConcurrency.ts

@@ -0,0 +1,35 @@
+/**
+ * Run async workers over a list of items with a bounded number running at once.
+ *
+ * Results are returned in the same order as `items` regardless of completion
+ * order. The first rejection aborts the run (no new workers are started) and is
+ * propagated, mirroring Promise.all semantics. `limit` defaults to the number of
+ * items.
+ */
+export default async function runWithConcurrency<T, R>(
+    items: T[],
+    worker: (item: T, index: number) => Promise<R>,
+    limit: number = items.length,
+): Promise<R[]> {
+    if (!Array.isArray(items)) {
+        throw new TypeError("runWithConcurrency: items must be an array.");
+    }
+    if (typeof worker !== "function") {
+        throw new TypeError("runWithConcurrency: worker must be a function.");
+    }
+
+    const effectiveLimit = Math.max(1, Math.min(limit, items.length || 1));
+    const results = Array.from({ length: items.length }) as R[];
+    let nextIndex = 0;
+
+    async function runner() {
+        while (nextIndex < items.length) {
+            const current = nextIndex++;
+            results[current] = await worker(items[current], current);
+        }
+    }
+
+    const runners = Array.from({ length: Math.min(effectiveLimit, items.length) }, runner);
+    await Promise.all(runners);
+    return results;
+}

package/src/vite/defaultNodeResolver.ts

@@ -0,0 +1,17 @@
+export default {
+    name: "default-node-resolver",
+    resolveId: {
+        order: "post",
+        handler(id) {
+            try {
+                const resolvedPath = import.meta.resolve(id);
+                if (resolvedPath) {
+                    return resolvedPath.replace("file://", "");
+                }
+            } catch {
+                // Not resolvable as a node package; let later resolvers handle it.
+            }
+            return null;
+        },
+    },
+};

package/src/{service/inheritAssetsModuleResolver.js → vite/inheritAssetsModuleResolver.ts}

@@ -1,12 +1,11 @@
 import path from "path";
-import configResolver from "./configResolver.js";
+import configResolver from "../core/configResolver.ts";
 import fs from "fs";
 
 export default function customAssetsResolverPlugin() {
     const CURRENT_THEME = process.env.CURRENT_THEME;
-    const THEME_ASSETS_PATH = 'web';
-    const MODULE_ASSETS_PATH = 'view/frontend/web';
-
+    const THEME_ASSETS_PATH = "web";
+    const MODULE_ASSETS_PATH = "view/frontend/web";
 
     function tryResolveAssetPathByTheme(themeName, filePath) {
         const themeDefinition = configResolver.getThemeDefinition(themeName);
@@ -36,16 +35,21 @@ export default function customAssetsResolverPlugin() {
         return null;
     }
 
-
     const resolveAssetPath = (moduleName, filePath) => {
         if (!filePath.startsWith("assets/")) {
             return null;
         }
-        let assetSrc = null;
+        let assetSrc;
         if (moduleName === "Theme") {
-            assetSrc = tryResolveAssetPathByTheme(CURRENT_THEME, path.join(THEME_ASSETS_PATH, filePath));
+            assetSrc = tryResolveAssetPathByTheme(
+                CURRENT_THEME,
+                path.join(THEME_ASSETS_PATH, filePath),
+            );
         } else {
-            assetSrc = tryResolveAssetPathByTheme(CURRENT_THEME, path.join(moduleName, THEME_ASSETS_PATH, filePath));
+            assetSrc = tryResolveAssetPathByTheme(
+                CURRENT_THEME,
+                path.join(moduleName, THEME_ASSETS_PATH, filePath),
+            );
         }
         if (!assetSrc) {
             assetSrc = tryResolveAssetPathByModule(moduleName, filePath);
@@ -57,7 +61,7 @@ export default function customAssetsResolverPlugin() {
     return {
         name: "inherit-assets-resolver",
         resolveId: {
-            order: 'pre',
+            order: "pre",
             handler(id) {
                 if (!id) {
                     return;
@@ -72,7 +76,7 @@ export default function customAssetsResolverPlugin() {
                     return;
                 }
                 return assetSrc;
-            }
-        }
+            },
+        },
     };
 }

package/src/{service/inheritModuleResolver.js → vite/inheritModuleResolver.ts}

@@ -1,6 +1,6 @@
-import moduleResolver from "./moduleResolver.js";
+import moduleResolver from "../core/moduleResolver.ts";
 import path from "path";
-import configResolver from "./configResolver.js";
+import configResolver from "../core/configResolver.ts";
 
 export default function customResolverPlugin() {
     const allComponents = moduleResolver.getAllJsVueFilesWithInheritanceCached();
@@ -10,22 +10,18 @@ export default function customResolverPlugin() {
         validComponentExtensions.some((ext) => filePath.endsWith(ext));
     const hasExtension = (filePath) => !!path.extname(filePath);
 
-
     const resolveComponentPath = (moduleName, filePath) => {
         if (!filePath.startsWith("components/") && !filePath.startsWith("js/")) {
             filePath = "components/" + filePath;
         }
-        const fileName = path.join(
-            path.dirname(filePath),
-            path.parse(filePath).name
-        );
+        const fileName = path.join(path.dirname(filePath), path.parse(filePath).name);
         return allComponents[`${moduleName}/${fileName}`];
     };
 
     return {
         name: "inherit-resolver",
         resolveId: {
-            order: 'pre',
+            order: "pre",
             handler(id) {
                 if (!id) {
                     return;
@@ -44,7 +40,7 @@ export default function customResolverPlugin() {
                 }
 
                 return componentSrc;
-            }
-        }
+            },
+        },
     };
 }

package/src/{service/interceptorsPlugin.js → vite/interceptorsPlugin.ts}

@@ -1,22 +1,25 @@
-import generateInterceptorsService from './generateInterceptors.js';
+import generateInterceptorsService from "../core/generateInterceptors.ts";
 
-export default function interceptorsPlugin(options = {}) {
+export default function interceptorsPlugin(options: { themeName?: string } = {}) {
     const { themeName } = options;
-    let interceptorsMap = new Map(); // path -> interceptorData
+    const interceptorsMap = new Map(); // path -> interceptorData
 
     return {
-        name: 'mage-obsidian:interceptors',
-        enforce: 'pre',
+        name: "mage-obsidian:interceptors",
+        enforce: "pre",
 
         async buildStart() {
             if (!themeName) {
-                console.warn('[mage-obsidian:interceptors] themeName option is missing. Interceptors will not be generated.');
+                console.warn(
+                    "[mage-obsidian:interceptors] themeName option is missing. Interceptors will not be generated.",
+                );
                 return;
             }
-            
+
             try {
-                const interceptors = await generateInterceptorsService.generateInterceptors(themeName);
-                
+                const interceptors =
+                    await generateInterceptorsService.generateInterceptors(themeName);
+
                 // Create a map for fast lookup by file path
                 for (const key in interceptors) {
                     const data = interceptors[key];
@@ -25,25 +28,28 @@ export default function interceptorsPlugin(options = {}) {
                     }
                 }
             } catch (error) {
-                console.error('[mage-obsidian:interceptors] Failed to generate interceptors:', error);
+                console.error(
+                    "[mage-obsidian:interceptors] Failed to generate interceptors:",
+                    error,
+                );
             }
         },
 
         async resolveId(source, importer) {
             // Skip if we haven't loaded interceptors or if it's a virtual module
-            if (interceptorsMap.size === 0 || source.startsWith('\0')) return null;
+            if (interceptorsMap.size === 0 || source.startsWith("\0")) return null;
 
             // Try to resolve the import to a full path
             const resolution = await this.resolve(source, importer, { skipSelf: true });
-            
+
             if (!resolution || !resolution.id) return null;
-            
+
             // Clean up the ID (remove query params)
-            const resolvedId = resolution.id.split('?')[0];
+            const resolvedId = resolution.id.split("?")[0];
 
             if (interceptorsMap.has(resolvedId)) {
                 const virtualId = `\0interceptor:${resolvedId}`;
-                
+
                 // Check if we are inside the interceptor trying to import the original
                 if (importer === virtualId) {
                     return null; // Allow original import
@@ -56,15 +62,15 @@ export default function interceptorsPlugin(options = {}) {
         },
 
         load(id) {
-            if (id.startsWith('\0interceptor:')) {
-                const originalPath = id.slice('\0interceptor:'.length);
+            if (id.startsWith("\0interceptor:")) {
+                const originalPath = id.slice("\0interceptor:".length);
                 const data = interceptorsMap.get(originalPath);
-                
+
                 if (data) {
                     return data.source;
                 }
             }
             return null;
-        }
+        },
     };
 }

package/src/vite/magentoHrmRewrite.ts

@@ -0,0 +1,44 @@
+import moduleResolver from "../core/moduleResolver.ts";
+
+export default () => {
+    const components = moduleResolver.getAllJsVueFilesWithInheritanceCached();
+    return {
+        name: "handle-magento-routes-middleware",
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                const url = req.url;
+
+                const matchedKey = Object.keys(components).find((key) => url.includes(key));
+
+                if (matchedKey) {
+                    const filePath = components[matchedKey];
+                    let suffix;
+                    if (matchedKey === "lib/vue") {
+                        suffix = "/";
+                    } else if (matchedKey.startsWith("lib/")) {
+                        suffix = "/@fs";
+                        const fileExtension = filePath.split(".").pop();
+                        let mimeType = "application/node";
+                        if (
+                            fileExtension === "cjs" ||
+                            fileExtension === "mjs" ||
+                            fileExtension === "js"
+                        )
+                            mimeType = "application/javascript";
+                        if (fileExtension === "css") mimeType = "text/css";
+                        if (fileExtension === "json") mimeType = "application/json";
+                        if (fileExtension === "html") mimeType = "text/html";
+
+                        res.setHeader("Content-Type", mimeType);
+                    } else {
+                        suffix = "/@fs";
+                    }
+                    req.url = `${suffix}${filePath}`;
+                    next();
+                } else {
+                    next();
+                }
+            });
+        },
+    };
+};

package/src/vite/sharedPlugins.ts

@@ -0,0 +1,54 @@
+import inheritModuleResolver from "./inheritModuleResolver.ts";
+import inheritAssetsModuleResolver from "./inheritAssetsModuleResolver.ts";
+import defaultNodeResolve from "./defaultNodeResolver.ts";
+import unresolvedModuleGuard from "./unresolvedModuleGuard.ts";
+import preCompileMagentoFiles from "../core/preCompileMagentoFiles.ts";
+import configResolver from "../core/configResolver.ts";
+
+/**
+ * The framework's module-resolution plugin chain: `Vendor_Module::` component
+ * and asset resolution plus the node-package fallback. Resolution order is
+ * governed by each plugin's resolveId `order` ('pre'/'post'), not by array
+ * position, so this group can sit anywhere in a consumer's plugin list.
+ *
+ * Shared so the dev/build config, component tests, auto-import and the
+ * playground all resolve imports through the exact same chain instead of each
+ * reimplementing it and drifting.
+ */
+export function getResolverPlugins() {
+    return [
+        inheritModuleResolver(),
+        inheritAssetsModuleResolver(),
+        defaultNodeResolve,
+        unresolvedModuleGuard(),
+    ];
+}
+
+/**
+ * Ensure a theme's precompiled entries exist on disk before a build/test/story
+ * run. Idempotent per (theme, contract hash). Any consumer that resolves
+ * `Vendor_Module::` imports MUST call this first: without it the resolver map
+ * is empty and those imports resolve to undefined with no error.
+ */
+export function ensurePrecompiled(themeName) {
+    return preCompileMagentoFiles(themeName);
+}
+
+/**
+ * Build Vite's `server.fs.allow` list from the contract. Modules and themes can
+ * live outside the Magento root — e.g. symlinked from a monorepo during dev —
+ * in which case their real `src` roots are outside the default allow-list and
+ * Vite answers 403 for any file under them. A single 403 on a bootstrap module
+ * (such as the i18n runtime) aborts the whole ESM graph, so the page renders
+ * unstyled with no components. Deriving the list from each module/theme `src`
+ * makes the dev server serve sources wherever they physically live.
+ */
+export function getFsAllowList(rootDir) {
+    const srcRoots = [
+        ...configResolver.getModulesConfigArray(),
+        ...configResolver.getThemesConfigArray(),
+    ]
+        .map(([, definition]) => definition?.src)
+        .filter(Boolean);
+    return [...new Set([rootDir, ...srcRoots])];
+}

package/src/vite/themeSourceWatcher.ts

@@ -0,0 +1,96 @@
+import path from "node:path";
+import configResolver from "../core/configResolver.ts";
+import moduleResolver from "../core/moduleResolver.ts";
+import { precompileJs, precompileJsconfig, precompileTsconfig } from "../core/preCompileFiles.ts";
+import { MODULE_WEB_PATH } from "../config/default.ts";
+
+const SOURCE_EXT = /\.(vue|ts|js)$/;
+// Build output and engine scratch live under the watched trees but are not
+// authored sources — reacting to them would loop (we write them ourselves).
+const IGNORED = /[/\\](generated|\.precompiled|node_modules)[/\\]/;
+const DEBOUNCE_MS = 150;
+
+// The source roots whose structure feeds the inheritance map: every opted-in
+// module's web dir plus the theme and its parent chain. Adding/removing a
+// `.vue`/`.ts`/`.js` under these changes what `Vendor_Module::` can resolve.
+function collectWatchDirs(themeName) {
+    const dirs = new Set();
+    for (const [, definition] of configResolver.getModulesConfigArray()) {
+        if (definition?.src) dirs.add(path.resolve(definition.src, MODULE_WEB_PATH));
+    }
+    const themes = configResolver.getMagentoConfig().themes;
+    const seen = new Set();
+    let name = themeName;
+    while (name && themes[name] && !seen.has(name)) {
+        seen.add(name);
+        if (themes[name].src) dirs.add(themes[name].src);
+        name = themes[name].parent;
+    }
+    return [...dirs];
+}
+
+/**
+ * Dev-only plugin that keeps `Vendor_Module::` resolution live. Precompile runs
+ * once at server start and is cached by contract hash; adding or removing a
+ * component/js source changes neither, so without this the new file is invisible
+ * to both the runtime resolver and the editor jsconfig until a restart. On a
+ * structural change we drop the theme cache, rewrite the persisted inheritance
+ * map (runtime) and regenerate the theme jsconfig (editor). Writes are
+ * idempotent, so the burst of events when the watch dirs are first scanned
+ * collapses to a single no-op.
+ */
+export default function themeSourceWatcher(themeName) {
+    return {
+        name: "mage-obsidian:theme-source-watcher",
+        apply: "serve",
+        configureServer(server) {
+            for (const dir of collectWatchDirs(themeName)) {
+                server.watcher.add(dir);
+            }
+
+            let timer = null;
+            let running = false;
+            let queued = false;
+
+            const regenerate = async () => {
+                if (running) {
+                    queued = true;
+                    return;
+                }
+                running = true;
+                try {
+                    moduleResolver.invalidateTheme(themeName);
+                    await precompileJs(themeName);
+                    await precompileJsconfig(themeName);
+                    await precompileTsconfig(themeName);
+                    server.config.logger.info(
+                        `[mage-obsidian] sources changed — refreshed ${themeName} import resolution`,
+                    );
+                } catch (error) {
+                    server.config.logger.error(
+                        `[mage-obsidian] failed to refresh import resolution: ${error?.message ?? error}`,
+                    );
+                } finally {
+                    running = false;
+                    if (queued) {
+                        queued = false;
+                        schedule();
+                    }
+                }
+            };
+
+            const schedule = () => {
+                if (timer) clearTimeout(timer);
+                timer = setTimeout(regenerate, DEBOUNCE_MS);
+            };
+
+            const onChange = (file) => {
+                if (!SOURCE_EXT.test(file) || IGNORED.test(file)) return;
+                schedule();
+            };
+
+            server.watcher.on("add", onChange);
+            server.watcher.on("unlink", onChange);
+        },
+    };
+}

package/src/vite/unresolvedModuleGuard.ts

@@ -0,0 +1,87 @@
+import moduleResolver from "../core/moduleResolver.ts";
+
+// The part before `::` must look like a Magento module (Vendor_Module) or the
+// special `Theme` namespace. This keeps the guard from firing on unrelated ids
+// (virtual modules, already-resolved absolute paths) that happen to contain `::`.
+const NAMESPACE_PATTERN = /^(Theme|[A-Z][A-Za-z0-9_]*)$/;
+
+function distance(a: string, b: string): number {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    const dp = Array.from({ length: rows }, () => Array.from({ length: cols }, () => 0));
+    for (let i = 0; i < rows; i++) dp[i][0] = i;
+    for (let j = 0; j < cols; j++) dp[0][j] = j;
+    for (let i = 1; i < rows; i++) {
+        for (let j = 1; j < cols; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+        }
+    }
+    return dp[a.length][b.length];
+}
+
+function suggest(namespace: string, target: string): string[] {
+    let keys: string[];
+    try {
+        keys = Object.keys(moduleResolver.getAllJsVueFilesWithInheritanceCached());
+    } catch {
+        // No precompiled cache yet — nothing to suggest from.
+        return [];
+    }
+    const prefix = `${namespace}/`;
+    return keys
+        .filter((key) => key.startsWith(prefix))
+        .map((key) => `${namespace}::${key.slice(prefix.length)}`)
+        .map((candidate) => [candidate, distance(candidate, target)] as const)
+        .sort((a, b) => a[1] - b[1])
+        .slice(0, 3)
+        .map(([candidate]) => candidate);
+}
+
+function buildMessage(id: string, namespace: string, rest: string, importer?: string): string {
+    const from = importer ? `\n  imported by: ${importer}` : "";
+
+    let hint: string;
+    if (rest.startsWith("assets/")) {
+        hint =
+            `\n  Asset not found. Expected a theme override at` +
+            ` <theme>/${namespace}/web/${rest} or the module at` +
+            ` <module>/view/frontend/web/${rest}.`;
+    } else {
+        const suggestions = suggest(namespace, id);
+        hint = suggestions.length
+            ? `\n  Did you mean:\n${suggestions.map((s) => `    - ${s}`).join("\n")}`
+            : `\n  Nothing is registered under "${namespace}". Is the module/theme enabled` +
+              ` and compatible, and the contract regenerated` +
+              ` (bin/magento mage-obsidian:frontend:config --generate)?`;
+    }
+
+    return `[mage-obsidian] Unresolved import "${id}".${from}${hint}`;
+}
+
+/**
+ * Fail-loud guard for the framework's `Vendor_Module::` import notation. It runs
+ * last in the resolver chain (`order: "post"`), so a `::` specifier only reaches
+ * it when none of the earlier resolvers (component, asset, node) could resolve
+ * it — i.e. a typo or a missing file. Without this, Rollup externalizes the
+ * unknown specifier silently and the import breaks at runtime with no clear
+ * cause; here it becomes a build/dev error naming the specifier, the importer,
+ * and the closest valid alternatives.
+ */
+export default function unresolvedModuleGuard() {
+    return {
+        name: "unresolved-module-guard",
+        resolveId: {
+            order: "post",
+            handler(id: string, importer?: string) {
+                if (!id || id[0] === "\0") return;
+                const separator = id.indexOf("::");
+                if (separator === -1) return;
+                const namespace = id.slice(0, separator);
+                if (!NAMESPACE_PATTERN.test(namespace)) return;
+
+                throw new Error(buildMessage(id, namespace, id.slice(separator + 2), importer));
+            },
+        },
+    };
+}

package/tsconfig.json

@@ -0,0 +1,34 @@
+{
+    "compilerOptions": {
+        "target": "ES2023",
+        "lib": ["ES2023", "DOM", "DOM.Iterable"],
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "types": ["node"],
+
+        // No build in dev: Vite and Node (>=22.18 type-stripping) consume the
+        // .ts sources directly. tsc is type-check only. Importing `.ts`
+        // specifiers is therefore allowed, and only erasable TS syntax is
+        // permitted so type-stripping never fails.
+        "noEmit": true,
+        "allowImportingTsExtensions": true,
+        "erasableSyntaxOnly": true,
+        "verbatimModuleSyntax": true,
+
+        // Author components stay JS; the engine is TS. allowJs keeps the mixed
+        // tree resolvable without forcing checkJs on legacy/JS files.
+        "allowJs": true,
+        "checkJs": false,
+
+        // Lenient baseline for the JS->TS migration: the tree is now TypeScript
+        // and type-strippable, but not yet annotated. strict is the ratchet
+        // target, tightened progressively per subdirectory in follow-up work.
+        "strict": false,
+        "skipLibCheck": true,
+        "resolveJsonModule": true,
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "include": ["src/**/*.ts", "src/**/*.js", "*.ts", "*.js"],
+    "exclude": ["node_modules", ".precompiled", "src/__tests__/magento_scenarios"]
+}

package/vitest.config.js

@@ -0,0 +1,18 @@
+import { defineConfig } from "vitest/config";
+
+// Engine unit tests run in Node. Vitest transpiles TS/ESM natively, replacing
+// the `node --experimental-vm-modules` + Jest setup. Data trees under
+// __tests__ are fixtures, not suites.
+export default defineConfig({
+    test: {
+        environment: "node",
+        globals: true,
+        include: ["src/__tests__/**/*.test.{js,ts}"],
+        exclude: [
+            "**/node_modules/**",
+            "src/__tests__/magento_scenarios/**",
+            "src/__tests__/fixtures/**",
+            "src/__tests__/__mocks__/**",
+        ],
+    },
+});