Skip to content

Commit 2c6f61d

Browse files
chadparkerchadparker
committed
add docs/XCODE_STATUS_MONITORING.md
1 parent b9fedb9 commit 2c6f61d

1 file changed

Lines changed: 189 additions & 0 deletions

File tree

‎Docs/XCODE_STATUS_MONITORING.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Copilot for Xcode: Complete Xcode Status Reading Architecture Map
2+
3+
Based on a thorough analysis of the codebase, here's the comprehensive map of how this project reads Xcode status:
4+
5+
## 🏗️ **Core Architecture Overview**
6+
7+
The project uses a **multi-layered approach** combining:
8+
1. **macOS Accessibility API** (primary method)
9+
2. **Xcode Editor Extensions** (direct integration)
10+
3. **XPC Inter-Process Communication** (service coordination)
11+
4. **NSWorkspace monitoring** (application state tracking)
12+
13+
---
14+
15+
## 📊 **Data Flow & Components**
16+
17+
### **1. Application State Monitoring**
18+
**Location**: `Tool/Sources/ActiveApplicationMonitor/ActiveApplicationMonitor.swift`
19+
- **Purpose**: Tracks which applications are active/running
20+
- **Key Data Captured**:
21+
- Active application status (`isActive`, `isXcode`)
22+
- Process identifiers
23+
- Application lifecycle events (launch/terminate)
24+
- **Real-time Updates**: Uses `NSWorkspace.didActivateApplicationNotification`
25+
26+
### **2. Accessibility-Based Xcode Monitoring**
27+
**Primary Components**:
28+
29+
**A. AXUIElement Extensions** (`Tool/Sources/AXExtension/AXUIElement.swift:1-330`)
30+
- **UI Element Properties**:
31+
- `selectedTextRange` (current cursor/selection)
32+
- `value` (editor content)
33+
- `isFocused`, `isSourceEditor` (element state)
34+
- `document`, `title`, `role` (element metadata)
35+
- **Element Hierarchy Navigation**:
36+
- `parent`, `children`, `focusedElement`
37+
- `window`, `focusedWindow` access
38+
- **Xcode-Specific Detection**:
39+
- `isXcodeWorkspaceWindow`
40+
- `isEditorArea`, `isSourceEditor`
41+
42+
**B. AX Notification Streaming** (`Tool/Sources/AXNotificationStream/AXNotificationStream.swift:8-170`)
43+
- **Real-time Event Monitoring**:
44+
- `kAXFocusedUIElementChangedNotification`
45+
- `kAXTitleChangedNotification`
46+
- `kAXWindowMovedNotification`/`kAXWindowResizedNotification`
47+
- `kAXUIElementDestroyedNotification`
48+
- **Performance Features**:
49+
- Configurable run loop modes
50+
- Automatic retry with backoff
51+
- Accessibility permission detection
52+
53+
**C. AX Helper Utilities** (`Tool/Sources/AXHelper/AXHelper.swift:5-70`)
54+
- **Code Injection**: Direct content manipulation via accessibility API
55+
- **Cursor Management**: Selection range preservation/restoration
56+
- **Scroll Position**: Viewport state maintenance
57+
58+
### **3. Centralized Xcode Inspector**
59+
**Location**: `Tool/Sources/XcodeInspector/XcodeInspector.swift:23-432`
60+
61+
**A. Published State Properties**:
62+
```swift
63+
@Published public var activeProjectRootURL: URL?
64+
@Published public var activeDocumentURL: URL?
65+
@Published public var activeWorkspaceURL: URL?
66+
@Published public var focusedWindow: XcodeWindowInspector?
67+
@Published public var focusedEditor: SourceEditor?
68+
@Published public var focusedElement: AXUIElement?
69+
@Published public var completionPanel: AXUIElement?
70+
```
71+
72+
**B. Real-time vs Cached Data**:
73+
- **Cached**: `activeDocumentURL`, `activeWorkspaceURL`
74+
- **Real-time**: `realtimeActiveDocumentURL`, `realtimeActiveWorkspaceURL`
75+
- **Source**: Real-time data extracted directly from window titles/elements
76+
77+
**C. Self-Healing Mechanisms**:
78+
- **Malfunction Detection**: Monitors for accessibility API corruption
79+
- **Auto-Recovery**: Automatic restart when inconsistencies detected
80+
- **Debounced Validation**: Prevents excessive restart attempts
81+
82+
### **4. Xcode App Instance Monitoring**
83+
**Location**: `Tool/Sources/XcodeInspector/Apps/XcodeAppInstanceInspector.swift:8-200+`
84+
85+
**A. Window-Level Inspection**:
86+
- **Workspace Window Detection**: `identifier == "Xcode.WorkspaceWindow"`
87+
- **Document URL Extraction**: From window title parsing
88+
- **Project Structure Analysis**: Workspace vs project distinction
89+
90+
**B. Real-time Data Extraction**:
91+
```swift
92+
public var realtimeDocumentURL: URL? // From focused window
93+
public var realtimeWorkspaceURL: URL? // From window title
94+
public var realtimeProjectURL: URL? // Derived from workspace/document
95+
```
96+
97+
**C. Notification Handling**:
98+
- **AX Event Processing**: 13 different notification types
99+
- **Async Stream**: `AsyncPassthroughSubject<AXNotification>`
100+
- **Window Focus Tracking**: Automatic inspector switching
101+
102+
### **5. Editor Extension Integration**
103+
**Location**: `EditorExtension/SourceEditorExtension.swift:11-91`
104+
105+
**A. Direct Xcode Integration**:
106+
- **XCSourceEditorExtension**: Official Xcode extension API
107+
- **Command Registration**: Built-in commands for suggestions/chat
108+
- **XPC Service Wake-up**: Automatic service initialization
109+
110+
**B. Available Commands**:
111+
- Suggestion controls (accept/reject/navigate)
112+
- Settings access
113+
- Chat integration
114+
- Real-time suggestion toggling
115+
116+
### **6. XPC Communication Layer**
117+
**Location**: `ExtensionService/XPCController.swift:5-87`
118+
119+
**A. Service Coordination**:
120+
- **Anonymous XPC Listener**: Cross-process communication
121+
- **Bridge Management**: Connection lifecycle handling
122+
- **Ping Mechanism**: Service health monitoring
123+
124+
**B. Data Exposure**:
125+
- **Inspector Data API**: `getXcodeInspectorData()`
126+
- **State Serialization**: JSON encoding of current Xcode state
127+
- **Background Permission Handling**: Automated permission requests
128+
129+
---
130+
131+
## 🔄 **Real-time Data Extraction Flow**
132+
133+
```
134+
1. NSWorkspace → Application Launch/Focus Detection
135+
2. AXNotificationStream → UI Change Events
136+
3. XcodeInspector → State Aggregation & Publishing
137+
4. XcodeAppInstanceInspector → Window-Specific Analysis
138+
5. AXUIElement Extensions → Element Property Reading
139+
6. XPC Service → Data Exposure to Extensions
140+
```
141+
142+
## 📍 **Key Data Points Tracked**
143+
144+
| Data Point | Source | Frequency | Method |
145+
|------------|--------|-----------|---------|
146+
| **Active File** | Window title parsing | Real-time | `realtimeDocumentURL` |
147+
| **Workspace** | Window title/AX tree | Real-time | `realtimeWorkspaceURL` |
148+
| **Cursor Position** | Focused element | Real-time | `selectedTextRange` |
149+
| **Editor Content** | AX value attribute | On-demand | `focusedEditor.getContent()` |
150+
| **UI State** | AX notifications | Event-driven | `focusedElement`, `completionPanel` |
151+
| **Project Root** | Workspace analysis | Cached | `activeProjectRootURL` |
152+
153+
## 🛡️ **Robustness Features**
154+
155+
- **Permission Monitoring**: Continuous accessibility permission validation
156+
- **Malfunction Detection**: Element consistency checking
157+
- **Auto-Recovery**: Intelligent restart mechanisms
158+
- **Backoff Strategies**: Exponential retry delays
159+
- **Thread Safety**: Global actor isolation (`@XcodeInspectorActor`)
160+
161+
## 🔧 **Key Implementation Details**
162+
163+
### Accessibility API Usage
164+
The project heavily relies on macOS Accessibility APIs to monitor Xcode's UI state:
165+
- Uses `AXUIElementCreateApplication()` to get app-level access
166+
- Monitors specific notification types for real-time updates
167+
- Implements robust error handling for permission issues
168+
- Provides fallback mechanisms when accessibility API fails
169+
170+
### Window Title Parsing
171+
Real-time file and workspace detection happens through:
172+
- Parsing Xcode workspace window titles
173+
- Extracting file paths from window identifiers
174+
- Distinguishing between workspace and project contexts
175+
- Handling edge cases like unsaved files and temporary documents
176+
177+
### Performance Optimizations
178+
- **Debounced Updates**: Prevents excessive state changes
179+
- **Selective Monitoring**: Only tracks relevant UI elements
180+
- **Async Processing**: Non-blocking state updates
181+
- **Memory Management**: Proper cleanup of observers and tasks
182+
183+
### Error Recovery
184+
- **Automatic Restart**: When accessibility API becomes corrupted
185+
- **Exponential Backoff**: For failed connection attempts
186+
- **State Validation**: Continuous consistency checking
187+
- **Graceful Degradation**: Fallback to cached data when real-time fails
188+
189+
This comprehensive architecture enables the Copilot for Xcode extension to maintain accurate, real-time awareness of Xcode's state while providing robust error handling and performance optimization.

0 commit comments

Comments
 (0)