dead_end 2.0.2 → 3.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec9e05716b47eb5d96ac063126a59977d98b8cf3e6f09ba0a0065d425a3c15e5
-  data.tar.gz: c78047c6dd36c1c716e1970e9bec5887bbcaf1fcc0341cbb5c11405043a07105
+  metadata.gz: 88cc140d421e1df16009993e7d7438054dad7a6b6fec740496e92c06c0bc2f6d
+  data.tar.gz: ba736b1459f6c18aed62b566fa8e48ca6a4dd8379bc2dc2d99594c0daf136fb6
 SHA512:
-  metadata.gz: 2eca38b35ef1371cae5fd104fa88dad33d44b17cb6bf29b01b5dea0c650d3d21c0dfbf2b1ac96f0a6f307e7d541cf2a2f7be062d59f1626b16c82f1a2f7d3a3e
-  data.tar.gz: 1a09171cb208465cf48ff5ac0346240d5bf155aebb886c27b6259742f325bc58a0b73ec9998fcbb1544440e6df7363fa7ab57a04dba9e7887207f30916e8c3a9
+  metadata.gz: 3cf585c9f073344d6259478c239fd45b77a5fb7fd1c37c18d3d2a7cf91323b00750cccb18d666935ea20ce2c209137216304429a26aac0bf26fec7aa5440ff14
+  data.tar.gz: 8a818ac4001ce7ec01ae36c4c223f47c7686e111226718cf22e8e2ca9f00a0bb3f3ef6409ad703cb698a67dc62035225973f37ea5f527207c26e705acd4c8f33

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 ## HEAD (unreleased)
 
