appmap 0.18.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 536929649e77a1a136aabc2ffbf8df4b43a1f51420334b4d556f5978aa205e06
+  data.tar.gz: b052fa2b3853f962932216a21f2c0d07052e7288695787bc60fccba4ed97cf1f
+SHA512:
+  metadata.gz: fca12acdd2d3a096cc1ecb8bb8d5e19fb5f88ad91e67de83aa71d59e9cdaa0a70733d1904e4d29078ea94eddbc3005d1cb33ea4e86f0fad95270ec7b3bd35e67
+  data.tar.gz: 395891a44f2d185bcb5bd447bbe39d1d16a07c30c065c6fb7a45ea5979f54f7c1b30efab1baf6043838a9e9d166e1f14ff4412b9a04743d03c8a818a4c082b15

data/.dockerignore

@@ -0,0 +1,5 @@
+vendor
+node_modules
+spec/fixtures/rails_users_app
+spec/fixtures/rack_users_app
+

data/.gitignore

@@ -0,0 +1,17 @@
+.DS_Store
+/html/
+/.appmap/
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+tmp/
+vendor
+node_modules
+Gemfile.lock
+appmap.json
+.byebug_history
+

data/.rubocop.yml

@@ -0,0 +1,18 @@
+Style/MultilineBlockChain:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+
+Layout/SpaceInsideArrayLiteralBrackets:
+  Enabled: false
+
+# We have squiggly heredocs
+Layout/IndentHeredoc:
+  Enabled: false
+
+Style/AndOr:
+  Enabled: false
+
+Metrics/LineLength:
+  Max: 120

data/.ruby-version

@@ -0,0 +1 @@
+2.6.2

data/CHANGELOG.md

@@ -0,0 +1,100 @@
+# v0.18.1
+
+* Now tested with Rails 4, 5, and 6.
+* Now tested with Ruby 2.5 and 2.6.
+* `explain_sql` is no longer collected.
+* `appmap/railtie` is automatically required when running in a Rails environment.
+
+# v0.17.0
+
+**WARNING** Breaking changes
+
+* **appmap upload** expects arguments `user` and `org`.
+* **appmap upload** receives and retransmits the scenario batch id
+* assigned by the server.
+
+# v0.16.0
+
+**WARNING** Breaking changes
+
+* **Record button** removed. Frontend interactions are now recorded with a browser extension.
+  As a result, `AppMap::Middleware::RecordButton` has been renamed to 
+  `AppMap::Middleware::RemoteRecording`
+
+# v0.15.1
+
+* **Record button** moved to the bottom of the window.
+
+# v0.15.0
+
+**WARNING** Breaking changes
+
+* **AppMap version** updated to 1.1
+* **Event `parameters`** are reported as an array rather than a map, so that parameter order is preserved.
+* **Event `receiver`** reports the `receiver/this/self` parameter of each method call.
+
+# v0.14.1
+
+* **RSpec recorder** won't try to modify a frozen string.
+
+# v0.14.0
+
+* **SQL queries** are reported for SQLite.
+
+# v0.13.0
+
+* **SQL queries** are reported for ActiveRecord.
+
+# v0.12.0
+
+* **Record button** integrates into any HTML UI and provides a button to record and upload AppMaps.
+
+# v0.11.0
+
+* Information about `language` and `frameworks` is provided in the AppMap `metadata`.
+
+# v0.10.0
+
+* **`AppMap::Algorithm::PruneClassMap`** prunes a class map so that only functions, classes and packages which are
+  referenced by some event are retained.
+
+# v0.9.0
+
+* **`appmap/rspec`** only records trace events which happen during an example block. `before` and `after` events are
+  excluded from the AppMap.
+* **`appmap/rspec`** exports `feature` and `feature_group` attributes to the AppMap `metadata`
+  section.
+
+# v0.8.0
+
+* **`appmap upload`** accepts multiple arguments, to upload multiple files in one command.
+
+# v0.7.0
+
+* **`appmap/railtie`** is provided to integrate AppMap recording into Rails apps.
+  * Use `gem :appmap, require: %w[appmap appmap/railtie]` to activate.
+  * Set Rails configuration setting `config.appmap.enabled = true` to enable recording of the app via the Railtie, and
+    to enable recording of RSpec tests via `appmap/rspec`.
+  * In a non-Rails environment, set `APPMAP=true` to to enable recording of RSpec tests.
+* **SQL queries** are reported as AppMap event `sql_query` data.
+* **`self` attribute** is removed from `call` events.
+
+# v0.6.0
+
+* **Web server requests and responses** through WEBrick are reported as AppMap event `http_server_request` data.
+* **Rails `params` hash** is reported as an AppMap event `message` data.
+* **Rails `request`** is reported as an AppMap event `http_server_request` data.
+
+# v0.5.1
+
+* **RSpec** test recorder is added.
+
+# v0.5.0
+
+* **'inspect', 'record' and 'upload' commands** are converted into a unified 'appmap' command with subcommands.
+* **Config file name** is changed from .appmap.yml to appmap.yml.
+* **`appmap.yml`** configuration format is updated.
+
+# v0.4.0
+
+Initial release.

