riverpod-3-scanner 1.13.1

Comprehensive static analysis tool for detecting Riverpod 3.0 async safety violations in Flutter/Dart projects

Riverpod 3.0 Safety Scanner

Comprehensive static analysis tool for detecting Riverpod 3.0 async safety violations in Flutter/Dart projects.

---

🎯 What It Does

Riverpod 3.0 introduced ref.mounted to safely handle provider disposal during async operations. This scanner detects 20 types of violations that can cause production crashes — across Riverpod notifier classes, ConsumerState, ConsumerWidget, HookConsumerWidget, plain classes, and top-level function providers — including:

• ❌ Field caching patterns (pre-Riverpod 3.0 workarounds)
• ❌ Lazy getters in async classes
• ❌ Missing ref.mounted checks before/after async operations
• ❌ ref operations inside lifecycle callbacks
• ❌ Sync methods without mounted checks (called from async contexts)
• ❌ Ref/WidgetRef stored as field in plain classes (not Riverpod notifiers)
• ❌ Ref/WidgetRef passed to a plain class constructor (the entry point to the above)
• ❌ Unguarded ref in an async* function provider (the generator body runs after the provider element is created)

Features:

• ✅ Zero false positives via sophisticated call-graph analysis
• ✅ Cross-file violation detection (indirect method calls)
• ✅ Variable resolution (traces basketballNotifier → BasketballNotifier)
• ✅ Comment stripping (prevents false positives from commented code)
• ✅ Detailed fix instructions for each violation
• ✅ CI/CD ready (exit codes, verbose mode, pattern filtering)

---

🚀 Quick Start

Installation

Via PyPI (Recommended)

pip install riverpod-3-scanner

Then run directly:

riverpod-3-scanner lib

Via Git Checkout

git clone https://github.com/DayLight-Creative-Technologies/riverpod_3_scanner.git
cd riverpod_3_scanner && python3 -m pip install .

Basic Usage

# Scan entire project
riverpod-3-scanner lib

# Scan specific file
riverpod-3-scanner lib/features/game/notifiers/game_notifier.dart

# Verbose output
riverpod-3-scanner lib --verbose

# JSON output for CI / tooling
riverpod-3-scanner lib --format json

# Print version
riverpod-3-scanner --version

(Equivalently: python3 -m riverpod_3_scanner lib — useful when the entry-point script is not on PATH.)

Example Output

🔍 RIVERPOD 3.0 COMPLIANCE SCAN COMPLETE
📁 Scanned: lib
🚨 Total violations: 3

VIOLATIONS BY TYPE:
🔴 LAZY GETTER: 2
🔴 MISSING MOUNTED AFTER AWAIT: 1

📄 lib/features/game/notifiers/game_notifier.dart (3 violation(s))
   • Line 45: lazy_getter
   • Line 120: missing_mounted_after_await
   • Line 145: lazy_getter

---

📊 Violation Types

CRITICAL (Will crash in production)

Type	Description	Production Impact
Field caching	Nullable fields with getters in async classes	Crash on widget unmount
Lazy getters	get x => ref.read() in async classes	Crash on widget unmount
ref.read() before mounted	Missing mounted check before ref operations	Crash after disposal
Missing mounted after await	No mounted check after async gap	Crash after disposal
ref in lifecycle callbacks	ref.read() in ref.onDispose/ref.listen	AssertionError crash
Sync methods without mounted	Sync methods with ref.read() called from async	Crash from callbacks
Ref stored as field	final Ref ref; in plain Dart classes (not notifiers)	Crash after provider disposal

WARNINGS (High crash risk)

• Widget lifecycle methods with unsafe ref usage
• Timer/Future.delayed deferred callbacks without mounted checks

DEFENSIVE (Type safety & best practices)

• Untyped var lazy getters (loses type information)
• mounted vs ref.mounted confusion (educational)

See GUIDE.md for complete violation reference and fix patterns.

---

🛡️ How It Works

Multi-Pass Call-Graph Analysis

The scanner uses a 4-pass architecture to achieve zero false positives:

Pass 1: Build cross-file reference database

• Index all classes, methods, provider mappings
• Map XxxNotifier → xxxProvider (Riverpod codegen)
• Store class → file path mapping

Pass 1.5: Build complete method database

• Index ALL methods with metadata (has_ref_read, has_mounted_check, is_async)
• Detect framework lifecycle methods
• Store method bodies for analysis

Pass 2: Build async callback call-graph

• Trace methods called after await statements
• Detect callback parameters (onCompletion:, builder:, etc.)
• Find stream.listen() callbacks
• Detect Timer/Future.delayed/addPostFrameCallback calls
• Resolve variables to classes (basketballNotifier → BasketballNotifier)

Pass 2.5: Propagate async context transitively

• If method A calls method B, and B is in async context → A is too
• Fixed-point iteration until no new methods added
• Handles transitive call chains

Pass 3: Detect violations with full call-graph context

• Strip comments to prevent false positives
• Check lifecycle callbacks (direct and indirect violations)
• Flag sync methods with ref.read() called from async contexts
• Verify with call-graph data (zero false positives)

Key Innovations

