Raise completion errors

Author: vinistock

ext/rubydex/graph.c

@@ -490,8 +490,15 @@ static VALUE rdxr_graph_diagnostics(VALUE self) {
     return diagnostics;
 }
 
-// Helper: convert a CompletionCandidateArray into a Ruby array of typed objects and free the C array.
-static VALUE completion_candidates_to_ruby_array(CompletionCandidateArray *array, VALUE graph_obj) {
+// Helper: convert a CompletionResult into a Ruby array, raising ArgumentError on error.
+static VALUE completion_result_to_ruby_array(struct CompletionResult result, VALUE graph_obj) {
+    if (result.error != NULL) {
+        VALUE msg = rb_utf8_str_new_cstr(result.error);
+        free_c_string(result.error);
+        rb_raise(rb_eArgError, "%s", StringValueCStr(msg));
+    }
+
+    CompletionCandidateArray *array = result.candidates;
     if (array == NULL) {
         return rb_ary_new();
     }
@@ -501,7 +508,7 @@ static VALUE completion_candidates_to_ruby_array(CompletionCandidateArray *array
         return rb_ary_new();
     }
 
-    VALUE result = rb_ary_new_capa((long)array->len);
+    VALUE ruby_array = rb_ary_new_capa((long)array->len);
 
     for (size_t i = 0; i < array->len; i++) {
         CCompletionCandidate item = array->items[i];
@@ -532,11 +539,11 @@ static VALUE completion_candidates_to_ruby_array(CompletionCandidateArray *array
             rb_raise(rb_eRuntimeError, "Unknown CCompletionCandidateKind: %d", item.kind);
         }
 
-        rb_ary_push(result, obj);
+        rb_ary_push(ruby_array, obj);
     }
 
     rdx_completion_candidates_free(array);
-    return result;
+    return ruby_array;
 }
 
 // Graph#complete_expression: (Array[String] nesting) -> Array[Declaration | Keyword]
@@ -551,11 +558,11 @@ static VALUE rdxr_graph_complete_expression(VALUE self, VALUE nesting) {
     size_t nesting_count = RARRAY_LEN(nesting);
     char **converted_nesting = rdxi_str_array_to_char(nesting, nesting_count);
 
-    CompletionCandidateArray *results =
+    struct CompletionResult result =
         rdx_graph_complete_expression(graph, (const char *const *)converted_nesting, nesting_count);
 
     rdxi_free_str_array(converted_nesting, nesting_count);
-    return completion_candidates_to_ruby_array(results, self);
+    return completion_result_to_ruby_array(result, self);
 }
 
 // Graph#complete_namespace_access: (String name) -> Array[Declaration]
@@ -566,8 +573,8 @@ static VALUE rdxr_graph_complete_namespace_access(VALUE self, VALUE name) {
     void *graph;
     TypedData_Get_Struct(self, void *, &graph_type, graph);
 
-    CompletionCandidateArray *results = rdx_graph_complete_namespace_access(graph, StringValueCStr(name));
-    return completion_candidates_to_ruby_array(results, self);
+    struct CompletionResult result = rdx_graph_complete_namespace_access(graph, StringValueCStr(name));
+    return completion_result_to_ruby_array(result, self);
 }
 
 // Graph#complete_method_call: (String name) -> Array[Declaration]
@@ -578,8 +585,8 @@ static VALUE rdxr_graph_complete_method_call(VALUE self, VALUE name) {
     void *graph;
     TypedData_Get_Struct(self, void *, &graph_type, graph);
 
-    CompletionCandidateArray *results = rdx_graph_complete_method_call(graph, StringValueCStr(name));
-    return completion_candidates_to_ruby_array(results, self);
+    struct CompletionResult result = rdx_graph_complete_method_call(graph, StringValueCStr(name));
+    return completion_result_to_ruby_array(result, self);
 }
 
 // Graph#complete_method_argument: (String name, Array[String] nesting) -> Array[Declaration | Keyword | KeywordParameter]
@@ -594,11 +601,11 @@ static VALUE rdxr_graph_complete_method_argument(VALUE self, VALUE name, VALUE n
     size_t nesting_count = RARRAY_LEN(nesting);
     char **converted_nesting = rdxi_str_array_to_char(nesting, nesting_count);
 
-    CompletionCandidateArray *results = rdx_graph_complete_method_argument(
+    struct CompletionResult result = rdx_graph_complete_method_argument(
         graph, StringValueCStr(name), (const char *const *)converted_nesting, nesting_count);
 
     rdxi_free_str_array(converted_nesting, nesting_count);
-    return completion_candidates_to_ruby_array(results, self);
+    return completion_result_to_ruby_array(result, self);
 }
 
 void rdxi_initialize_graph(VALUE moduleRubydex) {

rbi/rubydex.rbi

@@ -248,17 +248,17 @@ class Rubydex::Graph
   #
   # The nesting array represents the lexical scope stack, where the last element is the self type. An empty array
   # defaults to `Object` as the self type (top-level context).
-  sig { params(nesting: T::Array[String]).returns(T::Array[T.any(Rubydex::Declaration, Rubydex::Keyword, Rubydex::KeywordParameter)]) }
+  sig { params(nesting: T::Array[String]).returns(T::Array[T.any(Rubydex::Declaration, Rubydex::Keyword)]) }
   def complete_expression(nesting); end
 
   # Returns completion candidates after a namespace access operator (e.g., `Foo::`). This includes all constants and
   # singleton methods for the namespace and its ancestors.
-  sig { params(name: String).returns(T::Array[T.any(Rubydex::Declaration, Rubydex::Keyword, Rubydex::KeywordParameter)]) }
+  sig { params(name: String).returns(T::Array[Rubydex::Declaration]) }
   def complete_namespace_access(name); end
 
   # Returns completion candidates after a method call operator (e.g., `foo.`). This includes all methods that exist on
   # the type of the receiver and its ancestors.
-  sig { params(name: String).returns(T::Array[T.any(Rubydex::Declaration, Rubydex::Keyword, Rubydex::KeywordParameter)]) }
+  sig { params(name: String).returns(T::Array[Rubydex::Method]) }
   def complete_method_call(name); end
 
   # Returns completion candidates inside a method call's argument list (e.g., `foo.bar(|)`). This includes everything

rust/rubydex-sys/src/graph_api.rs

@@ -715,60 +715,104 @@ unsafe fn completion_nesting_name_id(
     Ok(name_api::nesting_stack_to_name_id(graph, &self_name, nesting))
 }
 
-/// Runs completion for the given receiver and returns a structured array of candidates
+/// The result of a completion operation, carrying either a candidate array or an error message.
+#[repr(C)]
+pub struct CompletionResult {
+    /// Non-null on success; null on error.
+    pub candidates: *mut CompletionCandidateArray,
+    /// Non-null on error; null on success. Caller must free with `free_c_string`.
+    pub error: *const c_char,
+}
+
+impl CompletionResult {
+    fn success(candidates: *mut CompletionCandidateArray) -> Self {
+        Self {
+            candidates,
+            error: ptr::null(),
+        }
+    }
+
+    fn error(message: &str) -> Self {
+        Self {
+            candidates: ptr::null_mut(),
+            error: CString::new(message)
+                .map(|s| s.into_raw().cast_const())
+                .unwrap_or(ptr::null()),
+        }
+    }
+}
+
+/// Runs completion for the given receiver and returns a structured result with candidates or an error message
 fn run_and_finalize_completion(
     graph: &mut Graph,
     receiver: CompletionReceiver,
     names_to_untrack: Vec<NameId>,
-) -> *mut CompletionCandidateArray {
-    let Ok(candidates) = query::completion_candidates(graph, CompletionContext::new(receiver)) else {
-        for name_id in names_to_untrack {
-            graph.untrack_name(name_id);
+) -> CompletionResult {
+    let candidates = match query::completion_candidates(graph, CompletionContext::new(receiver)) {
+        Ok(candidates) => candidates,
+        Err(e) => {
+            for name_id in names_to_untrack {
+                graph.untrack_name(name_id);
+            }
+            return CompletionResult::error(&e.to_string());
         }
-        return ptr::null_mut();
     };
 
     let entries: Vec<CCompletionCandidate> = candidates
         .into_iter()
-        .filter_map(|candidate| {
-            Some(match candidate {
-                CompletionCandidate::Declaration(id) => {
-                    let decl = graph.declarations().get(&id)?;
-                    CCompletionCandidate {
-                        kind: CCompletionCandidateKind::Declaration,
-                        declaration: Box::into_raw(Box::new(CDeclaration::from_declaration(id, decl))),
-                        name: ptr::null(),
-                        documentation: ptr::null(),
-                    }
+        .map(|candidate| match candidate {
+            CompletionCandidate::Declaration(id) => {
+                let decl = graph
+                    .declarations()
+                    .get(&id)
+                    .expect("completion candidate declaration must exist in graph");
+                CCompletionCandidate {
+                    kind: CCompletionCandidateKind::Declaration,
+                    declaration: Box::into_raw(Box::new(CDeclaration::from_declaration(id, decl))),
+                    name: ptr::null(),
+                    documentation: ptr::null(),
                 }
-                CompletionCandidate::Keyword(kw) => CCompletionCandidate {
-                    kind: CCompletionCandidateKind::Keyword,
+            }
+            CompletionCandidate::Keyword(kw) => CCompletionCandidate {
+                kind: CCompletionCandidateKind::Keyword,
+                declaration: ptr::null(),
+                name: CString::new(kw.name())
+                    .expect("keyword name must not contain NUL")
+                    .into_raw()
+                    .cast_const(),
+                documentation: CString::new(kw.documentation())
+                    .expect("keyword documentation must not contain NUL")
+                    .into_raw()
+                    .cast_const(),
+            },
+            CompletionCandidate::KeywordArgument(str_id) => {
+                let name_str = graph
+                    .strings()
+                    .get(&str_id)
+                    .expect("keyword argument string must exist in graph");
+                CCompletionCandidate {
+                    kind: CCompletionCandidateKind::KeywordParameter,
                     declaration: ptr::null(),
-                    name: CString::new(kw.name()).ok()?.into_raw().cast_const(),
-                    documentation: CString::new(kw.documentation()).ok()?.into_raw().cast_const(),
-                },
-                CompletionCandidate::KeywordArgument(str_id) => {
-                    let name_str = graph.strings().get(&str_id)?;
-                    CCompletionCandidate {
-                        kind: CCompletionCandidateKind::KeywordParameter,
-                        declaration: ptr::null(),
-                        name: CString::new(name_str.as_str()).ok()?.into_raw().cast_const(),
-                        documentation: ptr::null(),
-                    }
+                    name: CString::new(name_str.as_str())
+                        .expect("keyword argument name must not contain NUL")
+                        .into_raw()
+                        .cast_const(),
+                    documentation: ptr::null(),
                 }
-            })
+            }
         })
         .collect();
 
     for name_id in names_to_untrack {
         graph.untrack_name(name_id);
     }
 
-    CompletionCandidateArray::from_vec(entries)
+    CompletionResult::success(CompletionCandidateArray::from_vec(entries))
 }
 
 /// Returns expression completion candidates.
-/// The caller must free the result with `rdx_completion_candidates_free`.
+/// The caller must free candidates with `rdx_completion_candidates_free`
+/// and the error string (if non-null) with `free_c_string`.
 ///
 /// # Safety
 ///
@@ -779,19 +823,20 @@ pub unsafe extern "C" fn rdx_graph_complete_expression(
     pointer: GraphPointer,
     nesting: *const *const c_char,
     nesting_count: usize,
-) -> *mut CompletionCandidateArray {
+) -> CompletionResult {
     with_mut_graph(pointer, |graph| {
         let Ok((name_id, names_to_untrack)) = (unsafe { completion_nesting_name_id(graph, nesting, nesting_count) })
         else {
-            return ptr::null_mut();
+            return CompletionResult::success(ptr::null_mut());
         };
 
         run_and_finalize_completion(graph, CompletionReceiver::Expression(name_id), names_to_untrack)
     })
 }
 
 /// Returns namespace access completion candidates.
-/// The caller must free the result with `rdx_completion_candidates_free`.
+/// The caller must free candidates with `rdx_completion_candidates_free`
+/// and the error string (if non-null) with `free_c_string`.
 ///
 /// # Safety
 ///
@@ -801,9 +846,9 @@ pub unsafe extern "C" fn rdx_graph_complete_expression(
 pub unsafe extern "C" fn rdx_graph_complete_namespace_access(
     pointer: GraphPointer,
     name: *const c_char,
-) -> *mut CompletionCandidateArray {
+) -> CompletionResult {
     let Ok(name_str) = (unsafe { utils::convert_char_ptr_to_string(name) }) else {
-        return ptr::null_mut();
+        return CompletionResult::success(ptr::null_mut());
     };
 
     with_mut_graph(pointer, |graph| {
@@ -816,7 +861,8 @@ pub unsafe extern "C" fn rdx_graph_complete_namespace_access(
 }
 
 /// Returns method call completion candidates.
-/// The caller must free the result with `rdx_completion_candidates_free`.
+/// The caller must free candidates with `rdx_completion_candidates_free`
+/// and the error string (if non-null) with `free_c_string`.
 ///
 /// # Safety
 ///
@@ -826,9 +872,9 @@ pub unsafe extern "C" fn rdx_graph_complete_namespace_access(
 pub unsafe extern "C" fn rdx_graph_complete_method_call(
     pointer: GraphPointer,
     name: *const c_char,
-) -> *mut CompletionCandidateArray {
+) -> CompletionResult {
     let Ok(name_str) = (unsafe { utils::convert_char_ptr_to_string(name) }) else {
-        return ptr::null_mut();
+        return CompletionResult::success(ptr::null_mut());
     };
 
     with_mut_graph(pointer, |graph| {
@@ -841,7 +887,8 @@ pub unsafe extern "C" fn rdx_graph_complete_method_call(
 }
 
 /// Returns method argument completion candidates.
-/// The caller must free the result with `rdx_completion_candidates_free`.
+/// The caller must free candidates with `rdx_completion_candidates_free`
+/// and the error string (if non-null) with `free_c_string`.
 ///
 /// # Safety
 ///
@@ -854,16 +901,16 @@ pub unsafe extern "C" fn rdx_graph_complete_method_argument(
     name: *const c_char,
     nesting: *const *const c_char,
     nesting_count: usize,
-) -> *mut CompletionCandidateArray {
+) -> CompletionResult {
     let Ok(name_str) = (unsafe { utils::convert_char_ptr_to_string(name) }) else {
-        return ptr::null_mut();
+        return CompletionResult::success(ptr::null_mut());
     };
 
     with_mut_graph(pointer, |graph| {
         let Ok((self_name_id, names_to_untrack)) =
             (unsafe { completion_nesting_name_id(graph, nesting, nesting_count) })
         else {
-            return ptr::null_mut();
+            return CompletionResult::success(ptr::null_mut());
         };
 
         run_and_finalize_completion(