syntax_tree 2.3.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5855cfed255d36a243d697083688e553ae02aa5373ec08af6bc730eea66ab995
-  data.tar.gz: 15da5f28c3cff6953eb1204abbd42ac22b2c5ea78546242f543034360b39fb62
+  metadata.gz: '0804ba6e87e03ec83616511679283c17dc5c6250c5718c9e25aa218117abc2a1'
+  data.tar.gz: 485b0e850086f9b3cc949af3308edbd9f6a75b9ae0c13dda56a1eaf9847d2a28
 SHA512:
-  metadata.gz: 49bd5ad54611d46c9379e98f53c0ae789949d5104b225af51a54e7d4780e274a9a9bbcff1322c5af641dadd4c5d8d633b94b1271436ef1767bd9eb869dcb6be5
-  data.tar.gz: 12cd7e5be2218aeaf9a0833dd95ce40be9d2ee248933962e3f24e854ab5335dd25b2a86b9f6ecb2c6a7e24759dcf316a9db0e8aca8841a5365e6c8030882ac76
+  metadata.gz: f85fd10aec38d5d66f77359620ee37ad8b3494546763d96effc5ff0395a2bfdaacb3ade3698238d09201955a6e452a6b8ee52b575c9d17b00ca6fda17dfdbc79
+  data.tar.gz: 61faf8fc45245d9795717aa9a54c7bb4ccd2bc197facf0f8c9eeb9e55ce5dd04ddea63697d4e1c1cd7cf2663361ba8a078bf664f9407349860840958ce7d3c17

data/.github/workflows/main.yml

@@ -24,9 +24,28 @@ jobs:
         ruby-version: ${{ matrix.ruby }}
     - name: Test
       run: bundle exec rake test
+
+  check:
+    name: Check
+    runs-on: ubuntu-latest
+    env:
+      CI: true
+    steps:
+    - uses: actions/checkout@master
+    - uses: ruby/setup-ruby@v1
+      with:
+        bundler-cache: true
+        ruby-version: '3.1'
+    - name: Check
+      run: |
+        bundle exec rake check
+        bundle exec rubocop
+
   automerge:
     name: AutoMerge
-    needs: ci
+    needs:
+    - ci
+    - check
     runs-on: ubuntu-latest
     if: github.event_name == 'pull_request_target' && github.actor == 'dependabot[bot]'
     steps:

data/.rubocop.yml

@@ -0,0 +1,80 @@
+inherit_from: config/rubocop.yml
+
+AllCops:
+  DisplayCopNames: true
+  DisplayStyleGuide: true
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 2.7
+  Exclude:
+  - '{bin,coverage,pkg,test/fixtures,vendor,tmp}/**/*'
+  - test.rb
+
+Layout/LineLength:
+  Max: 80
+
+Lint/DuplicateBranch:
+  Enabled: false
+
+Lint/EmptyBlock:
+  Enabled: false
+
+Lint/InterpolationCheck:
+  Enabled: false
+
+Lint/MissingSuper:
+  Enabled: false
+
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
+Metrics:
+  Enabled: false
+
+Naming/MethodName:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Enabled: false
+
+Naming/RescuedExceptionsVariableName:
+  PreferredName: error
+
+Style/ExplicitBlockArgument:
+  Enabled: false
+
+Style/FormatString:
+  EnforcedStyle: percent
+
+Style/GuardClause:
+  Enabled: false
+
+Style/IdenticalConditionalBranches:
+  Enabled: false
+
+Style/IfInsideElse:
+  Enabled: false
+
+Style/KeywordParametersOrder:
+  Enabled: false
+
+Style/MissingRespondToMissing:
+  Enabled: false
+
+Style/MutableConstant:
+  Enabled: false
+
+Style/NegatedIfElseCondition:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+
+Style/ParallelAssignment:
+  Enabled: false
+
+Style/PerlBackrefs:
+  Enabled: false
+
+Style/SpecialGlobalVars:
+  Enabled: false

data/CHANGELOG.md

@@ -6,6 +6,22 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 ## [Unreleased]
 
