feature_map 1.1.0

data/lib/feature_map/code_features.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+require 'yaml'
+require 'csv'
+require 'set'
+require 'pathname'
+require 'feature_map/code_features/plugin'
+require 'feature_map/code_features/plugins/identity'
+
+module FeatureMap
+  module CodeFeatures
+    extend T::Sig
+
+    NON_BREAKING_SPACE = T.let(65_279.chr(Encoding::UTF_8), String)
+
+    class IncorrectPublicApiUsageError < StandardError; end
+
+    sig { returns(T::Array[Feature]) }
+    def self.all
+      @all = T.let(@all, T.nilable(T::Array[Feature]))
+      @all ||= from_csv('.feature_map/feature_definitions.csv')
+      @all ||= for_directory('.feature_map/definitions')
+    end
+
+    sig { params(name: String).returns(T.nilable(Feature)) }
+    def self.find(name)
+      @index_by_name = T.let(@index_by_name, T.nilable(T::Hash[String, CodeFeatures::Feature]))
+      @index_by_name ||= begin
+        result = {}
+        all.each { |t| result[t.name] = t }
+        result
+      end
+
+      @index_by_name[name]
+    end
+
+    sig { params(file_path: String).returns(T.nilable(T::Array[Feature])) }
+    def self.from_csv(file_path)
+      return nil if !File.exist?(file_path)
+
+      file_lines = File.readlines(file_path)
+      # Remove any non-breaking space characters, as these can throw off the comment handling
+      # and/or attribute key values.
+      csv_content = file_lines.map { |line| line.gsub(NON_BREAKING_SPACE, '') }
+                              .reject { |line| line.start_with?('#') }
+                              .join.strip
+
+      CSV.parse(csv_content, headers: true).map do |csv_row|
+        feature_data = csv_row.to_h.transform_keys { |column_name| tag_value_for(column_name) }
+        Feature.from_hash(feature_data)
+      end
+    end
+
+    sig { params(dir: String).returns(T::Array[Feature]) }
+    def self.for_directory(dir)
+      Pathname.new(dir).glob('**/*.yml').map do |path|
+        Feature.from_yml(path.to_s)
+      rescue Psych::SyntaxError
+        raise IncorrectPublicApiUsageError, "The YML in #{path} has a syntax error!"
+      end
+    end
+
+    sig { params(features: T::Array[Feature]).returns(T::Array[String]) }
+    def self.validation_errors(features)
+      Plugin.all_plugins.flat_map do |plugin|
+        plugin.validation_errors(features)
+      end
+    end
+
+    sig { params(string: String).returns(String) }
+    def self.tag_value_for(string)
+      string.tr('&', ' ').gsub(/\s+/, '_').downcase
+    end
+
+    # Generally, you should not ever need to do this, because once your ruby process loads, cached content should not change.
+    # Namely, the YML files that are the source of truth for features should not change, so we should not need to look at the YMLs again to verify.
+    # The primary reason this is helpful is for tests where each context is testing against a different set of features
+    sig { void }
+    def self.bust_caches!
+      Plugin.bust_caches!
+      @all = nil
+      @index_by_name = nil
+    end
+
+    class Feature
+      extend T::Sig
+
+      sig { params(config_yml: String).returns(Feature) }
+      def self.from_yml(config_yml)
+        hash = YAML.load_file(config_yml)
+
+        new(
+          config_yml: config_yml,
+          raw_hash: hash
+        )
+      end
+
+      sig { params(raw_hash: T::Hash[T.untyped, T.untyped]).returns(Feature) }
+      def self.from_hash(raw_hash)
+        new(
+          config_yml: nil,
+          raw_hash: raw_hash
+        )
+      end
+
+      sig { returns(T::Hash[T.untyped, T.untyped]) }
+      attr_reader :raw_hash
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :config_yml
+
+      sig do
+        params(
+          config_yml: T.nilable(String),
+          raw_hash: T::Hash[T.untyped, T.untyped]
+        ).void
+      end
+      def initialize(config_yml:, raw_hash:)
+        @config_yml = config_yml
+        @raw_hash = raw_hash
+      end
+
+      sig { returns(String) }
+      def name
+        Plugins::Identity.for(self).identity.name
+      end
+
+      sig { returns(String) }
+      def to_tag
+        CodeFeatures.tag_value_for(name)
+      end
+
+      sig { params(other: Object).returns(T::Boolean) }
+      def ==(other)
+        if other.is_a?(CodeFeatures::Feature)
+          name == other.name
+        else
+          false
+        end
+      end
+
+      alias eql? ==
+
+      sig { returns(Integer) }
+      def hash
+        name.hash
+      end
+    end
+  end
+end

