appmap 0.31.0 → 0.34.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54b9a05aeb3eea84572b115a6de1106e6743b74046048e3c168f99a75aa9e669
-  data.tar.gz: eb8a690376d833c4bec9f0789c5499f413f7dcb3b1ef111257785bd344861f64
+  metadata.gz: 81605d2c95140e963991e04af89235ee903cce0e3a86b2477f0f80961704e2d6
+  data.tar.gz: 7e526d9ffbc559bb3968b8a973dcd757147676d17a5028f737192fd8956d1b43
 SHA512:
-  metadata.gz: 453f06041220ecd0a4fc563ae007e7f8247d3dfcccf49657cbf47ddc53d0175e6834d1dbd89a2338a032d6cfae866929216b58a11bb6f0fe3fd2ea69508d7b2a
-  data.tar.gz: 77f372ad255c3c664c690affa2962958cebd1e8f34579809e4d975fdf57404889d8506f9153d44a95afda297ffe7b1654529252a5293487477e803bdf0cc9608
+  metadata.gz: 6a34ba2662d48a7e0083e16d6abe4693b57711f9ac0020da6631ca6c40172aeb8f3ef734edd504cec00f2f437742e45fc0cf631b425cb960c9d51239556bc461
+  data.tar.gz: 156f126aac6f63e819c175d6b4d481679cbced9184007871c12fb174f187198afd8e7788befc4ab0ff35b10293e1e163eee25a985b35bd93853c03aa8268d192

data/.gitignore

@@ -14,4 +14,4 @@ Gemfile.lock
 appmap.json
 .vscode
 .byebug_history
-
+/lib/appmap/appmap.bundle

data/.rbenv-gemsets

@@ -0,0 +1 @@
+appmap-ruby

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+# v0.34.2
+* Add an extension that gets the name of the owner of a singleton method without calling
+  any methods that may have been redefined (e.g. `#to_s` or `.name`).
+  
+# v0.34.1
+* Ensure that capturing events doesn't change the behavior of a hooked method that uses
+  `Time.now`. For example, if a test expects that `Time.now` will be called a certain
+  number of times by a hooked method, that expectation will now be met.
+* Make sure `appmap/cucumber` requires `appmap`.
+
+# v0.34.0
+
+* Records builtin security and I/O methods from `OpenSSL`, `Net`, and `IO`.
+
+# v0.33.0
+
+* Added command `AppMap.open` to open an AppMap in the browser.
+
+# v0.32.0
+
+* Removes un-necessary fields from `return` events.
+
 # v0.31.0
 
 * Add the ability to hook methods by default, and optionally add labels to them in the

data/README.md

@@ -33,7 +33,7 @@ There are several ways to record AppMaps of your Ruby program using the `appmap`
 
 Once you have recorded some AppMaps (for example, by running RSpec tests), you use the `appland upload` command
 to upload them to the AppLand server. This command, and some others, is provided
-by the [AppLand CLI](https://github.com/applandinc/appland-cli/releases), to
+by the [AppLand CLI](https://github.com/applandinc/appland-cli/releases).
 Then, on the [AppLand website](https://app.land), you can
 visualize the design of your code and share links with collaborators.
 
@@ -87,12 +87,25 @@ Each entry in the `packages` list is a YAML object which has the following keys:
 
 To record RSpec tests, follow these additional steps:
 
-1) Require `appmap/rspec` in your `spec_helper.rb`.
+1) Require `appmap/rspec` in your `spec_helper.rb` before any other classes are loaded.
 
 ```ruby
 require 'appmap/rspec'
 ```
 
+Note that `spec_helper.rb` in a Rails project typically loads the application's classes this way:
+
+```ruby
+require File.expand_path("../../config/environment", __FILE__)
+```
+
+and `appmap/rspec` must be required before this:
+
+```ruby
+require 'appmap/rspec'
+require File.expand_path("../../config/environment", __FILE__)
+```
+
 2) *Optional* Add `feature: '<feature name>'` and `feature_group: '<feature group name>'` annotations to your 
    examples. 
 
@@ -136,6 +149,19 @@ To record Minitest tests, follow these additional steps:
 require 'appmap/minitest'
 ```
 
+Note that `test_helper.rb` in a Rails project typically loads the application's classes this way:
+
+```ruby
+require_relative '../config/environment'
+```
+
+and `appmap/rspec` must be required before this:
+
+```ruby
+require 'appmap/rspec'
+require_relative '../config/environment'
+```
+
 2) Run the tests with the environment variable `APPMAP=true`:
 
 ```sh-session
