appmap 0.28.1 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8619a5924ba51ee48d76ebfe5c72030629c5338217b4fe659cd0a580eaa6ddb9
-  data.tar.gz: 0d8b1e8fcd41e0785b362350a53c95c5bc0ba5c628371b7b6216315b7ddcd85e
+  metadata.gz: 54b9a05aeb3eea84572b115a6de1106e6743b74046048e3c168f99a75aa9e669
+  data.tar.gz: eb8a690376d833c4bec9f0789c5499f413f7dcb3b1ef111257785bd344861f64
 SHA512:
-  metadata.gz: c4da2cadb6a852b1213d1938b035ca147a939e7dc1378ef435d1e8b4d42d6f5b98e19191ecd2e1d1e48493817117123e0b9167080308dcc9ea5527bb676f436b
-  data.tar.gz: 04c2a36c913a3eec42dcd8aa61e789b9b91fed1e43b4bfe84729c6a7b4451fb1064c6efdba39e3818674df8f9560caa486e1d4c8170f04682938775fbb2c4d7e
+  metadata.gz: 453f06041220ecd0a4fc563ae007e7f8247d3dfcccf49657cbf47ddc53d0175e6834d1dbd89a2338a032d6cfae866929216b58a11bb6f0fe3fd2ea69508d7b2a
+  data.tar.gz: 77f372ad255c3c664c690affa2962958cebd1e8f34579809e4d975fdf57404889d8506f9153d44a95afda297ffe7b1654529252a5293487477e803bdf0cc9608

data/CHANGELOG.md

@@ -1,7 +1,20 @@
+# v0.31.0
+
+* Add the ability to hook methods by default, and optionally add labels to them in the
+  classmap. Use it to hook `ActiveSupport::SecurityUtils.secure_compare`.
+  
+# v0.30.0
+
+* Add support for Minitest.
+
+# v0.29.0
+
+* Add `lib/appmap/record.rb`, which can be `require`d to record the rest of the process.
+
 # v0.28.1
+
 * Fix the `defined_class` recorded in an appmap for an instance method included in a class
   at runtime.
-
 * Only include the `static` attribute on `call` events in an appmap. Determine its value
   based on the receiver of the method call.
 

data/README.md

