spoom 1.5.4 → 1.6.0

data/lib/spoom/model/model.rb

@@ -3,46 +3,57 @@
 
 module Spoom
   class Model
-    extend T::Sig
-
     class Error < Spoom::Error; end
 
+    class Comment
+      #: String
+      attr_reader :string
+
+      #: Location
+      attr_reader :location
+
+      #: (String string, Location location) -> void
+      def initialize(string, location)
+        @string = string
+        @location = location
+      end
+    end
+
     # A Symbol is a uniquely named entity in the Ruby codebase
     #
     # A symbol can have multiple definitions, e.g. a class can be reopened.
     # Sometimes a symbol can have multiple definitions of different types,
     # e.g. `foo` method can be defined both as a method and as an attribute accessor.
     class Symbol
-      extend T::Sig
-
       # The full, unique name of this symbol
-      sig { returns(String) }
+      #: String
       attr_reader :full_name
 
       # The definitions of this symbol (where it exists in the code)
-      sig { returns(T::Array[SymbolDef]) }
+      #: Array[SymbolDef]
       attr_reader :definitions
 
-      sig { params(full_name: String).void }
+      #: (String full_name) -> void
       def initialize(full_name)
         @full_name = full_name
         @definitions = T.let([], T::Array[SymbolDef])
       end
 
       # The short name of this symbol
-      sig { returns(String) }
+      #: -> String
       def name
         T.must(@full_name.split("::").last)
       end
 
-      sig { returns(String) }
+      #: -> String
       def to_s
         @full_name
       end
     end
 
     class UnresolvedSymbol < Symbol
-      sig { override.returns(String) }
+      # @override
+      #: -> String
       def to_s
         "<#{@full_name}>"
       end
@@ -53,41 +64,45 @@ module Spoom
     # It can be a class, module, constant, method, etc.
     # A SymbolDef has a location pointing to the actual code that defines the symbol.
     class SymbolDef
-      extend T::Sig
       extend T::Helpers
 
       abstract!
 
       # The symbol this definition belongs to
-      sig { returns(Symbol) }
+      #: Symbol
       attr_reader :symbol
 
       # The enclosing namespace this definition belongs to
-      sig { returns(T.nilable(Namespace)) }
+      #: Namespace?
       attr_reader :owner
 
       # The actual code location of this definition
-      sig { returns(Location) }
+      #: Location
       attr_reader :location
 
-      sig { params(symbol: Symbol, owner: T.nilable(Namespace), location: Location).void }
-      def initialize(symbol, owner:, location:)
+      # The comments associated with this definition
+      #: Array[Comment]
+      attr_reader :comments
+
+      #: (Symbol symbol, owner: Namespace?, location: Location, ?comments: Array[Comment]) -> void
+      def initialize(symbol, owner:, location:, comments:)
         @symbol = symbol
         @owner = owner
         @location = location
+        @comments = comments
 
         symbol.definitions << self
         owner.children << self if owner
       end
 
       # The full name of the symbol this definition belongs to
-      sig { returns(String) }
+      #: -> String
       def full_name
         @symbol.full_name
       end
 
       # The short name of the symbol this definition belongs to
-      sig { returns(String) }
+      #: -> String
       def name
         @symbol.name
       end
@@ -97,15 +112,15 @@ module Spoom
     class Namespace < SymbolDef
       abstract!
 
-      sig { returns(T::Array[SymbolDef]) }
+      #: Array[SymbolDef]
       attr_reader :children
 
-      sig { returns(T::Array[Mixin]) }
+      #: Array[Mixin]
       attr_reader :mixins
 
-      sig { params(symbol: Symbol, owner: T.nilable(Namespace), location: Location).void }
-      def initialize(symbol, owner:, location:)
-        super(symbol, owner: owner, location: location)
+      #: (Symbol symbol, owner: Namespace?, location: Location, ?comments: Array[Comment]) -> void
+      def initialize(symbol, owner:, location:, comments: [])
+        super(symbol, owner: owner, location: location, comments: comments)
 
         @children = T.let([], T::Array[SymbolDef])
         @mixins = T.let([], T::Array[Mixin])