@@ -159,6 +185,8 @@ To record Cucumber tests, follow these additional steps:
 require 'appmap/cucumber'
 ```
 
+Be sure to require it before `config/environment` is required.
+
 2) Create an `Around` hook in `support/hooks.rb` to record the scenario:
 
 
@@ -239,7 +267,13 @@ $ bundle config local.appmap $(pwd)
 Run the tests via `rake`:
 ```
 $ bundle exec rake test
-```  
+```
+
+The `test` target will build the native extension first, then run the tests. If you need
+to build the extension separately, run
+```
+$ bundle exec rake compile
+```
 
 ## Using fixture apps
 
@@ -258,7 +292,7 @@ resources such as a PostgreSQL database.
 To build the fixture container images, first run:
 
 ```sh-session
-$ bundle exec rake fixtures:all
+$ bundle exec rake build:fixtures:all
 ```
 
 This will build the `appmap.gem`, along with a Docker image for each fixture app.

data/Rakefile

@@ -6,6 +6,13 @@ require 'rdoc/task'
 
 require 'open3'
 
+require "rake/extensiontask"
+
+desc 'build the native extension'
+Rake::ExtensionTask.new("appmap") do |ext|
+  ext.lib_dir = "lib/appmap"
+end
+
 namespace 'gem' do
   require 'bundler/gem_tasks'
 end
@@ -104,7 +111,7 @@ end
 namespace :spec do
   RUBY_VERSIONS.each do |ruby_version|
     desc ruby_version
-    task ruby_version, [:specs] => ["build:fixtures:#{ruby_version}:all"] do |_, task_args|
+    task ruby_version, [:specs] => ["compile", "build:fixtures:#{ruby_version}:all"] do |_, task_args|
       run_specs(ruby_version, task_args)
     end.tap do|t|
       desc "Run all specs"
@@ -119,13 +126,13 @@ Rake::RDocTask.new do |rd|
   rd.title = 'AppMap'
 end
 
-Rake::TestTask.new(:minitest) do |t|
+Rake::TestTask.new(minitest: 'compile') do |t|
   t.libs << 'test'
   t.libs << 'lib'
   t.test_files = FileList['test/*_test.rb']
 end
 
-task spec: "spec:all"
+task spec: %i[spec:all]
 
 task test: %i[spec:all minitest]
 

data/appmap.gemspec

