appmap 0.41.1 → 0.44.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75523ebe41aa8e327db7ff2acc4fa20bf1283474b97baf6610e11292bb1abb8b
-  data.tar.gz: 1c0293cf928ff1f6615d7f0a72a6ba7a03acdee04d00065ffc4a0eb41e0192ad
+  metadata.gz: 02dfa68caaa5e5413c68ae06e89664a676624c9dbb301e2ebbc2a7ae26359afd
+  data.tar.gz: af97e3fb4bb428a238b854ef30969f232c48d4f3a59956865a4cc95788ac35e8
 SHA512:
-  metadata.gz: c0a39d8067f455a1c0179c65a7f17ffd041de405bc3c48be567970e2b987765216a33801e7c486c6aeee66cae5c2291f91196c3132bd9ad65d147617f6282468
-  data.tar.gz: bdc24d37f171945127c2ff67c834fa55932c019dbbe5e74a2f1625d11b12ca881e6a2d0c6419c0ffe625bba3295b5ef2ef1e96d6256f152ca7fbaa3d2a99b52d
+  metadata.gz: 9a0f2454acf5d10c48aaf1abb6e4b23d674acbbfe495770a25ff83093c38dd81cf0bb1c85dfbae4691773586ace8500c3f9b879b31749c4142851f460ed1a87c
+  data.tar.gz: a2860fb0258b96d95e5ca98f7d13b382c86b635ce1c2d97084c1f651a55973d2ffe31e360695fdec963292081e527b96876c6b42976a90573b9201e14032d1f5

data/.travis.yml

@@ -13,11 +13,26 @@ services:
 # necessary.
 before_script:
   - unset RAILS_ENV
