@schalkneethling/miyagi-core 4.0.2 → 4.2.0

package/lib/render/views/iframe/component.js

@@ -6,6 +6,7 @@ import * as helpers from "../../../helpers.js";
 import validateMocks from "../../../validator/mocks.js";
 import { getComponentData } from "../../../mocks/index.js";
 import { getUserUiConfig, getThemeMode } from "../../helpers.js";
+import resolveAssets from "../../helpers/resolve-assets.js";
 import log from "../../../logger.js";
 
 /**
@@ -216,18 +217,19 @@ async function renderVariations({
 				({ shortPath }) => shortPath === component.paths.dir.short,
 			);
 
+			const componentDeclaredAssets =
+				context.length > 0 ? context[0].$assets || null : null;
+			const { cssFiles, jsFilesHead, jsFilesBody } =
+				resolveAssets(componentDeclaredAssets);
+
 			await res.render(
 				"iframe_component.twig.miyagi",
 				{
 					lang: global.config.ui.lang,
 					variations,
-					cssFiles: global.config.assets.css,
-					jsFilesHead: global.config.assets.js.filter(
-						(entry) => entry.position === "head" || !entry.position,
-					),
-					jsFilesBody: global.config.assets.js.filter(
-						(entry) => entry.position === "body",
-					),
+					cssFiles,
+					jsFilesHead,
+					jsFilesBody,
 					assets: {
 						css: componentsEntry
 							? componentsEntry.assets.css

package/lib/render/views/iframe/variation.standalone.js

@@ -1,12 +1,14 @@
 import path from "path";
 import config from "../../../default-config.js";
 import { getUserUiConfig } from "../../helpers.js";
+import resolveAssets from "../../helpers/resolve-assets.js";
 
 /**
  * @param {object} object - parameter object
  * @param {object} [object.res] - the express response object
  * @param {object} object.component
  * @param {object} object.componentData
+ * @param {object|null} [object.componentDeclaredAssets] - $assets from mocks
  * @param {Function} [object.cb] - callback function
  * @param {object} [object.cookies]
  * @returns {Promise} gets resolved when the variation has been rendered
@@ -15,6 +17,7 @@ export default async function renderIframeVariationStandalone({
 	res,
 	component,
 	componentData,
+	componentDeclaredAssets = null,
 	cb,
 	cookies,
 }) {
@@ -38,17 +41,16 @@ export default async function renderIframeVariationStandalone({
 						({ shortPath }) => shortPath === directoryPath,
 					);
 
+					const { cssFiles, jsFilesHead, jsFilesBody } =
+						resolveAssets(componentDeclaredAssets);
+
 					await res.render(
 						"component_variation.twig.miyagi",
 						{
 							html: result,
-							cssFiles: global.config.assets.css,
-							jsFilesHead: global.config.assets.js.filter(
-								(entry) => entry.position === "head" || !entry.position,
-							),
-							jsFilesBody: global.config.assets.js.filter(
-								(entry) => entry.position === "body",
-							),
+							cssFiles,
+							jsFilesHead,
+							jsFilesBody,
 							assets: {
 								css: componentsEntry
 									? componentsEntry.assets.css

package/lib/state/file-contents.js

@@ -11,6 +11,31 @@ import { marked as Markdown } from "marked";
 import * as helpers from "../helpers.js";
 import log from "../logger.js";
 
+/**
+ * @param {string} fileName
+ * @returns {boolean}
+ */
+function isSchemaFile(fileName) {
+	const schemaFileName = `${global.config.files.schema.name}.${global.config.files.schema.extension}`;
+	return path.basename(fileName) === schemaFileName;
+}
+
+/**
+ * @param {string} fileName
+ * @param {Error & { code?: string }} err
+ */
+function markFileReadError(fileName, err) {
+	if (!global.state?.fileReadErrors || !isSchemaFile(fileName)) {
+		return;
+	}
+
+	global.state.fileReadErrors[fileName] = {
+		type: "schema-parse",
+		code: err?.code || null,
+		message: err?.message || String(err),
+	};
+}
+
 /**
  * Checks if a given array of file paths includes a given file path
  * @param {string} file - file path string
@@ -134,8 +159,13 @@ export const readFile = async function (fileName) {
 		case [".yaml", ".yml"].includes(path.extname(fileName)):
 			{
 				try {
-					return await getYamlFileContent(fileName);
+					const content = await getYamlFileContent(fileName);
+					if (global.state?.fileReadErrors) {
+						delete global.state.fileReadErrors[fileName];
+					}
+					return content;
 				} catch (err) {
+					markFileReadError(fileName, err);
 					log("error", `Error when reading file ${fileName}`, err);
 				}
 			}
@@ -153,8 +183,13 @@ export const readFile = async function (fileName) {
 			[".js", ".mjs"].includes(path.extname(fileName)):
 			{
 				try {
-					return await getJsFileContent(fileName);
+					const content = await getJsFileContent(fileName);
+					if (global.state?.fileReadErrors) {
+						delete global.state.fileReadErrors[fileName];
+					}
+					return content;
 				} catch (err) {
+					markFileReadError(fileName, err);
 					log("error", `Error when reading file ${fileName}`, err);
 				}
 			}
@@ -162,8 +197,13 @@ export const readFile = async function (fileName) {
 		case fileName.endsWith(".json"):
 			{
 				try {
-					return await getParsedJsonFileContent(fileName);
+					const content = await getParsedJsonFileContent(fileName);
+					if (global.state?.fileReadErrors) {
+						delete global.state.fileReadErrors[fileName];
+					}
+					return content;
 				} catch (err) {
+					markFileReadError(fileName, err);
 					log("error", `Error when reading file ${fileName}`, err);
 				}
 			}
@@ -187,6 +227,9 @@ export const readFile = async function (fileName) {
  */
 export const getFileContents = async function (sourceTree) {
 	const fileContents = {};
+	if (global.state) {
+		global.state.fileReadErrors = {};
+	}
 	const paths = await getFilePaths(sourceTree);
 
 	if (paths) {

package/lib/state/index.js

@@ -18,6 +18,7 @@ export default async function setState(methods) {
 	if (!global.state) {
 		global.state = {
 			routes: [],
+			fileReadErrors: {},
 		};
 	}
 

package/lib/validator/mocks.js

@@ -1,4 +1,5 @@
 import jsYaml from "js-yaml";
+import { existsSync } from "node:fs";
 import deepMerge from "deepmerge";
 import log from "../logger.js";
 import { t } from "../i18n/index.js";
@@ -9,31 +10,19 @@ import { t } from "../i18n/index.js";
  * @param {object} component
  * @param {Array} dataArray - an array with mock data
  * @param {boolean} [noCli]
+ * @param {Array<object>} [validSchemas]
  * @returns {null|object[]} null if there is no schema or an array with booleans defining the validity of the entries in the data array
  */
-export default function validateMockData(component, dataArray, noCli) {
+export default function validateMockData(
+	component,
+	dataArray,
+	noCli,
+	validSchemas = [],
+) {
 	const componentSchema =
 		global.state.fileContents[component.paths.schema.full];
 
 	if (componentSchema) {
-		const schemas = [];
-
-		Object.entries(global.state.fileContents).forEach(([key, value]) => {
-			if (
-				key.endsWith(
-					`${global.config.files.schema.name}.${global.config.files.schema.extension}`,
-				)
-			) {
-				const arr = Array.isArray(value) ? value : [value];
-
-				arr.forEach((schema) => {
-					if (schema && componentSchema.$id !== schema.$id) {
-						schemas.push(schema);
-					}
-				});
-			}
-		});
-
 		const validity = [];
 		let validate;
 		let jsonSchemaValidator;
@@ -43,16 +32,19 @@ export default function validateMockData(component, dataArray, noCli) {
 				deepMerge(
 					{
 						allErrors: true,
-						schemas: schemas.map((schema, i) => {
-							if (!schema.$id) {
-								schema.$id = i.toString();
-							}
-							return schema;
-						}),
 					},
 					global.config.schema.options || {},
 				),
 			);
+
+			validSchemas.forEach((entry) => {
+				// Preload only other validated schemas for cross-component $ref resolution.
+				// The current component schema is compiled below and must not be added twice.
+				if (entry?.schemaFile !== component.paths.schema.full && entry?.schema) {
+					jsonSchemaValidator.addSchema(entry.schema);
+				}
+			});
+
 			validate = jsonSchemaValidator.compile(componentSchema);
 		} catch (e) {
 			const message = e.toString();
@@ -95,9 +87,22 @@ export default function validateMockData(component, dataArray, noCli) {
 	}
 
 	if (!global.config.isBuild && !noCli) {
+		const parseError = global.state.fileReadErrors?.[component.paths.schema.full];
+		const schemaExistsOnDisk = existsSync(component.paths.schema.full);
+		const warningMessage = parseError
+			? t("validator.mocks.schemaParseFailed")
+					.replace("{{schemaFile}}", component.paths.schema.short)
+					.replace("{{format}}", "JSON or YAML")
+			: schemaExistsOnDisk
+				? t("validator.mocks.schemaParseFailed")
+						.replace("{{schemaFile}}", component.paths.schema.short)
+						.replace("{{format}}", "JSON or YAML")
+				: t("validator.mocks.schemaMissing")
+						.replace("{{component}}", component.paths.dir.short)
+						.replace("{{schemaFile}}", component.paths.schema.short);
 		log(
 			"warn",
-			`${component.paths.dir.short}: ${t("validator.mocks.noSchemaFound")}`,
+			warningMessage,
 		);
 	}
 

package/lib/validator/schemas.js

@@ -0,0 +1,234 @@
+// @ts-check
+
+import deepMerge from "deepmerge";
+
+const DEFAULT_SCHEMA_VALIDATION_MODE = "collect-all";
+const ALLOWED_SCHEMA_VALIDATION_MODES = new Set(["collect-all", "fail-fast"]);
+
+/**
+ * @returns {"collect-all"|"fail-fast"}
+ */
+export function getSchemaValidationMode() {
+	const mode = global.config.schemaValidationMode ?? DEFAULT_SCHEMA_VALIDATION_MODE;
+
+	if (!ALLOWED_SCHEMA_VALIDATION_MODES.has(mode)) {
+		return DEFAULT_SCHEMA_VALIDATION_MODE;
+	}
+
+	return mode;
+}
+
+/**
+ * @param {object} options
+ * @param {Array<object>} [options.components]
+ * @returns {{ valid: boolean, errors: Array<object>, validSchemas: Array<object> }}
+ */
+export function validateSchemas({ components } = {}) {
+	const validSchemas = [];
+	const errors = [];
+	const componentRoutes =
+		components ??
+		global.state.routes.filter((route) => route.type === "components" && route.paths.tpl);
+	const validator = new global.config.schema.ajv(
+		deepMerge(
+			{
+				allErrors: true,
+			},
+			global.config.schema.options || {},
+		),
+	);
+
+	let pendingSchemas = componentRoutes
+		.map((component, index) => {
+			// Absolute schema file path.
+			const schemaFile = component.paths.schema.full;
+			// Parsed schema from in-memory state cache.
+			const schemaFromState = global.state.fileContents[schemaFile];
+
+			if (!schemaFromState) {
+				return null;
+			}
+
+			const schema = structuredClone(schemaFromState);
+			if (!schema.$id) {
+				schema.$id = component.paths.schema.short || schemaFile || index.toString();
+			}
+
+			return {
+				component: component.paths.dir.short,
+				schemaFile,
+				rawSchema: schemaFromState,
+				schema,
+			};
+		})
+		.filter(Boolean);
+
+	while (pendingSchemas.length > 0) {
+		let progress = false;
+		const retrySchemas = [];
+
+		pendingSchemas.forEach((entry) => {
+			try {
+				validator.compile(entry.schema);
+				if (!validator.getSchema(entry.schema.$id)) {
+					validator.addSchema(entry.schema);
+				}
+				validSchemas.push({
+					component: entry.component,
+					schemaFile: entry.schemaFile,
+					schema: entry.schema,
+				});
+				progress = true;
+			} catch (error) {
+				if (isUnresolvedRefError(error)) {
+					retrySchemas.push(entry);
+					return;
+				}
+
+				errors.push(
+					buildSchemaValidationError({
+						error,
+						component: entry.component,
+						schemaFile: entry.schemaFile,
+						rawSchema: entry.rawSchema,
+					}),
+				);
+			}
+		});
+
+		if (!progress) {
+			retrySchemas.forEach((entry) => {
+				const error = new Error(
+					`can't resolve reference while validating schema ${entry.schemaFile}`,
+				);
+				errors.push(
+					buildSchemaValidationError({
+						error,
+						component: entry.component,
+						schemaFile: entry.schemaFile,
+						rawSchema: entry.rawSchema,
+					}),
+				);
+			});
+			break;
+		}
+
+		pendingSchemas = retrySchemas;
+	}
+
+	return {
+		valid: errors.length === 0,
+		errors,
+		validSchemas,
+	};
+}
+
+/**
+ * @param {object} obj
+ * @param {Error & { errors?: Array<object> }} obj.error
+ * @param {string} obj.component
+ * @param {string} obj.schemaFile
+ * @param {object} obj.rawSchema
+ * @returns {object}
+ */
+function buildSchemaValidationError({ error, component, schemaFile, rawSchema }) {
+	const ajvErrors = Array.isArray(error?.errors) ? error.errors : [];
+	const [firstAjvError] = ajvErrors;
+	const hint = getSchemaHint(rawSchema, ajvErrors);
+	const type = isUnresolvedRefError(error) ? "schema-ref" : "schema";
+
+	return {
+		type,
+		component,
+		schemaFile,
+		message: error?.toString?.() || "Unknown schema validation error",
+		schemaPath: firstAjvError?.schemaPath || "",
+		instancePath: firstAjvError?.instancePath || "",
+		hint,
+		details: ajvErrors.map((entry) => ({
+			keyword: entry.keyword,
+			message: entry.message,
+			schemaPath: entry.schemaPath,
+			instancePath: entry.instancePath,
+			params: entry.params,
+		})),
+	};
+}
+
+/**
+ * @param {object} schema
+ * @param {Array<object>} ajvErrors
+ * @returns {string|undefined}
+ */
+function getSchemaHint(schema, ajvErrors) {
+	if (schema?.properties === null) {
+		return "Hint: `properties` resolves to null. In YAML this often means `properties:` has no nested keys.";
+	}
+
+	if (
+		ajvErrors.some(
+			(error) =>
+				error?.schemaPath?.endsWith("/properties/type") &&
+				error?.instancePath?.includes("/properties/"),
+		)
+	) {
+		return "Hint: check each field `type` value; it must be a valid JSON Schema type.";
+	}
+
+	return undefined;
+}
+
+/**
+ * @param {Error & { message?: string, missingRef?: string, missingSchema?: string, code?: string }} error
+ * @returns {boolean}
+ */
+function isUnresolvedRefError(error) {
+	if (typeof error?.missingRef === "string" && error.missingRef.length > 0) {
+		return true;
+	}
+
+	if (
+		typeof error?.missingSchema === "string" &&
+		error.missingSchema.length > 0
+	) {
+		return true;
+	}
+
+	if (error?.code === "ERR_MISSING_REF") {
+		return true;
+	}
+
+	return /can't resolve reference|missing ref|missing schema/i.test(
+		error?.message || "",
+	);
+}
+
+/**
+ * @param {object} schemaError
+ * @param {object} [options]
+ * @param {boolean} [options.verbose]
+ * @returns {{ type: "schema"|"schema-ref", data: Array<object> }}
+ */
+export function toSchemaValidationResult(schemaError, options = {}) {
+	const useVerbose =
+		options.verbose ?? global.config?.schema?.verbose === true;
+	const formattedError = {
+		message: schemaError.message,
+		component: schemaError.component,
+		schemaFile: schemaError.schemaFile,
+		hint: schemaError.hint,
+	};
+
+	if (useVerbose) {
+		formattedError.schemaPath = schemaError.schemaPath;
+		formattedError.instancePath = schemaError.instancePath;
+		formattedError.details = schemaError.details;
+	}
+
+	return {
+		type: schemaError.type || "schema",
+		data: [
+			formattedError,
+		],
+	};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@schalkneethling/miyagi-core",
-	"version": "4.0.2",
+	"version": "4.2.0",
 	"description": "miyagi is a component development tool for JavaScript template engines.",
 	"main": "index.js",
 	"author": "Schalk Neethling <schalkneethling@duck.com>, Michael Großklaus <mail@mgrossklaus.de> (https://www.mgrossklaus.de)",
@@ -9,7 +9,7 @@
 	"bugs": "https://github.com/miyagi-dev/miyagi/issues",
 	"repository": {
 		"type": "git",
-		"url": "git@github.com:miyagi-dev/miyagi.git"
+		"url": "https://github.com/schalkneethling/miyagi.git"
 	},
 	"type": "module",
 	"keywords": [
@@ -20,7 +20,7 @@
 		"frontend"
 	],
 	"engines": {
-		"node": ">=20.11.0"
+		"node": ">=24"
 	},
 	"files": [
 		"api",
@@ -43,9 +43,10 @@
 		"directory-tree": "^3.5.2",
 		"express": "^5.1.0",
 		"js-yaml": "^4.1.0",
-		"marked": "^16.4.1",
+		"marked": "^17.0.2",
 		"node-watch": "^0.7.4",
-		"twing": "7.2.2",
+		"twing": "7.3.1",
+		"valibot": "^1.2.0",
 		"ws": "^8.18.3",
 		"yargs": "^18.0.0"
 	},
@@ -53,11 +54,13 @@
 		"@eslint/js": "^9.39.2",
 		"@rollup/plugin-node-resolve": "^16.0.3",
 		"@rollup/plugin-terser": "^0.4.4",
+		"@types/js-yaml": "^4.0.9",
 		"@types/node": "^24.10.0",
+		"@types/yargs": "^17.0.35",
 		"@vitest/coverage-v8": "^4.0.6",
 		"cssnano": "^7.1.2",
 		"eslint": "^9.39.0",
-		"eslint-plugin-jsdoc": "^61.1.11",
+		"eslint-plugin-jsdoc": "^62.5.4",
 		"globals": "^15.15.0",
 		"gulp": "^5.0.1",
 		"gulp-postcss": "^10.0.0",
@@ -75,8 +78,7 @@
 		"build": "gulp build",
 		"test": "vitest run --coverage --coverage.include=api --coverage.include=lib",
 		"lint": "stylelint frontend/assets/css/ && eslint lib/ && eslint frontend/assets/js/",
-		"fix": "eslint lib/ --fix && eslint frontend/assets/js/ --fix",
-		"release": "standard-version"
+		"fix": "eslint lib/ --fix && eslint frontend/assets/js/ --fix"
 	},
 	"browserslist": [
 		"last 2 versions",