ladybug 0.0.1.alpha → 0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 19fccf01c424b4f35e62b84e6d7aaf3978e0253d
-  data.tar.gz: 5a12abd7a1eb3148e9fd067675ffacb4012f4dd4
+  metadata.gz: d05e6df669dd8a7fd238743c6480d6d9e54138a7
+  data.tar.gz: a77994e9bee36a609e79359749047cbccebcf7be
 SHA512:
-  metadata.gz: 481c6763053abdaea1057eba44c38003bc8475010a9684a02c82e5f5e55b217b960f93f29250c19a6cd5306aca4aac8bc6f644c1cd709e86017355a09504f3ac
-  data.tar.gz: 61f3f7a14e828a8192a21836f8f9325ebba844a091390b46e3540673476d8492db06f68f1bf70fa420ee9755beb22308276cdb1aa34abe5356a5dad8190c2f96
+  metadata.gz: a183844d91ee89fbbb524eb5a52c64978787062d00b7e25f4c218f6f2e2401e2fd6ae65523e683d54896db06b425d6f2bbf7519f32d36e44103d624c8c5b57b0
+  data.tar.gz: d50b4ac8ea8079587d4a5be1a7d006f8e2cbe7fb169156103b03878baf10f4501a0859c8ac1f7dc6141d2c40282ef2853823cc3e1c07a51924cd1d05e4ccdd5a

data/README.md

