appmap 0.31.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 54b9a05aeb3eea84572b115a6de1106e6743b74046048e3c168f99a75aa9e669
+  data.tar.gz: eb8a690376d833c4bec9f0789c5499f413f7dcb3b1ef111257785bd344861f64
+SHA512:
+  metadata.gz: 453f06041220ecd0a4fc563ae007e7f8247d3dfcccf49657cbf47ddc53d0175e6834d1dbd89a2338a032d6cfae866929216b58a11bb6f0fe3fd2ea69508d7b2a
+  data.tar.gz: 77f372ad255c3c664c690affa2962958cebd1e8f34579809e4d975fdf57404889d8506f9153d44a95afda297ffe7b1654529252a5293487477e803bdf0cc9608

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/
+.bundle
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+tmp/
+vendor
+node_modules
+Gemfile.lock
+appmap.json
+.vscode
+.byebug_history
+

data/.rubocop.yml

@@ -0,0 +1,27 @@
+Layout/SpaceInsideArrayLiteralBrackets:
+  Enabled: false
+
+# We have squiggly heredocs
+Layout/HeredocIndentation:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 120
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+  
+Style/AndOr:
+  Enabled: false
+
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true

data/.ruby-version

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

data/.travis.yml

@@ -0,0 +1,44 @@
+language: ruby
+
+addons:
+  apt:
+    packages:
+      # https://docs.travis-ci.com/user/docker/#installing-a-newer-docker-version
+      - docker-ce
+
+services:
+- docker
+
+# We expect RAILS_ENV to start off unset, then adjust its value as
+# necessary.
+before_script:
+  - unset RAILS_ENV
+  
+jobs:
+  include:
+  - stage: minitest
+    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
+    

data/CHANGELOG.md