@@ -18,6 +18,8 @@ Gem::Specification.new do |spec|
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = `git ls-files --no-deleted`.split("
 ")
+  spec.extensions << "ext/appmap/extconf.rb"
+
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
@@ -26,6 +28,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'faraday'
   spec.add_dependency 'gli'
   spec.add_dependency 'parser'
+  spec.add_dependency 'rack'
 
   spec.add_development_dependency 'bundler', '~> 1.16'
   spec.add_development_dependency 'minitest', '~> 5.0'
@@ -33,6 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '>= 12.3.3'
   spec.add_development_dependency 'rdoc'
   spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency "rake-compiler"
 
   # Testing
   spec.add_development_dependency 'climate_control'
@@ -41,4 +45,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'selenium-webdriver'
   spec.add_development_dependency 'webdrivers', '~> 4.0'
+  spec.add_development_dependency 'timecop'
 end

data/ext/appmap/appmap.c

@@ -0,0 +1,26 @@
+#include <ruby.h>
+#include <ruby/intern.h>
+
+// Seems like CLASS_OR_MODULE_P should really be in a header file in
+// the ruby source -- it's in object.c and duplicated in eval.c.  In
+// the future, we'll fail if it does get moved to a header.
+#define CLASS_OR_MODULE_P(obj) \
+    (!SPECIAL_CONST_P(obj) && \
+     (BUILTIN_TYPE(obj) == T_CLASS || BUILTIN_TYPE(obj) == T_MODULE))
+
+static VALUE singleton_method_owner_name(VALUE klass, VALUE method)
+{
+  VALUE owner = rb_funcall(method, rb_intern("owner"), 0);
+  VALUE attached = rb_ivar_get(owner, rb_intern("__attached__"));
+  if (!CLASS_OR_MODULE_P(attached)) {
+    attached = rb_funcall(attached, rb_intern("class"), 0);
+  }
+  return rb_mod_name(attached);
+}
+    
+void Init_appmap() {
+  VALUE appmap = rb_define_module("AppMap");
+  VALUE hook = rb_define_class_under(appmap, "Hook", rb_cObject);
+
+  rb_define_singleton_method(hook, "singleton_method_owner_name", singleton_method_owner_name, 1);
+}

data/ext/appmap/extconf.rb

@@ -0,0 +1,6 @@
+require "mkmf"
+
+$CFLAGS='-Werror'
+extension_name = "appmap"
+dir_config(extension_name)
+create_makefile(File.join(extension_name, extension_name))

data/lib/appmap.rb

@@ -13,19 +13,24 @@ require 'appmap/config'
 require 'appmap/trace'
 require 'appmap/class_map'
 require 'appmap/metadata'
+require 'appmap/util'
+require 'appmap/open'
+
+# load extension
+require 'appmap/appmap'
 
 module AppMap
   class << self
     @configuration = nil
     @configuration_file_path = nil
 
-    # configuration gets the configuration. If there is no configuration, the default
+    # Gets the configuration. If there is no configuration, the default
     # configuration is initialized.
     def configuration
-      @configuration ||= configure
+      @configuration ||= initialize
     end
 
-    # configuration= sets the configuration. This is only expected to happen once per
+    # Sets the configuration. This is only expected to happen once per
     # Ruby process.
     def configuration=(config)
       warn 'AppMap is already configured' if @configuration && config
@@ -33,22 +38,24 @@ module AppMap
       @configuration = config
     end
 
-    # initialize configures AppMap for recording. Default behavior is to configure from "appmap.yml".
+    # Configures AppMap for recording. Default behavior is to configure from "appmap.yml".
     # This method also activates the code hooks which record function calls as trace events.
     # Call this function before the program code is loaded by the Ruby VM, otherwise
     # 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}"
-      self.configuration = Config.load_from_file(config_file_path)
-      Hook.new(configuration).enable
+      Config.load_from_file(config_file_path).tap do |configuration|
+        self.configuration = configuration
+        Hook.new(configuration).enable
+      end
     end
 
-    # tracing can be used to start tracing, stop tracing, and record events.
+    # Used to start tracing, stop tracing, and record events.
     def tracing
       @tracing ||= Trace::Tracing.new
     end
 
-    # record records the events which occur while processing a block,
+    # Records the events which occur while processing a block,
     # and returns an AppMap as a Hash.
     def record
       tracer = tracing.trace
@@ -69,12 +76,18 @@ module AppMap
       }
     end
 
-    # class_map builds a class map from a config and a list of Ruby methods.
+    # Uploads an AppMap to the AppLand website and displays it.
+    def open(appmap = nil, &block)
+      appmap ||= AppMap.record(&block)
+      AppMap::Open.new(appmap).perform
+    end
+
+    # Builds a class map from a config and a list of Ruby methods.
     def class_map(methods)
       ClassMap.build_from_methods(configuration, methods)
     end
 
-    # detect_metadata returns default metadata detected from the Ruby system and from the
+    # Returns default metadata detected from the Ruby system and from the
     # filesystem.
     def detect_metadata
       @metadata ||= Metadata.detect.freeze

data/lib/appmap/class_map.rb

@@ -61,7 +61,7 @@ module AppMap
             location: location,
             static: static,
             labels: labels
-          }.delete_if {|k,v| v.nil?}
+          }.delete_if { |k,v| v.nil? || v == [] }
         end
       end
     end
@@ -80,10 +80,6 @@ module AppMap
       protected
 
       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
