Flutter Code Guard 🛡️ #

A real-time code review and linting tool for Flutter/Dart projects that acts as your personal code guardian in the terminal.

Features ✨ #

🔍 Real-time code analysis - Watch your files and get instant feedback
⚠️ Error & warning detection - Catches issues as you code
📍 Precise location reporting - Shows exact file and line numbers
🚀 Lightning fast - Built on Dart's native analyzer
🎯 Zero configuration - Works out of the box
💻 Cross-platform - Windows, macOS, and Linux support

Environment Setup 🔧 #

Prerequisites #

Before installing Flutter Code Guard, ensure you have:

Dart SDK (version 3.0.0 or higher)
```
# Check your Dart version
dart --version
```
If you don't have Dart installed:
- Windows: Download from dart.dev or use Chocolatey: choco install dart-sdk
- macOS: brew tap dart-lang/dart && brew install dart
- Linux: Follow official installation guide
Flutter SDK (optional, but recommended for Flutter projects)
```
# Check your Flutter version
flutter --version
```

System Requirements #

OS: Windows 10+, macOS 10.15+, or Linux
RAM: 512MB+ available memory
Disk: 10MB+ free space

Installation 📦 #

Option 1: Install from pub.dev (Recommended) #

dart pub global activate flutter_code_guard

Option 2: Install from source #

git clone https://github.com/strivepawan/flutter-code-guard.git
cd flutter-code-guard
dart pub global activate --source path .

Verify Installation #

flutter_code_guard --help

If you see the help message, you're ready to go! 🎉

Usage 🚀 #

Quick Start #

Navigate to your Dart/Flutter project directory and run:

# One-time analysis
flutter_code_guard

# Real-time watching mode
flutter_code_guard --watch

Integration with Flutter Development Workflow #

🔄 During Development

Run in watch mode while coding:

cd your_flutter_project
flutter_code_guard --watch

This integrates seamlessly with your IDE:

Keep the terminal open with flutter_code_guard --watch
Code in your IDE (VS Code, Android Studio, etc.)
Save files and get instant feedback in the terminal
Fix issues before they become problems

🏗️ Build Process Integration

Add to your build scripts in pubspec.yaml:

scripts:
  analyze: flutter_code_guard
  watch: flutter_code_guard --watch

Then run:

dart run analyze  # One-time check
dart run watch    # Watch mode

🔗 CI/CD Pipeline Integration

Add to your GitHub Actions, GitLab CI, or other CI systems:

GitHub Actions Example:

name: Flutter Code Quality
on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: subosito/flutter-action@v2
      - name: Install Flutter Code Guard
        run: dart pub global activate flutter_code_guard
      - name: Run Code Analysis
        run: flutter_code_guard

GitLab CI Example:

code_analysis:
  stage: test
  script:
    - dart pub global activate flutter_code_guard
    - flutter_code_guard
  only:
    - merge_requests
    - main

Basic Commands #

🔍 One-time Analysis

Analyze your project once and exit:

flutter_code_guard

Output:

🔍 Running one-time analysis...
⚠️  WARNING at lib/main.dart:23: Unused import: 'dart:io'.
⚠️  ERROR at lib/utils.dart:45: Undefined name 'invalidVariable'.

👀 Watch Mode

Monitor files and re-analyze on changes:

flutter_code_guard --watch

Output:

👀 Watching project files for changes...
✅ No issues found!

💾 File changed: lib/main.dart
⚠️  ERROR at lib/main.dart:12: Expected ';' after this.

Working with Different Project Types #

Flutter App Projects

For typical Flutter applications:

cd my_flutter_app
flutter_code_guard --watch

Best Practices for Flutter Apps:

Run during development to catch UI/state issues early
Use before flutter build to ensure clean releases
Integrate with hot reload workflow

Flutter Package Development

For creating Flutter packages/plugins:

cd my_flutter_package
flutter_code_guard --watch

Package Development Workflow:

Create your package: flutter create --template=package my_package
Start code guard: flutter_code_guard --watch
Develop your package with real-time feedback
Run flutter_code_guard before publishing

