Skip to content

Commit 8db33e6

Browse files
lijie-leelijie-lee
authored
Merge pull request #1 from lijie-lee/copilot/fix-f17f9031-e8e3-4701-be02-cf25f4ee3411
Add comprehensive coding agent instructions for GitHub Copilot for Xcode
2 parents 8641fa9 + 2d64349 commit 8db33e6

1 file changed

Lines changed: 201 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,203 @@
1+
# GitHub Copilot for Xcode - Coding Agent Instructions
2+
3+
## Project Overview
4+
5+
**GitHub Copilot for Xcode** is a Swift-based Xcode Source Editor Extension that brings GitHub Copilot's AI-powered code suggestions directly into Xcode. This project consists of multiple components working together to provide real-time code completion and chat functionality.
6+
7+
### Repository Statistics
8+
- **Primary Language**: Swift (with supporting Node.js components)
9+
- **Platforms**: macOS 12+, Xcode 8+
10+
- **Architecture**: Multi-target Xcode project with Swift Package Manager dependencies
11+
- **Size**: ~50MB codebase with comprehensive test suite
12+
- **Dependencies**: Node.js/npm required for build process
13+
14+
## Build Instructions
15+
16+
### Prerequisites (CRITICAL)
17+
**Node.js and npm MUST be available in system PATH** - the build will fail without these:
18+
```bash
19+
# Verify prerequisites
20+
which npm && which node
21+
# If missing, ensure they're symlinked to /usr/local/bin:
22+
sudo ln -s $(which npm) /usr/local/bin
23+
sudo ln -s $(which node) /usr/local/bin
24+
```
25+
26+
### Build Commands
27+
**Always use the workspace file, not the project file:**
28+
```bash
29+
# Clean build (recommended first step)
30+
xcodebuild clean -workspace "Copilot for Xcode.xcworkspace" -scheme "Copilot for Xcode"
31+
32+
# Build for development
33+
xcodebuild build \
34+
-workspace "Copilot for Xcode.xcworkspace" \
35+
-scheme "Copilot for Xcode" \
36+
-configuration Debug
37+
38+
# Archive for release
39+
xcodebuild archive \
40+
-workspace "Copilot for Xcode.xcworkspace" \
41+
-scheme "Copilot for Xcode" \
42+
-configuration Release \
43+
-archivePath build/Archives/CopilotForXcode.xcarchive \
44+
CODE_SIGNING_ALLOWED="NO"
45+
```
46+
47+
### Testing
48+
**Always run tests using the test plan:**
49+
```bash
50+
# Run all unit tests (takes ~2-3 minutes)
51+
xcodebuild test \
52+
-workspace "Copilot for Xcode.xcworkspace" \
53+
-scheme "Copilot for Xcode" \
54+
-testPlan TestPlan
55+
56+
# Run specific test target
57+
xcodebuild test \
58+
-workspace "Copilot for Xcode.xcworkspace" \
59+
-scheme "Copilot for Xcode" \
60+
-only-testing:ServiceTests
61+
```
62+
63+
### Code Formatting
64+
**Always run SwiftFormat before committing:**
65+
```bash
66+
# Format all Swift code (uses .swiftformat config)
67+
swiftformat .
68+
69+
# Check formatting without changes
70+
swiftformat . --lint
71+
```
72+
73+
## Project Architecture
74+
75+
### Core Components
76+
- **Copilot for Xcode** (`/Copilot for Xcode/`) - Main host application providing settings UI
77+
- **EditorExtension** (`/EditorExtension/`) - Xcode Source Editor Extension (sandboxed)
78+
- **ExtensionService** (`/ExtensionService/`) - Background service implementing core features
79+
- **CommunicationBridge** (`/CommunicationBridge/`) - XPC communication between components
80+
81+
### Swift Packages
82+
- **Core** (`/Core/`) - Service logic, UI components, and host app implementations
83+
- **Tool** (`/Tool/`) - Shared utilities, preferences, and provider implementations
84+
85+
### Key Configuration Files
86+
- `Version.xcconfig` - Controls app version for all targets
87+
- `Config.xcconfig` - Bundle identifiers, URLs, and app configuration
88+
- `.swiftformat` - Code formatting rules (4 spaces, 100 char width)
89+
- `TestPlan.xctestplan` - Comprehensive test configuration
90+
91+
## Build System Details
92+
93+
### npm Integration
94+
The build system automatically downloads the Copilot Language Server via npm:
95+
```bash
96+
# This runs automatically during Xcode build
97+
npm -C Server install
98+
```
99+
100+
### Common Build Issues & Solutions
101+
102+
1. **"npm command not found" during build**
103+
- Ensure npm is in PATH: `sudo ln -s $(which npm) /usr/local/bin`
104+
- Restart Xcode after fixing PATH
105+
106+
2. **Package resolution failures**
107+
- Use `-disableAutomaticPackageResolution` flag
108+
- Delete `Package.resolved` files and rebuild
109+
110+
3. **SwiftUI Preview issues with Objective-C packages**
111+
- Switch to package product targets in scheme selector
112+
- Known limitation documented in DEVELOPMENT.md
113+
114+
4. **Extension not appearing in Xcode**
115+
- Check System Settings > Extensions > Xcode Source Editor
116+
- Restart Xcode after enabling extension
117+
118+
## Validation Pipeline
119+
120+
### GitHub Actions
121+
- **CodeQL Analysis** - Runs on push/PR to main branch
122+
- **Swift Build** - Uses Xcode 15.3 by default
123+
- **Security Scanning** - Automated via CodeQL
124+
125+
### Local Validation Steps
126+
```bash
127+
# 1. Format code
128+
swiftformat .
129+
130+
# 2. Build cleanly
131+
xcodebuild clean build -workspace "Copilot for Xcode.xcworkspace" -scheme "Copilot for Xcode"
132+
133+
# 3. Run tests
134+
xcodebuild test -workspace "Copilot for Xcode.xcworkspace" -scheme "Copilot for Xcode" -testPlan TestPlan
135+
136+
# 4. Check for common issues
137+
grep -r "TODO\|FIXME\|HACK" --include="*.swift" .
138+
```
139+
140+
## Directory Structure
141+
142+
```
143+
/
144+
├── .github/
145+
│ ├── workflows/codeql.yml # Security analysis
146+
│ └── actions/set-xcode-version/ # Xcode version management
147+
├── Core/ # Main service package
148+
│ ├── Package.swift
149+
│ ├── Sources/
150+
│ │ ├── Service/ # Extension service logic
151+
│ │ ├── HostApp/ # Main app implementation
152+
│ │ ├── SuggestionWidget/ # UI components
153+
│ │ └── Client/ # XPC client
154+
│ └── Tests/ # Unit tests
155+
├── Tool/ # Utilities package
156+
│ ├── Package.swift
157+
│ ├── Sources/
158+
│ │ ├── GitHubCopilotService/ # Copilot integration
159+
│ │ ├── Preferences/ # Settings management
160+
│ │ └── Workspace/ # File system utilities
161+
│ └── Tests/
162+
├── Server/ # Node.js dependencies
163+
│ ├── package.json # Copilot Language Server
164+
│ └── node_modules/ # Auto-generated
165+
├── Script/ # Utility scripts
166+
│ └── uninstall-app.sh # Development helper
167+
├── Copilot for Xcode/ # Main app target
168+
├── EditorExtension/ # Xcode extension
169+
├── ExtensionService/ # Background service
170+
├── CommunicationBridge/ # XPC service
171+
└── TestPlan.xctestplan # Test configuration
172+
```
173+
174+
## Development Notes
175+
176+
### Dependencies to Note
177+
- Swift Package Manager manages most dependencies
178+
- Node.js packages are embedded during build
179+
- Custom forks used for KeyboardShortcuts, CGEventOverride, and Highlightr
180+
- Sparkle framework for auto-updates
181+
182+
### Extension Architecture
183+
Due to Xcode extension sandboxing limitations:
184+
1. EditorExtension forwards content to ExtensionService via XPCService
185+
2. CommunicationBridge handles XPC communication
186+
3. ExtensionService implements all features outside sandbox
187+
188+
### Permissions Required
189+
- **Accessibility Permission** - For real-time editor content reading
190+
- **Xcode Source Editor Extension** - For integration with Xcode
191+
- Both must be enabled for full functionality
192+
193+
## Trust These Instructions
194+
195+
These instructions are comprehensive and tested. Only perform additional exploration if:
196+
- Information here is incomplete for your specific task
197+
- You encounter errors not covered in the troubleshooting section
198+
- Build commands fail unexpectedly
199+
200+
For any issues, check TROUBLESHOOTING.md first, then DEVELOPMENT.md for additional context.
201+
1202
# Code Review
2203
Always add hello wording "Hi, this is the review comment" for the review result message

0 commit comments

Comments
 (0)