parlour 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f603ddca16331f43a36b4120b7d12aa5a4b7c83f753e8527b91bc1391109e9fe
-  data.tar.gz: f550cdf4cc358dd6ac0c21853ad26756d4729c7f28f3695af53d25775b3f45f0
+  metadata.gz: 382331994bebd14df33b96b084d725b0375fa84e0a3aa263e944bad22bb5ef3f
+  data.tar.gz: 33b9014173a85bc6dddec5aa3ad38cc7e23d869636694fbbe96d4e07c7e78886
 SHA512:
-  metadata.gz: a962191c42becbe6dbe213eb63be142df100643786006093e5663af51f80049890c26ff8974b718cfd89198387cf0ec801b8d3e10cbf032aaf3aa86f746fda97
-  data.tar.gz: 1bfafd7afbcf81105379d7b747e0c204e47fdd593b0b1a67e659275b0ebd8d236753e48b5bc05896e1e1759ac6495ad3e8132f85a497f28b35c436ddb3cb1585
+  metadata.gz: 6ecd35a473c689909a7ef3b84af799cfa718b1901929743676c557d95f6dd717b3c9cd60dcec1c4274ce1ecc4e69310aa3213505c6f3ef479cfa580ccb39f187
+  data.tar.gz: 7dddda7cb3a9d123e74f0ed218d62b17697f63451b7389d6d5c92bb4712d41b1cc920380eb8ee3b84c7916be5ad8c32c5d2bb0f3b46c7828acefa45fa0581683

data/.gitignore

@@ -8,6 +8,7 @@
 /tmp/
 Gemfile.lock
 /.vscode
+/sorbte/rbi/hidden-definitions/errors.txt
 
 # rspec failure tracking
 .rspec_status

data/.travis.yml

@@ -8,6 +8,7 @@ rvm:
   - 2.4
   - 2.5
   - 2.6
+  - 2.7
   - ruby-head
 matrix:
   allow_failures:

data/CHANGELOG.md

@@ -3,6 +3,31 @@ 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/).
 
+## [2.0.0] - 2020-02-10
+### Added
+- Parlour can now load types back out of RBI files or Ruby source files by
+parsing them, using the `TypeLoader` module.
+- The `sort_namespaces` option has been added to `RbiGenerator` to
+alphabetically sort all namespace children.
+- Added `DetachedRbiGenerator`, which can be used to create instances of 
+`RbiObject` which are not bound to a particular set of options. This is
+used internally for `TypeLoader`.
+- Parlour will now create a polyfill for `then` on `Kernel`.
+- Added `NodePath#sibling`.
+
+### Changed
+- Version restrictions on _rainbow_ and _commander_ have been slightly relaxed.
+- The version of _sorbet-runtime_ is now restricted to `>= 0.5` after previously
+being unrestricted.
+- Instances of `Namespace` can now be merged with instances of `ClassNamespace`
+or `MethodNamespace`.
+- A method and a namespace can now have the same name without causing a merge
+conflict.
+
+### Fixed
+- Parameter names are no longer nilable.
+**Potentially breaking if you were doing something cursed with Parameter names.**
+
 ## [1.0.0] - 2019-11-22
 ### Added
 - `T::Enum` classes have been implemented, and can be generated using

data/README.md

