parlour 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 761bffbc56ef9da0ef4c5fd4bce6ddb60dacafa0162a367fc2073d8466e37db9
-  data.tar.gz: cb5a6966088858d39c6942d2d38ed7ff947cff26853828200eaca7313cdaca33
+  metadata.gz: c2e368fa34eb2073d6b20beda3455dbf51db175ec2f5ef6c085de62f62601888
+  data.tar.gz: c0c0b1e1f0e9df83e76cba72609083058149d7de169afcb07418a3117b00880a
 SHA512:
-  metadata.gz: 942a3f4b6ebffed1c09ee2b396ec0230663c12f4549a7dd62ce4f72f12705976edb4a9b370aa6da806c8c40e62997c653ab057a6ac4d3aebd747f9c9b040dfc3
-  data.tar.gz: b9327692a59d57413a6095e509b99ea55ab05629406aff1c7bd244e1a8d7fee3547fc2b3feec99556ea6d93b8f931d6f18a621283c8f813423a93bc290099fb4
+  metadata.gz: e6d87997cabce942aa838efc114071f08465de8fb7c442eb58a6bce45d1e95bb78369183fa11568da31b52038bbb38af9ddf78617f5328536bbd6f3fbd0976f7
+  data.tar.gz: 70b90d57fc92f67934816152c6ac40505e2305400cbadab4313d3e01b079a0637e6e056c1f58a93db455a6d5d715d58c6cdc8e4b43f9274fa23d718f225519fa

data/.gitignore

@@ -6,6 +6,8 @@
 /pkg/
 /spec/reports/
 /tmp/
+Gemfile.lock
+/.vscode
 
 # rspec failure tracking
 .rspec_status

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+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/).
+
+## [0.1.1] - 2019-07-05
+### Added
+- Initial release!
+
+_(0.1.0 was a blank gem.)_

data/README.md

@@ -1,38 +1,118 @@
 # Parlour
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/parlour`. To experiment with that code, run `bin/console` for an interactive prompt.
+Parlour is an RBI generator and merger for Sorbet. Once done, it'll consist of
+two parts:
 
-TODO: Delete this and the text above, and describe your gem
+  - The generator, which outputs beautifully formatted RBI files, created using
+    an intuitive DSL.
 
-## Installation
+  - The plugin/build system, which allows multiple Parlour plugins to generate
+    RBIs for the same codebase. These are combined automatically as much as 
+    possible, but any other conflicts can be resolved manually through prompts.
 
-Add this line to your application's Gemfile:
+## Usage
+
+Here's a quick example of how you might generate an RBI currently, though this
+API is very likely to change:
 
 ```ruby
-gem 'parlour'
-```
+require 'parlour'
 
-And then execute:
+generator = Parlour::RbiGenerator.new
+generator.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
 
-    $ bundle
+  a.create_class('Bar', superclass: 'Foo')
+end
 
-Or install it yourself as:
+generator.rbi # => Our RBI as a string
+```
 
-    $ gem install parlour
+This will generate the following RBI:
 
-## Usage
+```ruby
+module A
+  class Foo
+    sig { params(a: Integer, b: Integer).returns(Integer) }
+    def add_two_integers(a, b); end
+  end
+
+  class Bar < Foo
+  end
+end
+```
 
-TODO: Write usage instructions here
+There aren't really any docs currently, so have a look around the code to find
+any extra options you may need.
 
-## Development
+## Code Structure
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### Overall Flow
+```
+                        STEP 1
+                 All plugins mutate the
+                 instance of RbiGenerator
+                 They generate a tree
+                 structure of RbiObjects
+
+                 +--------+  +--------+
+                 |Plugin 1|  |Plugin 2|
+                 +----+---+  +----+---+         STEP 2
+                      ^           ^        ConflictResolver
+                      |           |        mutates the structure
++-------------------+ |           |        to fix conflicts
+|                   | |           |
+| One instance of   +-------------+        +----------------+
+| RbiGenerator      +--------------------->+ConflictResolver|
+|                   |                      +----------------+
++---------+---------+
+          |
+          |
+          |          +-------+          STEP 3
+          +--------->+ File  |    The final RBI is written
+                     +-------+    to a file
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+### 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.
+(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.
+
+### Conflict Resolution
+This will be 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.
+
+It is able to do the following merges automatically:
+
+  - If many methods are identical, delete all but one.
+  - If many classes are defined with the same name, merge their methods,
+    includes and extends. (But only if they are all abstract or all not,
+    and only if they don't define more than one superclass together.)
+  - If many modules are defined with the same name, merge their methods,
+    includes and extends. (But only if they are all interfaces or all not.)
+
+If a merge can't be performed automatically, then the `#resolve_conflicts`
+method takes a block. This block is passed all the conflicting objects, and one
+should be selected and returned - all others will be deleted. (Alternatively,
+the block can return nil, and all will be deleted.) This will allow a CLI to 
+prompt the user asking them what they'd like to do, in the case of conflicts
+between each plugin's signatures which can't automatically be resolved.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/parlour. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/AaronC81/parlour. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 
@@ -40,4 +120,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Parlour project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/parlour/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Parlour project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/AaronC81/parlour/blob/master/CODE_OF_CONDUCT.md).

