Expose Cypher via Rubydex::Graph and the rdx command CLI

Add FFI exports (rdx_graph_query and rdx_cypher_schema) in rubydex-sys,
bind them as the Graph#query instance method and the Graph.cypher_schema
class method, and add their Sorbet signatures. query accepts an optional
format (String or Symbol, default :table) and raises ArgumentError on
parse, execution, or format errors.

Restructure the exe/rdx executable around subcommands: `rdx query
<CYPHER>`, `rdx schema`, and `rdx console` (the interactive session),
each with a --format option where applicable. Cover the Ruby API with
tests for query output, schema output, format coercion, label
disjunction, and error handling.

Author: paracycle

exe/rdx

@@ -5,40 +5,100 @@ $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 
 require "optparse"
 
-options = {}
+USAGE = <<~TEXT
+  Usage: rdx <command> [options]
 
-OptionParser.new do |parser|
-  parser.on("--version", "Print the gem's version") do
-    require "rubydex/version"
-    puts "v#{Rubydex::VERSION}"
-    exit
-  end
+  Commands:
+    query <CYPHER>   Run a Cypher query against the workspace graph and print the result
+    schema           Describe the queryable Cypher schema (labels, relationships, properties)
+    console          Open an interactive session with a populated graph for the current workspace
+    help             Show this help message
 
-  parser.on("-h", "--help", "Prints this help") do
-    puts parser
-    exit
-  end
+  Run `rdx <command> --help` for command-specific options.
+TEXT
 
-  parser.on("-i", "--interactive", "Open an interactive session with a populated graph for the current workspace") do
-    options[:interactive] = true
-  end
-end.parse!
+def abort_with_usage(message)
+  warn(message)
+  warn("")
+  warn(USAGE)
+  exit(1)
+end
 
-require "rubydex"
+# Top-level --version / --help / bare invocation, handled before command dispatch.
+case ARGV.first
+when "--version", "version"
+  require "rubydex/version"
+  puts "v#{Rubydex::VERSION}"
+  exit
+when nil, "-h", "--help", "help"
+  puts USAGE
+  exit
+end
+
+command = ARGV.shift
 
-def __with_timer(message, &block)
-  print(message)
+def with_timer(io, message)
+  io.print(message)
   start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
-  block.call
+  yield
   duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond) - start
-  puts " finished in #{duration.round(2)}ms"
+  io.puts(" finished in #{duration.round(2)}ms")
+end
+
+# Builds the workspace graph, sending progress messages to `progress_io`.
+def build_graph(progress_io)
+  graph = Rubydex::Graph.new
+  with_timer(progress_io, "Indexing workspace...") { graph.index_workspace }
+  with_timer(progress_io, "Resolving graph...") { graph.resolve }
+  graph
 end
 
-graph = Rubydex::Graph.new
-__with_timer("Indexing workspace...") { graph.index_workspace }
-__with_timer("Resolving graph...") { graph.resolve }
+# Parses `--format`/`--help` for a command and returns the chosen format.
+def parse_format(usage)
+  format = "table"
+  OptionParser.new do |parser|
+    parser.banner = usage
+    parser.on("--format FORMAT", ["table", "json"], "Output format (table or json)") { |value| format = value }
+    parser.on("-h", "--help", "Show this help") do
+      puts parser
+      exit
+    end
+  end.parse!
+  format
+end
+
+case command
+when "query"
+  format = parse_format("Usage: rdx query <CYPHER> [options]")
+  query = ARGV.shift
+  abort_with_usage("`query` requires a Cypher query argument") if query.nil? || query.empty?
+
+  require "rubydex"
+  # Progress goes to stderr so stdout carries only the query result (e.g. for piping JSON).
+  graph = build_graph($stderr)
+  begin
+    print(graph.query(query, format))
+  rescue ArgumentError => e
+    abort(e.message)
+  end
+when "schema"
+  format = parse_format("Usage: rdx schema [options]")
+
+  require "rubydex"
+  # The schema is static, so describe it without indexing the workspace.
+  print(Rubydex::Graph.cypher_schema(format))
+when "console"
+  OptionParser.new do |parser|
+    parser.banner = "Usage: rdx console"
+    parser.on("-h", "--help", "Show this help") do
+      puts parser
+      exit
+    end
+  end.parse!
+
+  require "rubydex"
+  graph = build_graph($stdout)
 
