mvn-tree-visualizer 1.4.0__tar.gz → 1.5.0__tar.gz

mvn_tree_visualizer-1.5.0/.github/copilot-instructions.md

@@ -0,0 +1,87 @@
+# Maven Dependency Tree Visualizer - AI Coding Agent Instructions
+
+## Architecture Overview
+
+This is a **command-line tool** that converts Maven dependency tree output into interactive HTML diagrams and JSON data. The tool follows a **pipeline architecture**:
+
+1. **Input Processing**: Merges multiple `maven_dependency_file` files from different Maven modules (`get_dependencies_in_one_file.py`)
+2. **Data Transformation**: Parses Maven tree format and converts to Mermaid diagram syntax (`diagram.py`, `outputs/html_output.py`)
+3. **Output Generation**: Creates themed HTML with interactive features or structured JSON (`outputs/`)
+4. **Watch Mode**: Real-time file monitoring for development workflows (`file_watcher.py`)
+
+## Key Components & Data Flow
+
+### Core Pipeline (`cli.py`)
+- Entry point validates inputs → merges dependency files → generates outputs
+- **Error handling is comprehensive** - uses custom exception hierarchy in `exceptions.py`
+- Supports both HTML (interactive) and JSON (programmatic) output formats
+
+### Multi-Module Maven Support (`get_dependencies_in_one_file.py`)
+- **Critical pattern**: Recursively finds and merges `maven_dependency_file` from all subdirectories
+- Maven projects often have complex module structures - tool handles this automatically
+- Generated intermediate file `dependency_tree.txt` is cleaned up unless `--keep-tree` is used
+
+### Mermaid.js Conversion (`outputs/html_output.py`)
+- **Node classification logic**: Root (blue), intermediate (orange), leaf (green) based on dependency relationships
+- **Sanitization pattern**: Maven artifact names → valid Mermaid node IDs (hyphens to underscores)
+- Tracks parent/child relationships to determine node types for consistent styling
+
+### Theme System (`themes.py`, `enhanced_template.py`)
+- **Consistent color scheme** across all themes via `STANDARD_COLORS`
+- Dark theme has specific text visibility fixes for Mermaid.js compatibility
+- Template includes pan/zoom, download functionality, keyboard shortcuts
+
+## Maven Integration Workflow
+
+The tool expects this Maven command to be run first:
+```bash
+mvn dependency:tree -DoutputFile=maven_dependency_file -DappendOutput=true
+```
+
+**Why this matters**: The tool is designed around Maven's specific output format and file placement in `target/` directories.
+
+## Development Conventions
+
+### Error Handling
+- Custom exception hierarchy: `MvnTreeVisualizerError` → specific error types
+- **Pattern**: Validate early, fail fast with helpful error messages including Maven commands
+- File operations wrapped with encoding and permission checks
+
+### Testing Patterns (`tests/`)
+- **Key test pattern**: Use temporary directories for file operations
+- Mock file system events for watch mode testing
+- Mermaid output validation focuses on relationships and styling classes
+
+### Code Organization
+- **Outputs as pluggable modules**: `outputs/html_output.py`, `outputs/json_output.py`
+- Validation logic centralized in `validation.py`
+- Theme configuration as data classes, not inheritance
+
+## Critical Implementation Details
+
+### Watch Mode (`file_watcher.py`)
+- Uses `watchdog` library with custom event handlers
+- Monitors for changes to any file named `maven_dependency_file` in directory tree
+- Callback-based architecture for diagram regeneration
+
+### Version Display Logic
+- `--show-versions` flag affects both HTML and JSON output
+- Version info stripped/included during Mermaid conversion, not at template level
+
+### File Path Handling
+- **Windows compatibility**: Uses `pathlib.Path` consistently
+- Intermediate files created in output directory, not temp
+- Directory creation is recursive (`parents=True, exist_ok=True`)
+
+## Common Debugging Workflows
+
+1. **No dependency files found**: Check if Maven command was run and generated files in `target/` dirs
+2. **Empty diagrams**: Verify Maven output format and encoding (UTF-8 expected)
+3. **Theme rendering issues**: Dark theme has specific CSS overrides for Mermaid.js text visibility
+4. **Watch mode not triggering**: Ensure file names match exactly (`maven_dependency_file`)
+
+## Extension Points
+
+- **New output formats**: Add modules to `outputs/` directory following existing pattern
+- **Custom themes**: Extend `THEMES` dict in `themes.py` with `Theme` objects
+- **New validation rules**: Add to `validation.py` following existing error patterns

