appmap 0.37.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fba24ecdb42c951741292378419eef430a56cc16816df46a14b2ae3e318f8f94
-  data.tar.gz: 67ff27467f72322c5a8514c90b0a6039e3fd1268dba103dea3b832eda95ac317
+  metadata.gz: 1b0943dadde84e67780d724918fa26377b869791eaab6edfb714e5081ecb5c80
+  data.tar.gz: c492323d80541a913b800924d04a7c24a6c8682263ba3ec4deabfa8d7ade3908
 SHA512:
-  metadata.gz: 1823304c2733b46470481fd731a1f4650a80e769d96b47dbcdb0e5763e59930d6754068b4cf0729f9f748c55109575f3c8146b09030741fccfafd06cd45669b9
-  data.tar.gz: bbebe31041ed1720dc54b9522e4c6baac3b27d8d77be0622315657d0fa5b355c3e12474aa756811a6d747b563999c6e76206805c1392a015f92c6b863e8eeda0
+  metadata.gz: 2a27e5b9bc3dafbba8aafd7035732b6ffcb813d57bb216d0e544af30260c0e26f23a920d1b2d6d35882046e74a57f8b492b12b9869de5d820ff6a4e09cafd716
+  data.tar.gz: f1bdc22fda7a6fdf0a37fc1d5bd419947e0fffa16511873dbe8a1549f30bf862566fe74fa4c9952c4338f5263414c99f3d598daec0a599b467e52ebac374b4f7

data/.dockerignore

@@ -1,5 +1,5 @@
 vendor
 node_modules
-spec/fixtures/rails_users_app
+spec/fixtures/rails*_users_app
 spec/fixtures/rack_users_app
 

data/.rubocop.yml

@@ -1,6 +1,12 @@
 AllCops:
   NewCops: enable
 
+Layout/CaseIndentation:
+  EnforcedStyle: end
+
+Layout/FirstArgumentIndentation:
+  EnforcedStyle: consistent
+
 Layout/SpaceInsideArrayLiteralBrackets:
   Enabled: false
 
@@ -11,12 +17,17 @@ Layout/HeredocIndentation:
 Layout/LineLength:
   Max: 120
 
+Metrics/BlockLength:
+  ExcludedMethods:
+  - it
+  - context
+
 Style/MultilineBlockChain:
   Enabled: false
 
 Style/NumericPredicate:
   Enabled: false
-  
+
 Style/AndOr:
   Enabled: false
 

data/.travis.yml

@@ -16,29 +16,8 @@ before_script:
   
 jobs:
   include:
-  - stage: minitest
+  - stage: test
     script:
     - mkdir tmp
-    - bundle exec rake minitest
-    
-  - stage: base
-    script:
-    - bundle exec rake build:base:2.5
-  - stage: base
-    script:
-    - bundle exec rake build:base:2.6
-      
-  - stage: fixtures
-    script:
-    - bundle exec rake build:fixtures:2.5:all
-  - stage: fixtures
-    script:
-    - bundle exec rake build:fixtures:2.6:all
-
-  - stage: spec
-    script:
-    - bundle exec rake spec:2.5
-  - stage: spec
-    script:
-    - bundle exec rake spec:2.6
+    - bundle exec rake test
     

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+# v0.40.0
+
+* Parse source code comments into function labels.
+
+# v0.39.2
+* Correctly recognize normalized path info for subengines.
+
+# v0.39.1
+* Support Ruby 2.7.
+* Remove support for Rails 4.
+* Stop recommending `-t appmap` argument for `rspec`.
+
+# v0.39.0
+* Recognize and record `normalized_path_info` in Rails applications, per 1.4 AppMap format version.
+
+# v0.38.1
+* Package configuration can be `shallow`, in case which only the initial entry into the package is recorded.
+
+# v0.37.2
+* Fix ParameterFilter deprecation warning.
+
+# v0.37.1
+* Fix parameter mapping with keyword and rest arguments.
+
 # v0.37.0
 * Capture method source and comment.
 

