appmap 0.43.0 → 0.44.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4007f0eb67a3a25088e8b3677de8d0388fd1bfec4b326c43a51c503f640325b5
-  data.tar.gz: 1b593251a7a072b7a1483e7af172b9157d6913208658fb324630bc52b0b4fe73
+  metadata.gz: 02dfa68caaa5e5413c68ae06e89664a676624c9dbb301e2ebbc2a7ae26359afd
+  data.tar.gz: af97e3fb4bb428a238b854ef30969f232c48d4f3a59956865a4cc95788ac35e8
 SHA512:
-  metadata.gz: 6af64a17bf69655ae8bdc9b4b67b7e2c9bd1b87d07a23e266dcabd2a927311224a4b27a77355674559828a08ae1df2e7231e2a68a2734c0f620de8efc48ec6d4
-  data.tar.gz: 7725cb0c79d8be13fddf7a3b688113f4fd31941c4f08f64ee44d4fbb3f5255dd3a308b08ef578413938052ee3b9eeecedc3e58bc092b12e23bfa872eac119eb7
+  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,12 @@
+# 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.

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)
@@ -109,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.
@@ -117,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**
 
@@ -144,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
 
@@ -329,9 +345,20 @@ Run your Rails server with `APPMAP_RECORD=true`. When the server exits, an *appm
 
 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
 

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
@@ -50,11 +51,6 @@ module AppMap
       end
     end
 
-    # Whether to include source and comments in all class maps.
-    def include_source?
-      ENV['APPMAP_SOURCE'] == 'true'
-    end
-
     # Used to start tracing, stop tracing, and record events.
     def tracing
       @tracing ||= Trace::Tracing.new
@@ -88,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/command/record.rb

@@ -27,7 +27,7 @@ module AppMap
           event_thread.join
           yield AppMap::APPMAP_FORMAT_VERSION,
                 AppMap.detect_metadata,
-                AppMap.class_map(tracer.event_methods, include_source: AppMap.include_source?),
+                AppMap.class_map(tracer.event_methods),
                 events
         end
 

data/lib/appmap/config.rb

@@ -49,44 +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', labels: %w[provider.secure_compare])),
+      '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::Cookies::CookieJar' => Hook.new(%i[[]= clear update delete recycle], Package.build_from_path('action_pack', labels: %w[provider.http.cookie])),
-      'ActionDispatch::Cookies::EncryptedCookieJar' => Hook.new(%i[[]=], Package.build_from_path('action_pack', labels: %w[provider.http.cookie crypto])),
-      'CanCan::ControllerAdditions' => Hook.new(%i[authorize! can? cannot?], Package.build_from_path('cancancan', labels: %w[provider.authorization])),
-      'CanCan::Ability' => Hook.new(%i[authorize!], Package.build_from_path('cancancan', labels: %w[provider.authorization])),
+      '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])),
-      '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']
@@ -112,7 +167,8 @@ module AppMap
             Package.build_from_path(path, exclude: package['exclude'] || [], shallow: package['shallow'])
           end
         end.compact
-        Config.new config_data['name'], packages, config_data['exclude'] || []
+        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

data/lib/appmap/cucumber.rb

@@ -50,7 +50,7 @@ module AppMap
         appmap['metadata'] = update_metadata(scenario, appmap['metadata'])
         scenario_filename = AppMap::Util.scenario_filename(appmap['metadata']['name'])
 
-        File.write(File.join(APPMAP_OUTPUT_DIR, scenario_filename), JSON.generate(appmap))
+        AppMap::Util.write_appmap(File.join(APPMAP_OUTPUT_DIR, scenario_filename), JSON.generate(appmap))
       end
 
       def enabled?

data/lib/appmap/hook.rb

@@ -32,6 +32,7 @@ module AppMap
     end
 
     attr_reader :config
+
     def initialize(config)
       @config = config
     end
@@ -59,6 +60,10 @@ module AppMap
 
         hook = lambda do |hook_cls|
           lambda do |method_id|
+            # Don't try and trace the AppMap methods or there will be
+            # a stack overflow in the defined hook method.
+            return if (hook_cls&.name || '').split('::')[0] == AppMap.name
+
             method = begin
               hook_cls.public_instance_method(method_id)
             rescue NameError
@@ -78,11 +83,9 @@ module AppMap
               config.always_hook?(hook_cls, method.name) ||
               config.included_by_location?(method)
 
-            hook_method = Hook::Method.new(config.package_for_method(method), hook_cls, method)
+            package = config.package_for_method(method)
 
-            # Don't try and trace the AppMap methods or there will be
-            # a stack overflow in the defined hook method.
-            next if /\AAppMap[:\.]/.match?(hook_method.method_display_name)
+            hook_method = Hook::Method.new(package, hook_cls, method)
 
             hook_method.activate
           end
@@ -112,25 +115,27 @@ module AppMap
         end
       end
 
-      Config::BUILTIN_METHODS.each do |class_name, hook|
-        require hook.package.package_name if hook.package.package_name
-        Array(hook.method_names).each do |method_name|
-          method_name = method_name.to_sym
+      config.builtin_methods.each do |class_name, hooks|
+        Array(hooks).each do |hook|
+          require hook.package.package_name if hook.package.package_name
+          Array(hook.method_names).each do |method_name|
+            method_name = method_name.to_sym
 
-          cls = class_from_string.(class_name)
-          method = \
-            begin
-              cls.instance_method(method_name)
-            rescue NameError
-              cls.method(method_name) rescue nil
-            end
+            cls = class_from_string.(class_name)
+            method = \
+              begin
+                cls.instance_method(method_name)
+              rescue NameError
+                cls.method(method_name) rescue nil
+              end
 
-          next if config.never_hook?(method)
+            next if config.never_hook?(method)
 
-          if method
-            Hook::Method.new(hook.package, cls, method).activate
-          else
-            warn "Method #{method_name} not found on #{cls.name}"
+            if method
+              Hook::Method.new(hook.package, cls, method).activate
+            else
+              warn "Method #{method_name} not found on #{cls.name}"
+            end
           end
         end
       end