Smart Coverage

coverage

A modern Dart CLI tool for intelligent coverage analysis with AI-powered insights for Flutter/Dart projects.

🚀 Features

Intelligent Coverage Analysis: Analyzes test coverage with focus on modified files using git integration
AI-Powered Insights: Generate automated code reviews and coverage insights using AI services
Git Integration: Automatically detects modified files by comparing against base branches
Multiple Output Formats: Supports HTML, JSON, console, and LCOV report formats
Configurable: Flexible configuration options via YAML files or command-line arguments
Modern CLI: Built with best practices using Mason Logger and CLI completion

📦 Installation

Global Installation (Recommended)

dart pub global activate smart_coverage

Local Installation

dart pub global activate --source=path <path to this package>

Verify Installation

smart_coverage --version

📖 Commands Overview

`init` - Generate Configuration File

Quickly generate a smart_coverage.yaml configuration file for your project.

smart_coverage init

This creates a configuration file with sensible defaults, making it easy to customize settings for your project.

`analyze` - Coverage Analysis

Analyze test coverage for your Flutter/Dart project with intelligent file detection and optional test insights.

smart_coverage analyze [options]

`setup` - Interactive Setup

Interactive setup wizard for more advanced configuration.

smart_coverage setup

`update` - CLI Updates

Update the smart_coverage CLI to the latest version.

smart_coverage update

Global Options

--version, -v: Show the current version
--verbose: Enable verbose logging with detailed output
--help: Show usage help

🚀 Quick Start

The fastest way to get started with smart_coverage:

# 1. Generate configuration file
smart_coverage init

# 2. Customize the generated smart_coverage.yaml file (optional)

# 3. Run analysis
smart_coverage analyze

That's it! The init command creates a configuration file with all common options pre-configured.

🔧 Init Command - Detailed Usage

The init command generates a smart_coverage.yaml configuration file with sensible defaults.

Basic Usage

# Generate configuration with default settings
smart_coverage init

# Generate minimal configuration
smart_coverage init --minimal

# Include AI configuration
smart_coverage init --with-ai

# Use custom output path
smart_coverage init --output my-config.yaml

# Overwrite existing configuration
smart_coverage init --force

Command Options

--output, -o <file>: Output path for the configuration file (default: smart_coverage.yaml)
--base-branch, -b <branch>: Default base branch for git comparisons (default: origin/main)
--with-ai: Include AI configuration section in the generated file
--minimal, -m: Generate minimal configuration with only essential options
--force, -f: Overwrite existing configuration file if it exists

Examples

# Generate full configuration with AI settings
smart_coverage init --with-ai --base-branch origin/develop

# Generate minimal config for quick setup
smart_coverage init --minimal

# Generate config in a custom location
smart_coverage init --output config/coverage.yaml

# Overwrite existing config
smart_coverage init --force

What Gets Generated?

The init command creates a YAML file with:

Essential settings: Base branch, output directory, output formats
Feature flags: Test insights, code review, performance profiling
Comments and tips: Helpful explanations for each option
AI configuration (when --with-ai is used): Ready-to-use AI service settings

After running init, you can:

Review the generated file and customize as needed
Simply run smart_coverage analyze without any additional flags
All settings from the config file will be automatically applied

🔍 Analyze Command - Detailed Usage

The analyze command is the core functionality of smart_coverage, providing intelligent coverage analysis with git integration and test insights.

Basic Usage

# Analyze modified files compared to main branch
smart_coverage analyze --base-branch main

# Analyze specific package with custom output
smart_coverage analyze --package-path ./my_project --output-dir ./reports

# Quick analysis with existing coverage data
smart_coverage analyze --skip-tests --lcov-file coverage/lcov.info

Command Options

Required Options

--base-branch, -b <branch>: Base branch to compare against for detecting modified files
- Example: --base-branch main, --base-branch origin/develop
- Tip: Use origin/main for remote branches to avoid "unknown revision" errors

Path and File Options

--package-path, -p <path>: Path to the Flutter/Dart package to analyze (default: .)
- Example: --package-path ./packages/core
- Tip: Use absolute paths for packages outside current directory
--output-dir, -o <directory>: Output directory for generated reports (default: coverage/smart_coverage)
- Example: --output-dir ./build/coverage
- Tip: Directory will be created automatically if it doesn't exist
--config, -c <file>: Path to configuration file
- Example: --config smart_coverage.yaml
- Tip: Use config files for consistent team settings
--lcov-file, -l <file>: Path to LCOV coverage file (default: coverage/lcov.info)
- Example: --lcov-file build/coverage/lcov.info
- Tip: Ensure the file exists or use --skip-tests to generate it first

Execution Control

--skip-tests: Skip running tests and use existing coverage data
- Use case: When you already have fresh coverage data
- Tip: Speeds up analysis significantly for large projects

AI-Powered Features

