@case-framework/survey-core 0.6.2 → 0.7.0

package/build/index.mjs

@@ -547,34 +547,81 @@ function buildItemExpression(item, definitions, expressionId, params) {
 }
 //#endregion
 //#region src/expressions/reference-integrity.ts
+const ITEM_DISPLAY_DEPENDENCY_OWNER_SCOPE_POLICY = {
+	component: false,
+	item: true,
+	survey: false
+};
+const ITEM_DISPLAY_DEPENDENCY_SURFACE_POLICY = {
+	"display-condition": true,
+	"disabled-condition": false,
+	validation: false,
+	"prefill-condition": false,
+	"prefill-source": false,
+	"template-value": false
+};
+/**
+* Display-condition cycles are advisory because responses may be populated before visibility is
+* evaluated, including through runtime prefills that are unavailable to static survey analysis.
+* Concrete expression integrity failures remain blocking. This exhaustive map is the source of
+* truth copied onto every analyzer-produced diagnostic.
+*/
+const SURVEY_EXPRESSION_REFERENCE_DIAGNOSTIC_POLICY = {
+	"invalid-expression": {
+		category: "reference-integrity",
+		disposition: "blocking"
+	},
+	"unknown-response-ref": {
+		category: "reference-integrity",
+		disposition: "blocking"
+	},
+	"expression-reference-type-mismatch": {
+		category: "reference-integrity",
+		disposition: "blocking"
+	},
+	"unknown-reference-value": {
+		category: "reference-integrity",
+		disposition: "blocking"
+	},
+	"display-condition-cycle": {
+		category: "display-dependency",
+		disposition: "advisory"
+	}
+};
+const createExpressionReferenceDiagnostic = (diagnostic) => ({
+	...diagnostic,
+	...SURVEY_EXPRESSION_REFERENCE_DIAGNOSTIC_POLICY[diagnostic.code]
+});
 const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const isJsonExpression = (value) => isRecord$1(value) && typeof value.type === "string";
 const collectItemExpressionLocations = (item) => {
 	const locations = [];
-	const add = (expression, location, surface) => {
+	const add = (expression, location, ownerScope, surface) => {
 		if (!isJsonExpression(expression)) return;
 		locations.push({
 			expression,
 			location,
 			ownerItemId: item.id,
 			ownerItemKey: item.key,
+			ownerScope,
 			surface
 		});
 	};
-	add(item.displayConditions?.root, "displayConditions.root", "display-condition");
-	for (const [componentId, expression] of Object.entries(item.displayConditions?.components ?? {})) add(expression, `displayConditions.components.${componentId}`, "display-condition");
-	for (const [componentId, expression] of Object.entries(item.disabledConditions?.components ?? {})) add(expression, `disabledConditions.components.${componentId}`, "disabled-condition");
-	for (const [validationKey, expression] of Object.entries(item.validations ?? {})) add(expression, `validations.${validationKey}`, "validation");
+	add(item.displayConditions?.root, "displayConditions.root", "item", "display-condition");
+	for (const [componentId, expression] of Object.entries(item.displayConditions?.components ?? {})) add(expression, `displayConditions.components.${componentId}`, "component", "display-condition");
+	for (const [componentId, expression] of Object.entries(item.disabledConditions?.components ?? {})) add(expression, `disabledConditions.components.${componentId}`, "component", "disabled-condition");
+	for (const [validationKey, expression] of Object.entries(item.validations ?? {})) add(expression, `validations.${validationKey}`, "item", "validation");
 	for (const [prefillIndex, prefill] of (item.prefills ?? []).entries()) {
 		const prefillId = prefill.id || String(prefillIndex);
-		add(prefill.when, `prefills.${prefillId}.when`, "prefill-condition");
-		if (prefill.source.type === "expression") add(prefill.source.expression, `prefills.${prefillId}.source.expression`, "prefill-source");
+		add(prefill.when, `prefills.${prefillId}.when`, "item", "prefill-condition");
+		if (prefill.source.type === "expression") add(prefill.source.expression, `prefills.${prefillId}.source.expression`, "item", "prefill-source");
 	}
 	return locations;
 };
 const collectSurveyExpressionLocations = (survey) => [...survey.surveyItems.flatMap(collectItemExpressionLocations), ...Object.entries(survey.templateValues ?? {}).flatMap(([templateKey, templateValue]) => templateValue.expression ? [{
 	expression: templateValue.expression,
 	location: `templateValues.${templateKey}.expression`,
+	ownerScope: "survey",
 	surface: "template-value"
 }] : [])];
 const candidateRefs = (unknownRef, availableRefs) => {
@@ -594,6 +641,76 @@ const candidateRefs = (unknownRef, availableRefs) => {
 	});
 	return (sameItemAndMethod.length > 0 ? sameItemAndMethod : availableRefs).slice(0, 5);
 };
