syntax_suggest 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3c694e7b419ea1a715d2cccf55e706be86035c2563e2f4506769da76829a65a
-  data.tar.gz: a42f42ceb34fc29e0534072cc25e27e7b416c7a954ec6ccdc75c5748db491e22
+  metadata.gz: 20590130dde6c0a40a17b7d01ad9fca063c7044c83d7f04609f9d75df564f9ce
+  data.tar.gz: 73bed388644be5a7a71fe5ab892c8925d50f9dbcad5d918ca07512ffd85188af
 SHA512:
-  metadata.gz: 755b4e3e2a5bb86ae61b4f29417a0a4f6531dbe5866ce32d56e0cb2452496fb858469bbeb3aa369ca953814e475cb52e93c2273eb54ec203cff98520d10bac07
-  data.tar.gz: 178a7ecd8a04d8f53f1778a331400273a2980f42451942012c3e98d5171ab30c590e76eaf69b6c78d7c63274f8040cce2e4e4f85ad35601c34fe46149420aa44
+  metadata.gz: 42a28115779d75b9ff89e58b2a26a9c4807e834a91f8671ffdb2725f9dea954b017310c3b67a9bfe7b97ea6bdbb28e84c59f8bf5c951b0692e99f74ab3e9a5a3
+  data.tar.gz: 51c04529ff19c2181b7f025ff04165f436afaf22e7c9daffb23767176b48b8216006a9fd669b96a435abd8c9886b046224212e9f6c50435008a8ef677477f771

data/.github/workflows/check_changelog.yml

@@ -13,7 +13,7 @@ jobs:
       !contains(github.event.pull_request.body, '[skip ci]') &&
       !contains(github.event.pull_request.labels.*.name, 'skip changelog')
     steps:
-      - uses: actions/checkout@v3.2.0
+      - uses: actions/checkout@v3.3.0
       - name: Check that CHANGELOG is touched
         run: |
           git fetch origin ${{ github.base_ref }} --depth 1 && \

data/.github/workflows/ci.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3.2.0
+        uses: actions/checkout@v3.3.0
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
@@ -29,16 +29,16 @@ jobs:
           - 2.7
           - '3.0'
           - 3.1
-          - "3.2.0-rc1"
+          - 3.2
           - head
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3.2.0
+        uses: actions/checkout@v3.3.0
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
       - name: test
-        run: bundle exec rake test
+        run: bin/rake test
         continue-on-error: ${{ matrix.ruby == 'head' }}

data/.rspec

@@ -1,3 +1,2 @@
 --format documentation
---color
 --require spec_helper

data/CHANGELOG.md

@@ -1,8 +1,14 @@
 ## HEAD (unreleased)
 
