parlour 3.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e2b9021c22592632f30a0a51c17cfbf3838c18061638297e9437c1dd34b5c9f
-  data.tar.gz: 337e2ea6d8212e6c2d16d2f8f5577b16bfd1c8ffa41197fad70f9dc7c51620b5
+  metadata.gz: f37a6dd2dffd0b59594b4c0ed664cdd27c4ea5bb02d1ca0f944ddff2d6ccda83
+  data.tar.gz: 38b776b79c349f48e672fbb81534d4ab1b751af13ecdab9e60d3f08562f03332
 SHA512:
-  metadata.gz: 22e0196918f8214827f9904e45fff8689f4609ec71683ad4aca36c8eb75593e19f5d0ec4e5a5e034afdca1d3bdf7f0d9482bfb24b0e3e667553c13b5cb5b65a6
-  data.tar.gz: 2b322d3dcdce74985b2104a8d8beb8ac0a7b6b4de1bcc8af7288d5334d715765285cba032017c7ab6e5dccde045b284dd8056e57515e13f32f319de26fdc0666
+  metadata.gz: 8da56118b8e784707a054ae7dbdddda63dade826ec19d87a06f468229e8e53ef1669f7b05c4c5be6cc9e75377846e729748b0f31d3400768041079050fb72776
+  data.tar.gz: c7a39a7a91aee7298fbdf3e5d7ebdebc278001317cb365bc7f3970d62fa49c2d9e3f5d7e1eb4c70a386ef0964f14bde2647871ab8c0b6a3a5adad8c774bc08f5

data/.parlour

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

data/CHANGELOG.md

@@ -3,6 +3,16 @@ 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.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.

data/README.md

@@ -13,7 +13,7 @@ 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 
+  - The parser, which can read an RBI and convert it back into a tree of
     generator objects.
 
 ## Why should I use this?
@@ -26,7 +26,10 @@ key parts:
     RBI output file.
 
   - You can **effortlessly build tools which need to access types within an RBI**;
-    no need to write your own parser! 
+    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!
@@ -174,6 +177,29 @@ 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/detached_rbi_generator.rb

@@ -6,17 +6,12 @@ module Parlour
     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

data/lib/parlour/plugin.rb

@@ -50,7 +50,7 @@ module Parlour
       end
     end
 
-    sig { params(options: Hash).void }
+    sig { params(options: T::Hash[T.untyped, T.untyped]).void }
     def initialize(options); end
 
     sig { abstract.params(root: RbiGenerator::Namespace).void }

data/lib/parlour/rbi_generator/constant.rb

@@ -8,6 +8,7 @@ module Parlour
           generator: RbiGenerator,
           name: String,
           value: String,
+          eigen_constant: T::Boolean,
           block: T.nilable(T.proc.params(x: Constant).void)
         ).void
       end
@@ -15,9 +16,12 @@ module Parlour
       #
       # @param name [String] The name of the constant.
       # @param value [String] The value of the constant, as a Ruby code string.
-      def initialize(generator, name: '', value: '', &block)
+      # @param eigen_constant [Boolean] Whether this constant is defined on the
+      #   eigenclass of the current namespace.
+      def initialize(generator, name: '', value: '', eigen_constant: false, &block)
         super(generator, name)
         @value = value
+        @eigen_constant = eigen_constant
         yield_self(&block) if block
       end
 
@@ -25,6 +29,10 @@ module Parlour
       sig { returns(String) }
       attr_reader :value
 
+      # @return [Boolean] Whether this constant is defined on the eigenclass
+      #   of the current namespace.
+      attr_reader :eigen_constant
+
       sig { params(other: Object).returns(T::Boolean) }
       # Returns true if this instance is equal to another extend.
       #
@@ -32,7 +40,8 @@ module Parlour
       #   subclass of it), this will always return false.
       # @return [Boolean]
       def ==(other)
-        Constant === other && name == other.name && value == other.value
+        Constant === other && name == other.name && value == other.value \
+          && eigen_constant == other.eigen_constant
       end
 
       sig do

data/lib/parlour/rbi_generator/namespace.rb