--test-insights: Enable AI-powered insights generation
- Features: Generates intelligent analysis of coverage patterns
- Tip: Requires AI service configuration (see Configuration section)
--code-review: Generate AI-powered code review
- Features: Creates detailed code review based on coverage data
- Tip: Best used with --test-insights flag for comprehensive analysis

Performance Optimization

--profile: Enable performance profiling and optimization
- Features: Monitors operation duration, memory usage, and provides optimization recommendations
- Benefits: Identifies bottlenecks in large codebases and suggests performance improvements
- Tip: Use with --verbose to export detailed performance reports

Output and Formatting

--output-formats <formats>: Output formats to generate (default: console)
- Available formats: console, html, json, lcov
- Examples:
  - --output-formats console,html - Console + HTML reports
  - --output-formats json - JSON only for CI integration
  - --output-formats html,json,lcov - Multiple formats
- Tip: Use html for detailed visual reports, json for CI/CD integration
--dark-mode: Use dark theme for HTML reports (default: true)
- Tip: Use --no-dark-mode to disable dark theme

🎯 Usage Examples

Basic Coverage Analysis

# Analyze changes against main branch
smart_coverage analyze --base-branch origin/main

# Analyze with HTML report
smart_coverage analyze --base-branch main --output-formats html

Advanced Analysis with AI

# Full AI-powered analysis
smart_coverage analyze \
  --base-branch origin/main \
  --test-insights \
  --code-review \
  --output-formats console,html,json

# Quick test insights on existing coverage
smart_coverage analyze \
  --skip-tests \
  --test-insights \
  --lcov-file coverage/lcov.info

CI/CD Integration

# Optimized for CI pipelines
smart_coverage analyze \
  --base-branch origin/main \
  --output-formats json \
  --output-dir ./coverage-reports \
  --no-dark-mode

Multi-package Projects

# Analyze specific package
smart_coverage analyze \
  --package-path ./packages/core \
  --base-branch main \
  --output-dir ./reports/core

# Using configuration file
smart_coverage analyze \
  --config ./tools/smart_coverage.yaml \
  --base-branch origin/develop

Performance Profiling for Large Codebases

# Enable performance monitoring
smart_coverage analyze \
  --base-branch origin/main \
  --profile

# Detailed performance analysis with export
smart_coverage analyze \
  --base-branch origin/main \
  --profile \
  --verbose \
  --output-formats console,html

# Profile large projects with optimization recommendations
smart_coverage analyze \
  --package-path ./large_project \
  --base-branch main \
  --profile \
  --skip-tests

🛠️ Configuration File

Create a smart_coverage.yaml file for consistent settings:

package_path: "."
base_branch: "origin/main"
output_dir: "coverage/smart_coverage"
skip_tests: false
test_insights: true
code_review: true
profile: false  # Enable performance profiling
dark_mode: true
output_formats:
  - "console"
  - "html"
  - "json"
ai_config:
  provider: "gemini"
  model: "gemini-pro"

💡 Pro Tips

Git Branch Issues: Use origin/main instead of main if you get "unknown revision" errors
Performance: Use --skip-tests when you have fresh coverage data to speed up analysis
CI Integration: Use --output-formats json for machine-readable output in CI/CD
Large Projects: Consider analyzing specific packages with --package-path
AI Features: Ensure proper AI service configuration before using --test-insights or --code-review
Report Viewing: HTML reports provide the most detailed and visual coverage analysis
Performance Profiling: Use --profile for large codebases (1000+ files) to get optimization recommendations
Memory Optimization: Performance profiling helps identify memory bottlenecks and suggests batch processing improvements

🧪 Generating Coverage Data

Before using smart_coverage, ensure you have coverage data:

# Generate coverage data
dart test --coverage=coverage
dart pub global run coverage:format_coverage --lcov --in=coverage --out=coverage/lcov.info

# Then analyze with smart_coverage
smart_coverage analyze --base-branch main

Alternative: Let smart_coverage handle it

# smart_coverage will run tests and generate coverage automatically
smart_coverage analyze --base-branch main

🤖 AI Configuration

To use AI-powered features, configure your AI service:

Environment Variables

# For Gemini AI (Google)
export GEMINI_API_KEY="your-api-key-here"

# For OpenAI
export OPENAI_API_KEY="your-api-key-here"

Configuration File

ai_config:
  provider: "gemini"  # or "openai", "claude"
  model: "gemini-pro"
  api_key_env: "GEMINI_API_KEY"
  provider_type: "api"  # or "local"

🚨 Troubleshooting

Common Issues

"Unknown revision 'main'"

Problem: Git can't find the specified branch.

Solution: Use the full remote branch name:

# Instead of
smart_coverage analyze --base-branch main

# Use
smart_coverage analyze --base-branch origin/main

"No coverage data found"

Problem: LCOV file doesn't exist or is empty.

