feat: Provide default appmap.yml settings

If appmap.yml is not found, warn the user.
Detect some possible source paths, and the project name from the .git file,
and use this info to create a temporary appmap.yml.
Print it to the console so the user can use it as a starting point.

Author: kgilpin

lib/appmap.rb

@@ -27,7 +27,7 @@ class << self
     # Gets the configuration. If there is no configuration, the default
     # configuration is initialized.
     def configuration
-      @configuration ||= initialize
+      @configuration ||= initialize_configuration
     end
 
     # Sets the configuration. This is only expected to happen once per
@@ -38,12 +38,19 @@ def configuration=(config)
       @configuration = config
     end
 
-    # Configures AppMap for recording. Default behavior is to configure from "appmap.yml".
+    def default_config_file_path
+      ENV['APPMAP_CONFIG_FILE'] || 'appmap.yml'
+    end
+
+    # Configures AppMap for recording. Default behavior is to configure from
+    # APPMAP_CONFIG_FILE, or 'appmap.yml'. If no config file is available, a
+    # configuration will be automatically generated and used - and the user is prompted
+    # to create the config file.
+    #
     # This method also activates the code hooks which record function calls as trace events.
     # Call this function before the program code is loaded by the Ruby VM, otherwise
     # the load events won't be seen and the hooks won't activate.
-    def initialize(config_file_path = 'appmap.yml')
-      raise "AppMap configuration file #{config_file_path} does not exist" unless ::File.exists?(config_file_path)
+    def initialize_configuration(config_file_path = default_config_file_path)
       warn "Configuring AppMap from path #{config_file_path}"
       Config.load_from_file(config_file_path).tap do |configuration|
         self.configuration = configuration
@@ -118,4 +125,4 @@ def detect_metadata
   require 'appmap/minitest'
 end
 
-AppMap.initialize if ENV['APPMAP'] == 'true'
+AppMap.initialize_configuration if ENV['APPMAP'] == 'true'

lib/appmap/config.rb

@@ -223,10 +223,14 @@ def method_hook(cls, method_names, labels)
       'JSON::Ext::Generator::State' => TargetMethods.new(:generate, Package.build_from_path('json', package_name: 'json', labels: %w[format.json.generate])),
     }.freeze
 
-    attr_reader :name, :packages, :exclude, :hooked_methods, :builtin_hooks
+    attr_reader :name, :appmap_dir, :packages, :exclude, :hooked_methods, :builtin_hooks
 
-    def initialize(name, packages, exclude: [], functions: [])
+    def initialize(name,
+      packages: [],
+      exclude: [],
+      functions: [])
       @name = name
+      @appmap_dir = AppMap::DEFAULT_APPMAP_DIR
       @packages = packages
       @hook_paths = Set.new(packages.map(&:path))
       @exclude = exclude
@@ -253,38 +257,119 @@ def initialize(name, packages, exclude: [], functions: [])
     class << self
       # Loads configuration data from a file, specified by the file name.
       def load_from_file(config_file_name)
