@react-querybuilder/core 8.14.3 → 8.15.0

package/dist/formatQuery.mjs

@@ -1,7 +1,7 @@
-import { D as toArray, O as trimIfString, S as toFlatOptionArray, T as parseNumber, _ as shouldRenderAsNumber, a as getNLTranslataion, c as isValidValue, d as mapSQLOperator, f as mongoOperators, g as processMatchMode, h as prismaOperators, i as defaultNLTranslations, l as isValueProcessorLegacy, m as numerifyValues, n as bigIntJsonStringifyReplacer, o as getQuoteFieldNamesWithArray, p as normalizeConstituentWordOrder, r as celCombinatorMap, s as getQuotedFieldName, t as bigIntJsonParseReviver, u as jsonLogicAdditionalOperators, v as getParseNumberMethod, w as toFullOptionList, y as getOption } from "./utils-BlMGIhvx.mjs";
-import { a as isRuleGroupTypeIC, c as nullOrUndefinedOrEmpty, i as isRuleGroupType, o as isPojo, r as isRuleGroup, s as lc } from "./objectUtils-C0WB-8ex.mjs";
+import { D as toArray, O as trimIfString, S as toFlatOptionArray, T as parseNumber, _ as shouldRenderAsNumber, a as getNLTranslataion, c as isValidValue, d as mapSQLOperator, f as mongoOperators, g as processMatchMode, h as prismaOperators, i as defaultNLTranslations, l as isValueProcessorLegacy, m as numerifyValues, n as bigIntJsonStringifyReplacer, o as getQuoteFieldNamesWithArray, p as normalizeConstituentWordOrder, r as celCombinatorMap, s as getQuotedFieldName, t as bigIntJsonParseReviver, u as jsonLogicAdditionalOperators, v as getParseNumberMethod, w as toFullOptionList, y as getOption } from "./utils-ChLG90DP.mjs";
+import { a as isRuleGroupTypeIC, c as nullOrUndefinedOrEmpty, i as isRuleGroupType, l as numericRegex, o as isPojo, r as isRuleGroup, s as lc } from "./objectUtils-D96eEEzL.mjs";
 import { transformQuery } from "./transformQuery.mjs";
-import { t as convertFromIC } from "./convertQuery-CeJSNn37.mjs";
+import { t as convertFromIC } from "./convertQuery-BeJJH9BI.mjs";
 //#region src/utils/isRuleOrGroupValid.ts
 /**
 * Determines if an object is useful as a validation result.
@@ -19,7 +19,7 @@ const isRuleOrGroupValid = (rg, validationResult, validator) => {
 	if (typeof validator === "function" && !isRuleGroup(rg)) {
 		const vr = validator(rg);
 		if (typeof vr === "boolean") return vr;
-		// istanbul ignore else
+		// v8 ignore else
 		if (isValidationResult(vr)) return vr.valid;
 	}
 	return true;
@@ -173,7 +173,8 @@ const mongoDbFallback = { $and: [{ $expr: true }] };
 * @group Export
 */
 const defaultRuleGroupProcessorMongoDBQuery = (ruleGroup, options, meta) => {
-	const { fields, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap } = options;
+	const { context, fields, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap } = options;
+	const { inExpressionContext } = context ?? {};
 	const processRuleGroup = (rg, outermost) => {
 		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermost ? mongoDbFallback : false;
 		const combinator = `$${lc(rg.combinator)}`;
@@ -197,7 +198,7 @@ const defaultRuleGroupProcessorMongoDBQuery = (ruleGroup, options, meta) => {
 			}, meta);
 		}).filter(Boolean);
 		const result = expressions.length > 0 ? expressions.length === 1 && !hasChildRules ? expressions[0] : { [combinator]: expressions } : mongoDbFallback;
-		return rg.not ? { $not: result } : result;
+		return rg.not ? inExpressionContext ? { $not: result } : { $nor: [result] } : result;
 	};
 	return processRuleGroup(convertFromIC(ruleGroup), true);
 };