@@ -3,6 +3,7 @@
 - [Configuration](#configuration)
 - [Running](#running)
   - [RSpec](#rspec)
+  - [Minitest](#minitest)
   - [Cucumber](#cucumber)
   - [Remote recording](#remote-recording)
   - [Ruby on Rails](#ruby-on-rails)
@@ -125,6 +126,29 @@ If you include the `feature` and `feature_group` metadata, these attributes will
 
 If you don't explicitly declare `feature` and `feature_group`, then they will be inferred from the spec name and example descriptions.
 
+## Minitest
+
+To record Minitest tests, follow these additional steps:
+
+1) Require `appmap/minitest` in `test_helper.rb`
+
+```ruby
+require 'appmap/minitest'
+```
+
+2) Run the tests with the environment variable `APPMAP=true`:
+
+```sh-session
+$ APPMAP=true bundle exec -Ilib -Itest test/*
+```
+
+Each Minitest test will output an AppMap file into the directory `tmp/appmap/minitest`. For example:
+
+```
+$ find tmp/appmap/minitest
+Hello_says_hello_when_prompted.appmap.json
+```
+
 ## Cucumber
 
 To record Cucumber tests, follow these additional steps:

data/Rakefile

@@ -122,7 +122,7 @@ end
 Rake::TestTask.new(:minitest) do |t|
   t.libs << 'test'
   t.libs << 'lib'
-  t.test_files = FileList['test/**/*_test.rb']
+  t.test_files = FileList['test/*_test.rb']
 end
 
 task spec: "spec:all"

data/lib/appmap.rb

@@ -8,6 +8,11 @@ rescue NameError
 end
 
 require 'appmap/version'
+require 'appmap/hook'
+require 'appmap/config'
+require 'appmap/trace'
+require 'appmap/class_map'
+require 'appmap/metadata'
 
 module AppMap
   class << self
@@ -34,14 +39,12 @@ module AppMap
     # the load events won't be seen and the hooks won't activate.
     def initialize(config_file_path = 'appmap.yml')
       warn "Configuring AppMap from path #{config_file_path}"
-      require 'appmap/hook'
-      self.configuration = Hook::Config.load_from_file(config_file_path)
-      Hook.hook(configuration)
+      self.configuration = Config.load_from_file(config_file_path)
+      Hook.new(configuration).enable
     end
 
     # tracing can be used to start tracing, stop tracing, and record events.
     def tracing
-      require 'appmap/trace'
       @tracing ||= Trace::Tracing.new
     end
 
@@ -68,14 +71,12 @@ module AppMap
 
     # class_map builds a class map from a config and a list of Ruby methods.
     def class_map(methods)
-      require 'appmap/class_map'
       ClassMap.build_from_methods(configuration, methods)
     end
 
     # detect_metadata returns default metadata detected from the Ruby system and from the
     # filesystem.
     def detect_metadata
-      require 'appmap/metadata'
       @metadata ||= Metadata.detect.freeze
       @metadata.deep_dup
     end

data/lib/appmap/class_map.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'active_support/core_ext'
-
 module AppMap
   class ClassMap
     module HasChildren
@@ -50,7 +48,7 @@ module AppMap
         end
       end
       Function = Struct.new(:name) do
-        attr_accessor :static, :location
+        attr_accessor :static, :location, :labels
 
         def type
           'function'
@@ -61,8 +59,9 @@ module AppMap
             name: name,
             type: type,
             location: location,
-            static: static
-          }
+            static: static,
+            labels: labels
+          }.delete_if {|k,v| v.nil?}
         end
       end
     end
@@ -71,27 +70,17 @@ module AppMap
       def build_from_methods(config, methods)
         root = Types::Root.new
         methods.each do |method|
-          package = package_for_method(config.packages, method)
-          add_function root, package.path, method
+          package = config.package_for_method(method) \
+            or raise "No package found for method #{method}"
+          add_function root, package, method
         end
         root.children.map(&:to_h)
       end
 
       protected
 
-      def package_for_method(packages, method)
-        location = method.method.source_location
-        location_file, = location
-        location_file = location_file[Dir.pwd.length + 1..-1] if location_file.index(Dir.pwd) == 0
-
-        packages.find do |pkg|
-          (location_file.index(pkg.path) == 0) &&
-            !pkg.exclude.find { |p| location_file.index(p) }
-        end or raise "No package found for method #{method}"
-      end
-
-      def add_function(root, package_name, method)
-        location = method.method.source_location
+      def add_function(root, package, method)
+        location = method.source_location
         location_file, lineno = location
         location_file = location_file[Dir.pwd.length + 1..-1] if location_file.index(Dir.pwd) == 0
 
@@ -99,7 +88,7 @@ module AppMap
 
         object_infos = [
           {
-            name: package_name,
+            name: package.path,
             type: 'package'
           }
         ]
@@ -109,12 +98,15 @@ module AppMap
             type: 'class'
           }
         end
-        object_infos << {
-          name: method.method.name,
+        function_info = {
+          name: method.name,
           type: 'function',
           location: [ location_file, lineno ].join(':'),
           static: static
         }
+        function_info[:labels] = package.labels if package.labels
+        object_infos << function_info
+        
         parent = root
         object_infos.each do |info|
           parent = find_or_create parent.children, info do

data/lib/appmap/config.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module AppMap
+  Package = Struct.new(:path, :exclude, :labels) do
+    def initialize(path, exclude, labels = nil)
+      super
+    end
+    
+    def to_h
+      {
+        path: path,
+        exclude: exclude.blank? ? nil : exclude,
+        labels: labels.blank? ? nil : labels
+      }.compact
+    end
+  end
+
+  class Config
+    # Methods that should always be hooked, with their containing
+    # package and labels that should be applied to them.
+    HOOKED_METHODS = {
+      'ActiveSupport::SecurityUtils' => {
+        secure_compare: Package.new('active_support', nil, ['security'])
+      },
+      'OpenSSL::X509::Certificate' => {
+        sign: Package.new('openssl', nil, ['security'])
+      }
+    }
+
+    attr_reader :name, :packages
+    def initialize(name, packages = [])
+      @name = name
+      @packages = packages
+    end
+
+    class << self
+      # Loads configuration data from a file, specified by the file name.
+      def load_from_file(config_file_name)
+        require 'yaml'
+        load YAML.safe_load(::File.read(config_file_name))
+      end
+
+      # Loads configuration from a Hash.
+      def load(config_data)
+        packages = (config_data['packages'] || []).map do |package|
+          Package.new(package['path'], package['exclude'] || [])
+        end
+        Config.new config_data['name'], packages
+      end
+    end
+
+    def to_h
+      {
+        name: name,
+        packages: packages.map(&:to_h)
+      }
+    end
+
+    def package_for_method(method)
+      location = method.source_location
+      location_file, = location
+      return unless location_file
+
+      defined_class,_,method_name = Hook.qualify_method_name(method)
+      hooked_method = find_hooked_method(defined_class, method_name)
+      return hooked_method if hooked_method
+      
+      location_file = location_file[Dir.pwd.length + 1..-1] if location_file.index(Dir.pwd) == 0
+      packages.find do |pkg|
+        (location_file.index(pkg.path) == 0) &&
+          !pkg.exclude.find { |p| location_file.index(p) }
+      end
+    end
+
+    def included_by_location?(method)
+      !!package_for_method(method)
+    end
+
+    def always_hook?(defined_class, method_name)
+      !!find_hooked_method(defined_class, method_name)
+    end
+
+    def find_hooked_method(defined_class, method_name)
+      find_hooked_class(defined_class)[method_name]
+    end
+    
+    def find_hooked_class(defined_class)
+      HOOKED_METHODS[defined_class] || {}
+    end
+  end
+end

data/lib/appmap/hook.rb

@@ -6,161 +6,125 @@ module AppMap
   class Hook
     LOG = false
 
-    Package = Struct.new(:path, :exclude) do
-      def to_h
-        {
-          path: path,
-          exclude: exclude.blank? ? nil : exclude
-        }.compact
+    HOOK_DISABLE_KEY = 'AppMap::Hook.disable'
+
+    class << self
+      # Return the class, separator ('.' or '#'), and method name for
+      # the given method.
+      def qualify_method_name(method)
+        if method.owner.singleton_class?
+          # Singleton class names can take two forms:
+          # #<Class:Foo> or
+          # #<Class:#<Bar:0x0123ABC>>. Retrieve the name of
+          # the class from the string.
+          # 
+          # (There really isn't a better way to do this. The
+          # singleton's reference to the class it was created
+          # from is stored in an instance variable named
+          # '__attached__'. It doesn't have the '@' prefix, so
+          # it's internal only, and not accessible from user
+          # code.)
+          class_name = /#<Class:((#<(?<cls>.*?):)|((?<cls>.*?)>))/.match(method.owner.to_s)['cls']
+          [ class_name, '.', method.name ]
+        else
+          [ method.owner.name, '#', method.name ]
+        end
       end
     end
 
-    Config = Struct.new(:name, :packages) do
-      class << self
-        # Loads configuration data from a file, specified by the file name.
-        def load_from_file(config_file_name)
-          require 'yaml'
-          load YAML.safe_load(::File.read(config_file_name))
-        end
+    attr_reader :config
+    def initialize(config)
+      @config = config
+    end
 
-        # Loads configuration from a Hash.
-        def load(config_data)
-          packages = (config_data['packages'] || []).map do |package|
-            Package.new(package['path'], package['exclude'] || [])
-          end
-          Config.new config_data['name'], packages
-        end
+    # Observe class loading and hook all methods which match the config.
+    def enable &block
+      before_hook = lambda do |defined_class, method, receiver, args|
+        require 'appmap/event'
+        call_event = AppMap::Event::MethodCall.build_from_invocation(defined_class, method, receiver, args)
+        AppMap.tracing.record_event call_event, defined_class: defined_class, method: method
+        [ call_event, Time.now ]
       end
 
-      def initialize(name, packages = [])
-        super name, packages || []
+      after_hook = lambda do |call_event, defined_class, method, start_time, return_value, exception|
+        require 'appmap/event'
+        elapsed = Time.now - start_time
+        return_event = AppMap::Event::MethodReturn.build_from_invocation \
+                                                     defined_class, method, call_event.id, elapsed, return_value, exception
+        AppMap.tracing.record_event return_event
       end
 
-      def to_h
-        {
-          name: name,
-          packages: packages.map(&:to_h)
-        }
+      with_disabled_hook = lambda do |&fn|
+        # Don't record functions, such as to_s and inspect, that might be called
+        # by the fn. Otherwise there can be a stack overflow.
+        Thread.current[HOOK_DISABLE_KEY] = true
+        begin
+          fn.call
+        ensure
+          Thread.current[HOOK_DISABLE_KEY] = false
+        end
       end
-    end
 
-    HOOK_DISABLE_KEY = 'AppMap::Hook.disable'
+      tp = TracePoint.new(:end) do |tp|
+        hook = self
+        cls = tp.self
 
-    class << self
-      # Observe class loading and hook all methods which match the config.
-      def hook(config = AppMap.configure)
-        package_include_paths = config.packages.map(&:path)
-        package_exclude_paths = config.packages.map do |pkg|
-          pkg.exclude.map do |exclude|
-            File.join(pkg.path, exclude)
-          end
-        end.flatten
+        instance_methods = cls.public_instance_methods(false)
+        class_methods = cls.singleton_class.public_instance_methods(false) - instance_methods
 
-        before_hook = lambda do |defined_class, method, receiver, args|
-          require 'appmap/event'
-          call_event = AppMap::Event::MethodCall.build_from_invocation(defined_class, method, receiver, args)
-          AppMap.tracing.record_event call_event, defined_class: defined_class, method: method
-          [ call_event, Time.now ]
-        end
+        hook_method = lambda do |cls|
+          lambda do |method_id|
+            next if method_id.to_s =~ /_hooked_by_appmap$/
 
-        after_hook = lambda do |call_event, defined_class, method, start_time, return_value, exception|
-          require 'appmap/event'
-          elapsed = Time.now - start_time
-          return_event = AppMap::Event::MethodReturn.build_from_invocation \
-            defined_class, method, call_event.id, elapsed, return_value, exception
-          AppMap.tracing.record_event return_event
-        end
+            method = cls.public_instance_method(method_id)
+            disasm = RubyVM::InstructionSequence.disasm(method)
+            # Skip methods that have no instruction sequence, as they are obviously trivial.
+            next unless disasm
 
-        with_disabled_hook = lambda do |&fn|
-          # Don't record functions, such as to_s and inspect, that might be called
-          # by the fn. Otherwise there can be a stack oveflow.
-          Thread.current[HOOK_DISABLE_KEY] = true
-          begin
-            fn.call
-          ensure
-            Thread.current[HOOK_DISABLE_KEY] = false
-          end
-        end
+            defined_class, method_symbol, method_name = Hook.qualify_method_name(method)
+            method_display_name = [defined_class, method_symbol, method_name].join
 
-        TracePoint.trace(:end) do |tp|
-          cls = tp.self
-
-          instance_methods = cls.public_instance_methods(false)
-          class_methods = cls.singleton_class.public_instance_methods(false) - instance_methods
-
-          hook_method = lambda do |cls|
-            lambda do |method_id|
-              next if method_id.to_s =~ /_hooked_by_appmap$/
-
-              method = cls.public_instance_method(method_id)
-              location = method.source_location
-              location_file, = location
-              next unless location_file
-
-              location_file = location_file[Dir.pwd.length + 1..-1] if location_file.index(Dir.pwd) == 0
-              match = package_include_paths.find { |p| location_file.index(p) == 0 }
-              match &&= !package_exclude_paths.find { |p| location_file.index(p) }
-              next unless match
-
-              disasm = RubyVM::InstructionSequence.disasm(method)
-              # Skip methods that have no instruction sequence, as they are obviously trivial.
-              next unless disasm
-
-              defined_class, method_symbol = if method.owner.singleton_class?
-                # Singleton class names can take two forms:
-                # #<Class:Foo> or
-                # #<Class:#<Bar:0x0123ABC>>. Retrieve the name of
-                # the class from the string.
-                # 
-                # (There really isn't a better way to do this. The
-                # singleton's reference to the class it was created
-                # from is stored in an instance variable named
-                # '__attached__'. It doesn't have the '@' prefix, so
-                # it's internal only, and not accessible from user
-                # code.)
-                class_name = /#<Class:((#<(?<cls>.*?):)|((?<cls>.*?)>))/.match(method.owner.to_s)['cls']
-                [ class_name, '.' ]
-              else
-                [ method.owner.name, '#' ]
-              end
-              
-              method_display_name = "#{defined_class}#{method_symbol}#{method.name}"
-              # Don't try and trace the tracing method or there will be a stack overflow
-              # in the defined hook method.
-              next if method_display_name == "AppMap.tracing"
+            # Don't try and trace the AppMap methods or there will be
+            # a stack overflow in the defined hook method.
+            next if /\AAppMap[:\.]/.match?(method_display_name) 
 
-              warn "AppMap: Hooking #{method_display_name}" if LOG
+            next unless \
+              config.always_hook?(defined_class, method_name) ||
+              config.included_by_location?(method)
 
-              cls.define_method method_id do |*args, &block|
-                base_method = method.bind(self).to_proc
+            warn "AppMap: Hooking #{method_display_name}" if LOG
 
-                hook_disabled = Thread.current[HOOK_DISABLE_KEY]
-                enabled = true if !hook_disabled && AppMap.tracing.enabled?
-                return base_method.call(*args, &block) unless enabled
+            cls.define_method method_id do |*args, &block|
+              base_method = method.bind(self).to_proc
 
-                call_event, start_time = with_disabled_hook.call do
-                  before_hook.call(defined_class, method, self, args)
-                end
-                return_value = nil
-                exception = nil
-                begin
-                  return_value = base_method.call(*args, &block)
-                rescue
-                  exception = $ERROR_INFO
-                  raise
-                ensure
-                  with_disabled_hook.call do
-                    after_hook.call(call_event, defined_class, method, start_time, return_value, exception)
-                  end
+              hook_disabled = Thread.current[HOOK_DISABLE_KEY]
+              enabled = true if !hook_disabled && AppMap.tracing.enabled?
+              return base_method.call(*args, &block) unless enabled
+
+              call_event, start_time = with_disabled_hook.call do
+                before_hook.call(defined_class, method, self, args)
+              end
+              return_value = nil
+              exception = nil
+              begin
+                return_value = base_method.call(*args, &block)
+              rescue
+                exception = $ERROR_INFO
+                raise
+              ensure
+                with_disabled_hook.call do
+                  after_hook.call(call_event, defined_class, method, start_time, return_value, exception)
                 end
               end
             end
+          end
         end
 
         instance_methods.each(&hook_method.call(cls))
         class_methods.each(&hook_method.call(cls.singleton_class))
       end
-      end
+
+      tp.enable(&block)
     end
   end
 end