Add README for circular dependency analysis deliverables

Co-authored-by: fduminy <143904+fduminy@users.noreply.github.com>

Author: Copilot

CIRCULAR_DEPENDENCY_README.md

@@ -0,0 +1,207 @@
+# Circular Dependency Analysis - README
+
+This directory contains a comprehensive analysis of the circular dependency between the `org.jnode.vm.core` and `rt` plugins in the JNode project.
+
+## Problem Statement
+
+The task was to:
+1. Read documentation in `docs/plugins`
+2. List detailed source-level dependencies between `org.jnode.vm.core` and `rt`
+3. Sort results by classes with fewer dependencies (involved in circular dependency)
+4. Propose solutions to break the circular dependency
+
+## Delivered Artifacts
+
+### 1. Analysis Tool: `analyze_vm_core_rt_cycle.py`
+
+**Purpose:** Automated tool to analyze the circular dependency between org.jnode.vm.core and rt at the Java source code level.
+
+**Usage:**
+```bash
+python3 analyze_vm_core_rt_cycle.py
+```
+
+**Output:**
+- Generates `VM_CORE_RT_CYCLE_DETAILED_ANALYSIS.md` with complete dependency list
+- Shows all 154 classes involved in the circular dependency
+- Lists classes sorted by number of dependencies (least dependencies first)
+- Separates vm.core → rt dependencies from rt → vm.core dependencies
+
+**What it does:**
+- Parses plugin descriptors to identify which packages belong to which plugins
+- Analyzes Java import statements in all source files
+- Maps dependencies at the class level
+- Generates detailed reports with actionable recommendations
+
+### 2. Detailed Analysis Report: `VM_CORE_RT_CYCLE_DETAILED_ANALYSIS.md`
+
+**Content:**
+- **154 classes** involved in the circular dependency
+- **113 classes** in org.jnode.vm.core that import from rt
+- **41 classes** in rt that import from org.jnode.vm.core
+- Each class listed with:
+  - Full qualified class name
+  - File path
+  - List of imports that create the circular dependency
+  - Number of dependencies
+- **Sorted by dependency count** (least dependencies first)
+
+**Key sections:**
+1. Summary statistics
+2. Classes in vm.core importing from rt (sorted)
+3. Classes in rt importing from vm.core (sorted)
+4. Recommendations to break the circular dependency
+
+### 3. Implementation Proposal: `BREAKING_VM_CORE_RT_CYCLE_PROPOSAL.md`
+
+**Content:**
+- **Three-phase approach** to breaking the circular dependency
+- **Phase 1:** Move JNodePermission to rt (quick win, 1 day)
+- **Phase 2:** Create org.jnode.vm.isolate.api plugin (medium effort, 3-5 days)
+- **Phase 3:** Document Native* pattern as intentional design
+- Detailed implementation steps for each phase
+- Risk assessment and testing plan
+- Timeline estimates
+
+**Key insight:**
+Not all circular dependencies should be eliminated. The analysis shows that 31 of 41 rt → vm.core dependencies are in Native* implementation classes, which represent **intentional architectural coupling** between the VM and runtime.
+
+### 4. Executive Summary: `CIRCULAR_DEPENDENCY_SUMMARY.md`
+
+**Purpose:** High-level overview of findings and recommendations
+
+**Content:**
+- Quick reference to all deliverables
+- Key findings and statistics
+- Classes with least dependencies (best refactoring candidates)
+- Architecture insights
+- Next steps and recommendations
+
+## Key Findings
+
+### Statistics
+
+| Metric | Value |
+|--------|-------|
+| Total classes in cycle | 154 |
+| Classes in vm.core importing rt | 113 |
+| Classes in rt importing vm.core | 41 |
+| Native* implementation classes | 31 |
+| javax.isolate wrapper classes | 4 |
+| Classes with 1 dependency | 33 |
+| Classes with 2-5 dependencies | 61 |
+| Classes with >5 dependencies | 60 |
+
+### Top Refactoring Candidates
+
+**From org.jnode.vm.core (classes with 1 dependency):**
+1. `VmSystemSettings` - imports java.util.Properties
+2. `JNodePermission` - imports java.security.BasicPermission ⭐ **Phase 1 target**
+3. `BaseVmArchitecture` - imports java.nio.ByteOrder
+4. `VmReflection` - imports java.lang.reflect.InvocationTargetException
+5. `ResourceManagerImpl` - imports javax.naming.NamingException
+
+**From rt (classes with 1 dependency):**
+1. `javax.isolate.LinkMessage` - imports org.jnode.vm.isolate.LinkMessageFactory ⭐ **Phase 2 target**
+2. `javax.isolate.Isolate` - imports org.jnode.vm.isolate.VmIsolate ⭐ **Phase 2 target**
+3. `javax.isolate.StreamBindings` - imports org.jnode.vm.isolate.VmStreamBindings ⭐ **Phase 2 target**
+4. `javax.isolate.Link` - imports org.jnode.vm.isolate.VmLink ⭐ **Phase 2 target**
+5. `java.lang.VMSecurityManager` - imports org.jnode.vm.VmSystem
+
+### Architecture Insight
+
+The analysis reveals an important architectural pattern:
+
+**Native* Classes Pattern:**
+- 31 out of 41 classes in rt that depend on vm.core are "Native*" implementation classes
+- These classes implement JNode's native method implementations
+- Examples: NativeObject, NativeSystem, NativeThread, NativeRuntime, NativeUnsafe
+- This dependency is **by design** and represents the fundamental coupling between:
+  - The Java standard library (rt)
+  - The VM implementation (vm.core)
+
+**Conclusion:** This is not a bug - it's the bootstrap architecture. Accept and document it.
+
+## Recommended Actions
+
+### Immediate (Low Risk)
+✅ **Phase 1: Move JNodePermission**
+- Move from org.jnode.vm.core to rt
+- Reduces circular dependency by 1 class
+- Very low risk - simple permission class
+- Estimated time: 1 day including testing
+
+### Short Term (Medium Risk)
+⏭️ **Phase 2: Extract Isolate API**
+- Create org.jnode.vm.isolate.api plugin
+- Move isolate interface definitions
+- Reduces circular dependency by ~9 classes
+- Medium risk - requires interface extraction
+- Estimated time: 3-5 days including testing
+
+### Long Term (Documentation)
+📝 **Phase 3: Document Native* Pattern**
+- Document the Native* → vm.core pattern as intentional
+- Create architectural guidelines
+- Accept ~145 remaining dependencies as fundamental
+- Estimated time: 1 day
+
+## How to Use These Tools
+
+### To Analyze Current State
+```bash
+cd /home/runner/work/jnode/jnode
+python3 analyze_vm_core_rt_cycle.py
+# Review VM_CORE_RT_CYCLE_DETAILED_ANALYSIS.md
+```
+
+### To Track Progress After Changes
+```bash
+# After making changes to break dependencies
+python3 analyze_vm_core_rt_cycle.py
+# Compare new report with previous one
+diff VM_CORE_RT_CYCLE_DETAILED_ANALYSIS.md.old VM_CORE_RT_CYCLE_DETAILED_ANALYSIS.md
+```
+
+### To Implement Phase 1
+```bash
+# Follow steps in BREAKING_VM_CORE_RT_CYCLE_PROPOSAL.md
+# Phase 1 section provides exact commands and changes needed
+```
+
+## Related Documentation
+
+- **Plugin System:** `docs/plugins/plugin.md`
+- **Plugin Lists:** `docs/plugins/plugin-list.md`
+- **Previous Analysis:** `SOURCE_LEVEL_CYCLES_REPORT.md`
+- **Previous Summary:** `SOURCE_LEVEL_CYCLES_SUMMARY.md`
+
+## Notes
+
+### Why Not Eliminate All Dependencies?
+
+The analysis shows that full elimination of the circular dependency is:
+1. **Not necessary** - Some coupling is by design
+2. **Not beneficial** - Would require major architectural changes
+3. **Not practical** - Native implementations fundamentally need VM access
+
+### Focus Areas
+
+Instead of trying to eliminate all dependencies, focus on:
+1. ✅ Reducing **accidental** coupling (Phases 1 & 2)
+2. ✅ Documenting **intentional** coupling (Phase 3)
+3. ✅ Maintaining clear architectural boundaries
+4. ✅ Tracking dependencies over time
+
+## Contact
+
+For questions about this analysis, refer to:
+- The detailed reports in this directory
+- The plugin documentation in `docs/plugins/`
+- The JNode development team
+
+---
+
+**Analysis Date:** 2025-11-16  
+**Tool Version:** 1.0  
+**Status:** Analysis Complete, Implementation Proposed