Refactor/cli

[ryanmccann1024]

📋 Pull Request Summary

PR Title: refactor(cli): implement modular CLI architecture with comprehensive configuration system

Related Issue(s):

Description:
This PR implements a comprehensive refactoring of the CLI architecture to support modular design patterns and improved configuration management. The refactor includes:

• Modular CLI Architecture: Migrated from monolithic CLI scripts to a centralized registry-based system with modular parsers
• Comprehensive Configuration Management: Implemented unified configuration system with INI fallback support and validation
• Package Restructuring: Reorganized codebase into logical modules (core/, cli/, modules/, etc.) for better maintainability
• Integration Improvements: Enhanced GUI-CLI integration and improved test coverage across all modules
• Infrastructure Updates: Added local development support, PR validation workflows, and improved exception handling

🔧 Type of Change

Primary Change Type:

• 🐛 Bug Fix - Non-breaking change that fixes an issue
• ✨ New Feature - Non-breaking change that adds functionality
• 💥 Breaking Change - Change that would cause existing functionality to break
• 🔄 Refactor - Code change that neither fixes a bug nor adds a feature
• 📚 Documentation - Documentation only changes
• 🧪 Tests - Adding missing tests or correcting existing tests
• 🏗️ Build/CI - Changes to build process or CI configuration
• 🎨 Style - Code style changes (formatting, missing semicolons, etc.)
• ⚡ Performance - Performance improvements
• 🔒 Security - Security vulnerability fixes

Component(s) Affected:

• CLI Interface (fusion/cli/)
• Configuration System (fusion/configs/)
• Simulation Core (fusion/core/)
• ML/RL Modules (fusion/modules/rl/, fusion/modules/ml/)
• Routing Algorithms (fusion/modules/routing/)
• Spectrum Assignment (fusion/modules/spectrum/)
• SNR Calculations (fusion/modules/snr/)
• Visualization (fusion/visualization/)
• GUI Interface (fusion/gui/)
• Unity/HPC Integration (fusion/unity/)
• Testing Framework (tests/)
• Documentation
• GitHub Workflows (.github/)
• Build/Dependencies

🧪 Testing

Test Coverage:

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed
• Existing tests still pass
• Performance impact assessed

Test Details:
All test files have been updated to work with the new modular architecture. Key testing areas include:

• CLI argument parsing and configuration loading
• Module import resolution and package structure
• RL pipeline integration and environment reset handling
• GUI-CLI integration and runner functionality
• Cross-platform compatibility and workflow validation

Test Configuration Used:

# Standard test configuration for simulation runs
[general_settings]
algorithm = dijkstra
node_file = TopologyZoo/GtsCe.graphml
num_requests = 1000
run_id = test_refactor_cli

Commands to Reproduce Testing:

# Run full test suite
python -m pytest tests/

# Test CLI functionality
python -m fusion.cli.run_sim run_sim --config_path test_config.ini --run_id test

# Test specific modules
python -m pytest tests/test_cli/ -v
python -m pytest tests/test_modules/ -v

Test Results:

• Operating System: macOS Darwin 24.5.0
• Python Version: 3.x (compatible with project requirements)
• Test Environment: Local development with CI validation

📊 Impact Analysis

Performance Impact:

• No performance impact
• Performance improved
• Minor performance decrease (acceptable)
• Significant performance impact (needs discussion)

Memory Usage:

• No change in memory usage
• Memory usage optimized
• Minor increase in memory usage
• Significant memory impact

Backward Compatibility:

• Fully backward compatible
• Minor breaking changes with migration path
• Major breaking changes (requires version bump)

Dependencies:

• No new dependencies
• New dependencies added (list in Additional Notes)
• Dependencies removed/updated

🔄 Migration Guide

Breaking Changes (if any):

• Import paths have changed due to package restructuring (e.g., fusion.cli.args instead of top-level imports)
• CLI entry points now use modular architecture with centralized registry
• Configuration loading now supports INI fallback with --config_path parameter

Migration Steps:

1. Update import statements to use new package structure (fusion.cli.*, fusion.core.*, etc.)
2. Update CLI invocations to use new modular entry points
3. Update configuration files to use new schema (if applicable)
4. Update any custom scripts to reference new module locations

Before/After Examples:

# Before (old usage)
from run_sim import main
from setup_helpers import generate_input_files

# After (new usage)  
from fusion.cli.run_sim import main
from fusion.sim.input_setup import generate_input_files

✅ Code Quality Checklist

Architecture & Design:

• Follows established architecture patterns
• Code is modular and follows separation of concerns
• Interfaces are well-defined and documented
• Error handling is comprehensive
• Logging is appropriate and informative

Code Standards:

• Code follows project style guidelines
• Variable and function names are descriptive
• Code is properly commented
• Complex logic is documented
• No dead code or unused imports

Configuration & CLI:

• CLI arguments follow established patterns
• Configuration validation updated (if needed)
• Schema updated for new config options
• Backward compatibility maintained for configs

Security:

• No sensitive information hardcoded
• Input validation performed where needed
• No security vulnerabilities introduced
• Dependencies scanned for vulnerabilities

📚 Documentation

Documentation Updates:

• Code comments added/updated
• API documentation updated
• User guide/tutorial updated
• Configuration reference updated
• CHANGELOG.md updated
• README updated (if needed)

Examples Added:

• Usage examples in docstrings
• Configuration examples
• CLI usage examples
• Integration examples

🚀 Deployment

Deployment Considerations:

• Safe to deploy to all environments
• Requires environment-specific configuration
• Needs database migration (if applicable)
• Requires manual steps (document below)

Manual Steps Required:
No manual steps required for deployment.

🔍 Review Guidelines

For Reviewers:

• PR description is clear and complete
• Code changes align with described functionality
• Tests are comprehensive and pass
• Documentation is adequate
• No obvious security issues
• Performance impact is acceptable

Review Focus Areas:

• CLI architecture and modular design patterns
• Configuration system integration and validation
• Package structure and import resolution
• Test coverage for refactored modules
• Backward compatibility and migration path

📝 Additional Notes

This refactor represents a significant architectural improvement that establishes a foundation for future development. The modular design makes the codebase more maintainable and extensible.

Open Questions:

• Should we add additional configuration validation for edge cases?
• Do we need more comprehensive documentation for the new architecture?

Future Work:

• Complete Unity/HPC integration updates for new architecture
• Add comprehensive API documentation
• Implement configuration schema validation
• Add integration examples and tutorials

Related PRs:
This PR consolidates work from multiple feature branches and sets the foundation for future modular enhancements.

---

🏁 Final Checklist

Before submitting this PR, confirm:

• I have followed the contributing guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

[ryanmccann1024]

Apologies for the 50 pipeline failures...You could argue this needs two branches but I might keep it at one.

Ready for your reviews @bozo-bud @arashr88

[ryanmccann1024]

I think after local run sim comparison tests pass and other comments I put down, this is good to go.

Also, the PR description needs to be filled in.

Let me know what you guys think.

[arashr88]

Great work @ryanmccann1024!