rubydex 0.2.8 → 0.3.0

data/exe/rdx

@@ -5,49 +5,151 @@ $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
+  Commands:
+    query <CYPHER>   Run a Cypher query against the workspace graph and print the result.
+                     Use `query --schema` to describe the queryable schema (labels,
+                     relationships, properties) without indexing the workspace.
+    console          Open an interactive session with a populated graph for the current workspace
+    mcp [PATH]       Run the MCP server for AI assistants (workspace defaults to the current dir)
+    help             Show this help message
+
+  Run `rdx <command> --help` for command-specific options.
+TEXT
+
+def abort_with_usage(message)
+  warn(message)
+  warn("")
+  warn(USAGE)
+  exit(1)
+end
+
+# Top-level --version / --help / bare invocation, handled before command dispatch. Each branch
+# performs its action and reports whether it handled the invocation, so we exit exactly once here
+# rather than from inside every branch.
+handled =
+  case ARGV.first
+  when "--version", "version"
     require "rubydex/version"
     puts "v#{Rubydex::VERSION}"
-    exit
+    true
+  when nil, "-h", "--help", "help"
+    puts USAGE
+    true
+  else
+    false
   end
 
-  parser.on("-h", "--help", "Prints this help") do
-    puts parser
-    exit
-  end
+exit if handled
 
-  parser.on("-i", "--interactive", "Open an interactive session with a populated graph for the current workspace") do
-    options[:interactive] = true
-  end
-end.parse!
-
-require "rubydex"
+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
 
-graph = Rubydex::Graph.new
-graph.load_config
-
-__with_timer("Indexing workspace...") { graph.index_workspace }
-__with_timer("Resolving graph...") { graph.resolve }
-
-if options[:interactive]
-  begin
-    require "irb"
-    IRB.setup(nil)
-    IRB.conf[:IRB_NAME] = "rubydex"
-    workspace = IRB::WorkSpace.new(binding)
-    IRB::Irb.new(workspace).run(IRB.conf)
-  rescue LoadError
-    abort("Interactive mode requires `irb` to be in the bundle")
-  end
+# Builds the workspace graph, sending progress messages to `progress_io`.
+def build_graph(progress_io)
+  graph = Rubydex::Graph.new
+  graph.load_config
+  with_timer(progress_io, "Indexing workspace...") { graph.index_workspace }
+  with_timer(progress_io, "Resolving graph...") { graph.resolve }
+  graph
 end
+
+require "rubydex"
+
+# Resolve the command into an operation on a populated graph. Each command parses its own options
+# and does any graph-independent work here; a command that needs no graph (like `query --schema`)
+# handles itself and exits. Whatever falls through returns a lambda that runs against the graph.
+operation =
+  case command
+  when "query"
+    schema = false
+    format = "table"
+    OptionParser.new do |parser|
+      parser.banner = "Usage: rdx query <CYPHER> [options]"
+      parser.on("--schema", "Describe the queryable schema instead of running a query") { schema = true }
+      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!
+
+    query = ARGV.shift
+
+    if schema
+      warn("warning: ignoring query argument because `--schema` was given") if query
+      # The schema is static, so describe it without building a graph, then exit.
+      print(Rubydex::Query.schema(format))
+      exit
+    end
+
+    abort_with_usage("`query` requires a Cypher query argument (or pass `--schema`)") if query.nil? || query.empty?
+
+    # Parse the query up front so a malformed query fails fast, before the expensive indexing below.
+    parsed = begin
+      Rubydex::Query.parse(query)
+    rescue ArgumentError => e
+      abort(e.message)
+    end
+
+    lambda do |graph|
+      print(parsed.render(graph, format))
+    rescue ArgumentError => e
+      abort(e.message)
+    end
+  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!
+
+    lambda do |graph|
+      require "irb"
+      IRB.setup(nil)
+      IRB.conf[:IRB_NAME] = "rubydex"
+      IRB::Irb.new(IRB::WorkSpace.new(binding)).run(IRB.conf)
+    rescue LoadError
+      abort("Interactive mode requires `irb` to be in the bundle")
+    end
+  when "mcp"
+    parser = OptionParser.new do |p|
+      p.banner = "Usage: rdx mcp [PATH]"
+      p.on("-h", "--help", "Show this help") do
+        puts p
+        exit
+      end
+    end
+    begin
+      parser.parse!
+    rescue OptionParser::ParseError => e
+      abort_with_usage(e.message)
+    end
+
+    path = ARGV.shift || Dir.pwd
+    abort_with_usage("unexpected argument: #{ARGV.first}") unless ARGV.empty?
+
+    # The MCP server manages its own graph lifecycle for the given workspace, so it runs here
+    # instead of falling through to the shared graph build below.
+    require "rubydex/mcp_server"
+    Rubydex::MCPServer.run(path)
+    exit
+  else
+    abort_with_usage("unknown command: #{command}")
+  end
+
+# Everything that reaches here operates on a populated graph. Progress goes to stderr so stdout
+# carries only the command's output (e.g. for piping a query's JSON).
+graph = build_graph($stderr)
+operation.call(graph)

