@schalkneethling/miyagi-core 4.0.2 → 4.2.0

package/lib/drupal/load-assets-config.js

@@ -0,0 +1,94 @@
+import path from "node:path";
+import * as v from "valibot";
+
+const DrupalBlockSchema = v.object({
+	libraries: v.string(),
+	ignorePrefixes: v.optional(v.array(v.string())),
+	mapping: v.optional(v.record(v.string(), v.string())),
+	autoDiscoveryPrefixes: v.optional(v.nullable(v.array(v.string()))),
+	components: v.optional(v.nullable(v.array(v.string()))),
+});
+
+const ConfigSchema = v.object({
+	engine: v.picklist(["drupal"]),
+	drupal: DrupalBlockSchema,
+});
+
+export const NormalizedConfigSchema = v.object({
+	engine: v.string(),
+	libraries: v.optional(v.string()),
+	ignorePrefixes: v.array(v.string()),
+	mapping: v.record(v.string(), v.string()),
+	autoDiscoveryPrefixes: v.nullable(v.array(v.string())),
+	components: v.nullable(v.array(v.string())),
+	dryRun: v.boolean(),
+});
+
+/** @typedef {v.InferOutput<typeof NormalizedConfigSchema>} NormalizedConfig */
+
+/**
+ * Loads the .miyagi-assets.js config and merges CLI overrides.
+ * @param {object} cliArgs
+ * @param {string} [cliArgs.engine] - engine to use (default: "drupal")
+ * @param {string} [cliArgs.config] - path to config file
+ * @param {string} [cliArgs.libraries] - CLI override for libraries path
+ * @param {string[]} [cliArgs.components] - CLI override for components list
+ * @param {string[]} [cliArgs.ignorePrefixes] - CLI override for ignore prefixes
+ * @param {boolean} [cliArgs.dryRun] - dry-run mode
+ * @returns {Promise<NormalizedConfig>} normalized config
+ */
+export async function loadAssetsConfig(cliArgs) {
+	let fileConfig = null;
+
+	const configPath = cliArgs.config || ".miyagi-assets.js";
+
+	try {
+		const resolved = path.resolve(configPath);
+		const mod = await import(resolved);
+		fileConfig = mod.default || mod;
+	} catch {
+		if (!cliArgs.libraries) {
+			throw new Error(
+				`Could not load config file "${configPath}" and no --libraries flag provided.`,
+			);
+		}
+	}
+
+	if (fileConfig) {
+		const result = v.safeParse(ConfigSchema, fileConfig);
+
+		if (!result.success) {
+			const messages = result.issues.map((issue) => {
+				const issuePath =
+					issue.path?.map((path) => path.key).join(".") || "root";
+				return `${issuePath}: ${issue.message}`;
+			});
+			throw new Error(`Invalid config: ${messages.join("; ")}`);
+		}
+
+		const { engine } = result.output;
+		const engineBlock = result.output[engine];
+
+		return {
+			engine,
+			libraries: cliArgs.libraries || engineBlock.libraries,
+			ignorePrefixes:
+				cliArgs.ignorePrefixes || engineBlock.ignorePrefixes || [],
+			mapping: engineBlock.mapping || {},
+			autoDiscoveryPrefixes: engineBlock.autoDiscoveryPrefixes ?? null,
+			components:
+				cliArgs.components || engineBlock.components || null,
+			dryRun: cliArgs.dryRun || false,
+		};
+	}
+
+	return {
+		engine: cliArgs.engine || "drupal",
+		libraries: cliArgs.libraries,
+		ignorePrefixes: cliArgs.ignorePrefixes || [],
+		mapping: {},
+		autoDiscoveryPrefixes: null,
+		components: cliArgs.components || null,
+		dryRun: cliArgs.dryRun || false,
+	};
+}

package/lib/drupal/resolve-library-assets.js

