Add infrastructure for Code Actions 💡, and our first action for generating a roxygen template (#809)

* Add `point_and_byte_from_cursor()` utility

* Add `is_binary_operator_of_kind()` utility

* Extract out `convert_lsp_range_to_tree_sitter_range()` utility

* Add code action infrastructure, and "Generate a roxygen template" code action

* Reference the light bulb blog post

* Rename `byte` to `offset`

* Use `lsp_types::` prefix

* Don't provide the code action for local functions

* Use `lsp_types::` in `roxygen.rs` too

Author: DavisVaughan

crates/ark/src/fixtures/utils.rs

@@ -37,12 +37,19 @@ pub(crate) fn r_test_init() {
 }
 
 pub fn point_from_cursor(x: &str) -> (String, Point) {
+    let (text, point, _offset) = point_and_offset_from_cursor(x);
+    (text, point)
+}
+
+pub fn point_and_offset_from_cursor(x: &str) -> (String, Point, usize) {
     let lines = x.split("\n").collect::<Vec<&str>>();
 
     // i.e. looking for `@` in something like `fn(x = @1, y = 2)`, and it treats the
     // `@` as the cursor position
     let cursor = b'@';
 
+    let mut offset = 0;
+
     for (line_row, line) in lines.into_iter().enumerate() {
         for (char_column, char) in line.as_bytes().into_iter().enumerate() {
             if char == &cursor {
@@ -51,9 +58,12 @@ pub fn point_from_cursor(x: &str) -> (String, Point) {
                     row: line_row,
                     column: char_column,
                 };
-                return (x, point);
+                offset += char_column;
+                return (x, point, offset);
             }
         }
+        // `+ 1` for the removed `\n` at the end of this line
+        offset += line.as_bytes().len() + 1;
     }
 
     panic!("`x` must include a `@` character!");
@@ -107,14 +117,15 @@ pub fn package_is_installed(package: &str) -> bool {
 mod tests {
     use tree_sitter::Point;
 
-    use crate::fixtures::point_from_cursor;
+    use crate::fixtures::point_and_offset_from_cursor;
 
     #[test]
     #[rustfmt::skip]
-    fn test_point_from_cursor() {
-        let (text, point) = point_from_cursor("1@ + 2");
+    fn test_point_and_offset_from_cursor() {
+        let (text, point, offset) = point_and_offset_from_cursor("1@ + 2");
         assert_eq!(text, "1 + 2".to_string());
         assert_eq!(point, Point::new(0, 1));
+        assert_eq!(offset, 1);
 
         let text =
 "fn(
@@ -124,8 +135,9 @@ mod tests {
 "fn(
   arg = 3
 )";
-        let (text, point) = point_from_cursor(text);
+        let (text, point, offset) = point_and_offset_from_cursor(text);
         assert_eq!(text, expect);
         assert_eq!(point, Point::new(1, 7));
+        assert_eq!(offset, 11);
     }
 }

crates/ark/src/lsp/backend.rs

@@ -143,6 +143,7 @@ pub(crate) enum LspRequest {
     StatementRange(StatementRangeParams),
     HelpTopic(HelpTopicParams),
     OnTypeFormatting(DocumentOnTypeFormattingParams),
+    CodeAction(CodeActionParams),
     VirtualDocument(VirtualDocumentParams),
     InputBoundaries(InputBoundariesParams),
 }
@@ -164,6 +165,7 @@ pub(crate) enum LspResponse {
     StatementRange(Option<StatementRangeResponse>),
     HelpTopic(Option<HelpTopicResponse>),
     OnTypeFormatting(Option<Vec<TextEdit>>),
+    CodeAction(Option<CodeActionResponse>),
     VirtualDocument(VirtualDocumentResponse),
     InputBoundaries(InputBoundariesResponse),
 }
@@ -371,6 +373,14 @@ impl LanguageServer for Backend {
             LspResponse::OnTypeFormatting
         )
     }
+
+    async fn code_action(&self, params: CodeActionParams) -> Result<Option<CodeActionResponse>> {
+        cast_response!(
+            self,
+            self.request(LspRequest::CodeAction(params)).await,
+            LspResponse::CodeAction
+        )
+    }
 }
 
 // Custom methods for the backend.

crates/ark/src/lsp/capabilities.rs

@@ -0,0 +1,115 @@
+//
+// capabilities.rs
+//
+// Copyright (C) 2025 Posit Software, PBC. All rights reserved.
+//
+//
+
+use tower_lsp::lsp_types;
+use tower_lsp::lsp_types::CodeActionKind;
+use tower_lsp::lsp_types::CodeActionOptions;
+use tower_lsp::lsp_types::CodeActionProviderCapability;
+use tower_lsp::lsp_types::WorkDoneProgressOptions;
+
+/// Capabilities negotiated with [lsp_types::ClientCapabilities]
+#[derive(Debug)]
+pub(crate) struct Capabilities {
+    dynamic_registration_for_did_change_configuration: bool,
+    code_action_literal_support: bool,
+    workspace_edit_document_changes: bool,
+}
+
+impl Capabilities {
+    pub(crate) fn new(client_capabilities: lsp_types::ClientCapabilities) -> Self {
+        let dynamic_registration_for_did_change_configuration = client_capabilities
+            .workspace
+            .as_ref()
+            .and_then(|workspace| workspace.did_change_configuration)
+            .and_then(|did_change_configuration| did_change_configuration.dynamic_registration)
+            .unwrap_or(false);
+
+        // In theory the client also tells us which code action kinds it supports inside
+        // `code_action_literal_support`, but clients are guaranteed to ignore any they
+        // don't support, so we just return `true` if the field exists (same as
+        // rust-analyzer).
+        let code_action_literal_support = client_capabilities
+            .text_document
+            .as_ref()
+            .and_then(|text_document| text_document.code_action.as_ref())
+            .and_then(|code_action| code_action.code_action_literal_support.as_ref())
+            .map_or(false, |_| true);
+
+        let workspace_edit_document_changes = client_capabilities
+            .workspace
+            .as_ref()
+            .and_then(|workspace| workspace.workspace_edit.as_ref())
+            .and_then(|workspace_edit| workspace_edit.document_changes)
+            .map_or(false, |document_changes| document_changes);
+
+        Self {
+            dynamic_registration_for_did_change_configuration,
+            code_action_literal_support,
+            workspace_edit_document_changes,
+        }
+    }
+
+    pub(crate) fn dynamic_registration_for_did_change_configuration(&self) -> bool {
+        self.dynamic_registration_for_did_change_configuration
+    }
+
+    pub(crate) fn code_action_literal_support(&self) -> bool {
+        self.code_action_literal_support
+    }
+
+    // Currently only used for testing
+    #[cfg(test)]
+    pub(crate) fn with_code_action_literal_support(
+        mut self,
+        code_action_literal_support: bool,
+    ) -> Self {
+        self.code_action_literal_support = code_action_literal_support;
+        return self;
+    }
+
+    pub(crate) fn workspace_edit_document_changes(&self) -> bool {
+        self.workspace_edit_document_changes
+    }
+
+    // Currently only used for testing
+    #[cfg(test)]
+    pub(crate) fn with_workspace_edit_document_changes(
+        mut self,
+        workspace_edit_document_changes: bool,
+    ) -> Self {
+        self.workspace_edit_document_changes = workspace_edit_document_changes;
+        return self;
+    }
+
+    pub(crate) fn code_action_provider_capability(&self) -> Option<CodeActionProviderCapability> {
+        if !self.code_action_literal_support() {
+            return None;
+        }
+
+        // Currently we only support documentation generating code actions, which don't
+        // map to an existing kind. rust-analyzer maps them to `EMPTY`, so we follow suit.
+        // Currently no code actions require delayed resolution.
+        Some(CodeActionProviderCapability::Options(CodeActionOptions {
+            code_action_kinds: Some(vec![CodeActionKind::EMPTY]),
+            work_done_progress_options: WorkDoneProgressOptions::default(),
+            resolve_provider: Some(false),
+        }))
+    }
+}
+
+// This is unfortunately required right now, because `LspState` is initialized before we
+// get the `Initialize` LSP request. We immediately overwrite the `LspState`
+// `capabilities` field after receiving the `Initialize` request.
+impl Default for Capabilities {
+    fn default() -> Self {
+        Self {
+            dynamic_registration_for_did_change_configuration: false,
+            code_action_literal_support: false,
+            workspace_edit_document_changes: false,
+        }
+    }
+}

crates/ark/src/lsp/code_action.rs

@@ -0,0 +1,111 @@
+//! Code actions
+//!
+//! These are contextual light bulbs that appear when the user's cursor is at a particular
+//! position. They allow for small context specific quick fixes, refactors, documentation
+//! generation, and other small code adjustments.
+//!
+//! Modeled after rust-analyzer's blog post:
+//! https://rust-analyzer.github.io/blog/2020/09/28/how-to-make-a-light-bulb.html
+
+use std::collections::HashMap;
+
+use tower_lsp::lsp_types;
+use tree_sitter::Range;
+use url::Url;
+
+use crate::lsp::capabilities::Capabilities;
+use crate::lsp::code_action::roxygen::roxygen_documentation;
+use crate::lsp::documents::Document;
+
+mod roxygen;
+
+/// A small wrapper around [CodeActionResponse] that make a few things more ergonomic
+pub(crate) struct CodeActions {
+    response: lsp_types::CodeActionResponse,
+}
+
+pub(crate) fn code_actions(
+    uri: &Url,
+    document: &Document,
+    range: Range,
+    capabilities: &Capabilities,
+) -> lsp_types::CodeActionResponse {
+    let mut actions = CodeActions::new();
+
+    roxygen_documentation(&mut actions, uri, document, range, capabilities);
+
+    actions.into_response()
+}
+
+pub(crate) fn code_action(
+    title: String,
+    kind: lsp_types::CodeActionKind,
+    edit: lsp_types::WorkspaceEdit,
+) -> lsp_types::CodeAction {
+    lsp_types::CodeAction {
+        title,
+        kind: Some(kind),
+        edit: Some(edit),
+        diagnostics: None,
+        command: None,
+        is_preferred: None,
+        disabled: None,
+        data: None,
+    }
+}
+
+/// Creates a common kind of `WorkspaceEdit` composed of one or more `TextEdit`s to
+/// apply to a single document
+pub(crate) fn code_action_workspace_text_edit(
+    uri: Url,
+    version: Option<i32>,
+    edits: Vec<lsp_types::TextEdit>,
+    capabilities: &Capabilities,
+) -> lsp_types::WorkspaceEdit {
+    if capabilities.workspace_edit_document_changes() {
+        // Prefer the versioned `DocumentChanges` feature
+        let edit = lsp_types::TextDocumentEdit {
+            text_document: lsp_types::OptionalVersionedTextDocumentIdentifier { uri, version },
+            edits: edits
+                .into_iter()
+                .map(|edit| lsp_types::OneOf::Left(edit))
+                .collect(),
+        };
+
+        let document_changes = lsp_types::DocumentChanges::Edits(vec![edit]);
+
+        lsp_types::WorkspaceEdit {
+            changes: None,
+            document_changes: Some(document_changes),
+            change_annotations: None,
+        }
+    } else {
+        // Fall back to hash map of `TextEdit`s if the client doesn't support `DocumentChanges`
+        let mut changes = HashMap::new();
+        changes.insert(uri, edits);
+
+        lsp_types::WorkspaceEdit {
+            changes: Some(changes),
+            document_changes: None,
+            change_annotations: None,
+        }
+    }
+}
+
+impl CodeActions {
+    pub(crate) fn new() -> Self {
+        Self {
+            response: lsp_types::CodeActionResponse::new(),
+        }
+    }
+
+    pub(crate) fn add_action(&mut self, x: lsp_types::CodeAction) -> Option<()> {
+        self.response
+            .push(lsp_types::CodeActionOrCommand::CodeAction(x));
+        Some(())
+    }
+
+    pub(crate) fn into_response(self) -> lsp_types::CodeActionResponse {
+        self.response
+    }
+}