data/ext/rubydex/declaration.c

@@ -236,7 +236,7 @@ static VALUE rdxr_declaration_owner(VALUE self) {
     const CDeclaration *decl = rdx_declaration_owner(graph, data->id);
 
     if (decl == NULL) {
-        rb_raise(rb_eRuntimeError, "owner can never be nil for any declarations");
+        rb_raise(rb_eRuntimeError, "Declaration must exist for a valid id");
     }
 
     VALUE decl_class = rdxi_declaration_class_for_kind(decl->kind);

data/ext/rubydex/definition.c

@@ -18,6 +18,7 @@ static VALUE mRubydex;
 static VALUE cInclude;
 static VALUE cPrepend;
 static VALUE cExtend;
+static VALUE cDocument;
 VALUE cComment;
 VALUE cDefinition;
 VALUE cClassDefinition;
@@ -88,6 +89,9 @@ static VALUE rdxr_definition_location(VALUE self) {
     void *graph = rdxi_graph_from_handle(self, &data);
 
     Location *loc = rdx_definition_location(graph, data->id);
+    if (loc == NULL) {
+        rb_raise(rb_eRuntimeError, "Definition must exist for a valid id");
+    }
     VALUE location = rdxi_build_location_value(loc);
     rdx_location_free(loc);
 
@@ -105,10 +109,11 @@ static VALUE rdxr_definition_comments(VALUE self) {
     void *graph = rdxi_graph_from_handle(self, &data);
 
     CommentArray *arr = rdx_definition_comments(graph, data->id);
-    if (arr == NULL || arr->len == 0) {
-        if (arr != NULL) {
-            rdx_definition_comments_free(arr);
-        }
+    if (arr == NULL) {
+        rb_raise(rb_eRuntimeError, "Definition must exist for a valid id");
+    }
+    if (arr->len == 0) {
+        rdx_definition_comments_free(arr);
         return rb_ary_new();
     }
 
@@ -261,6 +266,27 @@ static VALUE rdxr_definition_lexical_nesting(VALUE self) {
     return nesting;
 }
 
+/*
+ * call-seq:
+ *   document -> Rubydex::Document
+ *
+ * Returns the document this definition belongs to.
+ */
+static VALUE rdxr_definition_document(VALUE self) {
+    HandleData *data;
+    void *graph = rdxi_graph_from_handle(self, &data);
+
+    const uint64_t *uri_id = rdx_definition_document(graph, data->id);
+    if (uri_id == NULL) {
+        rb_raise(rb_eRuntimeError, "Definition not found");
+    }
+
+    VALUE argv[] = {data->graph_obj, ULL2NUM(*uri_id)};
+    free_u64(uri_id);
+
+    return rb_class_new_instance(2, argv, cDocument);
+}
+
 static VALUE rdxi_build_constant_reference(VALUE graph_obj, const CConstantReference *cref) {
     VALUE ref_class = (cref->declaration_id == 0)
         ? cUnresolvedConstantReference
@@ -397,6 +423,7 @@ void rdxi_initialize_definition(VALUE mod) {
     cInclude = rb_const_get(mRubydex, rb_intern("Include"));
     cPrepend = rb_const_get(mRubydex, rb_intern("Prepend"));
     cExtend = rb_const_get(mRubydex, rb_intern("Extend"));
+    cDocument = rb_const_get(mRubydex, rb_intern("Document"));
 
     cComment = rb_define_class_under(mRubydex, "Comment", rb_cObject);
 
@@ -412,6 +439,7 @@ void rdxi_initialize_definition(VALUE mod) {
     rb_define_method(cDefinition, "declaration", rdxr_definition_declaration, 0);
     rb_define_method(cDefinition, "lexical_owner", rdxr_definition_lexical_owner, 0);
     rb_define_method(cDefinition, "lexical_nesting", rdxr_definition_lexical_nesting, 0);
+    rb_define_method(cDefinition, "document", rdxr_definition_document, 0);
 
     cClassDefinition = rb_define_class_under(mRubydex, "ClassDefinition", cDefinition);
     rb_define_method(cClassDefinition, "superclass", rdxr_class_definition_superclass, 0);

data/ext/rubydex/extconf.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "mkmf"
-require "fileutils"
 require "pathname"
 
 unless system("cargo", "--version", out: File::NULL, err: File::NULL)
@@ -82,12 +81,6 @@ else
 end
 
 lib_dir = gem_dir.join("lib").join("rubydex")
-mcp_bin_dir = lib_dir.join("bin")
-FileUtils.mkdir_p(mcp_bin_dir)
-
-mcp_executable = Gem.win_platform? ? "rubydex_mcp.exe" : "rubydex_mcp"
-mcp_src = target_dir.join(mcp_executable)
-mcp_dst = mcp_bin_dir.join(mcp_executable)
 
 copy_dylib_commands = if Gem.win_platform?
   ""
@@ -114,7 +107,6 @@ new_makefile = makefile.gsub("$(OBJS): $(HDRS) $(ruby_headers)", <<~MAKEFILE.cho
   .rust_built: $(RUST_SRCS)
   \t#{cargo_command} || (echo "Compiling Rust failed" && exit 1)
   \t$(COPY) #{bindings_path} #{__dir__}
-  \t$(COPY) #{mcp_src} #{mcp_dst}
   \ttouch $@
 
   compile_rust: .rust_built

data/ext/rubydex/graph.c

@@ -63,16 +63,25 @@ const rb_data_type_t graph_type = {
     },
     .parent = NULL,
     .data = NULL,
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_FROZEN_SHAREABLE,
 };
 
-// Custom allocator for the Graph class. Calls into Rust to create a new `Arc<Mutex<Graph>>` that gets stored internally
-// as a void pointer
+// Custom allocator for the Graph class. Calls into Rust to create a new Box<RwLock<Graph>> that gets stored
+// internally as an opaque void pointer. The RwLock provides thread-safe concurrent access across Ractors.
 static VALUE rdxr_graph_alloc(VALUE klass) {
     void *graph = rdx_graph_new();
     return TypedData_Wrap_Struct(klass, &graph_type, graph);
 }
 
+// Graph is intentionally non-copyable. A dup/clone of the TypedData wrapper would alias the
+// same underlying Rust allocation (double-free on GC) or, if deep-copied, balloon memory use.
+// Block both paths: `dup` dispatches to `initialize_copy`, `clone` to `initialize_clone`.
+static VALUE rdxr_graph_initialize_copy(VALUE self, VALUE other) {
+    (void)self;
+    (void)other;
+    rb_raise(rb_eRuntimeError, "Rubydex::Graph cannot be duplicated or cloned");
+}
+
 /*
  * call-seq:
  *   index_all(file_paths) -> Array[String]
@@ -796,38 +805,38 @@ static VALUE rdxr_graph_complete_method_argument(int argc, VALUE *argv, VALUE se
 
 /*
  * call-seq:
- *   exclude_paths(paths) -> nil
+ *   exclude_patterns(patterns) -> nil
  *
- * Excludes the paths from file discovery during indexing.
+ * Excludes files matching the given glob patterns from discovery during indexing.
  */
-static VALUE rdxr_graph_exclude_paths(VALUE self, VALUE paths) {
-    Check_Type(paths, T_ARRAY);
-    rdxi_check_array_of_strings(paths);
+static VALUE rdxr_graph_exclude_patterns(VALUE self, VALUE patterns) {
+    Check_Type(patterns, T_ARRAY);
+    rdxi_check_array_of_strings(patterns);
 
-    size_t length = RARRAY_LEN(paths);
-    char **converted_paths = rdxi_str_array_to_char(paths, length);
+    size_t length = RARRAY_LEN(patterns);
+    char **converted_patterns = rdxi_str_array_to_char(patterns, length);
 
     void *graph;
     TypedData_Get_Struct(self, void*, &graph_type, graph);
 
-    rdx_graph_exclude_paths(graph, (const char **)converted_paths, length);
-    rdxi_free_str_array(converted_paths, length);
+    rdx_graph_exclude_patterns(graph, (const char **)converted_patterns, length);
+    rdxi_free_str_array(converted_patterns, length);
 
     return Qnil;
 }
 
 /*
  * call-seq:
- *   excluded_paths -> Array[String]
+ *   excluded_patterns -> Array[String]
  *
- * Returns the paths currently excluded from file discovery.
+ * Returns the glob patterns currently excluded from file discovery.
  */
-static VALUE rdxr_graph_excluded_paths(VALUE self) {
+static VALUE rdxr_graph_excluded_patterns(VALUE self) {
     void *graph;
     TypedData_Get_Struct(self, void*, &graph_type, graph);
 
     size_t out_count = 0;
-    const char *const *results = rdx_graph_excluded_paths(graph, &out_count);
+    const char *const *results = rdx_graph_excluded_patterns(graph, &out_count);
 
     if (results == NULL) {
         return rb_ary_new();
@@ -943,6 +952,8 @@ void rdxi_initialize_graph(VALUE moduleRubydex) {
     id_self_receiver = rb_intern("self_receiver");
 
     rb_define_alloc_func(cGraph, rdxr_graph_alloc);
+    rb_define_method(cGraph, "initialize_copy", rdxr_graph_initialize_copy, 1);
+    rb_define_method(cGraph, "initialize_clone", rdxr_graph_initialize_copy, 1);
     rb_define_method(cGraph, "index_all", rdxr_graph_index_all, 1);
     rb_define_method(cGraph, "index_source", rdxr_graph_index_source, 3);
     rb_define_method(cGraph, "document", rdxr_graph_document, 1);
@@ -965,8 +976,8 @@ void rdxi_initialize_graph(VALUE moduleRubydex) {
     rb_define_method(cGraph, "complete_namespace_access", rdxr_graph_complete_namespace_access, -1);
     rb_define_method(cGraph, "complete_method_call", rdxr_graph_complete_method_call, -1);
     rb_define_method(cGraph, "complete_method_argument", rdxr_graph_complete_method_argument, -1);
-    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, "exclude_patterns", rdxr_graph_exclude_patterns, 1);
+    rb_define_method(cGraph, "excluded_patterns", rdxr_graph_excluded_patterns, 0);
     rb_define_method(cGraph, "workspace_path", rdxr_graph_workspace_path, 0);
     rb_define_method(cGraph, "workspace_path=", rdxr_graph_set_workspace_path, 1);
     rb_define_method(cGraph, "load_config", rdxr_graph_load_config, -1);

data/ext/rubydex/query.c

@@ -0,0 +1,105 @@
+#include "query.h"
+#include "graph.h"
+#include "rustbindings.h"
+#include "utils.h"
+
+/*
+ * call-seq:
+ *   Rubydex::Query.schema(format = :table) -> String
+ *
+ * Returns a description of the queryable Cypher schema. +format+ may be +:table+ (default) or
+ * +:json+. The schema is static, so it does not require a graph.
+ */
+static VALUE rdxr_cypher_schema(int argc, VALUE *argv, VALUE self) {
+    VALUE format;
+    rb_scan_args(argc, argv, "01", &format);
+
+    const char *output = rdx_cypher_schema(rdxi_symbol_or_string_cstr(format, "table"));
+    VALUE result = output == NULL ? rb_utf8_str_new_cstr("") : rb_utf8_str_new_cstr(output);
+    if (output != NULL) {
+        free_c_string(output);
+    }
+
+    return result;
+}
+
+// Free function for Rubydex::Query: releases the parsed query allocated by Rust.
+static void query_free(void *ptr) {
+    if (ptr) {
+        rdx_cypher_query_free(ptr);
+    }
+}
+
+static const rb_data_type_t query_type = {
+    .wrap_struct_name = "Rubydex::Query",
+    .function = {
+        .dmark = NULL,
+        .dfree = query_free,
+        .dsize = NULL,
+        .dcompact = NULL,
+    },
+    .parent = NULL,
+    .data = NULL,
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+/*
+ * call-seq:
+ *   Rubydex::Query.parse(query) -> Rubydex::Query
+ *
+ * Parses a Cypher query into an opaque, reusable object without needing a graph. Raises
+ * ArgumentError on a syntax error, so a query can be validated before building a graph.
+ */
+static VALUE rdxr_query_parse(VALUE klass, VALUE query) {
+    Check_Type(query, T_STRING);
+
+    struct CParseResult result = rdx_cypher_parse(StringValueCStr(query));
+    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));
+    }
+
+    return TypedData_Wrap_Struct(klass, &query_type, result.query);
+}
+
+/*
+ * call-seq:
+ *   render(graph, format = :table) -> String
+ *
+ * Runs this parsed query against +graph+ and returns the formatted output. +format+ may be
+ * +:table+ (default) or +:json+. Raises ArgumentError on an execution or format error.
+ */
+static VALUE rdxr_query_render(int argc, VALUE *argv, VALUE self) {
+    VALUE graph_obj, format;
+    rb_scan_args(argc, argv, "11", &graph_obj, &format);
+
+    void *query;
+    TypedData_Get_Struct(self, void *, &query_type, query);
+
+    void *graph;
+    TypedData_Get_Struct(graph_obj, void *, &graph_type, graph);
+
+    struct CQueryResult result = rdx_query_run(query, graph, rdxi_symbol_or_string_cstr(format, "table"));
+
+    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;
+}
+
+void rdxi_initialize_query(VALUE mRubydex) {
+    VALUE cQuery = rb_define_class_under(mRubydex, "Query", rb_cObject);
+    rb_undef_alloc_func(cQuery);
+    rb_define_singleton_method(cQuery, "parse", rdxr_query_parse, 1);
+    rb_define_singleton_method(cQuery, "schema", rdxr_cypher_schema, -1);
+    rb_define_method(cQuery, "render", rdxr_query_render, -1);
+}

data/ext/rubydex/query.h

@@ -0,0 +1,8 @@
+#ifndef RUBYDEX_QUERY_H
+#define RUBYDEX_QUERY_H
+
+#include "ruby.h"
+
+void rdxi_initialize_query(VALUE mRubydex);
+
+#endif // RUBYDEX_QUERY_H

data/ext/rubydex/reference.c

@@ -17,6 +17,8 @@ VALUE cUnresolvedConstantReference;
 VALUE cResolvedConstantReference;
 VALUE cMethodReference;
 
+static VALUE cDocument;
+
 /*
  * call-seq:
  *   name -> String
@@ -28,6 +30,9 @@ static VALUE rdxr_constant_reference_name(VALUE self) {
     void *graph = rdxi_graph_from_handle(self, &data);
 
     const char *name = rdx_constant_reference_name(graph, data->id);
+    if (name == NULL) {
+        rb_raise(rb_eRuntimeError, "Constant reference must exist for a valid id");
+    }
     return rdxi_owned_c_string_to_ruby(name);
 }
 
@@ -42,11 +47,35 @@ static VALUE rdxr_constant_reference_location(VALUE self) {
     void *graph = rdxi_graph_from_handle(self, &data);
 
     Location *loc = rdx_constant_reference_location(graph, data->id);
+    if (loc == NULL) {
+        rb_raise(rb_eRuntimeError, "Constant reference must exist for a valid id");
+    }
     VALUE location = rdxi_build_location_value(loc);
     rdx_location_free(loc);
     return location;
 }
 
+/*
+ * call-seq:
+ *   document -> Rubydex::Document
+ *
+ * Returns the document this constant reference belongs to.
+ */
+static VALUE rdxr_constant_reference_document(VALUE self) {
+    HandleData *data;
+    void *graph = rdxi_graph_from_handle(self, &data);
+
+    const uint64_t *uri_id = rdx_constant_reference_document(graph, data->id);
+    if (uri_id == NULL) {
+        rb_raise(rb_eRuntimeError, "Constant reference not found");
+    }
+
+    VALUE argv[] = {data->graph_obj, ULL2NUM(*uri_id)};
+    free_u64(uri_id);
+
+    return rb_class_new_instance(2, argv, cDocument);
+}
+
 /*
  * call-seq:
  *   name -> String
@@ -58,6 +87,9 @@ static VALUE rdxr_method_reference_name(VALUE self) {
     void *graph = rdxi_graph_from_handle(self, &data);
 
     const char *name = rdx_method_reference_name(graph, data->id);
+    if (name == NULL) {
+        rb_raise(rb_eRuntimeError, "Method reference must exist for a valid id");
+    }
     return rdxi_owned_c_string_to_ruby(name);
 }
 
@@ -72,6 +104,9 @@ static VALUE rdxr_method_reference_location(VALUE self) {
     void *graph = rdxi_graph_from_handle(self, &data);
 
     Location *loc = rdx_method_reference_location(graph, data->id);
+    if (loc == NULL) {
+        rb_raise(rb_eRuntimeError, "Method reference must exist for a valid id");
+    }
     VALUE location = rdxi_build_location_value(loc);
     rdx_location_free(loc);
     return location;
@@ -100,6 +135,27 @@ static VALUE rdxr_method_reference_receiver(VALUE self) {
     return rb_class_new_instance(2, argv, decl_class);
 }
 
+/*
+ * call-seq:
+ *   document -> Rubydex::Document
+ *
+ * Returns the document this method reference belongs to.
+ */
+static VALUE rdxr_method_reference_document(VALUE self) {
+    HandleData *data;
+    void *graph = rdxi_graph_from_handle(self, &data);
+
+    const uint64_t *uri_id = rdx_method_reference_document(graph, data->id);
+    if (uri_id == NULL) {
+        rb_raise(rb_eRuntimeError, "Method reference not found");
+    }
+
+    VALUE argv[] = {data->graph_obj, ULL2NUM(*uri_id)};
+    free_u64(uri_id);
+
+    return rb_class_new_instance(2, argv, cDocument);
+}
+
 /*
  * call-seq:
  *   declaration -> Rubydex::Declaration
@@ -123,6 +179,8 @@ static VALUE rdxr_resolved_constant_reference_declaration(VALUE self) {
 }
 
 void rdxi_initialize_reference(VALUE mRubydex) {
+    cDocument = rb_const_get(mRubydex, rb_intern("Document"));
+
     cReference = rb_define_class_under(mRubydex, "Reference", rb_cObject);
     rb_define_alloc_func(cReference, rdxr_handle_alloc);
     rb_define_method(cReference, "initialize", rdxr_handle_initialize, 2);
@@ -132,6 +190,7 @@ void rdxi_initialize_reference(VALUE mRubydex) {
     rb_define_alloc_func(cConstantReference, rdxr_handle_alloc);
     rb_define_method(cConstantReference, "initialize", rdxr_handle_initialize, 2);
     rb_define_method(cConstantReference, "location", rdxr_constant_reference_location, 0);
+    rb_define_method(cConstantReference, "document", rdxr_constant_reference_document, 0);
     rb_funcall(rb_singleton_class(cConstantReference), rb_intern("private"), 1, ID2SYM(rb_intern("new")));
 
     cUnresolvedConstantReference = rb_define_class_under(mRubydex, "UnresolvedConstantReference", cConstantReference);
@@ -148,4 +207,5 @@ void rdxi_initialize_reference(VALUE mRubydex) {
     rb_define_method(cMethodReference, "name", rdxr_method_reference_name, 0);
     rb_define_method(cMethodReference, "location", rdxr_method_reference_location, 0);
     rb_define_method(cMethodReference, "receiver", rdxr_method_reference_receiver, 0);
+    rb_define_method(cMethodReference, "document", rdxr_method_reference_document, 0);
 }

data/ext/rubydex/rubydex.c

@@ -4,6 +4,7 @@
 #include "document.h"
 #include "graph.h"
 #include "location.h"
+#include "query.h"
 #include "reference.h"
 #include "signature.h"
 
@@ -19,6 +20,7 @@ void Init_rubydex(void) {
      */
     mRubydex = rb_define_module("Rubydex");
     rdxi_initialize_graph(mRubydex);
+    rdxi_initialize_query(mRubydex);
     rdxi_initialize_declaration(mRubydex);
     rdxi_initialize_document(mRubydex);
     rdxi_initialize_definition(mRubydex);

data/ext/rubydex/utils.c

@@ -52,6 +52,18 @@ VALUE rdxi_owned_c_string_to_ruby(const char *string) {
     return value;
 }
 
+// Coerce an optional String, Symbol, or nil to a C string, defaulting to `default_value` for nil.
+const char *rdxi_symbol_or_string_cstr(VALUE value, const char *default_value) {
+    if (NIL_P(value)) {
+        return default_value;
+    }
+    if (RB_TYPE_P(value, T_SYMBOL)) {
+        value = rb_sym2str(value);
+    }
+    Check_Type(value, T_STRING);
+    return StringValueCStr(value);
+}
+
 // Yield body for iterating over declarations
 VALUE rdxi_declarations_yield(VALUE args) {
     VALUE self = rb_ary_entry(args, 0);