{mvn_tree_visualizer-1.4.0 → mvn_tree_visualizer-1.5.0}/.github/workflows/release.yml

@@ -29,7 +29,7 @@ jobs:
         python-version: '3.13'
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v4
+      uses: astral-sh/setup-uv@v6
 
     - name: Install dependencies
       run: |

{mvn_tree_visualizer-1.4.0 → mvn_tree_visualizer-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mvn-tree-visualizer
-Version: 1.4.0
+Version: 1.5.0
 Summary: A simple command line tool to visualize the dependency tree of a Maven project in a graphical format.
 Project-URL: source, https://github.com/dyka3773/mvn-tree-visualizer
 Author-email: Iraklis Konsoulas <dyka3773@gmail.com>
@@ -57,12 +57,10 @@ pip install mvn-tree-visualizer
   - **JSON:** Creates a structured JSON representation of the dependency tree, perfect for scripting or integration with other tools.
 - **🎨 Theme System:** Choose from 2 built-in themes (minimal, dark) for clean and consistent diagram styling.
 - **🔄 Watch Mode:** Automatically regenerates diagrams when Maven dependency files change using the `--watch` flag.
-- **📋 Version Display:** Show or hide dependency versions in both HTML and JSON outputs using the `--show-versions` flag.
-- **⚡ Easy to Use:** A simple command-line interface that gets the job done with minimal configuration.
-- **📂 File Merging:** Automatically finds and merges multiple `maven_dependency_file` files from different subdirectories.
-- **🎨 Customizable Output:** Specify the output file name and location.
-- **💾 Enhanced Downloads:** Download diagrams as SVG or high-resolution PNG directly from the HTML page.
-- **🖱️ Interactive Features:** Hover tooltips, click-to-highlight connections, pan/zoom controls, and keyboard shortcuts.
+- **📋 Version Display:** Toggle dependency versions in outputs with `--show-versions`
+- **💾 Enhanced Downloads:** SVG and PNG export directly from browser
+- **📂 Smart File Handling:** Automatically finds and merges multiple `maven_dependency_file` files from different subdirectories.
+- **🎯 Color Coding:** Visual distinction between root, intermediate, and leaf dependencies
 
 ## How to Use
 

{mvn_tree_visualizer-1.4.0 → mvn_tree_visualizer-1.5.0}/README.md

@@ -37,12 +37,10 @@ pip install mvn-tree-visualizer
   - **JSON:** Creates a structured JSON representation of the dependency tree, perfect for scripting or integration with other tools.
 - **🎨 Theme System:** Choose from 2 built-in themes (minimal, dark) for clean and consistent diagram styling.
 - **🔄 Watch Mode:** Automatically regenerates diagrams when Maven dependency files change using the `--watch` flag.
-- **📋 Version Display:** Show or hide dependency versions in both HTML and JSON outputs using the `--show-versions` flag.
-- **⚡ Easy to Use:** A simple command-line interface that gets the job done with minimal configuration.
-- **📂 File Merging:** Automatically finds and merges multiple `maven_dependency_file` files from different subdirectories.
-- **🎨 Customizable Output:** Specify the output file name and location.
-- **💾 Enhanced Downloads:** Download diagrams as SVG or high-resolution PNG directly from the HTML page.
-- **🖱️ Interactive Features:** Hover tooltips, click-to-highlight connections, pan/zoom controls, and keyboard shortcuts.
+- **📋 Version Display:** Toggle dependency versions in outputs with `--show-versions`
+- **💾 Enhanced Downloads:** SVG and PNG export directly from browser
+- **📂 Smart File Handling:** Automatically finds and merges multiple `maven_dependency_file` files from different subdirectories.
+- **🎯 Color Coding:** Visual distinction between root, intermediate, and leaf dependencies
 
 ## How to Use
 

mvn_tree_visualizer-1.5.0/ROADMAP.md

@@ -0,0 +1,149 @@
+# Project Roadmap
+
+This document outlines the evolution and future direction of the `mvn-tree-visualizer` project. Major milestones show the progression from a basic tool to an enterprise-ready solution.
+
+## 🎉 Recently Completed ✅
+
+### v1.5.0 - Large Project Support & GitHub Issue #7 Resolution (Released)
+
+**Focus:** Enterprise-ready support for massive dependency trees and enhanced navigation.
+
+**Status:** Released July 19, 2025
+
+*   **GitHub Issue #7 Resolution (Completed):**
+    *   [x] **No More Size Limits**: Enhanced Mermaid configuration with `maxTextSize: 900000000`
+    *   [x] **Massive Edge Support**: Increased `maxEdges: 20000` for complex enterprise projects
+    *   [x] **50x Zoom Range**: Advanced zoom from 0.01x (overview) to 50x (detailed inspection)
+    *   [x] **Enhanced Performance**: Memory-optimized rendering for 1000+ dependency projects
+
+*   **Navigation Enhancements (Completed):**
+    *   [x] **Keyboard Shortcuts**: `Ctrl+R` (reset), `+/-` (zoom), `s` (download)
+    *   [x] **Smooth Zoom Controls**: Mouse wheel with 0.2 sensitivity for precise navigation
+    *   [x] **One-Click Reset**: Instant return to full diagram view
+    *   [x] **Error Prevention**: Zoom bounds validation and graceful error handling
+
+### Previous Major Releases ✅
+
+*   **v1.4.0 - Visual and Theme Enhancements** (July 17, 2025)
+    *   [x] Professional minimal and dark themes
+    *   [x] Enhanced HTML templates with interactive features
+    *   [x] SVG download functionality and improved user experience
+
+*   **v1.3.0 - User Experience Improvements** (July 9, 2025)
+    *   [x] Watch mode functionality with `--watch` flag
+    *   [x] Enhanced error handling system with comprehensive guidance
+    *   [x] Custom exception classes and validation modules
+    *   [x] Comprehensive test coverage and modular organization
+
+*   **Core Foundation** (Earlier versions)
+    *   [x] Multiple output formats (HTML and JSON)
+    *   [x] Dependency version display with `--show-versions`
+    *   [x] Multi-module Maven project support
+    *   [x] CI/CD workflows and comprehensive documentation
+    *   [x] `--theme` option with multiple built-in themes (default/minimal, dark, light)
+## 🔮 Future Development
+
+### v1.6.0 - Advanced Interactive Features 🎯 (Next Major Release)
+
+**Focus:** Enhanced interactivity and user experience for large enterprise projects.
+
+**Priority:** High - Building on the solid large project foundation with advanced user interaction.
+
+*   **Enhanced Node Search & Navigation (High Priority):**
+    *   [ ] **Smart Dependency Search:** Find nodes by dependency name with instant highlighting
+        *   **Technical Requirements:** Must highlight nodes WITHOUT moving or displacing SVG elements
+        *   **Approach:** Use SVG overlays or CSS-only highlighting instead of DOM manipulation
+        *   **Keyboard Shortcut:** `Ctrl+F` for search dialog
+        *   **Features:** Auto-complete, regex support, multiple match handling
+    *   [ ] **Dependency Path Tracing:** Highlight full dependency chains from root to selected node
+    *   [ ] **Scope-based Filtering:** Filter by dependency scope (compile, test, runtime, provided)
+
+*   **Advanced Navigation Controls (Medium Priority):**
+    *   [ ] **Zoom to Dependency Subtree:** Right-click zoom to focus on specific dependency branch
+    *   [ ] **Breadcrumb Navigation:** Show current zoom/focus location in large diagrams
+    *   [ ] **Mini-map Overlay:** Small overview map for orientation in large dependency trees
+
+*   **Enhanced User Experience (Medium Priority):**
+    *   [ ] **Rich Tooltips:** Detailed dependency information (groupId, artifactId, version, scope, licenses)
+    *   [ ] **Dependency Statistics:** Live counts of direct/transitive dependencies
+    *   [ ] **Export Enhancements:** PNG, PDF export with current zoom level and highlighting
+
+### v1.7.0 - Enterprise Integration
+
+**Focus:** Advanced functionality for enterprise development workflows.
+
+*   **CI/CD Integration:**
+    *   [ ] **GitHub Actions Integration:** Pre-built actions for automated diagram generation
+    *   [ ] **Jenkins Plugin:** Seamless integration with Jenkins pipelines
+    *   [ ] **Docker Container:** Official container images for containerized environments
+
+*   **Advanced Analysis:**
+    *   [ ] **Dependency Conflict Detection:** Visual highlighting of version conflicts
+    *   [ ] **Security Vulnerability Mapping:** Integration with vulnerability databases
+    *   [ ] **License Compliance:** Visual license information and compliance checking
+
+*   **Multi-Project Support:**
+    *   [ ] **Workspace Mode:** Handle multiple Maven projects simultaneously
+    *   [ ] **Cross-Project Dependencies:** Visualize dependencies between different projects
+    *   [ ] **Monorepo Support:** Enhanced support for large monorepo structures
+
+### v1.8.0+ - Advanced Capabilities 🚀
+
+**Focus:** Cutting-edge features for modern development workflows.
+
+*   **AI-Powered Features:**
+    *   [ ] **Dependency Recommendations:** AI suggestions for dependency updates and optimizations
+    *   [ ] **Architecture Insights:** Automated analysis of dependency architecture patterns
+    *   [ ] **Refactoring Suggestions:** Recommendations for dependency cleanup and optimization
+
+*   **Real-time Collaboration:**
+    *   [ ] **Shared Diagrams:** Cloud-based diagram sharing for team collaboration
+    *   [ ] **Live Updates:** Real-time diagram updates for team development
+    *   [ ] **Annotation System:** Team comments and notes on dependency diagrams
+
+## 🎯 Technical Debt & Maintenance
+
+### Ongoing Improvements
+*   **Performance Optimization:** Continuous improvements for larger and more complex projects
+*   **Browser Compatibility:** Ensure compatibility with all major browsers and versions
+*   **Accessibility:** Enhanced accessibility features for users with disabilities
+*   **Documentation:** Comprehensive API documentation and developer guides
+
+### Code Quality
+*   **Test Coverage:** Maintain high test coverage with focus on edge cases
+*   **Type Safety:** Full type annotation coverage and strict type checking
+*   **Security:** Regular security audits and dependency updates
+*   **Performance:** Continuous profiling and optimization of critical paths
+
+**Focus:** Advanced analysis and integration features.
+
+*   **Dependency Analysis:**
+    *   [ ] Dependency conflict detection and highlighting
+    *   [ ] Dependency statistics and analysis
+    *   [ ] Version mismatch warnings
+*   **Integration Capabilities:**
+    *   [ ] CI/CD pipeline integration examples
+    *   [ ] Docker support and containerization
+    *   [ ] Maven plugin version (if demand exists)
+
+## Long-Term Vision (6-12 Months+)
+
+*   **Web-Based Version:** A web-based version where users can paste their dependency tree and get a visualization without installing the CLI.
+*   **IDE Integration:** Plugins for VS Code, IntelliJ IDEA, or Eclipse for direct dependency visualization.
+*   **Multi-Language Support:** Extend beyond Maven to support Gradle, npm, pip, etc.
+
+## Release Strategy
+
+Each release follows this approach:
+- **Incremental Value:** Each version adds meaningful value without breaking existing functionality
+- **User-Driven:** Priority based on user feedback and common pain points
+- **Quality First:** New features include comprehensive tests and documentation
+- **Backward Compatibility:** CLI interface remains stable across minor versions
+
+## Contributing
+
+If you're interested in contributing to any of these features, please check out our [CONTRIBUTING.md](CONTRIBUTING.md) file for more information.
+
+---
+
+*Last updated: July 16, 2025*

mvn_tree_visualizer-1.5.0/examples/README.md

@@ -0,0 +1,164 @@
+# Examples
+
+This directory contains example Maven dependency files and their corresponding outputs to demonstrate the capabilities of mvn-tree-visualizer, including the enhanced features for large dependency trees.
+
+## Simple Project Example
+
+The `simple-project/` directory contains a modern Spring Boot 3.2 web application with:
+- **Spring Boot 3.2.0** - Latest stable version with Spring 6.1
+- **Apache Commons Lang3** - Utility library
+- **JUnit Jupiter 5.10.1** - Modern testing framework
+
+### 📁 Available Examples:
+- `diagram-minimal.html` - Clean light theme optimized for readability
+- `diagram-dark.html` - Dark theme perfect for low-light environments  
+- `dependencies.json` - JSON output for programmatic integration
+
+### 🛠️ Generation Commands:
+```bash
+cd examples/simple-project
+
+# Generate with different themes
+mvn_tree_visualizer --filename maven_dependency_file --output diagram-minimal.html
+mvn_tree_visualizer --filename maven_dependency_file --output diagram-dark.html --theme dark
+
+# Generate JSON output for automation
+mvn_tree_visualizer --filename maven_dependency_file --output dependencies.json --format json
+```
+
+## Complex Project Example
+
+The `complex-project/` directory demonstrates a **real-world enterprise microservice** with extensive dependencies:
+
+- **Spring Boot 3.2.0** with Web, Data JPA, and Actuator
+- **Database**: MySQL Connector with Hibernate ORM
+- **Monitoring**: Prometheus metrics and Micrometer
+- **Utilities**: Google Guava, Apache Commons
+- **Testing**: Comprehensive test stack with Testcontainers
+- **🎯 Over 100+ dependencies** - Perfect for testing large diagram capabilities!
+
+### 📁 Available Examples:
+- `diagram-minimal.html` - Clean visualization with version numbers
+- `diagram-dark.html` - Dark theme with complete dependency details
+
+### 🛠️ Generation Commands:
+```bash
+cd examples/complex-project
+
+# Generate with version numbers (recommended for enterprise projects)
+mvn_tree_visualizer --filename maven_dependency_file --output diagram-minimal.html --show-versions
+mvn_tree_visualizer --filename maven_dependency_file --output diagram-dark.html --theme dark --show-versions
+```
+
+## 🎨 Theme Comparison
+
+### Minimal Theme Features:
+- **Clean white background** for presentations and documentation
+- **Black text and borders** for high contrast and printing
+- **Monospace font** (Monaco/Menlo) for technical readability
+- **Optimized spacing** for large dependency trees
+
+### Dark Theme Features:
+- **Forest green background** with enhanced visibility fixes
+- **White text forced rendering** solves Mermaid.js dark theme issues
+- **Perfect for long coding sessions** and low-light environments
+- **Enhanced contrast** for better node distinction
+
+## 🔍 Enhanced Navigation Features
+
+Both examples demonstrate the powerful navigation capabilities:
+
+### Zoom Controls:
+- **Zoom In/Out Buttons**: `+` and `-` for precise control
+- **Reset Button**: `Ctrl+R` to return to full view
+- **Mouse Wheel**: Smooth zooming with 0.2 sensitivity
+- **Extreme Zoom Range**: 0.01x (full overview) to 50x (detailed inspection)
+
+### Keyboard Shortcuts:
+- `Ctrl+R` - Reset zoom and center
+- `+` / `=` - Zoom in
+- `-` - Zoom out  
+- `s` - Download SVG
+
+### Large Diagram Optimizations:
+- **No text size limits** - Handles projects with 1000+ dependencies
+- **Smooth performance** even with complex enterprise dependency trees
+- **Memory efficient** rendering with optimized edge handling
+
+## 🔧 Technical Details
+
+### Mermaid.js Configuration:
+```javascript
+maxTextSize: 900000000    // Virtually unlimited text rendering
+maxEdges: 20000          // Supports massive dependency graphs
+minZoom: 0.01           // 100x zoom out for full overview
+maxZoom: 50             // 50x zoom in for detailed inspection
+```
+
+### Color Coding:
+- **🔵 Blue nodes** - Root project dependencies
+- **🟠 Orange nodes** - Intermediate dependencies  
+- **🟢 Green nodes** - Leaf dependencies (no further deps)
+
+## 📊 Use Cases
+
+### Development Teams:
+- **Dependency analysis** and version conflict resolution
+- **Architecture reviews** and dependency health checks
+- **Documentation** for technical specifications
+
+### Enterprise Projects:
+- **Compliance audits** with complete dependency visibility
+- **Security analysis** of transitive dependencies
+- **Performance optimization** by identifying heavy dependency chains
+
+## 🎯 Getting Started
+
+1. **Generate your dependency file**:
+   ```bash
+   mvn dependency:tree -DoutputFile=maven_dependency_file -DappendOutput=true
+   ```
+
+2. **Create visualizations**:
+   ```bash
+   # Basic diagram
+   mvn_tree_visualizer --filename maven_dependency_file --output diagram.html
+   
+   # With versions for detailed analysis
+   mvn_tree_visualizer --filename maven_dependency_file --output diagram.html --show-versions
+   
+   # Dark theme for coding sessions
+   mvn_tree_visualizer --filename maven_dependency_file --output diagram.html --theme dark
+   ```
+
+3. **Open in browser** and explore with enhanced zoom and navigation controls!
+
+## Use Cases
+
+### 1. Quick Dependency Overview
+```bash
+mvn_tree_visualizer --filename maven_dependency_file --output overview.html
+```
+- Clean view without version numbers
+- Easy to identify dependency relationships
+
+### 2. Detailed Analysis with Versions
+```bash
+mvn_tree_visualizer --filename maven_dependency_file --output detailed.html --show-versions
+```
+- Shows all version information
+- Useful for debugging version conflicts
+
+### 3. Scripting and Automation
+```bash
+mvn_tree_visualizer --filename maven_dependency_file --output deps.json --format json
+```
+- Machine-readable JSON format
+- Perfect for CI/CD pipelines and automated analysis
+
+### 4. Multi-module Projects
+```bash
+mvn_tree_visualizer --directory ./my-project --output multi-module.html
+```
+- Automatically finds and merges dependency files from subdirectories
+- Comprehensive view of entire project structure