data/lib/feature_map/configuration.rb

@@ -0,0 +1,43 @@
+# typed: strict
+
+module FeatureMap
+  class Configuration < T::Struct
+    extend T::Sig
+
+    const :assigned_globs, T::Array[String]
+    const :unassigned_globs, T::Array[String]
+    const :unbuilt_gems_path, T.nilable(String)
+    const :skip_features_validation, T::Boolean
+    const :raw_hash, T::Hash[T.untyped, T.untyped]
+    const :skip_code_ownership, T::Boolean
+    const :require_assignment_for_teams, T.nilable(T::Array[String])
+    const :ignore_feature_definitions, T::Boolean
+    const :code_cov, T::Hash[String, T.nilable(String)]
+    const :repository, T::Hash[String, T.nilable(String)]
+    const :documentation_site, T::Hash[String, T.untyped]
+
+    sig { returns(Configuration) }
+    def self.fetch
+      config_hash = YAML.load_file('.feature_map/config.yml')
+
+      if config_hash.key?('require')
+        config_hash['require'].each do |require_directive|
+          Private::ExtensionLoader.load(require_directive)
+        end
+      end
+
+      new(
+        assigned_globs: config_hash.fetch('assigned_globs', []),
+        unassigned_globs: config_hash.fetch('unassigned_globs', []),
+        skip_features_validation: config_hash.fetch('skip_features_validation', false),
+        raw_hash: config_hash,
+        skip_code_ownership: config_hash.fetch('skip_code_ownership', true),
+        require_assignment_for_teams: config_hash.fetch('require_assignment_for_teams', nil),
+        ignore_feature_definitions: config_hash.fetch('ignore_feature_definitions', false),
+        code_cov: config_hash.fetch('code_cov', {}),
+        repository: config_hash.fetch('repository', {}),
+        documentation_site: config_hash.fetch('documentation_site', {})
+      )
+    end
+  end
+end

data/lib/feature_map/constants.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module FeatureMap
+  module Constants
+    SINGLE_LINE_COMMENT_PATTERNS = T.let(['#', '//'].map { |r| Regexp.escape(r) }.freeze, T::Array[String])
+    MULTILINE_COMMENT_START_PATTERNS = T.let(['/*', '<!--', '"""', "'''"].map { |r| Regexp.escape(r) }.freeze, T::Array[String])
+    MULTILINE_COMMENT_END_PATTERNS = T.let(['*/', '-->', '"""', "'''"].map { |r| Regexp.escape(r) }.freeze, T::Array[String])
+  end
+end

data/lib/feature_map/mapper.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module FeatureMap
+  module Mapper
+    extend T::Sig
+    extend T::Helpers
+
+    interface!
+
+    class << self
+      extend T::Sig
+
+      sig { params(base: T::Class[Mapper]).void }
+      def included(base)
+        @mappers ||= T.let(@mappers, T.nilable(T::Array[T::Class[Mapper]]))
+        @mappers ||= []
+        @mappers << base
+      end
+
+      sig { returns(T::Array[Mapper]) }
+      def all
+        (@mappers || []).map(&:new)
+      end
+    end
+
+    #
+    # This should be fast when run with ONE file
+    #
+    sig do
+      abstract.params(file: String)
+        .returns(T.nilable(CodeFeatures::Feature))
+    end
+    def map_file_to_feature(file); end
+
+    #
+    # This should be fast when run with MANY files
+    #
+    sig do
+      abstract.params(files: T::Array[String])
+        .returns(T::Hash[String, CodeFeatures::Feature])
+    end
+    def globs_to_feature(files); end
+
+    #
+    # This should be fast when run with MANY files
+    #
+    sig do
+      abstract.params(cache: GlobsToAssignedFeatureMap, files: T::Array[String]).returns(GlobsToAssignedFeatureMap)
+    end
+    def update_cache(cache, files); end
+
+    sig { abstract.returns(String) }
+    def description; end
+
+    sig { abstract.void }
+    def bust_caches!; end
+
+    sig { returns(Private::GlobCache) }
+    def self.to_glob_cache
+      glob_to_feature_map_by_mapper_description = {}
+
+      Mapper.all.each do |mapper|
+        mapped_files = mapper.globs_to_feature(Private.tracked_files)
+        glob_to_feature_map_by_mapper_description[mapper.description] ||= {}
+
+        mapped_files.each do |glob, feature|
+          next if feature.nil?
+
+          glob_to_feature_map_by_mapper_description.fetch(mapper.description)[glob] = feature
+        end
+      end
+
+      Private::GlobCache.new(glob_to_feature_map_by_mapper_description)
+    end
+  end
+end

