@fluidframework/tree 2.116.1 → 2.118.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/index.ts

@@ -18,10 +18,13 @@ export {
 	type RemoteChangeMetadata,
 	type ChangeMetadata,
 	type LabelTree,
+	type CustomMetadataTree,
 	type TransactionLabels,
 	type RevertibleFactory,
 	type RevertibleAlphaFactory,
 	type RevertibleAlpha,
+	type RevertOptionsAlpha,
+	type RevertToOptionsAlpha,
 } from "./core/index.js";
 
 import type {
@@ -91,6 +94,7 @@ export {
 } from "./shared-tree/index.js";
 
 export {
+	type CommitRevision,
 	TreeArrayNode,
 	type TreeArrayNodeAlpha,
 	type Unhydrated,
@@ -133,6 +137,8 @@ export {
 	type TreeNodeFromImplicitAllowedTypes,
 	type TreeNodeSchemaClass,
 	type SchemaCompatibilityStatus,
+	type SchemaCompatibilityStatusBeta,
+	type SchemaDiscrepancy,
 	type FieldProps,
 	type FieldPropsAlpha,
 	normalizeFieldSchema,
@@ -194,6 +200,7 @@ export {
 	singletonSchema,
 	type UnsafeUnknownSchema,
 	type TreeViewAlpha,
+	type StagedUpgradeStatus,
 	type TreeViewBeta,
 	type InsertableField,
 	type Insertable,
@@ -269,10 +276,14 @@ export {
 	type ReadonlyArrayNode,
 	type InsertableTreeNodeFromAllowedTypes,
 	type Input,
+	type UntypedTreeView,
 	type TreeBranch,
 	type TreeBranchAlpha,
+	type UntypedTreeViewAlpha,
 	type TreeBranchEvents,
 	asTreeViewAlpha,
+	type TreeBranchCommitMetadata,
+	type TreeBranchHistory,
 	type NodeSchemaOptions,
 	type NodeSchemaOptionsAlpha,
 	type NodeSchemaMetadata,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.116.1";
+export const pkgVersion = "2.118.0";

package/src/shared-tree/history.ts

@@ -0,0 +1,99 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+import type { IIdCompressor } from "@fluidframework/id-compressor";
+
+import type { GraphCommit, CustomMetadataTree } from "../core/index.js";
+import { flattenCustomMetadata } from "../core/index.js";
+import { BranchCommitCounter, type SharedTreeBranch } from "../shared-tree-core/index.js";
+import type { TreeBranchCommitMetadata, TreeBranchHistory } from "../simple-tree/index.js";
+import type { JsonCompatibleReadOnlyObject } from "../util/index.js";
+
+import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
+import type { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
+
+/**
+ * A lazily constructed implementation of {@link TreeBranchCommitMetadata} that wraps a {@link GraphCommit}.
+ */
+class LazyTreeBranchCommitMetadata implements TreeBranchCommitMetadata {
+	public readonly revision: string;
+	private parentCache?: {
+		readonly prior: GraphCommit<SharedTreeChange>;
+		readonly cached: TreeBranchCommitMetadata;
+	};
+
+	public constructor(
+		private readonly commit: GraphCommit<SharedTreeChange>,
+		private readonly idCompressor: IIdCompressor,
+	) {
+		assert(
+			commit.revision !== "root",
+			0xd34 /* Cannot construct metadata for the root commit */,
+		);
+		this.revision = idCompressor.decompress(commit.revision);
+	}
+
+	public get custom(): JsonCompatibleReadOnlyObject | undefined {
+		return flattenCustomMetadata(this.commit.customMetadata);
+	}
+
+	public get customTree(): CustomMetadataTree | undefined {
+		return this.commit.customMetadata;
+	}
+
+	public getParent(): TreeBranchCommitMetadata | undefined {
+		// The parent of the commit may change over time due to trunk trimming.
+		if (this.commit.parent !== this.parentCache?.prior) {
+			const { parent } = this.commit;
+			this.parentCache =
+				parent === undefined || parent.revision === "root"
+					? undefined
+					: {
+							prior: parent,
+							cached: new LazyTreeBranchCommitMetadata(parent, this.idCompressor),
+						};
+		}
+		return this.parentCache?.cached;
+	}
+}
+
+/**
+ * A default implementation of {@link TreeBranchHistory} that wraps a {@link SharedTreeBranch}.
+ */
+export class DefaultTreeBranchHistory implements TreeBranchHistory {
+	private readonly commitCounter: BranchCommitCounter<
+		SharedTreeEditBuilder,
+		SharedTreeChange,
+		unknown
+	>;
+
+	public constructor(
+		private readonly branch: SharedTreeBranch<
+			SharedTreeEditBuilder,
+			SharedTreeChange,
+			unknown
+		>,
+		private readonly idCompressor: IIdCompressor,
+	) {
+		this.commitCounter = new BranchCommitCounter(branch);
+	}
+
+	public dispose(): void {
+		this.commitCounter.dispose();
+	}
+
+	public get length(): number {
+		return this.commitCounter.count;
+	}
+
+	public getHead(): TreeBranchCommitMetadata | undefined {
+		const head = this.branch.getHead();
+		if (head.revision === "root") {
+			return undefined;
+		}
+		return new LazyTreeBranchCommitMetadata(head, this.idCompressor);
+	}
+}