@@ -115,19 +130,12 @@ module Spoom
     class SingletonClass < Namespace; end
 
     class Class < Namespace
-      sig { returns(T.nilable(String)) }
+      #: String?
       attr_accessor :superclass_name
 
-      sig do
-        params(
-          symbol: Symbol,
-          owner: T.nilable(Namespace),
-          location: Location,
-          superclass_name: T.nilable(String),
-        ).void
-      end
-      def initialize(symbol, owner:, location:, superclass_name: nil)
-        super(symbol, owner: owner, location: location)
+      #: (Symbol symbol, owner: Namespace?, location: Location, ?superclass_name: String?, ?comments: Array[Comment]) -> void
+      def initialize(symbol, owner:, location:, superclass_name: nil, comments: [])
+        super(symbol, owner: owner, location: location, comments: comments)
 
         @superclass_name = superclass_name
       end
@@ -136,12 +144,12 @@ module Spoom
     class Module < Namespace; end
 
     class Constant < SymbolDef
-      sig { returns(String) }
+      #: String
       attr_reader :value
 
-      sig { params(symbol: Symbol, owner: T.nilable(Namespace), location: Location, value: String).void }
-      def initialize(symbol, owner:, location:, value:)
-        super(symbol, owner: owner, location: location)
+      #: (Symbol symbol, owner: Namespace?, location: Location, value: String, ?comments: Array[Comment]) -> void
+      def initialize(symbol, owner:, location:, value:, comments: [])
+        super(symbol, owner: owner, location: location, comments: comments)
 
         @value = value
       end
@@ -151,23 +159,15 @@ module Spoom
     class Property < SymbolDef
       abstract!
 
-      sig { returns(Visibility) }
+      #: Visibility
       attr_reader :visibility
 
-      sig { returns(T::Array[Sig]) }
+      #: Array[Sig]
       attr_reader :sigs
 
-      sig do
-        params(
-          symbol: Symbol,
-          owner: T.nilable(Namespace),
-          location: Location,
-          visibility: Visibility,
-          sigs: T::Array[Sig],
-        ).void
-      end
-      def initialize(symbol, owner:, location:, visibility:, sigs: [])
-        super(symbol, owner: owner, location: location)
+      #: (Symbol symbol, owner: Namespace?, location: Location, visibility: Visibility, ?sigs: Array[Sig], ?comments: Array[Comment]) -> void
+      def initialize(symbol, owner:, location:, visibility:, sigs: [], comments: [])
+        super(symbol, owner: owner, location: location, comments: comments)
 
         @visibility = visibility
         @sigs = sigs
@@ -194,15 +194,14 @@ module Spoom
 
     # A mixin (include, prepend, extend) to a namespace
     class Mixin
-      extend T::Sig
       extend T::Helpers
 
       abstract!
 
-      sig { returns(String) }
+      #: String
       attr_reader :name
 
-      sig { params(name: String).void }
+      #: (String name) -> void
       def initialize(name)
         @name = name
       end
@@ -214,12 +213,10 @@ module Spoom
 
     # A Sorbet signature (sig block)
     class Sig
-      extend T::Sig
-
-      sig { returns(String) }
+      #: String
       attr_reader :string
 
-      sig { params(string: String).void }
+      #: (String string) -> void
       def initialize(string)
         @string = string
       end
@@ -228,13 +225,13 @@ module Spoom
     # Model
 
     # All the symbols registered in this model
-    sig { returns(T::Hash[String, Symbol]) }
+    #: Hash[String, Symbol]
     attr_reader :symbols
 
-    sig { returns(Poset[Symbol]) }
+    #: Poset[Symbol]
     attr_reader :symbols_hierarchy
 
-    sig { void }
+    #: -> void
     def initialize
       @symbols = T.let({}, T::Hash[String, Symbol])
       @symbols_hierarchy = T.let(Poset[Symbol].new, Poset[Symbol])