data/lib/feature_map/output_color.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module OutputColor
+  extend T::Sig
+
+  sig { params(color_code: Integer, text: String).returns(String) }
+  def self.colorize(color_code, text)
+    "\e[#{color_code}m#{text}\e[0m"
+  end
+
+  sig { params(text: String).returns(String) }
+  def self.red(text)
+    colorize(31, text)
+  end
+
+  sig { params(text: String).returns(String) }
+  def self.green(text)
+    colorize(32, text)
+  end
+
+  sig { params(text: String).returns(String) }
+  def self.yellow(text)
+    colorize(33, text)
+  end
+
+  sig { params(text: String).returns(String) }
+  def self.blue(text)
+    colorize(34, text)
+  end
+
+  sig { params(text: String).returns(String) }
+  def self.pink(text)
+    colorize(35, text)
+  end
+
+  sig { params(text: String).returns(String) }
+  def self.light_blue(text)
+    colorize(36, text)
+  end
+end

data/lib/feature_map/private/assignment_mappers/directory_assignment.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+# typed: true
+
+module FeatureMap
+  module Private
+    module AssignmentMappers
+      class DirectoryAssignment
+        extend T::Sig
+        include Mapper
+
+        FEATURE_DIRECTORY_ASSIGNMENT_FILE_NAME = '.feature'
+
+        @@directory_cache = T.let({}, T::Hash[String, T.nilable(CodeFeatures::Feature)]) # rubocop:disable Style/ClassVars
+
+        sig do
+          override.params(file: String)
+            .returns(T.nilable(CodeFeatures::Feature))
+        end
+        def map_file_to_feature(file)
+          map_file_to_relevant_feature(file)
+        end
+
+        sig do
+          override.params(cache: GlobsToAssignedFeatureMap, files: T::Array[String]).returns(GlobsToAssignedFeatureMap)
+        end
+        def update_cache(cache, files)
+          globs_to_feature(files)
+        end
+
+        #
+        # Directory assignment ignores the passed in files when generating feature assignment lines.
+        # This is because directory assignment knows that the fastest way to find features for directory based assignment
+        # is to simply iterate over the directories and grab the feature, rather than iterating over each file just to get what directory it is in
+        # In theory this means that we may generate feature lines that cover files that are not in the passed in argument,
+        # but in practice this is not of consequence because in reality we never really want to generate feature assignments for only a
+        # subset of files, but rather we want feature assignments for all files.
+        #
+        sig do
+          override.params(files: T::Array[String])
+            .returns(T::Hash[String, CodeFeatures::Feature])
+        end
+        def globs_to_feature(files)
+          # The T.unsafe is because the upstream RBI is wrong for Pathname.glob
+          T
+            .unsafe(Pathname)
+            .glob(File.join('**/', FEATURE_DIRECTORY_ASSIGNMENT_FILE_NAME))
+            .map(&:cleanpath)
+            .each_with_object({}) do |pathname, res|
+            feature = feature_for_directory_assignment_file(pathname)
+            glob = glob_for_directory_assignment_file(pathname)
+            res[glob] = feature
+          end
+        end
+
+        sig { override.returns(String) }
+        def description
+          'Feature Assigned in .feature'
+        end
+
+        sig { override.void }
+        def bust_caches!
+          @@directory_cache = {} # rubocop:disable Style/ClassVars
+        end
+
+        private
+
+        sig { params(file: Pathname).returns(CodeFeatures::Feature) }
+        def feature_for_directory_assignment_file(file)
+          raw_feature_value = File.foreach(file).first.strip
+
+          Private.find_feature!(
+            raw_feature_value,
+            file.to_s
+          )
+        end
+
+        # Takes a file and finds the relevant `.feature` file by walking up the directory
+        # structure. Example, given `a/b/c.rb`, this looks for `a/b/.feature`, `a/.feature`,
+        # and `.feature` in that order, stopping at the first file to actually exist.
+        # If the provided file is a directory, it will look for `.feature` in that directory and then upwards.
+        # We do additional caching so that we don't have to check for file existence every time.
+        sig { params(file: String).returns(T.nilable(CodeFeatures::Feature)) }
+        def map_file_to_relevant_feature(file)
+          file_path = Pathname.new(file)
+          feature = T.let(nil, T.nilable(CodeFeatures::Feature))
+
+          if File.directory?(file)
+            feature = get_feature_from_assignment_file_within_directory(file_path)
+            return feature unless feature.nil?
+          end
+
+          path_components = file_path.each_filename.to_a
+          if file_path.absolute?
+            path_components = ['/', *path_components]
+          end
+
+          (path_components.length - 1).downto(0).each do |i|
+            feature = get_feature_from_assignment_file_within_directory(
+               Pathname.new(File.join(*T.unsafe(path_components[0...i])))
+             )
+            return feature unless feature.nil?
+          end
+
+          feature
+        end
+
+        sig { params(directory: Pathname).returns(T.nilable(CodeFeatures::Feature)) }
+        def get_feature_from_assignment_file_within_directory(directory)
+          potential_directory_assignment_file = directory.join(FEATURE_DIRECTORY_ASSIGNMENT_FILE_NAME)
+
+          potential_directory_assignment_file_name = potential_directory_assignment_file.to_s
+
+          feature = nil
+          if @@directory_cache.key?(potential_directory_assignment_file_name)
+            feature = @@directory_cache[potential_directory_assignment_file_name]
+          elsif potential_directory_assignment_file.exist?
+            feature = feature_for_directory_assignment_file(potential_directory_assignment_file)
+
+            @@directory_cache[potential_directory_assignment_file_name] = feature
+          else
+            @@directory_cache[potential_directory_assignment_file_name] = nil
+          end
+
+          feature
+        end
+
+        sig { params(file: Pathname).returns(String) }
+        def glob_for_directory_assignment_file(file)
+          unescaped = file.dirname.cleanpath.join('**/**').to_s
+
+          # Globs can contain certain regex characters, like "[" and "]".
+          # However, when we are generating a glob from a .feature file, we
+          # need to escape bracket characters and interpret them literally.
+          # Otherwise the resulting glob will not actually match the directory
+          # containing the .feature file.
+          #
+          # Example
+          # file: "/some/[dir]/.feature"
+          # unescaped: "/some/[dir]/**/**"
+          # matches: "/some/d/file"
+          # matches: "/some/i/file"
+          # matches: "/some/r/file"
+          # does not match!: "/some/[dir]/file"
+          unescaped.gsub(/[\[\]]/) { |x| "\\#{x}" }
+        end
+      end
+    end
+  end
+end

