feature_map 1.1.0

data/lib/feature_map/private/test_pyramid_file.rb

@@ -0,0 +1,151 @@
+# typed: strict
+# frozen_string_literal: true
+
+module FeatureMap
+  module Private
+    #
+    # This class is responsible for compiling a set of feature-level test pyramid statistics into a test-pyramid.yml
+    # This file can then be used as an input to a variety of engineering team utilities
+    # (e.g. PR/release announcements, documentation generation, etc).
+    #
+    class TestPyramidFile
+      extend T::Sig
+
+      class FileContentError < StandardError; end
+
+      FEATURES_KEY = 'features'
+
+      FeatureName = T.type_alias { String }
+      PyramidStat = T.type_alias { String }
+
+      FeaturePyramid = T.type_alias do
+        T::Hash[
+          PyramidStat,
+          Integer
+        ]
+      end
+
+      FeaturesContent = T.type_alias do
+        T::Hash[
+          FeatureName,
+          FeaturePyramid
+        ]
+      end
+
+      sig do
+        params(
+          unit_examples: T::Array[T::Hash[T.untyped, T.untyped]],
+          integration_examples: T::Array[T::Hash[T.untyped, T.untyped]],
+          regression_examples: T::Array[T::Hash[T.untyped, T.untyped]],
+          regression_assignments: T::Hash[T.untyped, T.untyped]
+        ).void
+      end
+      def self.write!(unit_examples, integration_examples, regression_examples, regression_assignments)
+        FileUtils.mkdir_p(path.dirname) if !path.dirname.exist?
+
+        regression_file_assignments = regression_assignments['features']&.transform_values do |feature|
+          feature['files']&.map { |file| filepath(file) } || []
+        end || {}
+
+        content = generate_content(
+          unit_examples.group_by { |ex| filepath(ex['id']) },
+          integration_examples.group_by { |ex| filepath(ex['id']) },
+          regression_examples.group_by { |ex| filepath(ex['id']) },
+          regression_file_assignments
+        )
+        path.write([header_comment, "\n", { FEATURES_KEY => content }.to_yaml].join)
+      end
+
+      sig { returns(Pathname) }
+      def self.path
+        Pathname.pwd.join('.feature_map/test-pyramid.yml')
+      end
+
+      sig { returns(String) }
+      def self.header_comment
+        <<~HEADER
+          # STOP! - DO NOT EDIT THIS FILE MANUALLY
+          # This file was automatically generated by "bin/featuremap test_pyramid". The next time this file
+          # is generated any changes will be lost. For more details:
+          # https://github.com/Beyond-Finance/feature_map
+          #
+          # It is NOT recommended to commit this file into your source control. It will change or become
+          # outdated frequently. Instead it should be regenerated when test pyramid statistics are required.
+          # This file should be ignored by your source control, allowing the local copy to be used for other
+          # feature analysis operations (e.g. documentation generation, etc).
+        HEADER
+      end
+
+      sig do
+        params(
+          unit_examples: T::Hash[T.untyped, T.untyped],
+          integration_examples: T::Hash[T.untyped, T.untyped],
+          regression_examples: T::Hash[T.untyped, T.untyped],
+          regression_file_assignments: T::Hash[T.untyped, T.untyped]
+        ).returns(FeaturesContent)
+      end
+      def self.generate_content(unit_examples, integration_examples, regression_examples, regression_file_assignments)
+        Private.feature_file_assignments.reduce({}) do |content, (feature_name, files)|
+          regression_files = regression_file_assignments[feature_name] || []
+          regression_count, regression_pending = regression_files.reduce([0, 0]) do |accumulated_counts, file|
+            accumulated_count, accumulated_pending = accumulated_counts
+            count, pending = split(regression_examples[file])
+
+            [accumulated_count + count, accumulated_pending + pending]
+          end
+
+          pyramid = files.reduce({}) do |acc, file|
+            normalized_path = filepath(file)
+
+            unit_count, unit_pending = split(unit_examples["#{normalized_path}_spec"])
+            integration_count, integration_pending = split(integration_examples[normalized_path])
+
+            {
+              'unit_count' => (acc['unit_count'] || 0) + unit_count,
+              'unit_pending' => (acc['unit_pending'] || 0) + unit_pending,
+              'integration_count' => (acc['integration_count'] || 0) + integration_count,
+              'integration_pending' => (acc['integration_pending'] || 0) + integration_pending
+            }
+          end
+
+          {
+            feature_name => pyramid.merge(
+              'regression_count' => regression_count,
+              'regression_pending' => regression_pending
+            ),
+            **content
+          }
+        end
+      end
+
+      sig { returns(FeaturesContent) }
+      def self.load_features!
+        test_coverage_content = YAML.load_file(path)
+
+        return test_coverage_content[FEATURES_KEY] if test_coverage_content.is_a?(Hash) && test_coverage_content[FEATURES_KEY]
+
+        raise FileContentError, "Unexpected content found in #{path}. Use `bin/featuremap test_coverage` to regenerate it and try again."
+      rescue Psych::SyntaxError => e
+        raise FileContentError, "Invalid YAML content found at #{path}. Error: #{e.message} Use `bin/featuremap test_coverage` to generate it and try again."
+      rescue Errno::ENOENT
+        raise FileContentError, "No feature test coverage file found at #{path}. Use `bin/featuremap test_coverage` to generate it and try again."
+      end
+
+      sig { params(examples: T.nilable(T::Array[T::Hash[T.untyped, T.untyped]])).returns(T::Array[Integer]) }
+      def self.split(examples)
+        return [0, 0] if examples.nil?
+
+        examples.partition { |ex| ex['status'] == 'passed' }.map(&:count)
+      end
+
+      sig { params(pathlike: String).returns(String) }
+      def self.filepath(pathlike)
+        File
+          .join(File.dirname(pathlike), File.basename(pathlike, '.*'))
+          .gsub(%r{^\./}, '')
+          .gsub(%r{^spec/}, '')
+          .gsub(%r{^app/}, '')
+      end
+    end
+  end
+end

