flutter_state_migrator 2.4.0

Automated CLI tool to migrate Flutter apps from Provider, BLoC, GetX, and MobX to Riverpod.

Changelog

All notable changes to this project will be documented in this file.

2.4.0 - 2026-06-01

Fixed — Critical bugs (migrated code would not compile)

• edit_applier: pure insertions (length == 0) were silently dropped when they shared an offset with a content-replacing edit. File-level headers (riverpod_annotation import + part directive) are now always applied. A stderr warning is emitted when a non-zero edit is legitimately skipped.
• import_manager: riverpod_annotation was never injected — every file containing @riverpod annotations would fail to compile. Now injected whenever @riverpod or a .g.dart part directive is detected. Symbol detection now strips comments first to prevent false positives on // ConsumerWidget or similar comment lines.
• FutureProvider / StreamProvider output contained return /* TODO */; — a syntax error. Replaced with a throw UnimplementedError() stub inside a compilable async body.
• ProxyProvider output emitted throw UnimplementedError() as the build() body, crashing at runtime. Replaced with return ResultType() and a clear TODO comment.
• body_transformer: regex-based source rewriting corrupted string literals, multi-line expressions, and chained calls. Replaced with a safe comment-only approach: the original body is preserved verbatim and a structured // TODO(Migrator): block is prepended listing each detected mutation pattern and its Riverpod equivalent.

Fixed — Missing implementations

• dependency_manager: updateDependencies() now actually runs flutter pub get after updating pubspec.yaml. Legacy packages (provider, flutter_bloc, get, mobx, etc.) are commented out; Riverpod 3.x packages are added with correct current versions.
• analytics_manager: migration_success_ratio was hardcoded to 1.0. Now computed honestly from a partialMigrations count (files that received TODO placeholders). Health score now uses severity-weighted deductions (error smells deduct 10 pts, warnings 2.5 pts; governance errors 8 pts).

Added

• MobX Store detection: extends Store and with Store patterns are now detected in addition to field-level @observable/@computed annotations, covering the abstract-class-based MobX code-gen pattern.
• Integration tests (test/integration_test.dart): end-to-end pipeline test copies example/lib to a temp directory, runs the full Scanner → Transformer → applyEdits → ImportManager chain, and asserts that Riverpod patterns are present and no syntax-error placeholders remain. Also includes unit tests for the applyEdits overlap fix and ImportManager false-positive fix.

2.3.4 - 2026-06-01

Fixed

• Completely rewrote the example/ app — the previous example had syntax errors, used the deprecated StateNotifierProvider API, imported flutter_riverpod while only listing provider in its pubspec, and contained broken migration output.
• The example is now a clean, compilable Provider app (before-state) with CounterNotifier, TodoNotifier, and a SettingsScreen that exercises context.watch, context.read, Consumer, and context.select — the four patterns developers most commonly need to migrate. Run the migrator on it to see the automated Riverpod conversion.
• Removed committed generated artefacts (dependency_graph.mmd, migration_report.json, broken counter_model.dart) from example/lib/.

2.3.3 - 2026-05-30

Fixed

• Broadened analyzer constraint from ^12.1.0 to >=12.1.0 <14.0.0. The constraint range now includes analyzer 13.0.0, resolving the pub.dev transitive-dependency warning. The resolver still selects 12.1.0 because the Flutter SDK's test package currently requires analyzer <13.0.0; the constraint will automatically widen once a compatible test is shipped.

2.3.2 - 2026-05-30

Changed

• Comprehensive /// doc comments added to all remaining undocumented public API elements: FieldInfo, ParamInfo, MethodInfo, all IR node fields and constructors (ProviderDeclarationNode, ConsumerNode, ProviderOfNode, SelectorNode, MultiProviderNode, AsyncProviderNode, WidgetNode, StateNode, HookWidgetNode, ProxyProviderNode, ContextSelectNode), WizardConfig, InteractiveWizard, PluginLoader, MigrationPlugin, CustomAdapter, CustomTransformer, IdeDiagnostic fields, toJson methods across all models, and DriftSnapshot factory/toJson.

2.3.1 - 2026-05-30

Fixed

• Added library-level /// doc comments to all 17 remaining undocumented files, raising pub.dev API documentation coverage from 19.1% to above 20%.

2.3.0 - 2026-05-30

