[huangji6693-max]

Summary

Creates comprehensive SDK version migration guides (v0.x -> v1.x and v1.x -> v2.x) and adds programmatic migration validation and progress tracking utilities (src/migration/versionMigrationGuide.ts).

Closes #1200

Changes

• Breaking Changes Catalog (docs/MIGRATION.md, src/migration/versionMigrationGuide.ts):
  • Identified and cataloged breaking changes across v0.x -> v1.0.0 (BC-101, BC-102) and v1.0.0 -> v2.0.0 (BC-201 through BC-205):
    • BC-101: Replaced legacyClient / createLegacySplitClient with new StellarSplitClient(config).
    • BC-102: Structured StellarSplitError hierarchy and type guards replace generic Error string checks.
    • BC-201: Unified WalletAdapter.connect() and Signer.signTransaction() interface replacing connector-specific methods (requestAccess()).
    • BC-202: Strict bigint requirement for all stroop/token amounts (amount, totalAmount, feeCeiling).
    • BC-203: Explicit NetworkEnvironment presets (getNetworkPreset(NetworkEnvironment.TESTNET)).
    • BC-204: Migrated inline onLog callbacks to PluginRegistry (LoggingPlugin) and TelemetryHooks.
    • BC-205: Scoped @stellar-split/sdk package name and official subpath exports (/utils, /ui, /react, /testing, /mock, /telemetry, /lazy).
• Migration Steps & Working Code Examples (docs/MIGRATION.md):
  • Documented ordered step-by-step upgrade paths for v0.x -> v1.x and v1.x -> v2.x with side-by-side before/after TypeScript examples and verification commands.
• Troubleshooting Guide (docs/MIGRATION.md, findTroubleshootingGuide):
  • Added troubleshooting entries (TS-001 through TS-004) for BigInt mixing errors, removed requestAccess() calls, UnknownNetworkError, and ERR_PACKAGE_PATH_NOT_EXPORTED deep import errors.
• Migration Validation & Progress Tracking (src/migration/versionMigrationGuide.ts):
  • Implemented validateSdkMigration(input) to validate consumer configurations, invoice payloads, and code snippets against target version rules and produce actionable remediation steps and readiness scores.
  • Implemented MigrationProgressTracker (startStep, completeStep, skipStep, blockStep, validateAndCompleteStep, getSummary, toJSON, fromJSON) to track step-by-step upgrade progress.
• Tests (test/versionMigrationGuide.test.ts):
  • Added 7 unit tests verifying breaking-change filtering, step ordering, executable v2 code examples, troubleshooting search, config/payload/code validation, and stateful progress tracking.

Verification

• npx vitest run test/versionMigrationGuide.test.ts test/migration.test.ts (all passing)
• npm test (all 110 core tests passing)