data/lib/feature_map/private/assignment_mappers/feature_definition_assignment.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# typed: true
+
+module FeatureMap
+  module Private
+    module AssignmentMappers
+      class FeatureDefinitionAssignment
+        extend T::Sig
+        include Mapper
+
+        @@map_files_to_features = T.let(@map_files_to_features, T.nilable(T::Hash[String, CodeFeatures::Feature])) # rubocop:disable Style/ClassVars
+        @@map_files_to_features = {} # rubocop:disable Style/ClassVars
+
+        sig do
+          params(files: T::Array[String])
+          .returns(T::Hash[String, CodeFeatures::Feature])
+        end
+        def map_files_to_features(files)
+          return @@map_files_to_features if @@map_files_to_features&.keys && @@map_files_to_features.keys.count.positive?
+
+          @@map_files_to_features = CodeFeatures.all.each_with_object({}) do |feature, map| # rubocop:disable Style/ClassVars
+            map[feature.config_yml] = feature
+          end
+        end
+
+        sig do
+          override.params(file: String)
+            .returns(T.nilable(CodeFeatures::Feature))
+        end
+        def map_file_to_feature(file)
+          return nil if Private.configuration.ignore_feature_definitions
+
+          map_files_to_features([file])[file]
+        end
+
+        sig do
+          override.params(files: T::Array[String])
+            .returns(T::Hash[String, CodeFeatures::Feature])
+        end
+        def globs_to_feature(files)
+          return {} if Private.configuration.ignore_feature_definitions
+
+          CodeFeatures.all.each_with_object({}) do |feature, map|
+            map[feature.config_yml] = feature
+          end
+        end
+
+        sig { override.void }
+        def bust_caches!
+          @@map_files_to_features = {} # rubocop:disable Style/ClassVars
+        end
+
+        sig do
+          override.params(cache: GlobsToAssignedFeatureMap, files: T::Array[String]).returns(GlobsToAssignedFeatureMap)
+        end
+        def update_cache(cache, files)
+          globs_to_feature(files)
+        end
+
+        sig { override.returns(String) }
+        def description
+          'Feature definition file assignment'
+        end
+      end
+    end
+  end
+end

