Comprehensive Code Review Tool for Flask Projects
A comprehensive code review tool for Flask applications that analyzes project structure, SQLAlchemy models, API patterns, and database configurations to ensure best practices and identify potential issues.
| Analysis Area | Purpose | Status |
|---|---|---|
| ποΈ Project Structure | Validates Flask project organization, required files, and configuration | β |
| π§ SQLAlchemy Models | Deep analysis of model definitions, relationships, constraints, and best practices | β |
| π API Patterns | Reviews Flask routes, blueprints, REST conventions, authentication, and error handling | β |
| ποΈ Database Analysis | Examines migrations, configurations, query patterns, and performance optimizations | β |
| π Multiple Reports | Console output with optional Markdown/JSON reports for documentation | β |
| π¨ Rich Terminal UI | Beautiful, colored output with emojis and professional formatting | β |
- β Entry point validation (app.py, main.py, etc.)
- β Directory organization (models/, views/, templates/, static/)
- β Configuration management (config.py, .env files)
- β Blueprint structure detection
- β Testing setup validation
- β Documentation presence
- β Model class structure and naming conventions
- β Table naming and column definitions
- β Primary key and foreign key validation
- β Relationship definitions and circular dependency detection
- β
Model methods (
__repr__,__str__) validation - β Model inheritance and mixins analysis
- β Route detection and Blueprint organization
- β REST API convention compliance
- β HTTP method usage patterns
- β Authentication and authorization checks
- β Input validation and error handling
- β API versioning and documentation
- β Security vulnerability detection
- β Migration setup (Alembic/Flask-Migrate)
- β Database configuration validation
- β Connection pooling and performance settings
- β Query pattern analysis and N+1 detection
- β Index usage and optimization suggestions
- β Security (hardcoded credentials detection)
FReview installs globally on your machine, making the freview command available from any directory. Choose the installation method that works best for your setup:
curl -sSL https://raw.githubusercontent.com/Chatelo/freview/main/install_freview.sh | bashThis script automatically detects the best installation method and installs FReview globally.
uv tool install git+https://github.com/Chatelo/freview.gitGlobal Installation: Makes freview command available system-wide
pipx install git+https://github.com/Chatelo/freview.gitGlobal Installation: Isolated dependencies with global freview command access
pip install --user git+https://github.com/Chatelo/freview.gitGlobal Installation: Traditional Python package installation with global access
Note: Currently installs from source. PyPI package (pip install freview) coming soon!
Download and run the installation script with specific method:
# Download the script
curl -O https://raw.githubusercontent.com/Chatelo/freview/main/install_freview.sh
chmod +x install_freview.sh
# Install with specific method
./install_freview.sh pipx # Using pipx
./install_freview.sh uv # Using uv
./install_freview.sh pip # Using pip
./install_freview.sh auto # Auto-detect (default)For contributors or testing:
git clone https://github.com/Chatelo/freview.git
cd freview
pip install -e .After installation, verify that FReview is working globally:
# Check version (works from any directory)
freview --version
# Show help (works from any directory)
freview --help
# Test on a project (run from anywhere)
freview review /path/to/your/flask/projectfreview review path_to_flask_project# Generate reports in multiple formats
freview review myproject --markdown --json --output-dir reports/
# Skip specific analysis areas
freview review myproject --skip-api --skip-db
# Verbose output for debugging
freview review myproject --verbose
# Analyze only specific components
freview review myproject --skip-structure --skip-models # API & DB only--markdown, -m: Generate Markdown report--json, -j: Generate JSON report--output-dir, -o: Specify output directory for reports--verbose, -v: Enable verbose output--skip-structure: Skip project structure analysis--skip-models: Skip SQLAlchemy model analysis--skip-api: Skip API pattern analysis--skip-db: Skip database analysis
β’ ποΈ Project Structure: Entry points, organization, configuration
β’ π§ SQLAlchemy Models: Definitions, relationships, best practices
β’ π API Patterns: Routes, blueprints, REST conventions, security
β’ οΏ½οΈ Database: Migrations, configurations, query patterns
β’ π Comprehensive Reports: Actionable insights and recommendations
After scanning, you'll find detailed analysis results in your terminal with color-coded insights:
π Reviewing Flask Project
π Project Path: /home/user/my-flask-app
ποΈ Project Structure Analysis
β
Structure looks good
β
Found app.py entry point
β
Configuration management detected
π§ SQLAlchemy Model Analysis
π models/user.py
β
User: Core model requirements satisfied
β
User: Uses foreign key constraints (2 found)
β
User: Defines relationships (3 found)
βΉοΈ User: Consider adding __repr__ method for better debugging
π models/post.py
β Post: Missing __tablename__ attribute
β οΈ Post: Class name should be PascalCase
π Post: Consider adding input validation
π API Pattern Analysis
π views/auth.py
β
Found 5 route(s) in auth.py
β
Good: Project uses 3 blueprint(s)
β οΈ Route 'delete_user' should include error handling
π Route 'admin_panel' may need authentication
ποΈ Database Analysis
π MIGRATIONS
β
Found 12 migration file(s)
β
Alembic configuration file present
β οΈ Migration 003_add_indexes.py contains potentially dangerous operation
π config.py
β
Database URI configuration present
π Warning: Potential hardcoded database credentials
π‘ Use environment variables: os.environ.get('DATABASE_URL')
π Saved Markdown report: review_report.md
π Saved JSON report: review_report.json
- Rich terminal display with colors and emojis
- Real-time progress indicators
- Categorized findings by analysis area
- Structured documentation with sections for each analysis area
- Actionable recommendations and best practices
- Code examples and implementation guides
- Priority-based issue categorization
- Machine-readable format for CI/CD integration
- Detailed metadata for each finding
- Programmatic access to analysis results
- Custom tooling integration support
- Route Detection: Automatically finds Flask routes and blueprints
- REST Compliance: Validates REST API conventions and best practices
- Security Review: Checks authentication, input validation, and error handling
- Architecture Analysis: Reviews API versioning, blueprint organization
- Migration Management: Validates Alembic/Flask-Migrate setup
- Configuration Security: Detects hardcoded credentials and security issues
- Performance Optimization: Identifies N+1 queries and indexing opportunities
- Connection Analysis: Reviews database pooling and connection settings
- Multi-format Output: Console, Markdown, and JSON reports
- Actionable Insights: Specific recommendations with implementation guides
- Priority Classification: Error, warning, and informational categorization
- Cross-component Analysis: Identifies relationships between different areas
FReview gracefully handles various scenarios:
β’ β Missing Dependencies: Continues analysis when optional components are unavailable
β’ π Invalid Structure: Provides guidance for incomplete or non-standard project layouts
β’ π§ Flexible Analysis: Individual analysis components can be skipped via CLI options
β’ π¨ Error Recovery: Detailed error reporting with suggestions for resolution
β οΈ Disclaimer: FReview is designed for code reviews and educational purposes, not as a definitive standard for production readiness.
π‘ Purpose: It serves as a helpful starting point for evaluating code quality and establishing best practices in your team's codebase.
οΏ½ Continuous Improvement: Regular updates include new analysis patterns and enhanced detection capabilities.
Found this helpful? Give it a β on GitHub!
If you encounter issues during installation:
Command not found after installation:
# Restart your terminal or reload your shell configuration
source ~/.bashrc # For bash
source ~/.zshrc # For zshPermission errors with pip:
# Use --user flag to install in user directory
pip install --user git+https://github.com/Chatelo/freview.gitPython version compatibility:
β’ Minimum required: Python 3.9+
β’ Check your version: python --version
For corporate networks:
# If behind proxy, configure git and pip accordingly
git config --global http.proxy http://proxy:port
pip install --proxy http://proxy:port --user git+https://github.com/Chatelo/freview.gitIf you need to remove FReview from your system:
uv tool uninstall freviewpipx uninstall freviewpip uninstall freviewIf you want to remove the PATH entries that were automatically added:
# For bash users - edit ~/.bashrc and remove the freview PATH line
nano ~/.bashrc
# For zsh users - edit ~/.zshrc and remove the freview PATH line
nano ~/.zshrc
# For fish users - edit ~/.config/fish/config.fish
nano ~/.config/fish/config.fishLook for and remove lines like:
export PATH="$HOME/.local/bin:$PATH"export PATH="$HOME/.local/share/uv/tools/bin:$PATH"
This project is licensed under the MIT License - see the LICENSE file for details.
See CHANGELOG.md for a detailed history of changes and releases.