-if options[:interactive]
   begin
     require "irb"
     IRB.setup(nil)
@@ -48,4 +108,6 @@ if options[:interactive]
   rescue LoadError
     abort("Interactive mode requires `irb` to be in the bundle")
   end
+else
+  abort_with_usage("unknown command: #{command}")
 end

ext/rubydex/graph.c

@@ -750,6 +750,68 @@ static VALUE rdxr_graph_keyword(VALUE self, VALUE name) {
     return rb_class_new_instance(2, argv, cKeyword);
 }
 
+// Graph#query: (String query, ?(String | Symbol) format) -> String
+// Runs a Cypher query against the graph and returns the formatted output.
+// `format` may be "table" (default) or "json". Raises ArgumentError on a parse, execution, or
+// format error.
+static VALUE rdxr_graph_query(int argc, VALUE *argv, VALUE self) {
+    VALUE query, format;
+    rb_scan_args(argc, argv, "11", &query, &format);
+    Check_Type(query, T_STRING);
+
+    const char *format_str = "table";
+    if (!NIL_P(format)) {
+        if (RB_TYPE_P(format, T_SYMBOL)) {
+            format = rb_sym2str(format);
+        }
+        Check_Type(format, T_STRING);
+        format_str = StringValueCStr(format);
+    }
+
+    void *graph;
+    TypedData_Get_Struct(self, void *, &graph_type, graph);
+
+    struct CQueryResult result = rdx_graph_query(graph, StringValueCStr(query), format_str);
+
+    if (result.error != NULL) {
+        VALUE message = rb_utf8_str_new_cstr(result.error);
+        free_c_string(result.error);
+        rb_raise(rb_eArgError, "%s", StringValueCStr(message));
+    }
+
+    VALUE output = result.output == NULL ? rb_utf8_str_new_cstr("") : rb_utf8_str_new_cstr(result.output);
+    if (result.output != NULL) {
+        free_c_string(result.output);
+    }
+
+    return output;
+}
+
+// Rubydex::Graph.cypher_schema(format = :table) -> String
+// Returns a description of the queryable Cypher schema. `format` may be "table" (default) or "json".
+// The schema is static, so this is a class method and does not require a graph instance.
+static VALUE rdxr_cypher_schema(int argc, VALUE *argv, VALUE self) {
+    VALUE format;
+    rb_scan_args(argc, argv, "01", &format);
+
+    const char *format_str = "table";
+    if (!NIL_P(format)) {
+        if (RB_TYPE_P(format, T_SYMBOL)) {
+            format = rb_sym2str(format);
+        }
+        Check_Type(format, T_STRING);
+        format_str = StringValueCStr(format);
+    }
+
+    const char *output = rdx_cypher_schema(format_str);
+    VALUE result = output == NULL ? rb_utf8_str_new_cstr("") : rb_utf8_str_new_cstr(output);
+    if (output != NULL) {
+        free_c_string(output);
+    }
+
+    return result;
+}
+
 void rdxi_initialize_graph(VALUE moduleRubydex) {
     mRubydex = moduleRubydex;
     cGraph = rb_define_class_under(mRubydex, "Graph", rb_cObject);
@@ -784,4 +846,7 @@ void rdxi_initialize_graph(VALUE moduleRubydex) {
     rb_define_method(cGraph, "exclude_paths", rdxr_graph_exclude_paths, 1);
     rb_define_method(cGraph, "excluded_paths", rdxr_graph_excluded_paths, 0);
     rb_define_method(cGraph, "keyword", rdxr_graph_keyword, 1);
+    rb_define_method(cGraph, "query", rdxr_graph_query, -1);
+
+    rb_define_singleton_method(cGraph, "cypher_schema", rdxr_cypher_schema, -1);
 }

rbi/rubydex.rbi

@@ -275,6 +275,11 @@ class Rubydex::IntegrityFailure < Rubydex::Failure; end
 class Rubydex::Graph
   IGNORED_DIRECTORIES = T.let(T.unsafe(nil), T::Array[String])
 
+  class << self
+    sig { params(format: T.any(String, Symbol)).returns(String) }
+    def cypher_schema(format = :table); end
+  end
+
   sig { params(workspace_path: T.nilable(String)).void }
   def initialize(workspace_path: nil); end
 
@@ -324,6 +329,9 @@ class Rubydex::Graph
   sig { params(require_path: String, load_paths: T::Array[String]).returns(T.nilable(Rubydex::Document)) }
   def resolve_require_path(require_path, load_paths); end
 
+  sig { params(query: String, format: T.any(String, Symbol)).returns(String) }
+  def query(query, format = :table); end
+
   sig { params(query: String).returns(T::Enumerable[Rubydex::Declaration]) }
   def search(query); end
 

rust/rubydex-sys/src/graph_api.rs

@@ -14,6 +14,7 @@ use rubydex::model::ids::{DeclarationId, NameId, UriId};
 use rubydex::model::keywords;
 use rubydex::model::name::NameRef;
 use rubydex::model::visibility::Visibility;
+use rubydex::query::cypher::{self, OutputFormat};
 use rubydex::query::{CompletionCandidate, CompletionContext, CompletionReceiver};
 use rubydex::resolution::Resolver;
 use rubydex::{indexing, integrity, listing, query};
@@ -977,6 +978,91 @@ pub unsafe extern "C" fn rdx_keyword_get(name: *const c_char) -> *const CKeyword
     }
 }
 
