appmap 0.39.1 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 384456ad51727b3c819e8307de92b2785da152a46c5fa60d0a4e6ff690dbb596
-  data.tar.gz: e0d5a984bc74ee91b0f9428d83cbaac70c387b442cc55666f36b75907080e620
+  metadata.gz: 1b0943dadde84e67780d724918fa26377b869791eaab6edfb714e5081ecb5c80
+  data.tar.gz: c492323d80541a913b800924d04a7c24a6c8682263ba3ec4deabfa8d7ade3908
 SHA512:
-  metadata.gz: 2f0670d632a370241168ad76ad30dd663568556ea3e524c48aafdbf86ae9d0c8e8f76f48a1c34a7a830457cff66c4417bbf19acb7ac952daeaaec65121e7a0d5
-  data.tar.gz: 3f1bec26161a40c75487e7f98f039df0c135f7de77ee089d72dde29c1a5d5fd19b43661c6aff3c3de58e945b87d330b96a66738a95a208ec7a4e75db1bd85363
+  metadata.gz: 2a27e5b9bc3dafbba8aafd7035732b6ffcb813d57bb216d0e544af30260c0e26f23a920d1b2d6d35882046e74a57f8b492b12b9869de5d820ff6a4e09cafd716
+  data.tar.gz: f1bdc22fda7a6fdf0a37fc1d5bd419947e0fffa16511873dbe8a1549f30bf862566fe74fa4c9952c4338f5263414c99f3d598daec0a599b467e52ebac374b4f7

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# 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.

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,21 +25,21 @@
 "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
 
@@ -48,15 +50,10 @@ Support for new versions is added frequently, please check back regularly for up
 
 # 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**
 
-```
-gem 'appmap'
-```
-
-**Install in test, development groups**
+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
@@ -72,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
@@ -85,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)
@@ -104,6 +109,34 @@ Each entry in the `packages` list is a YAML object which has the following keys:
   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
 
 ## RSpec