data/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing to appmap-ruby
+
+We are incredibly thankful for the contributions we receive from the community. Before contributing, please take a moment to read our [Contributor License Agreement](https://github.com/applandorg/community/blob/master/docs/CLA%20Instructions.pdf) and our [Code of Conduct](https://github.com/applandorg/community/blob/master/docs/Code%20of%20Conduct%20for%20Contributors.pdf).
+
+## Contributor License Agreement
+We require our external contributors to sign a Contributor License Agreement ("CLA") in order to ensure that
+our projects remain licensed under Free and Open Source licenses such as while allowing
+Appland to build a sustainable business.
+
+AppLand is committed to having a true Free and Open Source Software license for our
+non-commercial software. A CLA enables AppLand to safely commercialize our products while
+keeping a standard FOSS license with all the rights that license grants to users.
+
+ * [Contributor License Agreement](https://github.com/applandorg/community/blob/master/docs/CLA%20Instructions.pdf)
+
+
+## Code of Conduct
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and
+healthy community.
+
+ * [Code of Conduct](https://github.com/applandorg/community/blob/master/docs/Code%20of%20Conduct%20for%20Contributors.pdf)

data/README.md

@@ -1,13 +1,15 @@
 
 - [About](#about)
+    - [Supported versions](#supported-versions)
 - [Installation](#installation)
 - [Configuration](#configuration)
+- [Labels](#labels)
 - [Running](#running)
   - [RSpec](#rspec)
   - [Minitest](#minitest)
   - [Cucumber](#cucumber)
   - [Remote recording](#remote-recording)
-  - [Ruby on Rails](#ruby-on-rails)
+- [AppMap for VSCode](#appmap-for-vscode)
 - [Uploading AppMaps](#uploading-appmaps)
 - [Development](#development)
   - [Running tests](#running-tests)
@@ -23,33 +25,35 @@
 "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, 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.
+granular than a full debug trace. It's designed to be optimal for understanding the design intent and structure of code and key data flows.
 
 There are several ways to record AppMaps of your Ruby program using the `appmap` gem:
 
-* Run your RSpec tests with the environment variable `APPMAP=true`. An AppMap will be generated for each spec.
+* Run your tests (RSpec, Minitest, Cucumber) 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 [AppLand
   browser extension](https://github.com/applandinc/appland-browser-extension) to start,
   stop, and upload recordings.
-* Run the command `appmap record <program>` to record the entire execution of a program.
+* Wrap some code in an `AppMap.record` block, which returns JSON containing the code execution trace.
 
-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).
-Then, on the [AppLand website](https://app.land), you can
-visualize the design of your code and share links with collaborators.
+Once you have made a recording, there are two ways to view automatically generated diagrams of the AppMaps.
 
-# Installation
+The first option is to load the diagrams directly in your IDE, using the [AppMap extension for VSCode](https://marketplace.visualstudio.com/items?itemName=appland.appmap).
 
-Add `gem 'appmap'` to your Gemfile just as you would any other dependency.
+The second option is to upload them to the [AppLand server](https://app.land) using the [AppLand CLI](https://github.com/applandinc/appland-cli/releases).
 
-**Global installation**
+### Supported versions
 
-```
-gem 'appmap'
-```
+* Ruby 2.5, 2.6, 2.7
+* Rails 5, 6
+
+Support for new versions is added frequently, please check back regularly for updates.
+
+# Installation
 
-**Install in test, development groups**
+<a href="https://www.loom.com/share/78ab32a312ff4b85aa8827a37f1cb655"> <p>Quick and easy setup of the AppMap gem for Rails - Watch Video</p> <img style="max-width:300px;" src="https://cdn.loom.com/sessions/thumbnails/78ab32a312ff4b85aa8827a37f1cb655-with-play.gif"> </a>
+
+
+Add `gem 'appmap'` to your Gemfile just as you would any other dependency. We recommend that the Gem be added to the `:development, :test` section.
 
 ```
 group :development, :test do
@@ -65,7 +69,8 @@ If you are using Ruby on Rails, require the railtie after Rails is loaded.
 
 ```
 # application.rb is a good place to do this, along with all the other railties.
-require 'appmap/railtie'
+# Don't require the railtie in environments that don't bundle the appmap gem.
+require 'appmap/railtie' if defined?(AppMap).
 ```
 
 # Configuration
@@ -78,7 +83,14 @@ name: MyProject
 packages:
 - path: app/controllers
 - path: app/models
+- path: app/jobs
+- path: app/helpers
+# Include the gems that you want to see in the dependency maps.
+# These are just examples.
 - gem: activerecord
+- gem: devise
+- gem: aws-sdk
+- gem: will_paginate
 ```
 
 * **name** Provides the project name (required)
@@ -93,6 +105,37 @@ Each entry in the `packages` list is a YAML object which has the following keys:
 * **gem** As an alternative to specifying the path, specify the name of a dependency gem. When using `gem`, don't specify `path`.
 * **exclude** A list of files and directories which will be ignored. By default, all modules, classes and public
   functions are inspected.
+* **shallow** When set to `true`, only the first function call entry into a package will be recorded. Subsequent function calls within 
+  the same package are not recorded unless code execution leaves the package and re-enters it. Default: `true` when using `gem`,
+  `false` when using `path`.
+
+# Labels
+
+The [AppMap data format](https://github.com/applandinc/appmap) provides for class and function `labels`, which can be used to enhance the AppMap visualizations, and to programatically analyze the data.
+
+You can apply function labels using source code comments in your Ruby code. To apply a labels to a function, add a `@label` or `@labels` line to the comment which immediately precedes a function.
+
+For example, if you add this comment to your source code:
+
+```ruby
+class ApiKey
+  # @labels provider.authentication security
+  def authenticate(key)
+    # logic to verify the key here...
+  end
+end
+```
+
+Then the AppMap metadata section for this function will include:
+
+```json
+  {
+    "name": "authenticate",
+    "type": "function",
+    "labels": [ "provider.authentication", "security" ]
+  }
+```
+
 
 # Running
 
@@ -119,13 +162,10 @@ 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. 
-
-3) Run the tests with the environment variable `APPMAP=true`:
+2) Run the tests with the environment variable `APPMAP=true`:
 
 ```sh-session
-$ APPMAP=true bundle exec rspec -t appmap
+$ APPMAP=true bundle exec rspec
 ```
 
 Each RSpec test will output an AppMap file into the directory `tmp/appmap/rspec`. For example:
@@ -135,23 +175,6 @@ $ find tmp/appmap/rspec
 Hello_says_hello_when_prompted.appmap.json
 ```
 
-If you include the `feature` and `feature_group` metadata, these attributes will be exported to the AppMap file in the
-`metadata` section. It will look something like this:
-
-```json
-{
-  ...
-  "metadata": {
-    "name": "Hello app says hello when prompted",
-    "feature": "Hello app says hello",
-    "feature_group": "Hello"
-  },
-  ...
-}
-```
-
-If you don't explicitly declare `feature` and `feature_group`, then they will be inferred from the spec name and example descriptions.
-
 ## Minitest
 
 To record Minitest tests, follow these additional steps:
@@ -168,17 +191,23 @@ Note that `test_helper.rb` in a Rails project typically loads the application's
 require_relative '../config/environment'
 ```
 
-and `appmap/rspec` must be required before this:
+and `appmap/minitest` must be required before this:
 
 ```ruby
-require 'appmap/rspec'
+require 'appmap/minitest'
 require_relative '../config/environment'
 ```
 
-2) Run the tests with the environment variable `APPMAP=true`:
+2) Run your tests as you normally would with the environment variable `APPMAP=true`. For example:  
 
-```sh-session
-$ APPMAP=true bundle exec -Ilib -Itest test/*
+```
+$ APPMAP=true bundle exec rake test
+```
+
+or
+
+```
+$ APPMAP=true bundle exec ruby -Ilib -Itest test/*_test.rb
 ```
 
 Each Minitest test will output an AppMap file into the directory `tmp/appmap/minitest`. For example:
@@ -235,9 +264,9 @@ To manually record ad-hoc AppMaps of your Ruby app, use AppMap remote recording.
 1. Add the AppMap remote recording middleware. For example, in `config/initializers/appmap_remote_recording.rb`:
 
 ```ruby
-require 'appmap/middleware/remote_recording'
+if defined?(AppMap)
+  require 'appmap/middleware/remote_recording'
 
-unless Rails.env.test?
   Rails.application.config.middleware.insert_after \
     Rails::Rack::Logger,
     AppMap::Middleware::RemoteRecording
@@ -258,14 +287,14 @@ $ bundle exec rails server
 
 6. Open the AppLand browser extension and push `Stop`. The recording will be transferred to the AppLand website and opened in your browser.
 
-## Ruby on Rails
+# AppMap for VSCode
 
-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.
+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.
 
 # Uploading AppMaps
 
+[https://app.land](https://app.land) can be used to store, analyze, and share AppMaps.
+
 For instructions on uploading, see the documentation of the [AppLand CLI](https://github.com/applandinc/appland-cli).
 
 # Development

data/Rakefile

@@ -18,12 +18,12 @@ namespace 'gem' do
   require 'bundler/gem_tasks'
 end
 
-RUBY_VERSIONS=%w[2.5 2.6]
-FIXTURE_APPS=%w[rack_users_app rails_users_app rails4_users_app]
+RUBY_VERSIONS=%w[2.5 2.6 2.7]
+FIXTURE_APPS=%w[rack_users_app rails6_users_app rails5_users_app]
 
 def run_cmd(*cmd)
   $stderr.puts "Running: #{cmd}"
-  out,s = Open3.capture2e(*cmd)
+  out, s = Open3.capture2e(*cmd)
   unless s.success?
     $stderr.puts <<-END
       Command failed:

data/lib/appmap/class_map.rb

@@ -113,17 +113,18 @@ module AppMap
             [ method.defined_class, static ? '.' : '#', method.name ].join
           end
 
+        source, comment = begin
+          [ method.source, method.comment ]
+        rescue MethodSource::SourceNotFoundError
+          [ nil, nil, ]
+        end
+
         if include_source
-          begin
-            function_info[:source] = method.source
-            comment = method.comment || ''
-            function_info[:comment] = comment unless comment.empty?
-          rescue MethodSource::SourceNotFoundError
-            # pass
-          end
+          function_info[:source] = source unless source.blank?
+          function_info[:comment] = comment unless comment.blank?
         end
 
-        function_info[:labels] = package.labels if package.labels
+        function_info[:labels] = parse_labels(comment) + (package.labels || [])
         object_infos << function_info
 
         parent = root
@@ -141,6 +142,22 @@ module AppMap
         end
       end
 
+      # Labels can be embedded in the function comment. Label format is similar to YARD and JavaDoc.
+      # The keyword is @labels or @label. The keyword is followed by space-separated labels.
+      # For example:
+      # @label provider.authentication security
+      def parse_labels(comment)
+        return [] unless comment
+
+        comment
+          .split("\n")
+          .map { |line| line.match(/^\s*#\s*@labels?\s+(.*)/) }
+          .compact
+          .map { |match| match[1] }
+          .inject([]) { |accum, labels| accum += labels.split(/\s+/); accum }
+          .sort
+      end
+
       def find_or_create(list, info)
         obj = list.find { |item| item.type == info[:type] && item.name == info[:name] }
         return obj if obj

data/lib/appmap/config.rb

@@ -2,15 +2,22 @@
 
 module AppMap
   class Config
-    Package = Struct.new(:path, :gem, :package_name, :exclude, :labels) do
+    Package = Struct.new(:path, :gem, :package_name, :exclude, :labels, :shallow) do
+      # Indicates that only the entry points to a package will be recorded.
+      # Once the code has entered a package, subsequent calls within the package will not be
+      # recorded unless the code leaves the package and re-enters it.
+      def shallow?
+        shallow
+      end
+
       class << self
-        def build_from_path(path, package_name: nil, exclude: [], labels: [])
-          Package.new(path, nil, package_name, exclude, labels)
+        def build_from_path(path, shallow: false, package_name: nil, exclude: [], labels: [])
+          Package.new(path, nil, package_name, exclude, labels, shallow)
         end
 
-        def build_from_gem(gem, package_name: nil, exclude: [], labels: [])
+        def build_from_gem(gem, shallow: true, package_name: nil, exclude: [], labels: [])
           gem_paths(gem).map do |gem_path|
-            Package.new(gem_path, gem, package_name, exclude, labels)
+            Package.new(gem_path, gem, package_name, exclude, labels, shallow)
           end
         end
 
@@ -36,7 +43,8 @@ module AppMap
           package_name: package_name,
           gem: gem,
           exclude: exclude.blank? ? nil : exclude,
-          labels: labels.blank? ? nil : labels
+          labels: labels.blank? ? nil : labels,
+          shallow: shallow
         }.compact
       end
     end
@@ -49,7 +57,8 @@ module AppMap
     # 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[security crypto]))
+      'ActiveSupport::SecurityUtils' => Hook.new(:secure_compare, Package.build_from_path('active_support', package_name: 'active_support', labels: %w[security crypto])),
+      'ActionView::Renderer' => Hook.new(:render, Package.build_from_path('action_view', package_name: 'action_view', labels: %w[view]))
     }.freeze
 
     BUILTIN_METHODS = {
@@ -66,7 +75,7 @@ module AppMap
       'Marshal' => Hook.new(%i[dump load], Package.build_from_path('marshal', labels: %w[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[serialization yaml])),
       'JSON::Ext::Parser' => Hook.new(:parse, Package.build_from_path('json', package_name: 'json', labels: %w[serialization json])),
-      'JSON::Ext::Generator::State' => Hook.new(:generate, Package.build_from_path('json', package_name: 'json', labels: %w[serialization json]))
+      'JSON::Ext::Generator::State' => Hook.new(:generate, Package.build_from_path('json', package_name: 'json', labels: %w[serialization json])),
     }.freeze
 
     attr_reader :name, :packages
@@ -91,9 +100,12 @@ module AppMap
           raise 'AppMap package configuration should specify gem or path, not both' if gem && path
 
           if gem
-            Package.build_from_gem(gem, exclude: package['exclude'] || [])
+            shallow = package['shallow']
+            # shallow is true by default for gems
+            shallow = true if shallow.nil?
+            Package.build_from_gem(gem, exclude: package['exclude'] || [], shallow: shallow)
           else
-            [ Package.build_from_path(path, exclude: package['exclude'] || []) ]
+            [ Package.build_from_path(path, exclude: package['exclude'] || [], shallow: package['shallow']) ]
           end
         end.flatten
         Config.new config_data['name'], packages