appmap 0.18.1

data/lib/appmap/config.rb

@@ -0,0 +1,65 @@
+require 'appmap/config/path'
+require 'appmap/config/file'
+require 'appmap/config/directory'
+require 'appmap/config/package_dir'
+require 'appmap/config/named_function'
+
+module AppMap
+  module Config
+    class Configuration
+      attr_reader :name, :packages, :files, :named_functions
+
+      def initialize(name)
+        @name = name
+        @packages = []
+        @files = []
+        @named_functions = []
+      end
+
+      def source_locations
+        packages + files + named_functions
+      end
+    end
+
+    class << self
+      NAMED_FUNCTIONS = [
+        Config::NamedFunction.new(:rack_handler_webrick, 'rack', 'lib/rack/handler/webrick.rb',
+                                  %w[Rack Handler WEBrick], 'service', false)
+      ].freeze
+
+      # 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))
+      end
+
+      # Loads configuration from a Hash.
+      def load(config_data)
+        Configuration.new(config_data['name']).tap do |config|
+          builders = Hash.new { |_, key| raise "Unknown config type #{key.inspect}" }
+          builders[:packages] = lambda { |path, options|
+            AppMap::Config::PackageDir.new(path).tap do |pdir|
+              pdir.package_name = options['name'] if options['name']
+              pdir.exclude = options['exclude'] if options['exclude']
+            end
+          }
+          builders[:files] = ->(path, _) { AppMap::Config::File.new(path) }
+
+          %i[packages files].each do |kind|
+            next unless (members = config_data[kind.to_s])
+            members.each do |member|
+              path = member.delete('path')
+              config.send(kind) << builders[kind].call(path, member)
+            end
+          end
+
+          NAMED_FUNCTIONS.each do |dep|
+            next if config_data['named_functions'] && !config_data['named_functions'].member?(dep.gem_name)
+
+            config.named_functions << dep
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appmap/feature.rb

