appmap 0.61.1 → 0.62.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8238a1a1651c5fb157b7603ff92169e3e44097318057eb3ef29d57d600817335
-  data.tar.gz: dd805a2bfa96ae3da4ea3bc47df524aa606e9b6dc69d943daa0a360f8da98ea5
+  metadata.gz: 3a6320c85ad8807149cb904032ad4f9a316b7bcd9454985e0851601745dbca70
+  data.tar.gz: 18434ce1e06c9f3580c9d86bca8dc21966f7c728a20e8c0d782638af5ce93a28
 SHA512:
-  metadata.gz: 41e1766995e26ebf75d33403c7b4d72e562b8d14202d3e34f094a276254f67e193b957ea1e26b8e0a561328ed7594fb1dce8cf554ee780df7155e276f7e04e5f
-  data.tar.gz: ba4c314bf9b07b377ea7e3714c082f9121bc082add10d04118e59c9cc0fd4ccdc9575159f6e6023bf0acf25a28cf8559f4d3a00f6942b1f0c17bdd7face0c2f1
+  metadata.gz: 6d3069df241f58d2d2e6497713ceeef3a5d97dc3ba5f11acd9eb25834ebc51bca21516717cb5ee941ac4ea4373ec17c5fe956f493705baa858a7ebac69b8c48e
+  data.tar.gz: 26dceefdd1aec688c9a7d17aa5ebfddf42310b9557905caccd3594d86b1b048fa72d0ca99004f4aae4f6262dd2f282f03c68d9e0377a70ca854c0713f424b652

data/.travis.yml

@@ -14,14 +14,6 @@ addons:
 services:
 - docker
 
-# We expect RAILS_ENV to start off unset, then adjust its value as
-# necessary.
-before_script:
-  - unset RAILS_ENV
-
-cache:
-  bundler: true
-
 before_install:
   # see https://blog.travis-ci.com/docker-rate-limits 
   # and also https://www.docker.com/blog/what-you-need-to-know-about-upcoming-docker-hub-rate-limiting/
@@ -33,22 +25,20 @@ before_install:
     fi
   - |
     nvm install --lts \
-      && nvm use --lts
+      && nvm use --lts \
+      && npm i -g yarn
 
-# GEM_ALTERNATIVE_NAME only needed for deployment 
 jobs:
   include:
   - stage: test
-    script:
-    - set -e
-    - mkdir tmp
-    - npm i -g yarn
-    - GEM_ALTERNATIVE_NAME='' bundle exec rake gem:build test
+    env:
+      # GEM_ALTERNATIVE_NAME only needed for deployment 
+      - GEM_ALTERNATIVE_NAME=''
+    script: bundle exec rake
 
 before_deploy:
   - |
     npm i -g \
-      yarn \
       semantic-release \
       @semantic-release/git \
       @semantic-release/changelog \

data/ARCHITECTURE.md