-
         static = method.static
 
         object_infos = [
@@ -101,12 +97,22 @@ module AppMap
         function_info = {
           name: method.name,
           type: 'function',
-          location: [ location_file, lineno ].join(':'),
           static: static
         }
+        location = method.source_location
+
+        function_info[:location] = \
+          if location
+            location_file, lineno = location
+            location_file = location_file[Dir.pwd.length + 1..-1] if location_file.index(Dir.pwd) == 0
+            [ location_file, lineno ].join(':')
+          else
+            [ method.defined_class, static ? '.' : '#', method.name ].join
+          end
+
         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

@@ -1,33 +1,54 @@
 # frozen_string_literal: true
 
 module AppMap
-  Package = Struct.new(:path, :exclude, :labels) do
-    def initialize(path, exclude, labels = nil)
-      super
+  class Config
+    Package = Struct.new(:path, :package_name, :exclude, :labels) do
+      def initialize(path, package_name: nil, exclude: [], labels: [])
+        super path, package_name, exclude, labels
+      end
+  
+      def to_h
+        {
+          path: path,
+          package_name: package_name,
+          exclude: exclude.blank? ? nil : exclude,
+          labels: labels.blank? ? nil : labels
+        }.compact
+      end
     end
-    
-    def to_h
-      {
-        path: path,
-        exclude: exclude.blank? ? nil : exclude,
-        labels: labels.blank? ? nil : labels
-      }.compact
+
+    Hook = Struct.new(:method_names, :package) do
     end
-  end
 
-  class Config
+    OPENSSL_PACKAGE = Package.new('openssl', package_name: 'openssl', labels: %w[security crypto])
+
     # 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'])
-      }
-    }
+      'ActiveSupport::SecurityUtils' => Hook.new(:secure_compare, Package.new('active_support', package_name: 'active_support', labels: %w[security crypto]))
+    }.freeze
+
+    BUILTIN_METHODS = {
+      'OpenSSL::PKey::PKey' => Hook.new(:sign, OPENSSL_PACKAGE),
+      'Digest::Instance' => Hook.new(:digest, OPENSSL_PACKAGE),
+      'OpenSSL::X509::Request' => Hook.new(%i[sign verify], OPENSSL_PACKAGE),
+      'OpenSSL::PKCS5' => Hook.new(%i[pbkdf2_hmac_sha1 pbkdf2_hmac], OPENSSL_PACKAGE),
+      'OpenSSL::Cipher' => Hook.new(%i[encrypt decrypt final], OPENSSL_PACKAGE),
+      'OpenSSL::X509::Certificate' => Hook.new(:sign, OPENSSL_PACKAGE),
+      'Logger' => Hook.new(:add, Package.new('logger', labels: %w[log io])),
+      'Net::HTTP' => Hook.new(:request, Package.new('net/http', package_name: 'net/http', labels: %w[http io])),
+      'Net::SMTP' => Hook.new(:send, Package.new('net/smtp', package_name: 'net/smtp', labels: %w[smtp email io])),
+      'Net::POP3' => Hook.new(:mails, Package.new('net/pop3', package_name: 'net/pop', labels: %w[pop pop3 email io])),
+      'Net::IMAP' => Hook.new(:send_command, Package.new('net/imap', package_name: 'net/imap', labels: %w[imap email io])),
+      'IO' => Hook.new(%i[read write open close], Package.new('io', labels: %w[io])),
+      'Marshal' => Hook.new(%i[dump load], Package.new('marshal', labels: %w[serialization marshal])),
+      'Psych' => Hook.new(%i[dump dump_stream load load_stream parse parse_stream], Package.new('yaml', package_name: 'psych', labels: %w[serialization yaml])),
+      'JSON::Ext::Parser' => Hook.new(:parse, Package.new('json', package_name: 'json', labels: %w[serialization json])),
+      'JSON::Ext::Generator::State' => Hook.new(:generate, Package.new('json', package_name: 'json', labels: %w[serialization json]))
+    }.freeze
 
     attr_reader :name, :packages
+
     def initialize(name, packages = [])
       @name = name
       @packages = packages
@@ -43,7 +64,7 @@ module AppMap
       # Loads configuration from a Hash.
       def load(config_data)
         packages = (config_data['packages'] || []).map do |package|
-          Package.new(package['path'], package['exclude'] || [])
+          Package.new(package['path'], exclude: package['exclude'] || [])
         end
         Config.new config_data['name'], packages
       end
@@ -57,14 +78,14 @@ module AppMap
     end
 
     def package_for_method(method)
+      defined_class, _, method_name = ::AppMap::Hook.qualify_method_name(method)
+      package = find_package(defined_class, method_name)
+      return package if package
+
       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) &&
@@ -77,15 +98,18 @@ module AppMap
     end
 
     def always_hook?(defined_class, method_name)
-      !!find_hooked_method(defined_class, method_name)
+      !!find_package(defined_class, method_name)
     end
 
-    def find_hooked_method(defined_class, method_name)
-      find_hooked_class(defined_class)[method_name]
+    def find_package(defined_class, method_name)
+      hook = find_hook(defined_class)
+      return nil unless hook
+
+      Array(hook.method_names).include?(method_name) ? hook.package : nil      
     end
-    
-    def find_hooked_class(defined_class)
-      HOOKED_METHODS[defined_class] || {}
+
+    def find_hook(defined_class)
+      HOOKED_METHODS[defined_class] || BUILTIN_METHODS[defined_class]
     end
   end
 end