appmap 0.39.1 → 0.42.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 384456ad51727b3c819e8307de92b2785da152a46c5fa60d0a4e6ff690dbb596
-  data.tar.gz: e0d5a984bc74ee91b0f9428d83cbaac70c387b442cc55666f36b75907080e620
+  metadata.gz: 50826fcf91733d3bb29aad0b6c77af2516ad08aa87557c3675d4be896f7790db
+  data.tar.gz: 4e5ee3f431b68a69de5ff6b080eeae861f3f7de6fe952ea1e71b5c30d4777bc1
 SHA512:
-  metadata.gz: 2f0670d632a370241168ad76ad30dd663568556ea3e524c48aafdbf86ae9d0c8e8f76f48a1c34a7a830457cff66c4417bbf19acb7ac952daeaaec65121e7a0d5
-  data.tar.gz: 3f1bec26161a40c75487e7f98f039df0c135f7de77ee089d72dde29c1a5d5fd19b43661c6aff3c3de58e945b87d330b96a66738a95a208ec7a4e75db1bd85363
+  metadata.gz: fcd01c7d1a3d70c29e33d8890e8f1ea8d7dc5cd2fbca7724618fcc76190c2d0217b89ba69e4de5003eb80147d44c15335cfdff60e67cdaf3eeaa18655fdf2b4f
+  data.tar.gz: 32c714968c8669f3a9dceb20543a0f09856948f4b4d6b8584ad06d6347cf10f28a4d0386e4f3af1aaccb1709ec2a88fefe88da88104ffbe18dfd0fd81fb5cb95

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+# v0.42.0
+
+* Remove `feature_group` and `feature` metadata from minitest and RSpec AppMaps.
+* Add `metadata.source_location`.
+
+# v0.41.2
+
+* Don't rely on `gemspec.source_paths` to list all the source locations in a gem. Hook any code that's loaded
+  from inside the `gem_dir`.
+
+# v0.41.1
+
+* Make best effort to ensure that class name is not `null` in the appmap.json.
+* Don't try and instrument gems which are a dependency of the this gem.
+* Fix a nil exception when applying the exclude list to builtins.
+
+# v0.41.0
+
+* Adjust some label names to match `provider.*`, `format.*`.
+* Add global `exclude` list to *appmap.yml* which can be used to definitively exclude specific classes and methods.
+
+# 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,16 @@
 
 - [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)
