appmap 0.23.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ba1394503aa1c8f498901ed3c7b903af4bcf5b60b16fe48eee08d9c64f66d67
-  data.tar.gz: 665c48d0d450b2500277b2bdcb54dc356e0b31d442c1f7d9fcb47d0c5c054de6
+  metadata.gz: d42f8555b02b0478b8927c249f6dfa54c9326b7e3122cd5a0b91b5d1fb308fbb
+  data.tar.gz: 525faceacd156300098b897f7ef7789d94d42601f9ccec5d3bfad0f41b62ac54
 SHA512:
-  metadata.gz: 279932323e5ca1ba95eb42a7bc4410e795fb308b2861c1b3ee2bb29ece31e54664983731648967e82ce4367813eb67557791c21bab16cfc67192d743b34d7568
-  data.tar.gz: 0141f02617969b168a2dd0c158e8fbfd5b85caa5bc3fa23691c049ae37adefa269d8e76c3c37b4f08f139bc20071b53bf7b31056b2df1c5dfafef44123a7136b
+  metadata.gz: 8290dde850c68b07c51baa70c074a283907c77c15093c8d6ed9b151da66f1dbad866f37beef6a12c2897195b8b18d147a839dd049336fd52fa1b48fb5e3d8ab1
+  data.tar.gz: '035025557325693fd0a158ce007dab265ec2646a3cf2e729f42348ac0986081f4356a1cec1e66c1bc7d9608025c6889b497e52ec6f510612a3fb5cedd220f22d'

data/.gitignore

@@ -13,5 +13,6 @@ vendor
 node_modules
 Gemfile.lock
 appmap.json
+.vscode
 .byebug_history
 

data/.rubocop.yml

@@ -1,18 +1,27 @@
-Style/MultilineBlockChain:
+Layout/SpaceInsideArrayLiteralBrackets:
   Enabled: false
 
-Style/NumericPredicate:
+# We have squiggly heredocs
+Layout/HeredocIndentation:
   Enabled: false
 
-Layout/SpaceInsideArrayLiteralBrackets:
-  Enabled: false
+Layout/LineLength:
+  Max: 120
 
-# We have squiggly heredocs
-Layout/IndentHeredoc:
+Style/MultilineBlockChain:
   Enabled: false
 
+Style/NumericPredicate:
+  Enabled: false
+  
 Style/AndOr:
   Enabled: false
 
-Metrics/LineLength:
-  Max: 120
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true

data/.travis.yml

@@ -1,5 +1,11 @@
 language: ruby
 
