feature_map 1.2.2 → 1.2.3

data/lib/feature_map/private/documentation_site.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module FeatureMap
@@ -63,22 +62,9 @@ module FeatureMap
     # The `window.FEATURES` global variable is used within the site logic to render an appropriate set of
     # documentation artifacts and charts.
     class DocumentationSite
-      extend T::Sig
-
       ASSETS_DIRECTORY = 'docs'
       FETAURE_DEFINITION_KEYS_TO_INCLUDE = %w[description dashboard_link documentation_link].freeze
 
-      sig do
-        params(
-          feature_assignments: AssignmentsFile::FeaturesContent,
-          feature_metrics: MetricsFile::FeaturesContent,
-          feature_test_coverage: TestCoverageFile::FeaturesContent,
-          feature_test_pyramid: TestPyramidFile::FeaturesContent,
-          feature_additional_metrics: AdditionalMetricsFile::FeaturesContent,
-          project_configuration: T::Hash[T.untyped, T.untyped],
-          git_ref: String
-        ).void
-      end
       def self.generate(
         feature_assignments,
         feature_metrics,
@@ -117,12 +103,10 @@ module FeatureMap
         end
       end
 
-      sig { returns(Pathname) }
       def self.output_directory
         Pathname.pwd.join('.feature_map/docs')
       end
 
-      sig { returns(String) }
       def self.assets_directory
         File.join(File.dirname(__FILE__), ASSETS_DIRECTORY)
       end

data/lib/feature_map/private/extension_loader.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module FeatureMap
@@ -7,8 +6,6 @@ module FeatureMap
     # in the `.feature_map/config.yml` configuration.
     module ExtensionLoader
       class << self
-        extend T::Sig
-        sig { params(require_directive: String).void }
         def load(require_directive)
           # We want to transform the require directive to behave differently
           # if it's a specific local file being required versus a gem

data/lib/feature_map/private/feature_assigner.rb

@@ -1,12 +1,8 @@
-# typed: strict
 # frozen_string_literal: true
 
 module FeatureMap
   module Private
     class FeatureAssigner
-      extend T::Sig
-
-      sig { params(globs_to_assigned_feature_map: GlobsToAssignedFeatureMap).returns(GlobsToAssignedFeatureMap) }
       def self.assign_features(globs_to_assigned_feature_map)
         globs_to_assigned_feature_map.each_with_object({}) do |(glob, feature), mapping|
           # addresses the case where a directory name includes regex characters

data/lib/feature_map/private/feature_metrics_calculator.rb

@@ -1,12 +1,9 @@
-# typed: strict
 # frozen_string_literal: true
 
 require 'rubocop'
 module FeatureMap
   module Private
     class FeatureMetricsCalculator
-      extend T::Sig
-
       ABC_SIZE_METRIC = 'abc_size'
       CYCLOMATIC_COMPLEXITY_METRIC = 'cyclomatic_complexity'
       LINES_OF_CODE_METRIC = 'lines_of_code'
@@ -14,23 +11,15 @@ module FeatureMap
       COMPLEXITY_RATIO_METRIC = 'complexity_ratio'
       ENCAPSULATION_RATIO_METRIC = 'encapsulation_ratio'
 
-      SUPPORTED_METRICS = T.let([
+      SUPPORTED_METRICS = [
         ABC_SIZE_METRIC,
         CYCLOMATIC_COMPLEXITY_METRIC,
         LINES_OF_CODE_METRIC,
         TODO_LOCATIONS_METRIC,
         COMPLEXITY_RATIO_METRIC,
         ENCAPSULATION_RATIO_METRIC
-      ].freeze, T::Array[String])
-
-      FeatureMetrics = T.type_alias do
-        T::Hash[
-          String, # metric name
-          T.any(Integer, T.nilable(Float), T::Hash[String, String]) # score or todo locations with messages
-        ]
-      end
+      ].freeze
 
-      sig { params(file_paths: T::Array[String]).returns(FeatureMetrics) }
       def self.calculate_for_feature(file_paths)
         metrics = file_paths.map { |file| calculate_for_file(file) }
 
@@ -48,7 +37,6 @@ module FeatureMap
         aggregate_metrics
       end
 
-      sig { params(file_path: String).returns(FeatureMetrics) }
       def self.calculate_for_file(file_path)
         metrics = {
           LINES_OF_CODE_METRIC => LinesOfCodeCalculator.new(file_path).calculate
@@ -76,14 +64,12 @@ module FeatureMap
         )
       end
 
-      sig { params(aggregate_metrics: T::Hash[String, T.untyped]).returns(T.nilable(Float)) }
       def self.complexity_ratio(aggregate_metrics)
         return 0.0 if aggregate_metrics[LINES_OF_CODE_METRIC].nil? || aggregate_metrics[CYCLOMATIC_COMPLEXITY_METRIC].nil? || aggregate_metrics[CYCLOMATIC_COMPLEXITY_METRIC].zero?
 
         aggregate_metrics[LINES_OF_CODE_METRIC].to_f / aggregate_metrics[CYCLOMATIC_COMPLEXITY_METRIC]
       end
 
-      sig { params(file_paths: T.nilable(T::Array[String]), aggregate_metrics: T::Hash[String, T.untyped]).returns(T.nilable(Float)) }
       def self.encapsulation_ratio(file_paths, aggregate_metrics)
         return 0.0 if file_paths.nil? || aggregate_metrics[LINES_OF_CODE_METRIC].nil? || aggregate_metrics[LINES_OF_CODE_METRIC].zero?
 

data/lib/feature_map/private/feature_plugins/assignment.rb

@@ -1,13 +1,7 @@
-# typed: true
-
 module FeatureMap
   module Private
     module FeaturePlugins
       class Assignment < FeatureMap::CodeFeatures::Plugin
-        extend T::Sig
-        extend T::Helpers
-
-        sig { returns(T::Array[String]) }
         def assigned_globs
           @feature.raw_hash['assigned_globs'] || []
         end

data/lib/feature_map/private/glob_cache.rb

@@ -1,44 +1,22 @@
-# typed: strict
 # frozen_string_literal: true
 
 module FeatureMap
   module Private
     class GlobCache
-      extend T::Sig
-
-      MapperDescription = T.type_alias { String }
-
-      CacheShape = T.type_alias do
-        T::Hash[
-          MapperDescription,
-          GlobsToAssignedFeatureMap
-        ]
-      end
-
-      FilesByMapper = T.type_alias do
-        T::Hash[
-          String,
-          T::Set[MapperDescription]
-        ]
-      end
-
-      sig { params(raw_cache_contents: CacheShape).void }
       def initialize(raw_cache_contents)
         @raw_cache_contents = raw_cache_contents
       end
 
-      sig { returns(CacheShape) }
       def raw_cache_contents
         @raw_cache_contents
       end
 
-      sig { params(files: T::Array[String]).returns(FilesByMapper) }
       def mapper_descriptions_that_map_files(files)
         files_by_mappers = files.to_h { |f| [f, Set.new([])] }
 
         files_by_mappers_via_expanded_cache.each do |file, mappers|
           mappers.each do |mapper|
-            T.must(files_by_mappers[file]) << mapper if files_by_mappers[file]
+            files_by_mappers[file] << mapper if files_by_mappers[file]
           end
         end
 
@@ -47,10 +25,7 @@ module FeatureMap
 
       private
 
-      sig { returns(CacheShape) }
       def expanded_cache
-        @expanded_cache = T.let(@expanded_cache, T.nilable(CacheShape))
-
         @expanded_cache ||= begin
           expanded_cache = {}
           @raw_cache_contents.each do |mapper_description, globs_by_feature|
@@ -60,11 +35,9 @@ module FeatureMap
         end
       end
 
-      sig { returns(FilesByMapper) }
       def files_by_mappers_via_expanded_cache
-        @files_by_mappers_via_expanded_cache ||= T.let(@files_by_mappers_via_expanded_cache, T.nilable(FilesByMapper))
         @files_by_mappers_via_expanded_cache ||= begin
-          files_by_mappers = T.let({}, FilesByMapper)
+          files_by_mappers = {}
           expanded_cache.each do |mapper_description, file_by_feature|
             file_by_feature.each_key do |file|
               files_by_mappers[file] ||= Set.new([])

data/lib/feature_map/private/health_calculator.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module FeatureMap
+  module Private
+    class HealthCalculator
+      attr_reader :percentile_metrics, :cyclomatic_complexity_config, :encapsulation_config, :test_coverage_config, :todo_count_config
+
+      def initialize(percentile_metrics:, health_config:)
+        @percentile_metrics = percentile_metrics
+        @cyclomatic_complexity_config = health_config['components']['cyclomatic_complexity']
+        @encapsulation_config = health_config['components']['encapsulation']
+        @test_coverage_config = health_config['components']['test_coverage']
+        @todo_count_config = health_config['components']['todo_count']
+      end
+
+      def health_score_for(feature_name)
+        test_coverage_component = test_coverage_component_for(feature_name)
+        cyclomatic_complexity_component = cyclomatic_complexity_component_for(feature_name)
+        encapsulation_component = encapsulation_component_for(feature_name)
+        todo_count_component = todo_count_component_for(feature_name)
+
+        overall = [
+          test_coverage_component,
+          cyclomatic_complexity_component,
+          encapsulation_component,
+          todo_count_component
+        ].sum { |c| c['health_score'] }
+
+        total_weight = [
+          cyclomatic_complexity_config,
+          encapsulation_config,
+          test_coverage_config,
+          todo_count_config
+        ].sum { |c| c['weight'] }
+
+        {
+          'test_coverage_component' => test_coverage_component,
+          'cyclomatic_complexity_component' => cyclomatic_complexity_component,
+          'encapsulation_component' => encapsulation_component,
+          'todo_count_component' => todo_count_component,
+          'overall' => overall / total_weight * 100
+        }
+      end
+
+      private
+
+      def cyclomatic_complexity_component_for(feature_name)
+        cyclomatic_complexity = percentile_metrics.cyclomatic_complexity_for(feature_name)
+
+        health_score_component(
+          cyclomatic_complexity_config['weight'],
+          cyclomatic_complexity['percentile'],
+          cyclomatic_complexity['percent_of_max'],
+          cyclomatic_complexity_config['percent_of_max_threshold']
+        )
+      end
+
+      def encapsulation_component_for(feature_name)
+        encapsulation = percentile_metrics.encapsulation_for(feature_name)
+
+        health_score_component(
+          encapsulation_config['weight'],
+          encapsulation['percentile'],
+          encapsulation['percent_of_max'],
+          encapsulation_config['percent_of_max_threshold']
+        )
+      end
+
+      def health_score_component(awardable_points, score, percent_of_max, percent_of_max_threshold)
+        close_to_maximum_score = percent_of_max_threshold && percent_of_max >= percent_of_max_threshold
+        component = { 'awardable_points' => awardable_points, 'close_to_maximum_score' => close_to_maximum_score }
+
+        # NOTE:  Certain metrics scores are derived from their relative percentile.
+        #        As a codebase converges, say on encapsulation, relative percentile
+        #        scoring dictates that the lower percentiles always receive a
+        #        worse score than higher percentiles even when their values are close.
+        #
+        #        E.g., if encapsulation scores are of the set [9.6, 9.7, 9.8, 9.9],
+        #        is it fair to award the feature at `9.6` dramatically less than `9.9?`
+        #
+        #        Each host application can set a `percent_of_max_threshold` for these metrics such that
+        #        if a given feature's score is within this threshold of the highest performing feature,
+        #        it is awarded full points.
+        return component.merge('health_score' => awardable_points) if close_to_maximum_score
+
+        component.merge(
+          'health_score' => [(score.to_f / 100) * awardable_points, awardable_points].min
+        )
+      end
+
+      def test_coverage_component_for(feature_name)
+        test_coverage = percentile_metrics.test_coverage_for(feature_name)
+
+        # NOTE:  Test coverage is based on the absolute coverage percentage
+        #        of code within a given feature.  E.g., a score of 60 does not indicate
+        #        that test coverage is within the sixtieth percentile -- but rather
+        #        that 60% of its lines are covered by tests.
+        #
+        #        FeatureMap does not mean to imply that all codebases should seek to
+        #        cover 100% of lines, so `percent_of_max_threshold` in this case is the variance
+        #        from 100% test coverage which should receive full marks.
+        health_score_component(
+          test_coverage_config['weight'],
+          test_coverage['score'],
+          test_coverage['score'],
+          test_coverage_config['percent_of_max_threshold']
+        )
+      end
+
+      def todo_count_component_for(feature_name)
+        todo_count = percentile_metrics.todo_count_for(feature_name)
+
+        health_score_component(
+          todo_count_config['weight'],
+          100 - todo_count['percent_of_max'],
+          100 - todo_count['percent_of_max'],
+          todo_count_config['percent_of_max_threshold']
+        )
+      end
+    end
+  end
+end

data/lib/feature_map/private/lines_of_code_calculator.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 require 'parser/current'
@@ -6,33 +5,23 @@ require 'parser/current'
 module FeatureMap
   module Private
     class LinesOfCodeCalculator
-      extend T::Sig
-
       # NOTE:  regex 'x' arg ignores whitespace within the _construction_ of the regex.
       #        regex 'm' arg allows the regex to _execute_ on multiline strings.
-      SINGLE_LINE_COMMENT_PATTERN = T.let(
-        /
-          \s* # Any amount of whitespace
-          (#{Constants::SINGLE_LINE_COMMENT_PATTERNS.join('|')}) # Any comment start
-          .* # And the rest of the line
-        /x.freeze,
-        Regexp
-      )
-      MULTI_LINE_COMMENT_PATTERN = T.let(
-        /
-          (#{Constants::MULTILINE_COMMENT_START_PATTERNS.join('|')}) # Multiline comment start
-          .*? # Everything in between, but lazily so we stop when we hit...
-          (#{Constants::MULTILINE_COMMENT_END_PATTERNS.join('|')}) # ...Multiline comment end
-        /xm.freeze,
-        Regexp
-      )
+      SINGLE_LINE_COMMENT_PATTERN = /
+        \s* # Any amount of whitespace
+        (#{Constants::SINGLE_LINE_COMMENT_PATTERNS.join('|')}) # Any comment start
+        .* # And the rest of the line
+      /x.freeze
+      MULTI_LINE_COMMENT_PATTERN = /
+        (#{Constants::MULTILINE_COMMENT_START_PATTERNS.join('|')}) # Multiline comment start
+        .*? # Everything in between, but lazily so we stop when we hit...
+        (#{Constants::MULTILINE_COMMENT_END_PATTERNS.join('|')}) # ...Multiline comment end
+      /xm.freeze
 
-      sig { params(file_path: String).void }
       def initialize(file_path)
         @file_path = file_path
       end
 
-      sig { returns(Integer) }
       def calculate
         # Ignore lines that are entirely whitespace or that are entirely a comment.
         File

data/lib/feature_map/private/metrics_file.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module FeatureMap
@@ -9,41 +8,20 @@ module FeatureMap
     # PR/release announcements, documentation generation, etc).
     #
     class MetricsFile
-      extend T::Sig
-
       class FileContentError < StandardError; end
 
       FEATURES_KEY = 'features'
 
-      FeatureName = T.type_alias { String }
-
-      FeatureMetrics = T.type_alias do
-        T::Hash[
-          String,
-          T.any(Integer, T.nilable(Float), T::Hash[String, String])
-        ]
-      end
-
-      FeaturesContent = T.type_alias do
-        T::Hash[
-          FeatureName,
-          FeatureMetrics
-        ]
-      end
-
-      sig { void }
       def self.write!
         FileUtils.mkdir_p(path.dirname) if !path.dirname.exist?
 
         path.write([header_comment, "\n", generate_content.to_yaml].join)
       end
 
-      sig { returns(Pathname) }
       def self.path
         Pathname.pwd.join('.feature_map/metrics.yml')
       end
 
-      sig { returns(String) }
       def self.header_comment
         <<~HEADER
           # STOP! - DO NOT EDIT THIS FILE MANUALLY
@@ -58,9 +36,8 @@ module FeatureMap
         HEADER
       end
 
-      sig { returns(T::Hash[String, FeaturesContent]) }
       def self.generate_content
-        feature_metrics = T.let({}, FeaturesContent)
+        feature_metrics = {}
 
         Private.feature_file_assignments.each do |feature_name, files|
           feature_metrics[feature_name] = FeatureMetricsCalculator.calculate_for_feature(files)
@@ -69,7 +46,6 @@ module FeatureMap
         { FEATURES_KEY => feature_metrics }
       end
 
-      sig { returns(FeaturesContent) }
       def self.load_features!
         metrics_content = YAML.load_file(path)
 

data/lib/feature_map/private/percentile_metrics_calculator.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module FeatureMap
+  module Private
+    class PercentileMetricsCalculator
+      attr_reader :metrics, :test_coverage
+
+      def initialize(metrics:, test_coverage:)
+        @metrics = metrics
+        @test_coverage = test_coverage
+      end
+
+      def cyclomatic_complexity_for(feature_name)
+        calculate(
+          cyclomatic_complexity_ratios,
+          metrics.dig(feature_name, FeatureMetricsCalculator::COMPLEXITY_RATIO_METRIC)
+        )
+      end
+
+      def encapsulation_for(feature_name)
+        calculate(
+          encapsulation_ratios,
+          metrics.dig(feature_name, FeatureMetricsCalculator::ENCAPSULATION_RATIO_METRIC)
+        )
+      end
+
+      def feature_size_for(feature_name)
+        calculate(
+          feature_sizes,
+          metrics.dig(feature_name, FeatureMetricsCalculator::LINES_OF_CODE_METRIC)
+        )
+      end
+
+      def test_coverage_for(feature_name)
+        calculate(
+          test_coverage_ratios,
+          test_coverage.dig(feature_name, TestCoverageFile::COVERAGE_RATIO)
+        )
+      end
+
+      def todo_count_for(feature_name)
+        calculate(
+          todo_counts,
+          metrics.dig(feature_name, FeatureMetricsCalculator::TODO_LOCATIONS_METRIC)&.size
+        )
+      end
+
+      private
+
+      def calculate(collection, score)
+        if score.nil?
+          return { 'percentile' => 0.0, 'percent_of_max' => 0, 'score' => 0 }
+        end
+
+        max = collection.max || 0
+        percentile = percentile_of(collection, score)
+        percent_of_max = max.zero? ? 0 : ((score.to_f / max) * 100).round.to_i
+
+        { 'percentile' => percentile, 'percent_of_max' => percent_of_max, 'score' => score }
+      end
+
+      def cyclomatic_complexity_ratios
+        return @cyclomatic_complexity_ratios if defined?(@cyclomatic_complexity_ratios)
+
+        @cyclomatic_complexity_ratios = metrics.values.map { |m| m[FeatureMetricsCalculator::COMPLEXITY_RATIO_METRIC] }.compact
+      end
+
+      def encapsulation_ratios
+        return @encapsulation_ratios if defined?(@encapsulation_ratios)
+
+        @encapsulation_ratios = metrics.values.map { |m| m[FeatureMetricsCalculator::ENCAPSULATION_RATIO_METRIC] }.compact
+      end
+
+      def feature_sizes
+        return @feature_sizes if defined?(@feature_sizes)
+
+        @feature_sizes = metrics.values.map { |m| m[FeatureMetricsCalculator::LINES_OF_CODE_METRIC] }.compact
+      end
+
+      # NOTE:  This percentile calculation uses a midpoint convention for handling ties,
+      # where values equal to the target contribute 0.5 to the count.
+      # This approach considers each value as being "half below and half above" itself,
+      # resulting in the maximum value in a dataset having a percentile of (n-0.5)/n * 100
+      # instead of 100%.
+      def percentile_of(arr, val)
+        return 0.0 if arr.empty?
+
+        ensure_array_of_floats = arr.map(&:to_f)
+        ensure_float_value = val.to_f
+
+        below_or_equal_count = ensure_array_of_floats.reduce(0) do |acc, v|
+          if v < ensure_float_value
+            acc + 1
+          elsif v == ensure_float_value
+            acc + 0.5
+          else
+            acc
+          end
+        end
+
+        ((100 * below_or_equal_count) / ensure_array_of_floats.length).to_f
+      end
+
+      def test_coverage_ratios
+        return @test_coverage_ratios if defined?(@test_coverage_ratios)
+
+        @test_coverage_ratios = test_coverage.values.map { |c| c[TestCoverageFile::COVERAGE_RATIO] }.compact
+      end
+
+      def todo_counts
+        return @todo_counts if defined?(@todo_counts)
+
+        @todo_counts = metrics.values.map { |c| c[FeatureMetricsCalculator::TODO_LOCATIONS_METRIC]&.size }.compact
+      end
+    end
+  end
+end

data/lib/feature_map/private/release_notification_builder.rb

@@ -1,4 +1,3 @@
-# typed: strict
 # frozen_string_literal: true
 
 module FeatureMap
@@ -9,15 +8,7 @@ module FeatureMap
     # (see https://app.slack.com/block-kit-builder).
     #
     class ReleaseNotificationBuilder
-      extend T::Sig
-
-      BlockKitSection = T.type_alias { T::Hash[String, T.untyped] }
-      BlockKitPayload = T.type_alias { T::Array[T::Hash[String, T.untyped]] }
-
       class << self
-        extend T::Sig
-
-        sig { params(commits_by_feature: CommitsByFeature).returns(BlockKitPayload) }
         def build(commits_by_feature)
           return [] if commits_by_feature.empty?
 
@@ -26,13 +17,12 @@ module FeatureMap
           feature_names.flat_map.with_index do |feature_name, index|
             # Insert a divider between each feature but not above the first feature nor below the last feature.
             divider = index.zero? ? [] : [{ type: 'divider' }]
-            divider + [build_feature_section(feature_name, T.must(commits_by_feature[feature_name]))]
+            divider + [build_feature_section(feature_name, commits_by_feature[feature_name])]
           end
         end
 
         private
 
-        sig { params(feature_name: String, commits: T::Array[Commit]).returns(BlockKitSection) }
         def build_feature_section(feature_name, commits)
           feature_header_markdown = "*_#{feature_name}_*"
 
@@ -61,12 +51,10 @@ module FeatureMap
           }
         end
 
-        sig { returns(T.nilable(String)) }
         def documentation_site_url
           Private.configuration.documentation_site_url
         end
 
-        sig { returns(T.nilable(String)) }
         def repository_url
           Private.configuration.repository['url']
         end