add docs/XCODE_INTEGRATION_COMPONENTS.md

Author: chadparker

Docs/XCODE_INTEGRATION_COMPONENTS.md

@@ -0,0 +1,163 @@
+# Xcode Integration Components Guide
+
+This guide breaks down which components in the CopilotForXcode project are needed for Xcode interaction versus Copilot-specific features. Use this when building a parallel app that needs to monitor and communicate with Xcode without Copilot functionality.
+
+## **Essential Xcode Monitoring Components**
+
+### Core Xcode State Monitoring
+These components provide the fundamental ability to monitor Xcode's state in real-time:
+
+#### **`Tool/Sources/XcodeInspector/`** - Central Coordinator
+- **`XcodeInspector.swift`** - Main coordinator that publishes Xcode state
+- **`Apps/XcodeAppInstanceInspector.swift`** - Xcode-specific window and document tracking
+- **`XcodeWindowInspector.swift`** - Window-level inspection
+- **`SourceEditor.swift`** - Editor content and cursor management
+
+**Published State Properties:**
+```swift
+@Published public var activeDocumentURL: URL?
+@Published public var activeWorkspaceURL: URL? 
+@Published public var focusedWindow: XcodeWindowInspector?
+@Published public var focusedEditor: SourceEditor?
+@Published public var focusedElement: AXUIElement?
+```
+
+#### **`Tool/Sources/ActiveApplicationMonitor/`** - App State Tracking
+- **`ActiveApplicationMonitor.swift`** - Tracks which applications are active/running
+- Uses `NSWorkspace.didActivateApplicationNotification` for real-time updates
+- Provides: `isActive`, `isXcode`, process identifiers, lifecycle events
+
+#### **`Tool/Sources/AXExtension/`** - Accessibility API Interface
+- **`AXUIElement.swift`** - Core accessibility API extensions
+- Provides UI element access: `selectedTextRange`, `value`, `isFocused`, `isSourceEditor`
+- Element navigation: `parent`, `children`, `focusedElement`, `window`
+- Xcode detection: `isXcodeWorkspaceWindow`, `isEditorArea`
+
+#### **`Tool/Sources/AXNotificationStream/`** - Real-time Events
+- **`AXNotificationStream.swift`** - Real-time accessibility event monitoring
+- Monitors: Focus changes, title changes, window moves/resizes, element destruction
+- Features: Configurable run loops, retry with backoff, permission detection
+
+#### **`Tool/Sources/AXHelper/`** - Accessibility Utilities
+- **`AXHelper.swift`** - Higher-level accessibility operations
+- Code injection, cursor management, scroll position handling
+
+### Communication Infrastructure (if needed)
+
+#### **`Tool/Sources/XPCShared/`** - XPC Communication
+- **`XPCServiceProtocol.swift`** - Service protocols
+- **`XcodeInspectorData.swift`** - Xcode state data types
+- **`Models.swift`** - Shared data models
+
+#### **`ExtensionService/XPCController.swift`** - Service Coordination
+- Anonymous XPC listener for cross-process communication
+- Bridge management and connection lifecycle
+- Data exposure API: `getXcodeInspectorData()`
+
+#### **`EditorExtension/SourceEditorExtension.swift`** - Xcode Menu Integration
+- Official Xcode source editor extension
+- Command registration for custom menu items
+- XPC service wake-up and communication
+
+### Supporting Infrastructure
+
+#### **`Tool/Sources/Workspace/`** - File System Management
+- **`Workspace.swift`** - Project and workspace management
+- **`WorkspacePool.swift`** - Multiple workspace handling
+- **File watching components** - Monitor file system changes
+
+#### **`Tool/Sources/Preferences/`** - Configuration
+- **`AppStorage.swift`** - UserDefaults with property wrappers
+- **`Keys.swift`** - Preference key definitions
+- **`UserDefaults.swift`** - Type-safe preference access
+
+#### **`Tool/Sources/Logger/`** - Logging
+- **`Logger.swift`** - Centralized logging infrastructure
+- **`FileLogger.swift`** - File-based logging
+
+#### **`Tool/Sources/UserDefaultsObserver/`** - Settings Observation
+- **`UserDefaultsObserver.swift`** - Real-time settings changes
+
+## **Copilot-Specific Components (Not Needed)**
+
+### GitHub Copilot Integration
+- **`Tool/Sources/GitHubCopilotService/`** - All Language Server integration
+- **`Tool/Sources/BuiltinExtension/`** - Copilot extension provider
+- **`Tool/Sources/SuggestionProvider/`** - Code suggestion services
+- **`Tool/Sources/SuggestionBasic/`** - Suggestion data types
+- **`Tool/Sources/ConversationServiceProvider/`** - Chat conversation handling
+- **`Tool/Sources/TelemetryService/`** - Usage telemetry
+
+### UI Components for Copilot Features
+- **`Core/Sources/SuggestionWidget/`** - Code suggestion UI
+- **`Core/Sources/ConversationTab/`** - Chat interface
+- **`Core/Sources/ChatService/`** - Chat functionality
+- **`Core/Sources/SuggestionService/`** - Suggestion management
+- **`Core/Sources/PromptToCodeService/`** - Code generation
+- **`Tool/Sources/ChatAPIService/`** - Chat API integration
+- **`Tool/Sources/ChatTab/`** - Chat tab management
+
+### Server Components
+- **`Server/`** - All Node.js/TypeScript web components
+- Monaco editor integration, terminal integration, webpack build
+
+## **Minimal Architecture for Xcode Monitoring**
+
+### Recommended Component Structure
+```
+Tool/Sources/
+├── ActiveApplicationMonitor/     # App state tracking
+├── AXExtension/                 # Accessibility API
+├── AXNotificationStream/        # Real-time events  
+├── AXHelper/                    # AX utilities
+├── XcodeInspector/              # Central coordinator
+├── XPCShared/                   # Communication (optional)
+├── Logger/                      # Logging
+├── Preferences/                 # Configuration
+├── UserDefaultsObserver/        # Settings
+└── Workspace/                   # File management
+```
+
+### Core Data Flow Pattern
+```
+1. ActiveApplicationMonitor → Detect Xcode launch/focus
+2. AXNotificationStream → Real-time UI change events  
+3. XcodeInspector → Aggregate and publish state
+4. XcodeAppInstanceInspector → Extract specific data
+5. AXUIElement extensions → Low-level element access
+6. XPC Service → Expose data to extensions (optional)
+```
+
+### Key Published Data
+The `XcodeInspector` provides real-time awareness of:
+- **Active File**: `activeDocumentURL: URL?`
+- **Workspace**: `activeWorkspaceURL: URL?`
+- **Editor State**: `focusedEditor: SourceEditor?`
+- **Cursor Position**: Available through `SourceEditor.selectedTextRange`
+- **Editor Content**: Available through `SourceEditor.getContent()`
+
+## **Implementation Notes**
+
+### Accessibility Permissions
+- Requires macOS Accessibility permission
+- Automatic permission detection and retry mechanisms
+- Robust error handling for permission issues
+
+### Performance Optimizations
+- **Debounced Updates**: Prevents excessive state changes
+- **Selective Monitoring**: Only tracks relevant UI elements  
+- **Async Processing**: Non-blocking state updates
+- **Memory Management**: Proper cleanup of observers
+
+### Error Recovery
+- **Automatic Restart**: When accessibility API corrupts
+- **Exponential Backoff**: For failed connections
+- **State Validation**: Consistency checking
+- **Graceful Degradation**: Fallback to cached data
+
+### Thread Safety
+- Uses global actors (`@XcodeInspectorActor`) for thread safety
+- All state updates happen on appropriate actors
+- Proper async/await patterns throughout
+
+This architecture provides comprehensive Xcode monitoring without any Copilot dependencies, giving you real-time awareness of files, workspaces, cursor position, and editor content.