@@ -527,7 +527,7 @@ module Parlour
         returned_includables
       end
 
-      sig { params(name: String, value: String, block: T.nilable(T.proc.params(x: Constant).void)).returns(Constant) }
+      sig { params(name: String, value: String, eigen_constant: T::Boolean, block: T.nilable(T.proc.params(x: Constant).void)).returns(Constant) }
       # Adds a new constant definition to this namespace.
       #
       # @example Add an +Elem+ constant to the class.
@@ -535,13 +535,16 @@ module Parlour
       #
       # @param name [String] The name of the constant.
       # @param value [String] The value of the constant, as a Ruby code string.
+      # @param eigen_constant [Boolean] Whether this constant is defined on the
+      #   eigenclass of the current namespace.
       # @param block A block which the new instance yields itself to.
       # @return [RbiGenerator::Constant]
-      def create_constant(name, value:, &block)
+      def create_constant(name, value:, eigen_constant: false, &block)
         new_constant = RbiGenerator::Constant.new(
           generator,
           name: name,
           value: value,
+          eigen_constant: eigen_constant,
           &block
         )
         move_next_comments(new_constant)
@@ -631,14 +634,19 @@ module Parlour
 
         result += [options.indented(indent_level, 'final!'), ''] if final
 
-        if includes.any? || extends.any? || constants.any?
+        # Split away the eigen constants; these need to be put in a
+        # "class << self" block later
+        eigen_constants, non_eigen_constants = constants.partition(&:eigen_constant)
+        eigen_constants.sort_by!(&:name) if options.sort_namespaces
+
+        if includes.any? || extends.any? || non_eigen_constants.any?
           result += (options.sort_namespaces ? includes.sort_by(&:name) : includes)
             .flat_map { |x| x.generate_rbi(indent_level, options) }
             .reject { |x| x.strip == '' }
           result += (options.sort_namespaces ? extends.sort_by(&:name) : extends)
             .flat_map { |x| x.generate_rbi(indent_level, options) }
             .reject { |x| x.strip == '' }
-          result += (options.sort_namespaces ? constants.sort_by(&:name) : constants)
+          result += (options.sort_namespaces ? non_eigen_constants.sort_by(&:name) : non_eigen_constants)
             .flat_map { |x| x.generate_rbi(indent_level, options) }
             .reject { |x| x.strip == '' }
           result << ""
@@ -658,14 +666,29 @@ module Parlour
           child.is_a?(Attribute) && child.class_attribute
         end
 
-        if class_attributes.any?
-          result << options.indented(indent_level, 'class << self')
+        # Handle the "class << self block"
+        result << options.indented(indent_level, 'class << self') \
+          if class_attributes.any? || eigen_constants.any?
+
+        if eigen_constants.any?
+          first, *rest = eigen_constants
+          result += T.must(first).generate_rbi(indent_level + 1, options) + T.must(rest)
+            .map { |obj| obj.generate_rbi(indent_level + 1, options) }
+            .map { |lines| [""] + lines }
+            .flatten
+        end
+
+        result << '' if eigen_constants.any? && class_attributes.any?
 
+        if class_attributes.any?
           first, *rest = class_attributes
           result += T.must(first).generate_rbi(indent_level + 1, options) + T.must(rest)
             .map { |obj| obj.generate_rbi(indent_level + 1, options) }
             .map { |lines| [""] + lines }
             .flatten
+        end
+
+        if class_attributes.any? || eigen_constants.any?
           result << options.indented(indent_level, 'end')
           result << ''
         end

data/lib/parlour/rbi_generator/parameter.rb

@@ -42,7 +42,7 @@ module Parlour
 
         @kind = :keyword if kind == :normal && name.end_with?(':')
 
-        @type = type
+        @type = type || 'T.untyped'
         @default = default
       end
 
@@ -80,10 +80,10 @@ module Parlour
         T.must(name[prefix.length..-1])
       end
 
-      sig { returns(T.nilable(String)) }
+      sig { returns(String) }
       # A Sorbet string of this parameter's type, such as +"String"+ or
       # +"T.untyped"+.