@@ -0,0 +1,189 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+
+/**
+ * @typedef {{src: string, type?: string}} JsEntry
+ * @typedef {{prefix: string, name: string}} DepEntry
+ * @typedef {{css: string[], js: JsEntry[], dependencies: DepEntry[]}} LibraryEntry
+ */
+
+/**
+ * Parses a Drupal *.libraries.yml string into a normalized map.
+ * @param {string} yamlContent - raw YAML string (not a file path)
+ * @returns {Record<string, LibraryEntry>}
+ */
+export function parseLibrariesYaml(yamlContent) {
+	/**
+	 * @type {Record<string, {
+	 *   css?: Record<string, Record<string, object>>,
+	 *   js?: Record<string, {attributes?: {type?: string}}>,
+	 *   dependencies?: string[]
+	 * }>}
+	 */
+	const raw = /** @type {never} */ (yaml.load(yamlContent));
+	/** @type {Record<string, LibraryEntry>} */
+	const map = {};
+
+	for (const [name, entry] of Object.entries(raw)) {
+		const css = entry.css
+			? Object.values(entry.css).flatMap(Object.keys)
+			: [];
+
+		const js = entry.js
+			? Object.entries(entry.js).map(([src, opts]) =>
+				opts?.attributes?.type
+					? { src, type: opts.attributes.type }
+					: { src },
+			)
+			: [];
+
+		const dependencies = (entry.dependencies || [])
+			.filter((dep) => dep.includes("/"))
+			.map((dep) => ({
+				prefix: dep.slice(0, dep.indexOf("/")),
+				name: dep.slice(dep.indexOf("/") + 1),
+			}));
+
+		map[name] = { css, js, dependencies };
+	}
+
+	return map;
+}
+
+/**
+ * Recursively resolves all CSS and JS assets for a library, depth-first.
+ * Dependencies are collected before the component's own assets to preserve
+ * the CSS cascade (base styles before component styles) and ensure JS
+ * dependencies are available before scripts that rely on them.
+ * @param {string} libraryName
+ * @param {Record<string, LibraryEntry>} librariesMap - output of parseLibrariesYaml
+ * @param {string[]} ignorePrefixes - dependency prefixes to skip
+ * @returns {{css: string[], js: JsEntry[]}}
+ */
+export function resolveComponentAssets(
+	libraryName,
+	librariesMap,
+	ignorePrefixes,
+) {
+	const cssSet = [];
+	const jsSet = [];
+	const resolved = new Set();
+
+	/**
+	 * @param {string} name
+	 * @param {Set<string>} ancestors
+	 */
+	function walk(name, ancestors) {
+		if (ancestors.has(name)) {
+			console.warn(
+				`Circular dependency detected: "${name}" already in chain.`,
+			);
+			return;
+		}
+
+		if (resolved.has(name)) {
+			return;
+		}
+
+		const lib = librariesMap[name];
+		if (!lib) {
+			console.warn(
+				`Dependency "${name}" not found in libraries — skipping.`,
+			);
+			return;
+		}
+
+		const chain = new Set(ancestors);
+		chain.add(name);
+
+		for (const dep of lib.dependencies) {
+			if (ignorePrefixes.includes(dep.prefix)) {
+				continue;
+			}
+			walk(dep.name, chain);
+		}
+
+		for (const cssFile of lib.css) {
+			if (!cssSet.includes(cssFile)) {
+				cssSet.push(cssFile);
+			}
+		}
+
+		for (const jsEntry of lib.js) {
+			if (!jsSet.some((entry) => entry.src === jsEntry.src)) {
+				jsSet.push(jsEntry);
+			}
+		}
+
+		resolved.add(name);
+	}
+
+	walk(libraryName, new Set());
+	return { css: cssSet, js: jsSet };
+}
+
+const DEFAULT_PREFIXES = ["element-", "pattern-", "template-", "component-"];
+
+/**
+ * Maps a Drupal library name to a miyagi component folder path.
+ * Uses explicit mapping first, falls back to auto-discovery.
+ * @param {string} libraryName
+ * @param {Record<string, string>} mapping - explicit library-to-folder mapping
+ * @param {string} componentsFolder - root components folder path
+ * @param {string[]} [autoDiscoveryPrefixes] - prefixes to strip when matching folder names
+ * @returns {string|null} component folder relative path, or null if not found
+ */
+export function mapLibraryToComponent(
+	libraryName,
+	mapping,
+	componentsFolder,
+	autoDiscoveryPrefixes = DEFAULT_PREFIXES,
+) {
+	if (mapping[libraryName]) {
+		return mapping[libraryName];
+	}
+
+	const candidates = [libraryName];
+
+	for (const prefix of autoDiscoveryPrefixes) {
+		if (libraryName.startsWith(prefix)) {
+			candidates.push(libraryName.slice(prefix.length));
+		}
+	}
+
+	try {
+		/** @type {string[]} */
+		const searchDirs = [componentsFolder];
+		while (searchDirs.length > 0) {
+			const dir = /** @type {string} */ (searchDirs.pop());
+
+			if (!fs.existsSync(dir)) {
+				continue;
+			}
+
+			const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+			for (const entry of entries) {
+				if (!entry.isDirectory()) {
+					continue;
+				}
+
+				if (candidates.includes(entry.name)) {
+					return path.relative(
+						componentsFolder,
+						path.join(dir, entry.name),
+					);
+				}
+				searchDirs.push(path.join(dir, entry.name));
+			}
+		}
+	} catch {
+		// Swallow filesystem errors (missing/unreadable dirs) intentionally.
+		// Caller handles null return with a user-facing warning.
+	}
+
+	return null;
+}

