parlour 6.0.1 → 7.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55378d16bdfdd7b027be168f8ed8bc0e78a49ba2ec42150692ba4e864c1f12eb
-  data.tar.gz: 21a92ac404908f7c8ea99975ac3be11486d8335ce6b0b0d329b1d3eb70a9c906
+  metadata.gz: cc5c6c8baabe95bbc999a4143264b1dad8b84260bdc156d2a35526244322db2f
+  data.tar.gz: 580430b0cfe37f80b60f9dd47f8673f4d1d973e6ef6abca44efa299355d19fed
 SHA512:
-  metadata.gz: 0cf8085a865e7865b1291b1cfde385cd3d9aff648f06c8ab7ea47d85161cc988faba165bae14bb450a979f27ef6687482105abe9a875781aea41d84a8b3f164e
-  data.tar.gz: 0a660369feb37945261fa7720034d8c48721b03ee1b8b71eaa121fd6f9c72070a20e32360fcba8109cc8dcb10dbeb7f471b24c8d80900ca6938b411756128e61
+  metadata.gz: ae2fd0263a3d955ff7904a28e69bf16eb21b413bda3e71be42636e0829e730a33ee0eb477712fc45dffbce948de3a4c3d6ae6e19147e21b114cd58fe93679676
+  data.tar.gz: 549cd5f91736b8aa5c1f5e1ebaa69fd2d8e4e9f905f1d4aa9ed799677e2d2367a573548d6a9ea220f3c6c6dbf268cc2679c8d0e26516c52224574563974070b6

data/.parlour

@@ -1,5 +1,7 @@
-excluded_paths:
-  - lib/parlour/kernel_hack.rb
+parser:
+  excluded_paths:
+    - lib/parlour/kernel_hack.rb
 
 excluded_modules:
   - Parlour::DetachedRbiGenerator
+  - Parlour::DetachedRbsGenerator

data/CHANGELOG.md

@@ -3,6 +3,24 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [7.0.0] - 2022-04-18
+### Added
+- `#describe` now uses a new, clearer format.
+- Added `#describe_tree`, which produces `#describe` output for a node and all
+  of its children.
+- Added `#find` and `#find_all` for retrieving a node's children based on
+  criteria.
+
+### Changed
+- Parlour now uses the new block-based `type_member` syntax internally.
+  **Potentially breaking** if you pin an older version of Sorbet which doesn't
+  support this syntax!
+- Improved error message when unable to retrieve the file table from Sorbet.
+- `#inspect` and `#to_s` now call `#describe`.
+
+## Fixed
+- Fixed some incorrect YARD documentation tags.
+
 ## [6.0.1] - 2021-02-28
 ### Changed
 - Disabled runtime type checking for `TypedObject#name`, resulting in a

data/exe/parlour

@@ -11,9 +11,8 @@ program :description, 'An RBI generator and plugin system'
 
 default_command :run
 command :run do |c|
-  # TODO: re-add support for flags and figure out how to merge them with .parlour
-  c.syntax = 'parlour run <plugins...> <output-file> [options]'
-  c.description = 'Generates an RBI file from your .parlour file'
+  c.syntax = 'parlour run'
+  c.description = 'Generates a signature file from your .parlour file'
 
   c.action do |args, options|
     working_dir = Dir.pwd

data/lib/parlour/conflict_resolver.rb

@@ -7,6 +7,10 @@ module Parlour
   class ConflictResolver
     extend T::Sig
 
