appmap 0.38.1 → 0.41.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0255347aa61c6f39bfec0f43a78b3cc3060bd20e4f80f1e39e0ff3714a52dff3
-  data.tar.gz: 822bc2fe118426d6d9c9437c85ead8e603a446cabd6bd49d0053c2b1cfaf3789
+  metadata.gz: 75523ebe41aa8e327db7ff2acc4fa20bf1283474b97baf6610e11292bb1abb8b
+  data.tar.gz: 1c0293cf928ff1f6615d7f0a72a6ba7a03acdee04d00065ffc4a0eb41e0192ad
 SHA512:
-  metadata.gz: 031534a5eb015fa99d6ad161665b131677cadbe41ed1bce20357cb1ded7ba19e5f0bcbe37cfef0c8ad35cc2904fe83e4cc9d2b12d04260b970d24cc9aea64ba3
-  data.tar.gz: e7996262f4da21936567c1238df624220987ed04bf5aebd9a525da4d3f181ca752c1060056a5bb41b52c9cdb29e958cf7335973ac7076113278c7e8583755477
+  metadata.gz: c0a39d8067f455a1c0179c65a7f17ffd041de405bc3c48be567970e2b987765216a33801e7c486c6aeee66cae5c2291f91196c3132bd9ad65d147617f6282468
+  data.tar.gz: bdc24d37f171945127c2ff67c834fa55932c019dbbe5e74a2f1625d11b12ca881e6a2d0c6419c0ffe625bba3295b5ef2ef1e96d6256f152ca7fbaa3d2a99b52d

data/.rubocop.yml

@@ -4,6 +4,9 @@ AllCops:
 Layout/CaseIndentation:
   EnforcedStyle: end
 
+Layout/FirstArgumentIndentation:
+  EnforcedStyle: consistent
+
 Layout/SpaceInsideArrayLiteralBrackets:
   Enabled: false
 
@@ -17,13 +20,14 @@ Layout/LineLength:
 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,5 +1,30 @@
-# v0.38.1
+# v0.41.1
+
+* Make best effort to ensure that class name is not `null` in the appmap.json.
+* Don't try and instrument gems which are a dependency of the this gem.
+* Fix a nil exception when applying the exclude list to builtins.
+
+# v0.41.0
+
+* Adjust some label names to match `provider.*`, `format.*`.
+* Add global `exclude` list to *appmap.yml* which can be used to definitively exclude specific classes and methods.
+
+# 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

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,16 @@
 
 - [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)
+  - [Server process recording](#server-process-recording)
+- [AppMap for VSCode](#appmap-for-vscode)
 - [Uploading AppMaps](#uploading-appmaps)
 - [Development](#development)
   - [Running tests](#running-tests)
@@ -23,41 +26,51 @@
 "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.
+
+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).
+
+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).
+
+### Supported versions
+
+* Ruby 2.5, 2.6, 2.7
+* Rails 5, 6
+
+Support for new versions is added frequently, please check back regularly for updates.
 
 # Installation
 
-Add `gem 'appmap'` to your Gemfile just as you would any other dependency.
+<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>
 
-**Global installation**
+
+Add `gem 'appmap'` to **beginning** of your Gemfile. We recommend that you add the `appmap` gem to the `:development, :test` group. Your Gemfile should look something like this:
 
 ```
-gem 'appmap'
-```
+source 'https://rubygems.org'
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 
-**Install in test, development groups**
+# Optional rubRuby version
+# ruby '2.7.2'
 
-```
 group :development, :test do
   gem 'appmap'
 end
 ```
 
-Then install with `bundle`.
+Install with `bundle install`, as usual.
+
+It's important to add the `appmap` gem before any other gems that you may want to instrument. There is more about this in the section on adding gems to the *appmap.yml*.
 
 **Railtie**
 
@@ -65,7 +78,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
@@ -74,15 +88,28 @@ When you run your program, the `appmap` gem reads configuration settings from `a
 file for a typical Rails project:
 
 ```yaml
-name: MyProject
+# 'name' should generally be the same as the code repo name.
+name: my_project
 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
+exclude:
+- MyClass
+- MyClass#my_instance_method
+- MyClass.my_class_method
 ```
 
 * **name** Provides the project name (required)
-* **packages** A list of source code directories which should be instrumented.
+* **packages** A list of source code directories which should be recorded.
+* **exclude** A list of classes and/or methods to definitively exclude from recording.
 
 **packages**
 
@@ -90,13 +117,46 @@ 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.
-* **gem** As an alternative to specifying the path, specify the name of a dependency gem. When using `gem`, don't specify `path`.
+* **gem** As an alternative to specifying the path, specify the name of a dependency gem. When using `gem`, don't specify `path`. In your `Gemfile`, the `appmap` gem **must** be listed **before** any gem that you specify in your *appmap.yml*.
 * **exclude** A list of files and directories which will be ignored. By default, all modules, classes and public
-  functions are inspected.
+  functions are inspected. See also: global `exclude` list.
 * **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`.
 
+**exclude**
+
+Optional list of fully qualified class and method names. Separate class and method names with period (`.`) for class methods and hash (`#`) for instance methods.
+
+
+# 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
 
 ## RSpec
@@ -122,13 +182,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:
@@ -138,23 +195,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:
@@ -171,17 +211,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:
@@ -238,9 +284,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
@@ -261,14 +307,34 @@ $ 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
+## Server process recording
 
-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.
+Add this line to *configuration.rb*:
 
-Note that using this method is kind of a blunt instrument. Recording RSpecs and using Remote Recording are usually better options.
+```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.
+
+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.
 
 # 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 rails6_users_app rails5_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