@@ -0,0 +1,262 @@
+module AppMap
+  # A Feature is a construct within the code that will be observed. Examples features include
+  # modules, classes and functions.
+  module Feature
+    TYPE_MAP = {
+      'cls' => 'class'
+    }.freeze
+
+    class << self
+      FEATURE_BUILDERS = {
+        module: ->(_) { Module.new },
+        class: ->(_) { Cls.new },
+        function: lambda do |hash|
+                    static = hash.delete('static')
+                    class_name = hash.delete('class_name')
+                    Function.new.tap do |e|
+                      e.static = static
+                      e.class_name = class_name
+                    end
+                  end
+      }.freeze
+
+      # Deserialize a feature from a Hash. The Hash is typically a deserialized JSON dump of the feature.
+      def from_hash(hash)
+        builder = FEATURE_BUILDERS[hash['type'].to_sym]
+        raise "Unrecognized type of feature: #{type.inspect}" unless builder
+
+        feature = builder.call(hash)
+        feature.name = hash['name']
+        feature.location = hash['location']
+        feature.attributes = hash['attributes'] || {}
+        feature.children = (hash['children'] || []).map { |child| from_hash(child) }
+        feature
+      end
+    end
+
+    FeatureStruct = Struct.new(:name, :location, :attributes)
+
+    # Base is an abstract base class for features.
+    class Base < FeatureStruct
+      class << self
+        def expand_path(location)
+          path, lineno = location.split(':')
+          [ path, lineno ].compact.join(':')
+        end
+      end
+
+      attr_reader :parent, :children
+
+      def initialize(name, location, attributes)
+        super(name, self.class.expand_path(location), attributes)
+
+        @parent = nil
+        @children = []
+      end
+
+      def remove_child(child)
+        # TODO: Encountered this indexing appland with active_dispatch
+        children.delete(child) or warn "Unable to remove #{name.inspect} from parent" # or raise "No such child : #{child}"
+        child.instance_variable_set('@parent', nil)
+      end
+
+      def add_child(child)
+        @children << child
+        child.instance_variable_set('@parent', self)
+      end
+
+      # Gets an array containing the type names which enclose this feature.
+      def enclosing_type_name
+        @enclosing_type_name ||= [].tap do |names|
+          p = self
+          while (p = p.parent) && p.type?
+            names << p.name
+          end
+        end.reverse
+      end
+
+      # true iff this feature has an enclosing type. An example of when this is false: when
+      # the parent of the feature is not a type (e.g. it's a location).
+      def enclosing_type_name?
+        !enclosing_type_name.empty?
+      end
+
+      # The 'include' attribute can indicate which elements of the parse subtree
+      # to automatically add as features. For example: public_classes, public_modules,
+      # public_methods.
+      def include_option
+        (attributes[:include] || '').split(',')
+      end
+
+      # yield each function to a block.
+      def collect_functions(accumulator = [])
+        accumulator.tap do |_|
+          accumulator << self if is_a?(Function)
+          children.each { |child| child.collect_functions(accumulator) }
+        end
+      end
+
+      def type?
+        false
+      end
+
+      def valid?
+        !name.blank? && !location.blank?
+      end
+
+      def to_json(*opts)
+        to_h.to_json(*opts)
+      end
+
+      def to_h
+        super.tap do |map|
+          map.delete(:parent)
+          class_name = self.class.name.underscore.split('/')[-1]
+          map[:type] = TYPE_MAP[class_name] || class_name
+          map[:children] = @children.map(&:to_h) unless @children.empty?
+          map.delete(:attributes) if map[:attributes].empty?
+        end
+      end
+
+      # Determines if this feature should be dropped from the feature tree.
+      # A feature is dropped from the feature tree if it doesn't add useful information for the user.
+      # Performing this operation removes feature nodes that don't add anything useful to the user.
+      # For example, empty classes.
+      def prune(parent = nil)
+        should_prune = prune? && !parent.nil?
+        parent = self unless should_prune
+        children.dup.each do |child|
+          child.prune(parent)
+        end
+
+        # Perform the prune in post-fix traversal order, otherwise the
+        # features will get confused about whether they should prune or not.
+        if should_prune
+          parent.remove_child(self)
+          children.each do |child|
+            parent.add_child(child)
+          end
+        end
+      end
+
+      # Determines if this feature should be re-parented as a child of a different feature.
+      #
+      # A feature is re-parented if the enclosing type of the feature has already been defined in the tree.
+      #
+      # @param parent the parent of this feature in the compacted tree.
+      def reparent(parent = nil, features_by_type = {})
+        # Determine if the enclosing type of the feature is defined.
+        # Generally, it should be.
+
+        existing_enclosing_type = features_by_type[enclosing_type_name] if enclosing_type_name?
+        if existing_enclosing_type
+          parent = existing_enclosing_type
+        end
+
+        # Determine if this feature is a type which is already defined.
+        type_exists = true if type? && features_by_type.key?(type_name)
+
+        # If this feature is a type that's already defined, skip over it and
+        # add the children to the existing feature. Otherwise, clone this feature
+        # under the parent and use the cloned object as the parent of the compacted 
+        # children.
+        if type_exists
+          features_by_type[type_name]
+        else
+          clone.tap do |f|
+            parent.add_child(f) if parent
+            features_by_type[type_name] = f if type?
+          end
+        end.tap do |updated_parent|
+          children.each do |child|
+            child.reparent(updated_parent, features_by_type)
+          end
+        end
+      end
+
+      def prune?
+        false
+      end
+
+      protected
+
+      def clone
+        self.class.new(name, location, attributes)
+      end
+
+      def child_classes
+        children.select { |c| c.is_a?(Cls) }
+      end
+
+      def child_nonclasses
+        children.reject { |c| c.is_a?(Cls) }
+      end
+    end
+
+    # Package is a feature which represents the directory containing code.
+    class Package < Base
+      # prune a package if it's empty, or if it contains anything but packages.
+      def prune?
+        children.empty? || children.any? { |c| !c.is_a?(Package) }
+      end
+    end
+
+    # Cls is a feature which represents a code class. A class defines a namespace which contains other
+    # features (such as member classes and functions), and it also usually encapsulates some data on which
+    # the member features operate.
+    class Cls < Base
+      # prune a class if it's empty.
+      def prune?
+        children.empty?
+      end
+
+      def type?
+        true
+      end
+
+      # Gets the type name of this class as an array.
+      def type_name
+        @type_name ||= enclosing_type_name + [ name ]
+      end
+    end
+
+    # Function is a feature which represents a code function. It can be an instance function or static (aka 'class')
+    # function. Instance functions operate on the instance data of the class on which they are defined. Static
+    # functions are used to perform operations which don't have want or need of instance data.
+    #
+    # * `handler_id` If provided, identifies a trace handler which can apply specialized logic to the
+    #   event data which is recorded for this function. For example, if the function represents a handler
+    #   method for a web server, the custom handler can inspect and record the HTTP request method and path info.
+    class Function < Base
+      attr_accessor :static, :class_name, :handler_id
+
+      alias static? static
+      def instance?
+        !static?
+      end
+
+      # Static functions must have an enclosing class defined in order to be traced.
+      def valid?
+        super && (instance? || !class_name.blank?)
+      end
+
+      def to_h
+        super.tap do |h|
+          # Suppress the class name when it can be inferred from the enclosing type.
+          h[:class_name] = class_name if class_name && class_name != enclosing_type_name.join('::')
+          h[:static] = static?
+        end
+      end
+
+      protected
+
+      def clone
+        super.tap do |obj|
+          obj.static = static
+          obj.class_name = class_name
+          obj.handler_id = handler_id
+        end
+      end
+    end
+  end
+end