Variable Resolution:

final basketballNotifier = ref.read(basketballProvider(gameId).notifier);

onCompletion: () {
  basketballNotifier.completeGame();
  //  ↓ Scanner resolves ↓
  // BasketballNotifier.completeGame()
}

Comment Stripping:

// Scanner ignores this:
// Cleanup handled by ref.onDispose() in build()

// Only flags real code:
ref.onDispose(() {
  ref.read(myProvider);  // ← VIOLATION DETECTED
});

---

🔧 Advanced Usage

Pattern Filtering

# Scan only notifiers
riverpod-3-scanner lib --pattern "**/*_notifier.dart"

# Scan only widgets
riverpod-3-scanner lib --pattern "**/widgets/**/*.dart"

# Scan only services
riverpod-3-scanner lib --pattern "**/services/**/*.dart"

Exit Codes

• 0 - No violations (clean)
• 1 - Violations found (must be fixed)
• 2 - Error (invalid path, etc.)

Use in CI/CD pipelines:

riverpod-3-scanner lib || exit 1

---

🚀 CI/CD Integration

GitHub Actions

name: Riverpod 3.0 Safety Check
on: [push, pull_request]

jobs:
  riverpod-safety:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2

      - name: Install Scanner
        run: python3 -m pip install riverpod-3-scanner

      - name: Run Scanner
        run: riverpod-3-scanner lib

      - name: Dart Analyze
        run: dart analyze lib/

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

echo "Running Riverpod 3.0 compliance check..."
riverpod-3-scanner lib || exit 1
dart analyze lib/ || exit 1
echo "✅ All checks passed!"

Make executable:

chmod +x .git/hooks/pre-commit

---

📚 Documentation

• GUIDE.md - Complete guide with all violation types, fix patterns, decision trees
• EXAMPLES.md - Real-world examples and production crash case studies
• CHANGELOG.md - Version history and updates

---

🎓 The Riverpod 3.0 Pattern

❌ Before (Crashes)

class MyNotifier extends _$MyNotifier {
  MyLogger? _logger;
  MyLogger get logger {
    final l = _logger;
    if (l == null) throw StateError('Disposed');
    return l;
  }

  @override
  build() {
    _logger = ref.read(myLoggerProvider);
    ref.onDispose(() => _logger = null);
    return State.initial();
  }

  Future<void> doWork() async {
    await operation();
    logger.logInfo('Done');  // CRASH: _logger = null during await
  }
}

✅ After (Safe)

class MyNotifier extends _$MyNotifier {
  @override
  State build() => State.initial();

  Future<void> doWork() async {
    // Check BEFORE ref.read()
    if (!ref.mounted) return;

    final logger = ref.read(myLoggerProvider);

    await operation();

    // Check AFTER await
    if (!ref.mounted) return;

    logger.logInfo('Done');
  }
}

Key Differences:

• ❌ Removed nullable field _logger
• ❌ Removed enhanced getter with StateError
• ❌ Removed field initialization in build()
• ❌ Removed ref.onDispose() cleanup
• ✅ Added ref.mounted checks
• ✅ Added just-in-time ref.read()

---

🔍 Requirements

• Python: 3.9+
• Dart/Flutter: Any version using Riverpod 3.0+
• Riverpod: 3.0+ (for ref.mounted feature)

No external dependencies required - scanner uses only Python standard library.

---

📊 Scanner Statistics

From production deployment (140+ violations fixed):

Most Common Violations:

1. Lazy getters (26%) - get logger => ref.read(...)
2. Field caching (29%) - Pre-Riverpod 3.0 workaround
3. Missing mounted after await (27%)
4. ref.read before mounted (28%)

Crash Prevention:

• Before: 12+ production crashes/week from unmounted ref
• After: Zero crashes for 30+ days

False Positive Rate: 0% (with call-graph analysis)

---

🤝 Contributing

Contributions welcome! Please:

1. Report Issues: https://github.com/DayLight-Creative-Technologies/riverpod_3_scanner/issues
2. Submit PRs: Fork → Branch → PR
3. Add Tests: Include test cases for new violation types
4. Update Docs: Keep GUIDE.md synchronized with code changes

---

📝 License

MIT License - see LICENSE file for details.

---

🙏 Credits

Created by: Steven Day, DayLight Creative Technologies

Acknowledgments:

• Riverpod Team - For ref.mounted feature and official pattern
• Andrea Bizzotto - For educational content on AsyncNotifier safety
• Flutter Community - For feedback and real-world crash reports

---

📞 Support

• Issues: https://github.com/DayLight-Creative-Technologies/riverpod_3_scanner/issues
• Discussions: https://github.com/DayLight-Creative-Technologies/riverpod_3_scanner/discussions
• Author: Steven Day ([e-mail])
• Company: DayLight Creative Technologies
• Riverpod Discord: https://discord.gg/riverpod

---

🔗 Related Resources

• Riverpod 3.0 Documentation
• Riverpod 3.0 Migration Guide
• Andrea Bizzotto: AsyncNotifier Mounted

---

Prevent production crashes. Enforce Riverpod 3.0 async safety. Use riverpod_3_scanner.