mage-obsidian 1.1.2 → 2.0.0

package/src/core/configResolver.ts

@@ -0,0 +1,141 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { DEPENDENCY_CONFIG_FILE_PATH, OUTPUT_THEME_DIR } from "../config/default.ts";
+import { validateContract } from "./contractValidator.ts";
+
+const REGENERATE_HINT =
+    "Try running `bin/magento mage-obsidian:frontend:config --generate` to generate the configuration file.";
+
+// Minimal shapes for the generated contract entries. Only `src` (and the theme
+// `parent`) are typed today; the rest stays open as the engine is typed
+// progressively. The contract itself is validated at runtime by validateContract.
+interface ModuleDefinition {
+    src: string;
+    [key: string]: any;
+}
+
+interface ThemeDefinition {
+    src: string;
+    parent?: string;
+    [key: string]: any;
+}
+
+// Cached contract, invalidated by the file's mtime. A per-process `const` read
+// at import time never picked up a regenerated contract (e.g. a module enabled
+// while a long-lived dev server runs), so caches keyed only by theme served
+// stale results. Reloading on mtime change makes the contract — and the hash
+// derived from it — track the file.
+let cached = null; // { mtimeMs, config, hash }
+
+function fail(message, extra = []) {
+    console.error(message);
+    extra.forEach((line) => console.error(line));
+    console.error(REGENERATE_HINT);
+    process.exit(1);
+}
+
+function loadContract() {
+    let stats;
+    try {
+        stats = fs.statSync(DEPENDENCY_CONFIG_FILE_PATH);
+    } catch (error) {
+        fail(
+            `Error reading configuration file at ${DEPENDENCY_CONFIG_FILE_PATH}: ${error.message}`,
+        );
+    }
+
+    if (cached && cached.mtimeMs === stats.mtimeMs) {
+        return cached.config;
+    }
+
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(DEPENDENCY_CONFIG_FILE_PATH, "utf-8"));
+    } catch (error) {
+        fail(
+            `Error reading or parsing configuration file at ${DEPENDENCY_CONFIG_FILE_PATH}: ${error.message}`,
+        );
+    }
+
+    const validation = validateContract(config);
+    if (!validation.ok) {
+        fail(`Invalid MageObsidian frontend contract at ${DEPENDENCY_CONFIG_FILE_PATH}:`, [
+            ...validation.errors.map((message) => `  - ${message}`),
+            "If the version differs, the PHP module and JS engine are out of sync — align their versions, then regenerate.",
+        ]);
+    }
+
+    // Hash the parts that change the build graph (which modules/themes exist and
+    // their resolution). Caches downstream key on this so a changed module set
+    // invalidates them, rather than serving a result keyed only by theme name.
+    const hash = crypto
+        .createHash("sha1")
+        .update(
+            JSON.stringify({
+                modules: config.modules,
+                themes: config.themes,
+                allModules: config.allModules,
+            }),
+        )
+        .digest("hex");
+
+    cached = { mtimeMs: stats.mtimeMs, config, hash };
+    return config;
+}
+
+const getContract = () => loadContract();
+
+export const getMagentoConfig = () => getContract();
+export const getContractHash = () => {
+    getContract();
+    return cached.hash;
+};
+export const getModulesConfigArray = () =>
+    Object.entries(getContract().modules) as [string, ModuleDefinition][];
+export const getThemesConfigArray = () =>
+    Object.entries(getContract().themes) as [string, ThemeDefinition][];
+export const getAllMagentoModulesEnabled = () => getContract().allModules;
+export const isDev = () => getContract().mode !== "production";
+
+export const getOutputDirFromTheme = (themePath) => path.resolve(themePath, OUTPUT_THEME_DIR);
+
+export const getModuleDefinition = (moduleName): ModuleDefinition =>
+    getContract().modules[moduleName];
+
+export const getThemeDefinition = (themeName): ThemeDefinition => getContract().themes[themeName];
+
+export const MODE = process.env.NODE_ENV;
+
+export function resolveLibPath(lib) {
+    return path.join(getContract().LIB_PATH, lib);
+}
+
+export function resolveNodePath(packageName) {
+    try {
+        const resolvedPath = import.meta.resolve(packageName);
+        return resolvedPath.replace("file://", "");
+    } catch (error) {
+        console.error(`The package ${packageName} can't be resolved.`);
+        throw error;
+    }
+}
+
+export function resolveLibRealPath(lib) {
+    return MODE === "production" ? lib : resolveNodePath(lib);
+}
+
+export default {
+    getMagentoConfig,
+    getContractHash,
+    getModulesConfigArray,
+    getThemesConfigArray,
+    getAllMagentoModulesEnabled,
+    isDev,
+    getOutputDirFromTheme,
+    getModuleDefinition,
+    getThemeDefinition,
+    resolveLibPath,
+    resolveNodePath,
+    resolveLibRealPath,
+};

