FireDoctor

FireDoctor is a CLI tool that diagnoses Firebase configuration and setup issues in Flutter projects. It scans your project's structure, dependencies, platform configuration files (Android & iOS), Firebase Core initialization, Firebase Cloud Messaging (FCM) setup, and Crashlytics integration — reporting issues, computing a health score, and providing actionable recommendations.

Designed for CI/CD pipelines with deterministic exit codes, threshold flags, and machine-readable JSON output.

Quick Installation

dart pub global activate --source path .

Or from pub.dev:

dart pub global activate firedoctor

Quick Usage

# Lightweight diagnostics
firedoctor diagnose

# Full health check with health score
firedoctor doctor

# Generate JSON report
firedoctor report --json

# Save report to file
firedoctor report --output report.json

# Fail CI on warnings or above
firedoctor doctor --fail-on warning

# Require minimum health score of 80
firedoctor doctor --min-score 80

Features

7 Analyzers — Project structure, dependencies, Firebase Core, Android, iOS, FCM, and Crashlytics
56 Diagnostic Codes — Granular issue detection with info, warning, error, and critical severity levels
Health Score Engine — Category-level scoring, priority grouping, weighted recommendations
CI/CD Ready — Deterministic exit codes (0–4), --fail-on and --min-score thresholds
JSON Report — Machine-readable output with full schema (schemaVersion, analyzerResults, categoryScores, recommendations)
Cross-Platform — Works on macOS, Linux, and Windows
ANSI Terminal — Colorized output with NO_COLOR support

Example Output

Running FireDoctor analysis on /path/to/flutter-project...

[FD300] ERROR   Missing firebase_core dependency
[FD400] CRITICAL Missing google-services.json
[FD500] CRITICAL Missing GoogleService-Info.plist

Health Score: 42.3 / 100 — Failed

Categories:
  Project:        100.0 / 100
  Dependency:     100.0 / 100
  Firebase Core:   0.0  / 100
  Android:         0.0  / 100
  iOS:             0.0  / 100
  FCM:            100.0 / 100
  Crashlytics:    100.0 / 100

Recommendations:
  1. Add google-services.json to android/app/
  2. Add GoogleService-Info.plist to ios/Runner/
  3. Add firebase_core dependency to pubspec.yaml

CI/CD Integration

# Fail pipeline if any error-level issues found
firedoctor doctor --fail-on error

# Fail pipeline if health score drops below 75
firedoctor doctor --min-score 75

# Generate JSON report for downstream processing
firedoctor report --json > firedoctor-report.json

Exit codes: 0 (passed), 1 (warnings), 2 (errors), 3 (critical), 4 (internal failure).

See the CI/CD integration guide for detailed CI setup examples.

Documentation

Resource	Description
Getting Started	Installation and first steps
Diagnostic Codes	Complete reference of all 56 codes
Health Score	How the scoring engine works
CI/CD Integration	Using FireDoctor in CI pipelines
Architecture	Project architecture and design
CHANGELOG	Release history

Requirements

Dart SDK >= 3.0.0

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

Fork the repository
Create a feature branch (git checkout -b feat/my-feature)
Commit your changes (git commit -am 'Add my feature')
Push to the branch (git push origin feat/my-feature)
Open a Pull Request

Run tests before submitting:

dart test
dart analyze

License

MIT — see LICENSE for details.

Libraries

analyzers/analyzer
analyzers/analyzer_context
analyzers/analyzer_result
analyzers/analyzers
analyzers/android/android
analyzers/android/android_analyzer
analyzers/crashlytics/crashlytics
analyzers/crashlytics/crashlytics_analyzer
analyzers/dependency/dependency
analyzers/dependency/dependency_analyzer
analyzers/dependency/firebase_package
analyzers/fcm/fcm
analyzers/fcm/fcm_analyzer
analyzers/firebase_core/firebase_core
analyzers/firebase_core/firebase_core_analyzer
analyzers/ios/ios
analyzers/ios/ios_analyzer
analyzers/ios/parsers/parsers
analyzers/ios/parsers/pbxproj_parser
analyzers/ios/parsers/plist_parser
analyzers/ios/parsers/podfile_lock_parser
analyzers/ios/parsers/podfile_parser
analyzers/project/project
analyzers/project/project_analyzer
cli/cli
cli/command
cli/command_runner
cli/commands/commands
cli/commands/diagnose_command
cli/commands/doctor_command
cli/commands/help_command
cli/commands/report_command
cli/commands/validate_command
cli/commands/version_command
constants/app_constants
constants/constants
exceptions/exceptions
exceptions/fire_doctor_exception
filesystem/file_system_interface
filesystem/filesystem
filesystem/local_file_system
firedoctor
logging/logger
logging/logging
models/analyzer_confidence
models/check_status
models/diagnostic_issue
models/diagnostic_report
models/diagnostic_result
models/health_score
models/models
models/pubspec
models/score_weights
models/severity
models/validation_result
parsers/parsers
parsers/pubspec_parser
services/analyzer_service
services/health_score_engine
services/report_service
services/services
services/validation_runner
services/validation_service
shared/shared
shared/source_file_cache
terminal/ansi_terminal
terminal/terminal
terminal/terminal_interface