appmap 0.23.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ba1394503aa1c8f498901ed3c7b903af4bcf5b60b16fe48eee08d9c64f66d67
-  data.tar.gz: 665c48d0d450b2500277b2bdcb54dc356e0b31d442c1f7d9fcb47d0c5c054de6
+  metadata.gz: fd23faab460498cfac79b397c4fc87920df8d1a984142909542f524057d1e4cb
+  data.tar.gz: a967224c65d6a479287768389feb73a378e6e1be133f1033d06be6034a43b18e
 SHA512:
-  metadata.gz: 279932323e5ca1ba95eb42a7bc4410e795fb308b2861c1b3ee2bb29ece31e54664983731648967e82ce4367813eb67557791c21bab16cfc67192d743b34d7568
-  data.tar.gz: 0141f02617969b168a2dd0c158e8fbfd5b85caa5bc3fa23691c049ae37adefa269d8e76c3c37b4f08f139bc20071b53bf7b31056b2df1c5dfafef44123a7136b
+  metadata.gz: 7822e4c821cb5e57579163fdd080bc3b74fb5ad0c8999bc6e3d29ace636301d8ed931966abfe9a59a6a59603f83af03e82130c241293ee198173ef6f6f41ebd1
+  data.tar.gz: 8ba03667929d4571e13439ab53420934e0b1c9ee4605dfd71e9a7ff82b984d34e37ca43e206cbf5dc750201df93dc8dc9babbdafbadf12a86051e52efc6ef985

data/.gitignore

@@ -13,5 +13,7 @@ vendor
 node_modules
 Gemfile.lock
 appmap.json
+.vscode
 .byebug_history
 
+/test/fixtures/rspec_recorder/.bundle/

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,46 @@
+# v0.27.0
+
+* Add **AppMap.record** to programatically record and capture an AppMap of a Ruby block.
+
+# v0.26.1
+
+* Fix a bug that caused duplicate entries in the list of frameworks that appear
+  in the `metadata` section of an appmap.
+  
+# v0.26.0
+
+* **appmap upload** is removed. Upload functionality has been moved to
+  the [AppLand CLI](https://github.com/applandinc/appland-cli).
+
+# v0.25.2
+
+* Stop checking a whitelist to see if each SQL query should be recorded. Record
+all queries.
+
+# v0.25.1
+
+* Ensure that caught exceptions are re-raised.
+* Add safety around indexing potentially nil backtrace locations. 
+
+# 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,31 +1,47 @@
 - [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)
 
 # About
 
-`appmap-ruby` is a Ruby Gem for recording and uploading
+`appmap-ruby` is a Ruby Gem for recording
 [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
+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
+Then, on the [AppLand website](https://app.land), you can
 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 +76,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 +83,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 +141,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,17 +173,15 @@ $ 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.
 
-# Uploading AppMaps
+## Ruby on Rails
 
-To upload an AppMap file to AppLand, run the `appmap upload` command. For example:
+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.
 
-```sh-session
-$ appmap upload tmp/appmap/rspec/Hello_app_says_hello_when_prompted.appmap.json
-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
-```
+Note that using this method is kind of a blunt instrument. Recording RSpecs and using Remote Recording are usually better options.
+
+# Uploading AppMaps
+
+For instructions on uploading, see the documentation of the [AppLand CLI](https://github.com/applandinc/appland-cli).
 
 # 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
@@ -136,62 +125,6 @@ module AppMap
       end
     end
 
-    desc 'Upload a scenario file to AppLand.'
-    arg_name 'filename'
-    command :upload do |c|
-      output_file_flag(c, default_value: '-')
-
-      c.desc 'Whether to open the new scenario in the browser'
-      c.default_value true
-      c.switch [:open]
-
-      c.desc 'AppLand website URL'
-      c.default_value ENV['APPLAND_URL'] || 'https://appland-staging.herokuapp.com'
-      c.flag :url
-
-      # TODO: This will be replaced with proper login
-      c.desc 'User id to own the scenario'
-      c.default_value(ENV['APPLAND_USER'])
-      c.flag :user
-
-      c.desc 'Organization id to own the scenario'
-      c.default_value(ENV['APPLAND_ORG'])
-      c.flag :org
-
-      c.action do |_, options, args|
-        require 'appmap/command/upload'
-
-        filenames = args
-        help_now!("'filename' argument is required") if filenames.empty?
-
-        url = options[:url]
-        user = options[:user]
-        org = options[:org]
-
-        batch_id = nil
-        uuids = filenames.map do |filename|
-          appmap = JSON.parse(File.read(filename))
-
-          warn "Uploading #{filename.inspect}"
-          upload = AppMap::Command::Upload.new(@config, appmap, url, user, org)
-          upload.batch_id = batch_id if batch_id
-          upload.perform.tap do |response|
-            batch_id ||= response.batch_id
-            @output_file.puts "Scenario Id: #{response.scenario_uuid}"
-          end.scenario_uuid
-        end
-        @output_file.puts "Batch Id: #{batch_id}"
-
-        if options[:open] && STDIN.tty?
-          if uuids.length == 1
-            system "open #{url}/scenarios/#{uuids.first}"
-          else
-            system "open #{url}/scenario_batches/#{batch_id}"
-          end
-        end
-      end
-    end
-
     pre do |global, _, options, _|
       @config = interpret_config_option(global[:config])
       @output_file = interpret_output_file_option(options[:output])
@@ -203,8 +136,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,67 @@ 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
+
+    # Record a block and return the array of events.
+    def record
+      tracer = tracing.trace
+      begin
+        yield
+      ensure
+        tracing.delete(tracer)
+      end
+
+      [].tap do |events|
+        events << tracer.next_event.to_h while tracer.event?
+      end
+    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