@@ -3,7 +3,8 @@
 [![Build Status](https://travis-ci.org/AaronC81/parlour.svg?branch=master)](https://travis-ci.org/AaronC81/parlour)
 ![Gem](https://img.shields.io/gem/v/parlour.svg)
 
-Parlour is an RBI generator and merger for Sorbet. It consists of two key parts:
+Parlour is an RBI generator, merger and parser for Sorbet. It consists of three
+key parts:
 
   - The generator, which outputs beautifully formatted RBI files, created using
     an intuitive DSL.
@@ -12,6 +13,9 @@ Parlour is an RBI generator and merger for Sorbet. It consists of two key parts:
     RBIs for the same codebase. These are combined automatically as much as
     possible, but any other conflicts can be resolved manually through prompts.
 
+  - The parser, which can read an RBI and convert it back into a tree of 
+    generator objects.
+
 ## Why should I use this?
 
   - Parlour enables **much easier creation of RBI generators**, as formatting
@@ -21,6 +25,8 @@ Parlour is an RBI generator and merger for Sorbet. It consists of two key parts:
     single command and consolidating all of their definitions into a single
     RBI output file.
 
+  - You can **effortlessly build tools which need to access types within an RBI**;
+    no need to write your own parser! 
 
 Please [**read the wiki**](https://github.com/AaronC81/parlour/wiki) to get
 started!
@@ -147,6 +153,27 @@ plugins:
   Gem3::Plugin: {}
 ```
 
+## Parsing RBIs
+
+You can either parse individual RBI files, or point Parlour to the root of a
+project and it will locate, parse and merge all RBI files.
+
+Note that Parlour isn't limited to just RBIs; it can parse inline `sigs` out
+of your Ruby source too!
+
+```ruby
+require 'parlour'
+
+# Return the object tree of a particular file
+Parlour::TypeLoader.load_file('path/to/your/file.rbis')
+
+# Return the object tree for an entire Sorbet project - slow but thorough!
+Parlour::TypeLoader.load_project('root/of/the/project')
+```
+
+The structure of the returned object trees is identical to those you would
+create when generating an RBI, built of instances of `RbiObject` subclasses.
+
 ## Parlour Plugins
 
 _Have you written an awesome Parlour plugin? Please submit a PR to add it to this list!_

data/lib/parlour.rb

@@ -23,5 +23,10 @@ require 'parlour/rbi_generator/module_namespace'
 require 'parlour/rbi_generator/class_namespace'
 require 'parlour/rbi_generator/enum_class_namespace'
 require 'parlour/rbi_generator'
+require 'parlour/detached_rbi_generator'
 
 require 'parlour/conflict_resolver'
+
+require 'parlour/parse_error'
+require 'parlour/type_parser'
+require 'parlour/type_loader'

data/lib/parlour/conflict_resolver.rb

@@ -88,11 +88,11 @@ module Parlour
             namespace.children.delete(c)
           end
 
-          # We can only try to resolve automatically if they're all the same 
-          # type of object, so check that first
-          children_type = single_type_of_array(children)
-          unless children_type
-            Debugging.debug_puts(self, Debugging::Tree.end("Children are different types; requesting manual resolution"))
+          # Check that the types of the given objects allow them to be merged,
+          # 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"))
             # 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)
@@ -100,8 +100,36 @@ module Parlour
             next
           end
 
+          case strategy
+          when :normal
+            first, *rest = children
+          when :differing_namespaces
+            # Let the namespaces be merged normally, but handle the method here
+            namespaces, non_namespaces = children.partition { |x| RbiGenerator::Namespace === x }
+
+            # If there is any non-namespace item in this conflict, it should be
+            # 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"))
+                # 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)
+                non_namespaces = []
+                non_namespaces << choice if choice
+              end 
+            end
+
+            non_namespaces.each do |x|
+              namespace.children << x
+            end
+
+            first, *rest = namespaces
+          else
+            raise 'unknown merge strategy; this is a Parlour bug'
+          end
+
           # Can the children merge themselves automatically? If so, let them
-          first, *rest = children
           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"))
@@ -131,15 +159,49 @@ module Parlour
 
     private
 
-    sig { params(arr: T::Array[T.untyped]).returns(T.nilable(Class)) }
+    sig { params(arr: T::Array[T.untyped]).returns(T.nilable(Symbol)) }
     # Given an array, if all elements in the array are instances of the exact
-    # same class, returns that class. If they are not, returns nil.
+    # same class or are otherwise mergeable (for example Namespace and 
+    # ClassNamespace), returns the kind of merge which needs to be made. A
+    # return value of nil indicates that the values cannot be merged.
+    #
+    # The following kinds are available:
+    #   - They are all the same. (:normal)
+    #   - There are exactly two types, one of which is Namespace and other is a 
+    #     subclass of it. (:differing_namespaces)
+    #   - One of them is Namespace or a subclass (or both, as described above),
+    #     and the only other is Method. (also :differing_namespaces) 
     #
     # @param arr [Array] The array.
-    # @return [Class, nil] Either a class, or nil.
-    def single_type_of_array(arr)
+    # @return [Symbol] The merge strategy to use, or nil if they can't be
+    #   merged.
+    def merge_strategy(arr)
+      # If they're all the same type, they can be merged easily
       array_types = arr.map { |c| c.class }.uniq
-      array_types.length == 1 ? array_types.first : nil
+      return :normal if array_types.length == 1
+
+      # Find all the namespaces and non-namespaces
+      namespace_types, non_namespace_types = array_types.partition { |x| x <= RbiGenerator::Namespace }
+
+      # If there are two namespace types, one should be Namespace and the other
+      # should be a subclass of it
+      if namespace_types.length == 2
+        exactly_namespace, exactly_one_subclass = namespace_types.partition { |x| x == RbiGenerator::Namespace }
+
+        return nil unless exactly_namespace.length == 1 \
+          && exactly_one_subclass.length == 1 \
+          && exactly_one_subclass.first < RbiGenerator::Namespace
+      elsif namespace_types.length != 1
+        # The only other valid number of namespaces is 1, where we don't need to
+        # check anything
+        return nil
+      end
+      
+      # It's OK, albeit cursed, for there to be a method with the same name as
+      # a namespace (Rainbow does this)
+      return nil if non_namespace_types.length != 0 && non_namespace_types != [RbiGenerator::Method]
+
+      :differing_namespaces
     end
 
     sig { params(arr: T::Array[T.untyped]).returns(T::Boolean) }

data/lib/parlour/detached_rbi_generator.rb

@@ -0,0 +1,30 @@
+# typed: true
+
+module Parlour
+  class DetachedRbiGenerator < RbiGenerator
+    sig { returns(T.untyped) }
+    def detached!
+      raise "cannot call methods on a detached RBI generator"
+    end
+  
+    sig { override.returns(Options) }
+    def options
+      detached!
+    end
+
+    sig { override.returns(Namespace) }
+    def root
+      detached!
+    end
+
+    sig { override.returns(T.nilable(Plugin)) }
+    def current_plugin
+      nil
+    end
+
+    sig { override.params(strictness: String).returns(String) }
+    def rbi(strictness = 'strong')
+      detached!
+    end
+  end
+end

data/lib/parlour/kernel_hack.rb

@@ -3,4 +3,6 @@ module Kernel
     return to_enum(__method__) { 1 } unless block_given?
     yield self
   end unless method_defined? :yield_self
+
+  alias then yield_self
 end

data/lib/parlour/parse_error.rb

@@ -0,0 +1,19 @@
+# typed: true
+
+module Parlour
+  class ParseError < StandardError
+    extend T::Sig
+
+    sig { returns(Parser::Source::Buffer) }
+    attr_reader :buffer
+
+    sig { returns(Parser::Source::Range) }
+    attr_reader :range
+
+    def initialize(buffer, range)
+      super()
+      @buffer = buffer
+      @range = range
+    end
+  end
+end

data/lib/parlour/rbi_generator.rb

@@ -4,7 +4,7 @@ module Parlour
   class RbiGenerator
     extend T::Sig
 
-    sig { params(break_params: Integer, tab_size: Integer).void }
+    sig { params(break_params: Integer, tab_size: Integer, sort_namespaces: T::Boolean).void }
     # Creates a new RBI generator.
     #
     # @example Create a default generator.
@@ -16,29 +16,35 @@ module Parlour
     # @param break_params [Integer] If there are at least this many parameters in a 
     #   Sorbet +sig+, then it is broken onto separate lines.
     # @param tab_size [Integer] The number of spaces to use per indent.
+    # @param sort_namespaces [Boolean] Whether to sort all items within a
+    #   namespace alphabetically.
     # @return [void]
-    def initialize(break_params: 4, tab_size: 2)
-      @options = Options.new(break_params: break_params, tab_size: tab_size)
+    def initialize(break_params: 4, tab_size: 2, sort_namespaces: false)
+      @options = Options.new(
+        break_params: break_params,
+        tab_size: tab_size,
+        sort_namespaces: sort_namespaces
+      )
       @root = Namespace.new(self)
     end
 
-    sig { returns(Options) }
+    sig { overridable.returns(Options) }
     # The formatting options for this generator.
     # @return [Options]
     attr_reader :options
 
-    sig { returns(Namespace) }
+    sig { overridable.returns(Namespace) }
     # The root {Namespace} of this generator.
     # @return [Namespace]
     attr_reader :root
 
-    sig { returns(T.nilable(Plugin)) }
+    sig { overridable.returns(T.nilable(Plugin)) }
     # The plugin which is currently generating new definitions.
     # {Plugin#run_plugins} controls this value.
     # @return [Plugin, nil]
     attr_accessor :current_plugin
 
-    sig { params(strictness: String).returns(String) }
+    sig { overridable.params(strictness: String).returns(String) }
     # Returns the complete contents of the generated RBI file as a string.
     #
     # @return [String] The generated RBI file

data/lib/parlour/rbi_generator/class_namespace.rb

@@ -70,19 +70,21 @@ module Parlour
           others: T::Array[RbiGenerator::RbiObject]
         ).returns(T::Boolean)
       end
-      # Given an array of {ClassNamespace} instances, returns true if they may
+      # Given an array of {Namespace} instances, returns true if they may
       # be merged into this instance using {merge_into_self}. For instances to
       # be mergeable, they must either all be abstract or all not be abstract,
       # and they must define the same superclass (or none at all).
       #
-      # @param others [Array<RbiGenerator::RbiObject>] An array of other {ClassNamespace} instances.
+      # @param others [Array<RbiGenerator::RbiObject>] An array of other {Namespace} instances.
       # @return [Boolean] Whether this instance may be merged with them.
       def mergeable?(others)
-        others = T.cast(others, T::Array[ClassNamespace]) rescue (return false)
+        others = T.cast(others, T::Array[Namespace]) rescue (return false)
         all = others + [self]
 
-        all.map(&:abstract).uniq.length == 1 &&
-          all.map(&:superclass).compact.uniq.length <= 1
+        all_classes = T.cast(all.select { |x| ClassNamespace === x }, T::Array[ClassNamespace])
+
+        all_classes.map(&:abstract).uniq.length == 1 &&
+          all_classes.map(&:superclass).compact.uniq.length <= 1
       end
 
       sig do 
@@ -99,6 +101,7 @@ module Parlour
         super
 
         others.each do |other|
+          next unless ClassNamespace === other
           other = T.cast(other, ClassNamespace)
 
           @superclass = other.superclass unless superclass

data/lib/parlour/rbi_generator/module_namespace.rb

@@ -59,18 +59,20 @@ module Parlour
           others: T::Array[RbiGenerator::RbiObject]
         ).returns(T::Boolean)
       end
-      # Given an array of {ModuleNamespace} instances, returns true if they may
+      # Given an array of {Namespace} instances, returns true if they may
       # be merged into this instance using {merge_into_self}. For instances to
       # be mergeable, they must either all be interfaces or all not be 
       # interfaces.
       #
-      # @param others [Array<RbiGenerator::RbiObject>] An array of other {ModuleNamespace} instances.
+      # @param others [Array<RbiGenerator::RbiObject>] An array of other {Namespace} instances.
       # @return [Boolean] Whether this instance may be merged with them.
       def mergeable?(others)
-        others = T.cast(others, T::Array[RbiGenerator::ModuleNamespace]) rescue (return false)
+        others = T.cast(others, T::Array[Namespace]) rescue (return false)
         all = others + [self]
 
-        all.map(&:interface).uniq.length == 1
+        all_modules = T.cast(all.select { |x| ModuleNamespace === x }, T::Array[ModuleNamespace])
+
+        all_modules.map(&:interface).uniq.length == 1
       end
 
       sig do 

data/lib/parlour/rbi_generator/namespace.rb

@@ -559,11 +559,15 @@ module Parlour
       # Given an array of {Namespace} instances, merges them into this one.
       # All children, constants, extends and includes are copied into this 
       # instance.
+      #
+      # There may also be {RbiGenerator::Method} instances in the stream, which
+      # are ignored.
       # 
       # @param others [Array<RbiGenerator::RbiObject>] An array of other {Namespace} instances.
       # @return [void]
       def merge_into_self(others)
         others.each do |other|
+          next if other.is_a?(RbiGenerator::Method)
           other = T.cast(other, Namespace)
 
           other.children.each { |c| children << c }
@@ -599,22 +603,23 @@ module Parlour
         result += [options.indented(indent_level, 'final!'), ''] if final
 
         if includes.any? || extends.any? || constants.any?
-          result += includes
+          result += (options.sort_namespaces ? includes.sort_by(&:name) : includes)
             .flat_map { |x| x.generate_rbi(indent_level, options) }
             .reject { |x| x.strip == '' }
-          result += extends
+          result += (options.sort_namespaces ? extends.sort_by(&:name) : extends)
             .flat_map { |x| x.generate_rbi(indent_level, options) }
             .reject { |x| x.strip == '' }
-          result += constants
+          result += (options.sort_namespaces ? constants.sort_by(&:name) : constants)
             .flat_map { |x| x.generate_rbi(indent_level, options) }
             .reject { |x| x.strip == '' }
           result << ""
         end
 
         # Process singleton class attributes
-        class_attributes, remaining_children = children.partition do |child|
-          child.is_a?(Attribute) && child.class_attribute
-        end
+        class_attributes, remaining_children = \
+          (options.sort_namespaces ? children.sort_by(&:name) : children)
+          .partition { |child| child.is_a?(Attribute) && child.class_attribute }
+        
         if class_attributes.any?
           result << options.indented(indent_level, 'class << self')