data/lib/feature_map/private/todo_inspector.rb

@@ -0,0 +1,57 @@
+# typed: strict
+# frozen_string_literal: true
+
+module FeatureMap
+  module Private
+    class TodoInspector
+      extend T::Sig
+
+      ENTERING_COMMENT = T.let(
+        /
+          (#{(Constants::SINGLE_LINE_COMMENT_PATTERNS + Constants::MULTILINE_COMMENT_START_PATTERNS).join('|')})
+        /x.freeze,
+        Regexp
+      )
+
+      EXITING_COMMENT = T.let(
+        /
+          (#{(Constants::SINGLE_LINE_COMMENT_PATTERNS + Constants::MULTILINE_COMMENT_END_PATTERNS).join('|')})
+        /x.freeze,
+        Regexp
+      )
+
+      TODO_PATTERN = T.let(
+        /
+          TODO:?\s* # TODO with optional colon with whitespace
+          (?<content>.*?) # The actual TODO content
+          (#{Constants::MULTILINE_COMMENT_END_PATTERNS.join('|')})?$ # ignores comment end patterns
+        /xi.freeze,
+        Regexp
+      )
+
+      sig { params(file_path: String).void }
+      def initialize(file_path)
+        @file_path = file_path
+      end
+
+      sig { returns(T::Hash[String, String]) }
+      def calculate
+        todos = {}
+        content = File.read(@file_path)
+        in_comment = T.let(false, T::Boolean)
+
+        content.each_line.with_index do |line, index|
+          in_comment ||= line.match?(ENTERING_COMMENT)
+
+          if in_comment && (match = line.match(TODO_PATTERN))
+            todos["#{@file_path}:#{index + 1}"] = T.must(match[:content]).strip
+          end
+
+          in_comment &&= !line.match?(EXITING_COMMENT)
+        end
+
+        todos
+      end
+    end
+  end
+end

data/lib/feature_map/private/validations/features_up_to_date.rb

@@ -0,0 +1,78 @@
+# typed: strict
+
+module FeatureMap
+  module Private
+    module Validations
+      class FeaturesUpToDate
+        extend T::Sig
+        extend T::Helpers
+        include Validator
+
+        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)
+          return [] if Private.configuration.skip_features_validation
+
+          actual_content_lines = AssignmentsFile.actual_contents_lines
+          expected_content_lines = AssignmentsFile.expected_contents_lines
+
+          features_file_up_to_date = actual_content_lines == expected_content_lines
+          errors = T.let([], T::Array[String])
+
+          if !features_file_up_to_date
+            if autocorrect
+              AssignmentsFile.write!
+              if stage_changes
+                `git add #{AssignmentsFile.path}`
+              end
+            # If there is no current file or its empty, display a shorter message.
+            elsif actual_content_lines == ['']
+              errors << <<~FEATURES_FILE_ERROR
+                .feature_map/assignments.yml out of date. Run `bin/featuremap validate` to update the .feature_map/assignments.yml file
+              FEATURES_FILE_ERROR
+            else
+              missing_lines = expected_content_lines - actual_content_lines
+              extra_lines = actual_content_lines - expected_content_lines
+
+              missing_lines_text = if missing_lines.any?
+                                     <<~COMMENT
+                                       .feature_map/assignments.yml should contain the following lines, but does not:
+                                       #{missing_lines.map { |line| "- \"#{line}\"" }.join("\n")}
+                                     COMMENT
+                                   end
+
+              extra_lines_text = if extra_lines.any?
+                                   <<~COMMENT
+                                     .feature_map/assignments.yml should not contain the following lines, but it does:
+                                     #{extra_lines.map { |line| "- \"#{line}\"" }.join("\n")}
+                                   COMMENT
+                                 end
+
+              diff_text = if missing_lines_text && extra_lines_text
+                            "#{missing_lines_text}\n#{extra_lines_text}".chomp
+                          elsif missing_lines_text
+                            missing_lines_text
+                          elsif extra_lines_text
+                            extra_lines_text
+                          else
+                            <<~TEXT
+                              There may be extra lines, or lines are out of order.
+                              You can try to regenerate the .feature_map/assignments.yml file from scratch:
+                              1) `rm .feature_map/assignments.yml`
+                              2) `bin/featuremap validate`
+                            TEXT
+                          end
+
+              errors << <<~FEATURES_FILE_ERROR
+                .feature_map/assignments.yml out of date. Run `bin/featuremap validate` to update the .feature_map/assignments.yml file
+
+                #{diff_text.chomp}
+              FEATURES_FILE_ERROR
+            end
+          end
+
+          errors
+        end
+      end
+    end
+  end
+end