+/// The result of running a Cypher query, carrying either the formatted output or an error message.
+#[repr(C)]
+pub struct CQueryResult {
+    /// Non-null on success; null on error. Caller must free with `free_c_string`.
+    pub output: *const c_char,
+    /// Non-null on error; null on success. Caller must free with `free_c_string`.
+    pub error: *const c_char,
+}
+
+impl CQueryResult {
+    fn success(output: &str) -> Self {
+        match CString::new(output) {
+            Ok(c_string) => Self {
+                output: c_string.into_raw().cast_const(),
+                error: ptr::null(),
+            },
+            Err(_) => Self::error("query output contained an interior NUL byte"),
+        }
+    }
+
+    fn error(message: &str) -> Self {
+        Self {
+            output: ptr::null(),
+            error: CString::new(message).map_or(ptr::null(), |s| s.into_raw().cast_const()),
+        }
+    }
+}
+
+/// Returns a description of the queryable Cypher schema (node labels, relationship types, and
+/// properties) in the given format (`"table"` or `"json"`). The schema is static and requires no
+/// graph. Caller must free the returned pointer with `free_c_string`.
+///
+/// # Safety
+///
+/// - `format` must be a valid, null-terminated UTF-8 string.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_cypher_schema(format: *const c_char) -> *const c_char {
+    let format_str = unsafe { utils::convert_char_ptr_to_string(format) }.unwrap_or_else(|_| "table".to_string());
+    let output_format = if format_str == "json" {
+        OutputFormat::Json
+    } else {
+        OutputFormat::Table
+    };
+
+    CString::new(cypher::schema(output_format)).map_or(ptr::null(), |s| s.into_raw().cast_const())
+}
+
+/// Runs a Cypher query against the graph and returns the formatted output or an error message.
+///
+/// `format` must be `"table"` or `"json"`.
+///
+/// # Safety
+///
+/// - `pointer` must be a valid `GraphPointer` previously returned by this crate.
+/// - `query` and `format` must be valid, null-terminated UTF-8 strings.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_graph_query(
+    pointer: GraphPointer,
+    query: *const c_char,
+    format: *const c_char,
+) -> CQueryResult {
+    let Ok(query_str) = (unsafe { utils::convert_char_ptr_to_string(query) }) else {
+        return CQueryResult::error("query is not valid UTF-8");
+    };
+
+    let Ok(format_str) = (unsafe { utils::convert_char_ptr_to_string(format) }) else {
+        return CQueryResult::error("format is not valid UTF-8");
+    };
+
+    let output_format = match format_str.as_str() {
+        "table" => OutputFormat::Table,
+        "json" => OutputFormat::Json,
+        other => {
+            return CQueryResult::error(&format!("unknown query format `{other}` (expected `table` or `json`)"));
+        }
+    };
+
+    with_graph(pointer, |graph| {
+        match cypher::run_query(graph, &query_str, output_format) {
+            Ok(output) => CQueryResult::success(&output),
+            Err(error) => CQueryResult::error(&error.to_string()),
+        }
+    })
+}
+
 #[repr(u8)]
 #[derive(Debug, Clone, Copy)]
 pub enum CVisibility {