parlour 1.0.0 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f603ddca16331f43a36b4120b7d12aa5a4b7c83f753e8527b91bc1391109e9fe
-  data.tar.gz: f550cdf4cc358dd6ac0c21853ad26756d4729c7f28f3695af53d25775b3f45f0
+  metadata.gz: 707934b89fd83fbb876582bd7e66679bc2f8cf2179961eed62358ba6266bf524
+  data.tar.gz: 3d0a0c8be95e09275a9b02232ce9b9b062a9f00eb3216a0e74ce63a036025d76
 SHA512:
-  metadata.gz: a962191c42becbe6dbe213eb63be142df100643786006093e5663af51f80049890c26ff8974b718cfd89198387cf0ec801b8d3e10cbf032aaf3aa86f746fda97
-  data.tar.gz: 1bfafd7afbcf81105379d7b747e0c204e47fdd593b0b1a67e659275b0ebd8d236753e48b5bc05896e1e1759ac6495ad3e8132f85a497f28b35c436ddb3cb1585
+  metadata.gz: ae723cbe6bebbba12ee3d802b223fa91fcda085f6b1fce4ec107efa3f9e3cc5df53ee0269a6e9d1391ff32c903d15b72153c67fae61392b7e5495688b69b7b0a
+  data.tar.gz: 98626719eb9d2c08f7e87c1ae48933d8b1afb9badab000bb408a8df26c57716846b71278654193c821ce59a552c83456d1f61523ce5bd9ff0e52d296ab34e274

data/.gitignore

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

data/.parlour

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

data/.travis.yml

@@ -8,10 +8,8 @@ rvm:
   - 2.4
   - 2.5
   - 2.6
+  - 2.7
   - ruby-head
-matrix:
-  allow_failures:
-    - rvm: ruby-head
 
 jobs:
   include:
@@ -25,3 +23,6 @@ jobs:
         keep_history: true
         on:
           branch: master
+  allow_failures:
+    - rvm: 2.3
+    - rvm: ruby-head

data/CHANGELOG.md

@@ -3,6 +3,71 @@ 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/).
 
