Merge pull request #778 from Shopify/Expose_declaration_visibility_in_the_Ruby_API

Expose declaration visibility in the Ruby API

Author: alexcrocha

ext/rubydex/declaration.c

@@ -407,6 +407,38 @@ static VALUE rdxr_variable_declaration_references(VALUE self) {
     return rb_ary_new();
 }
 
+static VALUE rdxi_visibility_to_symbol(CVisibility visibility) {
+    switch (visibility) {
+    case CVisibility_Public:
+        return ID2SYM(rb_intern("public"));
+    case CVisibility_Protected:
+        return ID2SYM(rb_intern("protected"));
+    case CVisibility_Private:
+        return ID2SYM(rb_intern("private"));
+    default:
+        rb_raise(rb_eRuntimeError, "Unknown CVisibility: %d", visibility);
+    }
+}
+
+// Declaration#visibility -> Symbol
+static VALUE rdxr_declaration_visibility(VALUE self) {
+    HandleData *data;
+    TypedData_Get_Struct(self, HandleData, &handle_type, data);
+
+    void *graph;
+    TypedData_Get_Struct(data->graph_obj, void *, &graph_type, graph);
+
+    const CVisibility *visibility = rdx_graph_visibility(graph, data->id);
+    if (visibility == NULL) {
+        rb_raise(rb_eRuntimeError, "declaration has no visibility");
+    }
+
+    VALUE symbol = rdxi_visibility_to_symbol(*visibility);
+    free_c_visibility(visibility);
+
+    return symbol;
+}
+
 // ConstantAlias#target -> Declaration?
 // Returns the first resolved target declaration for this constant alias, or nil if none of its definitions resolved to
 // a target
@@ -459,13 +491,19 @@ void rdxi_initialize_declaration(VALUE mRubydex) {
     rb_define_method(cNamespace, "descendants", rdxr_declaration_descendants, 0);
     rb_define_method(cNamespace, "members", rdxr_declaration_members, 0);
 
+    rb_define_method(cClass, "visibility", rdxr_declaration_visibility, 0);
+    rb_define_method(cModule, "visibility", rdxr_declaration_visibility, 0);
+
     // Constant and ConstantAlias have constant references
     rb_define_method(cConstant, "references", rdxr_constant_declaration_references, 0);
+    rb_define_method(cConstant, "visibility", rdxr_declaration_visibility, 0);
     rb_define_method(cConstantAlias, "references", rdxr_constant_declaration_references, 0);
     rb_define_method(cConstantAlias, "target", rdxr_constant_alias_target, 0);
+    rb_define_method(cConstantAlias, "visibility", rdxr_declaration_visibility, 0);
 
     // Method has method references
     rb_define_method(cMethod, "references", rdxr_method_declaration_references, 0);
+    rb_define_method(cMethod, "visibility", rdxr_declaration_visibility, 0);
 
     // Variable declarations don't yet support references
     rb_define_method(cGlobalVariable, "references", rdxr_variable_declaration_references, 0);

lib/rubydex/declaration.rb

@@ -1,11 +1,42 @@
 # frozen_string_literal: true
 
 module Rubydex
+  module Visibility
+    #: () -> bool
+    def public? = visibility == :public
+
+    #: () -> bool
+    def private? = visibility == :private
+
+    #: () -> bool
+    def protected? = visibility == :protected
+  end
+
   class Declaration
     # @abstract
     #: () -> Enumerable[Reference]
     def references
       raise NotImplementedError, "Subclasses must implement #references"
     end
   end
+
+  class Class < Namespace
+    include Visibility
+  end
+
+  class Module < Namespace
+    include Visibility
+  end
+
+  class Constant < Declaration
+    include Visibility
+  end
+
+  class ConstantAlias < Declaration
+    include Visibility
+  end
+
+  class Method < Declaration
+    include Visibility
+  end
 end

rust/rubydex-sys/src/graph_api.rs

@@ -13,6 +13,7 @@ use rubydex::model::graph::Graph;
 use rubydex::model::ids::{DeclarationId, NameId, UriId};
 use rubydex::model::keywords;
 use rubydex::model::name::NameRef;
+use rubydex::model::visibility::Visibility;
 use rubydex::query::{CompletionCandidate, CompletionContext, CompletionReceiver};
 use rubydex::resolution::Resolver;
 use rubydex::{indexing, integrity, listing, query};
@@ -962,6 +963,53 @@ pub unsafe extern "C" fn rdx_keyword_get(name: *const c_char) -> *const CKeyword
     }
 }
 
