feature_map 1.1.0

data/lib/feature_map/private/documentation_site.rb

@@ -0,0 +1,128 @@
+# typed: strict
+# frozen_string_literal: true
+
+module FeatureMap
+  module Private
+    #
+    # This class is responsible for generating a standalone site that provides documentation of the features
+    # defined within a given application. This site consists of precompiled HTML, JS, and CSS content that
+    # is combined with a JSON file containing the assignment and metrics information about all application
+    # features.
+    #
+    # The code within the `docs` directory is directly copied into an output directory and combined
+    # with a single `feature-map-config.js` file containing content like the following:
+    #   ```
+    #   window.FEATURE_MAP_CONFIG = {
+    #     environment: {
+    #       "git_ref": "https://github.com/REPO/blob/GIT_SHA"
+    #     },
+    #     features: {
+    #       "Foo": {
+    #         "description": "The Foo feature with this sample application.",
+    #         "dashboard_link": "https://example.com/dashbords/foo",
+    #         "documentation_link": "https://example.com/docs/foo",
+    #         "assignments": {
+    #           "files": ["app/jobs/foo_job.rb", "app/lib/foo_service.rb"],
+    #           "teams": ["team_a", "team_b"]
+    #         },
+    #         "metrics": {
+    #           "abc_size": 12.34,
+    #           "lines_of_code": 56,
+    #           "cyclomatic_complexity": 7
+    #         },
+    #         "test_pyramid": {
+    #           "unit_count": 100,
+    #           "unit_pending": 12,
+    #           "integration_count": 15,
+    #           "integration_pending": 2,
+    #           "regression_count": 6,
+    #           "regression_pending": 0,
+    #         }
+    #       },
+    #       "Bar": {
+    #         "description": "Another feature within the application.",
+    #         "dashboard_link": "https://example.com/docs/bar",
+    #         "documentation_link": "https://example.com/dashbords/bar",
+    #         "assignments":{
+    #           "files": ["app/controllers/bar_controller.rb", "app/lib/bar_service.rb"],
+    #           "teams": ["team_a"]
+    #         },
+    #         "metrics": {
+    #           "abc_size": 98.76,
+    #           "lines_of_code": 54,
+    #           "cyclomatic_complexity": 32
+    #         },
+    #         "test_pyramid": null
+    #       }
+    #     },
+    #     project: {
+    #       ...values from ./feature_map/config.yml
+    #     }
+    #   };
+    #   ```
+    # 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,
+          project_configuration: T::Hash[T.untyped, T.untyped],
+          git_ref: String
+        ).void
+      end
+      def self.generate(
+        feature_assignments,
+        feature_metrics,
+        feature_test_coverage,
+        feature_test_pyramid,
+        project_configuration,
+        git_ref
+      )
+        FileUtils.mkdir_p(output_directory) if !output_directory.exist?
+
+        features = feature_assignments.keys.each_with_object({}) do |feature_name, hash|
+          feature_definition = CodeFeatures.find(feature_name)
+          hash[feature_name] = feature_definition&.raw_hash&.slice(*FETAURE_DEFINITION_KEYS_TO_INCLUDE) || {}
+          hash[feature_name].merge!(
+            assignments: feature_assignments[feature_name],
+            metrics: feature_metrics[feature_name],
+            test_coverage: feature_test_coverage[feature_name],
+            test_pyramid: feature_test_pyramid[feature_name]
+          )
+        end
+
+        environment = {
+          git_ref: git_ref
+        }
+        feature_map_config = {
+          features: features,
+          environment: environment,
+          project: project_configuration
+        }.to_json
+        output_directory.join('feature-map-config.js').write("window.FEATURE_MAP_CONFIG = #{feature_map_config};")
+
+        Dir.each_child(assets_directory) do |file_name|
+          FileUtils.cp(File.join(assets_directory, file_name), output_directory.join(file_name))
+        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
+    end
+  end
+end

data/lib/feature_map/private/extension_loader.rb

@@ -0,0 +1,24 @@
+# typed: strict
+# frozen_string_literal: true
+
+module FeatureMap
+  module Private
+    # This class handles loading extensions to feature_map using the `require` directive
+    # 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
+          if require_directive.start_with?('.')
+            require File.join(Pathname.pwd, require_directive)
+          else
+            require require_directive
+          end
+        end
+      end
+    end
+  end
+end