Added

• ProxyProvider / ChangeNotifierProxyProvider scanning and migration: new ProxyProviderNode IR type; transformer replaces the declaration site and appends a @riverpod Notifier skeleton with ref.watch(baseProvider).
• context.select<T, R>() scanning: new ContextSelectNode IR type; transforms to ref.watch(provider.select(...)).
• ValueNotifier<T> subclasses detected as LogicUnitNode with a single value state field.
• ValueListenableBuilder<T> detected as ConsumerNode (builder offset captured).
• MultiBlocProvider / MultiRepositoryProvider (BLoC) detected as MultiProviderNode; transformer replaces with ProviderScope.
• BlocSelector<B, S, T> detected as SelectorNode; existing _transformSelector handles it automatically.
• Get.lazyPut<T>() / Get.create<T>() (GetX) detected as ProviderDeclarationNode, same as Get.put.
• @computed MobX fields now captured in stateFields alongside @observable fields.

Changed

• analyzer dependency bumped ^10.0.1 → ^12.1.0; resolves pub.dev transitive dependency warning.
• API documentation coverage raised from 6% → above pub.dev 20% threshold: /// doc comments added to all public classes, constructors, fields, and key methods across all 27 lib/ files.

2.2.5 - 2026-05-23

Fixed

• Selector scanner fallback now emits (state) => state instead of a non-compiling /* TODO: Selector */ comment when no selector: argument is captured.
• Riverpod generator fallback for unresolved selectors updated to match — emits (state) => state instead of (state) => state./* TODO: specify property */.

Added

• Widget tests re-enabled and expanded: covers HomeScreen title, ThemeToggleButton, and navigation to TodoScreen via go_router.

Changed

• go_router dependency bumped to ^17.2.3 (verified zero API breakage).
• get bumped to ^4.7.3, mobx to ^2.6.0.

2.2.4 - 2026-05-23

Fixed

• BodyTransformer now detects single-field state and emits direct state = ... assignments instead of unnecessary copyWith(...) calls.
• Single-field list mutations rewritten cleanly: state = [...state, item], state = state.where(...).toList().
• Added .removeWhere(predicate) → state = state.where(...) rewrite for single-field list providers.
• Adjacent copyWith calls in multi-field notifiers are now merged into one statement.

Changed

• Demo app UI updated: HomeScreen uses go_router navigation, glassmorphism card layout, and a ThemeToggleButton.
• Provider todo screen and todo_screen.dart refactored to match updated routing and theme system.
• Dashboard main.dart refreshed for consistency with new theme.

2.2.2 - 2026-05-16

Fixed

• dart format applied to all lib/ and bin/ files — resolves pub.dev static-analysis formatting check.
• Repaired broken example/lib/main.dart (syntax error in Consumer builder); example now compiles and runs correctly.
• Removed dead cloud_manager.dart from lib/migrator/analysis/ (file was never imported post-2.2.1 cleanup).
• Fixed unresolved doc reference [Project Plan] in README.md (filename contained a space); renamed to Project_Plan.md.
• Added /// doc comments to all public IR node classes (ProviderNode, LogicUnitNode, WidgetNode, et al.) to meet pub.dev 20% documentation coverage threshold.
• Stripped auto-generated Flutter app boilerplate comments from pubspec.yaml.

2.2.1 - 2026-05-16

Fixed

• AsyncNotifier and StreamNotifier build() now uses the real method body and infers the concrete return type (e.g. Future<List<User>>) instead of emitting a return null; // TODO placeholder that failed to compile.
• Selector transformer now skips nodes where no selector: argument was captured, preventing broken Dart output. Generator uses the actual normalised selector snippet instead of a hardcoded state.someProperty template.
• Removed the --sync flag and CloudManager which simulated a fake cloud upload with a fabricated URL.
• PluginLoader now prints a clear warning when a migrator_plugins/ directory is detected rather than silently doing nothing.

Added

• 13 new tests covering edge cases: generic type parameters, mixin usage, family candidates, widgets with multiple provider accesses, empty/malformed input. Suite: 84 → 97 tests.
• scripts/publish.sh — automated release script that bumps version, updates CHANGELOG, tags, pushes, publishes to pub.dev, and opens a dev branch.

2.2.0 - 2026-05-13

Added