data/lib/feature_map/private/validations/files_have_features.rb

@@ -0,0 +1,45 @@
+# typed: strict
+
+require 'code_ownership'
+
+module FeatureMap
+  module Private
+    module Validations
+      class FilesHaveFeatures
+        extend T::Sig
+        extend T::Helpers
+        include Validator
+
+        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)
+          cache = Private.glob_cache
+          file_mappings = cache.mapper_descriptions_that_map_files(files)
+          files_not_mapped_at_all = file_mappings.select do |_file, mapper_descriptions|
+            mapper_descriptions.count.zero?
+          end
+
+          errors = T.let([], T::Array[String])
+
+          # When a set of teams are configured that require assignments, ignore any files NOT
+          # assigned to one of these teams.
+          unless Private.configuration.require_assignment_for_teams.nil?
+            files_not_mapped_at_all.filter! do |file, _mappers|
+              file_team = CodeOwnership.for_file(file)
+              file_team && T.must(Private.configuration.require_assignment_for_teams).include?(file_team.name)
+            end
+          end
+
+          if files_not_mapped_at_all.any?
+            errors << <<~MSG
+              Some files are missing a feature assignment:
+
+              #{files_not_mapped_at_all.map { |file, _mappers| "- #{file}" }.join("\n")}
+            MSG
+          end
+
+          errors
+        end
+      end
+    end
+  end
+end

data/lib/feature_map/private/validations/files_have_unique_features.rb

@@ -0,0 +1,34 @@
+# typed: strict
+
+module FeatureMap
+  module Private
+    module Validations
+      class FilesHaveUniqueFeatures
+        extend T::Sig
+        extend T::Helpers
+        include Validator
+
+        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)
+          cache = Private.glob_cache
+          file_mappings = cache.mapper_descriptions_that_map_files(files)
+          files_mapped_by_multiple_mappers = file_mappings.select do |_file, mapper_descriptions|
+            mapper_descriptions.count > 1
+          end
+
+          errors = T.let([], T::Array[String])
+
+          if files_mapped_by_multiple_mappers.any?
+            errors << <<~MSG
+              Feature assignment should only be defined for each file in one way. The following files have had features assigned in multiple ways.
+
+              #{files_mapped_by_multiple_mappers.map { |file, descriptions| "- #{file} (#{descriptions.to_a.join(', ')})" }.join("\n")}
+            MSG
+          end
+
+          errors
+        end
+      end
+    end
+  end
+end

