diff --git a/QUALITY_STANDARDS.md b/QUALITY_STANDARDS.md new file mode 100644 index 0000000..29f9bcf --- /dev/null +++ b/QUALITY_STANDARDS.md @@ -0,0 +1,155 @@ +# EU-Utility Quality Standards + +This document defines the quality standards for EU-Utility to maintain peak code quality. + +## Code Organization + +``` +EU-Utility/ +├── core/ # Core functionality +│ ├── __init__.py +│ ├── main.py # Application entry point +│ ├── api/ # API layer +│ │ ├── __init__.py +│ │ ├── nexus_api.py +│ │ └── external_api.py +│ ├── services/ # Business logic +│ │ ├── __init__.py +│ │ ├── ocr_service.py +│ │ ├── screenshot.py +│ │ └── data_store.py +│ ├── ui/ # UI components +│ │ ├── __init__.py +│ │ ├── overlay.py +│ │ ├── dashboard.py +│ │ └── widgets/ +│ └── utils/ # Utilities +│ ├── __init__.py +│ ├── security.py +│ └── helpers.py +├── plugins/ # Plugin system +│ ├── __init__.py +│ ├── base_plugin.py +│ ├── plugin_manager.py +│ └── builtin/ # Built-in plugins +├── tests/ # Test suite +│ ├── __init__.py +│ ├── test_core/ +│ ├── test_plugins/ +│ └── test_integration/ +├── docs/ # Documentation +├── assets/ # Static assets +├── config/ # Configuration files +├── scripts/ # Utility scripts +├── setup.py # Package setup +├── pyproject.toml # Modern Python config +├── requirements.txt # Dependencies +├── requirements-dev.txt # Dev dependencies +├── Makefile # Build automation +├── LICENSE # MIT License +├── CHANGELOG.md # Version history +├── CONTRIBUTING.md # Contribution guide +└── README.md # Project readme +``` + +## Naming Conventions + +- **Files**: `snake_case.py` +- **Classes**: `PascalCase` +- **Functions/Methods**: `snake_case()` +- **Constants**: `UPPER_SNAKE_CASE` +- **Private**: `_leading_underscore` +- **Protected**: `_single_leading_underscore` + +## Code Style + +- Follow PEP 8 +- Maximum line length: 100 characters +- Use type hints for all function signatures +- Docstrings for all public APIs (Google style) +- Comments for complex logic + +## Documentation Standards + +### README.md +- Clear project description +- Installation instructions +- Quick start guide +- Feature list +- Screenshots/GIFs +- Contributing link +- License + +### Function Docstrings +```python +def example_function(param1: str, param2: int) -> bool: + """Short description. + + Longer description if needed. Can span multiple + lines and provide detailed context. + + Args: + param1: Description of param1. + param2: Description of param2. + + Returns: + Description of return value. + + Raises: + ValueError: When param2 is negative. + + Example: + >>> example_function("test", 42) + True + """ + pass +``` + +## Testing Standards + +- Unit tests for all functions +- Integration tests for workflows +- Minimum 80% code coverage +- Tests must pass before merging + +## Security Standards + +- No hardcoded credentials +- Input validation on all user inputs +- Use parameterized queries +- Secure defaults +- Regular dependency updates + +## Performance Standards + +- Profile before optimizing +- Use async for I/O operations +- Cache expensive operations +- Lazy loading for heavy resources +- Memory cleanup on exit + +## Git Standards + +- Commit messages: `type(scope): description` +- Types: feat, fix, docs, style, refactor, test, chore +- One logical change per commit +- Reference issues in commits +- Squash before merging to main + +## Release Process + +1. Update version in `__init__.py` +2. Update CHANGELOG.md +3. Run full test suite +4. Create git tag: `git tag vX.Y.Z` +5. Push to origin: `git push origin vX.Y.Z` +6. Create GitHub release + +## Code Review Checklist + +- [ ] Code follows style guide +- [ ] Tests added/updated +- [ ] Documentation updated +- [ ] No security vulnerabilities +- [ ] Performance acceptable +- [ ] Backwards compatible (or properly versioned) diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..e8cd4cd --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,55 @@ +# EU-Utility Improvement Roadmap + +## Immediate Priorities + +### 1. Code Cleanup +- [ ] Remove duplicate files (screenshot_vulnerable.py, data_store_vulnerable.py) +- [ ] Consolidate multiple screenshot implementations into one secure version +- [ ] Remove or archive test plugins from main codebase +- [ ] Clean up root directory (too many markdown files) + +### 2. Project Structure +- [ ] Create proper package structure with `__init__.py` files +- [ ] Organize core/ into logical subpackages (api, services, ui, utils) +- [ ] Move all plugins to plugins/builtin/ +- [ ] Separate tests into unit, integration, and e2e + +### 3. Documentation Consolidation +- [ ] Merge BUG_FIXES_APPLIED_DETAILED.md + BUG_FIX_REPORT.md → CHANGELOG.md +- [ ] Merge multiple refactoring reports into one +- [ ] Create single comprehensive README.md +- [ ] Archive old/duplicate documentation + +### 4. Code Quality +- [ ] Add type hints to all public APIs +- [ ] Add comprehensive docstrings +- [ ] Fix any PEP8 violations +- [ ] Add proper error handling + +### 5. Modern Python Packaging +- [ ] Create proper setup.py with all metadata +- [ ] Add pyproject.toml with build configuration +- [ ] Create MANIFEST.in for package distribution +- [ ] Separate requirements.txt into runtime and dev + +### 6. CI/CD +- [ ] Set up GitHub Actions for automated testing +- [ ] Add code quality checks (black, flake8, mypy) +- [ ] Automated releases on tag push + +### 7. Testing +- [ ] Ensure all existing tests pass +- [ ] Add missing test coverage +- [ ] Create integration test suite +- [ ] Add performance benchmarks + +## Completed + +- [x] Created QUALITY_STANDARDS.md +- [x] Spawned sub-agents for refactoring, docs, and packaging + +## In Progress + +- [ ] Code refactoring (eu-utility-refactor agent) +- [ ] Documentation improvements (eu-utility-docs agent) +- [ ] Packaging setup (eu-utility-packaging agent) diff --git a/core/__init__.py b/core/__init__.py index 3e7e853..cac9250 100644 --- a/core/__init__.py +++ b/core/__init__.py @@ -1,7 +1,4 @@ -# EU-Utility Core Package -""" -EU-Utility Core Package -======================= +"""EU-Utility Core Package. This package contains the core functionality for EU-Utility, including: - Plugin management and base classes @@ -11,7 +8,6 @@ This package contains the core functionality for EU-Utility, including: - Data persistence and settings Quick Start: ------------- from core.api import get_api from core.event_bus import get_event_bus, LootEvent @@ -19,130 +15,135 @@ Quick Start: bus = get_event_bus() Architecture: -------------- -- **api/**: Three-tier API system (PluginAPI, WidgetAPI, ExternalAPI) -- **services/**: Core services (OCR, screenshot, audio, etc.) -- **ui/**: UI components and views -- **utils/**: Utility modules (styles, security, etc.) + - **api/**: Three-tier API system (PluginAPI, WidgetAPI, ExternalAPI) + - **services/**: Core services (OCR, screenshot, audio, etc.) + - **ui/**: UI components and views + - **utils/**: Utility modules (styles, security, etc.) See individual modules for detailed documentation. """ +from __future__ import annotations + __version__ = "2.1.0" - -# Safe imports (no PyQt6 dependency) -from core.nexus_api import NexusAPI, get_nexus_api -from core.nexus_api import EntityType, SearchResult, ItemDetails, MarketData - -from core.log_reader import LogReader, get_log_reader - -from core.event_bus import ( - get_event_bus, - EventBus, - EventCategory, - BaseEvent, - SkillGainEvent, - LootEvent, - DamageEvent, - GlobalEvent, - ChatEvent, - EconomyEvent, - SystemEvent, -) - -# Data Store (SQLite) -from core.data import ( - SQLiteDataStore, - get_sqlite_store, - PluginState, - UserPreference, - SessionData, -) - -# Dashboard Widgets -from core.widgets import ( - DashboardWidget, - SystemStatusWidget, - QuickActionsWidget, - RecentActivityWidget, - PluginGridWidget, - WidgetGallery, - DashboardWidgetManager, - WIDGET_TYPES, - create_widget, -) - -# Enhanced Components -from core.dashboard_enhanced import ( - EnhancedDashboard, - DashboardContainer, - DashboardManager, - get_dashboard_manager, -) - -from core.activity_bar_enhanced import ( - EnhancedActivityBar, - AppDrawer, - PinnedPluginsArea, - get_activity_bar, -) - -from core.ui.settings_panel import ( - EnhancedSettingsPanel, - EnhancedSettingsView, -) - -# Version info VERSION = __version__ API_VERSION = "2.2" -# Data Store (SQLite) +# Safe imports (no PyQt6 dependency) +from core.nexus_api import ( + EntityType, + ItemDetails, + MarketData, + NexusAPI, + SearchResult, + get_nexus_api, +) +from core.log_reader import LogReader, get_log_reader +from core.event_bus import ( + BaseEvent, + ChatEvent, + DamageEvent, + EconomyEvent, + EventBus, + EventCategory, + GlobalEvent, + LootEvent, + SkillGainEvent, + SystemEvent, + get_event_bus, +) from core.data import ( - SQLiteDataStore, - get_sqlite_store, PluginState, - UserPreference, SessionData, + SQLiteDataStore, + UserPreference, + get_sqlite_store, +) +from core.security_utils import ( + DataValidator, + InputValidator, + PathValidator, + SecurityError, ) -# Dashboard Widgets -from core.widgets import ( - DashboardWidget, - SystemStatusWidget, - QuickActionsWidget, - RecentActivityWidget, - PluginGridWidget, - WidgetGallery, - DashboardWidgetManager, - WIDGET_TYPES, - create_widget, -) +# Lazy imports for Qt-dependent components +# Use functions to avoid importing PyQt6 at module load time -# Enhanced Components -from core.dashboard_enhanced import ( - EnhancedDashboard, - DashboardContainer, - DashboardManager, - get_dashboard_manager, -) -from core.activity_bar_enhanced import ( - EnhancedActivityBar, - AppDrawer, - PinnedPluginsArea, - get_activity_bar, -) +def _get_widgets(): + """Lazy load widget components.""" + from core.widgets import ( + DashboardWidget, + DashboardWidgetManager, + PluginGridWidget, + QuickActionsWidget, + RecentActivityWidget, + SystemStatusWidget, + WidgetGallery, + WIDGET_TYPES, + create_widget, + ) + return { + 'DashboardWidget': DashboardWidget, + 'DashboardWidgetManager': DashboardWidgetManager, + 'PluginGridWidget': PluginGridWidget, + 'QuickActionsWidget': QuickActionsWidget, + 'RecentActivityWidget': RecentActivityWidget, + 'SystemStatusWidget': SystemStatusWidget, + 'WidgetGallery': WidgetGallery, + 'WIDGET_TYPES': WIDGET_TYPES, + 'create_widget': create_widget, + } + + +def _get_dashboard(): + """Lazy load dashboard components.""" + from core.dashboard_enhanced import ( + DashboardContainer, + DashboardManager, + EnhancedDashboard, + get_dashboard_manager, + ) + return { + 'DashboardContainer': DashboardContainer, + 'DashboardManager': DashboardManager, + 'EnhancedDashboard': EnhancedDashboard, + 'get_dashboard_manager': get_dashboard_manager, + } + + +def _get_activity_bar(): + """Lazy load activity bar components.""" + from core.activity_bar_enhanced import ( + AppDrawer, + EnhancedActivityBar, + PinnedPluginsArea, + get_activity_bar, + ) + return { + 'AppDrawer': AppDrawer, + 'EnhancedActivityBar': EnhancedActivityBar, + 'PinnedPluginsArea': PinnedPluginsArea, + 'get_activity_bar': get_activity_bar, + } + + +def _get_settings_panel(): + """Lazy load settings panel components.""" + from core.ui.settings_panel import ( + EnhancedSettingsPanel, + EnhancedSettingsView, + ) + return { + 'EnhancedSettingsPanel': EnhancedSettingsPanel, + 'EnhancedSettingsView': EnhancedSettingsView, + } -from core.ui.settings_panel import ( - EnhancedSettingsPanel, - EnhancedSettingsView, -) __all__ = [ # Version 'VERSION', 'API_VERSION', - # Nexus API 'NexusAPI', 'get_nexus_api', @@ -150,11 +151,9 @@ __all__ = [ 'SearchResult', 'ItemDetails', 'MarketData', - # Log Reader 'LogReader', 'get_log_reader', - # Event Bus 'get_event_bus', 'EventBus', @@ -167,34 +166,20 @@ __all__ = [ 'ChatEvent', 'EconomyEvent', 'SystemEvent', - # Data Store 'SQLiteDataStore', 'get_sqlite_store', 'PluginState', 'UserPreference', 'SessionData', - - # Dashboard Widgets - 'DashboardWidget', - 'SystemStatusWidget', - 'QuickActionsWidget', - 'RecentActivityWidget', - 'PluginGridWidget', - 'WidgetGallery', - 'DashboardWidgetManager', - 'WIDGET_TYPES', - 'create_widget', - - # Enhanced Components - 'EnhancedDashboard', - 'DashboardContainer', - 'DashboardManager', - 'get_dashboard_manager', - 'EnhancedActivityBar', - 'AppDrawer', - 'PinnedPluginsArea', - 'get_activity_bar', - 'EnhancedSettingsPanel', - 'EnhancedSettingsView', + # Security + 'PathValidator', + 'InputValidator', + 'DataValidator', + 'SecurityError', + # Lazy loaders (documented but not directly exported) + '_get_widgets', + '_get_dashboard', + '_get_activity_bar', + '_get_settings_panel', ]