• IDE Intelligence (Phase 40): migrator --ide-json now emits structured architecture and governance diagnostics for editor integrations.
• VS Code Diagnostics & Quick Fixes: The extension now surfaces inline diagnostics, recommendation actions, and migration commands for Dart files.
• AI Architecture Guidance (Phase 44): AIManager now produces explainable guidance for architecture smells, governance violations, and complex notifier methods.

Changed

• --ai now prefers a local Ollama-compatible endpoint and falls back to deterministic recommendations when the LLM is unavailable.

2.1.1 - 2026-05-11

Fixed

• Preserved getter signatures and return types in generated Riverpod output instead of emitting method-shaped accessors.
• Preserved method parameter lists during migration so notifier methods keep their original call contract.
• Corrected Consumer and Selector rewrites to emit valid builder separators and normalized .select(...) lambdas.
• Preserved chained provider method calls so imperative actions migrate to ref.read(...).method().
• Removed conflicting Riverpod output patterns by standardizing migrated logic units on the @riverpod code generation flow.
• Inferred build() return types from typed state fields instead of defaulting to dynamic.
• Captured typed state fields in the IR so generated state and notifier code keeps source field types.

2.1.0 - 2026-05-10

Added

• Notifier Type Selector (Phase 26): Adapters now detect async methods and Stream return types to automatically select the correct Riverpod primitive — AsyncNotifier, StreamNotifier, or StateNotifier.
• Provider Family Detection (Phase 27): Constructor parameters (beyond key) are detected across all adapters; the generator emits .family scaffold with the appropriate provider type and ArgType placeholder.
• Real Dependency Graph (Phase 28): DependencyChecker now builds a true provider→consumer adjacency map from the IR and uses DFS with visited/inStack tracking to report all circular dependency chains.

Fixed

• CI analysis no longer fails on example/ and test_project/ sub-projects (excluded via analysis_options.yaml and workflow scope).
• All source files reformatted to pass dart format check.

2.0.0 - 2026-05-09

Added

• Universal Migrator: Support for all major state libraries — Provider, BLoC/Cubit, GetX, and MobX.
• Interactive CLI Wizard: Guided onboarding with auto-detection of installed state libraries (--wizard).
• Snapshot & Rollback: Automatic project snapshots before aggressive migration with one-command rollback.
• Automated Dependency Management: Auto-updates pubspec.yaml with Riverpod packages after migration.
• ROI & Analytics Engine: Migration metrics including complexity scores and estimated engineering hours saved.
• AI-Assisted Refactoring: Local LLM integration for complex method body transformation (--ai).
• Deep Body Refactoring: Automatic rewriting of state mutations to state.copyWith(...).
• Immutable State Generation: Auto-generated immutable state classes for migrated notifiers.
• Flutter Web Dashboard: Browser-based visual interface for migration reports.
• Cloud Report Sync: Upload migration audits to a central dashboard (--sync).
• Custom Plugin System: Registry-based extensibility via external Dart scripts.
• Lint-Aware Safety: Project-level health checks before and after migration.

Changed

• Description updated: tool now migrates from Provider, BLoC, GetX, and MobX — not just Provider.
• CLI flags reorganised; wizard mode launched automatically when no path is provided.
• migration_report.json now includes ROI metrics, node inventory, and modified file list.

---

1.0.0 - 2026-05-09

Added

• Core Migration Engine: AST-based scanning and transformation for Flutter projects.
• Provider Support: Migration of ChangeNotifierProvider, Consumer, Selector, and Provider.of.
• BLoC & Cubit Support: Initial migration support for Bloc and Cubit classes to Riverpod.
• Interactive Dry-run: Colorized console diff previews using the --dry-run flag.
• Monorepo Support: Automatic detection and reporting of multiple packages in a workspace.
• VS Code Extension: Explorer context menu integration for "Right-click to migrate".
• Provider Visualizer: Generation of Mermaid dependency graphs via the --visualize flag.
• Audit Reporting: Detailed migration_report.json with complexity scores and metrics.
• Import Management: Automated handling of flutter_riverpod imports and legacy cleanup.
• CI/CD: GitHub Actions pipeline for automated testing and code quality.

Changed

• Refined CLI UX with polished headers and color-coded status messages.
• Improved intelligent logic mapping for state-changing methods.

---

Initial release of the Flutter State Migrator ecosystem.