+## 1.0.3
+
+- Output improvement: Handle methods with only newlines or comments in them (https://github.com/ruby/syntax_suggest/pull/179)
+- No longer shows the detail of monkey patch as the document (https://github.com/ruby/syntax_suggest/pull/174)
+- Drop CI for Ruby 3.2.0-rc1, now that 3.2.0 is available (https://github.com/ruby/syntax_suggest/pull/172)
+
 ## 1.0.2
 
-- Drop support or Ruby 3.2.0 preview, now that 3.2.0-rc1 is available (https://github.com/ruby/syntax_suggest/pull/165)
+- Drop support for Ruby 3.2.0 preview, now that 3.2.0-rc1 is available (https://github.com/ruby/syntax_suggest/pull/165)
 - Native support of `SyntaxError#path`, support 3.2.0-preview3 will be dropped with the release of 3.2.0-preview4 (https://github.com/ruby/syntax_suggest/pull/164)
 - Added dependabot for GitHub Actions (https://github.com/ruby/syntax_suggest/pull/160)
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    syntax_suggest (1.0.1)
+    syntax_suggest (1.0.3)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -180,9 +180,20 @@ Any other entrypoints are subject to change without warning. If you want to use
 
 ## Development
 
-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.
+### Handling conflicts with the default gem
 
-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).
+Because `syntax_suggest` is a default gem you can get conflicts when working on this project with Ruby 3.2+. To fix conflicts you can disable loading `syntax_suggest` as a default gem by using then environment variable `RUBYOPT` with the value `--disable=syntax_suggest`. The `RUBYOPT` environment variable works the same as if we had entered those flags directly in the ruby cli (i.e. `ruby --disable=syntax_suggest` is the same as `RUBYOPT="--disable=syntax_suggest" ruby`). It's needed because we don't always directly execute Ruby and RUBYOPT will be picked up when other commands load ruby (`rspec`, `rake`, or `bundle` etc.).
+
+There are some binstubs that already have this done for you. Instead of running `bundle exec rake` you can run `bin/rake`. Binstubs provided:
+
+- `bin/rake`
+- `bin/rspec`
+
+### Installation
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bin/rake install`. To release a new version, update the version number in `version.rb`, and then run `bin/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).
 
 ### How to debug changes to output display
 

data/bin/rake

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Make sure syntax_suggest default gem is not loaded first
+RUBYOPT="${RUBYOPT-} --disable=syntax_suggest"
+RUBYOPT="$RUBYOPT" bundle exec rake "$@"

data/bin/rspec

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Make sure syntax_suggest default gem is not loaded first
+RUBYOPT="${RUBYOPT-} --disable=syntax_suggest"
+RUBYOPT="$RUBYOPT" bundle exec rspec "$@"

data/lib/syntax_suggest/api.rb

@@ -91,7 +91,9 @@ module SyntaxSuggest
     dir = Pathname(dir)
     dir.join(time).tap { |path|
       path.mkpath
-      FileUtils.ln_sf(time, dir.join("last"))
+      alias_dir = dir.join("last")
+      FileUtils.rm_rf(alias_dir) if alias_dir.exist?
+      FileUtils.ln_sf(time, alias_dir)
     }
   end
 

data/lib/syntax_suggest/around_block_scan.rb

@@ -38,36 +38,64 @@ module SyntaxSuggest
       @before_array = []
       @stop_after_kw = false
 
-      @skip_hidden = false
-      @skip_empty = false
-    end
-
-    def skip(name)
-      case name
-      when :hidden?
-        @skip_hidden = true
-      when :empty?
-        @skip_empty = true
-      else
-        raise "Unsupported skip #{name}"
-      end
+      @force_add_hidden = false
+      @force_add_empty = false
+    end
+
+    # When using this flag, `scan_while` will
+    # bypass the block it's given and always add a
+    # line that responds truthy to `CodeLine#hidden?`
+    #
+    # Lines are hidden when they've been evaluated by
+    # the parser as part of a block and found to contain
+    # valid code.
+    def force_add_hidden
+      @force_add_hidden = true
+      self
+    end
+
+    # When using this flag, `scan_while` will
+    # bypass the block it's given and always add a
+    # line that responds truthy to `CodeLine#empty?`
+    #
+    # Empty lines contain no code, only whitespace such
+    # as leading spaces a newline.
+    def force_add_empty
+      @force_add_empty = true
       self
     end
 
+    # Tells `scan_while` to look for mismatched keyword/end-s
+    #
+    # When scanning up, if we see more keywords then end-s it will
+    # stop. This might happen when scanning outside of a method body.
+    # the first scan line up would be a keyword and this setting would
+    # trigger a stop.
+    #
+    # When scanning down, stop if there are more end-s than keywords.
     def stop_after_kw
       @stop_after_kw = true
       self
     end
 
+    # Main work method
+    #
+    # The scan_while method takes a block that yields lines above and
+    # below the block. If the yield returns true, the @before_index
+    # or @after_index are modified to include the matched line.
+    #
+    # In addition to yielding individual lines, the internals of this
+    # object give a mini DSL to handle common situations such as
+    # stopping if we've found a keyword/end mis-match in one direction
+    # or the other.
     def scan_while
       stop_next = false
-
       kw_count = 0
       end_count = 0
       index = before_lines.reverse_each.take_while do |line|
         next false if stop_next
-        next true if @skip_hidden && line.hidden?
-        next true if @skip_empty && line.empty?
+        next true if @force_add_hidden && line.hidden?
+        next true if @force_add_empty && line.empty?
 
         kw_count += 1 if line.is_kw?
         end_count += 1 if line.is_end?
@@ -87,8 +115,8 @@ module SyntaxSuggest
       end_count = 0
       index = after_lines.take_while do |line|
         next false if stop_next
-        next true if @skip_hidden && line.hidden?
-        next true if @skip_empty && line.empty?
+        next true if @force_add_hidden && line.hidden?
+        next true if @force_add_empty && line.empty?
 
         kw_count += 1 if line.is_kw?
         end_count += 1 if line.is_end?
@@ -105,6 +133,33 @@ module SyntaxSuggest
       self
     end
 
+    # Shows surrounding kw/end pairs
+    #
+    # The purpose of showing these extra pairs is due to cases
+    # of ambiguity when only one visible line is matched.
+    #
+    # For example:
+    #
+    #     1  class Dog
+    #     2    def bark
+    #     4    def eat
+    #     5    end
+    #     6  end
+    #
+    # In this case either line 2 could be missing an `end` or
+    # line 4 was an extra line added by mistake (it happens).
+    #
+    # When we detect the above problem it shows the issue
+    # as only being on line 2
+    #
+    #     2    def bark
+    #
+    # Showing "neighbor" keyword pairs gives extra context:
+    #
+    #     2    def bark
+    #     4    def eat
+    #     5    end
+    #
     def capture_neighbor_context
       lines = []
       kw_count = 0
@@ -146,6 +201,20 @@ module SyntaxSuggest
       lines
     end
 
+    # Shows the context around code provided by "falling" indentation
+    #
+    # Converts:
+    #
+    #       it "foo" do
+    #
+    # into:
+    #
+    #   class OH
+    #     def hello
+    #       it "foo" do
+    #     end
+    #   end
+    #
     def on_falling_indent
       last_indent = @orig_indent
       before_lines.reverse_each do |line|
@@ -166,18 +235,79 @@ module SyntaxSuggest
       end
     end
 
-    def scan_neighbors
+    # Scanning is intentionally conservative because
+    # we have no way of rolling back an agressive block (at this time)
+    #
+    # If a block was stopped for some trivial reason, (like an empty line)
+    # but the next line would have caused it to be balanced then we
+    # can check that condition and grab just one more line either up or
+    # down.
+    #
+    # For example, below if we're scanning up, line 2 might cause
+    # the scanning to stop. This is because empty lines might
+    # denote logical breaks where the user intended to chunk code
+    # which is a good place to stop and check validity. Unfortunately
+    # it also means we might have a "dangling" keyword or end.
+    #
+    #   1 def bark
+    #   2
+    #   3 end
+    #
+    # If lines 2 and 3 are in the block, then when this method is
+    # run it would see it is unbalanced, but that acquiring line 1
+    # would make it balanced, so that's what it does.
+    def lookahead_balance_one_line
+      kw_count = 0
+      end_count = 0
+      lines.each do |line|
+        kw_count += 1 if line.is_kw?
+        end_count += 1 if line.is_end?
+      end
+
+      return self if kw_count == end_count # nothing to balance
+
+      # More ends than keywords, check if we can balance expanding up
+      if (end_count - kw_count) == 1 && next_up
+        return self unless next_up.is_kw?
+        return self unless next_up.indent >= @orig_indent
+
+        @before_index = next_up.index
+
+      # More keywords than ends, check if we can balance by expanding down
+      elsif (kw_count - end_count) == 1 && next_down
+        return self unless next_down.is_end?
+        return self unless next_down.indent >= @orig_indent
+
+        @after_index = next_down.index
+      end
+      self
+    end
+
+    # Finds code lines at the same or greater indentation and adds them
+    # to the block
+    def scan_neighbors_not_empty
       scan_while { |line| line.not_empty? && line.indent >= @orig_indent }
     end
 
+    # Returns the next line to be scanned above the current block.
+    # Returns `nil` if at the top of the document already
     def next_up
       @code_lines[before_index.pred]
     end
 
+    # Returns the next line to be scanned below the current block.
+    # Returns `nil` if at the bottom of the document already
     def next_down
       @code_lines[after_index.next]
     end
 
+    # Scan blocks based on indentation of next line above/below block
+    #
+    # Determines indentaion of the next line above/below the current block.
+    #
+    # Normally this is called when a block has expanded to capture all "neighbors"
+    # at the same (or greater) indentation and needs to expand out. For example
+    # the `def/end` lines surrounding a method.
     def scan_adjacent_indent
       before_after_indent = []
       before_after_indent << (next_up&.indent || 0)
@@ -189,6 +319,16 @@ module SyntaxSuggest
       self
     end
 
+    # TODO: Doc or delete
+    #
+    # I don't remember why this is needed, but it's called in code_context.
+    # It's related to the implementation of `capture_neighbor_context` somehow
+    # and that display improvement is only triggered when there's one visible line
+    #
+    # I think the primary purpose is to not include the current line in the
+    # logic evaluation of `capture_neighbor_context`. If that's true, then
+    # we should fix that method to handle this logic instead of only using
+    # it in one place and together.
     def start_at_next_line
       before_index
       after_index
@@ -197,26 +337,39 @@ module SyntaxSuggest
       self
     end
 
+    # Return the currently matched lines as a `CodeBlock`
+    #
+    # When a `CodeBlock` is created it will gather metadata about
+    # itself, so this is not a free conversion. Avoid allocating
+    # more CodeBlock's than needed
     def code_block
       CodeBlock.new(lines: lines)
     end
 
+    # Returns the lines matched by the current scan as an
+    # array of CodeLines
     def lines
       @code_lines[before_index..after_index]
     end
 
+    # Gives the index of the first line currently scanned
     def before_index
       @before_index ||= @orig_before_index
     end
 
+    # Gives the index of the last line currently scanned
     def after_index
       @after_index ||= @orig_after_index
     end
 
+    # Returns an array of all the CodeLines that exist before
+    # the currently scanned block
     private def before_lines
       @code_lines[0...before_index] || []
     end
 
+    # Returns an array of all the CodeLines that exist after
+    # the currently scanned block
     private def after_lines
       @code_lines[after_index.next..-1] || []
     end

data/lib/syntax_suggest/block_expand.rb

@@ -35,30 +35,115 @@ module SyntaxSuggest
       @code_lines = code_lines
     end
 
+    # Main interface. Expand current indentation, before
+    # expanding to a lower indentation
     def call(block)
       if (next_block = expand_neighbors(block))
-        return next_block
+        next_block
+      else
+        expand_indent(block)
       end
-
-      expand_indent(block)
     end
 
+    # Expands code to the next lowest indentation
+    #
+    # For example:
+    #
+    #   1 def dog
+    #   2   print "dog"
+    #   3 end
+    #
+    # If a block starts on line 2 then it has captured all it's "neighbors" (code at
+    # the same indentation or higher). To continue expanding, this block must capture
+    # lines one and three which are at a different indentation level.
+    #
+    # This method allows fully expanded blocks to decrease their indentation level (so
+    # they can expand to capture more code up and down). It does this conservatively
+    # as there's no undo (currently).
     def expand_indent(block)
       AroundBlockScan.new(code_lines: @code_lines, block: block)
-        .skip(:hidden?)
+        .force_add_hidden
         .stop_after_kw
         .scan_adjacent_indent
         .code_block
     end
 
+    # A neighbor is code that is at or above the current indent line.
+    #
+    # First we build a block with all neighbors. If we can't go further
+    # then we decrease the indentation threshold and expand via indentation
+    # i.e. `expand_indent`
+    #
+    # Handles two general cases.
+    #
+    # ## Case #1: Check code inside of methods/classes/etc.
+    #
+    # It's important to note, that not everything in a given indentation level can be parsed
+    # as valid code even if it's part of valid code. For example:
+    #
+    #   1 hash = {
+    #   2   name: "richard",
+    #   3   dog: "cinco",
+    #   4 }
+    #
+    # In this case lines 2 and 3 will be neighbors, but they're invalid until `expand_indent`
+    # is called on them.
+    #
+    # When we are adding code within a method or class (at the same indentation level),
+    # use the empty lines to denote the programmer intended logical chunks.
+    # Stop and check each one. For example:
+    #
+    #   1 def dog
+    #   2   print "dog"
+    #   3
+    #   4   hash = {
+    #   5 end
+    #
+    # If we did not stop parsing at empty newlines then the block might mistakenly grab all
+    # the contents (lines 2, 3, and 4) and report them as being problems, instead of only
+    # line 4.
+    #
+    # ## Case #2: Expand/grab other logical blocks
+    #
+    # Once the search algorithm has converted all lines into blocks at a given indentation
+    # it will then `expand_indent`. Once the blocks that generates are expanded as neighbors
+    # we then begin seeing neighbors being other logical blocks i.e. a block's neighbors
+    # may be another method or class (something with keywords/ends).
+    #
+    # For example:
+    #
+    #   1 def bark
+    #   2
+    #   3 end
+    #   4
+    #   5 def sit
+    #   6 end
+    #
+    # In this case if lines 4, 5, and 6 are in a block when it tries to expand neighbors
+    # it will expand up. If it stops after line 2 or 3 it may cause problems since there's a
+    # valid kw/end pair, but the block will be checked without it.
+    #
+    # We try to resolve this edge case with `lookahead_balance_one_line` below.
     def expand_neighbors(block)
-      expanded_lines = AroundBlockScan.new(code_lines: @code_lines, block: block)
-        .skip(:hidden?)
+      neighbors = AroundBlockScan.new(code_lines: @code_lines, block: block)
+        .force_add_hidden
         .stop_after_kw
-        .scan_neighbors
-        .scan_while { |line| line.empty? } # Slurp up empties
+        .scan_neighbors_not_empty
+
+      # Slurp up empties
+      with_empties = neighbors
+        .scan_while { |line| line.empty? }
+
+      # If next line is kw and it will balance us, take it
+      expanded_lines = with_empties
+        .lookahead_balance_one_line
         .lines
 
+      # Don't allocate a block if it won't be used
+      #
+      # If nothing was taken, return nil to indicate that status
+      # used in `def call` to determine if
+      # we need to expand up/out (`expand_indent`)
       if block.lines == expanded_lines
         nil
       else

data/lib/syntax_suggest/capture_code_context.rb

@@ -76,7 +76,6 @@ module SyntaxSuggest
     #     end
     #   end
     #
-    #
     def capture_falling_indent(block)
       AroundBlockScan.new(
         block: block,

data/lib/syntax_suggest/clean_document.rb

@@ -110,7 +110,7 @@ module SyntaxSuggest
       @document.join
     end
 
-    # Remove comments and whitespace only lines
+    # Remove comments
     #
     # replace with empty newlines
     #
@@ -155,8 +155,10 @@ module SyntaxSuggest
     #    ).to eq(2)
     #
     def clean_sweep(source:)
+      # Match comments, but not HEREDOC strings with #{variable} interpolation
+      # https://rubular.com/r/HPwtW9OYxKUHXQ
       source.lines.map do |line|
-        if line.match?(/^\s*(#[^{].*)?$/) # https://rubular.com/r/LLE10D8HKMkJvs
+        if line.match?(/^\s*#([^{].*|)$/)
           $/
         else
           line

data/lib/syntax_suggest/code_line.rb

@@ -48,12 +48,10 @@ module SyntaxSuggest
       strip_line = line.dup
       strip_line.lstrip!
 
-      if strip_line.empty?
-        @empty = true
-        @indent = 0
+      @indent = if (@empty = strip_line.empty?)
+        line.length - 1 # Newline removed from strip_line is not "whitespace"
       else
-        @empty = false
-        @indent = line.length - strip_line.length
+        line.length - strip_line.length
       end
 
       set_kw_end

data/lib/syntax_suggest/core_ext.rb

@@ -66,9 +66,13 @@ if SyntaxError.method_defined?(:detailed_message)
 else
   autoload :Pathname, "pathname"
 
+  #--
   # Monkey patch kernel to ensure that all `require` calls call the same
   # method
+  #++
   module Kernel
+    # :stopdoc:
+
     module_function
 
     alias_method :syntax_suggest_original_require, :require

data/lib/syntax_suggest/parse_blocks_from_indent_line.rb

@@ -36,8 +36,8 @@ module SyntaxSuggest
     # Builds blocks from bottom up
     def each_neighbor_block(target_line)
       scan = AroundBlockScan.new(code_lines: code_lines, block: CodeBlock.new(lines: target_line))
-        .skip(:empty?)
-        .skip(:hidden?)
+        .force_add_empty
+        .force_add_hidden
         .scan_while { |line| line.indent >= target_line.indent }
 
       neighbors = scan.code_block.lines

data/lib/syntax_suggest/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SyntaxSuggest
-  VERSION = "1.0.2"
+  VERSION = "1.0.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: syntax_suggest
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - schneems
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-20 00:00:00.000000000 Z
+date: 2023-03-17 00:00:00.000000000 Z
 dependencies: []
 description: When you get an "unexpected end" in your syntax this gem helps you find
   it
@@ -33,6 +33,8 @@ files:
 - README.md
 - Rakefile
 - bin/console
+- bin/rake
+- bin/rspec
 - bin/setup
 - exe/syntax_suggest
 - lib/syntax_suggest.rb
@@ -82,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.0.dev
+rubygems_version: 3.4.6
 signing_key:
 specification_version: 4
 summary: Find syntax errors in your source in a snap