data/lib/feature_map/private/assignment_mappers/feature_globs.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# typed: true
+
+module FeatureMap
+  module Private
+    module AssignmentMappers
+      class FeatureGlobs
+        extend T::Sig
+        include Mapper
+        include Validator
+
+        @@map_files_to_features = T.let(@map_files_to_features, T.nilable(T::Hash[String, FeatureMap::CodeFeatures::Feature])) # rubocop:disable Style/ClassVars
+        @@map_files_to_features = {} # rubocop:disable Style/ClassVars
+
+        sig do
+          params(files: T::Array[String])
+          .returns(T::Hash[String, FeatureMap::CodeFeatures::Feature])
+        end
+        def map_files_to_features(files)
+          return @@map_files_to_features if @@map_files_to_features&.keys && @@map_files_to_features.keys.count.positive?
+
+          @@map_files_to_features = FeatureMap::CodeFeatures.all.each_with_object({}) do |feature, map| # rubocop:disable Style/ClassVars
+            FeaturePlugins::Assignment.for(feature).assigned_globs.each do |glob|
+              Dir.glob(glob).each do |filename|
+                map[filename] = feature
+              end
+            end
+          end
+        end
+
+        class MappingContext < T::Struct
+          const :glob, String
+          const :feature, FeatureMap::CodeFeatures::Feature
+        end
+
+        class GlobOverlap < T::Struct
+          extend T::Sig
+
+          const :mapping_contexts, T::Array[MappingContext]
+
+          sig { returns(String) }
+          def description
+            # These are sorted only to prevent non-determinism in output between local and CI environments.
+            sorted_contexts = mapping_contexts.sort_by { |context| context.feature.config_yml.to_s }
+            description_args = sorted_contexts.map do |context|
+              "`#{context.glob}` (from `#{context.feature.config_yml}`)"
+            end
+
+            description_args.join(', ')
+          end
+        end
+
+        sig do
+          returns(T::Array[GlobOverlap])
+        end
+        def find_overlapping_globs
+          mapped_files = T.let({}, T::Hash[String, T::Array[MappingContext]])
+          FeatureMap::CodeFeatures.all.each_with_object({}) do |feature, _map|
+            FeaturePlugins::Assignment.for(feature).assigned_globs.each do |glob|
+              Dir.glob(glob).each do |filename|
+                mapped_files[filename] ||= []
+                T.must(mapped_files[filename]) << MappingContext.new(glob: glob, feature: feature)
+              end
+            end
+          end
+
+          overlaps = T.let([], T::Array[GlobOverlap])
+          mapped_files.each_value do |mapping_contexts|
+            if mapping_contexts.count > 1
+              overlaps << GlobOverlap.new(mapping_contexts: mapping_contexts)
+            end
+          end
+
+          overlaps.uniq do |glob_overlap|
+            glob_overlap.mapping_contexts.map do |context|
+              [context.glob, context.feature.name]
+            end
+          end
+        end
+
+        sig do
+          override.params(file: String)
+            .returns(T.nilable(FeatureMap::CodeFeatures::Feature))
+        end
+        def map_file_to_feature(file)
+          map_files_to_features([file])[file]
+        end
+
+        sig do
+          override.params(cache: GlobsToAssignedFeatureMap, files: T::Array[String]).returns(GlobsToAssignedFeatureMap)
+        end
+        def update_cache(cache, files)
+          globs_to_feature(files)
+        end
+
+        sig do
+          override.params(files: T::Array[String])
+            .returns(T::Hash[String, FeatureMap::CodeFeatures::Feature])
+        end
+        def globs_to_feature(files)
+          FeatureMap::CodeFeatures.all.each_with_object({}) do |feature, map|
+            FeaturePlugins::Assignment.for(feature).assigned_globs.each do |assigned_glob|
+              map[assigned_glob] = feature
+            end
+          end
+        end
+
+        sig { override.void }
+        def bust_caches!
+          @@map_files_to_features = {} # rubocop:disable Style/ClassVars
+        end
+
+        sig { override.returns(String) }
+        def description
+          'Feature-specific assigned globs'
+        end
+
+        sig { override.params(files: T::Array[String], autocorrect: T::Boolean, stage_changes: T::Boolean).returns(T::Array[String]) }
+        def validation_errors(files:, autocorrect: true, stage_changes: true)
+          overlapping_globs = AssignmentMappers::FeatureGlobs.new.find_overlapping_globs
+
+          errors = T.let([], T::Array[String])
+
+          if overlapping_globs.any?
+            errors << <<~MSG
+              `assigned_globs` cannot overlap between features. The following globs overlap:
+
+              #{overlapping_globs.map { |overlap| "- #{overlap.description}" }.join("\n")}
+            MSG
+          end
+
+          errors
+        end
+      end
+    end
+  end
+end