Enable missing rules and more documentation

Author: kddnewton

.github/workflows/main.yml

@@ -37,7 +37,9 @@ jobs:
         bundler-cache: true
         ruby-version: '3.1'
     - name: Check
-      run: bundle exec rake check
+      run: |
+        bundle exec rake check
+        bundle exec rubocop
 
   automerge:
     name: AutoMerge

.rubocop.yml

@@ -12,9 +12,6 @@ AllCops:
 
 Layout/LineLength:
   Max: 80
-  AllowedPatterns:
-  - '^\s*in '
-  - '^\s*location: Location'
 
 Lint/DuplicateBranch:
   Enabled: false
@@ -25,6 +22,9 @@ Lint/InterpolationCheck:
 Lint/MissingSuper:
   Enabled: false
 
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
 Metrics:
   Enabled: false
 
@@ -72,17 +72,3 @@ Style/PerlBackrefs:
 
 Style/SpecialGlobalVars:
   Enabled: false
-
-###
-
-Lint/AssignmentInCondition:
-  Enabled: false
-
-Lint/UnusedMethodArgument:
-  Enabled: false
-
-Style/Documentation:
-  Enabled: false
-
-Style/StringLiterals:
-  Enabled: false

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)
@@ -34,6 +36,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)
 
@@ -395,6 +400,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.

config/rubocop.yml

@@ -9,13 +9,8 @@ Layout:
 #
 # Users can always override these defaults in their own rubocop.yml files.
 # https://github.com/prettier/plugin-ruby/issues/825
-#
-# We're also explicitly allowing pattern matching to extend beyond the maximum
-# line length, since SyntaxTree prefers putting patterns on a single line.
 Layout/LineLength:
   Enabled: true
-  AllowedPatterns:
-  - '^\s*in '
 
 Style/MultilineIfModifier:
   Enabled: false

lib/syntax_tree.rb

@@ -30,6 +30,10 @@
   end
 end
 
+# Syntax Tree is a suite of tools built on top of the internal CRuby parser. It
+# provides the ability to generate a syntax tree from source, as well as the
+# tools necessary to inspect and manipulate that syntax tree. It can be used to
+# build formatters, linters, language servers, and more.
 module SyntaxTree
   # This holds references to objects that respond to both #parse and #format
   # so that we can use them in the CLI.

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 @@ def failure
 
     # 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
@@ -100,7 +102,7 @@ def failure
 
     # An action of the CLI that prints out the doc tree IR for the given source.
     class Doc < Action
-      def run(handler, filepath, source)
+      def run(handler, _filepath, source)
         formatter = Formatter.new(source, [])
         handler.parse(source).format(formatter)
         pp formatter.groups.first
@@ -109,15 +111,15 @@ def run(handler, filepath, source)
 
     # 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)
+      def run(handler, _filepath, source)
         object = Visitor::JSONVisitor.new.visit(handler.parse(source))
         puts JSON.pretty_generate(object)
       end
@@ -126,7 +128,7 @@ def run(handler, filepath, source)
     # 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)
+      def run(handler, _filepath, source)
         formatter = Formatter.new(source, [])
         Visitor::MatchVisitor.new(formatter).visit(handler.parse(source))
         formatter.flush
@@ -296,7 +298,7 @@ def run(argv)
       private
 
       def each_file(arguments)
-        if $stdin.tty?
+        if $stdin.tty? || arguments.any?
           arguments.each do |pattern|
             Dir
               .glob(pattern)

lib/syntax_tree/language_server.rb

@@ -7,6 +7,11 @@
 require_relative "language_server/inlay_hints"
 
 module SyntaxTree
+  # Syntax Tree additionally ships with a language server conforming to the
+  # language server protocol. It can be invoked through the CLI by running:
+  #
+  #     stree lsp
+  #
   class LanguageServer
     attr_reader :input, :output
 
@@ -21,7 +26,7 @@ def run
           hash[uri] = File.binread(CGI.unescape(URI.parse(uri).path))
         end
 
-      while headers = input.gets("\r\n\r\n")
+      while (headers = input.gets("\r\n\r\n"))
         source = input.read(headers[/Content-Length: (\d+)/i, 1].to_i)
         request = JSON.parse(source, symbolize_names: true)
 

lib/syntax_tree/language_server/inlay_hints.rb

@@ -2,6 +2,13 @@
 
 module SyntaxTree
   class LanguageServer
+    # This class provides inlay hints for the language server. It is loosely
+    # designed around the LSP spec, but existed before the spec was finalized so
+    # is a little different for now.
+    #
+    # For more information, see the spec here:
+    # https://github.com/microsoft/language-server-protocol/issues/956.
+    #
     class InlayHints < Visitor
       attr_reader :stack, :before, :after