+addons:
+  apt:
+    packages:
+      # https://docs.travis-ci.com/user/docker/#installing-a-newer-docker-version
+      - docker-ce
+
 services:
 - docker
 

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+# v0.25.0
+
+* Reports `exceptions` in [function return attributes](https://github.com/applandinc/appmap#function-return-attributes).
+
+# v0.24.1
+* Fixes an issue which prevented a remote recording from returning scenario data successfully.
+* Remote recording routes now return descriptive status codes as intended.
+* Remote recording routes now have the correct `Content-Type` header.
+
+# v0.24.0
+
+Internals of `appmap-ruby` have been changed to record each method event using `alias_method`,
+rather than `TracePoint`. Performance is much better as a result.
+
+**WARNING** Breaking changes
+
+* **Rack** apps no longer generate `http_server_request` events.
+* **appmap inspect** has been removed. `appmap-ruby` no longer parses the source tree. Instead, it observes the methods as they are loaded by the VM. So, to get a class map, you have to create a recording. The `RSpec` recorder still prints an inventory to `Inventory.appmap.json` when it exits. The class map in this file contains every class and method which was loaded by any of the tests.
+
 # v0.23.0
 
 * **appmap stats** command added.

data/README.md

@@ -1,9 +1,11 @@
 - [About](#about)
+- [Testing](#testing)
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Running](#running)
   - [RSpec](#rspec)
   - [Remote recording](#remote-recording)
+  - [Ruby on Rails](#ruby-on-rails)
 - [Uploading AppMaps](#uploading-appmaps)
 - [Build status](#build-status)
 
@@ -11,21 +13,33 @@
 
 `appmap-ruby` is a Ruby Gem for recording and uploading
 [AppMaps](https://github.com/applandinc/appmap) of your code. 
-AppMap is a data format which records code structure (modules, classes, and methods), code execution events
+"AppMap" is a data format which records code structure (modules, classes, and methods), code execution events
 (function calls and returns), and code metadata (repo name, repo URL, commit
-SHA, etc). It's more granular than a performance profile, but it's less
+SHA, labels, etc). It's more granular than a performance profile, but it's less
 granular than a full debug trace. It's designed to be optimal for understanding the design intent and behavior of code.
 
 There are several ways to record AppMaps of your Ruby program using the `appmap` gem:
 
-* Run your RSpec tests. An AppMap will be generated for each one.
-* Run your application server with AppMap remote recording enabled, and use the AppMap
+* Run your RSpec tests with the environment variable `APPMAP=true`. An AppMap will be generated for each spec.
+* Run your application server with AppMap remote recording enabled, and use the AppMap.
   browser extension to start, stop, and upload recordings. 
+* Run the command `appmap record <program>` to record the entire execution of a program.
 
 When you record AppMaps on the command line (for example, by running RSpec tests), you use the `appmap upload` command to
 upload them to the AppLand website. On the AppLand website, you'll be able to
 visualize the design of your code and share links with collaborators.
 
+# Testing
+Before running tests, configure `local.appmap` to point to your local `appmap-ruby` directory.
+```
+$ bundle config local.appmap $(pwd)
+```
+
+Run the tests via `rake`:
+```
+$ bundle exec rake test
+```
+
 # Installation
 
 Add `gem 'appmap'` to your Gemfile just as you would any other dependency.
@@ -60,8 +74,6 @@ packages:
 
 * **name** Provides the project name (required)
 * **packages** A list of source code directories which should be instrumented.
-* **files** A list of individual files which should be instrumented. This is only used for files which are
-  not part of the `packages` list.
 
 **packages**
 
@@ -69,9 +81,7 @@ Each entry in the `packages` list is a YAML object which has the following keys:
 
 * **path** The path to the source code directory. The path may be relative to the current working directory, or it may
   be an absolute path.
-* **name** A name for the code package. By default, the package name will be the name of the directory in which the code
-  is located. In the example above, "controllers" or "models".
-* **excludes** A list of files and directories which will be ignored. By default, all modules, classes and public
+* **exclude** A list of files and directories which will be ignored. By default, all modules, classes and public
   functions are inspected.
 
 # Running
@@ -129,6 +139,8 @@ 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.
+
 ## Remote recording
 
 To manually record ad-hoc AppMaps of your Ruby app, use AppMap remote recording.
@@ -159,12 +171,18 @@ $ bundle exec rails server
 
 6. Open the AppApp browser extension and push `Stop`. The recording will be transferred to the AppLand website and opened in your browser.
 
+## Ruby on Rails
+
+If your app uses Ruby on Rails, the AppMap Railtie will be automatically enabled. Set the Rails config flag `app.config.appmap.enabled = true` to record the entire execution of your Rails app.
+
+Note that using this method is kind of a blunt instrument. Recording RSpecs and using Remote Recording are usually better options.
+
 # Uploading AppMaps
 
-To upload an AppMap file to AppLand, run the `appmap upload` command. For example:
+To upload an AppMap file to AppLand, run the `appmap upload` command. For example (with binstubs installed):
 
 ```sh-session
-$ appmap upload tmp/appmap/rspec/Hello_app_says_hello_when_prompted.appmap.json
+$ ./bin/appmap upload tmp/appmap/rspec/*
 Uploading "tmp/appmap/rspec/Hello_app_says_hello_when_prompted.appmap.json"
 Scenario Id: 4da4f267-bdea-48e8-bf67-f39463844230
 Batch Id: a116f1df-ee57-4bde-8eef-851af0f3d7bc
@@ -172,4 +190,3 @@ Batch Id: a116f1df-ee57-4bde-8eef-851af0f3d7bc
 
 # Build status
 [![Build Status](https://travis-ci.org/applandinc/appmap-ruby.svg?branch=master)](https://travis-ci.org/applandinc/appmap-ruby)
-

data/Rakefile

@@ -54,7 +54,7 @@ namespace :build do
       end
     end
   end
-  
+
   namespace :fixtures do
     RUBY_VERSIONS.each do |ruby_version|
       namespace ruby_version do
@@ -69,7 +69,7 @@ namespace :build do
           end
         end
       end
-      
+
       desc "Build all fixture images"
       task all: ["#{ruby_version}:all"]
     end
@@ -93,7 +93,7 @@ def run_specs(ruby_version, task_args)
       task.rspec_opts = args.to_a.join(' ')
     end
   end
-  
+
   # Set up the environment, then execute the rspec task we
   # created above.
   ClimateControl.modify(RUBY_VERSION: ruby_version) do

data/appmap.gemspec

@@ -30,11 +30,13 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '~> 1.16'
   spec.add_development_dependency 'minitest', '~> 5.0'
   spec.add_development_dependency 'pry-byebug'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rake', '>= 12.3.3'
   spec.add_development_dependency 'rdoc'
+  spec.add_development_dependency 'rubocop'
 
   # Testing
   spec.add_development_dependency 'climate_control'
+  spec.add_development_dependency 'diffy'
   spec.add_development_dependency 'launchy'
   spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'selenium-webdriver'

data/exe/appmap

@@ -42,17 +42,6 @@ module AppMap
     arg_name 'filename'
     flag %i[c config]
 
-    desc 'Inspect code and generate a classmap file'
-    command :inspect do |c|
-      output_file_flag(c, default_value: default_appmap_file)
-
-      c.action do
-        require 'appmap/command/inspect'
-        appmap = AppMap::Command::Inspect.new(@config).perform
-        @output_file.write JSON.pretty_generate(appmap)
-      end
-    end
-
     desc 'Record the execution of a program and generate an AppMap.'
     arg_name 'program'
     command :record do |c|
@@ -76,10 +65,10 @@ module AppMap
         ARGV.shift
 
         require 'appmap/command/record'
-        AppMap::Command::Record.new(@config, program).perform do |features, events|
-          @output_file.write JSON.generate(version: AppMap::APPMAP_FORMAT_VERSION,
-                                           classMap: features,
-                                           metadata: AppMap::Command::Record.detect_metadata,
+        AppMap::Command::Record.new(@config, program).perform do |version, metadata, class_map, events|
+          @output_file.write JSON.generate(version: version,
+                                           metadata: metadata,
+                                           classMap: class_map,
                                            events: events)
         end
       end
@@ -173,7 +162,7 @@ module AppMap
           appmap = JSON.parse(File.read(filename))
 
           warn "Uploading #{filename.inspect}"
-          upload = AppMap::Command::Upload.new(@config, appmap, url, user, org)
+          upload = AppMap::Command::Upload.new(appmap, url, user, org)
           upload.batch_id = batch_id if batch_id
           upload.perform.tap do |response|
             batch_id ||= response.batch_id
@@ -203,8 +192,7 @@ module AppMap
       protected
 
       def interpret_config_option(fname)
-        require 'appmap/config'
-        AppMap::Config.load_from_file fname
+        AppMap.configure fname
       end
 
       def interpret_output_file_option(file_name)

data/lib/appmap.rb

@@ -13,12 +13,53 @@ module AppMap
   BATCH_HEADER_NAME = 'AppLand-Scenario-Batch'
 
   class << self
-    # Simplified entry point to inspect code for features.
-    def inspect(config)
-      require 'appmap/inspect'
-      features = config.source_locations.map(&AppMap::Inspect.method(:detect_features)).flatten.compact
-      features = features.map(&:reparent)
-      features.each(&:prune)
+    @config = nil
+    @config_file_path = nil
+
+    # configuration gets the AppMap configuration.
+    def configuration
+      raise "AppMap is not configured" unless @config
+
+      @config
+    end
+
+    # configure applies the configuration from a file. This method can only be performed once.
+    # Be sure and call it before +hook+ if you want non-default configuration.
+    #
+    # Default behavior is to configure from "appmap.yml".
+    def configure(config_file_path = 'appmap.yml')
+      if @config
+        return @config if @config_file_path == config_file_path
+
+        raise "AppMap is already configured from #{@config_file_path}, can't reconfigure from #{config_file_path}"
+      end
+
+      warn "Configuring AppMap from path #{config_file_path}"
+      require 'appmap/hook'
+      AppMap::Hook::Config.load_from_file(config_file_path).tap do |config|
+        @config = config
+        @config_file_path = config_file_path
+      end
+    end
+
+    # Activate 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 hook(config = configure)
+      require 'appmap/hook'
+      AppMap::Hook.hook(config)
+    end
+
+    # Access the AppMap::Tracers, which can be used to start tracing, stop tracing, and record events.
+    def tracing
+      require 'appmap/trace'
+      @tracing ||= Trace::Tracers.new
+    end
+
+    # Build a class map from a config and a list of Ruby methods.
+    def class_map(config, methods)
+      require 'appmap/class_map'
+      AppMap::ClassMap.build_from_methods(config, methods)
     end
   end
 end

data/lib/appmap/algorithm/prune_class_map.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module AppMap
   module Algorithm
     # Prune a class map so that only functions, classes and packages which are referenced

data/lib/appmap/algorithm/stats.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module AppMap
   module Algorithm
     StatsStruct = Struct.new(:appmap)
@@ -31,7 +33,7 @@ module AppMap
           comparator = ->(a,b) { b.count <=> a.count }
           class_frequency.sort!(&comparator)
           method_frequency.sort!(&comparator)
-          
+
           self
         end
 
@@ -55,7 +57,7 @@ module AppMap
         end
       end
       Frequency = Struct.new(:name, :count)
-      
+
       def perform(limit: nil)
         events = appmap['events'] || []
         frequency_calc = lambda do |key_func|

data/lib/appmap/class_map.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext'
+
+module AppMap
+  class ClassMap
+    module HasChildren
+      def self.included(base)
+        base.module_eval do
+          def children
+            @children ||= []
+          end
+        end
+      end
+    end
+
+    module Types
+      class Root
+        include HasChildren
+      end
+
+      Package = Struct.new(:name) do
+        include HasChildren
+
+        def type
+          'package'
+        end
+
+        def to_h
+          {
+            name: name,
+            type: type,
+            children: children.map(&:to_h)
+          }
+        end
+      end
+      Class = Struct.new(:name) do
+        include HasChildren
+
+        def type
+          'class'
+        end
+
+        def to_h
+          {
+            name: name,
+            type: type,
+            children: children.map(&:to_h)
+          }
+        end
+      end
+      Function = Struct.new(:name) do
+        attr_accessor :static, :location
+
+        def type
+          'function'
+        end
+
+        def to_h
+          {
+            name: name,
+            type: type,
+            location: location,
+            static: static
+          }
+        end
+      end
+    end
+
+    class << self
+      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
+        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
+        location_file, lineno = location
+        location_file = location_file[Dir.pwd.length + 1..-1] if location_file.index(Dir.pwd) == 0
+
+        static = method.method.owner.singleton_class?
+
+        object_infos = [
+          {
+            name: package_name,
+            type: 'package'
+          }
+        ]
+        object_infos += method.defined_class.split('::').map do |name|
+          {
+            name: name,
+            type: 'class'
+          }
+        end
+        object_infos << {
+          name: method.method.name,
+          type: 'function',
+          location: [ location_file, lineno ].join(':'),
+          static: static
+        }
+        parent = root
+        object_infos.each do |info|
+          parent = find_or_create parent.children, info do
+            Types.const_get(info[:type].classify).new(info[:name].to_s).tap do |type|
+              info.keys.tap do |keys|
+                keys.delete(:name)
+                keys.delete(:type)
+              end.each do |key|
+                type.send "#{key}=", info[key]
+              end
+            end
+          end
+        end
+      end
+
+      def find_or_create(list, info)
+        obj = list.find { |item| item.type == info[:type] && item.name == info[:name] }
+        return obj if obj
+
+        yield.tap do |new_obj|
+          list << new_obj
+        end
+      end
+    end
+  end
+end