Pure Dart Projects

For Dart-only projects (CLI tools, servers, etc.):

cd my_dart_package
flutter_code_guard

Monorepo/Multiple Packages

For projects with multiple packages:

cd my_monorepo
flutter_code_guard --watch  # Analyzes all packages

Monorepo Structure Example:

my_monorepo/
├── packages/
│   ├── core/
│   ├── ui_components/
│   └── api_client/
├── apps/
│   ├── mobile_app/
│   └── admin_panel/
└── pubspec.yaml

Team Development Setup

For Development Teams:

Standardize Analysis Rules:

# analysis_options.yaml (project root)
include: package:flutter_lints/flutter.yaml
   
analyzer:
  errors:
    invalid_annotation_target: ignore
   
linter:
  rules:
    prefer_const_constructors: true
    avoid_print: true

Pre-commit Hook Setup:

# .git/hooks/pre-commit
#!/bin/sh
flutter_code_guard
if [ $? -ne 0 ]; then
  echo "❌ Code analysis failed. Fix issues before committing."
  exit 1
fi

VS Code Integration: Add to your .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Flutter Code Guard Watch",
      "type": "shell",
      "command": "flutter_code_guard --watch",
      "group": "build",
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": false,
        "panel": "new"
      },
      "runOptions": {
        "runOn": "folderOpen"
      }
    }
  ]
}

IDE Integration Tips

🔧 VS Code Setup:

