parlour 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2e368fa34eb2073d6b20beda3455dbf51db175ec2f5ef6c085de62f62601888
-  data.tar.gz: c0c0b1e1f0e9df83e76cba72609083058149d7de169afcb07418a3117b00880a
+  metadata.gz: 88487f0d150090c2b0877343e66efc37d0643892fd3b99966f0d4cca992d29e1
+  data.tar.gz: eb2f33d58f3606186d9691845d50071d456107d9a913947f70b89cfa2c9a6492
 SHA512:
-  metadata.gz: e6d87997cabce942aa838efc114071f08465de8fb7c442eb58a6bce45d1e95bb78369183fa11568da31b52038bbb38af9ddf78617f5328536bbd6f3fbd0976f7
-  data.tar.gz: 70b90d57fc92f67934816152c6ac40505e2305400cbadab4313d3e01b079a0637e6e056c1f58a93db455a6d5d715d58c6cdc8e4b43f9274fa23d718f225519fa
+  metadata.gz: 8ae0f4def7984b641df8b45000eddbafcf10048ccc772f4802d413e79b8e1431afc58963f2c1e40533b99729dad4801c3f328fc3a6f35cb654ad9c7b092a493c
+  data.tar.gz: ad6f1e9bd34f9b56aaa4ae1eb8ac30cded890f2b5f64672d9bdc5f3ca82d18ec4ee2b55cea1c7abd65ba32cd03d874715d470f4cd72c2a733d2ba209a7b06755

data/.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Create an issue to report a bug
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Include the code (and if applicable your `parlour` CLI invocation) where Parlour is doing something wrong. 
+
+**Expected behavior**
+A clear and concise description of what you expected to happen. It may be useful to write your own expected RBI for your code.
+
+**Actual behavior**
+A description of what actually happened. Please post any incorrect RBI signatures, as well as the command-line output of Parlour.
+
+**Additional information**
+Add any other information about the problem here. Please include the version of Parlour you're using as well as the versions of any plugins.

data/.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context about the feature request here.

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+before_install:
+  - gem install bundler
+rvm: 
+  - 2.6

data/README.md

@@ -1,7 +1,8 @@
 # Parlour
 