+## [4.0.1] - 2020-08-05
+### Fixed
+- Fixed duplicate includes and extends.
+- Fixed the block return type for `#resolve_conflicts` not being nilable.
+
+## [4.0.0] - 2020-05-23
+### Added
+- Parlour now defaults to loading the current project when running its command
+  line tool, allowing it to be used as a "`sig` extractor" when run without
+  plugins! **Breaking if you invoke Parlour from its command line tool** - to
+  revert to the old behaviour of having nothing loaded into the root namespace
+  initially, add `parser: false` to your `.parlour` file.
+- Generating constants in an eigenclass context (`class << self`) is now
+  supported.
+
+## [3.0.0] - 2020-05-15
+### Added
+- `T::Struct` classes can now be generated and parsed.
+- `T::Enum` classes can now be parsed.
+- Constants are now parsed.
+- `TypeParser` now detects and parses methods which do not have a `sig`.
+  **Potentially breaking if there is a strict set of methods you are expecting Parlour to detect.**
+
+### Fixed
+- "Specialized" classes, such as enums and now structs, have had many erroneous
+  conflicts with standard classes or namespaces fixed.
+- Attributes writers and methods with the same name no longer conflict incorrectly.
+
+## [2.1.0] - 2020-03-22
+### Added
+- Files can now be excluded from the `TypeLoader`.
+
+### Changed
+- A block argument in the definition but not in the signature no longer causes
+an error in the `TypeParser`.
+- Sorting of namespace children is now a stable sort.
+
+### Fixed
+- Type parameters are now parsed by the `TypeParser`.
+
+## [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,11 @@ 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!
+
+  - You can **generate RBI to ship with your gem** for consuming projects to use
+    ([see "RBIs within gems" in Sorbet's docs](https://sorbet.org/docs/rbi#rbis-within-gems)).
 
 Please [**read the wiki**](https://github.com/AaronC81/parlour/wiki) to get
 started!
@@ -147,6 +156,50 @@ 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.
+
+## Generating RBI for a Gem
+
+Include `parlour` as a development_dependency in your `.gemspec`:
+
+```ruby
+spec.add_development_dependency 'parlour'
+```
+
+Run Parlour from the command line:
+
+```ruby
+bundle exec parlour
+```
+
+Parlour is configured to use sane defaults assuming a standard gem structure
+to generate an RBI that Sorbet will automatically find when your gem is included
+as a dependency. If you require more advanced configuration you can add a
+`.parlour` YAML file in the root of your project (see this project's `.parlour`
+file as an example).
+
+To disable the parsing step entire and just run plugins you can set `parser: false`
+in your `.parlour` file.
+
 ## Parlour Plugins
 
 _Have you written an awesome Parlour plugin? Please submit a PR to add it to this list!_

data/exe/parlour

@@ -16,15 +16,42 @@ command :run do |c|
   c.description = 'Generates an RBI file from your .parlour file'
 
   c.action do |args, options|
-    configuration = keys_to_symbols(YAML.load_file(File.join(Dir.pwd, '.parlour')))
+    working_dir = Dir.pwd
+    config_filename = File.join(working_dir, '.parlour')
 
-    raise 'you must specify output_file in your .parlour file' unless configuration[:output_file]
+    if File.exists?(config_filename)
+      configuration = keys_to_symbols(YAML.load_file(config_filename))
+    else
+      configuration = {}
+    end
+
+    # Output default
+    configuration[:output_file] ||= "rbi/#{File.basename(working_dir)}.rbi"
 
     # Style defaults
     configuration[:style] ||= {}
     configuration[:style][:tab_size] ||= 2
     configuration[:style][:break_params] ||= 4
 
+    # Parser defaults, set explicitly to false to not run parser
+    if configuration[:parser] != false
+      configuration[:parser] ||= {}
+
+      # Input/Output defaults
+      configuration[:parser][:root] ||= '.'
+
+      # Included/Excluded path defaults
+      configuration[:parser][:included_paths] ||= ['lib']
+      configuration[:parser][:excluded_paths] ||= ['sorbet', 'spec']
+
+      # Defaults can be overridden but we always want to exclude the output file
+      configuration[:parser][:excluded_paths] << configuration[:output_file]
+    end
+
+    # Included/Excluded module defaults
+    configuration[:included_modules] ||= []
+    configuration[:excluded_modules] ||= []
+
     # Require defaults
     configuration[:requires] ||= []
     configuration[:relative_requires] ||= []
@@ -53,6 +80,15 @@ command :run do |c|
       break_params: configuration[:style][:break_params],
       tab_size: configuration[:style][:tab_size]
     )
+
+    if configuration[:parser]
+      Parlour::TypeLoader.load_project(
+        configuration[:parser][:root],
+        inclusions: configuration[:parser][:included_paths],
+        exclusions: configuration[:parser][:excluded_paths],
+        generator: gen,
+      )
+    end
     Parlour::Plugin.run_plugins(plugin_instances, gen)
 
     # Run a pass of the conflict resolver
@@ -74,6 +110,14 @@ command :run do |c|
       choice == 0 ? nil : candidates[choice - 1]
     end
 
+    if !configuration[:included_modules].empty? || !configuration[:excluded_modules].empty?
+      remove_unwanted_modules(
+        gen.root,
+        included_modules: configuration[:included_modules],
+        excluded_modules: configuration[:excluded_modules],
+      )
+    end
+
     # Figure out strictness levels
     requested_strictness_levels = plugin_instances.map do |plugin|
       s = plugin.strictness&.to_s
@@ -98,6 +142,7 @@ command :run do |c|
     end
 
     # Write the final RBI
+    FileUtils.mkdir_p(File.dirname(configuration[:output_file]))
     File.write(configuration[:output_file], gen.rbi(strictness))
   end
 end
@@ -122,3 +167,24 @@ def keys_to_symbols(hash)
     ]
   end.to_h
 end
+
+def remove_unwanted_modules(root, included_modules:, excluded_modules:, prefix: nil)
+  root.children.select! do |child|
+    module_name = "#{prefix}#{child.name}"
+
+    if child.respond_to?(:children)
+      remove_unwanted_modules(
+        child,
+        included_modules: included_modules,
+        excluded_modules: excluded_modules,
+        prefix: "#{module_name}::",
+      )
+      has_included_children = !child.children.empty?
+    end
+
+    included = included_modules.empty? ? true : included_modules.any? { |m| module_name.start_with?(m) }
+    excluded = excluded_modules.empty? ? false : excluded_modules.any? { |m| module_name.start_with?(m) }
+
+    (included || has_included_children) && !excluded
+  end
+end

data/lib/parlour.rb

@@ -22,6 +22,13 @@ require 'parlour/rbi_generator/namespace'
 require 'parlour/rbi_generator/module_namespace'
 require 'parlour/rbi_generator/class_namespace'
 require 'parlour/rbi_generator/enum_class_namespace'
+require 'parlour/rbi_generator/struct_prop'
+require 'parlour/rbi_generator/struct_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

@@ -1,4 +1,6 @@
 # typed: true
+require 'set'
+
 module Parlour
   # Responsible for resolving conflicts (that is, multiple definitions with the
   # same name) between objects defined in the same namespace.
@@ -11,7 +13,7 @@ module Parlour
         resolver: T.proc.params(
           desc: String,
           choices: T::Array[RbiGenerator::RbiObject]
-        ).returns(RbiGenerator::RbiObject)
+        ).returns(T.nilable(RbiGenerator::RbiObject))
       ).void
     end
     # Given a namespace, attempts to automatically resolve conflicts in the
@@ -21,13 +23,13 @@ module Parlour
     # All children of the given namespace which are also namespaces are
     # processed recursively, so passing {RbiGenerator#root} will eliminate all
     # conflicts in the entire object tree.