data/lib/parlour.rb

@@ -1,6 +1,16 @@
-require "parlour/version"
+# typed: strong
+require 'sorbet-runtime'
+
+require 'parlour/version'
+
+require 'parlour/rbi_generator/parameter'
+require 'parlour/rbi_generator/rbi_object'
+require 'parlour/rbi_generator/method'
+require 'parlour/rbi_generator/options'
+require 'parlour/rbi_generator/namespace'
+require 'parlour/rbi_generator/module_namespace'
+require 'parlour/rbi_generator/class_namespace'
+require 'parlour/rbi_generator'
+
+require 'parlour/conflict_resolver'
 
-module Parlour
-  class Error < StandardError; end
-  # Your code goes here...
-end

data/lib/parlour/conflict_resolver.rb

@@ -0,0 +1,81 @@
+# typed: true
+module Parlour
+  class ConflictResolver
+    extend T::Sig
+
+    sig do
+      params(
+        namespace: RbiGenerator::Namespace,
+        resolver: T.proc.params(
+          desc: String,
+          choices: T::Array[RbiGenerator::RbiObject]
+        ).returns(RbiGenerator::RbiObject)
+      ).void
+    end
+    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.each do |name, children|
+        if children.length > 1
+          # We found a conflict!
+          # Start by removing all the conflicting items
+          children.each do |c|
+            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
+            # The types aren't the same, so ask the resovler what to do, and
+            # insert that (if not nil)
+            choice = resolver.call("Different kinds of definition for the same name", children)
+            namespace.children << choice if choice
+            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)
+          if T.must(first).mergeable?(T.must(rest))
+            first.merge_into_self(rest)
+            namespace.children << first
+            next
+          end
+
+          # I give up! Let it be resolved manually somehow
+          choice = resolver.call("Can't automatically resolve", children)
+          namespace.children << choice if choice
+        end
+      end
+
+      # TODO: recurse to deeper namespaces
+    end
+
+    sig { params(arr: T::Array[T.untyped]).returns(T.nilable(Class)) }
+    def single_type_of_array(arr)
+      array_types = arr.map { |c| T.cast(c, Object).class }.uniq
+      array_types.length == 1 ? array_types.first : nil
+    end
+
+    sig { params(arr: T::Array[T.untyped]).returns(T::Boolean) }
+    def all_eql?(arr)
+      arr.each_cons(2).all? { |x, y| x == y }
+    end
+  end
+end

data/lib/parlour/rbi_generator.rb

@@ -0,0 +1,23 @@
+# typed: true
+module Parlour
+  class RbiGenerator
+    extend T::Sig
+
+    sig { params(break_params: Integer, tab_size: Integer).void }
+    def initialize(break_params: 4, tab_size: 2)
+      @options = Options.new(break_params: break_params, tab_size: tab_size)
+      @root = Namespace.new
+    end
+
+    sig { returns(Options) }
+    attr_reader :options
+
+    sig { returns(Namespace) }
+    attr_reader :root
+
+    sig { returns(String) }
+    def rbi
+      root.generate_rbi(0, options).join("\n")
+    end
+  end
+end

data/lib/parlour/rbi_generator/class_namespace.rb

@@ -0,0 +1,80 @@
+# typed: true
+module Parlour
+  class RbiGenerator
+    class ClassNamespace < Namespace
+      extend T::Sig
+
+      sig do
+        params(
+          name: String,
+          superclass: T.nilable(String),
+          abstract: T::Boolean,
+          block: T.nilable(T.proc.params(x: ClassNamespace).void)
+        ).void
+      end
+      def initialize(name, superclass, abstract, &block)
+        super(&block)
+        @name = name
+        @superclass = superclass
+        @abstract = abstract
+      end
+
+      sig do
+        override.params(
+          indent_level: Integer,
+          options: Options
+        ).returns(T::Array[String])
+      end
+      def generate_rbi(indent_level, options)
+        class_definition = superclass.nil? \
+          ? "class #{name}"
+          : "class #{name} < #{superclass}"
+        
+        lines = []
+        lines << options.indented(indent_level, class_definition)
+        lines += [options.indented(indent_level + 1, "abstract!"), ""] if abstract
+        lines += super(indent_level + 1, options)
+        lines << options.indented(indent_level, "end")
+      end
+
+      sig { returns(String) }
+      attr_reader :name
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :superclass
+
+      sig { returns(T::Boolean) }
+      attr_reader :abstract
+
+      sig do
+        override.params(
+          others: T::Array[RbiGenerator::RbiObject]
+        ).returns(T::Boolean)
+      end
+      def mergeable?(others)
+        others = T.cast(others, T::Array[ClassNamespace]) rescue (return false)
+        all = others + [self]
+
+        all.map(&:abstract).uniq.length == 1 &&
+          all.map(&:superclass).compact.uniq.length <= 1
+      end
+
+      sig do 
+        override.params(
+          others: T::Array[RbiGenerator::RbiObject]
+        ).void
+      end
+      def merge_into_self(others)
+        others.each do |other|
+          other = T.cast(other, ClassNamespace)
+
+          other.children.each { |c| children << c }
+          other.extends.each { |e| extends << e }
+          other.includes.each { |i| includes << i }
+
+          @superclass = other.superclass unless superclass
+        end
+      end
+    end
+  end
+end