@@ -243,7 +240,7 @@ module Spoom
     # Get a symbol by it's full name
     #
     # Raises an error if the symbol is not found
-    sig { params(full_name: String).returns(Symbol) }
+    #: (String full_name) -> Symbol
     def [](full_name)
       symbol = @symbols[full_name]
       raise Error, "Symbol not found: #{full_name}" unless symbol
@@ -254,12 +251,12 @@ module Spoom
     # Register a new symbol by it's full name
     #
     # If the symbol already exists, it will be returned.
-    sig { params(full_name: String).returns(Symbol) }
+    #: (String full_name) -> Symbol
     def register_symbol(full_name)
       @symbols[full_name] ||= Symbol.new(full_name)
     end
 
-    sig { params(full_name: String, context: Symbol).returns(Symbol) }
+    #: (String full_name, context: Symbol) -> Symbol
     def resolve_symbol(full_name, context:)
       if full_name.start_with?("::")
         full_name = full_name.delete_prefix("::")
@@ -280,26 +277,26 @@ module Spoom
       @symbols[full_name] = UnresolvedSymbol.new(full_name)
     end
 
-    sig { params(symbol: Symbol).returns(T::Array[Symbol]) }
+    #: (Symbol symbol) -> Array[Symbol]
     def supertypes(symbol)
       poe = @symbols_hierarchy[symbol]
       poe.ancestors
     end
 
-    sig { params(symbol: Symbol).returns(T::Array[Symbol]) }
+    #: (Symbol symbol) -> Array[Symbol]
     def subtypes(symbol)
       poe = @symbols_hierarchy[symbol]
       poe.descendants
     end
 
-    sig { void }
+    #: -> void
     def finalize!
       compute_symbols_hierarchy!
     end
 
     private
 
-    sig { void }
+    #: -> void
     def compute_symbols_hierarchy!
       @symbols.dup.each do |_full_name, symbol|
         symbol.definitions.each do |definition|

data/lib/spoom/model/namespace_visitor.rb

@@ -8,14 +8,15 @@ module Spoom
 
       abstract!
 
-      sig { void }
+      #: -> void
       def initialize
         super()
 
         @names_nesting = T.let([], T::Array[String])
       end
 
-      sig { override.params(node: T.nilable(Prism::Node)).void }
+      # @override
+      #: (Prism::Node? node) -> void
       def visit(node)
         case node
         when Prism::ClassNode, Prism::ModuleNode

data/lib/spoom/model/reference.rb

@@ -8,8 +8,6 @@ module Spoom
     # Constants could be classes, modules, or actual constants.
     # Methods could be accessors, instance or class methods, aliases, etc.
     class Reference < T::Struct
-      extend T::Sig
-
       class Kind < T::Enum
         enums do
           Constant = new("constant")
@@ -18,14 +16,12 @@ module Spoom
       end
 
       class << self
-        extend T::Sig
-
-        sig { params(name: String, location: Spoom::Location).returns(Reference) }
+        #: (String name, Spoom::Location location) -> Reference
         def constant(name, location)
           new(name: name, kind: Kind::Constant, location: location)
         end
 
-        sig { params(name: String, location: Spoom::Location).returns(Reference) }
+        #: (String name, Spoom::Location location) -> Reference
         def method(name, location)
           new(name: name, kind: Kind::Method, location: location)
         end
@@ -35,12 +31,12 @@ module Spoom
       const :name, String
       const :location, Spoom::Location
 
-      sig { returns(T::Boolean) }
+      #: -> bool
       def constant?
         kind == Kind::Constant
       end
 
-      sig { returns(T::Boolean) }
+      #: -> bool
       def method?
         kind == Kind::Method
       end

data/lib/spoom/model/references_visitor.rb

@@ -5,12 +5,10 @@ module Spoom
   class Model
     # Visit a file to collect all the references to constants and methods
     class ReferencesVisitor < Visitor
-      extend T::Sig
-
-      sig { returns(T::Array[Reference]) }
+      #: Array[Reference]
       attr_reader :references
 
-      sig { params(file: String).void }
+      #: (String file) -> void
       def initialize(file)
         super()
 