Open integrated terminal
Run flutter_code_guard --watch
Split terminal to have both Flutter and Code Guard running
Use Ctrl+` to toggle between terminals

🔧 Android Studio Setup:

Open Terminal tab
Create new terminal session for Code Guard
Run flutter_code_guard --watch
Use alongside built-in Dart Analysis

🔧 IntelliJ IDEA Setup:

Open Terminal tool window
Create dedicated tab for Code Guard
Configure as external tool for quick access

Examples 📋 #

Example 1: Flutter App Development #

Scenario: Developing a Flutter e-commerce app

$ cd flutter_ecommerce_app
$ flutter_code_guard --watch

👀 Watching project files for changes...
✅ No issues found!

# Developer adds new product widget...
💾 File changed: lib/widgets/product_card.dart
⚠️  WARNING at lib/widgets/product_card.dart:23: Unused import: 'package:flutter/services.dart'.
⚠️  INFO at lib/widgets/product_card.dart:45: Consider using 'const' for the widget constructor.

# Developer creates state management...
💾 File changed: lib/providers/cart_provider.dart
⚠️  ERROR at lib/providers/cart_provider.dart:67: The setter 'totalPrice' isn't defined for the type 'Cart'.

# After fixing issues...
💾 File changed: lib/providers/cart_provider.dart
✅ No issues found!

Example 2: Flutter Package Development #

Scenario: Creating a custom UI components package

$ flutter create --template=package awesome_ui_kit
$ cd awesome_ui_kit
$ flutter_code_guard --watch

👀 Watching project files for changes...
✅ No issues found!

# Adding new button component...
💾 File changed: lib/src/buttons/awesome_button.dart
⚠️  WARNING at lib/src/buttons/awesome_button.dart:15: Unused parameter 'context'.
⚠️  INFO at lib/src/buttons/awesome_button.dart:32: Documentation comment should be before annotation.

# Creating example app...
💾 File changed: example/lib/main.dart
⚠️  ERROR at example/lib/main.dart:28: Undefined class 'AwesomeButton'.

# After adding proper exports...
💾 File changed: lib/awesome_ui_kit.dart
✅ No issues found!

Example 3: Team Development Workflow #

Scenario: Multiple developers working on a large Flutter project

# Developer A working on authentication
$ cd flutter_team_project
$ flutter_code_guard --watch
👀 Watching project files for changes...

# Developer A commits changes
💾 File changed: lib/features/auth/login_screen.dart
⚠️  WARNING at lib/features/auth/login_screen.dart:89: Unused import: 'dart:async'.

# Developer B working on user profile
💾 File changed: lib/features/profile/profile_screen.dart
⚠️  ERROR at lib/features/profile/profile_screen.dart:123: The method 'updateUserData' isn't defined for the type 'UserRepository'.

# Developer C working on shared components
💾 File changed: lib/shared/widgets/custom_button.dart
⚠️  INFO at lib/shared/widgets/custom_button.dart:67: Prefer using lowerCamelCase for constant names.

# All issues resolved before team standup
✅ No issues found!

Example 4: CI/CD Pipeline Integration #

GitHub Actions Output:

Run flutter_code_guard
🔍 Running one-time analysis...
⚠️  ERROR at lib/services/api_service.dart:45: Undefined name 'httpClient'.
⚠️  WARNING at lib/utils/helpers.dart:23: Unused import: 'package:crypto/crypto.dart'.

Error: Process completed with exit code 1

After fixing issues:

Run flutter_code_guard
🔍 Running one-time analysis...
✅ No issues found!

✅ Code quality check passed!

Example 5: Monorepo Project #

Scenario: Large organization with multiple Flutter apps and shared packages

$ cd company_flutter_monorepo
$ flutter_code_guard --watch

👀 Watching project files for changes...

# Changes in shared core package
💾 File changed: packages/core/lib/models/user.dart
⚠️  INFO at packages/core/lib/models/user.dart:34: Consider adding 'const' constructor.

# Changes in mobile app
💾 File changed: apps/mobile/lib/screens/dashboard.dart
⚠️  WARNING at apps/mobile/lib/screens/dashboard.dart:67: Unused import: 'package:core/models/analytics.dart'.

# Changes in admin panel
💾 File changed: apps/admin_panel/lib/widgets/user_list.dart
⚠️  ERROR at apps/admin_panel/lib/widgets/user_list.dart:123: The argument type 'String?' can't be assigned to the parameter type 'String'.

# All packages analyzed simultaneously
✅ Analysis complete across all packages!

Troubleshooting 🔧 #

Common Issues #

"Command not found: flutter_code_guard"

Your PATH might not include Dart's pub cache bin directory:

Solution:

# Add to your shell profile (.bashrc, .zshrc, etc.)
export PATH="$PATH":"$HOME/.pub-cache/bin"

# Reload your shell
source ~/.bashrc  # or source ~/.zshrc

"dart: command not found"

Dart SDK is not installed or not in PATH.

Solution:

Install Dart SDK from dart.dev
Add Dart to your PATH environment variable

Permission Issues (Linux/macOS)

If you get permission errors:

sudo dart pub global activate flutter_code_guard

Analysis Takes Too Long

For large projects, the initial analysis might take time:

Solutions:

Exclude unnecessary directories (create .dartignore)
Use one-time analysis instead of watch mode for very large codebases

Getting Help #

If you encounter issues:

Check our GitHub Issues
Create a new issue with:
- Your OS and Dart version (dart --version)
- The command you ran
- Error message or unexpected behavior
- Sample code (if applicable)

Configuration 🔧 #

Flutter Code Guard works with your existing analysis_options.yaml file. It respects all the same rules and configurations as dart analyze.

Custom Analysis Options #

Create or modify analysis_options.yaml in your project root:

analyzer:
  strong-mode:
    implicit-casts: false
  errors:
    unused_import: warning
    dead_code: info

linter:
  rules:
    - prefer_const_constructors
    - avoid_print
    - prefer_final_locals

Performance Tips 🚀 #

Use .dartignore to exclude large directories (like build/, .dart_tool/)
For CI/CD, prefer one-time analysis over watch mode
Watch mode works best with up to 1000 files

Contributing 🤝 #

Contributions are welcome! Please feel free to submit a Pull Request.

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

License 📄 #

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments 🙏 #

Built on top of Dart's powerful analyzer
Inspired by the need for real-time code feedback
Thanks to the Flutter and Dart communities

Made with ❤️ for the Flutter community

Keep your code clean and your apps awesome! 🚀

flutter_code_guard 0.0.3 flutter_code_guard: ^0.0.3 copied to clipboard

Metadata