+## [2.4.0] - 2022-05-07
+
+### Added
+
+- [#65](https://github.com/ruby-syntax-tree/syntax_tree/pull/65) - Add a rubocop config at `config/rubocop.yml` that we can ship with the gem so folks can inherit from it to get their styling correct.
+- [#65](https://github.com/ruby-syntax-tree/syntax_tree/pull/65) - Improve hash pattern formatting by a lot - multiple lines are now not so ugly.
+- [#62](https://github.com/ruby-syntax-tree/syntax_tree/issues/62) - Add `options` as a method on `SyntaxTree::RegexpLiteral`, add it to pattern matching, and describe it using the `SyntaxTree::Visitor::FieldVisitor` class.
+- [#69](https://github.com/ruby-syntax-tree/syntax_tree/pull/69) - The `construct_keys` option has been added to every `SyntaxTree::Node` descendant. This allows building a pattern match expression that can be used later. It is meant as a reflection API, not necessarily something that should be eval'd.
+- [#69](https://github.com/ruby-syntax-tree/syntax_tree/pull/69) - You can now call `stree json` to get a JSON representation of your syntax tree.
+- [#69](https://github.com/ruby-syntax-tree/syntax_tree/pull/69) - You can now call `stree match` to get a Ruby pattern matching expression to match against the given input.
+
+### Changed
+
+- [#69](https://github.com/ruby-syntax-tree/syntax_tree/pull/69) - Fixed a long-standing bug with pretty-print where if certain things were required in different orders you could end up with a bug in `PP` when calling pretty-print with a confusing error referring to inspect keys.
+- [#69](https://github.com/ruby-syntax-tree/syntax_tree/pull/69) - `SyntaxTree.read` can now handle an empty file.
+
 ## [2.3.1] - 2022-04-22
 
 ### Changed
@@ -193,7 +209,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 - 🎉 Initial release! 🎉
 
-[unreleased]: https://github.com/ruby-syntax-tree/syntax_tree/compare/v2.3.0...HEAD
+[unreleased]: https://github.com/ruby-syntax-tree/syntax_tree/compare/v2.4.0...HEAD
+[2.4.0]: https://github.com/ruby-syntax-tree/syntax_tree/compare/v2.3.1...v2.4.0
+[2.3.1]: https://github.com/ruby-syntax-tree/syntax_tree/compare/v2.3.0...v2.3.1
 [2.3.0]: https://github.com/ruby-syntax-tree/syntax_tree/compare/v2.2.0...v2.3.0
 [2.2.0]: https://github.com/ruby-syntax-tree/syntax_tree/compare/v2.1.1...v2.2.0
 [2.1.1]: https://github.com/ruby-syntax-tree/syntax_tree/compare/v2.1.0...v2.1.1

data/Gemfile

@@ -3,3 +3,5 @@
 source "https://rubygems.org"
 
 gemspec
+
+gem "rubocop"

data/Gemfile.lock

@@ -1,20 +1,40 @@
 PATH
   remote: .
   specs:
-    syntax_tree (2.3.1)
+    syntax_tree (2.4.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    ast (2.4.2)
     docile (1.4.0)
     minitest (5.15.0)
+    parallel (1.22.1)
+    parser (3.1.2.0)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
     rake (13.0.6)
+    regexp_parser (2.3.1)
+    rexml (3.2.5)
+    rubocop (1.29.0)
+      parallel (~> 1.10)
+      parser (>= 3.1.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.17.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.17.0)
+      parser (>= 3.1.1.0)
+    ruby-progressbar (1.11.0)
     simplecov (0.21.2)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.4)
+    unicode-display_width (2.1.0)
 
 PLATFORMS
   arm64-darwin-21
@@ -27,6 +47,7 @@ DEPENDENCIES
   bundler
   minitest
   rake
+  rubocop
   simplecov
   syntax_tree!
 

data/README.md

@@ -16,6 +16,8 @@ It is built with only standard library dependencies. It additionally ships with
   - [ast](#ast)
   - [check](#check)
   - [format](#format)
+  - [json](#json)
+  - [match](#match)
   - [write](#write)
 - [Library](#library)
   - [SyntaxTree.read(filepath)](#syntaxtreereadfilepath)
@@ -27,6 +29,7 @@ It is built with only standard library dependencies. It additionally ships with
   - [pretty_print(q)](#pretty_printq)
   - [to_json(*opts)](#to_jsonopts)
   - [format(q)](#formatq)
+  - [construct_keys](#construct_keys)
 - [Visitor](#visitor)
   - [visit_method](#visit_method)
 - [Language server](#language-server)
@@ -34,6 +37,9 @@ It is built with only standard library dependencies. It additionally ships with
   - [textDocument/inlayHints](#textdocumentinlayhints)
   - [syntaxTree/visualizing](#syntaxtreevisualizing)
 - [Plugins](#plugins)
+- [Integration](#integration)
+  - [RuboCop](#rubocop)
+  - [VSCode](#vscode)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -122,6 +128,73 @@ For a file that contains `1 + 1`, you will receive:
 1 + 1
 ```
 
+### json
+
+This command will output a JSON representation of the syntax tree that is functionally equivalent to the input. This is mostly used in contexts where you need to access the tree from JavaScript or serialize it over a network.
+
+```sh
+stree json path/to/file.rb
+```
+
+For a file that contains `1 + 1`, you will receive:
+
+```json
+{
+  "type": "program",
+  "location": [1, 0, 1, 6],
+  "statements": {
+    "type": "statements",
+    "location": [1, 0, 1, 6],
+    "body": [
+      {
+        "type": "binary",
+        "location": [1, 0, 1, 5],
+        "left": {
+          "type": "int",
+          "location": [1, 0, 1, 1],
+          "value": "1",
+          "comments": []
+        },
+        "operator": "+",
+        "right": {
+          "type": "int",
+          "location": [1, 4, 1, 5],
+          "value": "1",
+          "comments": []
+        },
+        "comments": []
+      }
+    ],
+    "comments": []
+  },
+  "comments": []
+}
+```
+
+### match
+
+This command will output a Ruby case-match expression that would match correctly against the input.
+
+```sh
+stree match path/to/file.rb
+```
+
+For a file that contains `1 + 1`, you will receive:
+
+```ruby
+SyntaxTree::Program[
+  statements: SyntaxTree::Statements[
+    body: [
+      SyntaxTree::Binary[
+        left: SyntaxTree::Int[value: "1"],
+        operator: :+,
+        right: SyntaxTree::Int[value: "1"]
+      ]
+    ]
+  ]
+]
+```
+
 ### write
 
 This command will format the listed files and write that formatted version back to the source files. Note that this overwrites the original content, to be sure to be using a version control system.
@@ -223,6 +296,27 @@ formatter.output.join
 # => "1 + 1"
 ```
 
+### construct_keys
+
+Every node responds to `construct_keys`, which will return a string that contains a Ruby pattern-matching expression that could be used to match against the current node. It's meant to be used in tooling and through the CLI mostly.
+
+```ruby
+program = SyntaxTree.parse("1 + 1")
+puts program.construct_keys
+
+# SyntaxTree::Program[
+#   statements: SyntaxTree::Statements[            
+#     body: [                                      
+#       SyntaxTree::Binary[                        
+#         left: SyntaxTree::Int[value: "1"],       
+#         operator: :+,                            
+#         right: SyntaxTree::Int[value: "1"]       
+#       ]                                          
+#     ]                                            
+#   ]                                              
+# ] 
+```
+
 ## Visitor
 
 If you want to operate over a set of nodes in the tree but don't want to walk the tree manually, the `Visitor` class makes it easy. `SyntaxTree::Visitor` is an implementation of the double dispatch visitor pattern. It works by the user defining visit methods that process nodes in the tree, which then call back to other visit methods to continue the descent. This is easier shown in code.
@@ -328,6 +422,25 @@ Below are listed all of the "official" plugins hosted under the same GitHub orga
 * [SyntaxTree::JSON](https://github.com/ruby-syntax-tree/syntax_tree-json) for JSON.
 * [SyntaxTree::RBS](https://github.com/ruby-syntax-tree/syntax_tree-rbs) for the [RBS type language](https://github.com/ruby/rbs).
 
+When invoking the CLI, you pass through the list of plugins with the `--plugins` options to the commands that accept them. They should be a comma-delimited list. When the CLI first starts, it will require the files corresponding to those names.
+
+## Integration
+
+Syntax Tree's goal is to seemlessly integrate into your workflow. To this end, it provides a couple of additional tools beyond the CLI and the Ruby library.
+
+### RuboCop
+
+RuboCop and Syntax Tree serve different purposes, but there is overlap with some of RuboCop's functionality. Syntax Tree provides a RuboCop configuration file to disable rules that are redundant with Syntax Tree. To use this configuration file, add the following snippet to the top of your project's `.rubocop.yml`:
+
+```yaml
+inherit_gem:
+  syntax_tree: config/rubocop.yml
+```
+
+### VSCode
+
+To integrate Syntax Tree into VSCode, you should use the official VSCode extension [ruby-syntax-tree/vscode-syntax-tree](https://github.com/ruby-syntax-tree/vscode-syntax-tree).
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/ruby-syntax-tree/syntax_tree.

data/Rakefile

@@ -1,12 +1,34 @@
 # frozen_string_literal: true
 
-require 'bundler/gem_tasks'
-require 'rake/testtask'
+require "bundler/gem_tasks"
+require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << 'test'
-  t.libs << 'lib'
-  t.test_files = FileList['test/**/*_test.rb']
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
 end
 
 task default: :test
+
+FILEPATHS = %w[
+  Gemfile
+  Rakefile
+  syntax_tree.gemspec
+  lib/**/*.rb
+  test/*.rb
+].freeze
+
+task :syntax_tree do
+  $:.unshift File.expand_path("lib", __dir__)
+  require "syntax_tree"
+  require "syntax_tree/cli"
+end
+
+task check: :syntax_tree do
+  exit SyntaxTree::CLI.run(["check"] + FILEPATHS)
+end
+
+task format: :syntax_tree do
+  exit SyntaxTree::CLI.run(["write"] + FILEPATHS)
+end

data/config/rubocop.yml

@@ -0,0 +1,64 @@
+# Disabling all Layout/* rules, as they're unnecessary when the user is using
+# Syntax Tree to handle all of the formatting.
+Layout:
+  Enabled: false
+
+# Re-enable Layout/LineLength because certain cops that most projects use
+# (e.g. Style/IfUnlessModifier) require Layout/LineLength to be enabled.
+# By leaving it disabled, those rules will mis-fire.
+#
+# Users can always override these defaults in their own rubocop.yml files.
+# https://github.com/prettier/plugin-ruby/issues/825
+Layout/LineLength:
+  Enabled: true
+
+Style/MultilineIfModifier:
+  Enabled: false
+
+# Syntax Tree will expand empty methods to put the end keyword on the subsequent
+# line to reduce git diff noise.
+Style/EmptyMethod:
+  EnforcedStyle: expanded
+
+# lambdas that are constructed with the lambda method call cannot be safely
+# turned into lambda literals without removing a method call.
+Style/Lambda:
+  Enabled: false
+
+# When method chains with multiple blocks are chained together, rubocop will let
+# them pass if they're using braces but not if they're using do and end
+# keywords. Because we will break individual blocks down to using keywords if
+# they are multiline, this conflicts with rubocop.
+Style/MultilineBlockChain:
+  Enabled: false
+
+# Syntax Tree by default uses double quotes, so changing the configuration here
+# to match that.
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/QuotedSymbols:
+  EnforcedStyle: double_quotes
+
+# We let users have a little more freedom with symbol and words arrays. If the
+# user only has an individual item like ["value"] then we don't bother
+# converting it because it ends up being just noise.
+Style/SymbolArray:
+  Enabled: false
+
+Style/WordArray:
+  Enabled: false
+
+# We don't support trailing commas in Syntax Tree by default, so just turning
+# these off for now.
+Style/TrailingCommaInArguments:
+  Enabled: false
+
+Style/TrailingCommaInArrayLiteral:
+  Enabled: false
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: false

data/lib/syntax_tree/cli.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module SyntaxTree
+  # Syntax Tree ships with the `stree` CLI, which can be used to inspect and
+  # manipulate Ruby code. This module is responsible for powering that CLI.
   module CLI
     # A utility wrapper around colored strings in the output.
     class Color
@@ -46,7 +48,7 @@ module SyntaxTree
 
     # An action of the CLI that prints out the AST for the given source.
     class AST < Action
-      def run(handler, filepath, source)
+      def run(handler, _filepath, source)
         pp handler.parse(source)
       end
     end
@@ -83,9 +85,7 @@ module SyntaxTree
         warning = "[#{Color.yellow("warn")}] #{filepath}"
         formatted = handler.format(source)
 
-        if formatted != handler.format(formatted)
-          raise NonIdempotentFormatError
-        end
+        raise NonIdempotentFormatError if formatted != handler.format(formatted)
       rescue StandardError
         warn(warning)
         raise
@@ -102,8 +102,8 @@ module SyntaxTree
 
     # An action of the CLI that prints out the doc tree IR for the given source.
     class Doc < Action
-      def run(handler, filepath, source)
-        formatter = Formatter.new([])
+      def run(handler, _filepath, source)
+        formatter = Formatter.new(source, [])
         handler.parse(source).format(formatter)
         pp formatter.groups.first
       end
@@ -111,11 +111,28 @@ module SyntaxTree
 
     # An action of the CLI that formats the input source and prints it out.
     class Format < Action
-      def run(handler, filepath, source)
+      def run(handler, _filepath, source)
         puts handler.format(source)
       end
     end
 
+    # An action of the CLI that converts the source into its equivalent JSON
+    # representation.
+    class Json < Action
+      def run(handler, _filepath, source)
+        object = Visitor::JSONVisitor.new.visit(handler.parse(source))
+        puts JSON.pretty_generate(object)
+      end
+    end
+
+    # An action of the CLI that outputs a pattern-matching Ruby expression that
+    # would match the input given.
+    class Match < Action
+      def run(handler, _filepath, source)
+        puts handler.parse(source).construct_keys
+      end
+    end
+
     # An action of the CLI that formats the input source and writes the
     # formatted output back to the file.
     class Write < Action
@@ -154,6 +171,12 @@ module SyntaxTree
       #{Color.bold("stree format [OPTIONS] [FILE]")}
         Print out the formatted version of the given files
 
+      #{Color.bold("stree json [OPTIONS] [FILE]")}
+        Print out the JSON representation of the given files
+
+      #{Color.bold("stree match [OPTIONS] [FILE]")}
+        Print out a pattern-matching Ruby expression that would match the given files
+
       #{Color.bold("stree help")}
         Display this help message
 
@@ -201,6 +224,10 @@ module SyntaxTree
             Debug.new
           when "doc"
             Doc.new
+          when "j", "json"
+            Json.new
+          when "m", "match"
+            Match.new
           when "f", "format"
             Format.new
           when "w", "write"
@@ -212,7 +239,7 @@ module SyntaxTree
 
         # If we're not reading from stdin and the user didn't supply and
         # filepaths to be read, then we exit with the usage message.
-        if STDIN.tty? && arguments.empty?
+        if $stdin.tty? && arguments.empty?
           warn(HELP)
           return 1
         end
@@ -239,18 +266,11 @@ module SyntaxTree
           action.run(handler, filepath, source)
         rescue Parser::ParseError => error
           warn("Error: #{error.message}")
-
-          if error.lineno
-            highlight_error(error, source)
-          else
-            warn(error.message)
-            warn(error.backtrace)
-          end
-
+          highlight_error(error, source)
           errored = true
         rescue Check::UnformattedError, Debug::NonIdempotentFormatError
           errored = true
-        rescue => error
+        rescue StandardError => error
           warn(error.message)
           warn(error.backtrace)
           errored = true
@@ -268,18 +288,20 @@ module SyntaxTree
       private
 
       def each_file(arguments)
-        if STDIN.tty?
+        if $stdin.tty? || arguments.any?
           arguments.each do |pattern|
-            Dir.glob(pattern).each do |filepath|
-              next unless File.file?(filepath)
-
-              handler = HANDLERS[File.extname(filepath)]
-              source = handler.read(filepath)
-              yield handler, filepath, source
-            end
+            Dir
+              .glob(pattern)
+              .each do |filepath|
+                next unless File.file?(filepath)
+
+                handler = HANDLERS[File.extname(filepath)]
+                source = handler.read(filepath)
+                yield handler, filepath, source
+              end
           end
         else
-          yield HANDLERS[".rb"], :stdin, STDIN.read
+          yield HANDLERS[".rb"], :stdin, $stdin.read
         end
       end
 
@@ -310,7 +332,21 @@ module SyntaxTree
       # Take a line of Ruby source and colorize the output.
       def colorize_line(line)
         require "irb"
-        IRB::Color.colorize_code(line, complete: false, ignore_error: true)
+        IRB::Color.colorize_code(line, **colorize_options)
+      end
+
+      # These are the options we're going to pass into IRB::Color.colorize_code.
+      # Since we support multiple versions of IRB, we're going to need to do
+      # some reflection to make sure we always pass valid options.
+      def colorize_options
+        options = { complete: false }
+
+        parameters = IRB::Color.method(:colorize_code).parameters
+        if parameters.any? { |(_type, name)| name == :ignore_error }
+          options[:ignore_error] = true
+        end
+
+        options
       end
     end
   end

data/lib/syntax_tree/formatter.rb

@@ -41,11 +41,12 @@ module SyntaxTree
 
         # If the node has a stree-ignore comment right before it, then we're
         # going to just print out the node as it was seen in the source.
-        if leading.last&.ignore?
-          doc = text(source[node.location.start_char...node.location.end_char])
-        else
-          doc = node.format(self)
-        end
+        doc =
+          if leading.last&.ignore?
+            text(source[node.location.start_char...node.location.end_char])
+          else
+            node.format(self)
+          end
 
         # Print all comments that were found after the node.
         trailing.each do |comment|