+#[repr(u8)]
+#[derive(Debug, Clone, Copy)]
+pub enum CVisibility {
+    Public = 0,
+    Protected = 1,
+    Private = 2,
+}
+
+/// Returns the visibility of a declaration (method, constant, class, or module) as a heap-allocated
+/// `CVisibility`, or NULL when the declaration carries no visibility (e.g. variables, singleton
+/// classes, todos). Caller must free the returned pointer with `free_c_visibility`.
+///
+/// # Safety
+///
+/// - `pointer` must be a valid `GraphPointer` previously returned by this crate.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_graph_visibility(pointer: GraphPointer, declaration_id: u64) -> *const CVisibility {
+    with_graph(pointer, |graph| {
+        let Some(visibility) = graph.visibility(&DeclarationId::new(declaration_id)) else {
+            return ptr::null();
+        };
+
+        let c_visibility = match visibility {
+            Visibility::Public => CVisibility::Public,
+            Visibility::Protected => CVisibility::Protected,
+            Visibility::Private => CVisibility::Private,
+            Visibility::ModuleFunction => {
+                unimplemented!("module_function visibility translation is not implemented yet")
+            }
+        };
+
+        Box::into_raw(Box::new(c_visibility)).cast_const()
+    })
+}
+
+/// Frees a `CVisibility` previously returned by `rdx_graph_visibility`.
+///
+/// # Safety
+///
+/// - `ptr` must be a valid pointer previously returned by `rdx_graph_visibility`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn free_c_visibility(ptr: *const CVisibility) {
+    unsafe {
+        let _ = Box::from_raw(ptr.cast_mut());
+    }
+}
+
 /// Frees a `CKeyword` previously returned by `rdx_keyword_get`.
 ///
 /// # Safety

test/declaration_test.rb

@@ -691,6 +691,234 @@ def test_circular_constant_alias_target
     end
   end
 
