flutter_ci_guard 0.1.0

CI-friendly quality gates for Flutter projects. Enforce format, analyze, and test coverage thresholds with ease.

🛡️ flutter_ci_guard

flutter_ci_guard is a lightweight CLI tool for running Flutter quality gates in CI. It checks formatting, static analysis, tests, and coverage thresholds from one command, and now supports YAML-based configuration.

🚀 What does it solve?

CIs often have separate steps for formatting, linting, and testing. If one fails, you might get scattered reports. More importantly, enforcing a minimum coverage percentage usually requires complex shell scripts or heavy third-party services.

flutter_ci_guard orchestrates these "Quality Gates" into a single, reliable command that:

1. 🧹 Ensures code is formatted (fails if dart format finds changes).
2. 🔍 Runs static analysis (fails if flutter analyze finds issues).
3. 🧪 Executes tests with coverage (fails if tests fail).
4. 📈 Enforces coverage thresholds (fails if coverage is below your limit).

---

📦 Installation

Add it as a dev dependency in your pubspec.yaml:

dev_dependencies:
  flutter_ci_guard: latest_version

Or install it globally:

dart pub global activate flutter_ci_guard

---

🛠️ Basic Usage

Run it from the root of your Flutter project:

# Runs everything with default 80% coverage threshold
dart run flutter_ci_guard

Real-world examples

Enforce strict 95% coverage:

dart run flutter_ci_guard --min-coverage 95

Check only analysis and coverage (skipping format and tests runtime):

# Useful if you already ran tests in a previous CI step but need to check the LCOV file
dart run flutter_ci_guard --skip-format --skip-tests --min-coverage 80

Configuration file

You can store defaults in a flutter_ci_guard.yaml file at your project root. The file is loaded automatically when present.

steps:
  format: true
  analyze: true
  test: true

coverage:
  min: 85
  path: coverage/lcov.info

Supported keys in this release:

• steps.format
• steps.analyze
• steps.test
• coverage.min
• coverage.path

You can also point to a custom config file:

dart run flutter_ci_guard --config ci/flutter_ci_guard.yaml

CLI flags still work exactly as before. When the same setting is provided in multiple places, precedence is:

CLI flags > YAML config > built-in defaults

---

⚙️ Configuration Flags

Flag	Default	Description
--config	auto-detect flutter_ci_guard.yaml	Path to a YAML config file.
--min-coverage	80	Required percentage (0-100).
--coverage-path	coverage/lcov.info	Path to the generated LCOV file.
--skip-format	false	Skip dart format validation.
--skip-analyze	false	Skip flutter analyze.
--skip-tests	false	Skip flutter test --coverage.
--help	-	Show usage information.

---

🤖 CI/CD Integration

GitHub Actions

The most common way to use flutter_ci_guard is as a single "Quality Gate" step.

jobs:
  check-quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: subosito/flutter-action@v2
      
      - name: Install dependencies
        run: flutter pub get

      - name: Run Quality Gates
        run: dart run flutter_ci_guard --min-coverage 90

---

🚪 Exit Behavior

flutter_ci_guard returns specific exit codes so your CI can react accordingly:

Code	Meaning
0	Success (All gates passed).
1	Step Failed (Format, Analyze, or Tests failed).
2	Low Coverage (Coverage is below the threshold).
3	Missing File (Coverage file not found at the specified path).
4	Parse Error (The LCOV file is malformed).
64	Invalid Args (Wrong CLI usage).

---

🎯 Scope & Philosophy

• Lightweight: Small surface area, fast startup.
• Fail Fast: If formatting fails, it doesn't waste time running tests.
• CI-First: Designed to be the standard way to run checks in pipelines.
• Pure Dart: No need for lcov or genhtml installed on the CI machine to check the percentage.

---

👨‍💻 Created & Maintained By

Miguel Angel Oquendo Rincon

---

📄 License

MIT License - see LICENSE for details.