-  
+
+cache:
+  bundler: true
+  directories:
+    - $HOME/docker
+
+# https://stackoverflow.com/a/41975912
+before_cache:
+  # Save tagged docker images
+  - >
+    mkdir -p $HOME/docker && docker images -a --filter='dangling=false' --format '{{.Repository}}:{{.Tag}} {{.ID}}'
+    | xargs -n 2 -t sh -c 'test -e $HOME/docker/$1.tar.gz || docker save $0 | gzip -2 > $HOME/docker/$1.tar.gz'
+
+before_install:
+  # Load cached docker images
+  - if [[ -d $HOME/docker ]]; then ls $HOME/docker/*.tar.gz | xargs -I {file} sh -c "zcat {file} | docker load"; fi
+
 jobs:
   include:
   - stage: test
     script:
     - mkdir tmp
     - bundle exec rake test
-    

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+# v0.44.0
+
+* Support recording and labeling of indivudal functions via `functions:` section in *appmap.yml*.
+* Remove deprecated `exe/appmap`.
+* Add `test_status` and `exception` fields to AppMap metadata.
+* Write AppMap file atomically, by writing to a temp file first and then moving it into place.
+* Remove printing of `Inventory.json` file.
+* Remove source code from `classMap`.
+
+# v0.43.0
+
+* Record `name` and `class` of each entry in Hash-like parameters, messages, and return values.
+* Record client-sent headers in HTTP server request and response.
+* Record HTTP server request `mime_type`.
+* Record HTTP server request `authorization`.
+
+# v0.42.1
+
+* Add missing require `set`.
+* Check `cls.respond_to?(:singleton_class)`, since it oddly, may not.
+
+# v0.42.0
+
+* Remove `feature_group` and `feature` metadata from minitest and RSpec AppMaps.
+* Add `metadata.source_location`.
+
+# v0.41.2
+
+* Don't rely on `gemspec.source_paths` to list all the source locations in a gem. Hook any code that's loaded
+  from inside the `gem_dir`.
+
 # v0.41.1
 
 * Make best effort to ensure that class name is not `null` in the appmap.json.

data/README.md

@@ -11,6 +11,7 @@
   - [Remote recording](#remote-recording)
   - [Server process recording](#server-process-recording)
 - [AppMap for VSCode](#appmap-for-vscode)
+- [AppMap Swagger](#appmap-swagger)
 - [Uploading AppMaps](#uploading-appmaps)
 - [Development](#development)
   - [Running tests](#running-tests)
@@ -82,6 +83,22 @@ If you are using Ruby on Rails, require the railtie after Rails is loaded.
 require 'appmap/railtie' if defined?(AppMap).
 ```
 
+**application.rb**
+
+Add this line to *application.rb*, to enable server recording with `APPMAP_RECORD=true`:
+
+```ruby
+module MyApp
+  class Application < Rails::Application
+    ...
+  
+    config.appmap.enabled = true if ENV['APPMAP_RECORD']
+    
+    ...
+  end
+end
+```
+
 # Configuration
 
 When you run your program, the `appmap` gem reads configuration settings from `appmap.yml`. Here's a sample configuration
@@ -93,6 +110,9 @@ name: my_project
 packages:
 - path: app/controllers
 - path: app/models
+  # Exclude sub-paths within the package path
+  exclude:
+  - concerns/accessor
 - path: app/jobs
 - path: app/helpers
 # Include the gems that you want to see in the dependency maps.
@@ -101,15 +121,22 @@ packages:
 - gem: devise
 - gem: aws-sdk
 - gem: will_paginate
+# Global exclusion of a class name
 exclude:
 - MyClass
 - MyClass#my_instance_method
 - MyClass.my_class_method
+functions:
+- packages: myapp
+  class: ControllerHelper
+  function: logged_in_user
+  labels: [ authentication ]
 ```
 
 * **name** Provides the project name (required)
 * **packages** A list of source code directories which should be recorded.
 * **exclude** A list of classes and/or methods to definitively exclude from recording.
+* **functions** A list of specific functions, scoped by package and class, to record.
 
 **packages**
 
@@ -128,6 +155,11 @@ Each entry in the `packages` list is a YAML object which has the following keys:
 
 Optional list of fully qualified class and method names. Separate class and method names with period (`.`) for class methods and hash (`#`) for instance methods.
 
+**functions**
+
+Optional list of `class, function` pairs. The `package` name is used to place the function within the class map, and does not have to match
+the folder or gem name. The primary use of `functions` is to apply specific labels to functions whose source code is not accessible (e.g., it's in a Gem).
+For functions which are part of the application code, use `@label` or `@labels` in code comments to apply labels.
 
 # Labels
 
@@ -309,27 +341,24 @@ $ bundle exec rails server
 
 ## Server process recording
 
-Add this line to *configuration.rb*:
-
-```ruby
-module MyApp
-  class Application < Rails::Application
-    ...
-  
-    config.appmap.enabled = true if ENV['APPMAP_RECORD']
-    
-    ...
-  end
-end
-```
-
-With this setting, you can run your Rails server with `APPMAP_RECORD=true`. When the server exits, an *appmap.json* file will be written to the project directory. This is a great way to start the server, interact with your app as a user (or through it's API), and then view an AppMap of everything that happened.
+Run your Rails server with `APPMAP_RECORD=true`. When the server exits, an *appmap.json* file will be written to the project directory. This is a great way to start the server, interact with your app as a user (or through it's API), and then view an AppMap of everything that happened.
 
 Be sure and set `WEB_CONCURRENCY=1`, if you are using a webserver that can run multiple processes. You only want there to be one process while you are recording, otherwise they will both try and write *appmap.json* and one of them will clobber the other.
 
+
 # AppMap for VSCode
 
-The [AppMap extension for VSCode](https://marketplace.visualstudio.com/items?itemName=appland.appmap) is a great way to onboard developers to new code, and troubleshoot hard-to-understand bugs with visuals.
+The [AppMap extension for VSCode](https://marketplace.visualstudio.com/items?itemName=appland.appmap) helps you navigate your code more efficiently with interactive, accurate software architecture diagrams right in your IDE. In less than two minutes you can go from installing the AppMap extension to exploring maps of your code's architecture. AppMap helps you:
+
+* Onboard to code architecture, with no extra work for the team
+* Conduct code and design reviews using live and accurate data
+* Troubleshoot hard-to-understand bugs using a "top-down" approach.
+
+Each interactive diagram links directly to the source code, and the information is easy to share.
+
+# AppMap Swagger
+
+[appmap_swagger](https://github.com/applandinc/appmap_swagger-ruby) is a tool to generate Swagger files from AppMap data. With `appmap_swagger`, you can add Swagger to your Ruby or Ruby on Rails project, with no need to write or modify code. Use the Swagger UI to interact with your web services API as you build it, and use diffs of Swagger to perform code review of web service changes.
 
 # Uploading AppMaps
 
@@ -338,7 +367,7 @@ The [AppMap extension for VSCode](https://marketplace.visualstudio.com/items?ite
 For instructions on uploading, see the documentation of the [AppLand CLI](https://github.com/applandinc/appland-cli).
 
 # Development
-[![Build Status](https://travis-ci.org/applandinc/appmap-ruby.svg?branch=master)](https://travis-ci.org/applandinc/appmap-ruby)
+[![Build Status](https://travis-ci.com/applandinc/appmap-ruby.svg?branch=master)](https://travis-ci.com/applandinc/appmap-ruby)
 
 ## Running tests
 
@@ -367,7 +396,7 @@ The fixture apps in `test/fixtures` are plain Ruby projects that exercise the ba
 
 ### `spec/fixtures`
 
-The fixture apps in `spec/fixtures` are simple Rack, Rails4, and Rails5 apps.
+The fixture apps in `spec/fixtures` are simple Rack, Rails5, and Rails6 apps.
 You can use them to interactively develop and test the recording features of the `appmap` gem.
 These fixture apps are more sophisticated than `test/fixtures`, because they include additional 
 resources such as a PostgreSQL database.
@@ -393,11 +422,15 @@ $ docker-compose run --rm app ./create_app
 Now you can start a development container.
 
 ```sh-session
-$ docker-compose run --rm -v $PWD/../../..:/src/appmap-ruby app bash
+$ docker-compose run --rm -v $PWD:/app -v $PWD/../../..:/src/appmap-ruby app bash
 Starting rails_users_app_pg_1 ... done
-root@6fab5f89125f:/app# cd /src/app
+root@6fab5f89125f:/app# cd /src/appmap-ruby
+root@6fab5f89125f:/src/appmap-ruby# rm ext/appmap/*.so ext/appmap/*.o
+root@6fab5f89125f:/src/appmap-ruby# bundle
+root@6fab5f89125f:/src/appmap-ruby# bundle exec rake compile
+root@6fab5f89125f:/src/appmap-ruby# cd /src/app
 root@6fab5f89125f:/src/app# bundle config local.appmap /src/appmap-ruby
-root@6fab5f89125f:/src/app# bundle update appmap
+root@6fab5f89125f:/src/app# bundle
 ```
 
 At this point, the bundle is built with the `appmap` gem located  in `/src/appmap`, which is volume-mounted from the host.
@@ -412,4 +445,3 @@ Configuring AppMap from path appmap.yml
 Finished in 0.07357 seconds (files took 2.1 seconds to load)
 4 examples, 0 failures
 ```
-

data/appmap.gemspec

@@ -20,8 +20,6 @@ Gem::Specification.new do |spec|
 ")
   spec.extensions << "ext/appmap/extconf.rb"
 
-  spec.bindir        = 'exe'
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
   spec.add_dependency 'activesupport'

data/lib/appmap.rb

@@ -43,6 +43,7 @@ module AppMap
     # 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')
+      raise "AppMap configuration file #{config_file_path} does not exist" unless ::File.exists?(config_file_path)
       warn "Configuring AppMap from path #{config_file_path}"
       Config.load_from_file(config_file_path).tap do |configuration|
         self.configuration = configuration
@@ -83,8 +84,8 @@ module AppMap
     end
 
     # Builds a class map from a config and a list of Ruby methods.
-    def class_map(methods, options = {})
-      ClassMap.build_from_methods(methods, options)
+    def class_map(methods)
+      ClassMap.build_from_methods(methods)
     end
 
     # Returns default metadata detected from the Ruby system and from the

data/lib/appmap/class_map.rb

@@ -71,17 +71,17 @@ module AppMap
     end
 
     class << self
-      def build_from_methods(methods, options = {})
+      def build_from_methods(methods)
         root = Types::Root.new
         methods.each do |method|
-          add_function root, method, options
+          add_function root, method
         end
         root.children.map(&:to_h)
       end
 
       protected
 
-      def add_function(root, method, include_source: true)
+      def add_function(root, method)
         package = method.package
         static = method.static
 
@@ -113,16 +113,13 @@ module AppMap
             [ method.defined_class, static ? '.' : '#', method.name ].join
           end
 
-        source, comment = begin
-          [ method.source, method.comment ]
+        comment = begin
+          method.comment
         rescue MethodSource::SourceNotFoundError
-          [ nil, nil, ]
+          nil
         end
 
-        if include_source
-          function_info[:source] = source unless source.blank?
-          function_info[:comment] = comment unless comment.blank?
-        end
+        function_info[:comment] = comment unless comment.blank?
 
         function_info[:labels] = parse_labels(comment) + (package.labels || [])
         object_infos << function_info

data/lib/appmap/config.rb

@@ -20,20 +20,16 @@ module AppMap
             warn "WARNING: #{gem} cannot be AppMapped because it is a dependency of the appmap gem"
             return
           end
-          gem_paths(gem).map do |gem_path|
-            Package.new(gem_path, gem, package_name, exclude, labels, shallow)
-          end
+          Package.new(gem_path(gem), gem, package_name, exclude, labels, shallow)
         end
 
         private_class_method :new
 
         protected
 
-        def gem_paths(gem)
+        def gem_path(gem)
           gemspec = Gem.loaded_specs[gem] or raise "Gem #{gem.inspect} not found"
-          gemspec.source_paths.map do |path|
-            File.join(gemspec.gem_dir, path)
-          end
+          gemspec.gem_dir
         end
       end
 
@@ -53,40 +49,89 @@ module AppMap
       end
     end
 
-    Hook = Struct.new(:method_names, :package) do
+    Function = Struct.new(:package, :cls, :labels, :function_names) do
+      def to_h
+        {
+          package: package,
+          class: cls,
+          labels: labels,
+          functions: function_names.map(&:to_sym)
+        }.compact
+      end
     end
 
-    OPENSSL_PACKAGES = Package.build_from_path('openssl', package_name: 'openssl', labels: %w[security crypto])
+    class Hook
+      attr_reader :method_names, :package
+
+      def initialize(method_names, package)
+        @method_names = method_names
+        @package = package
+      end
+
+      def to_h
+        {
+          package: package.name,
+          method_names: method_names
+        }
+      end
+    end
+
+    OPENSSL_PACKAGES = ->(labels) { Package.build_from_path('openssl', package_name: 'openssl', labels: labels) }
 
     # Methods that should always be hooked, with their containing
     # package and labels that should be applied to them.
     HOOKED_METHODS = {
-      'ActiveSupport::SecurityUtils' => Hook.new(:secure_compare, Package.build_from_path('active_support', package_name: 'active_support', labels: %w[provider.secure_compare])),
-      'ActionView::Renderer' => Hook.new(:render, Package.build_from_path('action_view', package_name: 'action_view', labels: %w[mvc.view]))
+      'ActiveSupport::SecurityUtils' => Hook.new(:secure_compare, Package.build_from_path('active_support', labels: %w[crypto.secure_compare])),
+      'ActionView::Renderer' => Hook.new(:render, Package.build_from_path('action_view', labels: %w[mvc.view])),
+      'ActionDispatch::Request::Session' => Hook.new(%i[destroy [] dig values []= clear update delete fetch merge], Package.build_from_path('action_pack', labels: %w[http.session])),
+      'ActionDispatch::Cookies::CookieJar' => Hook.new(%i[[]= clear update delete recycle], Package.build_from_path('action_pack', labels: %w[http.cookie])),
+      'ActionDispatch::Cookies::EncryptedCookieJar' => Hook.new(%i[[]=], Package.build_from_path('action_pack', labels: %w[http.cookie crypto.encrypt])),
+      'CanCan::ControllerAdditions' => Hook.new(%i[authorize! can? cannot?], Package.build_from_path('cancancan', labels: %w[security.authorization])),
+      'CanCan::Ability' => Hook.new(%i[authorize!], Package.build_from_path('cancancan', labels: %w[security.authorization])),
+      'ActionController::Instrumentation' => [
+        Hook.new(%i[process_action send_file send_data redirect_to], Package.build_from_path('action_view', labels: %w[mvc.controller])),
+        Hook.new(%i[render], Package.build_from_path('action_view', labels: %w[mvc.view])),
+      ]
     }.freeze
 
     BUILTIN_METHODS = {
-      'OpenSSL::PKey::PKey' => Hook.new(:sign, OPENSSL_PACKAGES),
-      'OpenSSL::X509::Request' => Hook.new(%i[sign verify], OPENSSL_PACKAGES),
-      'OpenSSL::PKCS5' => Hook.new(%i[pbkdf2_hmac_sha1 pbkdf2_hmac], OPENSSL_PACKAGES),
-      'OpenSSL::Cipher' => Hook.new(%i[encrypt decrypt final], OPENSSL_PACKAGES),
-      'OpenSSL::X509::Certificate' => Hook.new(:sign, OPENSSL_PACKAGES),
-      'Net::HTTP' => Hook.new(:request, Package.build_from_path('net/http', package_name: 'net/http', labels: %w[protocol.http io])),
-      'Net::SMTP' => Hook.new(:send, Package.build_from_path('net/smtp', package_name: 'net/smtp', labels: %w[protocol.smtp protocol.email io])),
-      'Net::POP3' => Hook.new(:mails, Package.build_from_path('net/pop3', package_name: 'net/pop', labels: %w[protocol.pop protocol.email io])),
-      'Net::IMAP' => Hook.new(:send_command, Package.build_from_path('net/imap', package_name: 'net/imap', labels: %w[protocol.imap protocol.email io])),
-      'Marshal' => Hook.new(%i[dump load], Package.build_from_path('marshal', labels: %w[format.marshal provider.serialization marshal])),
-      'Psych' => Hook.new(%i[dump dump_stream load load_stream parse parse_stream], Package.build_from_path('yaml', package_name: 'psych', labels: %w[format.yaml provider.serialization])),
-      'JSON::Ext::Parser' => Hook.new(:parse, Package.build_from_path('json', package_name: 'json', labels: %w[format.json provider.serialization])),
-      'JSON::Ext::Generator::State' => Hook.new(:generate, Package.build_from_path('json', package_name: 'json', labels: %w[format.json provider.serialization])),
+      'OpenSSL::PKey::PKey' => Hook.new(:sign, OPENSSL_PACKAGES.(%w[crypto.pkey])),
+      'OpenSSL::X509::Request' => Hook.new(%i[sign verify], OPENSSL_PACKAGES.(%w[crypto.x509])),
+      'OpenSSL::PKCS5' => Hook.new(%i[pbkdf2_hmac_sha1 pbkdf2_hmac], OPENSSL_PACKAGES.(%w[crypto.pkcs5])),
+      'OpenSSL::Cipher' => [
+        Hook.new(%i[encrypt], OPENSSL_PACKAGES.(%w[crypto.encrypt])),
+        Hook.new(%i[decrypt], OPENSSL_PACKAGES.(%w[crypto.decrypt]))
+      ],
+      'ActiveSupport::Callbacks::CallbackSequence' => [
+        Hook.new(:invoke_before, Package.build_from_path('active_support', package_name: 'active_support', labels: %w[mvc.before_action])),
+        Hook.new(:invoke_after, Package.build_from_path('active_support', package_name: 'active_support', labels: %w[mvc.after_action])),
+      ],
+      'OpenSSL::X509::Certificate' => Hook.new(:sign, OPENSSL_PACKAGES.(%w[crypto.x509])),
+      'Net::HTTP' => Hook.new(:request, Package.build_from_path('net/http', package_name: 'net/http', labels: %w[protocol.http])),
+      'Net::SMTP' => Hook.new(:send, Package.build_from_path('net/smtp', package_name: 'net/smtp', labels: %w[protocol.email.smtp])),
+      'Net::POP3' => Hook.new(:mails, Package.build_from_path('net/pop3', package_name: 'net/pop', labels: %w[protocol.email.pop])),
+      'Net::IMAP' => Hook.new(:send_command, Package.build_from_path('net/imap', package_name: 'net/imap', labels: %w[protocol.email.imap])),
+      'Marshal' => Hook.new(%i[dump load], Package.build_from_path('marshal', labels: %w[format.marshal])),
+      'Psych' => Hook.new(%i[dump dump_stream load load_stream parse parse_stream], Package.build_from_path('yaml', package_name: 'psych', labels: %w[format.yaml])),
+      'JSON::Ext::Parser' => Hook.new(:parse, Package.build_from_path('json', package_name: 'json', labels: %w[format.json])),
+      'JSON::Ext::Generator::State' => Hook.new(:generate, Package.build_from_path('json', package_name: 'json', labels: %w[format.json])),
     }.freeze
 
-    attr_reader :name, :packages, :exclude
+    attr_reader :name, :packages, :exclude, :builtin_methods
 
-    def initialize(name, packages = [], exclude = [])
+    def initialize(name, packages, exclude: [], functions: [])
       @name = name
       @packages = packages
       @exclude = exclude
+      @builtin_methods = BUILTIN_METHODS
+      @functions = functions
+      @hooked_methods = HOOKED_METHODS.dup
+      functions.each do |func|
+        package_options = {}
+        package_options[:labels] = func.labels if func.labels
+        @hooked_methods[func.cls] ||= []
+        @hooked_methods[func.cls] << Hook.new(func.function_names, Package.build_from_path(func.package, package_options))
+      end
     end
 
     class << self
@@ -98,6 +143,16 @@ module AppMap
 
       # Loads configuration from a Hash.
       def load(config_data)
+        functions = (config_data['functions'] || []).map do |function_data|
+          package = function_data['package']
+          cls = function_data['class']
+          functions = function_data['function'] || function_data['functions']
+          raise 'AppMap class configuration should specify package, class and function(s)' unless package && cls && functions
+          functions = Array(functions).map(&:to_sym)
+          labels = function_data['label'] || function_data['labels']
+          labels = Array(labels).map(&:to_s) if labels
+          Function.new(package, cls, labels, functions)
+        end
         packages = (config_data['packages'] || []).map do |package|
           gem = package['gem']
           path = package['path']
@@ -109,10 +164,11 @@ module AppMap
             shallow = true if shallow.nil?
             Package.build_from_gem(gem, exclude: package['exclude'] || [], shallow: shallow)
           else
-            [ Package.build_from_path(path, exclude: package['exclude'] || [], shallow: package['shallow']) ]
+            Package.build_from_path(path, exclude: package['exclude'] || [], shallow: package['shallow'])
           end
-        end.flatten.compact
-        Config.new config_data['name'], packages, config_data['exclude'] || []
+        end.compact
+        exclude = config_data['exclude'] || []
+        Config.new config_data['name'], packages, exclude: exclude, functions: functions
       end
     end
 
@@ -120,6 +176,7 @@ module AppMap
       {
         name: name,
         packages: packages.map(&:to_h),
+        functions: @functions.map(&:to_h),
         exclude: exclude
       }
     end
@@ -164,14 +221,17 @@ module AppMap
     end
 
     def find_package(defined_class, method_name)
-      hook = find_hook(defined_class)
-      return nil unless hook
+      hooks = find_hooks(defined_class)
+      return nil unless hooks
 
-      Array(hook.method_names).include?(method_name) ? hook.package : nil
+      hook = Array(hooks).find do |hook|
+        Array(hook.method_names).include?(method_name)
+      end
+      hook ? hook.package : nil
     end
 
-    def find_hook(defined_class)
-      HOOKED_METHODS[defined_class] || BUILTIN_METHODS[defined_class]
+    def find_hooks(defined_class)
+      Array(@hooked_methods[defined_class] || @builtin_methods[defined_class])
     end
   end
 end