data/lib/feature_map/private/feature_assigner.rb

@@ -0,0 +1,22 @@
+# 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
+          # such as `app/services/[test]/some_other_file.ts`
+          mapping[glob] = feature if File.exist?(glob)
+          Dir.glob(glob).each do |file|
+            mapping[file] ||= feature
+          end
+        end
+      end
+    end
+  end
+end

data/lib/feature_map/private/feature_metrics_calculator.rb

@@ -0,0 +1,76 @@
+# 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'
+      TODO_LOCATIONS_METRIC = 'todo_locations'
+
+      SUPPORTED_METRICS = T.let([
+        ABC_SIZE_METRIC,
+        CYCLOMATIC_COMPLEXITY_METRIC,
+        LINES_OF_CODE_METRIC,
+        TODO_LOCATIONS_METRIC
+      ].freeze, T::Array[String])
+
+      FeatureMetrics = T.type_alias do
+        T::Hash[
+          String, # metric name
+          T.any(Integer, Float, T::Hash[String, String]) # score or todo locations with messages
+        ]
+      end
+
+      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) }
+
+        # Handle numeric metrics
+        aggregate_metrics = SUPPORTED_METRICS.each_with_object({}) do |metric_key, agg|
+          next if metric_key == TODO_LOCATIONS_METRIC
+
+          agg[metric_key] = metrics.sum { |m| m[metric_key] || 0 }
+        end
+
+        # Merge all todo locations
+        todo_locations = metrics.map { |m| m[TODO_LOCATIONS_METRIC] }.compact.reduce({}, :merge)
+        aggregate_metrics[TODO_LOCATIONS_METRIC] = todo_locations
+
+        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
+        }
+
+        return metrics unless file_path.end_with?('.rb')
+
+        file_content = File.read(file_path)
+        source = RuboCop::ProcessedSource.new(file_content, RUBY_VERSION.to_f)
+        return metrics unless source.ast
+
+        # NOTE: We're using some internal RuboCop classes to calculate complexity metrics
+        # for each file. Doing this tightly couples our functionality with RuboCop,
+        # which does introduce some risk, should RuboCop decide to change the interface
+        # of these classes. That being said, this is a tradeoff we're willing to
+        # make right now.
+        abc_calculator = RuboCop::Cop::Metrics::Utils::AbcSizeCalculator.new(source.ast)
+        cyclomatic_calculator = CyclomaticComplexityCalculator.new(source.ast)
+        todo_locations = TodoInspector.new(file_path).calculate
+
+        metrics.merge(
+          ABC_SIZE_METRIC => abc_calculator.calculate.first.round(2),
+          CYCLOMATIC_COMPLEXITY_METRIC => cyclomatic_calculator.calculate,
+          TODO_LOCATIONS_METRIC => todo_locations
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# 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
+      end
+    end
+  end
+end

data/lib/feature_map/private/glob_cache.rb

@@ -0,0 +1,80 @@
+# 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]
+          end
+        end
+
+        files_by_mappers
+      end
+
+      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|
+            expanded_cache[mapper_description] = FeatureAssigner.assign_features(globs_by_feature)
+          end
+          expanded_cache
+        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)
+          expanded_cache.each do |mapper_description, file_by_feature|
+            file_by_feature.each_key do |file|
+              files_by_mappers[file] ||= Set.new([])
+              files_by_mappers.fetch(file) << mapper_description
+            end
+          end
+
+          files_by_mappers
+        end
+      end
+    end
+  end
+end

data/lib/feature_map/private/lines_of_code_calculator.rb

@@ -0,0 +1,49 @@
+# typed: strict
+# frozen_string_literal: true
+
+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
+      )
+
+      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
+          .readlines(@file_path)
+          .join("\n")
+          .gsub(SINGLE_LINE_COMMENT_PATTERN, '')
+          .gsub(MULTI_LINE_COMMENT_PATTERN, '')
+          .split("\n")
+          .reject { |l| l.strip == '' }
+          .size
+      end
+    end
+  end
+end

data/lib/feature_map/private/metrics_file.rb