+  def test_method_visibility_defaults_to_public
+    with_context do |context|
+      context.write!("file1.rb", <<~RUBY)
+        class Foo
+          def bare; end
+        end
+      RUBY
+
+      graph = Rubydex::Graph.new
+      graph.index_all(context.glob("**/*.rb"))
+      graph.resolve
+
+      assert_equal(:public, graph["Foo#bare()"].visibility)
+    end
+  end
+
+  def test_method_visibility_via_scope_flag
+    with_context do |context|
+      context.write!("file1.rb", <<~RUBY)
+        class Foo
+          private
+
+          def hidden; end
+
+          protected
+
+          def guarded; end
+
+          public
+
+          def visible; end
+        end
+      RUBY
+
+      graph = Rubydex::Graph.new
+      graph.index_all(context.glob("**/*.rb"))
+      graph.resolve
+
+      assert_equal(:private, graph["Foo#hidden()"].visibility)
+      assert_equal(:protected, graph["Foo#guarded()"].visibility)
+      assert_equal(:public, graph["Foo#visible()"].visibility)
+    end
+  end
+
+  def test_method_visibility_via_retroactive_call
+    with_context do |context|
+      context.write!("file1.rb", <<~RUBY)
+        class Foo
+          def hidden; end
+          private :hidden
+
+          def guarded; end
+          protected :guarded
+        end
+      RUBY
+
+      graph = Rubydex::Graph.new
+      graph.index_all(context.glob("**/*.rb"))
+      graph.resolve
+
+      assert_equal(:private, graph["Foo#hidden()"].visibility)
+      assert_equal(:protected, graph["Foo#guarded()"].visibility)
+    end
+  end
+
+  def test_constant_visibility_defaults_to_public
+    with_context do |context|
+      context.write!("file1.rb", <<~RUBY)
+        class Foo
+          BAR = 1
+        end
+      RUBY
+
+      graph = Rubydex::Graph.new
+      graph.index_all(context.glob("**/*.rb"))
+      graph.resolve
+
+      assert_equal(:public, graph["Foo::BAR"].visibility)
+    end
+  end
+
+  def test_constant_visibility_via_private_constant
+    with_context do |context|
+      context.write!("file1.rb", <<~RUBY)
+        class Foo
+          BAR = 1
+          private_constant :BAR
+        end
+      RUBY
+
+      graph = Rubydex::Graph.new
+      graph.index_all(context.glob("**/*.rb"))
+      graph.resolve
+
+      assert_equal(:private, graph["Foo::BAR"].visibility)
+    end
+  end
+
+  def test_constant_alias_visibility
+    with_context do |context|
+      context.write!("file1.rb", <<~RUBY)
+        class Foo
+          BAR = 1
+          ALIAS = BAR
+          private_constant :ALIAS
+        end
+      RUBY
+
+      graph = Rubydex::Graph.new
+      graph.index_all(context.glob("**/*.rb"))
+      graph.resolve
+
+      assert_equal(:private, graph["Foo::ALIAS"].visibility)
+    end
+  end
+
+  def test_class_and_module_visibility_via_private_constant
+    with_context do |context|
+      context.write!("file1.rb", <<~RUBY)
+        class Outer
+          class Inner; end
+          module Helpers; end
+          private_constant :Inner, :Helpers
+        end
+      RUBY
+
+      graph = Rubydex::Graph.new
+      graph.index_all(context.glob("**/*.rb"))
+      graph.resolve
+
+      assert_equal(:private, graph["Outer::Inner"].visibility)
+      assert_equal(:private, graph["Outer::Helpers"].visibility)
+    end
+  end
+
+  def test_visibility_is_undefined_for_declarations_without_visibility
+    with_context do |context|
+      context.write!("file1.rb", <<~RUBY)
+        class Foo
+          @@class_var = 1
+
+          def initialize
+            @ivar = 1
+          end
+
+          class << self; end
+        end
+
+        $global = 1
+      RUBY
+
+      graph = Rubydex::Graph.new
+      graph.index_all(context.glob("**/*.rb"))
+      graph.resolve
+
+      refute_respond_to(graph["Foo::<Foo>"], :visibility)
+      refute_respond_to(graph["Foo\#@ivar"], :visibility)
+      refute_respond_to(graph["Foo\#@@class_var"], :visibility)
+      refute_respond_to(graph["$global"], :visibility)
+    end
+  end
+
+  def test_inline_module_function_visibility
+    with_context do |context|
+      context.write!("file1.rb", <<~RUBY)
+        module Foo
+          module_function
+
+          def bar; end
+        end
+      RUBY
+
+      graph = Rubydex::Graph.new
+      graph.index_all(context.glob("**/*.rb"))
+      graph.resolve
+
+      assert_equal(:private, graph["Foo#bar()"].visibility)
+      assert_equal(:public, graph["Foo::<Foo>#bar()"].visibility)
+    end
+  end
+
+  def test_visibility_predicates
+    with_context do |context|
+      context.write!("file1.rb", <<~RUBY)
+        class Foo
+          def visible; end
+
+          def hidden; end
+          private :hidden
+
+          def guarded; end
+          protected :guarded
+
+          BAR = 1
+          PRIVATE_BAR = 2
+          private_constant :PRIVATE_BAR
+        end
+      RUBY
+
+      graph = Rubydex::Graph.new
+      graph.index_all(context.glob("**/*.rb"))
+      graph.resolve
+
+      visible = graph["Foo#visible()"]
+      assert_predicate(visible, :public?)
+      refute_predicate(visible, :private?)
+      refute_predicate(visible, :protected?)
+
+      hidden = graph["Foo#hidden()"]
+      assert_predicate(hidden, :private?)
+      refute_predicate(hidden, :public?)
+      refute_predicate(hidden, :protected?)
+
+      guarded = graph["Foo#guarded()"]
+      assert_predicate(guarded, :protected?)
+      refute_predicate(guarded, :public?)
+      refute_predicate(guarded, :private?)
+
+      bar = graph["Foo::BAR"]
+      assert_predicate(bar, :public?)
+      refute_predicate(bar, :private?)
+
+      private_bar = graph["Foo::PRIVATE_BAR"]
+      assert_predicate(private_bar, :private?)
+      refute_predicate(private_bar, :public?)
+    end
+  end
+
   def test_constant_alias_with_multiple_definitions_returns_one_resolved_target
     with_context do |context|
       context.write!("file1.rb", <<~RUBY)