data/Dockerfile.appmap

@@ -0,0 +1,5 @@
+FROM alpine
+ARG GEM_VERSION
+
+RUN mkdir /pkg
+COPY pkg/appmap-${GEM_VERSION}.gem /pkg/appmap.gem

data/Gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Kevin Gilpin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,133 @@
+- [About](#about)
+- [Installation](#installation)
+- [Configuration](#configuration)
+  - [`packages`](#packages)
+- [Running](#running)
+  - [RSpec](#rspec)
+  - [Rails](#rails)
+- [Uploading](#uploading)
+- [Build status](#build-status)
+
+# About
+
+`appmap-ruby` is a Ruby client for recording and uploading [AppMap](https://github.com/applandinc/appmap) data.
+
+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).
+
+The normal usage of an AppMap client is to run a test case (such as an RSpec test) with AppMap instrumentation enabled.
+The AppMap client will observe and record information about the code execution, and store it in an AppMap file.
+
+The command `appmap upload` is then used to upload the AppMap file to the App.Land server, which processes the file into
+useful displays such as graphical depiction of the code structure and execution.
+
+# Installation
+
+Add `gem 'appmap'` to your Gemfile just as you would any other dependency. You can place the gem in the `test` group.
+
+Then install with `bundle`. 
+
+# Configuration
+
+When you run the AppMap client, it will look for configuration settings in `appmap.yml`. Here's a sample configuration
+file for a typical Rails project:
+
+```yaml
+name: MyProject
+packages:
+- path: app/controllers
+- path: app/models
+```
+
+* **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`
+
+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
+  functions are inspected.
+
+# Running
+
+## RSpec
+
+To instrument RSpec tests, follow these steps:
+
+1) Include the `appmap` gem in your Gemfile
+2) Require `appmap/rspec` in your `spec_helper.rb` or `rails_helper.rb`
+3) Add `appmap: true` to the tests you want to instrument
+4) Add `feature: '<feature name>'` and `feature_group: '<feature group name>'` to your 
+   examples. 
+5) Export the environment variable `APPMAP=true`
+
+Here's an example of an appmap-enabled RSpec test:
+
+```ruby
+describe Hello, feature_group: 'Greeting' do
+  it 'says hello', feature: 'Print a greeting to the console', appmap: true do
+    expect(Hello.new.say_hello).to eq('Hello!')
+  end
+end
+```
+
+Then run the tests:
+
+```sh-session
+$ APPMAP=true bundle exec rspec
+```
+
+Each RSpec test will output a data file into the directory `tmp/appmap/rspec`. For example:
+
+```
+$ find tmp/appmap/rspec
+Hello says hello.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
+
+```
+
+## Rails
+
+To capture ad-hoc AppMaps of your Rails app, use the AppMap Railtie.
+
+1) Include the `appmap` gem in your Gemfile and require both `appmap` and `appmap/railtie`, like this:
+
+```ruby
+gem "appmap", require: %w[appmap appmap/railtie]
+```
+
+2) Export `APPMAP=true` when you start your Rails application server. For example:
+
+```sh-session
+$ APPMAP=true bundle exec rails server
+```
+
+When the Rails app exits, an `appmap.json` file will be written to the project root directory. You can upload it using
+the `appmap upload` command.
+
+# Uploading
+
+To upload an AppMap file to App.Land, run the `appmap upload` command. For example:
+
+```sh-session
+$ appmap upload tmp/appmap/rspec/Hello says hello.json
+Full classMap contains 1 classes
+Pruned classMap contains 1 classes
+Uploaded new scenario: d49f3d16-e9f2-4775-a731-6cb95193927e
+```
+
+# Build status
+
+![Build status](https://travis-ci.org/applandinc/appmap-ruby.svg?branch=master)

data/Rakefile

@@ -0,0 +1,117 @@
+require 'appmap/version'
+GEM_VERSION = AppMap::VERSION
+
+require 'rake/testtask'
+require 'rdoc/task'
+
+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]
+
+def build_base_image(ruby_version)
+  system "docker build" \
+         " --build-arg RUBY_VERSION=#{ruby_version} --build-arg GEM_VERSION=#{GEM_VERSION}" \
+         " -t appmap:#{GEM_VERSION} -f Dockerfile.appmap ." \
+  or raise 'Docker build failed'
+end
+  
+def build_app_image(app, ruby_version)
+  Dir.chdir "spec/fixtures/#{app}" do
+    system "env RUBY_VERSION=#{ruby_version} GEM_VERSION=#{GEM_VERSION}" \
+           " docker-compose build" \
+           " --build-arg RUBY_VERSION=#{ruby_version}" \
+           " --build-arg GEM_VERSION=#{GEM_VERSION}" \
+    or raise 'docker-compose build failed'
+  end
+end
+
+namespace :build do
+  namespace :base do
+    RUBY_VERSIONS.each do |ruby_version|
+      desc ruby_version
+      task ruby_version => ["gem:build"] do
+        build_base_image(ruby_version)
+      end.tap do |t|
+        desc "Build all images"
+        task all: t
+      end
+    end
+  end
+  
+  namespace :fixtures do
+    RUBY_VERSIONS.each do |ruby_version|
+      namespace ruby_version do
+        desc "build:fixtures:#{ruby_version}"
+        FIXTURE_APPS.each do |app|
+          desc app
+          task app => ["base:#{ruby_version}"] do
+            build_app_image(app, ruby_version)
+          end.tap do |t|
+            desc "Build all fixture images for #{ruby_version}"
+            task all: t
+          end
+        end
+      end
+      
+      desc "Build all fixture images"
+      task all: ["#{ruby_version}:all"]
+    end
+  end
+
+  task all: ["fixtures:all"]
+end
+
+def run_specs(ruby_version, task_args)
+  require 'rspec/core/rake_task'
+  require 'climate_control'
+  # Define an rspec rake task for the specified Ruby version. It's hidden (i.e. doesn't have a
+  # description), because it's not intended to be invoked directly
+  RSpec::Core::RakeTask.new("rspec_#{ruby_version}", [:specs]) do |task, args|
+    task.exclude_pattern = 'spec/fixtures/**/*_spec.rb'
+    if args.count > 0
+      # There doesn't appear to be a value for +pattern+ that will
+      # cause it to be ignored. Setting it to '' or +nil+ causes an
+      # empty argument to get passed to rspec, which confuses it.
+      task.pattern = 'never match this'
+      task.rspec_opts = '-f doc '
+      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
+    Rake::Task["rspec_#{ruby_version}"].execute(task_args)
+  end
+end
+
+namespace :spec do
+  RUBY_VERSIONS.each do |ruby_version|
+    desc ruby_version
+    task ruby_version, [:specs] => ["build:fixtures:#{ruby_version}:all"] do |_, task_args|
+      run_specs(ruby_version, task_args)
+    end.tap do|t|
+      desc "Run all specs"
+      task :all, [:specs] => t
+    end
+  end
+end
+
+Rake::RDocTask.new do |rd|
+  rd.main = 'README.rdoc'
+  rd.rdoc_files.include(%w[README.rdoc lib/**/*.rb exe/**/*])
+  rd.title = 'AppMap'
+end
+
+Rake::TestTask.new(:minitest) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task test: %i[spec:all minitest]
+
+task default: :test

data/appmap.gemspec

@@ -0,0 +1,41 @@
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'appmap/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'appmap'
+  spec.version       = AppMap::VERSION
+  spec.authors       = ['Kevin Gilpin']
+  spec.email         = ['kgilpin@gmail.com']
+
+  spec.summary       = %q{Inspect and trace your Ruby code, generating a JSON data file.}
+  spec.homepage      = 'https://github.com/kgilpin/appmap-ruby'
+  spec.license       = 'MIT'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = `git ls-files --no-deleted`.split("
+")
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport'
+  spec.add_dependency 'faraday'
+  spec.add_dependency 'gli'
+  spec.add_dependency 'parser'
+
+  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 'rdoc'
+
+  # Testing
+  spec.add_development_dependency 'climate_control'
+  spec.add_development_dependency 'launchy'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'selenium-webdriver'
+  spec.add_development_dependency 'webdrivers', '~> 4.0'
+end

data/appmap.yml

@@ -0,0 +1,8 @@
+name: AppMap Rubygem
+packages:
+  - path: lib/appmap
+    exclude:
+      - server
+      - trace
+
+  - path: examples

data/examples/install.rb

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.join(__dir__)
+require 'fileutils'
+
+module Command
+  def run_command command
+    `#{command}`.tap do |_|
+      raise "Command failed: #{command}" unless $? == 0
+    end
+  end
+end
+
+class InProjectDirectory
+  attr_reader :project_dir
+
+  def initialize
+    @project_dir = File.expand_path('../tmp/install', __dir__)
+  end
+
+  def perform(&block)
+    FileUtils.rm_rf project_dir
+    FileUtils.mkdir_p project_dir
+    Dir.chdir project_dir, &block
+  end
+end
+
+class InstallExampleCode
+  def perform
+    FileUtils.cp_r File.join(__dir__, 'mock_webapp'), '.'
+  end
+end
+
+class InExampleDirectory
+  def perform(&block)
+    Dir.chdir 'mock_webapp', &block
+  end
+end
+
+class InstallAppmapGem
+  include Command
+
+  def perform
+    run_command 'bundle --local > /dev/null'
+  end
+end
+
+class InspectExampleProject
+  include Command
+
+  def perform
+    FileUtils.mkdir_p '.appmap'
+    run_command "bundle exec #{File.expand_path('../exe/appmap', __dir__)} inspect -o appmap.json"
+  end
+end
+
+class PrintInventory
+  def initialize(inventory)
+    @inventory = inventory
+  end
+
+  def perform
+    puts @inventory
+  end
+end
+
+InProjectDirectory.new.perform do
+  InstallExampleCode.new.perform
+  InExampleDirectory.new.perform do
+    InstallAppmapGem.new.perform
+
+    inventory = InspectExampleProject.new.perform
+    PrintInventory.new(inventory).perform
+  end
+end
+

data/examples/mock_webapp/Gemfile

@@ -0,0 +1 @@
+gem 'appmap', git: '../..', branch: `git rev-parse --abbrev-ref HEAD`.strip

data/examples/mock_webapp/appmap.yml

@@ -0,0 +1,2 @@
+packages:
+  - path: lib

data/examples/mock_webapp/exe/mock_webapp_request

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.join(__dir__, '..', 'lib')
+
+require 'json'
+require 'mock_webapp/user'
+require 'mock_webapp/request'
+require 'mock_webapp/controller'
+
+include MockWebapp
+
+puts JSON.pretty_generate Controller.instance.process(Request.new(id: 'alice'))

data/examples/mock_webapp/lib/mock_webapp/controller.rb

@@ -0,0 +1,23 @@
+module MockWebapp
+  # Mock controller.
+  # @appmap
+  class Controller
+    @controller = nil
+
+    class << self
+      # Singleton factory method.
+      #
+      # @appmap
+      def instance
+        @controller ||= Controller.new
+      end
+    end
+
+    # @appmap
+    def process(request)
+      id = request.params[:id]
+      user = User.find(id)
+      user.to_h
+    end
+  end
+end

data/examples/mock_webapp/lib/mock_webapp/request.rb

@@ -0,0 +1,12 @@
+module MockWebapp
+  RequestStruct = Struct.new(:params)
+
+  # Mock request.
+  # @appmap
+  class Request < RequestStruct
+    # @appmap
+    def initialize(*args)
+      super
+    end
+  end
+end

data/examples/mock_webapp/lib/mock_webapp/user.rb

@@ -0,0 +1,18 @@
+module MockWebapp
+  UserStruct = Struct.new(:login)
+
+  # Mock model object.
+  # @appmap
+  class User < UserStruct
+    USERS = {
+      'alice' => User.new('alice')
+    }.freeze
+
+    class << self
+      # @appmap
+      def find(id)
+        USERS[id] || raise("No such user #{id}")
+      end
+    end
+  end
+end