Tweaks to checkSchemaCompatibilitySnapshots

[CraigMacomber]

Description

A collection of improvements split out from #26288 which were made based on the API review of checkSchemaCompatibilitySnapshots.

Reviewer Guidance

The review process is outlined on this wiki page.

[Copilot]

Pull request overview

This PR refines the checkSchemaCompatibilitySnapshots API and its documentation, adds a configurable version comparison function, and introduces a concrete example test plus more informative error messages.

Changes:

• Extend SchemaCompatibilitySnapshotsOptions with an optional versionComparer callback and update checkSchemaCompatibilitySnapshots to use it for version validation and ordering when provided.
• Enhance JSDoc and runtime error messages to better explain snapshot management and include snapshot directory and available snapshot versions in failures.
• Add an end-to-end Mocha example (snapshotCompatibilityCheckerExample) with a simple schema, version wiring, and a sample snapshot JSON file, and update tests to reflect the new error message format.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md	Updates the alpha API report to include the new versionComparer?: (a: string, b: string) => number property on SchemaCompatibilitySnapshotsOptions.
packages/dds/tree/api-report/tree.alpha.api.md	Mirrors the API report change for the @fluidframework/tree alpha surface, keeping the public API docs in sync with the implementation.
packages/dds/tree/src/simple-tree/api/snapshotCompatibilityChecker.ts	Extends SchemaCompatibilitySnapshotsOptions (JSDoc and type) with versionComparer, wires it into checkSchemaCompatibilitySnapshots (including validation and ordering), improves the doc block with guidance and a full Mocha example, adjusts some error messages, and augments the final error with snapshot directory and snapshot-version list.
packages/dds/tree/src/test/simple-tree/api/snapshotCompatibilityChecker.spec.ts	Updates expectations in existing tests to assert the richer error message that now includes snapshot directory and existing snapshot versions, and keeps the doc-example test in sync with the user-facing documentation.
packages/dds/tree/src/test/snapshotCompatibilityCheckerExample/schema.ts	Adds a minimal TreeViewConfiguration example using SchemaFactory.number to be consumed by the new example test.
packages/dds/tree/src/test/snapshotCompatibilityCheckerExample/version.ts	Provides a packageVersion export, wired to cleanedPackageVersion, to demonstrate programmatic version sourcing in the example.
packages/dds/tree/src/test/snapshotCompatibilityCheckerExample/snapshotCompatibilityChecker.example.mts	Introduces a complete Mocha test example showing how to call checkSchemaCompatibilitySnapshots with a filesystem implementation, schema, and version, writing snapshots into a dedicated example directory.
packages/dds/tree/src/test/snapshotCompatibilityCheckerExample/schema-snapshots/2.0.0.json	Supplies a concrete schema snapshot JSON used by the new example, illustrating the snapshot format and enabling the example test to run.

[Josmithr]

Suggested change

	`Current version ${JSON.stringify(currentVersion)} cannot upgrade documents froPm ${JSON.stringify(snapshotVersion)}.`,
	`Current version ${JSON.stringify(currentVersion)} cannot upgrade documents from ${JSON.stringify(snapshotVersion)}.`,

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

> fluid-framework-docs-site@0.0.0 ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-docs-site@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  257699 links
    1822 destination URLs
    2063 URLs ignored
       0 warnings
       0 errors