-        require 'yaml'
-        load YAML.safe_load(::File.read(config_file_name))
+        logo = lambda do
+          Util.color(<<~LOGO, :magenta)
+             ___             __  ___
+            / _ | ___  ___  /  |/  /__ ____
+           / __ |/ _ \\/ _ \\/ /|_/ / _ `/ _ \\
+          /_/ |_/ .__/ .__/_/  /_/\\_,_/ .__/
+               /_/  /_/              /_/
+          LOGO
+        end
+
+        config_present = true if File.exists?(config_file_name)
+
+        config_data = if config_present
+          require 'yaml'
+          YAML.safe_load(::File.read(config_file_name))
+        else
+          warn logo.()
+          warn ''
+          warn Util.color(%Q|NOTICE: The AppMap config file #{config_file_name} was not found!|, :magenta, bold: true)
+          warn ''
+          warn Util.color(<<~MISSING_FILE_MSG, :magenta)
+          AppMap uses this file to customize its behavior. For example, you can use
+          the 'packages' setting to indicate which local file paths and dependency
+          gems you want to include in the AppMap. Since you haven't provided specific
+          settings, the appmap gem will try and guess some reasonable defaults.
+          To suppress this message, create the file:
+          
+          #{Pathname.new(config_file_name).expand_path}.
+          
+          Here are the default settings that will be used in the meantime. You can
+          copy and paste this example to start your appmap.yml.
+          MISSING_FILE_MSG
+          {}
+        end
+        load(config_data).tap do |config|
+          config_yaml = {
+            'name' => config.name,
+            'packages' => config.packages.select{|p| p.path}.map do |pkg|
+              { 'path' => pkg.path }
+            end,
+            'exclude' => []
+          }.compact
+          unless config_present
+            warn Util.color(YAML.dump(config_yaml), :magenta)
+            warn logo.()
+          end
+        end
       end
 
       # Loads configuration from a Hash.
       def load(config_data)
-        functions = (config_data['functions'] || []).map do |function_data|
-          package = function_data['package']
-          cls = function_data['class']
-          functions = function_data['function'] || function_data['functions']
-          raise 'AppMap class configuration should specify package, class and function(s)' unless package && cls && functions
-          functions = Array(functions).map(&:to_sym)
-          labels = function_data['label'] || function_data['labels']
-          labels = Array(labels).map(&:to_s) if labels
-          Function.new(package, cls, labels, functions)
+        name = config_data['name'] || guess_name
+        config_params = {
+          exclude: config_data['exclude']
+        }.compact
+
+        if config_data['functions']
+          config_params[:functions] = config_data['functions'].map do |function_data|
+            package = function_data['package']
+            cls = function_data['class']
+            functions = function_data['function'] || function_data['functions']
+            raise %q(AppMap config 'function' element should specify 'package', 'class' and 'function' or 'functions') unless package && cls && functions
+
+            functions = Array(functions).map(&:to_sym)
+            labels = function_data['label'] || function_data['labels']
+            labels = Array(labels).map(&:to_s) if labels
+            Function.new(package, cls, labels, functions)
+          end
         end
-        packages = (config_data['packages'] || []).map do |package|
-          gem = package['gem']
-          path = package['path']
-          raise 'AppMap package configuration should specify gem or path, not both' if gem && path
-
-          if gem
-            shallow = package['shallow']
-            # shallow is true by default for gems
-            shallow = true if shallow.nil?
-            Package.build_from_gem(gem, exclude: package['exclude'] || [], shallow: shallow)
+
+        config_params[:packages] = \
+          if config_data['packages']
+            config_data['packages'].map do |package|
+              gem = package['gem']
+              path = package['path']
+              raise %q(AppMap config 'package' element should specify 'gem' or 'path', not both) if gem && path
+
+              if gem
+                shallow = package['shallow']
+                # shallow is true by default for gems
+                shallow = true if shallow.nil?
+                Package.build_from_gem(gem, exclude: package['exclude'] || [], shallow: shallow)
+              else
+                Package.build_from_path(path, exclude: package['exclude'] || [], shallow: package['shallow'])
+              end
+            end.compact
           else
-            Package.build_from_path(path, exclude: package['exclude'] || [], shallow: package['shallow'])
+            Array(guess_paths).map do |path|
+              Package.build_from_path(path)
+            end
           end
-        end.compact
-        exclude = config_data['exclude'] || []
-        Config.new config_data['name'], packages, exclude: exclude, functions: functions
+
+        Config.new name, config_params
+      end
+
+      def guess_name
+        reponame = lambda do
+          next unless File.directory?('.git')
+
+          repo_name = `git config --get remote.origin.url`.strip
+          repo_name.split('/').last.split('.').first unless repo_name == ''
+        end
+        dirname = -> { Dir.pwd.split('/').last }
+
+        reponame.() || dirname.()
+      end
+
+      def guess_paths
+        if defined?(::Rails)
+          %w[app/controllers app/models]
+        elsif File.directory?('lib')
+          %w[lib]
+        end
       end
     end
 
@@ -294,7 +379,7 @@ def to_h
         packages: packages.map(&:to_h),
         functions: @functions.map(&:to_h),
         exclude: exclude
-      }
+      }.compact
     end
 
     # Determines if methods defined in a file path should possibly be hooked.

lib/appmap/util.rb

@@ -4,6 +4,21 @@
 
 module AppMap
   module Util
+    # https://wynnnetherland.com/journal/a-stylesheet-author-s-guide-to-terminal-colors/
+    # Embed in a String to clear all previous ANSI sequences.
+    CLEAR   = "\e[0m"
+    BOLD    = "\e[1m"
+
+    # Colors
+    BLACK   = "\e[30m"
+    RED     = "\e[31m"
+    GREEN   = "\e[32m"
+    YELLOW  = "\e[33m"
+    BLUE    = "\e[34m"
+    MAGENTA = "\e[35m"
+    CYAN    = "\e[36m"
+    WHITE   = "\e[37m"
+
     class << self
       # scenario_filename builds a suitable file name from a scenario name.
       # Special characters are removed, and the file name is truncated to fit within
@@ -128,6 +143,12 @@ def write_appmap(filename, appmap)
           FileUtils.mv tempfile.path, filename
         end
       end
+
+      def color(text, color, bold: false)
+        color = Util.const_get(color.to_s.upcase) if color.is_a?(Symbol)
+        bold  = bold ? BOLD : ""
+        "#{bold}#{color}#{text}#{CLEAR}"
+      end
     end
   end
 end

lib/appmap/version.rb

@@ -6,4 +6,6 @@ module AppMap
   VERSION = '0.50.0'
 
   APPMAP_FORMAT_VERSION = '1.5.1'
+
+  DEFAULT_APPMAP_DIR = 'tmp/appmap'.freeze
 end

spec/abstract_controller_base_spec.rb

@@ -1,9 +1,30 @@
 require 'rails_spec_helper'
 
 describe 'Rails' do
+  shared_context 'rails integration test setup' do
+    def tmpdir
+      'tmp/spec/AbstractControllerBase'
+    end
+
+    unless use_existing_data?
+      before(:all) do
+        FileUtils.rm_rf tmpdir
+        FileUtils.mkdir_p tmpdir
+        run_spec 'spec/controllers/users_controller_spec.rb'
+        run_spec 'spec/controllers/users_controller_api_spec.rb'
+      end
+    end
+
+    let(:appmap) { JSON.parse File.read File.join tmpdir, 'appmap/rspec', appmap_json_file }
+    let(:appmap_json_path) { File.join(tmpdir, 'appmap/rspec', appmap_json_file) }
+    let(:appmap) { JSON.parse File.read(appmap_json_path) }
+    let(:events) { appmap['events'] }
+  end
+
   %w[5 6].each do |rails_major_version| # rubocop:disable Metrics/BlockLength
     context "#{rails_major_version}" do
       include_context 'Rails app pg database', "spec/fixtures/rails#{rails_major_version}_users_app" unless use_existing_data?
+      include_context 'rails integration test setup'
 
       def run_spec(spec_name)
         cmd = <<~CMD.gsub "\n", ' '
@@ -13,24 +34,6 @@ def run_spec(spec_name)
         run_cmd cmd, chdir: fixture_dir
       end
 
-      def tmpdir
-        'tmp/spec/AbstractControllerBase'
-      end
-
-      unless use_existing_data?
-        before(:all) do
-          FileUtils.rm_rf tmpdir
-          FileUtils.mkdir_p tmpdir
-          run_spec 'spec/controllers/users_controller_spec.rb'
-          run_spec 'spec/controllers/users_controller_api_spec.rb'
-        end
-      end
-
-      let(:appmap) { JSON.parse File.read File.join tmpdir, 'appmap/rspec', appmap_json_file }
-      let(:appmap_json_path) { File.join(tmpdir, 'appmap/rspec', appmap_json_file) }
-      let(:appmap) { JSON.parse File.read(appmap_json_path) }
-      let(:events) { appmap['events'] }
-
       describe 'an API route' do
         describe 'creating an object' do
           let(:appmap_json_file) do
@@ -253,4 +256,40 @@ def tmpdir
       end
     end
   end
+
+  describe 'with default appmap.yml' do
+    include_context 'Rails app pg database', "spec/fixtures/rails5_users_app" unless use_existing_data?
+    include_context 'rails integration test setup'
+
+    def run_spec(spec_name)
+      cmd = <<~CMD.gsub "\n", ' '
+        docker-compose run --rm -e RAILS_ENV=test -e APPMAP=true -e APPMAP_CONFIG_FILE=no/such/file
+        -v #{File.absolute_path tmpdir}:/app/tmp app ./bin/rspec #{spec_name}
+      CMD
+      run_cmd cmd, chdir: fixture_dir
+    end
+
+    let(:appmap_json_file) do
+      'Api_UsersController_POST_api_users_with_required_parameters_creates_a_user.appmap.json'
+    end
+
+    it 'http_server_request is recorded' do
+      expect(events).to include(
+        hash_including(
+          'http_server_request' => hash_including(
+            'request_method' => 'POST',
+            'path_info' => '/api/users'
+          )
+        )
+      )
+    end
+
+    it 'controller method is recorded' do
+      expect(events).to include hash_including(
+        'defined_class' => 'Api::UsersController',
+        'method_id' => 'build_user',
+        'path' => 'app/controllers/api/users_controller.rb',
+      )
+    end
+  end
 end

spec/config_spec.rb

@@ -55,4 +55,25 @@
 
     expect(config.to_h.deep_stringify_keys!).to eq(config_expectation)
   end
+
+  context do
+    let(:warnings) { @warnings ||= [] }
+    let(:warning) { warnings.join }
+    before do
+      expect(AppMap::Config).to receive(:warn).at_least(1) { |msg| warnings << msg }
+    end
+    it 'prints a warning and uses a default config' do
+      config = AppMap::Config.load_from_file 'no/such/file'
+      expect(config.to_h).to eq(YAML.load(<<~CONFIG))
+      :name: appmap-ruby
+      :packages:
+      - :path: lib
+        :handler_class: AppMap::Handler::Function
+        :shallow: false
+      :functions: []
+      :exclude: []
+      CONFIG
+      expect(warning).to include('NOTICE: The AppMap config file no/such/file was not found!')
+    end
+  end
 end

spec/hook_spec.rb

@@ -21,7 +21,7 @@ def visit_NilClass(o)
   def invoke_test_file(file, setup: nil, &block)
     AppMap.configuration = nil
     package = AppMap::Config::Package.build_from_path(file)
-    config = AppMap::Config.new('hook_spec', [ package ])
+    config = AppMap::Config.new('hook_spec', packages: [ package ])
     AppMap.configuration = config
     tracer = nil
     AppMap::Hook.new(config).enable do
@@ -57,7 +57,7 @@ def test_hook_behavior(file, events_yaml, setup: nil, &block)
   it 'excludes named classes and methods' do
     load 'spec/fixtures/hook/exclude.rb'
     package = AppMap::Config::Package.build_from_path('spec/fixtures/hook/exclude.rb')
-    config = AppMap::Config.new('hook_spec', [ package ], exclude: %w[ExcludeTest])
+    config = AppMap::Config.new('hook_spec', packages: [ package ], exclude: %w[ExcludeTest])
     AppMap.configuration = config
 
     expect(config.never_hook?(ExcludeTest, ExcludeTest.new.method(:instance_method))).to be_truthy