+## 3.0.3
+
+- Expand explanations coming from additional Ripper errors (https://github.com/zombocom/dead_end/pull/117)
+- Fix explanation involving shorthand syntax for literals like `%w[]` and `%Q{}` (https://github.com/zombocom/dead_end/pull/116)
+
+## 3.0.2
+
+- Fix windows filename detection (https://github.com/zombocom/dead_end/pull/114)
+- Update links on readme and code of conduct (https://github.com/zombocom/dead_end/pull/107)
+
+## 3.0.1
+
+- Fix CLI parsing when flags come before filename (https://github.com/zombocom/dead_end/pull/102)
+
+## 3.0.0
+
+- [Breaking] CLI now outputs to STDOUT instead of STDERR (https://github.com/zombocom/dead_end/pull/98)
+- [Breaking] Remove previously deprecated `require "dead_end/fyi"` interface (https://github.com/zombocom/dead_end/pull/94)
+- Fix double output bug (https://github.com/zombocom/dead_end/pull/99)
+- Fix bug causing poor results (fix #95, fix #88) (https://github.com/zombocom/dead_end/pull/96)
+- DeadEnd is now fired on EVERY syntax error (https://github.com/zombocom/dead_end/pull/94)
+- Output format changes:
+  - Parse errors emitted per-block rather than for the whole document (https://github.com/zombocom/dead_end/pull/94)
+  - The "banner" is now based on lexical analysis rather than parser regex (fix #68, fix #87) (https://github.com/zombocom/dead_end/pull/96)
+
 ## 2.0.2
 
 - Don't print terminal color codes when output is not tty (https://github.com/zombocom/dead_end/pull/91)

data/CODE_OF_CONDUCT.md

@@ -68,7 +68,7 @@ members of the project's leadership.
 ## Attribution
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at [https://contributor-covenant.org/version/1/4][version]
+available at [https://contributor-covenant.org/version/1/4/code-of-conduct/][version]
 
 [homepage]: https://contributor-covenant.org
-[version]: https://contributor-covenant.org/version/1/4/
+[version]: https://contributor-covenant.org/version/1/4/code-of-conduct/

data/Gemfile

@@ -9,3 +9,4 @@ gem "rake", "~> 12.0"
 gem "rspec", "~> 3.0"
 gem "stackprof"
 gem "standard"
+gem "ruby-prof"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    dead_end (2.0.2)
+    dead_end (3.0.3)
 
 GEM
   remote: https://rubygems.org/
@@ -42,6 +42,7 @@ GEM
     rubocop-performance (1.11.5)
       rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
+    ruby-prof (1.4.3)
     ruby-progressbar (1.11.0)
     stackprof (0.2.16)
     standard (1.3.0)
@@ -56,8 +57,9 @@ DEPENDENCIES
   dead_end!
   rake (~> 12.0)
   rspec (~> 3.0)
+  ruby-prof
   stackprof
   standard
 
 BUNDLED WITH
-   2.2.29
+   2.2.30

data/README.md

@@ -2,19 +2,14 @@
 
 An error in your code forces you to stop. DeadEnd helps you find those errors to get you back on your way faster.
 
-    DeadEnd: Unmatched `end` detected
-
-    This code has an unmatched `end`. Ensure that all `end` lines
-    in your code have a matching syntax keyword  (`def`,  `do`, etc.)
-    and that you don't have any extra `end` lines.
-
-    file: path/to/dog.rb
-    simplified:
+```
+Unmatched `end', missing keyword (`do', `def`, `if`, etc.) ?
 
-       3  class Dog
-    ❯  5    defbark
-    ❯  7    end
-      12  end
+  1  class Dog
+❯ 2    defbark
+❯ 4    end
+  5  end
+```
 
 ## Installation in your codebase
 
@@ -50,36 +45,108 @@ To get the CLI and manually search for syntax errors (but not automatically anno
 
 This gives you the CLI command `$ dead_end` for more info run `$ dead_end --help`.
 
+## Editor integration
+
+An extension is available for VSCode:
+
+- Extension: https://marketplace.visualstudio.com/items?itemName=Zombocom.dead-end-vscode
+- GitHub: https://github.com/zombocom/dead_end-vscode
+
 ## What syntax errors does it handle?
 
+Dead end will fire against all syntax errors and can isolate any syntax error. In addition, dead_end attempts to produce human readable descriptions of what needs to be done to resolve the issue. For example:
+
 - Missing `end`:
 
+<!--
 ```ruby
 class Dog
   def bark
     puts "bark"
-
-  def woof
-    puts "woof"
-  end
 end
-# => scratch.rb:8: syntax error, unexpected end-of-input, expecting `end'
 ```
+-->
 
-- Unexpected `end`
+```
+Unmatched keyword, missing `end' ?
 
+❯ 1  class Dog
+❯ 2    def bark
+❯ 4  end
+```
+
+- Missing keyword
+<!--
 ```ruby
 class Dog
   def speak
-    @sounds.each |sound| # Note the missing `do` here
+    @sounds.each |sound|
       puts sound
     end
   end
 end
-# => scratch.rb:7: syntax error, unexpected `end', expecting end-of-input
 ```
+-->
 
-As well as unmatched `|` and unmatched `}`. These errors can be time consuming to debug because Ruby often only tells you the last line in the file. The command `ruby -wc path/to/file.rb` can narrow it down a little bit, but this library does a better job.
+```
+Unmatched `end', missing keyword (`do', `def`, `if`, etc.) ?
+
+  1  class Dog
+  2    def speak
+❯ 3      @sounds.each |sound|
+❯ 5      end
+  6    end
+  7  end
+```
+
+- Missing pair characters (like `{}`, `[]`, `()` , or `|<var>|`)
+<!--
+
+```ruby
+class Dog
+  def speak(sound
+    puts sound
+  end
+end
+```
+-->
+
+```
+Unmatched `(', missing `)' ?
+
+  1  class Dog
+❯ 2    def speak(sound
+❯ 4    end
+  5  end
+```
+
+- Any ambiguous or unknown errors will be annotated by the original ripper error output:
+
+<!--
+class Dog
+  def meals_last_month
+    puts 3 *
+  end
+end
+-->
+
+```
+syntax error, unexpected end-of-input
+
+  1  class Dog
+  2    def meals_last_month
+❯ 3      puts 3 *
+  4    end
+  5  end
+```
+
+## How is it better than `ruby -wc`?
+
+Ruby allows you to syntax check a file with warnings using `ruby -wc`. This emits a parser error instead of a human focused error. Ruby's parse errors attempt to narrow down the location and can tell you if there is a glaring indentation error involving `end`.
+
+The `dead_end` algorithm doesn't just guess at the location of syntax errors, it re-parses the document to prove that it captured them.
+
+This library focuses on the human side of syntax errors. It cares less about why the document could not be parsed (computer problem) and more on what the programmer needs (human problem) to fix the problem.
 
 ## Sounds cool, but why isn't this baked into Ruby directly?
 
@@ -105,9 +172,37 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 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).
 
+### How to debug changes to output display
+
+You can see changes to output against a variety of invalid code by running specs and using the `DEBUG_DISPLAY=1` environment variable. For example:
+
+```
+$ DEBUG_DISPLAY=1 bundle exec rspec spec/ --format=failures
+```
+
+### Run profiler
+
+You can output profiler data to the `tmp` directory by running:
+
+```
+$ DEBUG_PERF=1 bundle exec rspec spec/integration/dead_end_spec.rb
+```
+
+Some outputs are in text format, some are html, the raw marshaled data is available in `raw.rb.marshal`. See https://ruby-prof.github.io/#reports for more info. One interesting one, is the "kcachegrind" interface. To view this on mac:
+
+```
+$ brew install qcachegrind
+```
+
+Open:
+
+```
+$ qcachegrind tmp/last/profile.callgrind.out.<numbers>
+```
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/zombocom/dead_end. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/zombocom/dead_end/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/zombocom/dead_end. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/zombocom/dead_end/blob/main/CODE_OF_CONDUCT.md).
 
 
 ## License
@@ -116,4 +211,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the DeadEnd project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/zombocom/dead_end/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the DeadEnd project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/zombocom/dead_end/blob/main/CODE_OF_CONDUCT.md).

data/exe/dead_end

@@ -1,81 +1,7 @@
 #!/usr/bin/env ruby
 
-require "pathname"
-require "optparse"
 require_relative "../lib/dead_end"
 
-options = {}
-options[:record_dir] = ENV["DEAD_END_RECORD_DIR"]
-
-parser = OptionParser.new do |opts|
-  opts.banner = <<~EOM
-    Usage: dead_end <file> [options]
-
-    Parses a ruby source file and searches for syntax error(s) such as
-    unexpected `end', expecting end-of-input.
-
-    Example:
-
-      $ dead_end dog.rb
-
-      # ...
-
-        ❯ 10  defdog
-        ❯ 15  end
-        ❯ 16
-
-    Env options:
-
-      DEAD_END_RECORD_DIR=<dir>
-
-      When enabled, records the steps used to search for a syntax error to the
-      given directory
-
-    Options:
-  EOM
-
-  opts.version = DeadEnd::VERSION
-
-  opts.on("--help", "Help - displays this message") do |v|
-    puts opts
-    exit
-  end
-
-  opts.on("--record <dir>", "When enabled, records the steps used to search for a syntax error to the given directory") do |v|
-    options[:record_dir] = v
-  end
-
-  opts.on("--terminal", "Enable terminal highlighting") do |v|
-    options[:terminal] = true
-  end
-
-  opts.on("--no-terminal", "Disable terminal highlighting") do |v|
-    options[:terminal] = false
-  end
-end
-parser.parse!
-
-file = ARGV[0]
-
-if file.nil? || file.empty?
-  # Display help if raw command
-  parser.parse! %w[--help]
-end
-
-file = Pathname(file)
-options[:record_dir] = "tmp" if ENV["DEBUG"]
-
-warn "Record dir: #{options[:record_dir]}" if options[:record_dir]
-
-display = DeadEnd.call(
-  source: file.read,
-  filename: file.expand_path,
-  terminal: options.fetch(:terminal, DeadEnd::DEFAULT_VALUE),
-  record_dir: options[:record_dir]
-)
-
-if display.document_ok?
-  exit(0)
-else
-  exit(1)
-end
+DeadEnd::Cli.new(
+  argv: ARGV
+).call

data/lib/dead_end/auto.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../dead_end/internals"
+require_relative "../dead_end"
 
 # Monkey patch kernel to ensure that all `require` calls call the same
 # method
@@ -33,23 +33,3 @@ module Kernel
     DeadEnd.handle_error(e)
   end
 end
-
-# I honestly have no idea why this Object delegation is needed
-# I keep staring at bootsnap and it doesn't have to do this
-# is there a bug in their implementation they haven't caught or
-# am I doing something different?
-class Object
-  private
-
-  def load(path, wrap = false)
-    Kernel.load(path, wrap)
-  rescue SyntaxError => e
-    DeadEnd.handle_error(e)
-  end
-
-  def require(path)
-    Kernel.require(path)
-  rescue SyntaxError => e
-    DeadEnd.handle_error(e)
-  end
-end

data/lib/dead_end/clean_document.rb

@@ -85,17 +85,16 @@ module DeadEnd
   #
   class CleanDocument
     def initialize(source:)
-      @source = source
-      @document = CodeLine.from_source(@source)
+      lines = clean_sweep(source: source)
+      @document = CodeLine.from_source(lines.join, lines: lines)
     end
 
     # Call all of the document "cleaners"
     # and return self
     def call
-      clean_sweep
-        .join_trailing_slash!
-        .join_consecutive!
-        .join_heredoc!
+      join_trailing_slash!
+      join_consecutive!
+      join_heredoc!
 
       self
     end
@@ -122,17 +121,15 @@ module DeadEnd
     #       puts "world"
     #     EOM
     #
-    #     lines = CleanDocument.new(source: source).clean_sweep.lines
+    #     lines = CleanDocument.new(source: source).lines
     #     expect(lines[0].to_s).to eq("\n")
     #     expect(lines[1].to_s).to eq("puts "hello")
     #     expect(lines[2].to_s).to eq("\n")
     #     expect(lines[3].to_s).to eq("puts "world")
     #
-    # WARNING:
-    # If you run this after any of the "join" commands, they
-    # will be un-joined.
+    # Important: This must be done before lexing.
     #
-    # After this change is made, we re-lex the document because
+    # After this change is made, we lex the document because
     # removing comments can change how the doc is parsed.
     #
     # For example:
@@ -142,7 +139,9 @@ module DeadEnd
     #         # comment
     #         where(name: 'schneems')
     #     EOM
-    #     expect(values.count {|v| v.type == :on_ignored_nl}).to eq(1)
+    #     expect(
+    #       values.count {|v| v.type == :on_ignored_nl}
+    #     ).to eq(1)
     #
     # After the comment is removed:
     #
@@ -151,26 +150,18 @@ module DeadEnd
     #
     #         where(name: 'schneems')
     #     EOM
-    #     expect(values.count {|v| v.type == :on_ignored_nl}).to eq(2)
+    #     expect(
+    #      values.count {|v| v.type == :on_ignored_nl}
+    #    ).to eq(2)
     #
-    def clean_sweep
-      source = @document.map do |code_line|
-        # Clean trailing whitespace on empty line
-        if code_line.line.strip.empty?
-          next CodeLine.new(line: "\n", index: code_line.index, lex: [])
+    def clean_sweep(source:)
+      source.lines.map do |line|
+        if line.match?(/^\s*(#[^{].*)?$/) # https://rubular.com/r/LLE10D8HKMkJvs
+          $/
+        else
+          line
         end
-
-        # Remove comments
-        if code_line.lex.detect { |lex| lex.type != :on_sp }&.type == :on_comment
-          next CodeLine.new(line: "\n", index: code_line.index, lex: [])
-        end
-
-        code_line
-      end.join
-
-      @source = source
-      @document = CodeLine.from_source(source)
-      self
+      end
     end
 
     # Smushes all heredoc lines into one line

data/lib/dead_end/cli.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "optparse"
+
+module DeadEnd
+  # All the logic of the exe/dead_end CLI in one handy spot
+  #
+  #   Cli.new(argv: ["--help"]).call
+  #   Cli.new(argv: ["<path/to/file>.rb"]).call
+  #   Cli.new(argv: ["<path/to/file>.rb", "--record=tmp"]).call
+  #   Cli.new(argv: ["<path/to/file>.rb", "--terminal"]).call
+  #
+  class Cli
+    attr_accessor :options
+
+    # ARGV is Everything passed to the executable, does not include executable name
+    #
+    # All other intputs are dependency injection for testing
+    def initialize(argv:, exit_obj: Kernel, io: $stdout, env: ENV)
+      @options = {}
+      @parser = nil
+      options[:record_dir] = env["DEAD_END_RECORD_DIR"]
+      options[:record_dir] = "tmp" if env["DEBUG"]
+      options[:terminal] = DeadEnd::DEFAULT_VALUE
+
+      @io = io
+      @argv = argv
+      @exit_obj = exit_obj
+    end
+
+    def call
+      if @argv.empty?
+        # Display help if raw command
+        parser.parse! %w[--help]
+        return
+      else
+        # Mutates @argv
+        parse
+        return if options[:exit]
+      end
+
+      file_name = @argv.first
+      if file_name.nil?
+        @io.puts "No file given"
+        @exit_obj.exit(1)
+        return
+      end
+
+      file = Pathname(file_name)
+      if !file.exist?
+        @io.puts "file not found: #{file.expand_path} "
+        @exit_obj.exit(1)
+        return
+      end
+
+      @io.puts "Record dir: #{options[:record_dir]}" if options[:record_dir]
+
+      display = DeadEnd.call(
+        io: @io,
+        source: file.read,
+        filename: file.expand_path,
+        terminal: options.fetch(:terminal, DeadEnd::DEFAULT_VALUE),
+        record_dir: options[:record_dir]
+      )
+
+      if display.document_ok?
+        @exit_obj.exit(0)
+      else
+        @exit_obj.exit(1)
+      end
+    end
+
+    def parse
+      parser.parse!(@argv)
+
+      self
+    end
+
+    def parser
+      @parser ||= OptionParser.new do |opts|
+        opts.banner = <<~EOM
+          Usage: dead_end <file> [options]
+
+          Parses a ruby source file and searches for syntax error(s) such as
+          unexpected `end', expecting end-of-input.
+
+          Example:
+
+            $ dead_end dog.rb
+
+            # ...
+
+              ❯ 10  defdog
+              ❯ 15  end
+
+          ENV options:
+
+            DEAD_END_RECORD_DIR=<dir>
+
+            Records the steps used to search for a syntax error
+            to the given directory
+
+          Options:
+        EOM
+
+        opts.version = DeadEnd::VERSION
+
+        opts.on("--help", "Help - displays this message") do |v|
+          @io.puts opts
+          options[:exit] = true
+          @exit_obj.exit
+        end
+
+        opts.on("--record <dir>", "Records the steps used to search for a syntax error to the given directory") do |v|
+          options[:record_dir] = v
+        end
+
+        opts.on("--terminal", "Enable terminal highlighting") do |v|
+          options[:terminal] = true
+        end
+
+        opts.on("--no-terminal", "Disable terminal highlighting") do |v|
+          options[:terminal] = false
+        end
+      end
+    end
+  end
+end

data/lib/dead_end/code_block.rb

@@ -70,8 +70,24 @@ module DeadEnd
     end
 
     def valid?
-      return @valid if @valid != UNSET
-      @valid = DeadEnd.valid?(to_s)
+      if @valid == UNSET
+        # Performance optimization
+        #
+        # If all the lines were previously hidden
+        # and we expand to capture additional empty
+        # lines then the result cannot be invalid
+        #
+        # That means there's no reason to re-check all
+        # lines with ripper (which is expensive).
+        # Benchmark in commit message
+        @valid = if lines.all? { |l| l.hidden? || l.empty? }
+          true
+        else
+          DeadEnd.valid?(lines.map(&:original).join)
+        end
+      else
+        @valid
+      end
     end
 
     def to_s