-    # 
+    #
     # If automatic resolution is not possible, the block passed to this method
     # is invoked and passed two arguments: a message on what the conflict is,
     # and an array of candidate objects. The block should return one of these
     # candidate objects, which will be kept, and all other definitions are
     # deleted. Alternatively, the block may return nil, which will delete all
-    # definitions. The block may be invoked many times from one call to 
+    # definitions. The block may be invoked many times from one call to
     # {resolve_conflicts}, one for each unresolvable conflict.
     #
     # @param namespace [RbiGenerator::Namespace] The starting namespace to
@@ -42,7 +44,14 @@ module Parlour
       Debugging.debug_puts(self, Debugging::Tree.begin("Resolving conflicts for #{namespace.name}..."))
 
       # Check for multiple definitions with the same name
-      grouped_by_name_children = namespace.children.group_by(&:name)
+      # (Special case here: writer attributes get an "=" appended to their name)
+      grouped_by_name_children = namespace.children.group_by do |child|
+        if RbiGenerator::Attribute === child && child.kind == :writer
+          "#{child.name}=" unless child.name.end_with?('=')
+        else
+          child.name
+        end
+      end
 
       grouped_by_name_children.each do |name, children|
         Debugging.debug_puts(self, Debugging::Tree.begin("Checking children named #{name}..."))
@@ -50,7 +59,7 @@ module Parlour
         if children.length > 1
           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 
+          # 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
           if children.length == 2 &&
             children.all? { |c| c.is_a?(RbiGenerator::Method) } &&
@@ -60,7 +69,22 @@ module Parlour
             next
           end
 
-          # Special case: do we have two attributes, one of which is a class 
+          # Special case: if we remove the namespaces, is everything either an
+          # include or an extend? If so, do nothing - this is fine
+          if children \
+            .reject { |c| c.is_a?(RbiGenerator::Namespace) }
+            .then do |x|
+              !x.empty? && x.all? do |c|
+                c.is_a?(RbiGenerator::Include) || c.is_a?(RbiGenerator::Extend)
+              end
+            end
+            deduplicate_mixins_of_name(namespace, name)
+
+            Debugging.debug_puts(self, Debugging::Tree.end("Includes/extends do not conflict with namespaces; no resolution required"))
+            next
+          end
+
+          # Special case: do we have two attributes, one of which is a class
           # attribute and the other isn't? If so, do nothing - this is fine
           if children.length == 2 &&
             children.all? { |c| c.is_a?(RbiGenerator::Attribute) } &&
@@ -70,13 +94,13 @@ module Parlour
             next
           end
 
-          # Special case: are they all clearly equal? If so, remove all but one
+          # 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"))
 
             # All of the children are the same, so this deletes all of them
             namespace.children.delete(T.must(children.first))
-          
+
             # Re-add one child
             namespace.children << T.must(children.first)
             next
@@ -88,11 +112,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 +124,47 @@ 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
+
+            # For certain namespace types the order matters. For example, if there's
+            # both a `Namespace` and `ModuleNamespace` then merging the two would
+            # produce different results depending on which is first.
+            first_index = (
+              namespaces.find_index { |x| RbiGenerator::EnumClassNamespace === x || RbiGenerator::StructClassNamespace === x } ||
+              namespaces.find_index { |x| RbiGenerator::ClassNamespace === x } ||
+              namespaces.find_index { |x| RbiGenerator::ModuleNamespace === x } ||
+              0
+            )
+
+            first = namespaces.delete_at(first_index)
+            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 +194,41 @@ 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 }
+      exactly_namespace, namespace_subclasses = namespace_types.partition { |x| x == RbiGenerator::Namespace }
+
+      return nil unless namespace_subclasses.empty? \
+        || (namespace_subclasses.length == 1 && namespace_subclasses.first < RbiGenerator::Namespace) \
+        || namespace_subclasses.to_set == Set[RbiGenerator::ClassNamespace, RbiGenerator::StructClassNamespace] \
+        || namespace_subclasses.to_set == Set[RbiGenerator::ClassNamespace, RbiGenerator::EnumClassNamespace]
+
+      # 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) }
@@ -151,5 +240,26 @@ module Parlour
     def all_eql?(arr)
       arr.each_cons(2).all? { |x, y| x == y }
     end
+
+    sig { params(namespace: RbiGenerator::Namespace, name: T.nilable(String)).void }
+    # Given a namespace and a child name, removes all duplicate children that are mixins
+    # and that have the given name, except the first found instance.
+    #
+    # @param namespace [RbiGenerator::Namespace] The namespace to deduplicate mixins in.
+    # @param name [String] The name of the mixin modules to deduplicate.
+    # @return [void]
+    def deduplicate_mixins_of_name(namespace, name)
+      found_map = {}
+      namespace.children.delete_if do |x|
+        # ignore children whose names don't match
+        next unless x.name == name
+        # ignore children that are not mixins
+        next unless x.is_a?(RbiGenerator::Include) || x.is_a?(RbiGenerator::Extend)
+
+        delete = found_map.key?(x.class)
+        found_map[x.class] = true
+        delete
+      end
+    end
   end
 end