data/lib/appmap/inspect/inspector.rb

@@ -0,0 +1,99 @@
+module AppMap
+  module Inspect
+    # Inspector is an abstract class for extracting features from a Ruby program.
+    class Inspector
+      attr_reader :file_path, :parse_nodes, :comments
+
+      def initialize(file_path, parse_nodes, comments)
+        @file_path = file_path
+        @parse_nodes = parse_nodes
+        @comments = comments
+      end
+    end
+
+    # ImplicitInspector extracts features from a Ruby program, creating a feature for each public class and method.
+    class ImplicitInspector < Inspector
+      def inspect_file
+        features = []
+        features_by_ast_node = {}
+        parse_nodes.select(&:public?).each do |parse_node|
+          feature = parse_node.to_feature({})
+          features_by_ast_node[parse_node.node] = feature
+          if feature
+            if (enclosing_type_node = parse_node.enclosing_type_node) &&
+               (parent_feature = features_by_ast_node[enclosing_type_node])
+              parent_feature.add_child(feature)
+            else
+              features << feature
+            end
+          end
+        end
+
+        features.keep_if(&:valid?)
+        features
+      end
+    end
+
+    # ExplicitInspector extracts features from a Ruby program, requiring the use of @appmap annotations to mark each
+    # relevant class and method.
+    class ExplicitInspector < Inspector
+      def inspect_file
+        nodes_by_line = parse_nodes.each_with_object({}) { |node, h| h[node.node.loc.line] = node }
+
+        features_by_ast_node = {}
+        features = []
+
+        comments.select { |c| c.text.index('@appmap') }.each do |c|
+          c.text.split("\n").select { |l| l.index('@appmap') }.each do |feature|
+            tokens = feature.split
+            tokens.delete_if { |t| %w[# @appmap].member?(t) }
+            attributes = tokens.inject({}) do |memo, token|
+              key, value = token.split('=')
+              memo.tap do |attrs|
+                attrs[key.to_sym] = value
+              end
+            end
+
+            parse_node = nodes_by_line[c.location.last_line + 1]
+            if parse_node
+              feature = parse_node.to_feature(attributes)
+              features_by_ast_node[parse_node.node] = feature
+              if feature
+                if (enclosing_type_node = parse_node.enclosing_type_node) &&
+                   (parent_feature = features_by_ast_node[enclosing_type_node])
+                  parent_feature.add_child(feature)
+                else
+                  features << feature
+                end
+
+                # At this point there's a parse_node and an associated feature.
+                # If the feature is a class which has the option 'include=public_methods',
+                # scan the rest of the class body for public methods and create features
+                # for them.
+
+                if parse_node.type == :class && feature.include_option.member?('public_methods')
+                  begin_node = parse_node.node.children.find { |n| n.respond_to?(:type) && n.type == :begin }
+                  if begin_node
+                    public_methods = begin_node
+                                     .children
+                                     .select { |n| n.respond_to?(:type) && n.type == :def }
+                                     .map { |n| ParseNode.from_node(n, file_path, parse_node.ancestors + [ parse_node.node, begin_node ]) }
+                                     .select(&:public?)
+                    public_methods.map { |m| m.to_feature([]) }.compact.each do |f|
+                      feature.add_child(f)
+                    end
+                  end
+                end
+              end
+            else
+              warn "No parse node found at #{file_path}:#{c.location.last_line + 1}"
+            end
+          end
+        end
+
+        features.keep_if(&:valid?)
+        features
+      end
+    end
+  end
+end

data/lib/appmap/inspect/parse_node.rb

@@ -0,0 +1,170 @@
+require 'appmap/feature'
+require 'forwardable'
+
+module AppMap
+  module Inspect
+    # ParseNodeStruct wraps a generic AST parse node.
+    ParseNodeStruct = Struct.new(:node, :file_path, :ancestors) do
+    end
+
+    # ParseNode wraps a generic AST parse node.
+    class ParseNode < ParseNodeStruct
+      extend Forwardable
+
+      def_delegators :node, :type, :location
+
+      class << self
+        # Build a ParseNode from an AST node.
+        def from_node(node, file_path, ancestors)
+          case node.type
+          when :class, :module
+            ClassParseNode.new(node, file_path, ancestors.dup)
+          when :def
+            InstanceMethodParseNode.new(node, file_path, ancestors.dup)
+          when :defs
+            StaticMethodParseNode.new(node, file_path, ancestors.dup) \
+              if StaticMethodParseNode.static?(node)
+          end
+        end
+      end
+
+      def public?
+        preceding_send = preceding_sibling_nodes
+                         .reverse
+                         .select { |n| n.respond_to?(:type) && n.type == :send }
+                         .find { |n| %i[public protected private].member?(n.children[1]) }
+        preceding_send.nil? || preceding_send.children[1] == :public
+      end
+
+      # Gets the AST node of the module or class which encloses this node.
+      def enclosing_type_node
+        ancestors.reverse.find do |a|
+          %i[class module].include?(a.type)
+        end
+      end
+
+      def parent_node
+        ancestors[-1]
+      end
+
+      def preceding_sibling_nodes
+        return [] unless parent_node
+        index_of_this_node = parent_node.children.index { |c| c == node }
+        parent_node.children[0...index_of_this_node]
+      end
+
+      protected
+
+      def extract_class_name(node)
+        node.children[0].children[1].to_s
+      end
+
+      def extract_module_name(node)
+        node.children[0].children[1].to_s
+      end
+    end
+
+    # A Ruby class.
+    class ClassParseNode < ParseNode
+      def to_feature(attributes)
+        AppMap::Feature::Cls.new(extract_class_name(node), "#{file_path}:#{location.line}", attributes)
+      end
+    end
+
+    # Abstract representation of a method.
+    class MethodParseNode < ParseNode
+      def to_feature(attributes)
+        AppMap::Feature::Function.new(name, "#{file_path}:#{location.line}", attributes).tap do |a|
+          a.static = static?
+          a.class_name = class_name
+        end
+      end
+
+      def enclosing_names
+        ancestors.select do |a|
+          %i[class module].include?(a.type)
+        end.map do |a|
+          send("extract_#{a.type}_name", a)
+        end
+      end
+    end
+
+    # A method defines as a :def AST node.
+    class InstanceMethodParseNode < MethodParseNode
+      def name
+        node.children[0].to_s
+      end
+
+      # class_name should be inferred from the enclosing type.
+      def class_name
+        enclosing_names.join('::')
+      end
+
+      # An instance method defined in an sclass is a static method.
+      #
+      # TODO: Well, not strictly true. A singleton class can be defined on a class or
+      # on an instance. In fact, to Ruby a class method is really just an instance method
+      # on a class. So, this needs fixing to try and determine if the singleton class is
+      # defined on an instance or on a class. This may actually be hard (impossible?) to do
+      # from static parsing.
+      def static?
+        result = ancestors[-1].type == :sclass ||
+          (ancestors[-1].type == :begin && ancestors[-2] && ancestors[-2].type == :sclass)
+        !!result
+      end
+    end
+
+    # A method defines as a :defs AST node.
+    # For example:
+    #
+    # class Main
+    #   def Main.main_func; end
+    #   def explain
+    #     some_func.tap do |s|
+    #       def s.inspect; self; end
+    #     end
+    #   end
+    # end
+    class StaticMethodParseNode < MethodParseNode
+      class << self
+        def static?(node)
+          %i[self const].member?(node.children[0].type)
+        end
+      end
+
+      def name
+        node.children[1].to_s
+      end
+
+      # class_name is specified as `nil` if it should be inferred from the
+      # enclosing type.
+      def class_name
+        case (defs_type = node.children[0].type)
+        when :self
+          class_name_from_enclosing_type
+        when :const
+          class_name_from_declaration
+        else
+          raise "Unrecognized 'defs' method type : #{defs_type.inspect}"
+        end
+      end
+
+      def static?
+        true
+      end
+
+      protected
+
+      def class_name_from_enclosing_type
+        enclosing_names.join('::')
+      end
+
+      def class_name_from_declaration
+        ancestor_names = enclosing_names
+        ancestor_names.pop
+        ancestor_names << node.children[0].children[1]
+        ancestor_names.join('::')
+      end
+    end
+  end
+end

data/lib/appmap/inspect/parser.rb

@@ -0,0 +1,15 @@
+require 'appmap/parser'
+require 'appmap/inspect/parse_node'
+
+module AppMap
+  module Inspect
+    # Parser processes a Ruby into a list of parse nodes and a list of comments.
+    class Parser < ::AppMap::Parser
+      protected
+
+      def build_parse_node(node, file_path, ancestors)
+        ParseNode.from_node(node, file_path, ancestors)
+      end
+    end
+  end
+end

data/lib/appmap/inspect.rb

@@ -0,0 +1,91 @@
+require 'appmap/inspect/inspector'
+require 'appmap/inspect/parser'
+
+module AppMap
+  # Inspect identifies features from a Ruby file.
+  module Inspect
+    class << self
+      # Detect features from a source code repository. The manner in which the features are detected in the
+      # code is defined and tuned by a path configuration object. The path configuration tells the
+      # feature detector what it should do when it encounters code that may be a "sub-feature",
+      # for example a public instance method of a class.
+      #
+      # rubocop:disable Metrics/AbcSize
+      # rubocop:disable Metrics/MethodLength
+      # @appmap
+      def detect_features(config_spec)
+        child_features = -> { config_spec.children.map(&Inspect.method(:detect_features)).flatten.compact }
+        parse_file = -> { inspect_file(config_spec.mode, file_path: config_spec.path) }
+
+        feature_builders = Hash.new { |_, key| raise "Unable to build features for #{key.inspect}" }
+        feature_builders[AppMap::Config::Directory] = child_features
+        feature_builders[AppMap::Config::File] = parse_file
+        feature_builders[AppMap::Config::PackageDir] = lambda {
+          AppMap::Feature::Package.new(config_spec.package_name, config_spec.path, {}).tap do |package|
+            child_features.call.each do |child|
+              package.add_child(child)
+            end
+          end
+        }
+        feature_builders[AppMap::Config::NamedFunction] = lambda {
+          # Loads named functions by finding the requested gem, finding the file within the gem,
+          # parsing that file, and then inspecting the module/class scope for the requested method.
+          # We can't 'require' the specified code, because if we do that, it can change the
+          # behavior of the program.
+
+          gem = Gem.loaded_specs[config_spec.gem_name]
+          return [] unless gem
+
+          gem_dir = gem.gem_dir
+          file_path = File.join(gem_dir, config_spec.file_path)
+
+          parse_nodes, comments = Parser.new(file_path: file_path).parse
+          features = ImplicitInspector.new(file_path, parse_nodes, comments).inspect_file
+
+          class_names = config_spec.class_names.dup
+          until class_names.empty?
+            class_name = class_names.shift
+            feature = features.find { |f| f.to_h[:type] == 'class' && f.name == class_name }
+            raise "#{class_name.inspect} not found" unless feature
+
+            features = feature.children
+          end
+
+          function = features.find { |f| f.to_h[:type] == 'function' && f.name == config_spec.method_name && f.static == config_spec.static }
+
+          # If the configuration specifier has an id, use it as the handler id.
+          # This is how we can associate custom handler logic with the named function.
+          function.handler_id = config_spec.id.to_s if config_spec.id
+
+          AppMap::Feature::Package.new(config_spec.gem_name, "#{gem_dir}:0", {}).tap do |pkg|
+            parent = pkg
+            class_names = config_spec.class_names.dup
+            until class_names.empty?
+              class_name = class_names.shift
+              cls = AppMap::Feature::Cls.new(class_name, "#{gem_dir}:0", {})
+              parent.children << cls
+              parent = cls
+            end
+            parent.children << function
+          end
+        }
+
+        feature_builders[config_spec.class].call
+      end
+      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Metrics/MethodLength
+
+      # Inspect a specific file for features.
+      #
+      # @appmap
+      def inspect_file(strategy, file_path: nil)
+        parse_nodes, comments = Parser.new(file_path: file_path).parse
+        inspector_class = {
+          implicit: ImplicitInspector,
+          explicit: ExplicitInspector
+        }[strategy] or raise "Invalid strategy : #{strategy.inspect}"
+        inspector_class.new(file_path, parse_nodes, comments).inspect_file
+      end
+    end
+  end
+end