@@ -18,18 +16,21 @@ module Spoom
         @references = T.let([], T::Array[Reference])
       end
 
-      sig { override.params(node: Prism::AliasMethodNode).void }
+      # @override
+      #: (Prism::AliasMethodNode node) -> void
       def visit_alias_method_node(node)
         reference_method(node.old_name.slice, node)
       end
 
-      sig { override.params(node: Prism::AndNode).void }
+      # @override
+      #: (Prism::AndNode node) -> void
       def visit_and_node(node)
         reference_method(node.operator_loc.slice, node)
         super
       end
 
-      sig { override.params(node: Prism::BlockArgumentNode).void }
+      # @override
+      #: (Prism::BlockArgumentNode node) -> void
       def visit_block_argument_node(node)
         expression = node.expression
         case expression
@@ -40,7 +41,8 @@ module Spoom
         end
       end
 
-      sig { override.params(node: Prism::CallAndWriteNode).void }
+      # @override
+      #: (Prism::CallAndWriteNode node) -> void
       def visit_call_and_write_node(node)
         visit(node.receiver)
         reference_method(node.read_name.to_s, node)
@@ -48,7 +50,8 @@ module Spoom
         visit(node.value)
       end
 
-      sig { override.params(node: Prism::CallOperatorWriteNode).void }
+      # @override
+      #: (Prism::CallOperatorWriteNode node) -> void
       def visit_call_operator_write_node(node)
         visit(node.receiver)
         reference_method(node.read_name.to_s, node)
@@ -56,7 +59,8 @@ module Spoom
         visit(node.value)
       end
 
-      sig { override.params(node: Prism::CallOrWriteNode).void }
+      # @override
+      #: (Prism::CallOrWriteNode node) -> void
       def visit_call_or_write_node(node)
         visit(node.receiver)
         reference_method(node.read_name.to_s, node)
@@ -64,7 +68,8 @@ module Spoom
         visit(node.value)
       end
 
-      sig { override.params(node: Prism::CallNode).void }
+      # @override
+      #: (Prism::CallNode node) -> void
       def visit_call_node(node)
         visit(node.receiver)
 
@@ -81,53 +86,62 @@ module Spoom
         visit(node.block)
       end
 
-      sig { override.params(node: Prism::ClassNode).void }
+      # @override
+      #: (Prism::ClassNode node) -> void
       def visit_class_node(node)
         visit(node.superclass) if node.superclass
         visit(node.body)
       end
 
-      sig { override.params(node: Prism::ConstantAndWriteNode).void }
+      # @override
+      #: (Prism::ConstantAndWriteNode node) -> void
       def visit_constant_and_write_node(node)
         reference_constant(node.name.to_s, node)
         visit(node.value)
       end
 
-      sig { override.params(node: Prism::ConstantOperatorWriteNode).void }
+      # @override
+      #: (Prism::ConstantOperatorWriteNode node) -> void
       def visit_constant_operator_write_node(node)
         reference_constant(node.name.to_s, node)
         visit(node.value)
       end
 
-      sig { override.params(node: Prism::ConstantOrWriteNode).void }
+      # @override
+      #: (Prism::ConstantOrWriteNode node) -> void
       def visit_constant_or_write_node(node)
         reference_constant(node.name.to_s, node)
         visit(node.value)
       end
 
-      sig { override.params(node: Prism::ConstantPathNode).void }
+      # @override
+      #: (Prism::ConstantPathNode node) -> void
       def visit_constant_path_node(node)
         visit(node.parent)
         reference_constant(node.name.to_s, node)
       end
 
-      sig { override.params(node: Prism::ConstantPathWriteNode).void }
+      # @override
+      #: (Prism::ConstantPathWriteNode node) -> void
       def visit_constant_path_write_node(node)
         visit(node.target.parent)
         visit(node.value)
       end
 
-      sig { override.params(node: Prism::ConstantReadNode).void }
+      # @override
+      #: (Prism::ConstantReadNode node) -> void
       def visit_constant_read_node(node)
         reference_constant(node.name.to_s, node)
       end
 