@@ -238,7 +239,8 @@ const defaultRuleProcessorMongoDBQuery = (rule, options = {}) => {
 			ruleProcessor: defaultRuleProcessorMongoDBQuery,
 			context: {
 				...options.context,
-				avoidFieldsAsKeys: true
+				avoidFieldsAsKeys: true,
+				inExpressionContext: true
 			}
 		});
 		const filteredCount = { $size: { $ifNull: [{ $filter: {
@@ -541,22 +543,22 @@ const defaultValueProcessorByRule = ({ operator, value, valueSource }, { escapeQ
 * @group Export
 */
 const defaultRuleProcessorDrizzle = (rule, _options) => {
-	const opts = _options ?? (	/* istanbul ignore next */ {});
-	// istanbul ignore next
+	const opts = _options ?? (	/* v8 ignore start -- @preserve */ {});
+	// v8 ignore next
 	const { parseNumbers, preserveValueOrder, context = {} } = opts;
 	const { columns, drizzleOperators, useRawFields } = context;
-	if (!columns || !drizzleOperators) return;
+	if (!columns || !drizzleOperators) return void 0;
 	const { between, eq, gt, gte, inArray, isNotNull, isNull, like, lt, lte, ne, notBetween, notInArray, notLike, sql } = drizzleOperators;
 	const { field, operator, value, valueSource } = rule;
 	const column = useRawFields && /[a-z][a-z0-9]*/i.test(field) ? sql.raw(field) : columns[field];
 	const operatorLC = lc(operator);
 	const valueIsField = valueSource === "field";
 	const asFieldOrValue = (v) => valueIsField ? columns[v] : v;
-	if (!column) return;
+	if (!column) return void 0;
 	const matchEval = processMatchMode(rule);
 	if (matchEval === false) return;
 	else if (matchEval) {
-		if (opts.preset !== "postgresql") return;
+		if (opts.preset !== "postgresql") return void 0;
 		const { mode, threshold } = matchEval;
 		const arrayElementAlias = "elem_alias";
 		const nestedArrayFilter = defaultRuleGroupProcessorDrizzle(transformQuery(rule.value, { ruleProcessor: (r) => ({
@@ -645,7 +647,7 @@ const defaultRuleProcessorDrizzle = (rule, _options) => {
 */
 const defaultRuleGroupProcessorDrizzle = (ruleGroup, options, _meta) => (columns, drizzleOperators) => {
 	const { fields, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, validateRule, validationMap } = options;
-	if (!columns || !drizzleOperators) return;
+	if (!columns || !drizzleOperators) return void 0;
 	const { and, not, or } = drizzleOperators;
 	const ruleProcessor = defaultRuleProcessorDrizzle;
 	const processRuleGroup = (rg, _outermost) => {
@@ -849,7 +851,7 @@ const defaultRuleGroupProcessorMongoDB = (ruleGroup, options, meta) => {
 			}, meta);
 		}).filter(Boolean);
 		const result = expressions.length > 0 ? expressions.length === 1 && !hasChildRules ? expressions[0] : `${combinator}:[${expressions.join(",")}]` : fallbackExpression;
-		return rg.not ? `"$not":${isBracketed(result) ? result : `{${result}}`}` : result;
+		return rg.not ? `"$nor":[${isBracketed(result) ? result : `{${result}}`}]` : result;
 	};
 	const processedQuery = processRuleGroup(convertFromIC(ruleGroup), true);
 	return isBracketed(processedQuery) ? processedQuery : `{${processedQuery}}`;
@@ -864,7 +866,7 @@ const defaultRuleGroupProcessorMongoDB = (ruleGroup, options, meta) => {
 const defaultRuleGroupProcessorNL = (ruleGroup, options) => {
 	const { fields, fallbackExpression, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, translations, validateRule, validationMap } = options;
 	const processRuleGroup = (rg, outermostOrLonelyInGroup) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermostOrLonelyInGroup ? fallbackExpression : "";
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermostOrLonelyInGroup ? fallbackExpression : 		/* v8 ignore next -- @preserve */ "";
 		const rg2 = isRuleGroupTypeIC(rg) && rg.rules.some((r) => typeof r === "string" && lc(r) === "xor") ? convertFromIC(rg) : rg;
 		const processedRules = [];
 		let precedingCombinator = "";
@@ -876,7 +878,7 @@ const defaultRuleGroupProcessorNL = (ruleGroup, options) => {
 			}
 			if (isRuleGroup(rule)) {
 				const processedGroup = processRuleGroup(rule, rg2.rules.length === 1 && !(rg2.not || /^xor$/i.test(rg2.combinator ?? "")));
-				// istanbul ignore else
+				// v8 ignore else
 				if (processedGroup) {
 					if (!firstRule && precedingCombinator) {
 						processedRules.push(precedingCombinator);
@@ -952,7 +954,7 @@ const defaultRuleGroupProcessorParameterized = (ruleGroup, options) => {
 		if (!isPojo(processedRule)) return "";
 		const { sql, params: customParams } = processedRule;
 		if (typeof sql !== "string" || !sql) return "";
-		// istanbul ignore else
+		// v8 ignore else
 		if (format === "parameterized" && Array.isArray(customParams)) params.push(...customParams);
 		else if (format === "parameterized_named" && isPojo(customParams)) {
 			Object.assign(paramsNamed, customParams);
@@ -961,7 +963,7 @@ const defaultRuleGroupProcessorParameterized = (ruleGroup, options) => {
 		return sql;
 	};
 	const processRuleGroup = (rg, outermostOrLonelyInGroup) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermostOrLonelyInGroup ? fallbackExpression : "";
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermostOrLonelyInGroup ? fallbackExpression : 		/* v8 ignore next -- @preserve */ "";
 		const processedRules = [];
 		let precedingCombinator = "";
 		let firstRule = true;
@@ -972,7 +974,7 @@ const defaultRuleGroupProcessorParameterized = (ruleGroup, options) => {
 			}
 			if (isRuleGroup(rule)) {
 				const processedGroup = processRuleGroup(rule, rg.rules.length === 1);
-				// istanbul ignore else
+				// v8 ignore else
 				if (processedGroup) {
 					if (!firstRule && precedingCombinator) {
 						processedRules.push(precedingCombinator);
@@ -1055,10 +1057,10 @@ const defaultRuleGroupProcessorPrisma = (ruleGroup, options) => {
 * @group Export
 */
 const defaultRuleGroupProcessorSequelize = (ruleGroup, options) => {
-	// istanbul ignore next
+	// v8 ignore next
 	const { fields, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap, context = {} } = options;
 	const { sequelizeOperators: Op } = context;
-	if (!Op) return;
+	if (!Op) return void 0;
 	const processRuleGroup = (rg, _outermost) => {
 		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return;
 		const combinator = rg.combinator.toUpperCase();
@@ -1081,7 +1083,7 @@ const defaultRuleGroupProcessorSequelize = (ruleGroup, options) => {
 				fieldData
 			});
 		}).filter(Boolean);
-		if (expressions.length === 0) return;
+		if (expressions.length === 0) return void 0;
 		const result = expressions.length === 1 && !hasChildRules ? expressions[0] : { [lc(combinator) === "or" ? Op.or : Op.and]: expressions };
 		return rg.not ? { [Op.not]: result } : result;
 	};
@@ -1097,7 +1099,7 @@ const defaultRuleGroupProcessorSequelize = (ruleGroup, options) => {
 const defaultRuleGroupProcessorSQL = (ruleGroup, options) => {
 	const { fields, fallbackExpression, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap } = options;
 	const processRuleGroup = (rg, outermostOrLonelyInGroup) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermostOrLonelyInGroup ? fallbackExpression : "";
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermostOrLonelyInGroup ? fallbackExpression : 		/* v8 ignore next -- @preserve */ "";
 		const processedRules = [];
 		let precedingCombinator = "";
 		let firstRule = true;
@@ -1108,7 +1110,7 @@ const defaultRuleGroupProcessorSQL = (ruleGroup, options) => {
 			}
 			if (isRuleGroup(rule)) {
 				const processedGroup = processRuleGroup(rule, rg.rules.length === 1);
-				// istanbul ignore else
+				// v8 ignore else
 				if (processedGroup) {
 					if (!firstRule && precedingCombinator) {
 						processedRules.push(precedingCombinator);
@@ -1144,6 +1146,325 @@ const defaultRuleGroupProcessorSQL = (ruleGroup, options) => {
 	return processRuleGroup(ruleGroup, true);
 };
 //#endregion
+//#region src/utils/formatQuery/defaultRuleGroupProcessorDiagnostics.ts
+const numericInputTypes = new Set([
+	"number",
+	"range",
+	"bigint"
+]);
+const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
+const timeRegex = /^\d{2}:\d{2}(:\d{2}(\.\d+)?)?$/;
+const monthRegex = /^\d{4}-\d{2}$/;
+const weekRegex = /^\d{4}-W\d{2}$/;
+const colorRegex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const isValidDateComponents = (y, m, d) => {
+	const date = new Date(Date.UTC(y, m - 1, d));
+	return date.getUTCFullYear() === y && date.getUTCMonth() === m - 1 && date.getUTCDate() === d;
+};
+const isValidTimeComponents = (s) => {
+	const parts = s.split(":");
+	const h = Number(parts[0]);
+	const m = Number(parts[1]);
+	const sec = parts[2] ? Number.parseFloat(parts[2]) : 0;
+	return h >= 0 && h <= 23 && m >= 0 && m <= 59 && sec >= 0 && sec < 60;
+};
+/**
+* Checks whether a value is compatible with the given {@link FullField.inputType}.
+* Returns a diagnostic code string if there is a mismatch, or `undefined` if OK.
+*/
+const checkValueTypeMismatch = (value, inputType) => {
+	if (value === null || value === void 0 || value === "") return void 0;
+	if (numericInputTypes.has(inputType)) {
+		const v = typeof value === "string" ? value.trim() : value;
+		if (typeof v === "number" || typeof v === "bigint") return void 0;
+		if (typeof v === "string" && numericRegex.test(v)) return void 0;
+		return "VALUE_TYPE_MISMATCH";
+	}
+	if (inputType === "date") {
+		if (typeof value !== "string") return "VALUE_TYPE_MISMATCH";
+		const v = value.trim();
+		if (!dateRegex.test(v)) return "VALUE_TYPE_MISMATCH";
+		const [y, m, d] = v.split("-").map(Number);
+		return isValidDateComponents(y, m, d) ? void 0 : "VALUE_TYPE_MISMATCH";
+	}
+	if (inputType === "datetime-local") {
+		if (typeof value !== "string") return "VALUE_TYPE_MISMATCH";
+		const base = value.trim().replace(/(Z|[+-]\d{2}:?\d{2}|[+-]\d{2})$/, "");
+		const tIndex = base.indexOf("T");
+		if (tIndex === -1) return "VALUE_TYPE_MISMATCH";
+		const datePart = base.slice(0, tIndex);
+		const timePart = base.slice(tIndex + 1);
+		if (!dateRegex.test(datePart) || !timeRegex.test(timePart)) return "VALUE_TYPE_MISMATCH";
+		const [y, m, d] = datePart.split("-").map(Number);
+		if (!isValidDateComponents(y, m, d)) return "VALUE_TYPE_MISMATCH";
+		return isValidTimeComponents(timePart) ? void 0 : "VALUE_TYPE_MISMATCH";
+	}
+	if (inputType === "time") {
+		if (typeof value !== "string") return "VALUE_TYPE_MISMATCH";
+		const v = value.trim();
+		if (!timeRegex.test(v)) return "VALUE_TYPE_MISMATCH";
+		return isValidTimeComponents(v) ? void 0 : "VALUE_TYPE_MISMATCH";
+	}
+	if (inputType === "month") {
+		if (typeof value !== "string") return "VALUE_TYPE_MISMATCH";
+		const v = value.trim();
+		if (!monthRegex.test(v)) return "VALUE_TYPE_MISMATCH";
+		const m = Number(v.slice(5));
+		return m >= 1 && m <= 12 ? void 0 : "VALUE_TYPE_MISMATCH";
+	}
+	if (inputType === "week") {
+		if (typeof value !== "string") return "VALUE_TYPE_MISMATCH";
+		const v = value.trim();
+		if (!weekRegex.test(v)) return "VALUE_TYPE_MISMATCH";
+		const w = Number(v.slice(6));
+		return w >= 1 && w <= 53 ? void 0 : "VALUE_TYPE_MISMATCH";
+	}
+	if (inputType === "color") {
+		if (typeof value !== "string") return "VALUE_TYPE_MISMATCH";
+		return colorRegex.test(value.trim()) ? void 0 : "VALUE_TYPE_MISMATCH";
+	}
+	if (inputType === "url") {
+		if (typeof value !== "string") return "VALUE_TYPE_MISMATCH";
+		try {
+			new URL(value.trim());
+			return;
+		} catch {
+			return "VALUE_TYPE_MISMATCH";
+		}
+	}
+	if (inputType === "email") {
+		if (typeof value !== "string") return "VALUE_TYPE_MISMATCH";
+		return emailRegex.test(value.trim()) ? void 0 : "VALUE_TYPE_MISMATCH";
+	}
+};
+/**
+* Rule group processor used by {@link formatQuery} for "diagnostics" format.
+*
+* Produces a {@link DiagnosticsResult} containing an annotated copy of the query
+* tree (`query`) with `valid`, `reasons`, `path`, and `level` properties on every
+* rule and group; a flat `diagnostics` array; aggregate `stats`; and a per-field
+* `fieldSummary`.
+*
+* @group Export
+*/
+const defaultRuleGroupProcessorDiagnostics = (ruleGroup, options) => {
+	const { fields: fieldsOption, placeholderFieldName, placeholderOperatorName, placeholderValueName, validateRule, validationMap } = options;
+	const diagnostics = [];
+	const stats = {
+		totalRules: 0,
+		totalGroups: 0,
+		validRules: 0,
+		invalidRules: 0,
+		validGroups: 0,
+		invalidGroups: 0
+	};
+	const fieldSummary = {};
+	const uniqueFields = toFlatOptionArray(fieldsOption);
+	const fieldsByName = /* @__PURE__ */ new Map();
+	for (const f of uniqueFields) fieldsByName.set(f.name, f);
+	const hasFieldsConfig = fieldsByName.size > 0;
+	const processRuleGroup = (rg, path) => {
+		stats.totalGroups++;
+		const level = path.length;
+		const groupValidationEntry = validationMap[rg.id ?? ""];
+		const groupSelfValid = isRuleOrGroupValid(rg, groupValidationEntry);
+		const groupReasons = getReasons(groupValidationEntry);
+		if (rg.muted) diagnostics.push({
+			id: rg.id ?? "",
+			path,
+			code: "MUTED",
+			message: "Group is muted",
+			source: "muted"
+		});
+		else if (!groupSelfValid && groupValidationEntry !== void 0) diagnostics.push({
+			id: rg.id ?? "",
+			path,
+			code: "CUSTOM_VALIDATOR",
+			message: groupReasons ? `Invalid: ${groupReasons.join(", ")}` : "Group failed validation",
+			source: "query-validator"
+		});
+		let allChildrenValid = true;
+		let ruleIndex = 0;
+		const annotatedRules = [];
+		for (const rule of rg.rules) {
+			if (typeof rule === "string") {
+				annotatedRules.push(rule);
+				ruleIndex++;
+				continue;
+			}
+			const childPath = [...path, ruleIndex];
+			if (isRuleGroup(rule)) {
+				const annotatedGroup = processRuleGroup(rule, childPath);
+				if (!annotatedGroup.valid) allChildrenValid = false;
+				annotatedRules.push(annotatedGroup);
+				ruleIndex++;
+				continue;
+			}
+			stats.totalRules++;
+			const childLevel = childPath.length;
+			const [validationResult, fieldValidator] = validateRule(rule);
+			const ruleValid = isRuleOrGroupValid(rule, validationResult, fieldValidator) && rule.field !== placeholderFieldName && rule.operator !== placeholderOperatorName && !(placeholderValueName !== void 0 && rule.value === placeholderValueName);
+			collectRuleDiagnostics(rule, childPath, validationResult, fieldValidator, ruleValid, diagnostics, placeholderFieldName, placeholderOperatorName, placeholderValueName, hasFieldsConfig, fieldsByName);
+			if (!ruleValid) {
+				allChildrenValid = false;
+				stats.invalidRules++;
+			} else stats.validRules++;
+			const fieldName = rule.field;
+			if (!fieldSummary[fieldName]) fieldSummary[fieldName] = {
+				ruleCount: 0,
+				invalidCount: 0
+			};
+			fieldSummary[fieldName].ruleCount++;
+			if (!ruleValid) fieldSummary[fieldName].invalidCount++;
+			const ruleReasons = getReasons(validationResult) ?? getFieldValidatorReasons(rule, fieldValidator);
+			const annotatedRule = {
+				...rule,
+				valid: ruleValid,
+				...ruleReasons ? { reasons: ruleReasons } : null,
+				path: childPath,
+				level: childLevel
+			};
+			annotatedRules.push(annotatedRule);
+			ruleIndex++;
+		}
+		const groupValid = groupSelfValid && allChildrenValid;
+		if (groupValid) stats.validGroups++;
+		else stats.invalidGroups++;
+		if (isRuleGroupType(rg)) return {
+			...rg,
+			valid: groupValid,
+			...groupReasons ? { reasons: groupReasons } : null,
+			path,
+			level,
+			rules: annotatedRules
+		};
+		return {
+			...rg,
+			valid: groupValid,
+			...groupReasons ? { reasons: groupReasons } : null,
+			path,
+			level,
+			rules: annotatedRules
+		};
+	};
+	const query = processRuleGroup(ruleGroup, []);
+	if (hasFieldsConfig) {
+		const referencedFields = new Set(Object.keys(fieldSummary));
+		for (const [fieldName] of fieldsByName) if (!referencedFields.has(fieldName)) diagnostics.push({
+			id: "",
+			path: [],
+			code: "UNREFERENCED_FIELD",
+			message: `Field "${fieldName}" is defined in the fields config but not used in the query`,
+			source: "field-check"
+		});
+	}
+	return {
+		query,
+		diagnostics,
+		stats,
+		fieldSummary
+	};
+};
+/**
+* Collects diagnostic entries for a single rule.
+*/
+const collectRuleDiagnostics = (rule, path, validationResult, fieldValidator, ruleValid, diagnostics, placeholderFieldName, placeholderOperatorName, placeholderValueName, hasFieldsConfig, fieldsByName) => {
+	const id = rule.id ?? "";
+	if (rule.muted) diagnostics.push({
+		id,
+		path,
+		code: "MUTED",
+		message: "Rule is muted",
+		source: "muted"
+	});
+	if (rule.field === placeholderFieldName) diagnostics.push({
+		id,
+		path,
+		code: "PLACEHOLDER_FIELD",
+		message: "Rule has a placeholder field",
+		source: "placeholder"
+	});
+	if (rule.operator === placeholderOperatorName) diagnostics.push({
+		id,
+		path,
+		code: "PLACEHOLDER_OPERATOR",
+		message: "Rule has a placeholder operator",
+		source: "placeholder"
+	});
+	if (placeholderValueName !== void 0 && rule.value === placeholderValueName) diagnostics.push({
+		id,
+		path,
+		code: "PLACEHOLDER_VALUE",
+		message: "Rule has a placeholder value",
+		source: "placeholder"
+	});
+	if (!rule.muted && rule.field !== placeholderFieldName && rule.operator !== placeholderOperatorName && !(placeholderValueName !== void 0 && rule.value === placeholderValueName)) {
+		if (typeof validationResult === "boolean" && !validationResult) diagnostics.push({
+			id,
+			path,
+			code: "CUSTOM_VALIDATOR",
+			message: "Rule failed validation",
+			source: "query-validator"
+		});
+		else if (typeof validationResult !== "boolean" && isValidationResult(validationResult) && !validationResult.valid) {
+			const reasons = validationResult.reasons;
+			diagnostics.push({
+				id,
+				path,
+				code: "CUSTOM_VALIDATOR",
+				message: reasons ? `Invalid: ${reasons.join(", ")}` : "Rule failed validation",
+				source: "query-validator"
+			});
+		} else if (!ruleValid && typeof fieldValidator === "function") {
+			const vr = fieldValidator(rule);
+			const reasons = typeof vr !== "boolean" && isValidationResult(vr) && !vr.valid ? vr.reasons : void 0;
+			diagnostics.push({
+				id,
+				path,
+				code: "CUSTOM_VALIDATOR",
+				message: reasons ? `Invalid: ${reasons.join(", ")}` : "Rule failed field validation",
+				source: "field-validator"
+			});
+		}
+	}
+	if (hasFieldsConfig && !fieldsByName.has(rule.field) && rule.field !== placeholderFieldName) diagnostics.push({
+		id,
+		path,
+		code: "UNDEFINED_FIELD",
+		message: `Field "${rule.field}" is not defined in the fields config`,
+		source: "field-check"
+	});
+	if (hasFieldsConfig) {
+		const fieldDef = fieldsByName.get(rule.field);
+		if (fieldDef?.inputType) {
+			const mismatchCode = checkValueTypeMismatch(rule.value, fieldDef.inputType);
+			if (mismatchCode) diagnostics.push({
+				id,
+				path,
+				code: mismatchCode,
+				message: `Value "${rule.value}" is not compatible with input type "${fieldDef.inputType}"`,
+				source: "type-check"
+			});
+		}
+	}
+};
+/**
+* Extracts `reasons` from a validation result, if present.
+*/
+const getReasons = (validationResult) => {
+	if (typeof validationResult !== "boolean" && isValidationResult(validationResult) && !validationResult.valid && validationResult.reasons) return validationResult.reasons;
+};
+/**
+* Runs a field-level validator and extracts `reasons` if present.
+*/
+const getFieldValidatorReasons = (rule, fieldValidator) => {
+	if (typeof fieldValidator === "function") {
+		const vr = fieldValidator(rule);
+		if (typeof vr !== "boolean" && isValidationResult(vr) && !vr.valid && vr.reasons) return vr.reasons;
+	}
+};
+//#endregion
 //#region src/utils/formatQuery/defaultRuleProcessorElasticSearch.ts
 const rangeOperatorMap = {
 	"<": "lt",
@@ -1522,12 +1843,12 @@ const defaultRuleProcessorLDAP = (rule, options = {}) => {
 			return negateIf(`(&(${field}>=${ldapEscape(firstValue)})(${field}<=${ldapEscape(secondValue)}))`, operatorLC === "notbetween");
 		}
 	}
-	// istanbul ignore next
+	// v8 ignore next
 	return "";
 };
 //#endregion
 //#region src/utils/formatQuery/defaultValueProcessorNL.ts
-const escapeStringValueQuotes = (v, quoteChar, escapeQuotes) => escapeQuotes && typeof v === "string" ? v.replaceAll(`${quoteChar}`, `${quoteChar}${quoteChar}`) : v;
+const escapeStringValueQuotes = (v, quoteChar, escapeQuotes) => escapeQuotes && typeof v === "string" ? v.replaceAll(`${quoteChar}`, `${quoteChar}${quoteChar}`) : /* v8 ignore next -- @preserve */ v;
 /**
 * Default value processor used by {@link formatQuery} for "natural_language" format.
 *
@@ -1545,7 +1866,7 @@ const defaultValueProcessorNL = (rule, opts = {}) => {
 		quoteFieldNamesWith,
 		fieldIdentifierSeparator
 	});
-	const t = translations ?? (	/* istanbul ignore next */ {});
+	const t = translations ?? (	/* v8 ignore start -- @preserve */ {});
 	const orTL = t.or ?? "or";
 	const trueTL = t.true ?? "true";
 	const falseTL = t.false ?? "false";
@@ -1601,7 +1922,7 @@ const defaultExportOperatorMap = {
 	between: ["is between", "is between the values in"],
 	notbetween: ["is not between", "is not between the values in"]
 };
-/* istanbul ignore next */
+/* v8 ignore next -- @preserve */
 const defaultGetOperators = () => [];
 /**
 * Default operator processor used by {@link formatQuery} for "natural_language" format.
@@ -1610,7 +1931,7 @@ const defaultGetOperators = () => [];
 */
 const defaultOperatorProcessorNL = (rule, opts = {}) => {
 	const { field, operator, valueSource = "value" } = rule;
-	// istanbul ignore next
+	// v8 ignore next
 	const { getOperators = defaultGetOperators, operatorMap: operatorMapParam = defaultExportOperatorMap } = opts;
 	const mergedOperatorMap = new Map(Object.entries(defaultExportOperatorMap));
 	for (const [key, value] of Object.entries(operatorMapParam)) mergedOperatorMap.set(lc(key), value);
@@ -1639,8 +1960,8 @@ const defaultOperatorProcessorNL = (rule, opts = {}) => {
 */
 const defaultRuleProcessorNL = (rule, opts) => {
 	const { field, operator } = rule;
-	// istanbul ignore next
-	const { fieldData, quoteFieldNamesWith = ["", ""], fieldIdentifierSeparator = "", quoteValuesWith = `'`, operatorProcessor = defaultOperatorProcessorNL, valueProcessor = defaultValueProcessorNL, concatOperator = "||", wordOrder = "SVO" } = opts ?? (	/* istanbul ignore next */ {});
+	// v8 ignore next
+	const { fieldData, quoteFieldNamesWith = ["", ""], fieldIdentifierSeparator = "", quoteValuesWith = `'`, operatorProcessor = defaultOperatorProcessorNL, valueProcessor = defaultValueProcessorNL, concatOperator = "||", wordOrder = "SVO" } = opts ?? (	/* v8 ignore start -- @preserve */ {});
 	const processedField = getQuotedFieldName(fieldData?.label ?? field, {
 		quoteFieldNamesWith,
 		fieldIdentifierSeparator
@@ -1746,7 +2067,7 @@ const defaultRuleProcessorSQL = (rule, opts = {}) => {
 * @group Export
 */
 const defaultRuleProcessorParameterized = (rule, opts, meta) => {
-	// istanbul ignore next
+	// v8 ignore next
 	const { fieldData, format, getNextNamedParam, parseNumbers, paramPrefix, paramsKeepPrefix, numberedParams, quoteFieldNamesWith = ["", ""], fieldIdentifierSeparator, concatOperator, operatorProcessor = defaultOperatorProcessorSQL, valueProcessor = defaultValueProcessorByRule } = opts ?? {};
 	const { processedParams = [] } = meta ?? {};
 	const parameterized = format === "parameterized";
@@ -1765,6 +2086,7 @@ const defaultRuleProcessorParameterized = (rule, opts, meta) => {
 	});
 	const ruleField = wrapFieldName(rule.field);
 	const matchEval = processMatchMode(rule);
+	/* v8 ignore start -- @preserve */
 	if (matchEval === false) return;
 	else if (matchEval) {
 		if (opts?.preset !== "postgresql") return finalize("");
@@ -1777,7 +2099,6 @@ const defaultRuleProcessorParameterized = (rule, opts, meta) => {
 			...opts,
 			fields: []
 		});
-		// istanbul ignore else
 		if (Array.isArray(nestedParams)) params.push(...nestedParams);
 		else Object.assign(paramsNamed, nestedParams);
 		switch (mode) {
@@ -1792,6 +2113,7 @@ const defaultRuleProcessorParameterized = (rule, opts, meta) => {
 			}
 		}
 	}
+	/* v8 ignore stop -- @preserve */
 	const value = valueProcessor(rule, {
 		parseNumbers,
 		quoteFieldNamesWith,
@@ -1832,7 +2154,7 @@ const defaultRuleProcessorParameterized = (rule, opts, meta) => {
 	}
 	let paramValue = rule.value;
 	if (typeof rule.value === "string") if (shouldRenderAsNumber(rule.value, parseNumbers)) paramValue = parseNumber(rule.value, { parseNumbers });
-	else paramValue = /^'.*'$/g.test(value) ? value.replaceAll(/(^'|'$)/g, "") : value;
+	else paramValue = /^'.*'$/g.test(value) ? value.replaceAll(/(^'|'$)/g, "") : 	/* v8 ignore next -- @preserve */ value;
 	let paramName = "";
 	if (parameterized) params.push(paramValue);
 	else {
@@ -1851,9 +2173,9 @@ const processNumber = (value, fallback, parseNumbers) => shouldRenderAsNumber(va
 */
 const defaultRuleProcessorPrisma = (rule, options = {}) => {
 	const { field, operator, value, valueSource } = rule;
-	// istanbul ignore next
+	// v8 ignore next
 	const { parseNumbers, preserveValueOrder } = options;
-	if (valueSource === "field" || processMatchMode(rule)) return;
+	if (valueSource === "field" || processMatchMode(rule)) return void 0;
 	const operatorLC = lc(operator);
 	switch (operatorLC) {
 		case "=": return { [field]: processNumber(value, value, parseNumbers) };
@@ -1911,7 +2233,7 @@ const defaultRuleProcessorPrisma = (rule, options = {}) => {
 */
 const defaultRuleProcessorSequelize = (rule, { parseNumbers, preserveValueOrder, context = {} } = {}) => {
 	const { sequelizeOperators: Op, sequelizeCol: col, sequelizeFn: fn } = context;
-	if (processMatchMode(rule)) return;
+	if (processMatchMode(rule)) return void 0;
 	const { field, operator, value, valueSource } = rule;
 	const valueIsField = valueSource === "field";
 	const operatorLC = lc(operator);
@@ -2015,9 +2337,10 @@ const defaultRuleProcessors = {
 	prisma: defaultRuleProcessorPrisma,
 	sequelize: defaultRuleProcessorSequelize,
 	spel: defaultRuleProcessorSpEL,
-	sql: defaultRuleProcessorSQL
+	sql: defaultRuleProcessorSQL,
+	diagnostics: defaultRuleProcessorSQL
 };
-/* istanbul ignore next */
+/* v8 ignore next -- @preserve */
 const defaultOperatorProcessor = (r) => r.operator;
 const defaultOperatorProcessors = {
 	cel: defaultOperatorProcessor,
@@ -2036,7 +2359,8 @@ const defaultOperatorProcessors = {
 	prisma: defaultOperatorProcessor,
 	sequelize: defaultOperatorProcessor,
 	spel: defaultOperatorProcessor,
-	sql: defaultOperatorProcessorSQL
+	sql: defaultOperatorProcessorSQL,
+	diagnostics: defaultOperatorProcessor
 };
 const defaultFallbackExpressions = {
 	cel: "1 == 1",
@@ -2110,24 +2434,26 @@ function formatQuery(ruleGroup, optionParam = {}) {
 	const getOperators = (f, m) => toFullOptionList(getOperators_option(f, m) ?? []);
 	const fallbackExpression = fallbackExpression_option ?? defaultFallbackExpressions[format] ?? defaultFallbackExpressions.sql;
 	let validationMap = {};
-	// istanbul ignore else
+	// v8 ignore else
 	if (typeof validator === "function") {
 		const validationResult = validator(ruleGroup);
 		if (typeof validationResult === "boolean") {
-			// istanbul ignore else
-			if (!validationResult) return format === "parameterized" ? {
-				sql: fallbackExpression,
-				params: []
-			} : format === "parameterized_named" ? {
-				sql: fallbackExpression,
-				params: {}
-			} : format === "mongodb" ? `{${fallbackExpression}}` : format === "mongodb_query" ? mongoDbFallback : format === "prisma" ? prismaFallback : format === "jsonlogic" ? false : format === "elasticsearch" ? {} : format === "drizzle" || format === "sequelize" ? void 0 : fallbackExpression;
+			// v8 ignore else
+			if (!validationResult) {
+				if (format !== "diagnostics") return format === "parameterized" ? {
+					sql: fallbackExpression,
+					params: []
+				} : format === "parameterized_named" ? {
+					sql: fallbackExpression,
+					params: {}
+				} : format === "mongodb" ? `{${fallbackExpression}}` : format === "mongodb_query" ? mongoDbFallback : format === "prisma" ? prismaFallback : format === "jsonlogic" ? false : format === "elasticsearch" ? {} : format === "drizzle" || format === "sequelize" ? void 0 : fallbackExpression;
+			}
 		} else validationMap = validationResult;
 	}
 	const validatorMap = {};
 	const uniqueFields = toFlatOptionArray(fields);
 	for (const f of uniqueFields)
- // istanbul ignore else
+ // v8 ignore else
 	if (typeof f.validator === "function") validatorMap[f.value ?? f.name] = f.validator;
 	const validateRule = (rule) => {
 		let validationResult;
@@ -2137,7 +2463,7 @@ function formatQuery(ruleGroup, optionParam = {}) {
 			const fieldArr = uniqueFields.filter((f) => f.name === rule.field);
 			if (fieldArr.length > 0) {
 				const field = fieldArr[0];
-				// istanbul ignore else
+				// v8 ignore else
 				if (typeof field.validator === "function") fieldValidator = field.validator;
 			}
 		}
@@ -2181,6 +2507,7 @@ function formatQuery(ruleGroup, optionParam = {}) {
 		case "prisma": return defaultRuleGroupProcessorPrisma(ruleGroup, finalOptions);
 		case "drizzle": return defaultRuleGroupProcessorDrizzle(ruleGroup, finalOptions);
 		case "sequelize": return defaultRuleGroupProcessorSequelize(ruleGroup, finalOptions);
+		case "diagnostics": return defaultRuleGroupProcessorDiagnostics(ruleGroup, finalOptions);
 		default: return "";
 	}
 }
@@ -2235,6 +2562,6 @@ const defaultValueProcessorMongoDBByRule = defaultRuleProcessorMongoDB;
 */
 const defaultValueProcessorSpELByRule = defaultRuleProcessorSpEL;
 //#endregion
-export { bigIntJsonParseReviver, bigIntJsonStringifyReplacer, celCombinatorMap, defaultCELValueProcessor, defaultExportOperatorMap, defaultMongoDBValueProcessor, defaultNLTranslations, defaultOperatorProcessorNL, defaultOperatorProcessorSQL, defaultRuleGroupProcessorCEL, defaultRuleGroupProcessorDrizzle, defaultRuleGroupProcessorElasticSearch, defaultRuleGroupProcessorJSONata, defaultRuleGroupProcessorJsonLogic, defaultRuleGroupProcessorLDAP, defaultRuleGroupProcessorMongoDB, defaultRuleGroupProcessorMongoDBQuery, defaultRuleGroupProcessorNL, defaultRuleGroupProcessorParameterized, defaultRuleGroupProcessorPrisma, defaultRuleGroupProcessorSQL, defaultRuleGroupProcessorSequelize, defaultRuleGroupProcessorSpEL, defaultRuleProcessorCEL, defaultRuleProcessorDrizzle, defaultRuleProcessorElasticSearch, defaultRuleProcessorJSONata, defaultRuleProcessorJsonLogic, defaultRuleProcessorLDAP, defaultRuleProcessorMongoDB, defaultRuleProcessorMongoDBQuery, defaultRuleProcessorNL, defaultRuleProcessorParameterized, defaultRuleProcessorPrisma, defaultRuleProcessorSQL, defaultRuleProcessorSequelize, defaultRuleProcessorSpEL, defaultSpELValueProcessor, defaultValueProcessor, defaultValueProcessorByRule, defaultValueProcessorCELByRule, defaultValueProcessorMongoDBByRule, defaultValueProcessorNL, defaultValueProcessorSpELByRule, formatQuery, formatQueryOptionPresets, getNLTranslataion, getQuoteFieldNamesWithArray, getQuotedFieldName, isValidValue, isValueProcessorLegacy, jsonLogicAdditionalOperators, mapSQLOperator, mongoDbFallback, mongoOperators, normalizeConstituentWordOrder, numerifyValues, prismaFallback, prismaOperators, processMatchMode, shouldRenderAsNumber, sqlDialectPresets };
+export { bigIntJsonParseReviver, bigIntJsonStringifyReplacer, celCombinatorMap, defaultCELValueProcessor, defaultExportOperatorMap, defaultMongoDBValueProcessor, defaultNLTranslations, defaultOperatorProcessorNL, defaultOperatorProcessorSQL, defaultRuleGroupProcessorCEL, defaultRuleGroupProcessorDiagnostics, defaultRuleGroupProcessorDrizzle, defaultRuleGroupProcessorElasticSearch, defaultRuleGroupProcessorJSONata, defaultRuleGroupProcessorJsonLogic, defaultRuleGroupProcessorLDAP, defaultRuleGroupProcessorMongoDB, defaultRuleGroupProcessorMongoDBQuery, defaultRuleGroupProcessorNL, defaultRuleGroupProcessorParameterized, defaultRuleGroupProcessorPrisma, defaultRuleGroupProcessorSQL, defaultRuleGroupProcessorSequelize, defaultRuleGroupProcessorSpEL, defaultRuleProcessorCEL, defaultRuleProcessorDrizzle, defaultRuleProcessorElasticSearch, defaultRuleProcessorJSONata, defaultRuleProcessorJsonLogic, defaultRuleProcessorLDAP, defaultRuleProcessorMongoDB, defaultRuleProcessorMongoDBQuery, defaultRuleProcessorNL, defaultRuleProcessorParameterized, defaultRuleProcessorPrisma, defaultRuleProcessorSQL, defaultRuleProcessorSequelize, defaultRuleProcessorSpEL, defaultSpELValueProcessor, defaultValueProcessor, defaultValueProcessorByRule, defaultValueProcessorCELByRule, defaultValueProcessorMongoDBByRule, defaultValueProcessorNL, defaultValueProcessorSpELByRule, formatQuery, formatQueryOptionPresets, getNLTranslataion, getQuoteFieldNamesWithArray, getQuotedFieldName, isValidValue, isValueProcessorLegacy, jsonLogicAdditionalOperators, mapSQLOperator, mongoDbFallback, mongoOperators, normalizeConstituentWordOrder, numerifyValues, prismaFallback, prismaOperators, processMatchMode, shouldRenderAsNumber, sqlDialectPresets };
 
 //# sourceMappingURL=formatQuery.mjs.map