@schalkneethling/miyagi-core 4.1.1 → 4.2.0

package/api/index.js

@@ -7,6 +7,11 @@ import build from "../lib/build/index.js";
 import generateMockData from "../lib/generator/mocks.js";
 import generateComponent from "../lib/generator/component.js";
 import validateMockData from "../lib/validator/mocks.js";
+import {
+	getSchemaValidationMode,
+	toSchemaValidationResult,
+	validateSchemas,
+} from "../lib/validator/schemas.js";
 
 /**
  * @param {object} obj
@@ -172,14 +177,44 @@ export const createComponent = async ({ component, only = [], skip = [] }) => {
 
 export const lintComponents = async () => {
 	global.app = await init("api");
-	const promises = [];
+	const mode = getSchemaValidationMode();
+	const components = global.state.routes.filter((route) => route.paths.tpl);
+	const schemaValidation = validateSchemas({
+		components,
+	});
+	const schemaErrorsByComponent = new Map();
+
+	schemaValidation.errors.forEach((entry) => {
+		if (!schemaErrorsByComponent.has(entry.component)) {
+			schemaErrorsByComponent.set(entry.component, []);
+		}
+		schemaErrorsByComponent
+			.get(entry.component)
+			.push(toSchemaValidationResult(entry));
+	});
 
-	global.state.routes.forEach((route) => {
-		if (route.paths.tpl) {
-			promises.push(
+	if (mode === "fail-fast" && schemaValidation.errors.length > 0) {
+		return {
+			success: false,
+			data: getLintComponentErrorsInRouteOrder({
+				components,
+				errorMap: schemaErrorsByComponent,
+			}),
+		};
+	}
+
+	const promises = components
+		.filter((route) => !schemaErrorsByComponent.has(route.paths.dir.short))
+		.map(
+			(route) =>
 				new Promise((resolve) => {
 					getComponentData(route).then((data) => {
-						const validation = validateMockData(route, data || [], true);
+						const validation = validateMockData(
+							route,
+							data || [],
+							true,
+							schemaValidation.validSchemas,
+						);
 
 						resolve({
 							component: route.alias,
@@ -187,13 +222,25 @@ export const lintComponents = async () => {
 						});
 					});
 				}),
-			);
-		}
-	});
+		);
 
 	return await Promise.all(promises)
 		.then((res) => {
-			const errors = res.filter((result) => result?.errors?.length > 0);
+			res.forEach((result) => {
+				if (!result?.errors?.length) {
+					return;
+				}
+				const componentErrors = schemaErrorsByComponent.get(result.component) || [];
+				schemaErrorsByComponent.set(result.component, [
+					...componentErrors,
+					...result.errors,
+				]);
+			});
+
+			const errors = getLintComponentErrorsInRouteOrder({
+				components,
+				errorMap: schemaErrorsByComponent,
+			});
 
 			return {
 				success: errors.length === 0,
@@ -216,8 +263,26 @@ export const lintComponent = async ({ component }) => {
 			message: `The component ${component} does not seem to exist.`,
 		};
 
+	const allSchemaValidation = validateSchemas({
+		components: [componentObject],
+	});
+
+	if (allSchemaValidation.errors.length > 0) {
+		return {
+			success: false,
+			data: allSchemaValidation.errors.map((entry) =>
+				toSchemaValidationResult(entry),
+			),
+		};
+	}
+
 	const data = await getComponentData(componentObject);
-	const errors = validateMockData(componentObject, data, true);
+	const errors = validateMockData(
+		componentObject,
+		data || [],
+		true,
+		allSchemaValidation.validSchemas,
+	);
 
 	return {
 		success: errors === null || errors?.length === 0,
@@ -234,3 +299,26 @@ function getComponentsObject(component) {
 		(route) => route.paths.dir.short === component,
 	);
 }
+
+/**
+ * @param {object} params
+ * @param {Array<object>} params.components
+ * @param {Map<string, Array<object>>} params.errorMap
+ * @returns {Array<object>}
+ */
+function getLintComponentErrorsInRouteOrder({ components, errorMap }) {
+	return components
+		.map((route) => {
+			const componentErrors = errorMap.get(route.alias) || [];
+
+			if (componentErrors.length === 0) {
+				return null;
+			}
+
+			return {
+				component: route.alias,
+				errors: componentErrors,
+			};
+		})
+		.filter(Boolean);
+}

package/lib/cli/lint.js

@@ -4,6 +4,11 @@ import getConfig from "../config.js";
 import log from "../logger.js";
 import { getComponentData } from "../mocks/index.js";
 import validateMockData from "../validator/mocks.js";