-      sig { override.params(node: Prism::ConstantWriteNode).void }
+      # @override
+      #: (Prism::ConstantWriteNode node) -> void
       def visit_constant_write_node(node)
         visit(node.value)
       end
 
-      sig { override.params(node: Prism::LocalVariableAndWriteNode).void }
+      # @override
+      #: (Prism::LocalVariableAndWriteNode node) -> void
       def visit_local_variable_and_write_node(node)
         name = node.name.to_s
         reference_method(name, node)
@@ -135,7 +149,8 @@ module Spoom
         visit(node.value)
       end
 
-      sig { override.params(node: Prism::LocalVariableOperatorWriteNode).void }
+      # @override
+      #: (Prism::LocalVariableOperatorWriteNode node) -> void
       def visit_local_variable_operator_write_node(node)
         name = node.name.to_s
         reference_method(name, node)
@@ -143,7 +158,8 @@ module Spoom
         visit(node.value)
       end
 
-      sig { override.params(node: Prism::LocalVariableOrWriteNode).void }
+      # @override
+      #: (Prism::LocalVariableOrWriteNode node) -> void
       def visit_local_variable_or_write_node(node)
         name = node.name.to_s
         reference_method(name, node)
@@ -151,18 +167,21 @@ module Spoom
         visit(node.value)
       end
 
-      sig { override.params(node: Prism::LocalVariableWriteNode).void }
+      # @override
+      #: (Prism::LocalVariableWriteNode node) -> void
       def visit_local_variable_write_node(node)
         reference_method("#{node.name}=", node)
         visit(node.value)
       end
 
-      sig { override.params(node: Prism::ModuleNode).void }
+      # @override
+      #: (Prism::ModuleNode node) -> void
       def visit_module_node(node)
         visit(node.body)
       end
 
-      sig { override.params(node: Prism::MultiWriteNode).void }
+      # @override
+      #: (Prism::MultiWriteNode node) -> void
       def visit_multi_write_node(node)
         node.lefts.each do |const|
           case const
@@ -173,7 +192,8 @@ module Spoom
         visit(node.value)
       end
 
-      sig { override.params(node: Prism::OrNode).void }
+      # @override
+      #: (Prism::OrNode node) -> void
       def visit_or_node(node)
         reference_method(node.operator_loc.slice, node)
         super
@@ -181,17 +201,17 @@ module Spoom
 
       private
 
-      sig { params(name: String, node: Prism::Node).void }
+      #: (String name, Prism::Node node) -> void
       def reference_constant(name, node)
         @references << Reference.constant(name, node_location(node))
       end
 
-      sig { params(name: String, node: Prism::Node).void }
+      #: (String name, Prism::Node node) -> void
       def reference_method(name, node)
         @references << Reference.method(name, node_location(node))
       end
 
-      sig { params(node: Prism::Node).returns(Location) }
+      #: (Prism::Node node) -> Location
       def node_location(node)
         Location.from_prism(@file, node.location)
       end

data/lib/spoom/parse.rb

@@ -7,9 +7,7 @@ module Spoom
   class ParseError < Error; end
 
   class << self
-    extend T::Sig
-
-    sig { params(ruby: String, file: String).returns(Prism::Node) }
+    #: (String ruby, file: String) -> Prism::Node
     def parse_ruby(ruby, file:)
       result = Prism.parse(ruby)
       unless result.success?
@@ -24,5 +22,21 @@ module Spoom
 
       result.value
     end
+
+    #: (String ruby, file: String) -> [Prism::Node, Array[Prism::Comment]]
+    def parse_ruby_with_comments(ruby, file:)
+      result = Prism.parse(ruby)
+      unless result.success?
+        message = +"Error while parsing #{file}:\n"
+
+        result.errors.each do |e|
+          message << "- #{e.message} (at #{e.location.start_line}:#{e.location.start_column})\n"
+        end
+
+        raise ParseError, message
+      end
+
+      [result.value, result.comments]
+    end
   end
 end