data/lib/parlour/rbi_generator/method.rb

@@ -0,0 +1,142 @@
+# typed: true
+module Parlour
+  class RbiGenerator
+    class Method
+      extend T::Sig
+
+      include RbiObject
+
+      sig do
+        params(
+          name: String,
+          parameters: T::Array[Parameter],
+          return_type: T.nilable(String),
+          abstract: T::Boolean,
+          implementation: T::Boolean,
+          override: T::Boolean,
+          overridable: T::Boolean,
+          class_method: T::Boolean
+        ).void
+      end
+      def initialize(name, parameters, return_type = nil, abstract: false, implementation: false, override: false, overridable: false, class_method: false)
+        @name = name
+        @parameters = parameters
+        @return_type = return_type
+        @abstract = abstract
+        @implementation = implementation
+        @override = override
+        @overridable = overridable
+        @class_method = class_method
+      end
+
+      sig { params(other: Object).returns(T::Boolean) }
+      def ==(other)
+        Method === other &&
+          name           == other.name && 
+          parameters     == other.parameters &&
+          return_type    == other.return_type &&
+          abstract       == other.abstract &&
+          implementation == other.implementation &&
+          override       == other.override &&
+          overridable    == other.overridable &&
+          class_method   == other.class_method
+      end
+
+      sig { returns(String) }
+      attr_reader :name
+
+      sig { returns(T::Array[Parameter]) }
+      attr_reader :parameters
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :return_type
+
+      sig { returns(T::Boolean) }
+      attr_reader :abstract
+
+      sig { returns(T::Boolean) }
+      attr_reader :implementation
+
+      sig { returns(T::Boolean) }
+      attr_reader :override
+
+      sig { returns(T::Boolean) }
+      attr_reader :overridable
+
+      sig { returns(T::Boolean) }
+      attr_reader :class_method
+
+      sig do
+        implementation.params(
+          indent_level: Integer,
+          options: Options
+        ).returns(T::Array[String])
+      end
+      def generate_rbi(indent_level, options)
+        return_call = return_type ? "returns(#{return_type})" : 'void'
+
+        sig_params = parameters.map(&:to_sig_param)
+        sig_lines = parameters.length >= options.break_params \
+          ? [
+              options.indented(indent_level, 'sig do'),
+              options.indented(indent_level + 1, "#{qualifiers}params("),
+            ] +
+            (
+              parameters.empty? ? [] : sig_params.map do |x|
+                options.indented(indent_level + 2, "#{x},") 
+              end
+            ) +
+            [
+              options.indented(indent_level + 1, ").#{return_call}"),
+              options.indented(indent_level, 'end')
+            ]
+
+          : [options.indented(
+              indent_level,
+              "sig { #{qualifiers}#{
+                parameters.empty? ? '' : "params(#{sig_params.join(', ')})"
+              }#{
+                qualifiers.empty? && parameters.empty? ? '' : '.'
+              }#{return_call} }"
+            )]
+
+        def_params = parameters.map(&:to_def_param)
+        name_prefix = class_method ? 'self.' : ''
+        def_line = options.indented(
+          indent_level,
+          "def #{name_prefix}#{name}(#{def_params.join(', ')}); end"
+        )
+
+        sig_lines + [def_line]
+      end
+
+      sig { returns(String) }
+      def qualifiers
+        result = ''
+        result += 'abstract.' if abstract
+        result += 'implementation.' if implementation
+        result += 'override.' if override
+        result += 'overridable.' if overridable
+        result
+      end
+
+      sig do
+        implementation.params(
+          others: T::Array[RbiGenerator::RbiObject]
+        ).returns(T::Boolean)
+      end
+      def mergeable?(others)
+        false
+      end
+
+      sig do 
+        implementation.params(
+          others: T::Array[RbiGenerator::RbiObject]
+        ).void
+      end
+      def merge_into_self(others)
+        raise 'methods can never be merged like this'
+      end
+    end
+  end
+end