Solutions:

Generate coverage data first:

dart test --coverage=coverage
dart pub global run coverage:format_coverage --lcov --in=coverage --out=coverage/lcov.info

Or let smart_coverage handle it (don't use --skip-tests):
```
smart_coverage analyze --base-branch main
```

"No modified files detected"

Problem: No files have changed compared to the base branch.

Solutions:

Check if you're on the right branch:
```
git branch
git status
```
Verify the base branch exists:
```
git branch -a
```
Make some changes and commit them, or analyze all files by omitting --base-branch

AI Features Not Working

Problem: Test insights or code review not generating.

Solutions:

Check API key configuration:

echo $GEMINI_API_KEY  # Should not be empty

Verify internet connection for API-based services
Check configuration file syntax if using config files

Debug Mode

Use verbose logging for detailed troubleshooting:

smart_coverage analyze --base-branch main --verbose

🔧 Development

Running from Source

# Clone the repository
git clone https://github.com/your-username/smart_coverage.git
cd smart_coverage

# Install dependencies
dart pub get

# Run from source
dart run bin/smart_coverage.dart analyze --help

Running Tests

# Run all tests
dart test

# Run tests with coverage
dart test --coverage=coverage
dart pub global run coverage:format_coverage --lcov --in=coverage --out=coverage/lcov.info

# View coverage report
genhtml coverage/lcov.info -o coverage/
open coverage/index.html

📊 Coverage Badge Automation

The coverage badge in this README is automatically updated! Here's how:

Automated Options

1️⃣ GitHub Actions (Recommended for Teams)

The badge auto-updates on every push to main:

✅ Runs tests automatically
📊 Calculates coverage percentage
🎨 Updates badge with color-coding
💬 Comments coverage on PRs

Setup: Already configured! Just push to GitHub.

2️⃣ Local Scripts (For Development)

Quick update with Makefile:

make badge          # Update badge (recommended)
make html-report    # Generate and open HTML report
make coverage-summary  # Show quick coverage stats

Or use individual scripts:

# Dart script (cross-platform)
dart run tool/update_coverage_badge.dart


#### 3️⃣ Git Pre-Commit Hook (Automatic Local Updates)
Install once, badge updates automatically on every commit:
```sh
make install-hooks
# or
cp tool/pre-commit .git/hooks/pre-commit

Now the badge updates automatically when you commit test/source changes!

Badge Color Scheme

Coverage	Color	Badge
≥90%	🟢 Bright Green	Excellent
≥80%	🟢 Green	Good
≥70%	🟡 Yellow	Acceptable
≥60%	🟠 Orange	Needs Improvement
<60%	🔴 Red	Poor

Quick Reference

# See all available commands
make help

# Complete workflow
make all            # Clean, test, analyze, and generate reports

# Individual steps
make test           # Run tests only
make coverage       # Generate coverage data
make badge          # Update badge
make html-report    # Generate visual report

For detailed documentation, see tool/README.md.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for your changes
Ensure tests pass (dart test)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

This project follows Very Good Analysis guidelines:

# Check code style
dart analyze

# Format code
dart format .

📄 License

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

🙏 Acknowledgments

Built with Very Good CLI
Powered by Mason Logger for beautiful CLI output
Uses LCOV format for coverage data

Smart Coverage

🚀 Features

📦 Installation

Global Installation (Recommended)

Local Installation

Verify Installation

📖 Commands Overview

init - Generate Configuration File

analyze - Coverage Analysis

setup - Interactive Setup

update - CLI Updates

Global Options

🚀 Quick Start

🔧 Init Command - Detailed Usage

Basic Usage

Command Options

Examples

What Gets Generated?

🔍 Analyze Command - Detailed Usage

Basic Usage

Command Options

Required Options

Path and File Options

Execution Control

AI-Powered Features

Performance Optimization

Output and Formatting

🎯 Usage Examples

Basic Coverage Analysis

Advanced Analysis with AI

CI/CD Integration

Multi-package Projects

Performance Profiling for Large Codebases

🛠️ Configuration File

💡 Pro Tips

🧪 Generating Coverage Data

Alternative: Let smart_coverage handle it

🤖 AI Configuration

Environment Variables

Configuration File

🚨 Troubleshooting

Common Issues

"Unknown revision 'main'"

"No coverage data found"

"No modified files detected"

AI Features Not Working

Debug Mode

🔧 Development

Running from Source

Running Tests

📊 Coverage Badge Automation

Automated Options

1️⃣ GitHub Actions (Recommended for Teams)

2️⃣ Local Scripts (For Development)

Badge Color Scheme

Quick Reference

🤝 Contributing

Development Setup

Code Style

📄 License

🙏 Acknowledgments

Libraries

smart_coverage package

`init` - Generate Configuration File

`analyze` - Coverage Analysis

`setup` - Interactive Setup

`update` - CLI Updates