+const findCyclicItemDisplayDependencyEdges = ({ edges, itemIds }) => {
+	const adjacency = new Map(itemIds.map((itemId) => [itemId, /* @__PURE__ */ new Set()]));
+	const reverseAdjacency = new Map(itemIds.map((itemId) => [itemId, /* @__PURE__ */ new Set()]));
+	for (const edge of edges) {
+		adjacency.get(edge.fromItemId)?.add(edge.toItemId);
+		reverseAdjacency.get(edge.toItemId)?.add(edge.fromItemId);
+	}
+	const finishOrder = [];
+	const visited = /* @__PURE__ */ new Set();
+	for (const startItemId of itemIds) {
+		if (visited.has(startItemId)) continue;
+		const stack = [{
+			expanded: false,
+			itemId: startItemId
+		}];
+		while (stack.length > 0) {
+			const current = stack.pop();
+			if (!current) break;
+			if (current.expanded) {
+				finishOrder.push(current.itemId);
+				continue;
+			}
+			if (visited.has(current.itemId)) continue;
+			visited.add(current.itemId);
+			stack.push({
+				expanded: true,
+				itemId: current.itemId
+			});
+			const dependencies = [...adjacency.get(current.itemId) ?? []];
+			for (let index = dependencies.length - 1; index >= 0; index -= 1) {
+				const dependencyId = dependencies[index];
+				if (visited.has(dependencyId)) continue;
+				stack.push({
+					expanded: false,
+					itemId: dependencyId
+				});
+			}
+		}
+	}
+	const componentByItemId = /* @__PURE__ */ new Map();
+	const componentMembers = /* @__PURE__ */ new Map();
+	for (const startItemId of finishOrder.reverse()) {
+		if (componentByItemId.has(startItemId)) continue;
+		const componentId = componentMembers.size;
+		const members = [];
+		const stack = [startItemId];
+		componentByItemId.set(startItemId, componentId);
+		while (stack.length > 0) {
+			const itemId = stack.pop();
+			if (!itemId) break;
+			members.push(itemId);
+			for (const dependencyOwnerId of reverseAdjacency.get(itemId) ?? []) {
+				if (componentByItemId.has(dependencyOwnerId)) continue;
+				componentByItemId.set(dependencyOwnerId, componentId);
+				stack.push(dependencyOwnerId);
+			}
+		}
+		componentMembers.set(componentId, members.sort());
+	}
+	return edges.flatMap((edge) => {
+		const componentId = componentByItemId.get(edge.fromItemId);
+		if (componentId === void 0 || componentId !== componentByItemId.get(edge.toItemId)) return [];
+		const cycleItemIds = componentMembers.get(componentId) ?? [];
+		if (edge.fromItemId !== edge.toItemId && cycleItemIds.length < 2) return [];
+		return [{
+			edge,
+			cycleItemIds
+		}];
+	});
+};
 const inferExpressionType = (expression, slots) => {
 	if (!expression) return void 0;
 	if (expression.type === ExpressionType.Const) return expression.value?.type;
@@ -668,6 +785,9 @@ const analyzeSurveyExpressionReferences = ({ responseSlots, survey }) => {
 	const slots = new Map(responseSlots.map((slot) => [slot.ref, slot]));
 	const availableRefs = responseSlots.map((slot) => slot.ref);
 	const diagnostics = [];
+	const surveyItemIds = survey.surveyItems.map((item) => item.id);
+	const surveyItemIdSet = new Set(surveyItemIds);
+	const itemDisplayDependencyEdges = [];
 	for (const location of collectSurveyExpressionLocations(survey)) {
 		let parsed;
 		try {
@@ -684,6 +804,12 @@ const analyzeSurveyExpressionReferences = ({ responseSlots, survey }) => {
 		}
 		for (const ref of parsed?.responseVariableRefs ?? []) {
 			const reference = ref.toString();
+			if (location.ownerItemId && ITEM_DISPLAY_DEPENDENCY_OWNER_SCOPE_POLICY[location.ownerScope] && ITEM_DISPLAY_DEPENDENCY_SURFACE_POLICY[location.surface] && surveyItemIdSet.has(ref.itemId)) itemDisplayDependencyEdges.push({
+				fromItemId: location.ownerItemId,
+				location,
+				reference,
+				toItemId: ref.itemId
+			});
 			if (!slots.has(reference)) diagnostics.push({
 				code: "unknown-response-ref",
 				message: `${location.location} references unknown response slot "${reference}".`,
@@ -701,7 +827,21 @@ const analyzeSurveyExpressionReferences = ({ responseSlots, survey }) => {
 			slots
 		});
 	}
-	return diagnostics;
+	for (const { cycleItemIds, edge } of findCyclicItemDisplayDependencyEdges({
+		edges: itemDisplayDependencyEdges,
+		itemIds: surveyItemIds
+	})) {
+		const isSelfReference = edge.fromItemId === edge.toItemId;
+		diagnostics.push({
+			code: "display-condition-cycle",
+			message: isSelfReference ? `${edge.location.location} for item "${edge.fromItemId}" references its own response "${edge.reference}", creating a circular display dependency.` : `${edge.location.location} for item "${edge.fromItemId}" references item "${edge.toItemId}" within a circular display dependency among ${cycleItemIds.map((itemId) => `"${itemId}"`).join(", ")}.`,
+			location: edge.location.location,
+			ownerItemId: edge.location.ownerItemId,
+			ownerItemKey: edge.location.ownerItemKey,
+			reference: edge.reference
+		});
+	}
+	return diagnostics.map(createExpressionReferenceDiagnostic);
 };
 const expressionReferenceDiagnosticKey = (diagnostic) => [
 	diagnostic.code,
@@ -710,10 +850,21 @@ const expressionReferenceDiagnosticKey = (diagnostic) => [
 	diagnostic.reference ?? "",
 	diagnostic.referenceValue ?? ""
 ].join("\0");
-const findIntroducedExpressionReferenceDiagnostics = ({ after, before }) => {
+const findIntroducedExpressionReferenceDiagnosticsIncludingAdvisories = ({ after, before }) => {
 	const existing = new Set(before.map(expressionReferenceDiagnosticKey));
 	return after.filter((diagnostic) => !existing.has(expressionReferenceDiagnosticKey(diagnostic)));
 };
+const isBlockingSurveyExpressionReferenceDiagnostic = (diagnostic) => {
+	switch (diagnostic.disposition) {
+		case "blocking": return true;
+		case "advisory": return false;
+		default: return true;
+	}
+};
+const findIntroducedBlockingExpressionReferenceDiagnostics = ({ after, before }) => findIntroducedExpressionReferenceDiagnosticsIncludingAdvisories({
+	after,
+	before
+}).filter(isBlockingSurveyExpressionReferenceDiagnostic);
 const replaceResponseVariableReferences = (value, replacements) => {
 	let changed = false;
 	const visit = (current) => {
@@ -1937,7 +2088,12 @@ const applyAdd = (document, path, value) => {
 		return document;
 	}
 	if (!isRecord(parent)) throw new JsonPatchError(`JSON pointer "${path}" parent is not an object or array.`, "invalid-target-parent", path);
-	parent[key] = structuredCloneMethod(value);
+	Object.defineProperty(parent, key, {
+		configurable: true,
+		enumerable: true,
+		value: structuredCloneMethod(value),
+		writable: true
+	});
 	return document;
 };
 const applyRemove = (document, path) => {
@@ -2369,6 +2525,6 @@ function generateCodebook(survey, options) {
 	};
 }
 //#endregion
-export { AndExpressionEditor, CURRENT_SURVEY_SCHEMA, ConstBooleanEditor, ConstDateArrayEditor, ConstDateEditor, ConstExpression, ConstNumberArrayEditor, ConstNumberEditor, ConstStringArrayEditor, ConstStringEditor, ContentType, ContextVariableExpression, ContextVariableType, CtxCustomExpressionEditor, CtxCustomValueEditor, CtxLocaleEditor, CtxPFlagDateEditor, CtxPFlagIsDefinedEditor, CtxPFlagNumEditor, CtxPFlagStringEditor, DEFAULT_TRANSFORM, DurationUnits, EXPORT_COLUMN_SLOT_SEPARATOR, EqExpressionEditor, Expression, ExpressionEditor, ExpressionEvaluator, ExpressionType, FunctionExpression, FunctionExpressionNames, GroupItemCore, GtExpressionEditor, GteExpressionEditor, InRangeExpressionEditor, JsonPatchError, LtExpressionEditor, LteExpressionEditor, META_COLUMN_ORDER, MaxExpressionEditor, MinExpressionEditor, NumberPrecision, OrExpressionEditor, PageBreakItemCore, ReferenceUsageType, ReservedSurveyItemTypes, ResponseItem, ResponseVariableEditor, ResponseVariableExpression, SURVEY_EDITOR_ITEM_COLORS, SURVEY_RESPONSE_SCHEMA_VERSION, SlotTransformMode, StrEqExpressionEditor, StrListContainsExpressionEditor, SumExpressionEditor, Survey, SurveyEngineCore, SurveyEventTypes, SurveyItemCore, SurveyItemKey, SurveyItemPrefillApplyMode, SurveyItemPrefillTargetType, SurveyItemResponse, SurveyItemTranslations, SurveyResponse, SurveyResponseExporter, SurveyTranslations, TemplateDefTypes, ValueReference, ValueReferenceMethod, ValueType, analyzeSurveyExpressionReferences, and, applyJsonPatch, assertResponseValue, buildItemExpression, builtInItemCoreRegistry, collectSurveyExpressionLocations, const_boolean, const_date, const_date_array, const_number, const_number_array, const_string, const_string_array, createFullRegistry, createItemCore, createItemTypeDefinitionRegistry, createRichTextContent, createSeededRandom, ctx_custom_expression, ctx_custom_value, ctx_locale, ctx_pflag_date, ctx_pflag_is_defined, ctx_pflag_num, ctx_pflag_string, decodeJsonPointerSegment, deserializeSurveyItemPrefill, deserializeTemplateValue, deserializeTemplateValues, encodeJsonPointerSegment, eq, escapeCsvCell, exportSingleResponseSlot, expressionReferenceDiagnosticKey, findIntroducedExpressionReferenceDiagnostics, flattenTree, generateCodebook, generateCodingKey, generateId, getAssetUsagesFromContent, getContentPlainText, getItemExpressionDefinition, getPlainTextFromRichTextContent, getValueAtJsonPointer, gt, gte, hasRenderableRichTextBlock, hasRenderableRichTextContent, in_range, initValueForType, isBuiltInItemType, isContentEmpty, isLegacyItemGroupComponent, isLegacySurveyGroupItem, isResponseValue, lt, lte, max, min, or, parseJsonPointer, prefillTargetsEqual, replaceResponseVariableReferences, responseValueReferenceIds, response_boolean, response_date, response_date_array, response_number, response_number_array, response_string, response_string_array, serializeSurveyItemPrefill, serializeTemplateValue, serializeTemplateValues, serializeToCsv, shuffleArray, shuffleIndices, str_eq, str_list_contains, structuredCloneMethod, sum, toItemTypeDefinitionRegistry, validateLocale };
+export { AndExpressionEditor, CURRENT_SURVEY_SCHEMA, ConstBooleanEditor, ConstDateArrayEditor, ConstDateEditor, ConstExpression, ConstNumberArrayEditor, ConstNumberEditor, ConstStringArrayEditor, ConstStringEditor, ContentType, ContextVariableExpression, ContextVariableType, CtxCustomExpressionEditor, CtxCustomValueEditor, CtxLocaleEditor, CtxPFlagDateEditor, CtxPFlagIsDefinedEditor, CtxPFlagNumEditor, CtxPFlagStringEditor, DEFAULT_TRANSFORM, DurationUnits, EXPORT_COLUMN_SLOT_SEPARATOR, EqExpressionEditor, Expression, ExpressionEditor, ExpressionEvaluator, ExpressionType, FunctionExpression, FunctionExpressionNames, GroupItemCore, GtExpressionEditor, GteExpressionEditor, InRangeExpressionEditor, JsonPatchError, LtExpressionEditor, LteExpressionEditor, META_COLUMN_ORDER, MaxExpressionEditor, MinExpressionEditor, NumberPrecision, OrExpressionEditor, PageBreakItemCore, ReferenceUsageType, ReservedSurveyItemTypes, ResponseItem, ResponseVariableEditor, ResponseVariableExpression, SURVEY_EDITOR_ITEM_COLORS, SURVEY_EXPRESSION_REFERENCE_DIAGNOSTIC_POLICY, SURVEY_RESPONSE_SCHEMA_VERSION, SlotTransformMode, StrEqExpressionEditor, StrListContainsExpressionEditor, SumExpressionEditor, Survey, SurveyEngineCore, SurveyEventTypes, SurveyItemCore, SurveyItemKey, SurveyItemPrefillApplyMode, SurveyItemPrefillTargetType, SurveyItemResponse, SurveyItemTranslations, SurveyResponse, SurveyResponseExporter, SurveyTranslations, TemplateDefTypes, ValueReference, ValueReferenceMethod, ValueType, analyzeSurveyExpressionReferences, and, applyJsonPatch, assertResponseValue, buildItemExpression, builtInItemCoreRegistry, collectSurveyExpressionLocations, const_boolean, const_date, const_date_array, const_number, const_number_array, const_string, const_string_array, createFullRegistry, createItemCore, createItemTypeDefinitionRegistry, createRichTextContent, createSeededRandom, ctx_custom_expression, ctx_custom_value, ctx_locale, ctx_pflag_date, ctx_pflag_is_defined, ctx_pflag_num, ctx_pflag_string, decodeJsonPointerSegment, deserializeSurveyItemPrefill, deserializeTemplateValue, deserializeTemplateValues, encodeJsonPointerSegment, eq, escapeCsvCell, exportSingleResponseSlot, expressionReferenceDiagnosticKey, findIntroducedBlockingExpressionReferenceDiagnostics, findIntroducedExpressionReferenceDiagnosticsIncludingAdvisories, flattenTree, generateCodebook, generateCodingKey, generateId, getAssetUsagesFromContent, getContentPlainText, getItemExpressionDefinition, getPlainTextFromRichTextContent, getValueAtJsonPointer, gt, gte, hasRenderableRichTextBlock, hasRenderableRichTextContent, in_range, initValueForType, isBlockingSurveyExpressionReferenceDiagnostic, isBuiltInItemType, isContentEmpty, isLegacyItemGroupComponent, isLegacySurveyGroupItem, isResponseValue, lt, lte, max, min, or, parseJsonPointer, prefillTargetsEqual, replaceResponseVariableReferences, responseValueReferenceIds, response_boolean, response_date, response_date_array, response_number, response_number_array, response_string, response_string_array, serializeSurveyItemPrefill, serializeTemplateValue, serializeTemplateValues, serializeToCsv, shuffleArray, shuffleIndices, str_eq, str_list_contains, structuredCloneMethod, sum, toItemTypeDefinitionRegistry, validateLocale };
 
 //# sourceMappingURL=index.mjs.map