1//! The Zed Rust Extension API allows you write extensions for [Zed](https://zed.dev/) in Rust.
2
3pub mod http_client;
4pub mod process;
5pub mod settings;
6
7use core::fmt;
8
9use wit::*;
10
11pub use serde_json;
12
13// WIT re-exports.
14//
15// We explicitly enumerate the symbols we want to re-export, as there are some
16// that we may want to shadow to provide a cleaner Rust API.
17pub use wit::{
18 CodeLabel, CodeLabelSpan, CodeLabelSpanLiteral, Command, DownloadedFileType, EnvVars,
19 KeyValueStore, LanguageServerInstallationStatus, Project, Range, Worktree, download_file,
20 make_file_executable,
21 zed::extension::context_server::ContextServerConfiguration,
22 zed::extension::github::{
23 GithubRelease, GithubReleaseAsset, GithubReleaseOptions, github_release_by_tag_name,
24 latest_github_release,
25 },
26 zed::extension::nodejs::{
27 node_binary_path, npm_install_package, npm_package_installed_version,
28 npm_package_latest_version,
29 },
30 zed::extension::platform::{Architecture, Os, current_platform},
31 zed::extension::slash_command::{
32 SlashCommand, SlashCommandArgumentCompletion, SlashCommandOutput, SlashCommandOutputSection,
33 },
34};
35
36// Undocumented WIT re-exports.
37//
38// These are symbols that need to be public for the purposes of implementing
39// the extension host, but aren't relevant to extension authors.
40#[doc(hidden)]
41pub use wit::Guest;
42
43/// Constructs for interacting with language servers over the
44/// Language Server Protocol (LSP).
45pub mod lsp {
46 pub use crate::wit::zed::extension::lsp::{
47 Completion, CompletionKind, InsertTextFormat, Symbol, SymbolKind,
48 };
49}
50
51/// A result returned from a Zed extension.
52pub type Result<T, E = String> = core::result::Result<T, E>;
53
54/// Updates the installation status for the given language server.
55pub fn set_language_server_installation_status(
56 language_server_id: &LanguageServerId,
57 status: &LanguageServerInstallationStatus,
58) {
59 wit::set_language_server_installation_status(&language_server_id.0, status)
60}
61
62/// A Zed extension.
63pub trait Extension: Send + Sync {
64 /// Returns a new instance of the extension.
65 fn new() -> Self
66 where
67 Self: Sized;
68
69 /// Returns the command used to start the language server for the specified
70 /// language.
71 fn language_server_command(
72 &mut self,
73 _language_server_id: &LanguageServerId,
74 _worktree: &Worktree,
75 ) -> Result<Command> {
76 Err("`language_server_command` not implemented".to_string())
77 }
78
79 /// Returns the initialization options to pass to the specified language server.
80 fn language_server_initialization_options(
81 &mut self,
82 _language_server_id: &LanguageServerId,
83 _worktree: &Worktree,
84 ) -> Result<Option<serde_json::Value>> {
85 Ok(None)
86 }
87
88 /// Returns the workspace configuration options to pass to the language server.
89 fn language_server_workspace_configuration(
90 &mut self,
91 _language_server_id: &LanguageServerId,
92 _worktree: &Worktree,
93 ) -> Result<Option<serde_json::Value>> {
94 Ok(None)
95 }
96
97 /// Returns the initialization options to pass to the other language server.
98 fn language_server_additional_initialization_options(
99 &mut self,
100 _language_server_id: &LanguageServerId,
101 _target_language_server_id: &LanguageServerId,
102 _worktree: &Worktree,
103 ) -> Result<Option<serde_json::Value>> {
104 Ok(None)
105 }
106
107 /// Returns the workspace configuration options to pass to the other language server.
108 fn language_server_additional_workspace_configuration(
109 &mut self,
110 _language_server_id: &LanguageServerId,
111 _target_language_server_id: &LanguageServerId,
112 _worktree: &Worktree,
113 ) -> Result<Option<serde_json::Value>> {
114 Ok(None)
115 }
116
117 /// Returns the label for the given completion.
118 fn label_for_completion(
119 &self,
120 _language_server_id: &LanguageServerId,
121 _completion: Completion,
122 ) -> Option<CodeLabel> {
123 None
124 }
125
126 /// Returns the label for the given symbol.
127 fn label_for_symbol(
128 &self,
129 _language_server_id: &LanguageServerId,
130 _symbol: Symbol,
131 ) -> Option<CodeLabel> {
132 None
133 }
134
135 /// Returns the completions that should be shown when completing the provided slash command with the given query.
136 fn complete_slash_command_argument(
137 &self,
138 _command: SlashCommand,
139 _args: Vec<String>,
140 ) -> Result<Vec<SlashCommandArgumentCompletion>, String> {
141 Ok(Vec::new())
142 }
143
144 /// Returns the output from running the provided slash command.
145 fn run_slash_command(
146 &self,
147 _command: SlashCommand,
148 _args: Vec<String>,
149 _worktree: Option<&Worktree>,
150 ) -> Result<SlashCommandOutput, String> {
151 Err("`run_slash_command` not implemented".to_string())
152 }
153
154 /// Returns the command used to start a context server.
155 fn context_server_command(
156 &mut self,
157 _context_server_id: &ContextServerId,
158 _project: &Project,
159 ) -> Result<Command> {
160 Err("`context_server_command` not implemented".to_string())
161 }
162
163 /// Returns the configuration options for the specified context server.
164 fn context_server_configuration(
165 &mut self,
166 _context_server_id: &ContextServerId,
167 _project: &Project,
168 ) -> Result<Option<ContextServerConfiguration>> {
169 Ok(None)
170 }
171
172 /// Returns a list of package names as suggestions to be included in the
173 /// search results of the `/docs` slash command.
174 ///
175 /// This can be used to provide completions for known packages (e.g., from the
176 /// local project or a registry) before a package has been indexed.
177 fn suggest_docs_packages(&self, _provider: String) -> Result<Vec<String>, String> {
178 Ok(Vec::new())
179 }
180
181 /// Indexes the docs for the specified package.
182 fn index_docs(
183 &self,
184 _provider: String,
185 _package: String,
186 _database: &KeyValueStore,
187 ) -> Result<(), String> {
188 Err("`index_docs` not implemented".to_string())
189 }
190}
191
192/// Registers the provided type as a Zed extension.
193///
194/// The type must implement the [`Extension`] trait.
195#[macro_export]
196macro_rules! register_extension {
197 ($extension_type:ty) => {
198 #[unsafe(export_name = "init-extension")]
199 pub extern "C" fn __init_extension() {
200 std::env::set_current_dir(std::env::var("PWD").unwrap()).unwrap();
201 zed_extension_api::register_extension(|| {
202 Box::new(<$extension_type as zed_extension_api::Extension>::new())
203 });
204 }
205 };
206}
207
208#[doc(hidden)]
209pub fn register_extension(build_extension: fn() -> Box<dyn Extension>) {
210 unsafe { EXTENSION = Some((build_extension)()) }
211}
212
213fn extension() -> &'static mut dyn Extension {
214 #[expect(static_mut_refs)]
215 unsafe {
216 EXTENSION.as_deref_mut().unwrap()
217 }
218}
219
220static mut EXTENSION: Option<Box<dyn Extension>> = None;
221
222#[cfg(target_arch = "wasm32")]
223#[unsafe(link_section = "zed:api-version")]
224#[doc(hidden)]
225pub static ZED_API_VERSION: [u8; 6] = *include_bytes!(concat!(env!("OUT_DIR"), "/version_bytes"));
226
227mod wit {
228
229 wit_bindgen::generate!({
230 skip: ["init-extension"],
231 path: "./wit/since_v0.5.0",
232 });
233}
234
235wit::export!(Component);
236
237struct Component;
238
239impl wit::Guest for Component {
240 fn language_server_command(
241 language_server_id: String,
242 worktree: &wit::Worktree,
243 ) -> Result<wit::Command> {
244 let language_server_id = LanguageServerId(language_server_id);
245 extension().language_server_command(&language_server_id, worktree)
246 }
247
248 fn language_server_initialization_options(
249 language_server_id: String,
250 worktree: &Worktree,
251 ) -> Result<Option<String>, String> {
252 let language_server_id = LanguageServerId(language_server_id);
253 Ok(extension()
254 .language_server_initialization_options(&language_server_id, worktree)?
255 .and_then(|value| serde_json::to_string(&value).ok()))
256 }
257
258 fn language_server_workspace_configuration(
259 language_server_id: String,
260 worktree: &Worktree,
261 ) -> Result<Option<String>, String> {
262 let language_server_id = LanguageServerId(language_server_id);
263 Ok(extension()
264 .language_server_workspace_configuration(&language_server_id, worktree)?
265 .and_then(|value| serde_json::to_string(&value).ok()))
266 }
267
268 fn language_server_additional_initialization_options(
269 language_server_id: String,
270 target_language_server_id: String,
271 worktree: &Worktree,
272 ) -> Result<Option<String>, String> {
273 let language_server_id = LanguageServerId(language_server_id);
274 let target_language_server_id = LanguageServerId(target_language_server_id);
275 Ok(extension()
276 .language_server_additional_initialization_options(
277 &language_server_id,
278 &target_language_server_id,
279 worktree,
280 )?
281 .and_then(|value| serde_json::to_string(&value).ok()))
282 }
283
284 fn language_server_additional_workspace_configuration(
285 language_server_id: String,
286 target_language_server_id: String,
287 worktree: &Worktree,
288 ) -> Result<Option<String>, String> {
289 let language_server_id = LanguageServerId(language_server_id);
290 let target_language_server_id = LanguageServerId(target_language_server_id);
291 Ok(extension()
292 .language_server_additional_workspace_configuration(
293 &language_server_id,
294 &target_language_server_id,
295 worktree,
296 )?
297 .and_then(|value| serde_json::to_string(&value).ok()))
298 }
299
300 fn labels_for_completions(
301 language_server_id: String,
302 completions: Vec<Completion>,
303 ) -> Result<Vec<Option<CodeLabel>>, String> {
304 let language_server_id = LanguageServerId(language_server_id);
305 let mut labels = Vec::new();
306 for (ix, completion) in completions.into_iter().enumerate() {
307 let label = extension().label_for_completion(&language_server_id, completion);
308 if let Some(label) = label {
309 labels.resize(ix + 1, None);
310 *labels.last_mut().unwrap() = Some(label);
311 }
312 }
313 Ok(labels)
314 }
315
316 fn labels_for_symbols(
317 language_server_id: String,
318 symbols: Vec<Symbol>,
319 ) -> Result<Vec<Option<CodeLabel>>, String> {
320 let language_server_id = LanguageServerId(language_server_id);
321 let mut labels = Vec::new();
322 for (ix, symbol) in symbols.into_iter().enumerate() {
323 let label = extension().label_for_symbol(&language_server_id, symbol);
324 if let Some(label) = label {
325 labels.resize(ix + 1, None);
326 *labels.last_mut().unwrap() = Some(label);
327 }
328 }
329 Ok(labels)
330 }
331
332 fn complete_slash_command_argument(
333 command: SlashCommand,
334 args: Vec<String>,
335 ) -> Result<Vec<SlashCommandArgumentCompletion>, String> {
336 extension().complete_slash_command_argument(command, args)
337 }
338
339 fn run_slash_command(
340 command: SlashCommand,
341 args: Vec<String>,
342 worktree: Option<&Worktree>,
343 ) -> Result<SlashCommandOutput, String> {
344 extension().run_slash_command(command, args, worktree)
345 }
346
347 fn context_server_command(
348 context_server_id: String,
349 project: &Project,
350 ) -> Result<wit::Command> {
351 let context_server_id = ContextServerId(context_server_id);
352 extension().context_server_command(&context_server_id, project)
353 }
354
355 fn context_server_configuration(
356 context_server_id: String,
357 project: &Project,
358 ) -> Result<Option<ContextServerConfiguration>, String> {
359 let context_server_id = ContextServerId(context_server_id);
360 extension().context_server_configuration(&context_server_id, project)
361 }
362
363 fn suggest_docs_packages(provider: String) -> Result<Vec<String>, String> {
364 extension().suggest_docs_packages(provider)
365 }
366
367 fn index_docs(
368 provider: String,
369 package: String,
370 database: &KeyValueStore,
371 ) -> Result<(), String> {
372 extension().index_docs(provider, package, database)
373 }
374}
375
376/// The ID of a language server.
377#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone)]
378pub struct LanguageServerId(String);
379
380impl AsRef<str> for LanguageServerId {
381 fn as_ref(&self) -> &str {
382 &self.0
383 }
384}
385
386impl fmt::Display for LanguageServerId {
387 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
388 write!(f, "{}", self.0)
389 }
390}
391
392/// The ID of a context server.
393#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone)]
394pub struct ContextServerId(String);
395
396impl AsRef<str> for ContextServerId {
397 fn as_ref(&self) -> &str {
398 &self.0
399 }
400}
401
402impl fmt::Display for ContextServerId {
403 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
404 write!(f, "{}", self.0)
405 }
406}
407
408impl CodeLabelSpan {
409 /// Returns a [`CodeLabelSpan::CodeRange`].
410 pub fn code_range(range: impl Into<wit::Range>) -> Self {
411 Self::CodeRange(range.into())
412 }
413
414 /// Returns a [`CodeLabelSpan::Literal`].
415 pub fn literal(text: impl Into<String>, highlight_name: Option<String>) -> Self {
416 Self::Literal(CodeLabelSpanLiteral {
417 text: text.into(),
418 highlight_name,
419 })
420 }
421}
422
423impl From<std::ops::Range<u32>> for wit::Range {
424 fn from(value: std::ops::Range<u32>) -> Self {
425 Self {
426 start: value.start,
427 end: value.end,
428 }
429 }
430}
431
432impl From<std::ops::Range<usize>> for wit::Range {
433 fn from(value: std::ops::Range<usize>) -> Self {
434 Self {
435 start: value.start as u32,
436 end: value.end as u32,
437 }
438 }
439}