-      # @return [String, nil]
+      # @return [String]
       attr_reader :type
 
       sig { returns(T.nilable(String)) }
@@ -118,7 +118,7 @@ module Parlour
       #
       # @return [String]
       def to_sig_param
-        "#{name_without_kind}: #{type || 'T.untyped'}"
+        "#{name_without_kind}: #{type}"
       end#
 
       # A mapping of {kind} values to the characteristic prefixes each kind has.

data/lib/parlour/type_loader.rb

@@ -10,27 +10,34 @@ module Parlour
     # TODO: make this into a class which stores configuration and passes it to
     # all typeparsers
 
-    sig { params(source: String, filename: T.nilable(String)).returns(RbiGenerator::Namespace) }
+    sig { params(source: String, filename: T.nilable(String), generator: T.nilable(RbiGenerator)).returns(RbiGenerator::Namespace) }
     # Converts Ruby source code into a tree of objects.
     #
     # @param [String] source The Ruby source code.
     # @param [String, nil] filename The filename to use when parsing this code.
     #   This may be used in error messages, but is optional.
     # @return [RbiGenerator::Namespace] The root of the object tree.
-    def self.load_source(source, filename = nil)
-      TypeParser.from_source(filename || '(source)', source).parse_all
+    def self.load_source(source, filename = nil, generator: nil)
+      TypeParser.from_source(filename || '(source)', source, generator: generator).parse_all
     end
 
-    sig { params(filename: String).returns(RbiGenerator::Namespace) }
+    sig { params(filename: String, generator: T.nilable(RbiGenerator)).returns(RbiGenerator::Namespace) }
     # Converts Ruby source code into a tree of objects from a file.
     #
     # @param [String] filename The name of the file to load code from.
     # @return [RbiGenerator::Namespace] The root of the object tree.
-    def self.load_file(filename)
-      load_source(File.read(filename), filename)
+    def self.load_file(filename, generator: nil)
+      load_source(File.read(filename), filename, generator: generator)
+    end
+
+    sig do
+      params(
+        root: String,
+        inclusions: T::Array[String],
+        exclusions: T::Array[String],
+        generator: T.nilable(RbiGenerator),
+      ).returns(RbiGenerator::Namespace)
     end
-  
-    sig { params(root: String, exclusions: T::Array[String]).returns(RbiGenerator::Namespace) }
     # Loads an entire Sorbet project using Sorbet's file table, obeying any
     # "typed: ignore" sigils, into a tree of objects.
     #
@@ -39,12 +46,15 @@ module Parlour
     #
     # @param [String] root The root of the project; where the "sorbet" directory
     #   and "Gemfile" are located.
+    # @param [Array<String>] inclusions A list of files to include when loading
+    #   the project, relative to the given root.
     # @param [Array<String>] exclusions A list of files to exclude when loading
     #   the project, relative to the given root.
     # @return [RbiGenerator::Namespace] The root of the object tree.
-    def self.load_project(root, exclusions: [])
+    def self.load_project(root, inclusions: ['.'], exclusions: [], generator: nil)
+      expanded_inclusions = inclusions.map { |i| File.expand_path(i, root) }
       expanded_exclusions = exclusions.map { |e| File.expand_path(e, root) }
-      
+
       stdin, stdout, stderr, wait_thr = T.unsafe(Open3).popen3(
         'bundle exec srb tc -p file-table-json',
         chdir: root
@@ -63,14 +73,17 @@ module Parlour
         path = File.expand_path(rel_path, root)
 
         # Skip this file if it was excluded
-        next if expanded_exclusions.include?(path)
+        next if !expanded_inclusions.any? { |i| path.start_with?(i) } \
+          || expanded_exclusions.any? { |e| path.start_with?(e) }
 
         # There are some entries which are URLs to stdlib
         next unless File.exist?(path)
 
-        namespaces << load_file(path)
+        namespaces << load_file(path, generator: generator)
       end
 
+      namespaces.uniq!
+
       raise 'project is empty' if namespaces.empty?
 
       first_namespace, *other_namespaces = namespaces