package/lib/i18n/en.js

@@ -70,6 +70,10 @@ export default {
 			invalid: "Mock data does not match schema file.",
 			noSchemaFound:
 				"No schema file found or the schema file could not be parsed as valid JSON.",
+			schemaMissing:
+				"Component {{component}} has no schema file (expected: {{schemaFile}}). Consider adding it to components.ignores if this is expected.",
+			schemaParseFailed:
+				"Schema file {{schemaFile}} could not be parsed as {{format}}.",
 		},
 	},
 	serverStarted: "Running miyagi server at http://localhost:{{port}}",

package/lib/index.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * The miyagi module
  * @module index
@@ -9,7 +11,11 @@ import log from "./logger.js";
 import yargs from "./init/args.js";
 import mockGenerator from "./generator/mocks.js";
 import getConfig from "./config.js";
-import { lint, component as createComponentViaCli } from "./cli/index.js";
+import {
+	lint,
+	component as createComponentViaCli,
+	drupalAssets,
+} from "./cli/index.js";
 import apiApp from "../api/app.js";
 
 /**
@@ -57,6 +63,14 @@ function argsIncludeLint(args) {
 	return args._.includes("lint");
 }
 
+/**
+ * @param {object} args
+ * @returns {boolean}
+ */
+function argsIncludeDrupalAssets(args) {
+	return args._.includes("drupal-assets");
+}
+
 /**
  * Runs the mock generator
  * @param {object} config - the user configuration object
@@ -97,26 +111,35 @@ export default async function Miyagi(cmd, { isBuild: isApiBuild } = {}) {
 	let isComponentGenerator;
 	let isMockGenerator;
 	let isLinter;
+	let isDrupalAssets;
 
 	if (cmd) {
 		isBuild = cmd === "build";
 	} else {
-		args = yargs.argv;
+		args = await yargs.argv;
 		isServer = argsIncludeServer(args);
 		isBuild = argsIncludeBuild(args);
 		isComponentGenerator = argsIncludeComponentGenerator(args);
 		isMockGenerator = argsIncludeMockGenerator(args);
 		isLinter = argsIncludeLint(args);
+		isDrupalAssets = argsIncludeDrupalAssets(args);
 	}
 
-	if (args.verbose) {
-		process.env.VERBOSE = args.verbose;
+	if (args && args.verbose) {
+		process.env.VERBOSE = String(args.verbose);
 	}
 
 	if (isLinter) {
 		return lint(args);
 	}
 
+	if (isDrupalAssets) {
+		process.env.NODE_ENV = "development";
+		global.config = await getConfig(args);
+		await drupalAssets(args);
+		process.exit();
+	}
+
 	if (isBuild || isComponentGenerator || isServer || isMockGenerator) {
 		if (isBuild) {
 			process.env.NODE_ENV = "production";

package/lib/init/args.js

@@ -45,6 +45,44 @@ export default yargs(hideBin(process.argv))
 		"lint",
 		"Validates if the component's mock data matches its JSON schema",
 	)
+	.command(
+		"drupal-assets",
+		"Resolves Drupal *.libraries.yml dependencies and updates component $assets in mock files",
+		{
+			engine: {
+				alias: "e",
+				description: "Engine to use for asset resolution",
+				type: "string",
+				choices: ["drupal"],
+				default: "drupal",
+			},
+			config: {
+				description: "Path to .miyagi-assets.js config file",
+				type: "string",
+				default: ".miyagi-assets.js",
+			},
+			libraries: {
+				alias: "l",
+				description: "Path to *.libraries.yml (overrides config)",
+				type: "string",
+			},
+			components: {
+				alias: "c",
+				description: "Library names to process (space-separated)",
+				type: "array",
+			},
+			"ignore-prefixes": {
+				description:
+					'Dependency prefixes to skip (e.g. "core" to ignore core/jquery)',
+				type: "array",
+			},
+			"dry-run": {
+				description: "Print resolved $assets without writing files",
+				type: "boolean",
+				default: false,
+			},
+		},
+	)
 	.help()
 	.version(pkgJson.version)
 	.alias("help", "h")

package/lib/init/config.js

@@ -7,6 +7,7 @@ import deepMerge from "deepmerge";
 import log from "../logger.js";
 import appConfig from "../default-config.js";
 import { t, available as langAvailable } from "../i18n/index.js";
+import { LINT_LOG_LEVELS } from "../constants/lint-log-levels.js";
 import fs from "fs";
 import path from "path";
 
@@ -216,6 +217,23 @@ export default (userConfig = {}) => {
 			);
 		}
 
+		if (config.assets.shared) {
+			if (config.assets.shared.css) {
+				config.assets.shared.css = getCssFilesArray(
+					config.assets.shared.css,
+					manifest,
+					config.assets.root,
+				);
+			}
+			if (config.assets.shared.js) {
+				config.assets.shared.js = getJsFilesArray(
+					config.assets.shared.js,
+					manifest,
+					config.assets.root,
+				);
+			}
+		}
+
 		if (!config.assets.customProperties) {
 			config.assets.customProperties = {};
 		}
@@ -309,6 +327,14 @@ export default (userConfig = {}) => {
 		merged.ui.lang = "en";
 	}
 
+	if (!Object.values(LINT_LOG_LEVELS).includes(merged.lint.logLevel)) {
+		log(
+			"warn",
+			`Invalid config.lint.logLevel "${merged.lint.logLevel}". Falling back to "${defaultUserConfig.lint.logLevel}".`,
+		);
+		merged.lint.logLevel = defaultUserConfig.lint.logLevel;
+	}
+
 	return merged;
 };
 

package/lib/init/router.js

@@ -222,6 +222,7 @@ export default function Router() {
 					res,
 					component: routesEntry,
 					componentData: data?.resolved ?? {},
+					componentDeclaredAssets: data?.$assets || null,
 					cookies: req.cookies,
 				});
 			}

package/lib/init/static.js

@@ -75,6 +75,35 @@ function registerUserFiles(files) {
 	}
 }
 
+/**
+ * Registers static routes for assets.shared CSS and JS files.
+ * @returns {void}
+ */
+function registerSharedFiles() {
+	const { assets } = global.config;
+
+	if (!assets?.shared) return;
+
+	for (const file of assets.shared.css || []) {
+		if (file.startsWith("https://")) continue;
+
+		global.app.use(
+			path.join("/", path.dirname(file)),
+			express.static(path.join(assets.root, path.dirname(file))),
+		);
+	}
+
+	for (const file of assets.shared.js || []) {
+		const src = file.src || file;
+		if (src.startsWith("https://")) continue;
+
+		global.app.use(
+			path.join("/", path.dirname(src)),
+			express.static(path.join(assets.root, path.dirname(src))),
+		);
+	}
+}
+
 /**
  * @returns {void}
  */
