docs: document the code completion pipeline#867
Closed
chronicgiardia wants to merge 1 commit into
Closed
Conversation
Adds Docs/CompletionPipeline.md covering the full end-to-end flow: - Trigger modes (on-demand vs realtime/prefetch) - All five layers: EditorExtension → XPC → ExtensionService → SuggestionService middleware chain → LSP client (GitHubCopilotService) - XPC protocol methods table - LSP JSON-RPC request types and server notifications - SuggestionInjector buffer modification semantics - Accept/reject cycle with telemetry - Key source file index Co-Authored-By: Oz <oz-agent@warp.dev>
Contributor
|
At the moment we are not accepting contributions to the repository. Feedback for GitHub Copilot for Xcode can be given in the Copilot community discussions. |
There was a problem hiding this comment.
Pull request overview
Adds a new developer reference document (Docs/CompletionPipeline.md) describing how inline code completions flow through the Copilot for Xcode architecture (editor extension → XPC relay → service app → LSP client → language server → cloud), including trigger modes, per-layer responsibilities, and key source file pointers.
Changes:
- Introduces a comprehensive completion pipeline overview with an end-to-end diagram and trigger mode descriptions.
- Documents XPC and LSP boundaries, including the protocol surface area and notification/request types.
- Adds a “key source files” index mapping major components to their role in the pipeline.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ### Realtime (prefetch) | ||
|
|
||
| `RealtimeSuggestionController` (in `Core/Sources/Service/`) watches for editor changes via the AX API (`XcodeInspector`) and calls `prefetchRealtimeSuggestions` on every keystroke after a debounce delay. The prefetched suggestion is cached in the filespace so it can be displayed immediately when the user pauses. |
|
|
||
| ### Protocol | ||
|
|
||
| `XPCServiceProtocol` is the `@objc` protocol that defines the raw XPC interface. All parameters are `Data` (JSON-encoded payloads) to satisfy the XPC serialisation requirement. |
Comment on lines
+125
to
+129
| 1. **Decode** `Data` → `EditorContent`. | ||
| 2. **Locate workspace** — uses `XcodeInspector` (AX API) to find the open workspace and the active file URL. | ||
| 3. **Delegate to `WorkspaceSuggestionService`** — which manages per-filespace suggestion state (current index, suggestion list, snapshot for invalidation checks). | ||
| 4. **Inject into filespace** — `SuggestionInjector` computes the line modifications. | ||
| 5. **Encode** `UpdatedContent` → `Data` and reply. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
Docs/CompletionPipeline.md— a developer reference document covering the full end-to-end flow for GitHub Copilot inline code completions.What's documented
Pipeline overview — ASCII diagram of all five layers:
EditorExtension → CommunicationBridge → ExtensionService → SuggestionService → LSP client → copilot-language-server → GitHub APITrigger modes
GetSuggestionsCommand) — whycompletionHandler(nil)must fire before the async workRealtimeSuggestionController) — keystroke-driven cachingLayer-by-layer breakdown
EditorContentpackagingXPCServiceProtocolmethod table (9 completion methods),CommunicationBridgerelay rationalePostProcessingSuggestionServiceMiddlewarefilter rulesGitHubCopilotService, JSON-RPC request types, server notification table, document sync callbacks and the-32602reopen workaroundSuggestion injection — multi-byte/emoji handling,
[Modification]semanticsAccept/reject cycle — full flow including telemetry back to the LSP server
Key source file index — 13 files mapped to layer and role
Motivation
The completion pipeline spans five processes, two XPC hops, and a stdio LSP subprocess. Understanding how a keypress becomes a displayed suggestion (and why certain architectural choices exist, like the early
completionHandler(nil)) currently requires reading across a dozen files. This document consolidates that knowledge in one place.