@@ -0,0 +1,86 @@
+# typed: strict
+# frozen_string_literal: true
+
+module FeatureMap
+  module Private
+    #
+    # This class is responsible for turning FeatureMap directives (e.g. annotations, directory assignments, etc)
+    # into a metrics.yml file, that can be used as an input to a variety of engineering team utilities (e.g.
+    # 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, 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
+          # This file was automatically generated by "bin/featuremap validate". 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 as a
+          # result of nearly all other source code changes. This file should be ignored by your source
+          # control but can be used for other feature analysis operations (e.g. documentation
+          # generation, etc).
+        HEADER
+      end
+
+      sig { returns(T::Hash[String, FeaturesContent]) }
+      def self.generate_content
+        feature_metrics = T.let({}, FeaturesContent)
+
+        Private.feature_file_assignments.each do |feature_name, files|
+          feature_metrics[feature_name] = FeatureMetricsCalculator.calculate_for_feature(files)
+        end
+
+        { FEATURES_KEY => feature_metrics }
+      end
+
+      sig { returns(FeaturesContent) }
+      def self.load_features!
+        metrics_content = YAML.load_file(path)
+
+        return metrics_content[FEATURES_KEY] if metrics_content.is_a?(Hash) && metrics_content[FEATURES_KEY]
+
+        raise FileContentError, "Unexpected content found in #{path}. Use `bin/featuremap validate` to regenerate it and try again."
+      rescue Psych::SyntaxError => e
+        raise FileContentError, "Invalid YAML content found at #{path}. Error: #{e.message} Use `bin/featuremap validate` to generate it and try again."
+      rescue Errno::ENOENT
+        raise FileContentError, "No feature metrics file found at #{path}. Use `bin/featuremap validate` to generate it and try again."
+      end
+    end
+  end
+end

data/lib/feature_map/private/test_coverage_file.rb

@@ -0,0 +1,97 @@
+# typed: strict
+# frozen_string_literal: true
+
+module FeatureMap
+  module Private
+    #
+    # This class is responsible for compiling a set of file-level test coverage statistics into a test-coverage.yml
+    # file that captures test coverage statistics on a per-feature basis. 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 TestCoverageFile
+      extend T::Sig
+
+      class FileContentError < StandardError; end
+
+      FEATURES_KEY = 'features'
+
+      FeatureName = T.type_alias { String }
+      CoverageStat = T.type_alias { String }
+
+      FeatureCoverage = T.type_alias do
+        T::Hash[
+          CoverageStat,
+          Integer
+        ]
+      end
+
+      FeaturesContent = T.type_alias do
+        T::Hash[
+          FeatureName,
+          FeatureCoverage
+        ]
+      end
+
+      sig { params(coverage_stats: CodeCov::TestCoverageStats).void }
+      def self.write!(coverage_stats)
+        FileUtils.mkdir_p(path.dirname) if !path.dirname.exist?
+
+        path.write([header_comment, "\n", generate_content(coverage_stats).to_yaml].join)
+      end
+
+      sig { returns(Pathname) }
+      def self.path
+        Pathname.pwd.join('.feature_map/test-coverage.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_coverage". 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 coverage 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 { params(coverage_stats: CodeCov::TestCoverageStats).returns(T::Hash[String, FeaturesContent]) }
+      def self.generate_content(coverage_stats)
+        feature_test_coverage = T.let({}, FeaturesContent)
+
+        Private.feature_file_assignments.each do |feature_name, files|
+          feature_test_coverage[feature_name] = T.let({ 'lines' => 0, 'hits' => 0, 'misses' => 0 }, FeatureCoverage)
+
+          files.each_with_object(T.must(feature_test_coverage[feature_name])) do |file_path, coverage|
+            next unless coverage_stats[file_path]
+
+            coverage['lines'] = T.must(coverage['lines']) + (T.must(coverage_stats[file_path])['lines'] || 0)
+            coverage['hits'] = T.must(coverage['hits']) + (T.must(coverage_stats[file_path])['hits'] || 0)
+            coverage['misses'] = T.must(coverage['misses']) + (T.must(coverage_stats[file_path])['misses'] || 0)
+
+            coverage
+          end
+        end
+
+        { FEATURES_KEY => feature_test_coverage }
+      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
+    end
+  end
+end