data/lib/feature_map/private.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+require 'feature_map/constants'
+require 'feature_map/private/extension_loader'
+require 'feature_map/private/cyclomatic_complexity_calculator'
+require 'feature_map/private/lines_of_code_calculator'
+require 'feature_map/private/todo_inspector'
+require 'feature_map/private/feature_metrics_calculator'
+require 'feature_map/private/assignments_file'
+require 'feature_map/private/metrics_file'
+require 'feature_map/private/glob_cache'
+require 'feature_map/private/feature_assigner'
+require 'feature_map/private/documentation_site'
+require 'feature_map/private/code_cov'
+require 'feature_map/private/test_coverage_file'
+require 'feature_map/private/test_pyramid_file'
+require 'feature_map/private/feature_plugins/assignment'
+require 'feature_map/private/validations/files_have_features'
+require 'feature_map/private/validations/features_up_to_date'
+require 'feature_map/private/validations/files_have_unique_features'
+require 'feature_map/private/assignment_mappers/file_annotations'
+require 'feature_map/private/assignment_mappers/feature_globs'
+require 'feature_map/private/assignment_mappers/directory_assignment'
+require 'feature_map/private/assignment_mappers/feature_definition_assignment'
+
+module FeatureMap
+  module Private
+    extend T::Sig
+
+    FeatureName = T.type_alias { String }
+    FileList = T.type_alias { T::Array[String] }
+    FeatureFiles = T.type_alias do
+      T::Hash[
+        FeatureName,
+        FileList
+      ]
+    end
+
+    sig { returns(Configuration) }
+    def self.configuration
+      @configuration ||= T.let(@configuration, T.nilable(Configuration))
+      @configuration ||= Configuration.fetch
+    end
+
+    # This is just an alias for `configuration` that makes it more explicit what we're doing instead of just calling `configuration`.
+    # This is necessary because configuration may contain extensions of feature map, so those extensions should be loaded prior to
+    # calling APIs that provide feature assignment information.
+    sig { returns(Configuration) }
+    def self.load_configuration!
+      configuration
+    end
+
+    sig { void }
+    def self.bust_caches!
+      @configuration = nil
+      @tracked_files = nil
+      @glob_cache = nil
+    end
+
+    sig { params(files: T::Array[String], autocorrect: T::Boolean, stage_changes: T::Boolean).void }
+    def self.validate!(files:, autocorrect: true, stage_changes: true)
+      AssignmentsFile.update_cache!(files) if AssignmentsFile.use_features_cache?
+
+      errors = Validator.all.flat_map do |validator|
+        validator.validation_errors(
+          files: files,
+          autocorrect: autocorrect,
+          stage_changes: stage_changes
+        )
+      end
+
+      if errors.any?
+        errors << 'See https://github.com/Beyond-Finance/feature_map#README.md for more details'
+        raise InvalidFeatureMapConfigurationError.new(errors.join("\n")) # rubocop:disable Style/RaiseArgs
+      end
+
+      MetricsFile.write!
+    end
+
+    sig { params(git_ref: T.nilable(String)).void }
+    def self.generate_docs!(git_ref)
+      feature_assignments = AssignmentsFile.load_features!
+      feature_metrics = MetricsFile.load_features!
+
+      # Generating the test pyramid involves collecting dry-run coverage from rspec for unit, integration,
+      # and regression tests.  This can be difficult to gather, so we allow for the docs site to be built
+      # without it.
+      feature_test_pyramid = TestPyramidFile.path.exist? ? TestPyramidFile.load_features! : {}
+
+      # Test coverage data can be onerous to load (e.g. generating a CodeCov token, etc). Allow engineers to generate
+      # and review the feature documentation without this data.
+      feature_test_coverage = TestCoverageFile.path.exist? ? TestCoverageFile.load_features! : {}
+
+      DocumentationSite.generate(
+        feature_assignments,
+        feature_metrics,
+        feature_test_coverage,
+        feature_test_pyramid,
+        configuration.raw_hash,
+        T.must(git_ref || configuration.repository['main_branch'])
+      )
+    end
+
+    sig do
+      params(
+        unit_path: String,
+        integration_path: String,
+        regression_path: String,
+        regression_assignments_path: String
+      ).void
+    end
+    def self.generate_test_pyramid!(unit_path, integration_path, regression_path, regression_assignments_path)
+      unit_examples = JSON.parse(File.read(unit_path))&.fetch('examples')
+      integration_examples = JSON.parse(File.read(integration_path))&.fetch('examples')
+      regression_examples = JSON.parse(File.read(regression_path))&.fetch('examples')
+      regression_assignments = YAML.load_file(regression_assignments_path)
+      TestPyramidFile.write!(unit_examples, integration_examples, regression_examples, regression_assignments)
+    end
+
+    sig { params(commit_sha: String, code_cov_token: String).void }
+    def self.gather_test_coverage!(commit_sha, code_cov_token)
+      coverage_stats = CodeCov.fetch_coverage_stats(commit_sha, code_cov_token)
+
+      TestCoverageFile.write!(coverage_stats)
+    end
+
+    # Returns a string version of the relative path to a Rails constant,
+    # or nil if it can't find something
+    sig { params(klass: T.nilable(T.any(T::Class[T.anything], Module))).returns(T.nilable(String)) }
+    def self.path_from_klass(klass)
+      if klass
+        path = Object.const_source_location(klass.to_s)&.first
+        (path && Pathname.new(path).relative_path_from(Pathname.pwd).to_s) || nil
+      else
+        nil
+      end
+    rescue NameError
+      nil
+    end
+
+    #
+    # The output of this function is string pathnames relative to the root.
+    #
+    sig { returns(T::Array[String]) }
+    def self.tracked_files
+      @tracked_files ||= T.let(@tracked_files, T.nilable(T::Array[String]))
+      @tracked_files ||= Dir.glob(configuration.assigned_globs) - Dir.glob(configuration.unassigned_globs)
+    end
+
+    sig { params(file: String).returns(T::Boolean) }
+    def self.file_tracked?(file)
+      # Another way to accomplish this is
+      # (Dir.glob(configuration.assigned_globs) - Dir.glob(configuration.unassigned_globs)).include?(file)
+      # However, globbing out can take 5 or more seconds on a large repository, dramatically slowing down
+      # invocations to `bin/featuremap validate --diff`.
+      # Using `File.fnmatch?` is a lot faster!
+      in_assigned_globs = configuration.assigned_globs.any? do |assigned_glob|
+        File.fnmatch?(assigned_glob, file, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+      end
+
+      in_unassigned_globs = configuration.unassigned_globs.any? do |unassigned_glob|
+        File.fnmatch?(unassigned_glob, file, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+      end
+      in_assigned_globs && !in_unassigned_globs && File.exist?(file)
+    end
+
+    sig { params(feature_name: String, location_of_reference: String).returns(CodeFeatures::Feature) }
+    def self.find_feature!(feature_name, location_of_reference)
+      found_feature = CodeFeatures.find(feature_name)
+      if found_feature.nil?
+        raise StandardError, "Could not find feature with name: `#{feature_name}` in #{location_of_reference}. Make sure the feature is one of `#{CodeFeatures.all.map(&:name).sort}`"
+      else
+        found_feature
+      end
+    end
+
+    sig { returns(GlobCache) }
+    def self.glob_cache
+      @glob_cache ||= T.let(@glob_cache, T.nilable(GlobCache))
+      @glob_cache ||= if AssignmentsFile.use_features_cache?
+                        AssignmentsFile.to_glob_cache
+                      else
+                        Mapper.to_glob_cache
+                      end
+    end
+
+    sig { returns(FeatureFiles) }
+    def self.feature_file_assignments
+      glob_cache.raw_cache_contents.values.each_with_object(T.let({}, FeatureFiles)) do |assignment_map_cache, feature_files|
+        assignment_map_cache.to_h.each do |path, feature|
+          feature_files[feature.name] ||= T.let([], FileList)
+          files = Dir.glob(path).reject { |glob_entry| File.directory?(glob_entry) }
+          files.each { |file| T.must(feature_files[feature.name]) << file }
+        end
+
+        feature_files
+      end
+    end
+  end
+
+  private_constant :Private
+end

data/lib/feature_map/validator.rb

@@ -0,0 +1,29 @@
+# typed: strict
+
+module FeatureMap
+  module Validator
+    extend T::Sig
+    extend T::Helpers
+
+    interface!
+
+    sig { abstract.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); end
+
+    class << self
+      extend T::Sig
+
+      sig { params(base: T::Class[Validator]).void }
+      def included(base)
+        @validators ||= T.let(@validators, T.nilable(T::Array[T::Class[Validator]]))
+        @validators ||= []
+        @validators << base
+      end
+
+      sig { returns(T::Array[Validator]) }
+      def all
+        (@validators || []).map(&:new)
+      end
+    end
+  end
+end