@fluidframework/tree 2.117.0 → 3.0.0

package/src/feature-libraries/schemaChecker.ts

@@ -3,8 +3,16 @@
  * Licensed under the MIT License.
  */
 
-import { unreachableCase, fail } from "@fluidframework/core-utils/internal";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import {
+	appendDebugMessage,
+	unreachableCase,
+	fail,
+} from "@fluidframework/core-utils/internal";
+import type {
+	ITelemetryBaseProperties,
+	TelemetryBaseEventPropertyType,
+} from "@fluidframework/core-interfaces";
+import { tagSchemaArtifacts, UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
 	type TreeFieldStoredSchema,
@@ -13,6 +21,7 @@ import {
 	MapNodeStoredSchema,
 	Multiplicity,
 	type SchemaAndPolicy,
+	ValueSchema,
 } from "../core/index.js";
 import { iterableHasSome, mapIterable } from "../util/index.js";
 
@@ -33,83 +42,137 @@ export enum SchemaValidationError {
 }
 
 /**
- * Additional context about a schema validation error.
- * @remarks
- * Not all fields are populated for every error type — only those relevant to the specific error.
+ * Information about a schema validation error.
  */
-export interface SchemaValidationErrorContext {
-	/**
-	 * The type identifier of the node that failed validation.
-	 */
-	readonly nodeType?: string;
-	/**
-	 * The set of type identifiers allowed in the field, if applicable.
-	 */
-	readonly allowedTypes?: ReadonlySet<string>;
-	/**
-	 * Field keys on the node that were not recognized by its schema.
-	 */
-	readonly unexpectedFields?: ReadonlySet<string>;
+export interface SchemaValidationErrorDetails {
+	readonly error: SchemaValidationError;
+	readonly path: readonly (string | number)[];
+	readonly telemetryProperties?: ITelemetryBaseProperties;
 }
 
 /**
  * Throws a UsageError indicating a tree is out of schema.
  */
-export function throwOutOfSchema(
-	maybeError: SchemaValidationError,
-	context?: SchemaValidationErrorContext,
-): never {
-	throw new UsageError(formatSchemaValidationError(maybeError, context));
+export function throwOutOfSchema(details: SchemaValidationErrorDetails): never {
+	const message = `Tree does not conform to schema. ${getSchemaValidationErrorMessage(details.error)}`;
+	throw new UsageError(
+		appendDebugMessage(message, () => getSchemaValidationDebugMessage(details)),
+		{
+			...tagSchemaArtifacts({
+				schemaValidationError: SchemaValidationError[details.error],
+				schemaValidationPath: JSON.stringify(details.path),
+			}),
+			...details.telemetryProperties,
+		},
+	);
 }
 
-// Not exported: internal helper used by throwOutOfSchema.
-function formatSchemaValidationError(
-	error: SchemaValidationError,
-	context: SchemaValidationErrorContext | undefined,
-): string {
-	switch (error) {
+function getTelemetryProperty(
+	details: SchemaValidationErrorDetails,
+	key: string,
+): TelemetryBaseEventPropertyType {
+	const property = details.telemetryProperties?.[key];
+	return typeof property === "object" ? property.value : property;
+}
+
+function getSchemaValidationDebugMessage(details: SchemaValidationErrorDetails): string {
+	const path = details.path.length === 0 ? "" : ` at path ${JSON.stringify(details.path)}`;
+	const nodeType = getTelemetryProperty(details, "nodeType");
+	const fieldKind = getTelemetryProperty(details, "fieldKind");
+	const childCount = getTelemetryProperty(details, "childCount");
+	switch (details.error) {
+		case SchemaValidationError.Field_KindNotInSchemaPolicy: {
+			return `Field kind ${JSON.stringify(fieldKind)} is not supported by the schema policy${path}.`;
+		}
+		case SchemaValidationError.Field_MissingRequiredChild: {
+			return `A required field of kind ${JSON.stringify(fieldKind)} must contain exactly one child, but found ${childCount}${path}.`;
+		}
+		case SchemaValidationError.Field_MultipleChildrenNotAllowed: {
+			return `A field of kind ${JSON.stringify(fieldKind)} allows at most one child, but found ${childCount}${path}.`;
+		}
+		case SchemaValidationError.Field_ChildInForbiddenField: {
+			return `A forbidden field of kind ${JSON.stringify(fieldKind)} must be empty, but found ${childCount} ${childCount === 1 ? "child" : "children"}${path}.`;
+		}
 		case SchemaValidationError.Field_NodeTypeNotAllowed: {
-			const nodeDesc = context?.nodeType === undefined ? "unknown" : `"${context.nodeType}"`;
-			const allowedDesc =
-				context?.allowedTypes === undefined
-					? "unknown"
-					: `[${[...context.allowedTypes].map((t) => `"${t}"`).join(", ")}]`;
-			return (
-				`Tree does not conform to schema. ` +
-				`A node of type ${nodeDesc} is not allowed in this field. Allowed types: ${allowedDesc}. ` +
-				`If using a staged allowed type, the stored schema has not been upgraded to include this type yet. ` +
-				`Either upgrade the schema to enable the staged type or avoid inserting content of this type until the schema is upgraded.`
-			);
+			return `A node of type ${JSON.stringify(nodeType)} is not allowed in this field${path}. Allowed types: ${getTelemetryProperty(details, "allowedTypes")}. If using a staged allowed type, upgrade the stored schema before inserting this content.`;
+		}
+		case SchemaValidationError.LeafNode_InvalidValue: {
+			return `Leaf node ${JSON.stringify(nodeType)} requires a value matching ${JSON.stringify(getTelemetryProperty(details, "expectedValueType"))}, but found ${JSON.stringify(getTelemetryProperty(details, "actualValueType"))}${path}.`;
+		}
+		case SchemaValidationError.LeafNode_FieldsNotAllowed: {
+			return `Leaf node ${JSON.stringify(nodeType)} must not contain fields${path}. Unexpected fields: ${getTelemetryProperty(details, "unexpectedFields")}.`;
+		}
+		case SchemaValidationError.ObjectNode_FieldNotInSchema: {
+			return `A node of type ${JSON.stringify(nodeType)} has fields not defined in its schema${path}. Unexpected fields: ${getTelemetryProperty(details, "unexpectedFields")}.`;
+		}
+		case SchemaValidationError.NonLeafNode_ValueNotAllowed: {
+			return `Non-leaf node ${JSON.stringify(nodeType)} must not have a value, but found ${JSON.stringify(getTelemetryProperty(details, "actualValueType"))}${path}.`;
 		}
 		case SchemaValidationError.Node_MissingSchema: {
-			const nodeDesc = context?.nodeType === undefined ? "unknown" : `"${context.nodeType}"`;
-			return (
-				`Tree does not conform to schema. ` +
-				`No schema definition was found for node type ${nodeDesc}. ` +
-				`Ensure the node's type is included in the schema and that the stored schema has been upgraded if needed.`
-			);
+			return `No schema definition was found for node type ${JSON.stringify(nodeType)}${path}. Ensure the node's type is included in the schema and that the stored schema has been upgraded if needed.`;
+		}
+		default: {
+			return unreachableCase(details.error);
+		}
+	}
+}
+
+function getSchemaValidationErrorMessage(error: SchemaValidationError): string {
+	switch (error) {
+		case SchemaValidationError.Field_KindNotInSchemaPolicy: {
+			return "The field kind is not supported by the schema policy.";
+		}
+		case SchemaValidationError.Field_MissingRequiredChild: {
+			return "A required field is missing its child.";
+		}
+		case SchemaValidationError.Field_MultipleChildrenNotAllowed: {
+			return "A field contains more children than its kind allows.";
+		}
+		case SchemaValidationError.Field_ChildInForbiddenField: {
+			return "A forbidden field contains children.";
+		}
+		case SchemaValidationError.Field_NodeTypeNotAllowed: {
+			return "A node type is not allowed in its field.";
+		}
+		case SchemaValidationError.LeafNode_InvalidValue: {
+			return "A leaf node value does not match its schema.";
+		}
+		case SchemaValidationError.LeafNode_FieldsNotAllowed: {
+			return "A leaf node contains fields.";
 		}
 		case SchemaValidationError.ObjectNode_FieldNotInSchema: {
-			const nodeDesc = context?.nodeType === undefined ? "unknown" : `"${context.nodeType}"`;
-			const fieldsDesc =
-				context?.unexpectedFields === undefined || context.unexpectedFields.size === 0
-					? undefined
-					: `[${[...context.unexpectedFields].map((f) => `"${f}"`).join(", ")}]`;
-			const fieldsPart =
-				fieldsDesc === undefined
-					? "The node has fields that are not defined in its schema."
-					: `Unexpected fields: ${fieldsDesc}.`;
-			return (
-				`Tree does not conform to schema. ` +
-				`A node of type ${nodeDesc} has fields not defined in its schema. ${fieldsPart}`
-			);
+			return "An object node contains fields not defined in its schema.";
+		}
+		case SchemaValidationError.NonLeafNode_ValueNotAllowed: {
+			return "A non-leaf node contains a value.";
+		}
+		case SchemaValidationError.Node_MissingSchema: {
+			return "The node type has no schema definition.";
 		}
 		default: {
-			return `Tree does not conform to schema: ${SchemaValidationError[error]}.`;
+			return unreachableCase(error);
 		}
 	}
 }
 
+function schemaValidationError(
+	error: SchemaValidationError,
+	telemetryProperties?: ITelemetryBaseProperties,
+): SchemaValidationErrorDetails {
+	return { error, path: [], telemetryProperties };
+}
+
+function prependPath<T extends NotUndefined>(
+	onError: (details: SchemaValidationErrorDetails) => T,
+	segment: string | number,
+): (details: SchemaValidationErrorDetails) => T {
+	return (details) => onError({ ...details, path: [segment, ...details.path] });
+}
+
+function getValueType(value: unknown): string {
+	return value === null ? "null" : typeof value;
+}
+
 type NotUndefined = number | string | boolean | bigint | symbol | object;
 
 /**
@@ -122,28 +185,52 @@ type NotUndefined = number | string | boolean | bigint | symbol | object;
 export function isNodeInSchema<T extends NotUndefined>(
 	node: MinimalMapTreeNodeView,
 	schemaAndPolicy: SchemaAndPolicy,
-	onError: (error: SchemaValidationError, context?: SchemaValidationErrorContext) => T,
+	onError: (details: SchemaValidationErrorDetails) => T,
 ): T | undefined {
 	// Validate the schema declared by the node exists
 	const schema = schemaAndPolicy.schema.nodeSchema.get(node.type);
 	if (schema === undefined) {
-		return onError(SchemaValidationError.Node_MissingSchema, {
-			nodeType: node.type,
-		});
+		return onError(
+			schemaValidationError(
+				SchemaValidationError.Node_MissingSchema,
+				tagSchemaArtifacts({ nodeType: node.type }),
+			),
+		);
 	}
 
 	// Validate the node is well formed according to its schema
 
 	if (schema instanceof LeafNodeStoredSchema) {
 		if (iterableHasSome(node.fields)) {
-			return onError(SchemaValidationError.LeafNode_FieldsNotAllowed);
+			const unexpectedFields = [...mapIterable(node.fields, ([key]) => key)].sort();
+			return onError(
+				schemaValidationError(SchemaValidationError.LeafNode_FieldsNotAllowed, {
+					...tagSchemaArtifacts({
+						nodeType: node.type,
+						unexpectedFields: JSON.stringify(unexpectedFields),
+					}),
+				}),
+			);
 		}
 		if (!allowsValue(schema.leafValue, node.value)) {
-			return onError(SchemaValidationError.LeafNode_InvalidValue);
+			return onError(
+				schemaValidationError(SchemaValidationError.LeafNode_InvalidValue, {
+					...tagSchemaArtifacts({
+						nodeType: node.type,
+						expectedValueType: ValueSchema[schema.leafValue],
+					}),
+					actualValueType: getValueType(node.value),
+				}),
+			);
 		}
 	} else {
 		if (node.value !== undefined) {
-			return onError(SchemaValidationError.NonLeafNode_ValueNotAllowed);
+			return onError(
+				schemaValidationError(SchemaValidationError.NonLeafNode_ValueNotAllowed, {
+					...tagSchemaArtifacts({ nodeType: node.type }),
+					actualValueType: getValueType(node.value),
+				}),
+			);
 		}
 
 		if (schema instanceof ObjectNodeStoredSchema) {
@@ -154,7 +241,7 @@ export function isNodeInSchema<T extends NotUndefined>(
 					nodeField,
 					fieldSchema,
 					schemaAndPolicy,
-					onError,
+					prependPath(onError, fieldKey),
 				);
 				if (fieldInSchemaResult !== undefined) {
 					return fieldInSchemaResult;
@@ -166,18 +253,22 @@ export function isNodeInSchema<T extends NotUndefined>(
 			// Code using this with a stored schema derived from a view schema rather than the document can be problematic because it may be missing unknown fields that the actual document has.
 			// Other schema evolution features like "staged" allowed types will likely cause similar issues elsewhere in this checker.
 			if (uncheckedFieldsFromNode.size > 0) {
-				return onError(SchemaValidationError.ObjectNode_FieldNotInSchema, {
-					nodeType: node.type,
-					unexpectedFields: uncheckedFieldsFromNode,
-				});
+				return onError(
+					schemaValidationError(SchemaValidationError.ObjectNode_FieldNotInSchema, {
+						...tagSchemaArtifacts({
+							nodeType: node.type,
+							unexpectedFields: JSON.stringify([...uncheckedFieldsFromNode].sort()),
+						}),
+					}),
+				);
 			}
 		} else if (schema instanceof MapNodeStoredSchema) {
-			for (const [_key, field] of node.fields) {
+			for (const [key, field] of node.fields) {
 				const fieldInSchemaResult = isFieldInSchema(
 					field,
 					schema.mapFields,
 					schemaAndPolicy,
-					onError,
+					prependPath(onError, key),
 				);
 				if (fieldInSchemaResult !== undefined) {
 					return fieldInSchemaResult;
@@ -202,36 +293,61 @@ export function isFieldInSchema<T extends NotUndefined>(
 	childNodes: MapTreeFieldViewGeneric<MinimalMapTreeNodeView>,
 	schema: TreeFieldStoredSchema,
 	schemaAndPolicy: SchemaAndPolicy,
-	onError: (error: SchemaValidationError, context?: SchemaValidationErrorContext) => T,
+	onError: (details: SchemaValidationErrorDetails) => T,
 ): T | undefined {
 	// Validate that the field kind is handled by the schema policy
 	const kind = schemaAndPolicy.policy.fieldKinds.get(schema.kind);
 	if (kind === undefined) {
-		return onError(SchemaValidationError.Field_KindNotInSchemaPolicy);
+		return onError(
+			schemaValidationError(
+				SchemaValidationError.Field_KindNotInSchemaPolicy,
+				tagSchemaArtifacts({ fieldKind: schema.kind }),
+			),
+		);
 	}
 
 	// Validate that the field doesn't contain more nodes than its type supports
 	{
 		const multiplicityCheck = compliesWithMultiplicity(childNodes.length, kind.multiplicity);
 		if (multiplicityCheck !== undefined) {
-			return onError(multiplicityCheck);
+			return onError(
+				schemaValidationError(multiplicityCheck, {
+					...tagSchemaArtifacts({ fieldKind: schema.kind }),
+					childCount: childNodes.length,
+				}),
+			);
 		}
 	}
 
+	let index = 0;
 	for (const node of childNodes) {
 		// Validate the type declared by the node is allowed in this field
 		if (schema.types !== undefined && !schema.types.has(node.type)) {
-			return onError(SchemaValidationError.Field_NodeTypeNotAllowed, {
-				nodeType: node.type,
-				allowedTypes: schema.types,
-			});
+			const allowedTypes = [...schema.types].sort();
+			return prependPath(
+				onError,
+				index,
+			)(
+				schemaValidationError(
+					SchemaValidationError.Field_NodeTypeNotAllowed,
+					tagSchemaArtifacts({
+						nodeType: node.type,
+						allowedTypes: JSON.stringify(allowedTypes),
+					}),
+				),
+			);
 		}
 
 		// Validate the node complies with the type it declares to be.
-		const nodeInSchemaResult = isNodeInSchema(node, schemaAndPolicy, onError);
+		const nodeInSchemaResult = isNodeInSchema(
+			node,
+			schemaAndPolicy,
+			prependPath(onError, index),
+		);
 		if (nodeInSchemaResult !== undefined) {
 			return nodeInSchemaResult;
 		}
+		index += 1;
 	}
 
 	return undefined;

package/src/feature-libraries/sequence-field/filterEdits.ts

@@ -3,20 +3,27 @@
  * Licensed under the MIT License.
  */
 
-import type { ChangeAtomId } from "../../core/index.js";
-import type { RangeQueryResult } from "../../util/index.js";
-import { EditFilterStatus, type EditFilterFunc } from "../modular-schema/index.js";
+import {
+	EditFilterStatus,
+	type FilterAttachFunc,
+	type FilterDetachFunc,
+} from "../modular-schema/index.js";
 import { MarkListFactory } from "./markListFactory.js";
 import { NoopMarkType, type Changeset, type Mark } from "./types.js";
-import { getDetachedNodeId, getDetachOutputCellId, omitMarkEffect } from "./utils.js";
+import {
+	getDetachedNodeId,
+	getDetachOutputCellId,
+	getOutputCellId,
+	omitMarkEffect,
+} from "./utils.js";
 import { MarkQueueBase } from "./markQueue.js";
-import { unreachableCase } from "@fluidframework/core-utils/internal";
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 
 export function filterEdits(
 	change: Changeset,
 	options: {
-		filterDetach: EditFilterFunc;
-		filterAttach: EditFilterFunc;
+		filterDetach: FilterDetachFunc;
+		filterAttach: FilterAttachFunc;
 		preserveOtherEdits: boolean;
 	},
 ): Changeset {
@@ -38,16 +45,8 @@ export function filterEdits(
 
 function filterMark(
 	mark: Mark,
-	filterDetach: (
-		id: ChangeAtomId,
-		count: number,
-		endpoint?: ChangeAtomId,
-	) => RangeQueryResult<EditFilterStatus>,
-	filterAttach: (
-		id: ChangeAtomId,
-		count: number,
-		endpoint?: ChangeAtomId,
-	) => RangeQueryResult<EditFilterStatus>,
+	filterDetach: FilterDetachFunc,
+	filterAttach: FilterAttachFunc,
 	preserveOtherEdits: boolean,
 ): Mark {
 	const type = mark.type;
@@ -58,11 +57,14 @@ function filterMark(
 				return preserveOtherEdits ? mark : omitMarkEffect(mark);
 			}
 
+			const attachId =
+				mark.type === "MoveIn" ? { revision: mark.revision, localId: mark.id } : mark.cellId;
+
 			const endpoint = mark.type === "MoveIn" ? mark.finalEndpoint : undefined;
-			const result = filterAttach(mark.cellId, mark.count, endpoint);
+			const result = filterAttach(attachId, mark.count, undefined, endpoint);
 
 			let filtered: Mark;
-			switch (result.value) {
+			switch (result.value.action) {
 				case EditFilterStatus.Preserve: {
 					filtered = mark;
 					break;
@@ -73,7 +75,11 @@ function filterMark(
 					// Insert marks use the cell ID as the attach ID, so we must change the cell ID here.
 					// This could be a problem if there were references to the old cell ID outside this changeset,
 					// but PreserveWithoutMove is only used for transaction minimization, where that is not a problem.
-					const newCellId = endpoint ?? { revision: mark.revision, localId: mark.id };
+					const newCellId = result.value.newAttachId ??
+						endpoint ?? {
+							revision: mark.revision,
+							localId: mark.id,
+						};
 					filtered = {
 						type: "Insert",
 						count: result.length,
@@ -81,6 +87,11 @@ function filterMark(
 						revision: mark.revision,
 						id: mark.id,
 					};
+
+					if (result.value.nodeId !== undefined) {
+						filtered.changes = result.value.nodeId;
+					}
+
 					break;
 				}
 				case EditFilterStatus.Remove: {
@@ -88,7 +99,7 @@ function filterMark(
 					break;
 				}
 				default: {
-					unreachableCase(result.value);
+					unreachableCase(result.value.action);
 				}
 			}
 
@@ -98,10 +109,10 @@ function filterMark(
 		case "MoveOut": {
 			const detachId = getDetachedNodeId(mark);
 			const endpoint = mark.type === "MoveOut" ? mark.finalEndpoint : undefined;
-			const result = filterDetach(detachId, mark.count, endpoint);
+			const result = filterDetach(detachId, mark.count, mark.cellId, endpoint);
 
 			let filtered: Mark;
-			switch (result.value) {
+			switch (result.value.action) {
 				case EditFilterStatus.Preserve: {
 					filtered = mark;
 					break;
@@ -123,17 +134,42 @@ function filterMark(
 				}
 				case EditFilterStatus.Remove: {
 					filtered = omitMarkEffect(mark);
+					if (result.value.shouldRemoveChild === true) {
+						delete filtered.changes;
+					}
+
 					break;
 				}
 				default: {
-					unreachableCase(result.value);
+					unreachableCase(result.value.action);
 				}
 			}
 			return { ...filtered, count: result.length };
 		}
-		case NoopMarkType:
-		case "Rename":
 		case "AttachAndDetach": {
+			assert(
+				mark.attach.type === "MoveIn",
+				0xd3c /* AttachAndDetach marks in changesets should always represent MoveIn + Remove */,
+			);
+
+			if (mark.cellId === undefined) {
+				return preserveOtherEdits ? mark : omitMarkEffect(mark);
+			}
+
+			const result = filterAttach(
+				{ revision: mark.attach.revision, localId: mark.attach.id },
+				mark.count,
+				getOutputCellId(mark),
+				mark.attach.finalEndpoint,
+			);
+
+			const filtered =
+				result.value.action === EditFilterStatus.Preserve ? mark : omitMarkEffect(mark);
+
+			return { ...filtered, count: result.length };
+		}
+		case NoopMarkType:
+		case "Rename": {
 			return preserveOtherEdits ? mark : omitMarkEffect(mark);
 		}
 		default: {

package/src/feature-libraries/sequence-field/utils.ts

@@ -19,7 +19,7 @@ import {
 	CrossFieldTarget,
 	type NodeId,
 	type CrossFieldKeyRange,
-	type NestedChangesIndices,
+	type ChildChangeInfo,
 } from "../modular-schema/index.js";
 
 import type {
@@ -62,25 +62,13 @@ export function createEmpty(): Changeset {
 	return [];
 }
 
-export function getNestedChanges(change: Changeset): NestedChangesIndices {
-	const output: NestedChangesIndices = [];
-	let inputIndex = 0;
-	let outputIndex = 0;
-	for (const mark of change) {
-		const { changes, count } = mark;
-		if (changes !== undefined) {
-			output.push([
-				changes,
-				areInputCellsEmpty(mark) ? undefined : inputIndex /* inputIndex */,
-				areOutputCellsEmpty(mark) ? undefined : outputIndex /* outputIndex */,
-			]);
-		}
-		if (!areInputCellsEmpty(mark)) {
-			inputIndex += count;
-		}
+export function getNestedChanges(change: Changeset): ChildChangeInfo[] {
+	const output: ChildChangeInfo[] = [];
 
-		if (!areOutputCellsEmpty(mark)) {
-			outputIndex += count;
+	for (const mark of change) {
+		if (mark.changes !== undefined) {
+			const detachId = isDetach(mark) ? getDetachedNodeId(mark) : undefined;
+			output.push({ nodeId: mark.changes, inputRootId: mark.cellId, detachId });
 		}
 	}
 	return output;