+    def initialize
+      @debugging_tree = Debugging::Tree.new(colour: true)
+    end
+
     sig do
       params(
         namespace: RbiGenerator::Namespace,
@@ -41,7 +45,7 @@ module Parlour
     #   will be kept, or nil to keep none of them.
     # @return [void]
     def resolve_conflicts(namespace, &resolver)
-      Debugging.debug_puts(self, Debugging::Tree.begin("Resolving conflicts for #{namespace.name}..."))
+      Debugging.debug_puts(self, @debugging_tree.begin("Resolving conflicts for #{namespace.name}..."))
 
       # Check for multiple definitions with the same name
       # (Special case here: writer attributes get an "=" appended to their name)
@@ -54,10 +58,10 @@ module Parlour
       end
 
       grouped_by_name_children.each do |name, children|
-        Debugging.debug_puts(self, Debugging::Tree.begin("Checking children named #{name}..."))
+        Debugging.debug_puts(self, @debugging_tree.begin("Checking children named #{name}..."))
 
         if children.length > 1
-          Debugging.debug_puts(self, Debugging::Tree.here("Possible conflict between #{children.length} objects"))
+          Debugging.debug_puts(self, @debugging_tree.here("Possible conflict between #{children.length} objects"))
 
           # Special case: do we have two methods, one of which is a class method
           # and the other isn't? If so, do nothing - this is fine
@@ -65,7 +69,7 @@ module Parlour
             children.all? { |c| c.is_a?(RbiGenerator::Method) } &&
             children.count { |c| T.cast(c, RbiGenerator::Method).class_method } == 1
 
-            Debugging.debug_puts(self, Debugging::Tree.end("One is an instance method and one is a class method; no resolution required"))
+            Debugging.debug_puts(self, @debugging_tree.end("One is an instance method and one is a class method; no resolution required"))
             next
           end
 
@@ -80,7 +84,7 @@ module Parlour
             end
             deduplicate_mixins_of_name(namespace, name)
 
-            Debugging.debug_puts(self, Debugging::Tree.end("Includes/extends do not conflict with namespaces; no resolution required"))
+            Debugging.debug_puts(self, @debugging_tree.end("Includes/extends do not conflict with namespaces; no resolution required"))
             next
           end
 
@@ -90,13 +94,13 @@ module Parlour
             children.all? { |c| c.is_a?(RbiGenerator::Attribute) } &&
             children.count { |c| T.cast(c, RbiGenerator::Attribute).class_attribute } == 1
 
-            Debugging.debug_puts(self, Debugging::Tree.end("One is an instance attribute and one is a class attribute; no resolution required"))
+            Debugging.debug_puts(self, @debugging_tree.end("One is an instance attribute and one is a class attribute; no resolution required"))
             next
           end
 
           # Optimization for Special case: are they all clearly equal? If so, remove all but one
           if all_eql?(children)
-            Debugging.debug_puts(self, Debugging::Tree.end("All children are identical"))
+            Debugging.debug_puts(self, @debugging_tree.end("All children are identical"))
 
             # All of the children are the same, so this deletes all of them
             namespace.children.delete(T.must(children.first))
@@ -116,7 +120,7 @@ module Parlour
           # and get the strategy to use
           strategy = merge_strategy(children)
           unless strategy
-            Debugging.debug_puts(self, Debugging::Tree.end("Children are unmergeable types; requesting manual resolution"))
+            Debugging.debug_puts(self, @debugging_tree.end("Children are unmergeable types; requesting manual resolution"))
             # The types aren't the same, so ask the resolver what to do, and
             # insert that (if not nil)
             choice = resolver.call("Different kinds of definition for the same name", children)
@@ -135,7 +139,7 @@ module Parlour
             # a single method
             if non_namespaces.length != 0
               unless non_namespaces.length == 1 && RbiGenerator::Method === non_namespaces.first
-                Debugging.debug_puts(self, Debugging::Tree.end("Non-namespace item in a differing namespace conflict is not a single method; requesting manual resolution"))
+                Debugging.debug_puts(self, @debugging_tree.end("Non-namespace item in a differing namespace conflict is not a single method; requesting manual resolution"))
                 # The types aren't the same, so ask the resolver what to do, and
                 # insert that (if not nil)
                 choice = resolver.call("Non-namespace item in a differing namespace conflict is not a single method", non_namespaces)
@@ -167,29 +171,29 @@ module Parlour
           # Can the children merge themselves automatically? If so, let them
           first, rest = T.must(first), T.must(rest)
           if T.must(first).mergeable?(T.must(rest))
-            Debugging.debug_puts(self, Debugging::Tree.end("Children are all mergeable; resolving automatically"))
+            Debugging.debug_puts(self, @debugging_tree.end("Children are all mergeable; resolving automatically"))
             first.merge_into_self(rest)
             namespace.children << first
             next
           end
 
           # I give up! Let it be resolved manually somehow
-          Debugging.debug_puts(self, Debugging::Tree.end("Unable to resolve automatically; requesting manual resolution"))
+          Debugging.debug_puts(self, @debugging_tree.end("Unable to resolve automatically; requesting manual resolution"))
           choice = resolver.call("Can't automatically resolve", children)
           namespace.children << choice if choice
         else
-          Debugging.debug_puts(self, Debugging::Tree.end("No conflicts"))
+          Debugging.debug_puts(self, @debugging_tree.end("No conflicts"))
         end
       end
 
-      Debugging.debug_puts(self, Debugging::Tree.here("Resolving children..."))
+      Debugging.debug_puts(self, @debugging_tree.here("Resolving children..."))
 
       # Recurse to child namespaces
       namespace.children.each do |child|
         resolve_conflicts(child, &resolver) if RbiGenerator::Namespace === child
       end
 
-      Debugging.debug_puts(self, Debugging::Tree.end("All children done"))
+      Debugging.debug_puts(self, @debugging_tree.end("All children done"))
     end
 
     private

data/lib/parlour/debugging.rb

@@ -17,7 +17,7 @@ module Parlour
       @debug_mode = value
     end
 
-    # Whether debug messages sent by {#debug_puts} should be printed.
+    # Whether debug messages sent by {.debug_puts} should be printed.
     # Defaults to true if the PARLOUR_DEBUG environment variable is set.
     # @return [Boolean] True if debug messages will be printed, false otherwise.
     sig { returns(T::Boolean) }
@@ -25,11 +25,11 @@ module Parlour
       @debug_mode
     end
 
-    # Prints a message with a debugging prefix to STDOUT if {#debug_mode?} is
+    # Prints a message with a debugging prefix to STDOUT if {.debug_mode?} is
     # true.
-    # @params [Object] object The object which is printing this debug message. 
+    # @param [Object] object The object which is printing this debug message.
     #   Callers should pass +self+.
-    # @params [String] message The message to print. It should not contain
+    # @param [String] message The message to print. It should not contain
     #   newlines.
     # @return [void]
     sig { params(object: T.untyped, message: String).void }
@@ -45,7 +45,7 @@ module Parlour
     # "conflict resolver". If the object type is unknown, this returns its class
     # name.
     # @param [Object] object The object to convert.
-    # @return [String] A string describing the object for {#debug_puts}. 
+    # @return [String] A string describing the object for {.debug_puts}.
     sig { params(object: T.untyped).returns(String) }
     def self.name_for_debug_caller(object)
       case object
@@ -63,24 +63,32 @@ module Parlour
 
     # A module for generating a globally-consistent, nicely-formatted tree of
     # output using Unicode block characters.
-    module Tree
+    class Tree
       extend T::Sig
 
       # The number of spaces to indent each layer of the tree by. Should be at
       # least 1.
       INDENT_SPACES = 2
 
-      # The current indent level of the tree.
-      @indent_level = 0
+      # Whether to colour output or not.
+      sig { returns(T::Boolean) }
+      attr_reader :colour
+
+      sig { params(colour: T::Boolean).void }
+      def initialize(colour: false)
+        @colour = colour
+        @indent_level = 0
+      end
 
       # Returns a new heading, and then decents the tree one level into it. 
       # (That is, future output will go under the new heading.)
       # @param [String] message The heading.
       # @return [String] The line of this tree which should be printed.
       sig { params(message: String).returns(String) }
-      def self.begin(message)
-        result = line_prefix + '├' + text_prefix + Rainbow(message).green.bright.bold
-        @indent_level += 1
+      def begin(message)
+        result = line_prefix + '├' + text_prefix +
+          (colour ? Rainbow(message).green.bright.bold : message)
+        indent!(1)
         result
       end
 
@@ -88,7 +96,7 @@ module Parlour
       # @param [String] message The element.
       # @return [String] The line of this tree which should be printed.
       sig { params(message: String).returns(String) }
-      def self.here(message)
+      def here(message)
         line_prefix + '├' + text_prefix + message
       end
 
@@ -97,16 +105,16 @@ module Parlour
       # @param [String] message The element.
       # @return [String] The line of this tree which should be printed.
       sig { params(message: String).returns(String) }
-      def self.end(message)
+      def end(message)
         result = line_prefix + '└' + text_prefix + message
-        @indent_level = [0, @indent_level - 1].max
+        indent!(-1)
         result
       end
 
       # The prefix which should be printed before anything else on this line of
       # the tree, based on the current indent level.
       # @return [String]
-      def self.line_prefix
+      def line_prefix
         @indent_level.times.map { '│' + ' ' * INDENT_SPACES }.join
       end
 
@@ -114,9 +122,14 @@ module Parlour
       # the current element and its text, based on the specified number of
       # spaces to use for indents.
       # @return [String]
-      def self.text_prefix
+      def text_prefix
         '─' * (INDENT_SPACES - 1) + " "
       end
+
+      # Modifies the current indent level by the given offset.
+      def indent!(offset)
+        @indent_level = [0, @indent_level + offset].max
+      end
     end
   end
 end

data/lib/parlour/mixin/searchable.rb

@@ -0,0 +1,54 @@
+# typed: true
+
+module Parlour
+  module Mixin
+    # Extends a particular type system's Namespace class to provide searchable
+    # children.
+    module Searchable
+      extend T::Sig
+      extend T::Generic
+
+      Child = type_member
+
+      abstract!
+
+      sig { abstract.returns(T::Array[Child]) }
+      def children; end
+
+      sig { params(name: T.nilable(String), type: T.nilable(Class)).returns(Child) }
+      # Finds the first child matching the given predicates.
+      #
+      # @param [String, nil] name The name of the child to filter on, or nil.
+      # @param [Class, nil] type The type of the child to filter on, or nil. The
+      #   type is compared using #is_a?.
+      def find(name: nil, type: nil)
+        T.unsafe(children).find { |c| searchable_child_matches(c, name, type) }
+      end
+
+      sig { params(name: T.nilable(String), type: T.nilable(Class)).returns(T::Array[Child]) }
+      # Finds the first child matching the given predicates.
+      #
+      # @param [String, nil] name The name of the child to filter on, or nil.
+      # @param [Class, nil] type The type of the child to filter on, or nil. The
+      #   type is compared using #is_a?.
+      def find_all(name: nil, type: nil)
+        T.unsafe(children).select { |c| searchable_child_matches(c, name, type) }
+      end
+
+      private
+
+      sig do
+        params(
+          child: Child,
+          name: T.nilable(String),
+          type: T.nilable(Class)
+        )
+        .returns(T::Boolean)
+      end
+      def searchable_child_matches(child, name, type)
+        (name.nil? ? true : child.name == name) \
+        && (type.nil? ? true : child.is_a?(type))
+      end
+    end
+  end
+end

data/lib/parlour/rbi_generator/arbitrary.rb

@@ -80,12 +80,9 @@ module Parlour
         raise 'arbitrary code is never mergeable'
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this code.
-      #
-      # @return [String]
-      def describe
-        "Arbitrary code (#{code})"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [:code]
       end
 
       sig { override.void }

data/lib/parlour/rbi_generator/attribute.rb

@@ -78,6 +78,15 @@ module Parlour
         @type = TypeParser.parse_single_type(@type) if String === @type
       end
 
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [
+          :kind,
+          {type: type}, # avoid quotes
+          :class_attribute
+        ]
+      end
+
       private
 
       sig do

data/lib/parlour/rbi_generator/class_namespace.rb

@@ -5,6 +5,8 @@ module Parlour
     class ClassNamespace < Namespace
       extend T::Sig
 
+      Child = type_member {{ fixed: RbiObject }}
+
       sig do
         params(
           generator: Generator,
@@ -110,13 +112,10 @@ module Parlour
         end
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this class.
-      # @return [String]
-      def describe
-        "Class #{name} - #{"superclass #{superclass}, " if superclass}" +
-          "#{"abstract, " if abstract}#{children.length} children, " +
-          "#{includes.length} includes, #{extends.length} extends"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        (superclass ? [:superclass] : []) \
+          + [:children, :abstract, :final, :sealed]
       end
 
       sig { override.void }

data/lib/parlour/rbi_generator/constant.rb

@@ -95,12 +95,9 @@ module Parlour
         # We don't need to change anything! We only merge identical constants
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this code.
-      #
-      # @return [String]
-      def describe
-        "Constant (#{name} = #{value})"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [:value, :eigen_constant]
       end
 
       sig { override.void }

data/lib/parlour/rbi_generator/enum_class_namespace.rb

@@ -5,6 +5,8 @@ module Parlour
     class EnumClassNamespace < ClassNamespace
       extend T::Sig
 
+      Child = type_member {{ fixed: RbiObject }}
+
       sig do
         params(
           generator: Generator,
@@ -114,6 +116,11 @@ module Parlour
       def generalize_from_rbi!
         super
       end
+
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        super + [{enums: enums.inspect}]
+      end
     end
   end
 end

data/lib/parlour/rbi_generator/extend.rb

@@ -75,16 +75,13 @@ module Parlour
         # We don't need to change anything! We only merge identical extends
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this code.
-      #
-      # @return [String]
-      def describe
-        "Extend (#{name})"
-      end
-
       sig { override.void }
       def generalize_from_rbi!; end # Nothing to do
+
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        []
+      end
     end
   end
 end

data/lib/parlour/rbi_generator/include.rb

@@ -75,16 +75,13 @@ module Parlour
         # We don't need to change anything! We only merge identical includes
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this code.
-      #
-      # @return [String]
-      def describe
-        "Include (#{name})"
-      end
-
       sig { override.void }
       def generalize_from_rbi!; end # Nothing to do
+
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        []
+      end
     end
   end
 end

data/lib/parlour/rbi_generator/method.rb

@@ -206,16 +206,6 @@ module Parlour
         # We don't need to change anything! We only merge identical methods
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this method.
-      #
-      # @return [String]
-      def describe
-        # TODO: more info
-        "Method #{name} - #{parameters.length} parameters, " +
-          " returns #{return_type}"
-      end
-
       sig { override.void }
       def generalize_from_rbi!
         @return_type = TypeParser.parse_single_type(@return_type) if String === @return_type
@@ -223,6 +213,21 @@ module Parlour
         parameters.each(&:generalize_from_rbi!)
       end
 
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        (type_parameters.any? ? [{ type_parameters: type_parameters.join(", ")}] : []) \
+          + [
+            {parameters: "(#{parameters.map(&:describe_in_method).join(", ")})"},
+            {return_type: return_type || '(void)'}, # avoid quotes
+            :class_method,
+            :abstract,
+            :implementation,
+            :override,
+            :overridable,
+            :final,
+          ]
+      end
+
       private
 
       sig do

data/lib/parlour/rbi_generator/module_namespace.rb

@@ -5,6 +5,8 @@ module Parlour
     class ModuleNamespace < Namespace
       extend T::Sig
 
+      Child = type_member {{ fixed: RbiObject }}
+
       sig do
         params(
           generator: Generator,
@@ -100,19 +102,15 @@ module Parlour
         super
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this module.
-      # @return [String]
-      def describe
-        "Module #{name} - #{"interface, " if interface}" +
-          "#{"abstract, " if abstract}#{children.length} " +
-          "children, #{includes.length} includes, #{extends.length} extends"
-      end
-
       sig { override.void }
       def generalize_from_rbi!
         super
       end
+
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [:children, :abstract, :interface, :final, :sealed]
+      end
     end
   end
 end

data/lib/parlour/rbi_generator/namespace.rb

@@ -5,6 +5,7 @@ module Parlour
     # {RbiGenerator#root}.
     class Namespace < RbiObject
       extend T::Sig
+      extend T::Generic
 
       sig do
         override.overridable.params(
@@ -60,11 +61,14 @@ module Parlour
       # @return [Boolean]
       attr_reader :sealed
 
-      sig { returns(T::Array[RbiObject]) }
+      sig { override.returns(T::Array[RbiObject]).checked(:never) }
       # The child {RbiObject} instances inside this namespace.
       # @return [Array<RbiObject>]
       attr_reader :children
 
+      include Mixin::Searchable
+      Child = type_member {{ fixed: RbiObject }}
+
       sig { returns(T::Array[RbiGenerator::Extend]) }
       # The {RbiGenerator::Extend} objects from {children}.
       # @return [Array<RbiGenerator::Extend>]
@@ -647,20 +651,16 @@ module Parlour
         end
       end
 
-      sig { override.overridable.returns(String) }
-      # Returns a human-readable brief string description of this namespace.
-      #
-      # @return [String]
-      def describe
-        "Namespace #{name} - #{children.length} children, #{includes.length} " +
-          "includes, #{extends.length} extends, #{constants.length} constants"
-      end
-
       sig { override.void }
       def generalize_from_rbi!
         children.each(&:generalize_from_rbi!)
       end
 
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [:children, :final, :sealed]
+      end
+
       private
 
       sig do

data/lib/parlour/rbi_generator/parameter.rb

@@ -134,6 +134,18 @@ module Parlour
       def generalize_from_rbi!
         @type = TypeParser.parse_single_type(@type) if String === @type
       end
+
+      sig { returns(String) }
+      def describe_in_method
+        t = type
+        t = t.is_a?(String) ? t : t.describe
+
+        if default
+          "#{name}: #{t} = #{default}"
+        else
+          "#{name}: #{t}"
+        end
+      end
     end
   end
 end

data/lib/parlour/rbi_generator/rbi_object.rb

@@ -69,11 +69,6 @@ module Parlour
       # @return [void]
       def merge_into_self(others); end
 
-      sig { override.overridable.returns(String) }
-      def describe
-        'RBI object'
-      end
-
       sig { abstract.void }
       # Assuming that the types throughout this object and its children have
       # been specified as RBI-style types, generalises them into type instances

data/lib/parlour/rbi_generator/struct_class_namespace.rb

@@ -6,6 +6,8 @@ module Parlour
     class StructClassNamespace < ClassNamespace
       extend T::Sig
 
+      Child = type_member {{ fixed: RbiObject }}
+
       sig do
         params(
           generator: Generator,
@@ -107,6 +109,11 @@ module Parlour
 
         props.each(&:generalize_from_rbi!)
       end
+
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        super + [{props: "(#{props.map(&:name)})"}]
+      end
     end
   end
 end

data/lib/parlour/rbi_generator/type_alias.rb

@@ -84,18 +84,15 @@ module Parlour
         # We don't need to change anything! We only merge identical type alias
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this code.
-      #
-      # @return [String]
-      def describe
-        "Type Alias (#{name} = #{type})"
-      end
-
       sig { override.void }
       def generalize_from_rbi!
         @type = TypeParser.parse_single_type(@type) if String === @type
       end
+
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [{type: type}] # avoid quotes
+      end
     end
   end
 end

data/lib/parlour/rbi_generator.rb

@@ -21,22 +21,7 @@ module Parlour
     #
     # @return [String] The generated RBI file
     def rbi(strictness = 'strong')
-      # TODO: Early test option - convert to RBS if requested
-      # Absolutely remove this later on
-      if ENV['PARLOUR_CONVERT_TO_RBS']
-        # Perform conversion
-        root.generalize_from_rbi!
-        rbs_gen = Parlour::RbsGenerator.new
-        converter = Parlour::Conversion::RbiToRbs.new(rbs_gen)
-        root.children.each do |child|
-          converter.convert_object(child, rbs_gen.root)
-        end
-
-        # Write the final RBS
-        rbs_gen.rbs
-      else
-        "# typed: #{strictness}\n" + root.generate_rbi(0, options).join("\n") + "\n"
-      end
+      "# typed: #{strictness}\n" + root.generate_rbi(0, options).join("\n") + "\n"
     end
   end
 end

data/lib/parlour/rbs_generator/arbitrary.rb

@@ -80,12 +80,9 @@ module Parlour
         raise 'arbitrary code is never mergeable'
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this code.
-      #
-      # @return [String]
-      def describe
-        "Arbitrary code (#{code})"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [:code]
       end
     end
   end

data/lib/parlour/rbs_generator/attribute.rb

@@ -77,6 +77,14 @@ module Parlour
           super(other) && Attribute === other && kind == other.kind
         )
       end
+
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [
+          :kind,
+          :class_attribute
+        ]
+      end
     end
   end
 end

data/lib/parlour/rbs_generator/class_namespace.rb

@@ -5,6 +5,8 @@ module Parlour
     class ClassNamespace < Namespace
       extend T::Sig
 
+      Child = type_member {{ fixed: RbsObject }}
+
       sig do
         params(
           generator: Generator,
@@ -18,10 +20,8 @@ module Parlour
       #
       # @param generator [RbsGenerator] The current RbsGenerator.
       # @param name [String] The name of this class.
-      # @param final [Boolean] Whether this namespace is final.
       # @param superclass [String, nil] The superclass of this class, or nil if it doesn't
       #   have one.
-      # @param abstract [Boolean] A boolean indicating whether this class is abstract.
       # @param block A block which the new instance yields itself to.
       # @return [void]
       def initialize(generator, name, superclass, &block)
@@ -93,13 +93,9 @@ module Parlour
         end
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this class.
-      # @return [String]
-      def describe
-        "Class #{name} - #{"superclass #{superclass}, " if superclass}" +
-          "#{children.length} children, " +
-          "#{includes.length} includes, #{extends.length} extends"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        (superclass ? [:superclass] : []) + [:children]
       end
     end
   end

data/lib/parlour/rbs_generator/constant.rb

@@ -83,12 +83,9 @@ module Parlour
         # We don't need to change anything! We only merge identical constants
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this code.
-      #
-      # @return [String]
-      def describe
-        "Constant (#{name} = #{type})"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [{type: type}] # avoid quotes
       end
     end
   end

data/lib/parlour/rbs_generator/extend.rb

@@ -80,12 +80,9 @@ module Parlour
         # We don't need to change anything! We only merge identical extends
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this code.
-      #
-      # @return [String]
-      def describe
-        "Extend (#{@type})"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [{type: type}] # avoid quotes
       end
     end
   end

data/lib/parlour/rbs_generator/include.rb

@@ -80,12 +80,9 @@ module Parlour
         # We don't need to change anything! We only merge identical includes
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this code.
-      #
-      # @return [String]
-      def describe
-        "Include (#{@type})"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [{type: type}] # avoid quotes
       end
     end
   end

data/lib/parlour/rbs_generator/interface_namespace.rb

@@ -5,6 +5,8 @@ module Parlour
     class InterfaceNamespace < Namespace
       extend T::Sig
 
+      Child = type_member {{ fixed: RbsObject }}
+
       sig do
         override.params(
           indent_level: Integer,
@@ -23,11 +25,9 @@ module Parlour
         lines << options.indented(indent_level, "end")
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this interface.
-      # @return [String]
-      def describe
-        "Interface #{name} - #{children.length}"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [:children]
       end
     end
   end

data/lib/parlour/rbs_generator/method.rb

@@ -133,13 +133,12 @@ module Parlour
         # TODO: merge signatures of different definitions
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this method.
-      #
-      # @return [String]
-      def describe
-        # TODO: more info
-        "Method #{name} - #{signatures.length} signatures"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+          [
+            {signatures: "(#{signatures.map(&:describe_in_method).join(", ")})"},
+            :class_method,
+          ]
       end
     end
   end

data/lib/parlour/rbs_generator/method_signature.rb

@@ -99,6 +99,19 @@ module Parlour
 
         generated_params
       end
+
+      sig { returns(String) }
+      def describe_in_method
+        # RBS is terse enough that just describing using the RBS is probably
+        # fine. (Unfortunately, this doesn't allow any differentiation between 
+        # string types and Parlour::Types types.)
+        # (#describe is supposed to be one line, but this will break if you
+        # have than 10000 parameters. Honestly, if you do have more than 10000
+        # parameters, you deserve this...)
+        generate_rbs(Parlour::Options.new(
+          break_params: 10000, tab_size: 2, sort_namespaces: false
+        )).join("\n")
+      end
     end
   end
 end

data/lib/parlour/rbs_generator/module_namespace.rb

@@ -5,6 +5,8 @@ module Parlour
     class ModuleNamespace < Namespace
       extend T::Sig
 
+      Child = type_member {{ fixed: RbsObject }}
+
       sig do
         override.params(
           indent_level: Integer,
@@ -23,12 +25,9 @@ module Parlour
         lines << options.indented(indent_level, "end")
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this module.
-      # @return [String]
-      def describe
-        "Module #{name} - #{children.length} " +
-          "children, #{includes.length} includes, #{extends.length} extends"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [:children]
       end
     end
   end

data/lib/parlour/rbs_generator/namespace.rb

@@ -5,6 +5,7 @@ module Parlour
     # {RbsGenerator#root}.
     class Namespace < RbsObject
       extend T::Sig
+      extend T::Generic
 
       sig do
         override.overridable.params(
@@ -45,11 +46,14 @@ module Parlour
         yield_self(&block) if block
       end
 
-      sig { returns(T::Array[RbsObject]) }
+      sig { override.returns(T::Array[RbsObject]).checked(:never) }
       # The child {RbsObject} instances inside this namespace.
       # @return [Array<RbsObject>]
       attr_reader :children
 
+      include Mixin::Searchable
+      Child = type_member {{ fixed: RbsObject }}
+
       sig { returns(T::Array[RbsGenerator::Extend]) }
       # The {RbsGenerator::Extend} objects from {children}.
       # @return [Array<RbsGenerator::Extend>]
@@ -517,13 +521,9 @@ module Parlour
         end
       end
 
-      sig { override.overridable.returns(String) }
-      # Returns a human-readable brief string description of this namespace.
-      #
-      # @return [String]
-      def describe
-        "Namespace #{name} - #{children.length} children, #{includes.length} " +
-          "includes, #{extends.length} extends, #{constants.length} constants"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [:children]
       end
 
       private

data/lib/parlour/rbs_generator/rbs_object.rb

@@ -68,11 +68,6 @@ module Parlour
       # @param others [Array<RbsGenerator::RbsObject>] An array of other {RbsObject} instances.
       # @return [void]
       def merge_into_self(others); end
-
-      sig { overridable.override.returns(String) }
-      def describe
-        'RBS object'
-      end  
     end
   end
 end

data/lib/parlour/rbs_generator/type_alias.rb

@@ -84,12 +84,9 @@ module Parlour
         # We don't need to change anything! We only merge identical type alias
       end
 
-      sig { override.returns(String) }
-      # Returns a human-readable brief string description of this code.
-      #
-      # @return [String]
-      def describe
-        "Type Alias (#{name} = #{type})"
+      sig { override.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+      def describe_attrs
+        [{type: type}] # avoid quotes
       end
     end
   end

data/lib/parlour/type_loader.rb

@@ -60,7 +60,12 @@ module Parlour
         chdir: root
       )
 
-      file_table_hash = JSON.parse(T.must(stdout.read))
+      stdout = T.must(stdout.read)
+      if stdout == ''
+        raise 'unable to get Sorbet file table; the project may be empty or not have Sorbet initialised'
+      end
+
+      file_table_hash = JSON.parse(stdout)
       file_table_entries = file_table_hash['files']
 
       namespaces = T.let([], T::Array[Parlour::RbiGenerator::Namespace])

data/lib/parlour/type_parser.rb

@@ -361,8 +361,8 @@ module Parlour
         #   (block (send (const nil :T) :type_alias) (args) (type_to_alias))
         if body.type == :block &&
           body.to_a[0].type == :send &&
-          body.to_a[0].to_a[0].type == :const &&
-          body.to_a[0].to_a[0].to_a == [nil, :T] &&
+          body.to_a[0].to_a[0]&.type == :const &&
+          body.to_a[0].to_a[0]&.to_a == [nil, :T] &&
           body.to_a[0].to_a[1] == :type_alias
 
           [Parlour::RbiGenerator::TypeAlias.new(

data/lib/parlour/typed_object.rb

@@ -57,16 +57,101 @@ module Parlour
 
     alias_method :add_comments, :add_comment
 
-    sig { abstract.returns(String) }
+    sig { returns(String) }
     # Returns a human-readable brief string description of this object. This
     # is displayed during manual conflict resolution with the +parlour+ CLI.
     #
-    # @abstract
     # @return [String]
-    def describe; end
+    def describe
+      if is_a?(RbiGenerator::RbiObject)
+        type_system = 'RBI'
+      elsif is_a?(RbsGenerator::RbsObject)
+        type_system = 'RBS'
+      else
+        raise 'unknown type system'
+      end
+
+      attr_strings = describe_attrs.map do |a|
+        case a
+        when Symbol
+          key = a
+          value = send(a)
+
+          case value
+          when Array, Hash
+            value = value.length
+            next nil if value == 0
+          when String
+            value = value.inspect
+          when Parlour::Types::Type
+            value = value.describe
+          when true
+            next key
+          when false
+            next nil
+          end
+        when Hash
+          raise 'describe_attrs Hash must have one key' unless a.length == 1
+
+          key = a.keys[0]
+          value = a.values[0]
+        end
+
+        "#{key}=#{value}"
+      end.compact
+
+      class_name = T.must(self.class.name).split('::').last
+      if attr_strings.empty?
+        "<#{type_system}:#{class_name}:#{name}>"
+      else
+        "<#{type_system}:#{class_name}:#{name} #{attr_strings.join(" ")}>"
+      end
+    end
+
+    sig { params(tree: T.nilable(Debugging::Tree)).returns(String) }
+    # Returns a human-readable multi-line string description of this object and
+    # its children recursively.
+    #
+    # @return [String]
+    def describe_tree(tree: nil)
+      if tree.nil?
+        tree = Debugging::Tree.new
+        result = "#{describe}\n"
+      else
+        result = ""
+      end
+
+      if is_a?(RbiGenerator::Namespace) || is_a?(RbsGenerator::Namespace)
+        children.each do |child|
+          result += "#{tree.begin(child.describe)}\n"
+          result += child.describe_tree(tree: tree)
+          tree.indent!(-1)
+        end
+      else
+        "#{describe}\n"
+      end
+
+      result
+    end
+
+    alias inspect describe
+    alias to_s describe
     
     protected
 
+    sig { abstract.returns(T::Array[T.any(Symbol, T::Hash[Symbol, String])]) }
+    # The attributes for an instance of this object which should be included in
+    # its string form generated by +#describe+.
+    # For each element in the returned array:
+    #   - If it is a symbol, this symbol will be called on +self+ and the
+    #     returned object will be dynamically converted into a string.
+    #   - If it is a hash, it must be of the format { Symbol => String }. The
+    #     given string will be used instead of calling the symbol.
+    #
+    # @abstract
+    # @return [<Symbol, String>]
+    def describe_attrs; end
+
     sig do
       params(
         indent_level: Integer,

data/lib/parlour/version.rb

@@ -1,5 +1,5 @@
 # typed: strong
 module Parlour
   # The library version.
-  VERSION = '6.0.1'
+  VERSION = '7.0.0'
 end

data/lib/parlour.rb

@@ -14,6 +14,8 @@ require 'parlour/types'
 require 'parlour/options'
 require 'parlour/typed_object'
 require 'parlour/generator'
+require 'parlour/mixin/searchable'
+
 require 'parlour/rbi_generator/parameter'
 require 'parlour/rbi_generator/rbi_object'
 require 'parlour/rbi_generator/type_alias'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parlour
 version: !ruby/object:Gem::Version
-  version: 6.0.1
+  version: 7.0.0
 platform: ruby
 authors:
 - Aaron Christiansen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-07-05 00:00:00.000000000 Z
+date: 2022-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
@@ -181,6 +181,7 @@ files:
 - lib/parlour/detached_rbs_generator.rb
 - lib/parlour/generator.rb
 - lib/parlour/kernel_hack.rb
+- lib/parlour/mixin/searchable.rb
 - lib/parlour/options.rb
 - lib/parlour/parse_error.rb
 - lib/parlour/plugin.rb
@@ -242,7 +243,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.0.rc.1
+rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
 summary: A type information generator, merger and parser for Sorbet and Ruby 3/Steep