feature_map 1.1.0

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

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module FeatureMap
+  module Private
+    module AssignmentMappers
+      # Calculate, cache, and return a mapping of file names (relative to the root
+      # of the repository) to a feature name.
+      #
+      # Example:
+      #
+      #   {
+      #     'app/models/company.rb' => Feature.find('Onboarding'),
+      #     ...
+      #   }
+      class FileAnnotations
+        extend T::Sig
+        include Mapper
+
+        # 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_ANNOTATION_PATTERN = T.let(
+          /
+            \s* # Any amount of whitespace
+            (#{Constants::SINGLE_LINE_COMMENT_PATTERNS.join('|')}) # Single line comment start
+            \s* # Any amount of whitespace, not including newlines
+            @feature\s # We find the feature annotation followed by one space
+            (?<feature>.*?$) # A named capture grabs the rest as the feature until the line ends
+          /x.freeze,
+          Regexp
+        )
+        MULTILINE_ANNOTATION_PATTERN = T.let(
+          /
+            (?:#{Constants::MULTILINE_COMMENT_START_PATTERNS.join('|')}) # Any comment start
+            .*? # Followed by any characters, including newlines, until...
+            @feature\s # We find the feature annotation followed by one space
+            (?<feature>.*?$) # A named capture grabs the rest as the feature until the line ends
+          /xm.freeze,
+          Regexp
+        )
+        DESCRIPTION = 'Annotations at the top of file'
+
+        sig do
+          override.params(file: String)
+            .returns(T.nilable(CodeFeatures::Feature))
+        end
+        def map_file_to_feature(file)
+          file_annotation_based_feature(file)
+        end
+
+        sig do
+          override
+            .params(files: T::Array[String])
+            .returns(T::Hash[String, CodeFeatures::Feature])
+        end
+        def globs_to_feature(files)
+          files.each_with_object({}) do |filename_relative_to_root, mapping|
+            feature = file_annotation_based_feature(filename_relative_to_root)
+            next unless feature
+
+            mapping[filename_relative_to_root] = feature
+          end
+        end
+
+        sig do
+          override.params(cache: GlobsToAssignedFeatureMap, files: T::Array[String]).returns(GlobsToAssignedFeatureMap)
+        end
+        def update_cache(cache, files)
+          # We map files to nil features so that files whose annotation have been removed will be properly
+          # overwritten (i.e. removed) from the cache.
+          fileset = Set.new(files)
+          updated_cache_for_files = globs_to_feature(files)
+          cache.merge!(updated_cache_for_files)
+
+          invalid_files = cache.keys.select do |file|
+            # If a file is not tracked, it should be removed from the cache
+            !Private.file_tracked?(file) ||
+              # If a file no longer has a file annotation (i.e. `globs_to_feature` doesn't map it)
+              # it should be removed from the cache
+              # We make sure to only apply this to the input files since otherwise `updated_cache_for_files.key?(file)` would always return `false` when files == []
+              (fileset.include?(file) && !updated_cache_for_files.key?(file))
+          end
+
+          invalid_files.each do |invalid_file|
+            cache.delete(invalid_file)
+          end
+
+          cache
+        end
+
+        sig { params(lines: T::Array[String]).returns(T.nilable(String)) }
+        def identify_feature_from(lines)
+          matched_single_line_feature = lines.join("\n").match(SINGLE_LINE_ANNOTATION_PATTERN)
+          matched_multiline_feature = lines.join("\n").match(MULTILINE_ANNOTATION_PATTERN)
+          matched_feature = matched_single_line_feature || matched_multiline_feature
+          return if matched_feature.nil?
+
+          T.must(matched_feature
+           .values_at(:feature)
+           .first)
+           .gsub(/#{Constants::MULTILINE_COMMENT_END_PATTERNS.join('|')}/, '')
+           .strip
+        rescue ArgumentError => e
+          raise unless e.message.include?('invalid byte sequence')
+        end
+
+        sig { params(filename: String).returns(T.nilable(CodeFeatures::Feature)) }
+        def file_annotation_based_feature(filename)
+          # Not too sure what the following comment means but it was carried over from the code_ownership repo, so
+          # I've opted to leave it unchanged in case it is helpful for future engineers:
+          #   > If for a directory is named with an ownable extension, we need to skip
+          #   > so File.foreach doesn't blow up below. This was needed because Cypress
+          #   > screenshots are saved to a folder with the test suite filename.
+          return if File.directory?(filename)
+          return unless File.file?(filename)
+
+          # The annotation should be on one of the first ten lines.
+          # If the annotation isn't in the first ten lines we assume it
+          # doesn't exist.
+
+          lines = File.foreach(filename).first(10)
+          return if lines.empty?
+
+          feature = identify_feature_from(lines)
+          return unless feature
+
+          Private.find_feature!(
+            feature,
+            filename
+          )
+        end
+
+        sig { params(filename: String).void }
+        def remove_file_annotation!(filename)
+          if file_annotation_based_feature(filename)
+            filepath = Pathname.new(filename)
+            lines = filepath.read.split("\n")
+            new_lines = lines.reject { |line| line[SINGLE_LINE_ANNOTATION_PATTERN] }
+            # We explicitly add a final new line since splitting by new line when reading the file lines
+            # ignores new lines at the ends of files
+            # We also remove leading new lines, since there is after a new line after an annotation
+            new_file_contents = "#{new_lines.join("\n")}\n".gsub(/\A\n+/, '')
+            filepath.write(new_file_contents)
+          end
+        end
+
+        sig { override.returns(String) }
+        def description
+          DESCRIPTION
+        end
+
+        sig { override.void }
+        def bust_caches!; end
+      end
+    end
+  end
+end

data/lib/feature_map/private/assignments_file.rb

@@ -0,0 +1,190 @@
+# 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 assignments.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 AssignmentsFile
+      extend T::Sig
+
+      class FileContentError < StandardError; end
+
+      FILES_KEY = 'files'
+      FILE_FEATURE_KEY = 'feature'
+      FILE_MAPPER_KEY = 'mapper'
+      FEATURES_KEY = 'features'
+      FEATURE_FILES_KEY = 'files'
+
+      FeatureName = T.type_alias { String }
+      FilePath = T.type_alias { String }
+      MapperDescription = T.type_alias { String }
+
+      FileDetails = T.type_alias do
+        T::Hash[
+          String,
+          T.any(FeatureName, MapperDescription)
+        ]
+      end
+
+      FilesContent = T.type_alias do
+        T::Hash[
+          FilePath,
+          FileDetails
+        ]
+      end
+
+      FileList = T.type_alias { T::Array[String] }
+      TeamList = T.type_alias { T::Array[String] }
+
+      FeatureDetails = T.type_alias do
+        T::Hash[
+          String,
+          T.any(FileList, TeamList)
+        ]
+      end
+
+      FeaturesContent = T.type_alias do
+        T::Hash[
+          FeatureName,
+          FeatureDetails
+        ]
+      end
+
+      sig { returns(T::Array[String]) }
+      def self.actual_contents_lines
+        if path.exist?
+          content = path.read
+          lines = path.read.split("\n")
+          if content.end_with?("\n")
+            lines << ''
+          end
+          lines
+        else
+          ['']
+        end
+      end
+
+      sig { returns(T::Array[T.nilable(String)]) }
+      def self.expected_contents_lines
+        cache = Private.glob_cache.raw_cache_contents
+
+        header = <<~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 recommended to commit this file into your source control. It will only change when the
+          # set of files assigned to a feature change, which should be explicitly tracked.
+        HEADER
+
+        files_content = T.let({}, FilesContent)
+        files_by_feature = T.let({}, T::Hash[FeatureName, FileList])
+        features_content = T.let({}, FeaturesContent)
+
+        cache.each do |mapper_description, assignment_map_cache|
+          assignment_map_cache = assignment_map_cache.sort_by do |glob, _feature|
+            glob
+          end
+
+          assignment_map_cache.to_h.each do |path, feature|
+            files_content[path] = T.let({ FILE_FEATURE_KEY => feature.name, FILE_MAPPER_KEY => mapper_description }, FileDetails)
+
+            files_by_feature[feature.name] ||= []
+            T.must(files_by_feature[feature.name]) << path
+          end
+        end
+
+        # Ordering of features in the resulting YAML content is determined by the order in which keys are added to
+        # each hash.
+        CodeFeatures.all.sort_by(&:name).each do |feature|
+          files = files_by_feature[feature.name] || []
+          expanded_files = files.flat_map { |file| Dir.glob(file) }.reject { |path| File.directory?(path) }
+
+          # Exclude features that have no releated files. These features are presumably irrelevant to the current
+          # repo/application.
+          next if expanded_files.empty?
+
+          features_content[feature.name] = T.let({ 'files' => expanded_files.sort }, FeatureDetails)
+
+          if !Private.configuration.skip_code_ownership
+            T.must(features_content[feature.name])['teams'] = expanded_files.map { |file| CodeOwnership.for_file(file)&.name }.compact.uniq.sort
+          end
+        end
+
+        [
+          *header.split("\n"),
+          '', # For line between header and file assignments lines
+          *{ FILES_KEY => files_content, FEATURES_KEY => features_content }.to_yaml.split("\n"),
+          '' # For end-of-file newline
+        ]
+      end
+
+      sig { void }
+      def self.write!
+        FileUtils.mkdir_p(path.dirname) if !path.dirname.exist?
+        path.write(expected_contents_lines.join("\n"))
+      end
+
+      sig { returns(Pathname) }
+      def self.path
+        Pathname.pwd.join('.feature_map/assignments.yml')
+      end
+
+      sig { params(files: T::Array[String]).void }
+      def self.update_cache!(files)
+        cache = Private.glob_cache
+        # Each mapper returns a new copy of the cache subset related to that mapper,
+        # which is then stored back into the cache.
+        Mapper.all.each do |mapper|
+          existing_cache = cache.raw_cache_contents.fetch(mapper.description, {})
+          updated_cache = mapper.update_cache(existing_cache, files)
+          cache.raw_cache_contents[mapper.description] = updated_cache
+        end
+      end
+
+      sig { returns(T::Boolean) }
+      def self.use_features_cache?
+        AssignmentsFile.path.exist? && !Private.configuration.skip_features_validation
+      end
+
+      sig { returns(GlobCache) }
+      def self.to_glob_cache
+        raw_cache_contents = T.let({}, GlobCache::CacheShape)
+        features_by_name = CodeFeatures.all.each_with_object({}) do |feature, map|
+          map[feature.name] = feature
+        end
+        mapper_descriptions = Set.new(Mapper.all.map(&:description))
+
+        features_file_content = YAML.load_file(path)
+        features_file_content[FILES_KEY]&.each do |file_path, file_assignment|
+          next if file_assignment.nil?
+          next if file_assignment[FILE_FEATURE_KEY].nil? || features_by_name[file_assignment[FILE_FEATURE_KEY]].nil?
+          next if file_assignment[FILE_MAPPER_KEY].nil? || !mapper_descriptions.include?(file_assignment[FILE_MAPPER_KEY])
+
+          raw_cache_contents[file_assignment[FILE_MAPPER_KEY]] ||= {}
+          raw_cache_contents.fetch(file_assignment[FILE_MAPPER_KEY])[file_path] = features_by_name[file_assignment[FILE_FEATURE_KEY]]
+        end
+
+        GlobCache.new(raw_cache_contents)
+      end
+
+      sig { returns(FeaturesContent) }
+      def self.load_features!
+        assignments_content = YAML.load_file(path)
+
+        return assignments_content[FEATURES_KEY] if assignments_content.is_a?(Hash) && assignments_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 assignments file found at #{path}. Use `bin/featuremap validate` to generate it and try again."
+      end
+    end
+  end
+end

data/lib/feature_map/private/code_cov.rb

@@ -0,0 +1,96 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'faraday'
+
+module FeatureMap
+  module Private
+    # This class is responsible for all interactions with the CodeCov platform.
+    class CodeCov
+      CODE_COV_API_BASE_URL = 'https://api.codecov.io/api/v2/'
+
+      class ApiError < StandardError; end
+      class ConfigurationError < StandardError; end
+
+      extend T::Sig
+
+      FilePath = T.type_alias { String }
+      CoverageStat = T.type_alias { String }
+
+      Coverage = T.type_alias do
+        T::Hash[
+          CoverageStat,
+          Integer
+        ]
+      end
+
+      TestCoverageStats = T.type_alias do
+        T::Hash[
+          FilePath,
+          Coverage
+        ]
+      end
+
+      sig { params(commit_sha: String, api_token: String).returns(TestCoverageStats) }
+      def self.fetch_coverage_stats(commit_sha, api_token)
+        commit_details_response = fetch_commit_details(commit_sha, api_token)
+        raise ApiError, "Failed to retrieve CodeCov stats for commit #{commit_sha}. Response: #{commit_details_response.status} - #{commit_details_response.body}" unless commit_details_response.success?
+
+        build_coverage_status(commit_details_response.body)
+      end
+
+      sig { params(commit_sha: String, api_token: String).returns(T.untyped) }
+      def self.fetch_commit_details(commit_sha, api_token)
+        conn.get("#{service}/#{owner}/repos/#{repo}/commits/#{commit_sha}",
+                 {},
+                 { 'Authorization' => "Bearer #{api_token}" })
+      end
+
+      sig { params(commit_details: T::Hash[T.untyped, T.untyped]).returns(TestCoverageStats) }
+      def self.build_coverage_status(commit_details)
+        file_coverage_details = commit_details.dig('report', 'files')
+        raise ApiError, 'No file coverage information retruned from CodeCov.' unless file_coverage_details
+
+        file_coverage_details.each_with_object({}) do |file_coverage, coverage_stats|
+          file_path = file_coverage['name']
+          file_coverage_stats = file_coverage['totals']
+
+          next if !file_path || !file_coverage_stats
+
+          coverage_stats[file_path] = {
+            'lines' => file_coverage_stats['lines'],
+            'hits' => file_coverage_stats['hits'],
+            'misses' => file_coverage_stats['misses']
+          }
+        end
+      end
+
+      # TODO: Move these values to config.
+      sig { returns(String) }
+      def self.service
+        Private.configuration.code_cov['service'] ||
+          (raise ConfigurationError, 'Missing CodeCov configuration: service')
+      end
+
+      sig { returns(String) }
+      def self.owner
+        Private.configuration.code_cov['owner'] ||
+          (raise ConfigurationError, 'Missing CodeCov configuration: owner')
+      end
+
+      sig { returns(String) }
+      def self.repo
+        Private.configuration.code_cov['repo'] ||
+          (raise ConfigurationError, 'Missing CodeCov configuration: repo')
+      end
+
+      sig { returns(Faraday::Connection) }
+      def self.conn
+        @conn ||= T.let(Faraday.new(url: CODE_COV_API_BASE_URL) do |f|
+          f.request :json
+          f.response :json
+        end, T.nilable(Faraday::Connection))
+      end
+    end
+  end
+end

data/lib/feature_map/private/cyclomatic_complexity_calculator.rb

@@ -0,0 +1,46 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'parser/current'
+
+module FeatureMap
+  module Private
+    class CyclomaticComplexityCalculator
+      extend T::Sig
+
+      COMPLEXITY_NODES = %i[
+        if case while until for
+        rescue when and or
+      ].freeze
+
+      sig { params(ast: T.nilable(Parser::AST::Node)).void }
+      def initialize(ast)
+        @ast = ast
+        @complexity = T.let(1, Integer) # Start at 1 for the base path
+      end
+
+      sig { returns(Integer) }
+      def calculate
+        process(@ast)
+        @complexity
+      end
+
+      private
+
+      sig { params(node: T.nilable(T.any(Parser::AST::Node, Symbol, Integer, String, NilClass))).void }
+      def process(node)
+        return unless node.is_a?(Parser::AST::Node)
+
+        # Increment complexity for each branching node
+        @complexity += 1 if COMPLEXITY_NODES.include?(node.type)
+
+        # Process children
+        node.children.each do |child|
+          # Nodes can have children that are Symbols, Integers, Strings, or nil
+          # We only want to process actual AST nodes
+          process(child) if child.is_a?(Parser::AST::Node)
+        end
+      end
+    end
+  end
+end