@@ -1 +1,62 @@
-# Ladybug
+# 🐞 ladybug
+
+ladybug is a visual debugger for Ruby web applications that uses
+Chrome Devtools as a user interface.
+
+It aims to provide a rich backend debugging experience in a UI that many
+web developers are already familiar with for debugging frontend Javascript.
+
+**This project is currently in a very early experimental phase.** Expect many limitations and bugs, and use at your own risk. If you try it out, please file
+Github issues or [email me](mailto:gklitt@gmail.com) to help make this a
+more useful tool.
+
+![screenshot](screenshots/demo.png)
+
+## Get started
+
+1) Install the gem:
+
+`gem install --pre ladybug`
+
+2) ladybug is implemented as a Rack middleware, so you'll need to add
+`Ladybug::Middleware` to the Rack middleware stack.
+For example, in Rails 5, add
+the following line to `config/application.rb`:
+
+```
+config.middleware.insert_before(Rack::Sendfile, Ladybug::Middleware)
+```
+
+3) Make sure you're using the puma web server, which is currently the
+only server that ladybug has been tested with.
+
+To use puma in Rails: add `gem 'puma'` to your `Gemfile` and `bundle install`.
+
+4) Then start up your server and try making a request.
+You should see your server program output something like:
+
+`Debug in Chrome: chrome-devtools://devtools/bundled/inspector.html?ws=localhost:3000`
+
+5) Navigate to that URL, and you'll see a Chrome Devtools window.
+In the Sources tab, you can view your Ruby source code.
+If you set a breakpoint and then make another request to your server,
+it should pause on the breakpoint and you'll be able to inspect
+some variables in Devtools.
+
+**Security warning:** This debugger should only be run in local development.
+Running it on a server open to the internet could allow anyone to
+execute code on your server without authenticating.
+
+## Development status
+
+* basic pause/continue breakpoint control is supported, but "step over" and "step into" aren't fully supported yet.
+* inspecting primtive objects like strings and numbers works okay; support for more complex objects is in development.
+* So far, ladybug has only been tested with simple Rails applications running on
+Rails 5 with the puma web server. Eventually it aims to support more Rack
+applications and web servers (and perhaps even non-Rack applications).
+
+## Author
+
+[@geoffreylitt](https://twitter.com/geoffreylitt)
+
+

data/lib/ladybug/debugger.rb

@@ -1,9 +1,20 @@
 # A simple debugger using set_trace_func
 # Allows for external control while in a breakpoint
 
+require 'parser/current'
+Parser::Builders::Default.emit_lambda = true
+Parser::Builders::Default.emit_procarg0 = true
+
+require 'memoist'
+
 module Ladybug
   class Debugger
-    def initialize
+    extend Memoist
+
+    # preload_paths (optional):
+    #   paths to pre-parse into Ruby code so that
+    #   later we can quickly respond to requests for breakpoint locations
+    def initialize(preload_paths: [])
       @breakpoints = []
 
       @to_main_thread = Queue.new
@@ -11,6 +22,15 @@ module Ladybug
 
       @on_pause = -> {}
       @on_resume = -> {}
+
+      @parsed_files = {}
+
+      # Todo: consider thread safety of mutating this hash
+      Thread.new do
+        preload_paths.each do |preload_path|
+          parse(preload_path)
+        end
+      end
     end
 
     def start
@@ -37,6 +57,14 @@ module Ladybug
       @to_main_thread.push({ command: 'step_over' })
     end
 
+    def step_into
+      @to_main_thread.push({ command: 'step_into' })
+    end
+
+    def step_out
+      @to_main_thread.push({ command: 'step_out' })
+    end
+
     def evaluate(expression)
       @to_main_thread.push({
         command: 'eval',
@@ -49,17 +77,34 @@ module Ladybug
       @from_main_thread.pop
     end
 
-    # returns a breakpoint ID
+    # Sets a breakpoint and returns a breakpoint object.
     def set_breakpoint(filename:, line_number:)
+      possible_lines = line_numbers_with_code(filename)
+
+      # It's acceptable for a caller to request setting a breakpoint
+      # on a location where it's not possible to set a breakpoint.
+      # In this case, we set a breakpoint on the next possible location.
+      if !possible_lines.include?(line_number)
+        line_number = possible_lines.sort.find { |ln| ln > line_number }
+      end
+
+      # Sometimes the above check will fail and there's no possible breakpoint.
+      if line_number.nil?
+        raise InvalidBreakpointLocationError,
+              "invalid breakpoint line: #{filename}:#{line_number}"
+      end
+
       breakpoint = {
-        filename: filename,
+        # We need to use the absolute path here
+        # because set_trace_func ends up checking against that
+        filename: File.absolute_path(filename),
         line_number: line_number,
-        id: "filename:#{line_number}"
+        id: "#{filename}:#{line_number}"
       }
 
       @breakpoints.push(breakpoint)
 
-      breakpoint[:id]
+      breakpoint
     end
 
     def remove_breakpoint(breakpoint_id)
@@ -69,11 +114,53 @@ module Ladybug
       @breakpoints.delete_if { |bp| bp[:id] == breakpoint_id }
     end
 
+    # Given a filename line number range of a requested breakpoint,
+    # give the line numbers of possible breakpoints.
+    #
+    # In practice, start and end number tend to be the same when
+    # Chrome devtools is the client.
+    #
+    # A breakpoint can be set at the beginning of any Ruby statement.
+    # (more details in #line_numbers_with_code)
+    def get_possible_breakpoints(path:, start_num:, end_num:)
+      (start_num..end_num).to_a & line_numbers_with_code(path)
+    end
+
     private
 
-    def trace_func
-      @step_over_file = nil
+    # remove ladybug code from a callstack and prepare it for comparison
+    # this is a hack implemenetation for now, can be made better
+    def clean(callstack)
+      callstack.drop_while { |frame| frame.to_s.include? "ladybug" }
+    end
+
+    # If we're in step over/in/out mode,
+    # detect if we should break even if there's not a breakpoint set here
+    def break_on_step?
+      # This is an important early return;
+      # we don't want to do anything w/ the callstack unless
+      # we're looking for a breakpoint, because
+      # that adds time to every single line of code execution
+      # which makes things really slow
+      return false if @break.nil?
+
+      bp_callstack = clean(@breakpoint_callstack)
+      current_callstack = clean(Thread.current.backtrace_locations)
+
+      if @break == 'step_over'
+        return bp_callstack[1].to_s == current_callstack[1].to_s
+      elsif @break == 'step_into'
+        return stacks_equal?(bp_callstack, current_callstack[1..-1])
+      elsif @break == 'step_out'
+        return stacks_equal?(current_callstack, bp_callstack[1..-1])
+      end
+    end
 
+    def stacks_equal?(stack1, stack2)
+      stack1.map(&:to_s) == stack2.map(&:to_s)
+    end
+
+    def trace_func
       proc { |event, filename, line_number, id, binding, klass, *rest|
         # This check is called a lot so perhaps worth making faster,
         # but might not matter much with small number of breakpoints in practice
@@ -81,9 +168,7 @@ module Ladybug
           bp[:filename] == filename && bp[:line_number] == line_number
         end
 
-        break_on_step_over = (@step_over_file == filename)
-
-        if breakpoint_hit || break_on_step_over
+        if breakpoint_hit || break_on_step?
           local_variables =
             binding.local_variables.each_with_object({}) do |lvar, hash|
               hash[lvar] = binding.local_variable_get(lvar)
@@ -129,12 +214,19 @@ module Ladybug
 
             case message[:command]
             when 'continue'
-              @step_over_file = nil
+              @break = nil
               break
             when 'step_over'
-              # todo: does "step over" really mean break in the same file,
-              # or is there are a deeper meaning
-              @step_over_file = filename
+              @break = 'step_over'
+              @breakpoint_callstack = Thread.current.backtrace_locations
+              break
+            when 'step_into'
+              @break = 'step_into'
+              @breakpoint_callstack = Thread.current.backtrace_locations
+              break
+            when 'step_out'
+              @break = 'step_out'
+              @breakpoint_callstack = Thread.current.backtrace_locations
               break
             when 'eval'
               evaluated =
@@ -152,5 +244,58 @@ module Ladybug
         end
       }
     end
+
+    # get valid breakpoint lines for a file, with a memoize cache
+    # todo: we don't really need to cache this; parsing is the slow part
+    def line_numbers_with_code(path)
+      ast = parse(path)
+      single_statement_lines(ast)
+    end
+
+    def parse(path)
+      if !@parsed_files.key?(path)
+        code = File.read(path)
+        @parsed_files[path] = Parser::CurrentRuby.parse(code)
+      end
+
+      @parsed_files[path]
+    end
+
+    # A breakpoint can be set at the beginning of any node where there is no
+    # begin (i.e. multi-line) node anywhere under the node
+    def single_statement_lines(ast)
+      child_types = deep_child_node_types(ast)
+
+      if !child_types.include?(:begin) && !child_types.include?(:kwbegin)
+        expr = ast.loc.expression
+
+        if !expr.nil?
+          expr.begin.line
+        else
+          nil
+        end
+      else
+        ast.children.
+          select { |child| child.is_a? AST::Node }.
+          flat_map { |child| single_statement_lines(child) }.
+          compact.
+          uniq
+      end
+    end
+
+    # Return all unique types of AST nodes under this node,
+    # including the node itself.
+    #
+    # We memoize this because we repeatedly hit this for each AST
+    def deep_child_node_types(ast)
+      types = ast.children.flat_map do |child|
+        deep_child_node_types(child) if child.is_a? AST::Node
+      end.compact + [ast.type]
+
+      types.uniq
+    end
+    memoize :deep_child_node_types
+
+    class InvalidBreakpointLocationError < StandardError; end
   end
 end

data/lib/ladybug/middleware.rb

@@ -16,7 +16,8 @@ module Ladybug
       @scripts = {}
 
       @script_repository = ScriptRepository.new
-      @debugger = Debugger.new
+      @debugger =
+        Debugger.new(preload_paths: @script_repository.all.map(&:path))
       @object_manager = ObjectManager.new
     end
 
@@ -79,8 +80,27 @@ module Ladybug
               scriptSource: File.new(path, "r").read
             }
           elsif data["method"] == "Debugger.getPossibleBreakpoints"
-            # Just echo back the location the browser requested
-            result = { locations: [ data["params"]["start"] ] }
+            script = @script_repository.find(id: data["params"]["start"]["scriptId"])
+
+            # we convert to/from 0-indexed line numbers in Chrome
+            # at the earliest/latest possible moment;
+            # in this gem, lines are 1-indexed
+            start_num = data["params"]["start"]["lineNumber"] + 1
+            end_num = data["params"]["end"]["lineNumber"] + 1
+
+            breakpoint_lines = @debugger.get_possible_breakpoints(
+              path: script.path, start_num: start_num, end_num: end_num
+            )
+
+            locations = breakpoint_lines.map do |breakpoint_line|
+              {
+                scriptId: script.id,
+                lineNumber: breakpoint_line - 1,
+                columnNumber: 0
+              }
+            end
+
+            result = { locations: locations }
           elsif data["method"] == "Debugger.setBreakpointByUrl"
             # Chrome gives us a virtual URL;
             # we need an absolute path to the file to match the API for set_trace_func
@@ -91,23 +111,27 @@ module Ladybug
             line_number = data["params"]["lineNumber"]
             ruby_line_number = line_number + 1
 
-            puts "setting breakpoint on #{script.path}:#{ruby_line_number}"
-
-            breakpoint_id = @debugger.set_breakpoint(
-              filename: script.absolute_path,
-              line_number: ruby_line_number
-            )
+            begin
+              breakpoint = @debugger.set_breakpoint(
+                filename: script.path,
+                line_number: ruby_line_number
+              )
 
-            result = {
-              breakpointId: breakpoint_id,
-              locations: [
-                {
-                  scriptId: script.id,
-                  lineNumber: line_number,
-                  columnNumber: data["params"]["columnNumber"],
-                }
-              ]
-            }
+              result = {
+                breakpointId: breakpoint[:id],
+                locations: [
+                  {
+                    scriptId: script.id,
+                    # todo: need to get these +/- transformations centralized.
+                    # a LineNumber class might be necessary...
+                    lineNumber: breakpoint[:line_number] - 1,
+                    columnNumber: data["params"]["columnNumber"],
+                  }
+                ]
+              }
+            rescue Debugger::InvalidBreakpointLocationError
+              result = {}
+            end
           elsif data["method"] == "Debugger.resume"
             # Synchronously just ack the command;
             # we'll async hear back from the main thread when execution resumes
@@ -118,6 +142,16 @@ module Ladybug
             # we'll async hear back from the main thread when execution resumes
             @debugger.step_over
             result = {}
+          elsif data["method"] == "Debugger.stepInto"
+            # Synchronously just ack the command;
+            # we'll async hear back from the main thread when execution resumes
+            @debugger.step_into
+            result = {}
+          elsif data["method"] == "Debugger.stepOut"
+            # Synchronously just ack the command;
+            # we'll async hear back from the main thread when execution resumes
+            @debugger.step_out
+            result = {}
           elsif data["method"] == "Debugger.evaluateOnCallFrame"
             evaluated = @debugger.evaluate(data["params"]["expression"])
             result = {

metadata

@@ -1,29 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: ladybug
 version: !ruby/object:Gem::Version
-  version: 0.0.1.alpha
+  version: '0.1'
 platform: ruby
 authors:
 - Geoffrey Litt
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-01-21 00:00:00.000000000 Z
+date: 2018-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faye-websocket
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.10.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.10.7
+- !ruby/object:Gem::Dependency
+  name: parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.4.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.4.0.2
+- !ruby/object:Gem::Dependency
+  name: memoist
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.14.0
 description: Debug Ruby code using Chrome Devtools
 email: gklitt@gmail.com
 executables: []
@@ -51,12 +79,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.10
+rubygems_version: 2.6.7
 signing_key: 
 specification_version: 4
 summary: Ladybug