@@ -0,0 +1,199 @@
+# v0.31.0
+
+* Add the ability to hook methods by default, and optionally add labels to them in the
+  classmap. Use it to hook `ActiveSupport::SecurityUtils.secure_compare`.
+  
+# v0.30.0
+
+* Add support for Minitest.
+
+# v0.29.0
+
+* Add `lib/appmap/record.rb`, which can be `require`d to record the rest of the process.
+
+# v0.28.1
+
+* Fix the `defined_class` recorded in an appmap for an instance method included in a class
+  at runtime.
+* Only include the `static` attribute on `call` events in an appmap. Determine its value
+  based on the receiver of the method call.
+
+# v0.28.0
+
+* Change behavior of **AppMap.record** to return a complete AppMap as a Hash.
+* Update README with information about recording Cucumber tests.
+* **AppMap.initialize** automatically runs when `AppMap` is required, unless disabled
+  by environment variable `APPMAP_INITIALIZE=false`.
+* **AppMap.hook** no longer takes a `configuration` argument.
+* Add **AppMap::Util.scenario_filename**.
+
+# 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.
+
+# v0.22.0
+
+* **RSpec** recorder generates an "inventory" (AppMap with classMap, without events) named `Inventory.appmap.json`.
+* **appmap inspect** generates an inventory AppMap which includes `version`, `metadata`, and `classMap`. Previously, the file output by this command was the class map represented as an array.
+
+# v0.21.0
+
+* Scenario data includes `recorder` and `client` info, describing how the data was recorded.
+
+# v0.20.0
+
+Updated to [AppMap file format](https://github.com/applandinc/appmap) version 1.2.
+
+* **Event `message`** is now an array of parameter objects.
+* The value of each `appmap:` tags in an RSpec is recorded as a `label` in the AppMap file metadata.
+* `layout` is removed from AppMap file metadata.
+
+# v0.19.0
+
+* **RSpec** feature and feature group names can be inferred from example group and example names.
+* Stop using `ActiveSupport::Inflector.transliterate`, since it can cause exceptions.
+* Handle StandardError which occurs while calling `#inspect` of an object.
+
+# 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,300 @@
+- [About](#about)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Running](#running)
+  - [RSpec](#rspec)
+  - [Minitest](#minitest)
+  - [Cucumber](#cucumber)
+  - [Remote recording](#remote-recording)
+  - [Ruby on Rails](#ruby-on-rails)
+- [Uploading AppMaps](#uploading-appmaps)
+- [Development](#development)
+  - [Running tests](#running-tests)
+  - [Using fixture apps](#using-fixture-apps)
+    - [`test/fixtures`](#testfixtures)
+    - [`spec/fixtures`](#specfixtures)
+- [Build status](#build-status)
+
+# About
+
+`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
+(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.
+
+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 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.
+
+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.
+
+# Installation
+
+Add `gem 'appmap'` to your Gemfile just as you would any other dependency.
+
+**Global installation**
+
+```
+gem 'appmap'
+```
+
+**Install in test, development groups**
+
+```
+group :development, :test do
+  gem 'appmap'
+end
+```
+
+Then install with `bundle`.
+
+# Configuration
+
+When you run your program, the `appmap` gem reads configuration settings from `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.
+
+**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.
+* **exclude** A list of files and directories which will be ignored. By default, all modules, classes and public
+  functions are inspected.
+
+# Running
+
+## RSpec
+
+To record RSpec tests, follow these additional steps:
+
+1) Require `appmap/rspec` in your `spec_helper.rb`.
+
+```ruby
+require 'appmap/rspec'
+```
+
+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`:
+
+```sh-session
+$ APPMAP=true bundle exec rspec -t appmap
+```
+
+Each RSpec test will output an AppMap file into the directory `tmp/appmap/rspec`. For example:
+
+```
+$ 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:
+
+1) Require `appmap/minitest` in `test_helper.rb`
+
+```ruby
+require 'appmap/minitest'
+```
+
+2) Run the tests with the environment variable `APPMAP=true`:
+
+```sh-session
+$ APPMAP=true bundle exec -Ilib -Itest test/*
+```
+
+Each Minitest test will output an AppMap file into the directory `tmp/appmap/minitest`. For example:
+
+```
+$ find tmp/appmap/minitest
+Hello_says_hello_when_prompted.appmap.json
+```
+
+## Cucumber
+
+To record Cucumber tests, follow these additional steps:
+
+1) Require `appmap/cucumber` in `support/env.rb`:
+
+```ruby
+require 'appmap/cucumber'
+```
+
+2) Create an `Around` hook in `support/hooks.rb` to record the scenario:
+
+
+```ruby
+if AppMap::Cucumber.enabled?
+  Around('not @appmap-disable') do |scenario, block|
+    appmap = AppMap.record do
+      block.call
+    end
+
+    AppMap::Cucumber.write_scenario(scenario, appmap)
+  end
+end
+```
+
+3) Run the tests with the environment variable `APPMAP=true`:
+
+```sh-session
+$ APPMAP=true bundle exec cucumber
+```
+
+Each Cucumber test will output an AppMap file into the directory `tmp/appmap/cucumber`. For example:
+
+```
+$ find tmp/appmap/cucumber
+Hello_Says_hello_when_prompted.appmap.json
+```
+
+## Remote recording
+
+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'
+
+unless Rails.env.test?
+  Rails.application.config.middleware.insert_after \
+    Rails::Rack::Logger,
+    AppMap::Middleware::RemoteRecording
+end
+```
+
+2. Download and unpack the [AppLand browser extension](https://github.com/applandinc/appland-browser-extension). Install into Chrome using `chrome://extensions/`. Turn on "Developer Mode" and then load the extension using the "Load unpacked" button.
+
+3. Start your Rails application server. For example:
+
+```sh-session
+$ bundle exec rails server
+```
+
+4. Open the AppApp browser extension and push `Start`.
+
+5. Use your app. For example, perform a login flow, or run through a manual UI test.
+
+6. Open the AppApp 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.
+
+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).
+
+# Development
+
+## Running tests
+
+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
+```  
+
+## Using fixture apps
+
+### `test/fixtures`
+
+The fixture apps in `test/fixtures` are plain Ruby projects that exercise the basic functionality of the
+`appmap` gem. To develop in a fixture, simple enter the fixture directory and `bundle`.
+
+### `spec/fixtures`
+
+The fixture apps in `spec/fixtures` are simple Rack, Rails4, and Rails5 apps.
+You can use them to interactively develop and test the recording features of the `appmap` gem.
+These fixture apps are more sophisticated than `test/fixtures`, because they include additional 
+resources such as a PostgreSQL database.
+
+To build the fixture container images, first run:
+
+```sh-session
+$ bundle exec rake fixtures:all
+```
+
+This will build the `appmap.gem`, along with a Docker image for each fixture app.
+
+Then move to the directory of the fixture you want to use, and provision the environment.
+In this example, we use Ruby 2.6.
+
+```sh-session
+$ export RUBY_VERSION=2.6
+$ docker-compose up -d pg
+$ sleep 10s # Or some reasonable amount of time
+$ docker-compose run --rm app ./create_app
+```
+
+Now you can start a development container.
+
+```sh-session
+$ docker-compose run --rm -v $PWD/../../..:/src/appmap-ruby app bash
+Starting rails_users_app_pg_1 ... done
+root@6fab5f89125f:/app# cd /src/app
+root@6fab5f89125f:/src/app# bundle config local.appmap /src/appmap-ruby
+root@6fab5f89125f:/src/app# bundle update appmap
+```
+
+At this point, the bundle is built with the `appmap` gem located  in `/src/appmap`, which is volume-mounted from the host.
+So you can edit the fixture code and the appmap code and run test commands such as `rspec` and `cucumber` in the container.
+For example:
+
+```sh-session
+root@6fab5f89125f:/src/app# bundle exec rspec
+Configuring AppMap from path appmap.yml
+....
+
+Finished in 0.07357 seconds (files took 2.1 seconds to load)
+4 examples, 0 failures
+```
+
+# Build status
+[![Build Status](https://travis-ci.org/applandinc/appmap-ruby.svg?branch=master)](https://travis-ci.org/applandinc/appmap-ruby)