+import {
+	getSchemaValidationMode,
+	toSchemaValidationResult,
+	validateSchemas,
+} from "../validator/schemas.js";
 import { t } from "../i18n/index.js";
 
 /**
@@ -14,6 +19,8 @@ export default async function lint(args) {
 
 	const componentArg = args._.slice(1)[0];
 	const config = await getConfig(args);
+	process.env.MIYAGI_LOG_CONTEXT = "lint";
+	process.env.MIYAGI_LOG_LEVEL = config.lint?.logLevel || "error";
 	global.app = await init(config);
 
 	if (componentArg) {
@@ -23,8 +30,20 @@ export default async function lint(args) {
 		);
 
 		if (component) {
+			const schemaValidation = validateSchemas({
+				components: [component],
+			});
+
+			if (schemaValidation.errors.length > 0) {
+				reportSchemaErrors(schemaValidation.errors);
+				process.exit(1);
+			}
+
+			log("success", "All schemas valid.");
+
 			await validateComponentMockData({
 				component,
+				validSchemas: schemaValidation.validSchemas,
 			});
 		} else {
 			log("error", `The component ${componentArg} does not seem to exist.`);
@@ -40,81 +59,90 @@ export default async function lint(args) {
  */
 async function validateAllMockData(exitProcess = true) {
 	log("info", t("linter.all.start"));
+	const mode = getSchemaValidationMode();
+	const components = global.state.routes.filter(
+		(route) => route.type === "components" && route.paths.tpl,
+	);
+	const schemaValidation = validateSchemas({
+		components,
+	});
+	const invalidSchemaComponents = new Set(
+		schemaValidation.errors.map((entry) => entry.component),
+	);
 
-	const promises = [];
-
-	global.state.routes.forEach((route) => {
-		if (route.type === "components") {
-			promises.push(
-				new Promise((resolve, reject) => {
-					validateComponentMockData({
-						component: route,
-						silent: true,
-						exitProcess: false,
-					})
-						.then((result) => resolve(result))
-						.catch((err) => {
-							console.error(err);
-							reject();
-						});
-				}),
-			);
+	if (schemaValidation.errors.length === 0) {
+		log("success", "All schemas valid.");
+	}
+
+	if (schemaValidation.errors.length > 0 && mode === "fail-fast") {
+		reportSchemaErrors(schemaValidation.errors);
+		log(
+			"error",
+			schemaValidation.errors.length === 1
+				? t("linter.all.schema.invalid.one")
+				: t("linter.all.schema.invalid.other").replace(
+						"{{amount}}",
+						schemaValidation.errors.length,
+					),
+		);
+		if (exitProcess) {
+			process.exit(1);
 		}
-	});
+		return;
+	}
 
-	Promise.all(promises)
-		.then((results) => {
-			const mockInvalidResults = results.filter(
-				(result) => result?.valid === false && result.type === "mocks",
-			);
-			const schemaInvalidResults = results.filter(
-				(result) => result?.valid === false && result.type === "schema",
-			);
+	const results = await Promise.all(
+		components
+			.filter((route) => !invalidSchemaComponents.has(route.paths.dir.short))
+			.map((component) =>
+				validateComponentMockData({
+					component,
+					silent: true,
+					exitProcess: false,
+					validSchemas: schemaValidation.validSchemas,
+				}),
+			),
+	);
+	const mockInvalidResults = results.filter(
+		(result) => result?.valid === false && result.type === "mocks",
+	);
 
-			if (
-				mockInvalidResults.length === 0 &&
-				schemaInvalidResults.length === 0
-			) {
-				log("success", t("linter.all.valid"));
-				if (exitProcess) {
-					process.exit(0);
-				}
-			}
+	if (mode === "collect-all" && schemaValidation.errors.length > 0) {
+		reportSchemaErrors(schemaValidation.errors);
+		log(
+			"error",
+			schemaValidation.errors.length === 1
+				? t("linter.all.schema.invalid.one")
+				: t("linter.all.schema.invalid.other").replace(
+						"{{amount}}",
+						schemaValidation.errors.length,
+					),
+		);
+	}
 
-			if (schemaInvalidResults.length > 0) {
-				log(
-					"error",
-					schemaInvalidResults.length === 1
-						? t("linter.all.schema.invalid.one")
-						: t("linter.all.schema.invalid.other").replace(
-								"{{amount}}",
-								schemaInvalidResults.length,
-							),
-				);
-			}
+	if (mockInvalidResults.length > 0) {
+		log(
+			"error",
+			mockInvalidResults.length === 1
+				? t("linter.all.mocks.invalid.one")
+				: t("linter.all.mocks.invalid.other").replace(
+						"{{amount}}",
+						mockInvalidResults.length,
+					),
+		);
+	}
 
-			if (mockInvalidResults.length > 0) {
-				log(
-					"error",
-					mockInvalidResults.length === 1
-						? t("linter.all.mocks.invalid.one")
-						: t("linter.all.mocks.invalid.other").replace(
-								"{{amount}}",
-								mockInvalidResults.length,
-							),
-				);
-			}
+	if (mockInvalidResults.length === 0 && schemaValidation.errors.length === 0) {
+		log("success", t("linter.all.valid"));
+		if (exitProcess) {
+			process.exit(0);
+		}
+		return;
+	}
 
-			if (exitProcess) {
-				process.exit(1);
-			}
-		})
-		.catch((err) => {
-			console.error(err);
-			if (exitProcess) {
-				process.exit(1);
-			}
-		});
+	if (exitProcess) {
+		process.exit(1);
+	}
 }
 
 /**
@@ -122,12 +150,14 @@ async function validateAllMockData(exitProcess = true) {
  * @param {object} obj.component
  * @param {boolean} [obj.silent]
  * @param {boolean} [obj.exitProcess]
+ * @param {Array<object>} [obj.validSchemas]
  * @returns {Promise<object|null>}
  */
 async function validateComponentMockData({
 	component,
 	silent,
 	exitProcess = true,
+	validSchemas = [],
 }) {
 	if (!silent) {
 		log(
@@ -139,42 +169,60 @@ async function validateComponentMockData({
 		);
 	}
 
-	const data = await getComponentData(component);
+	const data = (await getComponentData(component)) || [];
 
-	if (data) {
-		for (const { messages } of data) {
+	if (data.length > 0) {
+		for (const { messages = [] } of data) {
 			for (const { type, text, verbose } of messages) {
 				log(type, text, verbose);
 			}
 		}
+	}
 
-		const results = validateMockData(component, data);
+	const results = validateMockData(component, data, false, validSchemas);
 
-		if (!results) return null;
+	if (!results) return null;
 
-		if (results.length === 0) {
-			if (!silent) {
-				log("success", t("linter.component.valid"));
-			}
+	if (results.length === 0) {
+		if (!silent) {
+			log("success", t("linter.component.valid"));
+		}
 
-			if (exitProcess) {
-				process.exit(0);
-			} else {
-				return {
-					valid: true,
-				};
-			}
-		} else {
-			if (exitProcess) {
-				process.exit(0);
-			} else {
-				return {
-					valid: false,
-					type: results[0].type,
-				};
-			}
+		if (exitProcess) {
+			process.exit(0);
 		}
+
+		return {
+			valid: true,
+		};
 	}
 
-	return null;
+	if (exitProcess) {
+		process.exit(1);
+	}
+
+	return {
+		valid: false,
+		type: results[0].type,
+	};
+}
+
+/**
+ * @param {Array<object>} schemaErrors
+ */
+function reportSchemaErrors(schemaErrors) {
+	schemaErrors.forEach((entry) => {
+		const result = toSchemaValidationResult(entry);
+		log("error", `${entry.component}:\n${result.data[0].message}`);
+		log("error", `schema: ${entry.schemaFile}`);
+		if (entry.schemaPath || entry.instancePath) {
+			log(
+				"error",
+				`schemaPath: ${entry.schemaPath || "-"} | instancePath: ${entry.instancePath || "-"}`,
+			);
+		}
+		if (entry.hint) {
+			log("warn", entry.hint);
+		}
+	});
 }

package/lib/constants/lint-log-levels.js

@@ -0,0 +1,11 @@
+export const LINT_LOG_LEVELS = Object.freeze({
+	ERROR: "error",
+	WARN: "warn",
+	INFO: "info",
+});
+
+export const LINT_LOG_LEVEL_ORDER = Object.freeze({
+	[LINT_LOG_LEVELS.ERROR]: 0,
+	[LINT_LOG_LEVELS.WARN]: 1,
+	[LINT_LOG_LEVELS.INFO]: 2,
+});

package/lib/default-config.js

@@ -46,6 +46,9 @@ export default {
 			render: null,
 			options: {},
 		},
+		lint: {
+			logLevel: "error",
+		},
 		extensions: [],
 		files: {
 			css: {
@@ -96,7 +99,9 @@ export default {
 		},
 		schema: {
 			ajv: AJV,
+			verbose: false,
 		},
+		schemaValidationMode: "collect-all",
 	},
 	projectName: "miyagi",
 	defaultPort: 5000,

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/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";
 
@@ -326,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/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/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.1.1",
+	"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)",