-Parlour is an RBI generator and merger for Sorbet. Once done, it'll consist of
-two parts:
+[![Build Status](https://travis-ci.org/AaronC81/parlour.svg?branch=master)](https://travis-ci.org/AaronC81/parlour)
+
+Parlour is an RBI generator and merger for Sorbet. It consists of two key parts:
 
   - The generator, which outputs beautifully formatted RBI files, created using
     an intuitive DSL.
@@ -12,6 +13,11 @@ two parts:
 
 ## Usage
 
+There aren't really any docs currently, so have a look around the code to find
+any extra options you may need.
+
+### Using just the generator
+
 Here's a quick example of how you might generate an RBI currently, though this
 API is very likely to change:
 
@@ -47,8 +53,54 @@ module A
 end
 ```
 
-There aren't really any docs currently, so have a look around the code to find
-any extra options you may need.
+### Writing a plugin
+Plugins are better than using the generator alone, as your plugin can be 
+combined with others to produce larger RBIs without conflicts.
+
+We could write the above example as a plugin like this:
+
+```ruby
+require 'parlour'
+
+class MyPlugin < Parlour::Plugin
+  def generate(root)
+    root.create_module('A') do |a|
+      a.create_class('Foo') do |foo|
+        foo.create_method('add_two_integers', [
+          Parlour::RbiGenerator::Parameter.new('a', type: 'Integer'),
+          Parlour::RbiGenerator::Parameter.new('b', type: 'Integer')
+        ], 'Integer')
+      end
+
+      a.create_class('Bar', superclass: 'Foo')
+    end
+  end
+end
+```
+
+(Obviously, your plugin will probably examine a codebase somehow, to be more
+useful!)
+
+You can then run several plugins, combining their output and saving it into one
+RBI file, using the command-line tool. For example, if that code was in a file
+called `plugin.rb`, this would save the RBI into `output.rbi`:
+
+```
+parlour --relative-requires plugin.rb MyPlugin output.rbi
+```
+
+You can also use plugins from gems. If that plugin was published as a gem called
+`parlour-gem`:
+
+```
+parlour --requires parlour-gem MyPlugin output.rbi
+```
+
+The real power of this is the ability to use many plugins at once:
+
+```
+parlour --requires gem1,gem2,gem3 Gem1::Plugin Gem2::Plugin Gem3::Plugin output.rbi
+```
 
 ## Code Structure
 
@@ -80,16 +132,23 @@ any extra options you may need.
 
 ### Generation
 Everything that can generate lines of the RBI implements the 
-`RbiGenerator::RbiObject` interface. This defines one function, `generate_rbi`,
-which accepts the current indentation level and a set of formatting options.
+`RbiGenerator::RbiObject` abstract class. The function `generate_rbi`
+accepts the current indentation level and a set of formatting options.
 (Each object is responsible for generating its own indentation; that is, the
 lines generated by a child object should not then be indented by its parent.)
 
 I think generation is quite close to done, but it still needs features like 
 constants and type parameters.
 
+### Plugins
+Plugins are automatically detected when they subclass `Plugin`. Plugins can then
+be run by passing an array of them, along with an `RbiGenerator`, to
+`Plugin.run_plugins`. Once done, the generator will be populated with a tree of
+(possibly conflicting) `RbiObjects` - the conflict resolver (detailed below)
+will clear up any conflicts.
+  
 ### Conflict Resolution
-This will be a key part of the plugin/build system. The `ConflictResolver` takes
+This is a key part of the plugin/build system. The `ConflictResolver` takes
 a namespace from the `RbiGenerator` and merges duplicate items in it together. 
 This means that many plugins can generate their own signatures which are all 
 bundled into one, conflict-free output RBI.

data/Rakefile

@@ -0,0 +1,6 @@
+require 'rspec/core/rake_task'
+
+task :default => [:spec]
+
+desc "Run the specs."
+RSpec::Core::RakeTask.new

data/exe/parlour

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+require 'parlour'
+require 'commander/import'
+require 'bundler'
+require 'rainbow'
+
+program :name, 'parlour'
+program :version, Parlour::VERSION
+program :description, 'An RBI generator and plugin system'
+
+default_command :run
+command :run do |c|
+  c.syntax = 'parlour run <plugins...> <output-file> [options]'
+  c.description = 'Generates an RBI file from a list of plugins'
+  c.option '--requires STRING', String, 'A comma-separated string of gems to require'
+  c.option '--relative-requires STRING', String, 'A comma-separated string of files to require, relative to the working dir'
+  c.option '--tab-size INTEGER', Integer, 'The size of tabs to use'
+  c.option '--break-params INTEGER', Integer, 'Break params onto their own lines if there are this many'
+
+  c.action do |args, options|
+    options.default(
+      tab_size: 2,
+      break_params: 4,
+      requires: '',
+      relative_requires: ''
+    )
+
+    options.requires.split(',').each { |source| require(source) }
+    options.relative_requires.split(',').each do |source|
+      require(File.join(Dir.pwd, source))
+    end
+
+    *plugin_names, output_file = args
+
+    raise 'no output file specified' if output_file.nil?
+
+    plugin_instances = []
+
+    # Collect the instances of each plugin into an array
+    plugin_names.each do |name|
+      plugin = Parlour::Plugin.registered_plugins[name]
+      raise "missing plugin #{name}" unless plugin
+      plugin_instances << plugin
+    end
+
+    # Create a generator instance and run all plugins on it
+    gen = Parlour::RbiGenerator.new(
+      break_params: options.break_params,
+      tab_size: options.tab_size
+    )
+    Parlour::Plugin.run_plugins(plugin_instances, gen)
+
+    # Run a pass of the conflict resolver
+    Parlour::ConflictResolver.new.resolve_conflicts(gen.root) do |msg, candidates|
+      puts Rainbow('Conflict! ').red.bright.bold + Rainbow(msg).blue.bright
+      puts 'Multiple different definitions have been produced for the same object.'
+      puts 'They could not be merged automatically.'
+      puts Rainbow('What would you like to do?').bold + ' Type a choice and press Enter.'
+      puts
+      puts Rainbow('  [0] ').yellow + 'Remove ALL definitions'
+      puts
+      puts "Or select one definition to keep:"
+      puts
+      candidates.each.with_index do |candidate, i|
+        puts Rainbow("  [#{i + 1}] ").yellow + candidate.describe
+      end
+      puts
+      choice = ask("?  ", Integer) { |q| q.in = 0..candidates.length }
+      choice == 0 ? nil : candidates[choice - 1]
+    end
+ 
+    # Write the final RBI
+    File.write(output_file, gen.rbi)
+  end
+end

data/lib/parlour.rb

@@ -3,9 +3,12 @@ require 'sorbet-runtime'
 
 require 'parlour/version'
 
+require 'parlour/plugin'
+
 require 'parlour/rbi_generator/parameter'
 require 'parlour/rbi_generator/rbi_object'
 require 'parlour/rbi_generator/method'
+require 'parlour/rbi_generator/attribute'
 require 'parlour/rbi_generator/options'
 require 'parlour/rbi_generator/namespace'
 require 'parlour/rbi_generator/module_namespace'

data/lib/parlour/conflict_resolver.rb

@@ -1,5 +1,7 @@
 # typed: true
 module Parlour
+  # Responsible for resolving conflicts (that is, multiple definitions with the
+  # same name) between objects defined in the same namespace.
   class ConflictResolver
     extend T::Sig
 
@@ -12,17 +14,33 @@ module Parlour
         ).returns(RbiGenerator::RbiObject)
       ).void
     end
+    # Given a namespace, attempts to automatically resolve conflicts in the
+    # namespace's definitions. (A conflict occurs when multiple objects share
+    # the same name.)
+    #
+    # 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 
+    # {resolve_conflicts}, one for each unresolvable conflict.
+    #
+    # @param namespace [RbiGenerator::Namespace] The starting namespace to
+    #   resolve conflicts in.
+    # @yieldparam message [String] A descriptional message on what the conflict is.
+    # @yieldparam candidates [Array<RbiGenerator::RbiObject>] The objects for
+    #   which there is a conflict.
+    # @yieldreturn [RbiGenerator::RbiObject] One of the +candidates+, which
+    #   will be kept, or nil to keep none of them.
+    # @return [void]
     def resolve_conflicts(namespace, &resolver)
       # Check for multiple definitions with the same name
-      grouped_by_name_children = namespace.children.group_by do |rbi_obj|
-        if RbiGenerator::ModuleNamespace === rbi_obj \
-          || RbiGenerator::ClassNamespace === rbi_obj \
-          || RbiGenerator::Method === rbi_obj
-          rbi_obj.name
-        else
-          raise "unsupported child of type #{T.cast(rbi_obj, Object).class}"
-        end
-      end
+      grouped_by_name_children = namespace.children.group_by(&:name)
 
       grouped_by_name_children.each do |name, children|
         if children.length > 1
@@ -43,12 +61,6 @@ module Parlour
             next
           end
 
-          # Are all of the children equivalent? If so, just keep one of them
-          if all_eql?(children)
-            namespace.children << T.must(children.first)
-            next
-          end
-
           # Can the children merge themselves automatically? If so, let them
           first, *rest = children
           first, rest = T.must(first), T.must(rest)
@@ -64,18 +76,33 @@ module Parlour
         end
       end
 
-      # TODO: recurse to deeper namespaces
+      # Recurse to child namespaces
+      namespace.children.each do |child|
+        resolve_conflicts(child, &resolver) if RbiGenerator::Namespace === child
+      end
     end
 
+    private
+
     sig { params(arr: T::Array[T.untyped]).returns(T.nilable(Class)) }
+    # 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.
+    #
+    # @param arr [Array] The array.
+    # @return [Class, nil] Either a class, or nil.
     def single_type_of_array(arr)
-      array_types = arr.map { |c| T.cast(c, Object).class }.uniq
+      array_types = arr.map { |c| c.class }.uniq
       array_types.length == 1 ? array_types.first : nil
     end
 
     sig { params(arr: T::Array[T.untyped]).returns(T::Boolean) }
+    # Given an array, returns true if all elements in the array are equal by
+    # +==+. (Assumes a transitive definition of +==+.)
+    #
+    # @param arr [Array] The array.
+    # @return [Boolean] A boolean indicating if all elements are equal by +==+.
     def all_eql?(arr)
       arr.each_cons(2).all? { |x, y| x == y }
     end
   end
-end
+end

data/lib/parlour/plugin.rb

@@ -0,0 +1,53 @@
+# typed: true
+module Parlour
+  # The base class for user-defined RBI generation plugins.
+  # @abstract
+  class Plugin
+    extend T::Sig
+    extend T::Helpers
+    abstract!
+
+    @@registered_plugins = {}
+
+    sig { returns(T::Hash[String, Plugin]) }
+    # Returns all registered plugins, as a hash of their paths to the {Plugin}
+    # instances themselves.
+    #
+    # @return [{String, Plugin}]
+    def self.registered_plugins
+      @@registered_plugins
+    end
+
+    sig { params(new_plugin: T.class_of(Plugin)).void }
+    # Called automatically by the Ruby interpreter when {Plugin} is subclassed.
+    # This registers the new subclass into {registered_plugins}.
+    #
+    # @param new_plugin [Plugin] The new plugin.
+    # @return [void]
+    def self.inherited(new_plugin)
+      registered_plugins[T.must(new_plugin.name)] = new_plugin.new
+    end
+
+    sig { params(plugins: T::Array[Plugin], generator: RbiGenerator).void }
+    # Runs an array of plugins on a given generator instance.
+    #
+    # @param plugins [Array<Plugin>] An array of {Plugin} instances.
+    # @param generator [RbiGenerator] The {RbiGenerator} to run the plugins on.
+    # @return [void]
+    def self.run_plugins(plugins, generator)
+      plugins.each do |plugin|
+        generator.current_plugin = plugin
+        plugin.generate(generator.root)
+      end
+    end
+
+    sig { abstract.params(root: RbiGenerator::Namespace).void }
+    # Plugin subclasses should redefine this method and do their RBI generation
+    # inside it.
+    #
+    # @abstract
+    # @param root [RbiGenerator::Namespace] The root {RbiGenerator::Namespace}.
+    # @return [void]
+    def generate(root); end
+  end
+end

data/lib/parlour/rbi_generator.rb

@@ -1,23 +1,49 @@
 # typed: true
 module Parlour
+  # The RBI generator.
   class RbiGenerator
     extend T::Sig
 
     sig { params(break_params: Integer, tab_size: Integer).void }
+    # Creates a new RBI generator.
+    #
+    # @example Create a default generator.
+    #   generator = Parlour::RbiGenerator.new
+    # 
+    # @example Create a generator with a custom +tab_size+ of 3.
+    #   generator = Parlour::RbiGenerator.new(tab_size: 3)
+    #
+    # @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.
+    # @return [void]
     def initialize(break_params: 4, tab_size: 2)
       @options = Options.new(break_params: break_params, tab_size: tab_size)
-      @root = Namespace.new
+      @root = Namespace.new(self)
     end
 
     sig { returns(Options) }
+    # The formatting options for this generator.
+    # @return [Options]
     attr_reader :options
 
     sig { returns(Namespace) }
+    # The root {Namespace} of this generator.
+    # @return [Namespace]
     attr_reader :root
 
+    sig { 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 { returns(String) }
+    # Returns the complete contents of the generated RBI file as a string.
+    #
+    # @return [String] The generated RBI file
     def rbi
       root.generate_rbi(0, options).join("\n")
     end
   end
-end
+end