package/src/core/contractValidator.ts

@@ -0,0 +1,56 @@
+// Contract version this build engine understands. Must match
+// ConfigInterface::SCHEMA_VERSION on the PHP side; a mismatch means the module
+// and the JS engine are out of sync and the contract cannot be trusted.
+export const EXPECTED_SCHEMA_VERSION = "1.0.0";
+
+// Top-level keys the engine reads off the generated contract. Kept in step with
+// the JSON schema in module-modern-frontend/src/etc.
+export const REQUIRED_CONTRACT_KEYS = [
+    "schema_version",
+    "mode",
+    "modules",
+    "themes",
+    "allModules",
+    "VUE_COMPONENTS_PATH",
+    "JS_PATH",
+    "FOLDERS_TO_WATCH",
+    "ALLOWED_EXTENSIONS",
+    "MODULE_CSS_EXTEND_FILE",
+    "MODULE_CONFIG_FILE",
+    "THEME_CONFIG_FILE",
+    "THEME_CSS_SOURCE_FILE",
+    "THEME_FILES_PATH",
+    "LIB_PATH",
+];
+
+/**
+ * Validate the parsed frontend contract.
+ *
+ * Pure: no IO, no process exit. The caller decides how to react to errors.
+ *
+ * @param {unknown} config Parsed contract object.
+ * @param {string} [expectedVersion] Schema version the caller expects.
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateContract(config, expectedVersion = EXPECTED_SCHEMA_VERSION) {
+    if (config === null || typeof config !== "object" || Array.isArray(config)) {
+        return { ok: false, errors: ["Contract is not a JSON object."] };
+    }
+
+    const errors = [];
+
+    if (config.schema_version !== expectedVersion) {
+        errors.push(
+            `Schema version mismatch: this build engine expects "${expectedVersion}" ` +
+                `but the contract is "${config.schema_version ?? "(missing)"}".`,
+        );
+    }
+
+    for (const key of REQUIRED_CONTRACT_KEYS) {
+        if (!Object.prototype.hasOwnProperty.call(config, key)) {
+            errors.push(`Missing required key "${key}".`);
+        }
+    }
+
+    return { ok: errors.length === 0, errors };
+}

package/src/core/cssResolver.ts

@@ -0,0 +1,153 @@
+import themeResolver from "./themeResolverSync.ts";
+import path from "node:path";
+import {
+    MODULE_TEMPLATES_PATH,
+    MODULE_WEB_PATH,
+    THEME_CSS_FOLDER,
+    THEME_MODULE_WEB_PATH,
+} from "../config/default.ts";
+import { resolveFileByTheme, getAllJsVueFilesWithInheritanceCached } from "./moduleResolver.ts";
+import configResolver from "./configResolver.ts";
+import fs from "node:fs/promises";
+
+const { getMagentoConfig, getModuleDefinition, getThemeDefinition, getModulesConfigArray } =
+    configResolver;
+
+const MODULE_CSS_EXTEND_FILE = getMagentoConfig().MODULE_CSS_EXTEND_FILE;
+const THEME_CSS_SOURCE_FILE = getMagentoConfig().THEME_CSS_SOURCE_FILE;
+
+async function getThemeImports(themeName, themeConfig?) {
+    if (!themeConfig) {
+        themeConfig = await themeResolver.getThemeConfig(themeName);
+    }
+    const themeDefinition = getThemeDefinition(themeName);
+    const themePath = themeDefinition.src;
+
+    let imports = "";
+    if (themeConfig.includeCssSourceFromParentThemes && themeDefinition.parent) {
+        imports += await getThemeImports(themeDefinition.parent, themeConfig);
+    }
+
+    imports += `@import "${path.join(themePath, THEME_MODULE_WEB_PATH, THEME_CSS_FOLDER, THEME_CSS_SOURCE_FILE)}";\n`;
+    return imports;
+}
+
+function resolveModuleCssSourcePath(moduleName, themeName) {
+    let moduleConfigSourcePath = resolveFileByTheme(
+        themeName,
+        moduleName,
+        path.join("css", MODULE_CSS_EXTEND_FILE),
+    );
+    if (!moduleConfigSourcePath) {
+        const moduleDefinition = getModuleDefinition(moduleName);
+        moduleConfigSourcePath = path.join(
+            moduleDefinition.src,
+            MODULE_WEB_PATH,
+            "css",
+            MODULE_CSS_EXTEND_FILE,
+        );
+    }
+    return moduleConfigSourcePath;
+}
+
+// Walk the theme -> parent chain emitting a @source for each theme root so
+// Tailwind scans the Twig/phtml templates of every theme in the inheritance
+// chain (a child theme's classes plus everything it inherits unchanged).
+async function getThemeTemplateSources(themeName) {
+    const theme = getThemeDefinition(themeName);
+    if (!theme) return "";
+
+    let sources = "";
+    if (theme.parent) {
+        sources += await getThemeTemplateSources(theme.parent);
+    }
+    sources += `@source "${theme.src}";\n`;
+    return sources;
+}
+
+// Reads the source-scan opt-out: a theme (merged with its parents) lists the
+// modules whose files Tailwind must NOT scan via `ignoredTailwindConfigFromModules`
+// in theme.config.js — an array of module names, or "all" to skip every module.
+// The theme's own files are always scanned.
+async function getScanExclusions(themeName) {
+    const themeConfig = await themeResolver.getThemeConfig(themeName);
+    const ignored = themeConfig?.ignoredTailwindConfigFromModules;
+    return {
+        ignoreAllModules: ignored === "all",
+        excludedModules: new Set(Array.isArray(ignored) ? ignored : []),
+    };
+}
+
+// Templates (.twig/.phtml) are not auto-scanned by Tailwind in this pipeline
+// (its base path is the Vite root, not the Magento tree), and the engine only
+// emits @source for JS/Vue components. This registers the template dirs of
+// every compatible module plus the whole theme inheritance chain, mirroring how
+// components already resolve module + parent-theme sources, and honours the
+// per-module scan opt-out.
+async function getTemplateSources(themeName) {
+    const { ignoreAllModules, excludedModules } = await getScanExclusions(themeName);
+    let sources = "";
+
+    if (!ignoreAllModules) {
+        for (const [moduleName, moduleConfig] of getModulesConfigArray()) {
+            if (excludedModules.has(moduleName)) continue;
+            const templatesDir = path.join(moduleConfig.src, MODULE_TEMPLATES_PATH);
+            try {
+                await fs.access(templatesDir);
+                sources += `@source "${templatesDir}";\n`;
+            } catch {
+                // module ships no frontend templates
+            }
+        }
+    }
+
+    sources += await getThemeTemplateSources(themeName);
+    return sources;
+}
+
+async function getVueComponentsSource(themeName) {
+    const { ignoreAllModules, excludedModules } = await getScanExclusions(themeName);
+    const vueComponents = await getAllJsVueFilesWithInheritanceCached(themeName);
+    // Inheritance keys look like "Vendor_Module/components/X" or "Theme/...";
+    // "Theme" entries are the theme's own files and are always scanned.
+    const vueComponentSources = Object.entries(vueComponents)
+        .filter(([key]) => {
+            const owner = key.split("/")[0];
+            if (owner === "Theme") return true;
+            if (ignoreAllModules) return false;
+            return !excludedModules.has(owner);
+        })
+        .map(([, url]) => `@source "${url}";\n`);
+    return vueComponentSources.join("");
+}
+
+async function getCssImports(themeName) {
+    const themeConfig = await themeResolver.getThemeConfig(themeName);
+    const excludedModules = new Set(themeConfig.ignoredCssFromModules || []);
+    const modulesConfig = getModulesConfigArray();
+
+    const cssSource = await getVueComponentsSource(themeName);
+    let cssImports = "";
+
+    if (themeConfig.ignoredCssFromModules !== "all") {
+        for (const [moduleName] of modulesConfig) {
+            if (excludedModules.has(moduleName)) continue;
+
+            const filePath = resolveModuleCssSourcePath(moduleName, themeName);
+            try {
+                await fs.access(filePath);
+                cssImports += `@import "${filePath}";\n`;
+            } catch {
+                // ignore if file doesn't exist
+            }
+        }
+    }
+
+    cssImports += await getThemeImports(themeName);
+
+    const templateSources = await getTemplateSources(themeName);
+    return `${cssSource}${templateSources}\n${cssImports}`;
+}
+
+export default getCssImports;
+export { getTemplateSources };

package/src/{service/generateInterceptors.js → core/generateInterceptors.ts}

@@ -1,13 +1,13 @@
 import path from "path";
-import { pathToFileURL, fileURLToPath } from "url";
-import themeResolver from 'mage-obsidian/service/themeResolverSync.js';
-import moduleResolver from 'mage-obsidian/service/moduleResolver.js';
-import interceptorManager from 'mage-obsidian/service/interceptorManager.js';
-import configResolver from "mage-obsidian/service/configResolver.js";
+import { pathToFileURL } from "url";
+import themeResolver from "./themeResolverSync.ts";
+import moduleResolver from "./moduleResolver.ts";
+import interceptorManager from "../runtime/interceptorManager.ts";
+import configResolver from "./configResolver.ts";
 
 const interceptorsRegisteredByTheme = new Map();
 const generatedInterceptorsCache = new Map();
-export const KEY_INTERCEPTED = 'originalIntercepted';
+export const KEY_INTERCEPTED = "originalIntercepted";
 
 /**
  * Resolves the absolute path of a file using the cached file map
@@ -16,7 +16,7 @@ export const KEY_INTERCEPTED = 'originalIntercepted';
  * @returns {string|null}
  */
 function resolvePathFromMap(identifier, fileMap) {
-    const [moduleName, relativePath] = identifier.split('::');
+    const [moduleName, relativePath] = identifier.split("::");
     if (!moduleName || !relativePath) return null;
 
     const parsed = path.parse(relativePath);
@@ -26,7 +26,7 @@ function resolvePathFromMap(identifier, fileMap) {
     return fileMap[key] || null;
 }
 
-async function registerInterceptors(themeName) {
+async function registerInterceptors(themeName): Promise<Record<string, any[]>> {
     if (interceptorsRegisteredByTheme.has(themeName)) {
         return interceptorsRegisteredByTheme.get(themeName);
     }
@@ -38,8 +38,10 @@ async function registerInterceptors(themeName) {
         return {};
     }
     // Map<Target, Map<PluginName, PluginConfig>>
-    const interceptorsMap = new Map();
-    for (const [interceptorName, interceptorDefinition] of Object.entries( modulesConfig.interceptors)) {
+    const interceptorsMap = new Map<string, Map<string, any>>();
+    for (const [interceptorName, interceptorDefinition] of Object.entries(
+        modulesConfig.interceptors,
+    ) as [string, any][]) {
         const { target } = interceptorDefinition;
         if (!interceptorName || !target) continue;
 
@@ -59,10 +61,10 @@ async function registerInterceptors(themeName) {
     }
 
     // Convert Map to structured object and sort plugins
-    const result = {};
+    const result: Record<string, any[]> = {};
     for (const [target, pluginsMap] of interceptorsMap) {
         const plugins = Array.from(pluginsMap.values())
-            .filter(p => p.active !== false) // Filter out inactive plugins
+            .filter((p) => p.active !== false) // Filter out inactive plugins
             .sort((a, b) => (a.sortOrder || 10) - (b.sortOrder || 10));
 
         if (plugins.length > 0) {
@@ -82,11 +84,13 @@ async function generateInterceptors(themeName) {
     const interceptorsConfig = await registerInterceptors(themeName);
 
     // Get all files map from cache
-    let allFilesMap = {};
+    let allFilesMap;
     try {
         allFilesMap = moduleResolver.getAllJsVueFilesWithInheritanceCached(themeName);
     } catch (e) {
-        console.warn(`Cache not found for theme ${themeName}, falling back to async generation.`);
+        console.warn(
+            `Cache not found for theme ${themeName} (${e.message}), falling back to async generation.`,
+        );
         allFilesMap = await moduleResolver.getAllJsVueFilesWithInheritance(themeName);
     }
 
@@ -124,7 +128,10 @@ async function generateInterceptors(themeName) {
             try {
                 interceptorModule = await import(pathToFileURL(interceptorPath).href);
             } catch (e) {
-                console.error(`Failed to import interceptor module ${interceptorConfig.interceptor}:`, e.message);
+                console.error(
+                    `Failed to import interceptor module ${interceptorConfig.interceptor}:`,
+                    e.message,
+                );
                 continue;
             }
 
@@ -132,33 +139,37 @@ async function generateInterceptors(themeName) {
             for (const interceptorExport of Object.keys(interceptorModule)) {
                 let type, targetMethod;
 
-                if (interceptorExport.startsWith('before')) {
-                    type = 'before';
+                if (interceptorExport.startsWith("before")) {
+                    type = "before";
                     targetMethod = interceptorExport.substring(6);
-                } else if (interceptorExport.startsWith('around')) {
-                    type = 'around';
+                } else if (interceptorExport.startsWith("around")) {
+                    type = "around";
                     targetMethod = interceptorExport.substring(6);
-                } else if (interceptorExport.startsWith('after')) {
-                    type = 'after';
+                } else if (interceptorExport.startsWith("after")) {
+                    type = "after";
                     targetMethod = interceptorExport.substring(5);
                 } else {
                     continue;
                 }
 
                 // Check if target method exists in target module
-                if (!targetExports.includes(targetMethod) && targetMethod !== 'default') {
+                if (!targetExports.includes(targetMethod) && targetMethod !== "default") {
                     const lowerFirst = targetMethod.charAt(0).toLowerCase() + targetMethod.slice(1);
                     if (targetExports.includes(lowerFirst)) {
                         targetMethod = lowerFirst;
                     } else {
                         // Skip invalid methods but don't crash the whole process?
                         // User requested error if not found.
-                        throw new Error(`Interceptor ${interceptorConfig.name} (${interceptorConfig.interceptor}) exports '${interceptorExport}' but target ${target} does not export '${targetMethod}'`);
+                        throw new Error(
+                            `Interceptor ${interceptorConfig.name} (${interceptorConfig.interceptor}) exports '${interceptorExport}' but target ${target} does not export '${targetMethod}'`,
+                        );
                     }
                 }
 
-                if (typeof targetModule[targetMethod] !== 'function') {
-                    console.warn(`Interceptor ${interceptorConfig.name} (${interceptorConfig.interceptor}) exports '${interceptorExport}' but target ${target} export '${targetMethod}' is not a function.`);
+                if (typeof targetModule[targetMethod] !== "function") {
+                    console.warn(
+                        `Interceptor ${interceptorConfig.name} (${interceptorConfig.interceptor}) exports '${interceptorExport}' but target ${target} export '${targetMethod}' is not a function.`,
+                    );
                     continue;
                 }
 
@@ -168,7 +179,7 @@ async function generateInterceptors(themeName) {
                     interceptorConfig.name,
                     type,
                     interceptorModule[interceptorExport],
-                    interceptorConfig.sortOrder
+                    interceptorConfig.sortOrder,
                 );
 
                 methodsToIntercept.add(targetMethod);
@@ -176,7 +187,7 @@ async function generateInterceptors(themeName) {
                     exportName: interceptorExport,
                     type,
                     targetMethod,
-                    sortOrder: interceptorConfig.sortOrder
+                    sortOrder: interceptorConfig.sortOrder,
                 });
             }
 
@@ -184,7 +195,7 @@ async function generateInterceptors(themeName) {
                 validInterceptors.push({
                     ...interceptorConfig,
                     path: interceptorPath,
-                    methods: interceptorMethods
+                    methods: interceptorMethods,
                 });
             }
         }
@@ -194,14 +205,19 @@ async function generateInterceptors(themeName) {
             const wrapper = { ...targetModule };
             const proxy = interceptorManager.intercept(wrapper, target, true);
 
-            const source = generateInterceptorCode(target, targetPath, validInterceptors, targetExports);
+            const source = generateInterceptorCode(
+                target,
+                targetPath,
+                validInterceptors,
+                targetExports,
+            );
 
             interceptors[target] = {
                 proxy,
                 targetPath,
                 targetModule,
                 interceptors: validInterceptors,
-                source
+                source,
             };
         }
     }
@@ -219,41 +235,58 @@ function generateInterceptorCode(target, targetPath, interceptors, targetExports
     // Using a relative path from this service file might not work in the generated code context.
     // We'll assume '@mage-obsidian/plugin-manager' or similar alias is set up,
     // or use the absolute path which Vite handles.
-    const resolvedInterceptorManagerPath = configResolver.resolveLibRealPath('mage-obsidian/service/interceptorManager');
-    imports.push(`import interceptorManager from "${resolvedInterceptorManagerPath}";`);
+    // All string literals go through JSON.stringify so paths or interceptor
+    // names containing quotes/backslashes can't break (or inject into) the
+    // generated module. Identifiers (export names) come from Object.keys of a
+    // real ES module, so they are valid JS and used unquoted.
+    const resolvedInterceptorManagerPath = configResolver.resolveLibRealPath(
+        "mage-obsidian/runtime/interceptorManager",
+    );
+    imports.push(
+        `import interceptorManager from ${JSON.stringify(resolvedInterceptorManagerPath)};`,
+    );
 
     // Import Original Module
-    imports.push(`import * as originalModule from '/@fs${targetPath}?${KEY_INTERCEPTED}';`);
+    imports.push(
+        `import * as originalModule from ${JSON.stringify(`/@fs${targetPath}?${KEY_INTERCEPTED}`)};`,
+    );
 
     // Import Interceptors
     interceptors.forEach((interceptor, index) => {
         const interceptorVar = `interceptor_${index}`;
-        imports.push(`import * as ${interceptorVar} from '/@fs${interceptor.path}';`);
+        imports.push(
+            `import * as ${interceptorVar} from ${JSON.stringify(`/@fs${interceptor.path}`)};`,
+        );
 
-        interceptor.methods.forEach(method => {
+        interceptor.methods.forEach((method) => {
             const methodKey = `${target}::${method.targetMethod}`;
-            registrations.push(`interceptorManager.addInterceptor('${methodKey}', '${interceptor.name}', '${method.type}', ${interceptorVar}.${method.exportName}, ${method.sortOrder});`);
+            const sortOrder = Number.isFinite(method.sortOrder) ? method.sortOrder : 10;
+            registrations.push(
+                `interceptorManager.addInterceptor(${JSON.stringify(methodKey)}, ${JSON.stringify(interceptor.name)}, ${JSON.stringify(method.type)}, ${interceptorVar}.${method.exportName}, ${sortOrder});`,
+            );
         });
     });
 
     // Create Interceptor
     const interceptorCode = `
 const targetWrapper = { ...originalModule };
-const proxy = interceptorManager.intercept(targetWrapper, '${target}', true);
+const proxy = interceptorManager.intercept(targetWrapper, ${JSON.stringify(target)}, true);
 `;
 
     // Exports
-    const exportsCode = targetExports.map(exp => {
-        if (exp === 'default') {
-            return `export default proxy.default;`;
-        }
-        return `export const ${exp} = proxy.${exp};`;
-    }).join('\n');
+    const exportsCode = targetExports
+        .map((exp) => {
+            if (exp === "default") {
+                return `export default proxy.default;`;
+            }
+            return `export const ${exp} = proxy.${exp};`;
+        })
+        .join("\n");
 
     return `
-${imports.join('\n')}
+${imports.join("\n")}
 
-${registrations.join('\n')}
+${registrations.join("\n")}
 
 ${interceptorCode}
 
@@ -264,5 +297,5 @@ ${exportsCode}
 export default {
     registerInterceptors,
     generateInterceptors,
-    KEY_INTERCEPTED
+    KEY_INTERCEPTED,
 };