+  - [Server process recording](#server-process-recording)
+- [AppMap for VSCode](#appmap-for-vscode)
 - [Uploading AppMaps](#uploading-appmaps)
 - [Development](#development)
   - [Running tests](#running-tests)
@@ -23,21 +26,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,23 +51,26 @@ 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**
+
+Add `gem 'appmap'` to **beginning** of your Gemfile. We recommend that you add the `appmap` gem to the `:development, :test` group. Your Gemfile should look something like this:
 
 ```
-gem 'appmap'
-```
+source 'https://rubygems.org'
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 
-**Install in test, development groups**
+# Optional rubRuby version
+# ruby '2.7.2'
 
-```
 group :development, :test do
   gem 'appmap'
 end
 ```
 
-Then install with `bundle`.
+Install with `bundle install`, as usual.
+
+It's important to add the `appmap` gem before any other gems that you may want to instrument. There is more about this in the section on adding gems to the *appmap.yml*.
 
 **Railtie**
 
@@ -72,7 +78,24 @@ 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).
+```
+
+**application.rb**
+
+Add this line to *application.rb*, to enable server recording with `APPMAP_RECORD=true`:
+
+```ruby
+module MyApp
+  class Application < Rails::Application
+    ...
+  
+    config.appmap.enabled = true if ENV['APPMAP_RECORD']
+    
+    ...
+  end
+end
 ```
 
 # Configuration
@@ -81,15 +104,28 @@ When you run your program, the `appmap` gem reads configuration settings from `a
 file for a typical Rails project:
 
 ```yaml
-name: MyProject
+# 'name' should generally be the same as the code repo name.
+name: my_project
 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
+exclude:
+- MyClass
+- MyClass#my_instance_method
+- MyClass.my_class_method
 ```
 
 * **name** Provides the project name (required)
-* **packages** A list of source code directories which should be instrumented.
+* **packages** A list of source code directories which should be recorded.
+* **exclude** A list of classes and/or methods to definitively exclude from recording.
 
 **packages**
 
@@ -97,13 +133,46 @@ 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.
-* **gem** As an alternative to specifying the path, specify the name of a dependency gem. When using `gem`, don't specify `path`.
+* **gem** As an alternative to specifying the path, specify the name of a dependency gem. When using `gem`, don't specify `path`. In your `Gemfile`, the `appmap` gem **must** be listed **before** any gem that you specify in your *appmap.yml*.
 * **exclude** A list of files and directories which will be ignored. By default, all modules, classes and public
-  functions are inspected.
+  functions are inspected. See also: global `exclude` list.
 * **shallow** When set to `true`, only the first function call entry into a package will be recorded. Subsequent function calls within 
   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`.
 
+**exclude**
+
+Optional list of fully qualified class and method names. Separate class and method names with period (`.`) for class methods and hash (`#`) for instance methods.
+
+
+# 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 +198,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 +211,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 +237,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 +300,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,18 +323,24 @@ $ 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
+## Server process recording
+
+Run your Rails server with `APPMAP_RECORD=true`. When the server exits, an *appmap.json* file will be written to the project directory. This is a great way to start the server, interact with your app as a user (or through it's API), and then view an AppMap of everything that happened.
 
-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.
+Be sure and set `WEB_CONCURRENCY=1`, if you are using a webserver that can run multiple processes. You only want there to be one process while you are recording, otherwise they will both try and write *appmap.json* and one of them will clobber the other.
 
-Note that using this method is kind of a blunt instrument. Recording RSpecs and using Remote Recording are usually better options.
+# AppMap for VSCode
+
+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
-[![Build Status](https://travis-ci.org/applandinc/appmap-ruby.svg?branch=master)](https://travis-ci.org/applandinc/appmap-ruby)
+[![Build Status](https://travis-ci.com/applandinc/appmap-ruby.svg?branch=master)](https://travis-ci.com/applandinc/appmap-ruby)
 
 ## Running tests
 

data/lib/appmap.rb

@@ -50,6 +50,11 @@ module AppMap
       end
     end
 
+    # Whether to include source and comments in all class maps.
+    def include_source?
+      ENV['APPMAP_SOURCE'] == 'true'
+    end
+
     # Used to start tracing, stop tracing, and record events.
     def tracing
       @tracing ||= Trace::Tracing.new

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/command/record.rb

@@ -27,7 +27,7 @@ module AppMap
           event_thread.join
           yield AppMap::APPMAP_FORMAT_VERSION,
                 AppMap.detect_metadata,
-                AppMap.class_map(tracer.event_methods),
+                AppMap.class_map(tracer.event_methods, include_source: AppMap.include_source?),
                 events
         end
 

data/lib/appmap/config.rb

@@ -16,20 +16,20 @@ module AppMap
         end
 
         def build_from_gem(gem, shallow: true, package_name: nil, exclude: [], labels: [])
-          gem_paths(gem).map do |gem_path|
-            Package.new(gem_path, gem, package_name, exclude, labels, shallow)
+          if %w[method_source activesupport].member?(gem)
+            warn "WARNING: #{gem} cannot be AppMapped because it is a dependency of the appmap gem"
+            return
           end
+          Package.new(gem_path(gem), gem, package_name, exclude, labels, shallow)
         end
 
         private_class_method :new
 
         protected
 
-        def gem_paths(gem)
+        def gem_path(gem)
           gemspec = Gem.loaded_specs[gem] or raise "Gem #{gem.inspect} not found"
-          gemspec.source_paths.map do |path|
-            File.join(gemspec.gem_dir, path)
-          end
+          gemspec.gem_dir
         end
       end
 
@@ -57,32 +57,36 @@ module AppMap
     # Methods that should always be hooked, with their containing
     # package and labels that should be applied to them.
     HOOKED_METHODS = {
-      'ActiveSupport::SecurityUtils' => Hook.new(:secure_compare, Package.build_from_path('active_support', package_name: 'active_support', labels: %w[security crypto])),
-      'ActionView::Renderer' => Hook.new(:render, Package.build_from_path('action_view', package_name: 'action_view', labels: %w[view]))
+      'ActiveSupport::SecurityUtils' => Hook.new(:secure_compare, Package.build_from_path('active_support', labels: %w[provider.secure_compare])),
+      'ActionView::Renderer' => Hook.new(:render, Package.build_from_path('action_view', labels: %w[mvc.view])),
+      'ActionDispatch::Cookies::CookieJar' => Hook.new(%i[[]= clear update delete recycle], Package.build_from_path('action_pack', labels: %w[provider.http.cookie])),
+      'ActionDispatch::Cookies::EncryptedCookieJar' => Hook.new(%i[[]=], Package.build_from_path('action_pack', labels: %w[provider.http.cookie crypto])),
+      'CanCan::ControllerAdditions' => Hook.new(%i[authorize! can? cannot?], Package.build_from_path('cancancan', labels: %w[provider.authorization])),
+      'CanCan::Ability' => Hook.new(%i[authorize!], Package.build_from_path('cancancan', labels: %w[provider.authorization])),
     }.freeze
 
     BUILTIN_METHODS = {
       'OpenSSL::PKey::PKey' => Hook.new(:sign, OPENSSL_PACKAGES),
-      'Digest::Instance' => Hook.new(:digest, OPENSSL_PACKAGES),
       'OpenSSL::X509::Request' => Hook.new(%i[sign verify], OPENSSL_PACKAGES),
       'OpenSSL::PKCS5' => Hook.new(%i[pbkdf2_hmac_sha1 pbkdf2_hmac], OPENSSL_PACKAGES),
       'OpenSSL::Cipher' => Hook.new(%i[encrypt decrypt final], OPENSSL_PACKAGES),
       'OpenSSL::X509::Certificate' => Hook.new(:sign, OPENSSL_PACKAGES),
-      'Net::HTTP' => Hook.new(:request, Package.build_from_path('net/http', package_name: 'net/http', labels: %w[http io])),
-      'Net::SMTP' => Hook.new(:send, Package.build_from_path('net/smtp', package_name: 'net/smtp', labels: %w[smtp email io])),
-      'Net::POP3' => Hook.new(:mails, Package.build_from_path('net/pop3', package_name: 'net/pop', labels: %w[pop pop3 email io])),
-      'Net::IMAP' => Hook.new(:send_command, Package.build_from_path('net/imap', package_name: 'net/imap', labels: %w[imap email io])),
-      'Marshal' => Hook.new(%i[dump load], Package.build_from_path('marshal', labels: %w[serialization marshal])),
-      'Psych' => Hook.new(%i[dump dump_stream load load_stream parse parse_stream], Package.build_from_path('yaml', package_name: 'psych', labels: %w[serialization yaml])),
-      'JSON::Ext::Parser' => Hook.new(:parse, Package.build_from_path('json', package_name: 'json', labels: %w[serialization json])),
-      'JSON::Ext::Generator::State' => Hook.new(:generate, Package.build_from_path('json', package_name: 'json', labels: %w[serialization json])),
+      'Net::HTTP' => Hook.new(:request, Package.build_from_path('net/http', package_name: 'net/http', labels: %w[protocol.http io])),
+      'Net::SMTP' => Hook.new(:send, Package.build_from_path('net/smtp', package_name: 'net/smtp', labels: %w[protocol.smtp protocol.email io])),
+      'Net::POP3' => Hook.new(:mails, Package.build_from_path('net/pop3', package_name: 'net/pop', labels: %w[protocol.pop protocol.email io])),
+      'Net::IMAP' => Hook.new(:send_command, Package.build_from_path('net/imap', package_name: 'net/imap', labels: %w[protocol.imap protocol.email io])),
+      'Marshal' => Hook.new(%i[dump load], Package.build_from_path('marshal', labels: %w[format.marshal provider.serialization])),
+      'Psych' => Hook.new(%i[dump dump_stream load load_stream parse parse_stream], Package.build_from_path('yaml', package_name: 'psych', labels: %w[format.yaml provider.serialization])),
+      'JSON::Ext::Parser' => Hook.new(:parse, Package.build_from_path('json', package_name: 'json', labels: %w[format.json provider.serialization])),
+      'JSON::Ext::Generator::State' => Hook.new(:generate, Package.build_from_path('json', package_name: 'json', labels: %w[format.json provider.serialization])),
     }.freeze
 
-    attr_reader :name, :packages
+    attr_reader :name, :packages, :exclude
 
-    def initialize(name, packages = [])
+    def initialize(name, packages = [], exclude = [])
       @name = name
       @packages = packages
+      @exclude = exclude
     end
 
     class << self
@@ -105,44 +109,60 @@ module AppMap
             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']) ]
+            Package.build_from_path(path, exclude: package['exclude'] || [], shallow: package['shallow'])
           end
-        end.flatten
-        Config.new config_data['name'], packages
+        end.compact
+        Config.new config_data['name'], packages, config_data['exclude'] || []
       end
     end
 
     def to_h
       {
         name: name,
-        packages: packages.map(&:to_h)
+        packages: packages.map(&:to_h),
+        exclude: exclude
       }
     end
 
+    # package_for_method finds the Package, if any, which configures the hook
+    # for a method.
     def package_for_method(method)
+      package_hooked_by_class(method) || package_hooked_by_source_location(method)
+    end
+
+    def package_hooked_by_class(method)
       defined_class, _, method_name = ::AppMap::Hook.qualify_method_name(method)
-      package = find_package(defined_class, method_name)
-      return package if package
+      return find_package(defined_class, method_name)
+    end
 
+    def package_hooked_by_source_location(method)
       location = method.source_location
       location_file, = location
       return unless location_file
 
       location_file = location_file[Dir.pwd.length + 1..-1] if location_file.index(Dir.pwd) == 0
-      packages.find do |pkg|
+      packages.select { |pkg| pkg.path }.find do |pkg|
         (location_file.index(pkg.path) == 0) &&
           !pkg.exclude.find { |p| location_file.index(p) }
       end
     end
 
-    def included_by_location?(method)
-      !!package_for_method(method)
+    def never_hook?(method)
+      defined_class, separator, method_name = ::AppMap::Hook.qualify_method_name(method)
+      return true if exclude.member?(defined_class) || exclude.member?([ defined_class, separator, method_name ].join)
     end
 
+    # always_hook? indicates a method that should always be hooked.
     def always_hook?(defined_class, method_name)
       !!find_package(defined_class, method_name)
     end
 
+    # included_by_location? indicates a method whose source location matches a method definition that has been
+    # configured for inclusion.
+    def included_by_location?(method)
+      !!package_for_method(method)
+    end
+
     def find_package(defined_class, method_name)
       hook = find_hook(defined_class)
       return nil unless hook