flutter_ui_guard 0.0.3

A Flutter static analysis tool that detects UI performance issues, deep widget nesting, and missing best practices in widget trees.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.0.3 - 2026-01-25

🎉 Initial Release

Added

Core Features:

• ✅ Static widget tree analysis with configurable rules
• ✅ Comprehensive issue detection with 4 severity levels (Info, Warning, Error, Critical)
• ✅ Beautiful console report with emoji icons and color coding
• ✅ Performance metrics tracking (widget count, max depth, analysis time)

Analysis Rules:

• ✅ Const Detection - Identifies missing const keywords on Text, Icon, and Padding widgets
• ✅ Deep Nesting Warnings - Detects widget trees nested beyond configurable depth (default: 6 levels)
• ✅ Heavy Build Detection - Finds widgets with too many children that should use builder patterns
• ✅ Container Optimization - Suggests replacing empty Container with SizedBox
• ✅ Container Color/Decoration Conflict - Detects invalid use of both color and decoration properties
• ✅ Opacity Performance - Warns about expensive Opacity widgets and suggests alternatives
• ✅ ListView Optimization - Detects missing itemExtent or prototypeItem for better scrolling
• ✅ GestureDetector Suggestions - Recommends InkWell for Material Design tap effects
• ✅ MediaQuery Usage Checks - Helps identify potential rebuild issues
• ✅ Column to ListView - Suggests ListView.builder for columns with many children (>10)

Configuration Options:

• ✅ Customizable nesting depth threshold
• ✅ Customizable children count threshold
• ✅ Toggle for each analysis rule
• ✅ Verbose mode for detailed widget tree logging
• ✅ Full control over analysis behavior

Developer Experience:

• ✅ Type-safe GuardConfig class for configuration
• ✅ Structured GuardIssue model with severity, widget type, and suggestions
• ✅ GuardReport class with comprehensive statistics
• ✅ Actionable suggestions for every detected issue
• ✅ Clear documentation and code examples

Examples:

• ✅ Basic usage example
• ✅ Custom configuration example
• ✅ Production-ready widget analysis example
• ✅ Custom widget analysis example

Documentation

• ✅ Comprehensive README with usage examples
• ✅ API documentation with inline code comments
• ✅ Best practices guide
• ✅ Configuration guide with all available options

Future Enhancements (Planned)

v0.1.0:

• ❌ StatefulWidget rebuild analysis
• ❌ State management pattern detection
• ❌ Build method complexity scoring
• ❌ Custom rule support via plugins

v0.2.0:

• ❌ CI/CD integration support
• ❌ JSON/HTML report export
• ❌ GitHub Actions workflow
• ❌ Pre-commit hook support

v0.3.0:

• ❌ VSCode extension
• ❌ Android Studio / IntelliJ plugin
• ❌ Real-time analysis during development
• ❌ Auto-fix suggestions

v1.0.0:

• ❌ Complete widget catalog coverage
• ❌ Performance benchmarking
• ❌ Memory leak detection
• ❌ Custom widget analysis API

---

Version History

Unreleased

• Nothing yet!

---

Contributing

See something that should be added or changed? We welcome contributions!

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

---

Links

• GitHub Repository
• Issue Tracker
• pub.dev Package

---

Legend:

• ✅ = Implemented
• ❌ = Planned
• 🎉 = Major release
• 🐛 = Bug fix
• ⚡ = Performance improvement
• 📝 = Documentation
• 🔧 = Configuration