@@ -0,0 +1,68 @@
+# `appmap-ruby` architecture
+
+## Official documentation
+
+The official documentation for `appmap-ruby` is at [appland.com/docs](https://appland.com/docs/reference/appmap-ruby.html).
+
+## Integration with appmap-js
+
+Most of the analytics functionality for AppMap JSON is implemented in [appmap-js](https://github.com/applandinc/appmap-js/). In particular, `packages/cli`. `appmap-ruby` includes the source code and dependencies of `@appland/cli`. Check the [Rakefile](./Rakefile) for references to npm and/or yarn to see how the packaging works.
+
+`appmap-ruby` executes command-line programs provdied by `@appland/cli`; it doesn't attempt to load a Node.js library in-process. `@appland/cli` commands are designed to produce clean output on stdout, which is obtained and processed by `appmap-ruby`.
+
+## Swagger (OpenAPI) generation
+
+`appmap-ruby` provides a [Rake task](./lib/appmap/swagger/rake_tasks.rb) to generate Swagger files from AppMaps. The majority of the Swagger is generated by calling out to `appmap-js swagger`. `appmap-ruby` makes it Ruby-friendly by wrapping it with Rake, and by adding doc strings to the Swagger by converting RDoc to HTML. It also post-processes the Swagger to remove volatile parameter examples, producing `openapi_stable.yml`. 
+
+**Configuration**
+
+The Swagger task supports [configuration settings](./lib/appmap/swagger/configuration.rb) via appmap.yml. Put the settings under the `swagger` key. 
+
+The API version can also be specified explicitly in Ruby code, when the Rake task is defined:
+
+```ruby
+AppMap.configuration.swagger_config.project_version = \
+  [ 
+    'v',
+    File.read(File.join(Rails.root, 'VERSION')).strip,
+    '_',
+    `git rev-parse --short HEAD`.strip
+  ].join
+```
+
+**Note** From experience, it seems like almost all of the value of the Swagger gen is provided by openapi_stable. Therefore, in the future this may become the only output from the Rake task, and the RDoc to HTML functionality may be removed.
+
+The package `appmap/swagger` is loaded automatically by `appmap`, when Rake is available in the bundle.
+
+**Blogs and videos**
+
+* [How to auto-generate detailed Swagger/OpenAPI for all your Rails routes (Dev.to)](https://dev.to/appland/how-to-auto-generate-swagger-openapi-doc-for-your-web-services-3npn)
+* [Generate Swagger for your Rails project, with no code changes, in 2 ¹/₂ minutes](https://dev.to/appland/generate-swagger-for-your-rails-project-with-no-code-changes-in-2-minutes-3abj)
+
+## Depends (incremental testing)
+
+`appmap-ruby` provides a [Rake task](./lib/appmap/depends/rake_tasks.rb) to automatically run tests and update AppMaps as local source files and test files are modified. It leans heavily on the `depends` command provided by `@appland/cli`. To understand how the Rake tasks work, consider running `appmap-js depends` on your local AppMaps - you can `touch` source files to see the dependency detection in action.
+
+However, computing which AppMaps need updating as a result of source files changes is only part of the story. `depends` also has to:
+
+* Detect added, changed, and removed test files.
+* Run the tests which are determined to be out of date.
+* Update the AppMap index after updating the AppMaps.
+* Remove any AppMaps which refer to tests that have been deleted.
+
+Because `depends` has some complexity, there is an [API](./lib/appmap/depends/api.rb) module that implements key commands. To understand `depends` in further detail, after trying out the `@appland/cli` command, read this API.
+
+The package `appmap/depends` is loaded automatically by `appmap`, when Rake is available in the bundle.
+
+**Configuration**
+
+The Depends task supports [configuration settings](./lib/appmap/depends/configuration.rb) via appmap.yml. Put the settings under the `depends` key. Some configuration settings for Depends are specified as fully-qualified method names (e.g. `Class::Name.method_name`). The Rake task definition code should ensure that the code for any customized methods is loaded and available. At the time of this writing, the primary reasons for overridding the default Depends behavior are:
+
+* Inject custom environment variables into the test command.
+* Override the default test command string.
+
+There are separate settings for `rspec` and `minitest`.
+
+**Blogs and videos**
+
+* [July 2021 Roadmap](https://appland.com/videos/2021/07/01/appmap-july-2021-roadmap/)

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+# [0.62.0](https://github.com/applandinc/appmap-ruby/compare/v0.61.1...v0.62.0) (2021-07-21)
+
+
+### Bug Fixes
+
+* Update @appland/cli version ([e41fd65](https://github.com/applandinc/appmap-ruby/commit/e41fd6527dfc8730ad57471a62b3a058068829c8))
+
+
+### Features
+
+* Add 'depends' Rake tasks ([a2e6793](https://github.com/applandinc/appmap-ruby/commit/a2e67939ae4d580eabf666ee52287e66701bca53))
+* Add standalone appmap-index command ([ee497c9](https://github.com/applandinc/appmap-ruby/commit/ee497c9d1bb1eedf426f50fd00775d2421a852bf))
+* Update @appland/cli to 1.3.0 ([5821df3](https://github.com/applandinc/appmap-ruby/commit/5821df304665de6b0c2277da760d34efe1232766))
+* User no longer has to supply the command to run tests ([7ac2fed](https://github.com/applandinc/appmap-ruby/commit/7ac2fed796a09d53faacf40682f27a7c617f63da))
+
 ## [0.61.1](https://github.com/applandinc/appmap-ruby/compare/v0.61.0...v0.61.1) (2021-07-16)
 
 

data/exe/appmap-index

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.join(__dir__, '../lib')
+
+require 'appmap/command/index'
+AppMap::Command::Index.run

data/lib/appmap.rb

@@ -18,6 +18,7 @@
 # - appmap/rspec
 # - appmap/minitest
 # - appmap/swagger (Rake task)
+# - appmap/depends (Rake task)
 
 require 'appmap/version'
 require 'appmap/agent'
@@ -70,6 +71,7 @@ lambda do
 
   if defined?(::Rake)
     require 'appmap/swagger'
+    require 'appmap/depends'
   end
   
 end.call

data/lib/appmap/agent.rb

@@ -57,17 +57,6 @@ module AppMap
       end
     end
 
-    def config_message(msg)
-      logger = if defined?(::Rails) && ::Rails.logger
-        ::Rails.logger
-      elsif ENV['DEBUG'] == 'true'
-        method(:warn)
-      else
-        ->(msg) { }
-      end
-      logger.call(msg)
-    end
-
     # Used to start tracing, stop tracing, and record events.
     def tracing
       @tracing ||= Trace::Tracing.new

data/lib/appmap/command/index.rb

@@ -0,0 +1,25 @@
+require 'appmap/version'
+require 'appmap/node_cli'
+
+module AppMap
+  module Command
+    class Index < AppMap::NodeCLI
+      class << self
+        def run
+          command = Index.new(verbose: ENV['DEBUG'] == 'true')
+          command.index(ARGV)
+        end
+      end
+
+      def index(arguments)
+        detect_nodejs
+
+        arguments.unshift 'index'
+        arguments.unshift APPMAP_JS
+        arguments.unshift 'node'
+
+        exec(*arguments)
+      end
+    end
+  end
+end

data/lib/appmap/command/inspect.rb

@@ -1,5 +1,4 @@
 require 'appmap/version'
-require 'appmap/config'
 require 'appmap/node_cli'
 
 module AppMap

data/lib/appmap/config.rb

@@ -7,6 +7,7 @@ require 'appmap/handler/net_http'
 require 'appmap/handler/rails/template'
 require 'appmap/service/guesser'
 require 'appmap/swagger/configuration'
+require 'appmap/depends/configuration'
 
 module AppMap
   class Config
@@ -228,17 +229,19 @@ module AppMap
       'JSON::Ext::Generator::State' => TargetMethods.new(:generate, Package.build_from_path('json', package_name: 'json', labels: %w[format.json.generate])),
     }.freeze
 
-    attr_reader :name, :appmap_dir, :packages, :exclude, :swagger_config, :hooked_methods, :builtin_hooks
+    attr_reader :name, :appmap_dir, :packages, :exclude, :swagger_config, :depends_config, :hooked_methods, :builtin_hooks
 
     def initialize(name,
       packages: [],
       swagger_config: Swagger::Configuration.new,
+      depends_config: Depends::Configuration.new,
       exclude: [],
       functions: [])
       @name = name
       @appmap_dir = AppMap::DEFAULT_APPMAP_DIR
       @packages = packages
       @swagger_config = swagger_config
+      @depends_config = depends_config
       @hook_paths = Set.new(packages.map(&:path))
       @exclude = exclude
       @builtin_hooks = BUILTIN_HOOKS
@@ -359,6 +362,10 @@ module AppMap
           swagger_config = Swagger::Configuration.load(config_data['swagger'])
           config_params[:swagger_config] = swagger_config
         end
+        if config_data['depends']
+          depends_config = Depends::Configuration.load(config_data['depends'])
+          config_params[:depends_config] = depends_config
+        end
 
         Config.new name, config_params
       end

data/lib/appmap/depends.rb

@@ -0,0 +1,2 @@
+require 'appmap/depends/configuration'
+require 'appmap/depends/rake_tasks'

data/lib/appmap/depends/api.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative 'util'
+require_relative 'node_cli'
+require_relative 'test_file_inspector'
+require_relative 'test_runner'
+
+module AppMap
+  module Depends
+    class API
+      attr_reader :verbose
+
+      def initialize(verbose)
+        @verbose = verbose
+      end
+
+      # Compute the set of test files which are "out of date" with respect to source files in +base_dir+.
+      # Use AppMaps in +appmap_dir+ to make this computation.
+      def modified(appmap_dir:, base_dir:)
+        depends = AppMap::Depends::NodeCLI.new(verbose: verbose, appmap_dir: appmap_dir)
+        depends.base_dir = base_dir if base_dir
+        test_files = depends.depends
+
+        Set.new prune_directory_prefix(test_files)
+      end
+
+      # Compute which test case files have been added, removed, changed, or failed, relative to the
+      # AppMaps.
+      def inspect_test_files(appmap_dir:, test_file_patterns:)
+        inspector = AppMap::Depends::TestFileInspector.new(appmap_dir, test_file_patterns)
+        inspector.report
+      end
+
+      # Print a brief report to STDERR.
+      def report_list(title, files)
+        warn [ title, files.to_a.sort.join(' ') ].join(': ') unless files.empty?
+      end
+
+      # Run the specified test files. After running the tests, update the AppMap index.
+      # TODO: If the tests fail, this method will raise, and the index won't be updated.
+      # What's the right behavior for the index if there is a test failure? Current behavior may not match
+      # user expectations.
+      def run_tests(test_files, appmap_dir:)
+        test_files = test_files.to_a.sort
+        warn "Running tests: #{test_files.join(' ')}"
+
+        TestRunner.new(test_files).run
+
+        AppMap::NodeCLI.new(verbose: verbose, appmap_dir: appmap_dir).index_appmaps
+      end
+
+      # Remove out-of-date AppMaps which are unmodified +since+ the start time. This operation is used to remove AppMaps
+      # that were previously generated from a test case that has been removed from a test file.
+      #
+      # * +since+ an instance of Time
+      def remove_out_of_date_appmaps(since, appmap_dir:, base_dir:)
+        since_ms = ( since.to_f * 1000 ).to_i
+
+        depends = AppMap::Depends::NodeCLI.new(verbose: verbose, appmap_dir: appmap_dir)
+        depends.base_dir = base_dir if base_dir
+        depends.field = nil
+        out_of_date_appmaps = depends.depends
+        removed = []
+        out_of_date_appmaps.each do |appmap_path|
+          mtime_path = File.join(appmap_path, 'mtime')
+          next unless File.exists?(mtime_path)
+
+          appmap_mtime = File.read(mtime_path).to_i
+          if appmap_mtime < since_ms
+            Util.delete_appmap appmap_path
+            removed << appmap_path
+          end
+        end
+        removed.sort
+      end
+
+      protected
+
+      def prune_directory_prefix(files)
+        Array(files).map(&Util.method(:normalize_path))
+      end
+    end
+  end
+end

data/lib/appmap/depends/configuration.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'appmap'
+
+module AppMap
+  module Depends
+    class Configuration
+      # Default file to write Rake task results.
+      DEFAULT_OUTPUT_FILE = File.join('tmp', 'appmap_depends.txt')
+      # Default base branches which will be checked for existance.
+      DEFAULT_BASE_BRANCHES = %w[remotes/origin/main remotes/origin/master].freeze
+      # Default pattern to enumerate test cases.
+      DEFAULT_TEST_FILE_PATTERNS = [ 'spec/**/*_spec.rb', 'test/**/*_test.rb' ].freeze
+      DEFAULT_DEPENDENT_TASKS = [ :swagger ].freeze
+      DEFAULT_DESCRIPTION = 'Bring AppMaps up to date with local file modifications, and updated derived data such as Swagger files'
+      DEFAULT_ENVIRONMENT_METHOD = 'AppMap::Depends.test_env'
+      DEFAULT_RSPEC_SELECT_TESTS_METHOD = 'AppMap::Depends.select_rspec_tests'
+      DEFAULT_MINITEST_SELECT_TESTS_METHOD = 'AppMap::Depends.select_minitest_tests'
+      DEFAULT_RSPEC_TEST_COMMAND_METHOD = 'AppMap::Depends.rspec_test_command'
+      DEFAULT_MINITEST_TEST_COMMAND_METHOD = 'AppMap::Depends.minitest_test_command'
+
+      attr_accessor :base_dir,
+        :base_branches,
+        :test_file_patterns,
+        :dependent_tasks,
+        :description,
+        :rspec_environment_method,
+        :minitest_environment_method,
+        :rspec_select_tests_method,
+        :minitest_select_tests_method,
+        :rspec_test_command_method,
+        :minitest_test_command_method,
+
+      class << self
+        def load(config_data)
+          Configuration.new.tap do |config|
+            config_data.each do |k,v|
+              config.send "#{k}=", v
+            end
+          end
+        end
+      end
+
+      def initialize
+        @base_dir = nil
+        @base_branches = DEFAULT_BASE_BRANCHES
+        @test_file_patterns = DEFAULT_TEST_FILE_PATTERNS
+        @dependent_tasks = DEFAULT_DEPENDENT_TASKS
+        @description = DEFAULT_DESCRIPTION
+        @rspec_environment_method = DEFAULT_ENVIRONMENT_METHOD
+        @minitest_environment_method = DEFAULT_ENVIRONMENT_METHOD
+        @rspec_select_tests_method = DEFAULT_RSPEC_SELECT_TESTS_METHOD
+        @minitest_select_tests_method = DEFAULT_MINITEST_SELECT_TESTS_METHOD
+        @rspec_test_command_method = DEFAULT_RSPEC_TEST_COMMAND_METHOD
+        @minitest_test_command_method = DEFAULT_MINITEST_TEST_COMMAND_METHOD
+      end
+    end
+  end
+end

data/lib/appmap/depends/node_cli.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require 'appmap/node_cli'
+
+module AppMap
+  module Depends
+    # +Command+ wraps the Node +depends+ command.
+    class NodeCLI < ::AppMap::NodeCLI
+      # Directory name to prefix to the list of modified files which is provided to +depends+.
+      attr_accessor :base_dir
+      # AppMap field to report.
+      attr_accessor :field
+
+      def initialize(verbose:, appmap_dir:)
+        super(verbose: verbose, appmap_dir: appmap_dir)
+
+        @base_dir = nil
+        @field = 'source_location'
+      end
+
+      # Returns the source_location field of every AppMap that is "out of date" with respect to one of the
+      # +modified_files+.
+      def depends(modified_files = nil)
+        index_appmaps
+
+        cmd = %w[depends]
+        cmd += [ '--field', field ] if field
+        cmd += [ '--appmap-dir', appmap_dir ] if appmap_dir
+        cmd += [ '--base-dir', base_dir ] if base_dir
+
+        options = {}
+        if modified_files
+          cmd << '--stdin-files'
+          options[:stdin_data] = modified_files.map(&:shellescape).join("\n")
+          warn "Checking modified files: #{modified_files.join(' ')}" if verbose
+        end
+
+        stdout, = command cmd, options
+        stdout.split("\n")
+      end
+    end
+  end
+end