@@ -129,10 +162,7 @@ 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
@@ -145,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:
@@ -188,13 +201,13 @@ require_relative '../config/environment'
 2) Run your tests as you normally would with the environment variable `APPMAP=true`. For example:  
 
 ```
-$ APPMAP=true bundle exec rake
+$ APPMAP=true bundle exec rake test
 ```
 
 or
 
 ```
-$ APPMAP=true bundle exec -Ilib -Itest test/*
+$ 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:
@@ -251,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
@@ -274,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
-
-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.
+# AppMap for VSCode
 
-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/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/rails/request_handler.rb

@@ -47,9 +47,14 @@ module AppMap
 
         private
 
-        def normalized_path(request)
-          route = ::Rails.application.routes.router.enum_for(:recognize, request).first
-          route.first.path.spec.to_s if route
+        def normalized_path(request, router = ::Rails.application.routes.router)
+          router.recognize request do |route, _|
+            app = route.app
+            next unless app.matches? request
+            return normalized_path request, app.rack_app.routes.router if app.engine?
+
+            return route.path.spec.to_s
+          end
         end
       end
 

data/lib/appmap/railtie.rb

@@ -5,13 +5,9 @@ module AppMap
   class Railtie < ::Rails::Railtie
     config.appmap = ActiveSupport::OrderedOptions.new
 
-    initializer 'appmap.init' do |_| # params: app
-      require 'appmap'
-    end
-
     # appmap.subscribe subscribes to ActiveSupport Notifications so that they can be recorded as
     # AppMap events.
-    initializer 'appmap.subscribe', after: 'appmap.init' do |_| # params: app
+    initializer 'appmap.subscribe' do |_| # params: app
       require 'appmap/rails/sql_handler'
       require 'appmap/rails/request_handler'
       ActiveSupport::Notifications.subscribe 'sql.sequel', AppMap::Rails::SQLHandler.new

data/lib/appmap/version.rb

@@ -3,7 +3,7 @@
 module AppMap
   URL = 'https://github.com/applandinc/appmap-ruby'
 
-  VERSION = '0.39.1'
+  VERSION = '0.40.0'
 
   APPMAP_FORMAT_VERSION = '1.4'
 end

data/spec/fixtures/hook/labels.rb

@@ -0,0 +1,6 @@
+# @label has-cls-label
+class ClassWithLabel
+  # @label has-fn-label
+  def fn_with_label
+  end
+end

data/spec/fixtures/rails5_users_app/Gemfile

@@ -33,11 +33,10 @@ appmap_options = \
     { path: appmap_path }
   else
     {}
-  end.merge(require: %w[appmap appmap/railtie])
-
-gem 'appmap', appmap_options
+  end.merge(require: %w[appmap])
 
 group :development, :test do
+  gem 'appmap', appmap_options
   gem 'cucumber-rails', require: false
   gem 'rspec-rails'
   # Required for Sequel, since without ActiveRecord, the Rails transactional fixture support

data/spec/fixtures/rails5_users_app/config/application.rb

@@ -19,6 +19,8 @@ when 'activerecord'
   require 'active_record/railtie'
 end
 
+require 'appmap/railtie' if defined?(AppMap)
+
 # require "active_storage/engine"
 # require "action_mailer/railtie"
 # require "action_cable/engine"

data/spec/fixtures/rails6_users_app/Gemfile

@@ -34,11 +34,10 @@ appmap_options = \
     { path: appmap_path }
   else
     {}
-  end.merge(require: %w[appmap appmap/railtie])
-
-gem 'appmap', appmap_options
+  end.merge(require: %w[appmap])
 
 group :development, :test do
+  gem 'appmap', appmap_options
   gem 'cucumber-rails', require: false
   gem 'rspec-rails'
   # Required for Sequel, since without ActiveRecord, the Rails transactional fixture support

data/spec/fixtures/rails6_users_app/config/application.rb

@@ -19,6 +19,8 @@ when 'activerecord'
   require 'active_record/railtie'
 end
 
+require 'appmap/railtie' if defined?(AppMap)
+
 # require "active_storage/engine"
 # require "action_mailer/railtie"
 # require "action_cable/engine"

data/spec/hook_spec.rb

@@ -61,6 +61,32 @@ describe 'AppMap class Hooking', docker: false do
     AppMap.configuration = nil
   end
 
+  it 'parses labels from comments' do
+    _, tracer = invoke_test_file 'spec/fixtures/hook/labels.rb' do
+      ClassWithLabel.new.fn_with_label
+    end
+    class_map = AppMap.class_map(tracer.event_methods).to_yaml
+    expect(Diffy::Diff.new(<<~YAML, class_map).to_s).to eq('')
+    ---
+    - :name: spec/fixtures/hook/labels.rb
+      :type: package
+      :children:
+      - :name: ClassWithLabel
+        :type: class
+        :children:
+        - :name: fn_with_label
+          :type: function
+          :location: spec/fixtures/hook/labels.rb:4
+          :static: false
+          :labels:
+          - has-fn-label
+          :comment: "# @label has-fn-label\\n"
+          :source: |2
+              def fn_with_label
+              end
+      YAML
+  end
+
   it 'hooks an instance method that takes no arguments' do
     events_yaml = <<~YAML
     ---

data/spec/spec_helper.rb

@@ -3,6 +3,7 @@ require 'net/http'
 require 'json'
 require 'yaml'
 require 'English'
+require 'byebug'
 require 'webdrivers/chromedriver'
 
 # Disable default initialization of AppMap

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: appmap
 version: !ruby/object:Gem::Version
-  version: 0.39.1
+  version: 0.40.0
 platform: ruby
 authors:
 - Kevin Gilpin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-01-22 00:00:00.000000000 Z
+date: 2021-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -319,6 +319,7 @@ files:
 - ".rubocop.yml"
 - ".travis.yml"
 - CHANGELOG.md
+- CONTRIBUTING.md
 - Dockerfile.appmap
 - Gemfile
 - LICENSE.txt
@@ -386,6 +387,7 @@ files:
 - spec/fixtures/hook/constructor.rb
 - spec/fixtures/hook/exception_method.rb
 - spec/fixtures/hook/instance_method.rb
+- spec/fixtures/hook/labels.rb
 - spec/fixtures/hook/singleton_method.rb
 - spec/fixtures/rack_users_app/.dockerignore
 - spec/fixtures/rack_users_app/.gitignore