@@ -128,6 +157,7 @@ export default function initStatic() {
 	registerUserComponentAssets();
 	registerUserFiles("css");
 	registerUserFiles("js");
+	registerSharedFiles();
 	registerCustomPropertyFiles();
 	registerAssetFolder();
 }

package/lib/init/watcher.js

@@ -292,6 +292,25 @@ export default function Watcher(server) {
 
 	const { components, docs, assets, extensions } = global.config;
 
+	const sharedCssToWatch = (assets.shared?.css || [])
+		.filter(
+			(f) =>
+				!f.startsWith("http://") &&
+				!f.startsWith("https://") &&
+				!f.startsWith("://"),
+		)
+		.map((f) => path.join(global.config.assets.root, f));
+
+	const sharedJsToWatch = (assets.shared?.js || [])
+		.map((file) => file.src || file)
+		.filter(
+			(f) =>
+				!f.startsWith("http://") &&
+				!f.startsWith("https://") &&
+				!f.startsWith("://"),
+		)
+		.map((f) => path.join(global.config.assets.root, f));
+
 	const foldersToWatch = [
 		...assets.folder.map((f) => path.join(global.config.assets.root, f)),
 		...assets.css
@@ -311,6 +330,8 @@ export default function Watcher(server) {
 					!f.startsWith("://"),
 			)
 			.map((f) => path.join(global.config.assets.root, f)),
+		...sharedCssToWatch,
+		...sharedJsToWatch,
 	];
 
 	if (components.folder) {

package/lib/logger.js

@@ -1,3 +1,8 @@
+import {
+	LINT_LOG_LEVEL_ORDER,
+	LINT_LOG_LEVELS,
+} from "./constants/lint-log-levels.js";
+
 const COLORS = {
 	grey: "\x1b[90m",
 	red: "\x1b[31m",
@@ -21,8 +26,17 @@ const TYPES = {
  * @param {string|Error} [verboseMessage]
  */
 export default function log(type, message, verboseMessage) {
-	if (process.env.MIYAGI_JS_API) return;
-	if (!(type in TYPES)) return;
+	if (process.env.MIYAGI_JS_API) {
+		return;
+	}
+
+	if (!(type in TYPES)) {
+		return;
+	}
+
+	if (!shouldLogType(type)) {
+		return;
+	}
 
 	const date = new Date();
 	const year = date.getFullYear();
@@ -59,6 +73,27 @@ export default function log(type, message, verboseMessage) {
 	}
 }
 
+/**
+ * @param {string} type
+ * @returns {boolean}
+ */
+function shouldLogType(type) {
+	if (process.env.MIYAGI_LOG_CONTEXT !== "lint") {
+		return true;
+	}
+
+	const configuredLevel = process.env.MIYAGI_LOG_LEVEL || "error";
+	const normalizedType = type === "success" ? "info" : type;
+	const configuredLevelValue =
+		LINT_LOG_LEVEL_ORDER[configuredLevel] ??
+		LINT_LOG_LEVEL_ORDER[LINT_LOG_LEVELS.ERROR];
+	const typeLevelValue =
+		LINT_LOG_LEVEL_ORDER[normalizedType] ??
+		LINT_LOG_LEVEL_ORDER[LINT_LOG_LEVELS.INFO];
+
+	return typeLevelValue <= configuredLevelValue;
+}
+
 /**
  * @param {string} color
  * @param {string} str

package/lib/mocks/get.js

@@ -22,6 +22,7 @@ export const getComponentData = async function getComponentData(component) {
 
 	if (componentJson) {
 		context = [];
+		const componentDeclaredAssets = componentJson.$assets || null;
 		let componentData = helpers.removeInternalKeys(componentJson);
 		const rootData = helpers.cloneDeep(componentData);
 		const componentVariations = componentJson.$variants;
@@ -55,6 +56,7 @@ export const getComponentData = async function getComponentData(component) {
 						resolved: resolved,
 						raw: merged,
 						name: variationJson.$name,
+						$assets: componentDeclaredAssets,
 					};
 				}
 			}
@@ -67,6 +69,7 @@ export const getComponentData = async function getComponentData(component) {
 						resolved: data.resolved,
 						raw: data.merged,
 						name: componentJson.$name || config.defaultVariationName,
+						$assets: componentDeclaredAssets,
 					});
 				}
 			}
@@ -85,6 +88,7 @@ export const getComponentData = async function getComponentData(component) {
 					resolved: componentJson.$hidden ? {} : resolved,
 					raw: componentJson.$hidden ? {} : merged,
 					name: componentJson.$name || config.defaultVariationName,
+					$assets: componentDeclaredAssets,
 				});
 			}
 

package/lib/render/helpers/resolve-assets.js

@@ -0,0 +1,58 @@
+/**
+ * Resolves the final CSS and JS asset lists for a component render.
+ *
+ * Resolution logic:
+ * - If componentAssets ($assets from mocks) is provided:
+ *     shared + componentAssets
+ * - Else if isolateComponents is true:
+ *     shared only
+ * - Else (legacy fallback):
+ *     global.config.assets.css / .js
+ * @param {object|null|undefined} componentAssets - the $assets declaration from mocks, or null/undefined
+ * @returns {{ cssFiles: string[], jsFilesHead: object[], jsFilesBody: object[] }}
+ */
+export default function resolveAssets(componentAssets) {
+	const { shared, isolateComponents, css, js } = global.config.assets;
+
+	if (componentAssets) {
+		const mergedCss = [
+			...shared.css,
+			...(componentAssets.css || []),
+		];
+		const mergedJs = [
+			...shared.js,
+			...(componentAssets.js || []),
+		];
+
+		return {
+			cssFiles: mergedCss,
+			jsFilesHead: mergedJs.filter(
+				(entry) => entry.position === "head" || !entry.position,
+			),
+			jsFilesBody: mergedJs.filter(
+				(entry) => entry.position === "body",
+			),
+		};
+	}
+
+	if (isolateComponents) {
+		return {
+			cssFiles: [...shared.css],
+			jsFilesHead: shared.js.filter(
+				(entry) => entry.position === "head" || !entry.position,
+			),
+			jsFilesBody: shared.js.filter(
+				(entry) => entry.position === "body",
+			),
+		};
+	}
+
+	// Legacy fallback: return all global assets
+	return {
+		cssFiles: css,
+		jsFilesHead: js.filter(
+			(entry) => entry.position === "head" || !entry.position,
+		),
+		jsFilesBody: js.filter((entry) => entry.position === "body"),
+	};
+}