Add QUALITY_STANDARDS.md and ROADMAP.md for peak quality initiative

2026-02-16 20:58:35 +00:00 · 2026-02-16 20:58:35 +00:00 · b2ec4e2f0f
parent bf1214b3ca
commit b2ec4e2f0f
3 changed files with 329 additions and 134 deletions
--- a/QUALITY_STANDARDS.md
+++ 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)
--- a/ROADMAP.md
+++ 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)
--- 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,7 +15,6 @@ 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
@ -28,121 +23,127 @@ Architecture:
 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
+# Lazy imports for Qt-dependent components
+# Use functions to avoid importing PyQt6 at module load time
+
+
+def _get_widgets():
+    """Lazy load widget components."""
    from core.widgets import (
        DashboardWidget,
-    SystemStatusWidget,
+        DashboardWidgetManager,
+        PluginGridWidget,
        QuickActionsWidget,
        RecentActivityWidget,
-    PluginGridWidget,
+        SystemStatusWidget,
        WidgetGallery,
-    DashboardWidgetManager,
        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,
+    }

-# Enhanced Components
+
+def _get_dashboard():
+    """Lazy load dashboard components."""
    from core.dashboard_enhanced import (
-    EnhancedDashboard,
        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 (
-    EnhancedActivityBar,
        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,
+    }
+

 __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',
 ]