feature_map 1.2.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d557f6ea527d73672a53ea6a279e8574a0157d03ffe5da289cc12aa05fec2d3
-  data.tar.gz: 0b5d04be8cfd69f16d8f5ffc8e1ef0b4c7e5fa8de276feb3c776c7d733cce758
+  metadata.gz: 278f81ac986fb56714e9159ff94e5cb98c1bbca774486735c32cd837db13965d
+  data.tar.gz: 73b6c34564934df5f1febbfd7e5ec57d97142f4ff624b38294eed829090739c0
 SHA512:
-  metadata.gz: 5fa1edc5ba79772619aec3f730147ccffa37a19cc889959192086469757522d72f4c635fa67cb815237c9b0a8e71557c2fb52948e9f9db63b4c1f4338f0ca316
-  data.tar.gz: 7d75f638f6d06921b146d81a590bebb72e9db3ed1229bf833781aca68b9e92a274fb016190af9884ba8800c6ca982945a370634e73af3b9171b0c873c73cfcdc
+  metadata.gz: 5e4cd3dad27e16983f4cd4470c1d7c0f65dffbc630d4155cbf8994869a52469c7455d015066be951d0f6e39929277f17d68bfc254c42f6227d1446f060a27371
+  data.tar.gz: 531ed4a45bea00c64ff62733167fd6ea3d9f8f16342ce9f881e75ba935970a299204587bc18e38ec52cc20517595e7e79fc58a5a988a1e8857337a788b718c11

data/README.md

@@ -1,250 +1,32 @@
 # FeatureMap
 
-This gem helps identify and manage features within large Ruby and Rails applications. This gem works best in large, usually monolithic code bases for applications that incorporate a wide range of features with various dependencies.
+This gem helps identify and manage features within large applications.
 
-## Getting started
+For usage documentation, please see the [README Site](https://beyond-finance.github.io/feature_map).
 
-To get started there's a few things you should do.
+## Installation
 
-1) Create a `.feature_map/config.yml` file and declare where your files live. Here's a sample to start with:
-    ```yml
-    assigned_globs:
-      - '{app,components,config,frontend,lib,packs,spec}/**/*.{rb,rake,js,jsx,ts,tsx}'
-    unassigned_globs:
-      - db/**/*
-      - app/services/some_file1.rb
-      - app/services/some_file2.rb
-      - frontend/javascripts/**/__generated__/**/*
-    ```
-    You may find a more comprehensive example in this repository's `.feature_map/config.yml`.
+FeatureMap may be installed directly into a Ruby environment or Ruby on Rails application from [RubyGems](https://rubygems.org/gems/feature_map).
 
-2) Define the features of our your application. There are two methods for defining features:
-    * YAML Definitions: Each feature can be defined in a separate YAML file within the `.feature_map/definitions` directory. Here's an example, that would live at `.feature_map/definitions/onboarding.yml`:
-        ```yml
-        name: Onboarding
-        description: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation.
-        documentation_link: https://www.notion.so/onboarding-feature-abcd1234
-        ```
-    * CSV Definitions: All features can be defined within a single CSV file located at `.feature_map/feature_definitions.csv`. Here's an example of what that file might look like:
-        ```
-        # Comment explaining the purpose of this file and how it should be managed.
+\
+**Global Installation**
+> `gem install feature_map`
 
-        Name,Description,Documentation Link,Custom Attribute
-        Onboarding,"Lorem ipsum dolor sit amet, consectetur adipiscing elit.",https://www.notion.so/onboarding-feature-abcd1234,Test 123
-        User Management,"Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation",,
-        ``` 
-3) Declare feature assignments. You can do this at a directory level or at a file level. All of the files within the `assigned_globs` you declared in step 1 will need to have a feature assigned (or be opted out via `unassigned_globs`). See the next section for more detail.
-4) Run validations when you commit, and/or in CI. If you run validations in CI, ensure that if your `assignments.yml` file gets changed, that gets pushed to the PR. A `metrics.yml` file will also be generated but we recommend NOT commiting that file because it changes very frequently.
+**Gemfile**
+> `gem 'feature_map', '~> 1.2'``
 
-## Usage: Assigning Features
+**Inline**\
+FeatureMap may also be executed without direct installation via [inline bundling](https://bundler.io/guides/bundler_in_a_single_file_ruby_script.html).  For more information see [Inline Execution]({{ '/getting-started/inline-execution' | relative_url }}).
 
-There are multiple ways to assign the feature for a source file using this gem.
-
-### Directory-Based Assignment
-Directory based assignment allows for all files in that directory and all its sub-directories to be assigned to a single feature. To define this, add a `.feature` file inside that directory with the name of the feature as the contents of that file.
-
-### File-Annotation Based Assignment
-File annotations are a last resort if there is no clear home for your code. File annotations go at the top of your file, and look like this:
-```ruby
-# @feature Onboarding
-```
-
-### Glob-Based Assignment
-In the YML configuration of a feature, you can set `assigned_globs` to be a glob of files assigned to this feature. For example, in `onboarding.yml`:
-```yml
-name: Onboarding
-assigned_globs:
-  - app/services/stuff_for_onboarding/**/**
-  - app/controllers/other_stuff_for_onboarding/**/**
-```
-
-### Feature Definition File Assignment
-By default any feature definition YML files, located in the `.feature_map/definitions' directory, are assigned to their corresponding feature.
-
-The leading `.` in the path for these files results in them being quoted within the resulting `.feature_map/assignments` file. The following is an example of this content:
-```yml
----
-files:
-  ".feature_map/definitions/bar.yml":
-    feature: Bar
-    mapper: Feature definition file assignment
-features:
-  Bar:
-  - ".feature_map/definitions/bar.yml"
-```
-
-In cases when the feature assignments for these files is irrelevant, this behavior can be disabled by setting the `ignore_feature_definitions` key in the `.feature_map/config.yml` file to `true`.
-
-### Custom Assignment
-To enable custom assignment, you can inject your own custom classes into `feature_map`.
-To do this, first create a class that adheres to the `FeatureMap::Mapper` and/or `FeatureMap::Validator` interface.
-Then, in `.feature_map/config.yml`, you can require that file:
-```yml
-require:
-  - ./lib/my_extension.rb
-```
-
-Now, `bin/featuremap validate` will automatically include your new mapper and/or validator. See [`spec/lib/feature_map/private/extension_loader_spec.rb](spec/lib/feature_map/private/extension_loader_spec.rb) for an example of what this looks like.
-
-## Usage: Reading FeatureMap
+## FeatureMap Gem Structure
 
 Check out [`lib/feature_map.rb`](https://github.com/Beyond-Finance/feature_map/blob/main/lib/feature_map.rb) to see the public API.
 
 Check out [`feature_map_spec.rb`](https://github.com/Beyond-Finance/feature_map/blob/main/spec/lib/feature_map_spec.rb) to see examples of how the feature map utility is used.
 
-### `for_file`
-`FeatureMap.for_file`, given a relative path to a file returns a `CodeFeatures::Feature` if there is a feature assigned to the file, `nil` otherwise.
-
-```ruby
-FeatureMap.for_file('path/to/file/relative/to/application/root.rb')
-```
-
-Contributor note: If you are making updates to this method or the methods getting used here, please benchmark the performance of the new implementation against the current for both `for_files` and `for_file` (with 1, 100, 1000 files).
-
-See `feature_map_spec.rb` for examples.
-
-### `for_backtrace`
-`FeatureMap.for_backtrace` can be given a backtrace and will either return `nil`, or a `CodeFeatures::Feature`.
-
-```ruby
-FeatureMap.for_backtrace(exception.backtrace)
-```
-
-This will go through the backtrace, and return the feature of the first files with a feature assignment associated with frames within the backtrace.
-
-See `feature_map_spec.rb` for an example.
-
-### `for_class`
-
-`FeatureMap.for_class` can be given a class and will either return `nil`, or a `CodeFeatures::Feature`.
-
-```ruby
-FeatureMap.for_class(MyClass)
-```
-
-Under the hood, this finds the file where the class is defined and returns the featuer assigned to that file.
-
-See `feature_map_spec.rb` for an example.
-
-### `for_feature`
-`FeatureMap.for_feature` can be used to generate a feature report for a single feature.
-```ruby
-FeatureMap.for_feature('Onboarding')
-```
-
-You can shovel this into a markdown file for easy viewing using the CLI:
-```
-bin/feature_map for_feature 'Onboarding' > tmp/onboarding_feature_report.md
-```
-
-## Usage: Generating Feature Assignment files
-
-When you run `bin/featuremap validate`, the following files will automatically be generated:
- * `.feature_map/assignments.yml`: Captures a mapping of files within a repository to their corresponding feature and a mapping of features to their corresponding files.
- * `.feature_map/metrics.yml`: Captures a set of metrics rolled up at the feature level (i.e. computed over all files assigned to the feature).
-
-## Usage: Generating Documentation
-
-The feature map gem captures valuable insights about the features of your application (e.g. metrics like ABC size, lines of code, and cyclomatic complexity). To review this information locally, you can run `bin/featuremap docs` to produce a single, self contained HTML file that includes a fully functional documentation site with useful diagrams and details about the features of your application. This file is created within the `.feature_map/docs` directory and the `index.html` file can loaded in the browser of your choice by running `open .feature_map/docs/index.html`.
-
-**Example screenshot**
-![Feature Map Docs Dashboard](readme_assets/feature-map-docs-dashboard.png)
-
-## Usage: Generating the Test Pyramid
-
-The feature map gem supports reporting on the [test pyramid](https://martinfowler.com/bliki/TestPyramid.html) coverage of the application and its constituent features.  It works, broadly, by:  accepting test execution reports (e.g., rspec's `json` format) for unit, integration, and regression tests -- and then matches those tests to their corresponding features as follows:
-  - Unit:  Uses tech stack conventions, e.g., rspec tests in `spec/models/user_spec.rb` are resolved to the `app/models/user.rb` implementation file, which may be matched with its feature annotation.
-  - Integration:  Integration tests do not correspond to a single implementation file (though generally live within the same codebase), so they must be directly annotated with the feature they support.
-  - Regression:  Regression tests do not correspond to a single implementation file, and may live in a given codebase or in a separate repository.  They must both be tagged with the feature that they support, and a reference to the assignments of regression tests must be passed to the test pyramid generation command.
-
-Once test pyramid data has been generated for a give project, it's automatically included in that project's doc site.
-
-To generate the test pyramid data, run:
-> bin/featuremap test_pyramid [unit_examples_file] [integration_examples_file] [regression_examples_file] [regression_assignments_file]
-
-Note:  FeatureMap currently only supports _examples files_ in rspec's `json` format (--format json), though support for others (e.g., jest's `--json`, or the JUnit XML format) may be added in the future.
-
-## Usage: Collecting Test Coverage
-
-When you run `bin/featuremap test_coverage`, the test coverage statistics the latest commit on the main branch will be pulled from [CodeCov](https://codecov.io/) and collected into a set of per-feature test coverage statistics. This feature level test coverage data is then captured in the `.feature_map/test-coverage.yml` file.
-
-This command requires the following CodeCov account settings to be configured within the `.feature_map/config.yml` file:
-
-```yml
-code_cov:
-  service: github
-  owner: Acme-Org
-  repo: sample_app
-```
-
-See the [CodeCov API docs](https://docs.codecov.com/reference/repos_retrieve) for more information about the expected values for these configurations.
-
-Test coverage statistics can be pulled for a specific commit (e.g. the latest commit on a feature branch) by including the full commit SHA as an argument at the end of this CLI command (e.g. `bin/featuremap test_coverage ae80a927654997be4f48d3dbcd1320083cf22eea`). Before running this command please check the [CodeCov dashboard](https://app.codecov.io/) for your application to ensure test coverage statistics have been reported for this commit.
-
-### CodeCov API Token Generation
-
-Running the `bin/featuremap test_coverage` requires an active CodeCov API access token to be specified in the `CODECOV_API_TOKEN` environment variable of your shell session. This token is used to retrieve coverage statistics from the CodeCov account configured in the `.feature_map/config.yml` file.
-
-Use the following steps to generate a new CodeCov API token:
-
-1. Log into your [CodeCov account](https://app.codecov.io/)
-1. Click the "Settings" menu option in the profile dropdown menu in the top right corner of the screen
-    ![CodeCov profile menu with Settings menu highlighted](readme_assets/codeCov-profileMenu.png)
-1. Click the "Access" menu option from the left-hand navigation menu of the Settings page
-    ![CodeCov Settings page navigation bar with Access menu highlighted](readme_assets/codeCov-settingsMenu.png)
-1. Click the "Generate Token" button in the "API Tokens" section of the page
-    ![CodeCov Access page with Generate Token button highlighted](readme_assets/codeCov-apiTokensTable.png)
-1. Enter a descriptive name for the token (e.g. FeatureMap CLI) and click the "Generate Token" button
-    ![CodeCov API token creation modal](readme_assets/codeCov-createTokenModal.png)
-1. __IMPORTANT__: Copy the access token value presented on the screen and store it in a secure location (e.g. 1Password entry, BitWarden entry, etc)
-    ![CodeCov newly created API token modal](readme_assets/codeCov-newTokenModal.png)
-
-#### __OPTIONAL__:  Store the token as an environment variable in your shell's environment:
-**ZSH**
-  ```shell
-  echo 'export CODECOV_API_TOKEN="YOUR_CODECOV_API_TOKEN"' >> ~/.zshrc
-  source ~/.zshrc
-  ```
-
-**Bash**
-  ```shell
-  echo 'export CODECOV_API_TOKEN="YOUR_CODECOV_API_TOKEN"' >> ~/.bashrc
-  source ~/.bashrc
-  ```
-
-## Proper Configuration & Validation
-
-FeatureMap comes with a validation function to ensure the following things are true:
-
-1) Only one mechanism is defining the feature assignment for a file. That is -- you can't have a file annotation on a file assigned via glob-based assignment. This helps make feature assignment behavior more clear by avoiding concerns about precedence.
-2) All features referenced as an assignment for any file is a valid feature (i.e. it's in the list of `CodeFeatures.all`).
-3) All files have a feature assigned. You can specify in `unassigned_globs` to represent a TODO list of files to add feature assignments to.
-    * Teams using the [CodeOwnership](https://github.com/rubyatscale/code_ownership/tree/main) gem include a `require_assignment_for_teams` key in the `.feature_map/config.yml` file to have this validation to apply a specific list of team. This allows feature assignments to be rolled out in a gradual manner on a team-by-team basis. The `require_assignment_for_teams` configuration should contain a list of team names (i.e. the value from the `name` key in the associated `config/teams/*.yml` file) for the teams whose files will be included in this validation.
-3) The `assignments.yml` file is up to date. This is automatically corrected and staged unless specified otherwise with `bin/featuremap validate --skip-autocorrect --skip-stage`. You can turn this validation off by setting `skip_features_validation: true` in `.feature_map/config.yml`.
-
-FeatureMap also allows you to specify which globs and file extensions should be considered assignable.
-
-Here is an example `.feature_map/config.yml`.
-```yml
-assigned_globs:
-  - '{app,components,config,frontend,lib,packs,spec}/**/*.{rb,rake,js,jsx,ts,tsx}'
-unassigned_globs:
-  - db/**/*
-  - app/services/some_file1.rb
-  - app/services/some_file2.rb
-  - frontend/javascripts/**/__generated__/**/*
-```
-You can call the validation function with the Ruby API
-```ruby
-FeatureMap.validate!
-```
-or the CLI
-```
-bin/featuremap validate
-```
-
 ## Development
 
+### Ruby Gem
 Contributions are welcome and appreciated. Here's how to get started:
 
 - clone repo: `$ git clone git@github.com:Beyond-Finance/feature_map.git`
@@ -255,7 +37,21 @@ Contributions are welcome and appreciated. Here's how to get started:
 
 That's it! Assuming you can complete all of these steps without any error or issues, you should be good to go.
 
-#### Publication
+### Documentation Site
+
+The documentation site is a React application which is built on the Vite framework.  There are two steps to building the site:  first, the skeleton of the site is compiled and committed into this repository; second, the various artifacts are injected from a host repository into a project-specific instance of the site via [bin/featuremap docs](https://beyond-finance.github.io/feature_map/public-interface/docs).
+
+Compilation of the build asset is done via `npm run build` from within the [docs](./docs) folder.  This compiles the React app into a single static file which is placed in [./lib/feature_map/private/docs/index.html](./lib/feature_map/private/docs/index.html]).
+
+The documentation site may be run locally to aid in development via `bin/docs`.  It uses sample data found in [docs/src/data/sample_config.js](./docs/src/data/sample_config.js).
+
+More information on the development of the documentation site may be found in the [Docs Readme](./docs/README.md).
+
+### README Site
+
+The README site is built with Jekyll and TailwindCSS and is hosted via GitHub Pages at:  https://beyond-finance.github.io/feature_map.  It can be run locally to aid in development via `bin/readme`.
+
+### Publication
 
 When a new version of the gem is ready to be published, please follow these steps:
 
@@ -267,3 +63,9 @@ When a new version of the gem is ready to be published, please follow these step
    * Build a new version of the gem: `gem build feature_map.gemspec`
    * Authenticate with rubygems.org: `gem signin`
    * Publish the new version of the gem: `gem push feature_map-[NEW_VERSION].gem`
+
+## Colophon
+
+The structure and execution of FeatureMap's initial version was based on the gem [CodeOwnership](https://github.com/rubyatscale/code_ownership).
+
+The structure and styling of the README site was based on a theme from [Spinal](https://spinalcms.com/resources/documentation-theme-built-with-tailwind-css/).

data/bin/docs

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+
+if ! gem list foreman -i --silent; then
+  echo "Installing foreman..."
+  gem install foreman
+fi
+
+cd docs && npm install && cd ..
+exec foreman start -f Procfile.docs "$@"

data/bin/readme

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+
+if ! gem list foreman -i --silent; then
+  echo "Installing foreman..."
+  gem install foreman
+fi
+
+cp ./lib/feature_map/private/docs/index.html ./readme/example-docs-site.html
+exec foreman start -f Procfile.readme "$@"

data/lib/feature_map/cli.rb

@@ -19,6 +19,8 @@ module FeatureMap
         test_coverage!(argv)
       elsif command == 'test_pyramid'
         test_pyramid!(argv)
+      elsif command == 'additional_metrics'
+        additional_metrics!(argv)
       elsif command == 'for_file'
         for_file(argv)
       elsif command == 'for_feature'
@@ -34,6 +36,7 @@ module FeatureMap
             for_file - find feature assignment for a single file
             test_coverage - generates per-feature test coverage statistics
             test_pyramid - generates per-feature test pyramid (unit, integration, regression) statistics
+            additional_metrics - generates additional metrics per-feature (e.g. health score)
             validate - run all validations
 
             ##################################################
@@ -126,6 +129,10 @@ module FeatureMap
           options[:skip_validate] = true
         end
 
+        opts.on('--skip-additional-metrics', 'Skip the execution of the additional_metrics command, using the existing feature output files') do
+          options[:skip_additional_metrics] = true
+        end
+
         opts.on('--help', 'Shows this prompt') do
           puts opts
           exit
@@ -138,6 +145,7 @@ module FeatureMap
       custom_git_ref = non_flag_args[0]
 
       FeatureMap.validate!(stage_changes: !options[:skip_stage]) unless options[:skip_validate]
+      FeatureMap.generate_additional_metrics! unless options[:skip_additional_metrics]
 
       FeatureMap.generate_docs!(custom_git_ref)
 
@@ -199,6 +207,24 @@ module FeatureMap
       FeatureMap.generate_test_pyramid!(unit_path, integration_path, regression_path, regression_assignments_path)
     end
 
+    def self.additional_metrics!(argv)
+      parser = OptionParser.new do |opts|
+        opts.banner = <<~MSG
+          Usage: bin/featuremap additional_metrics
+          Should be run after metrics and test coverage files have been generated
+        MSG
+
+        opts.on('--help', 'Shows this prompt') do
+          puts opts
+          exit
+        end
+      end
+      args = parser.order!(argv)
+      parser.parse!(args)
+
+      FeatureMap.generate_additional_metrics!
+    end
+
     # For now, this just returns feature assignment
     # Later, this could also return feature assignment errors about that file.
     def self.for_file(argv)

data/lib/feature_map/private/additional_metrics_file.rb

@@ -0,0 +1,161 @@
+# typed: strict
+# frozen_string_literal: true
+
+module FeatureMap
+  module Private
+    class AdditionalMetricsFile
+      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 { params(metrics: T::Hash[String, T.untyped], test_coverage: T::Hash[String, T.untyped], health_config: T::Hash[String, T.untyped]).void }
+      def self.write!(metrics, test_coverage, health_config)
+        FileUtils.mkdir_p(path.dirname) if !path.dirname.exist?
+
+        path.write([header_comment, "\n", generate_content(metrics, test_coverage, health_config).to_yaml].join)
+      end
+
+      sig { returns(Pathname) }
+      def self.path
+        Pathname.pwd.join('.feature_map/additional-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 additional_metrics". 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 { params(feature_metrics: T::Hash[String, T.untyped], feature_test_coverage: T::Hash[String, T.untyped], health_config: T::Hash[String, T.untyped]).returns(T::Hash[String, FeaturesContent]) }
+      def self.generate_content(feature_metrics, feature_test_coverage, health_config)
+        feature_additional_metrics = T.let({}, FeaturesContent)
+
+        cyclomatic_complexity_ratios = feature_metrics.map { |_k, m| m[FeatureMetricsCalculator::COMPLEXITY_RATIO_METRIC] }.compact
+        encapsulation_ratios = feature_metrics.map { |_k, m| m[FeatureMetricsCalculator::ENCAPSULATION_RATIO_METRIC] }.compact
+        feature_sizes = feature_metrics.map { |_k, m| m[FeatureMetricsCalculator::LINES_OF_CODE_METRIC] }.compact
+        test_coverage_ratios = feature_test_coverage.map { |_k, c| c[TestCoverageFile::COVERAGE_RATIO] }.compact
+
+        Private.feature_file_assignments.each_key do |feature_name|
+          cyclomatic_complexity = calculate(cyclomatic_complexity_ratios, feature_metrics.dig(feature_name, FeatureMetricsCalculator::COMPLEXITY_RATIO_METRIC) || 0)
+          encapsulation = calculate(encapsulation_ratios, feature_metrics.dig(feature_name, FeatureMetricsCalculator::ENCAPSULATION_RATIO_METRIC) || 0)
+          feature_size = calculate(feature_sizes, feature_metrics.dig(feature_name, FeatureMetricsCalculator::LINES_OF_CODE_METRIC) || 0)
+          test_coverage = calculate(test_coverage_ratios, feature_test_coverage.dig(feature_name, TestCoverageFile::COVERAGE_RATIO) || 0)
+          health = health_score_for(cyclomatic_complexity, encapsulation, test_coverage, health_config)
+
+          feature_additional_metrics[feature_name] = {
+            'cyclomatic_complexity' => cyclomatic_complexity,
+            'encapsulation' => encapsulation,
+            'feature_size' => feature_size,
+            'test_coverage' => test_coverage,
+            'health' => health
+          }
+        end
+
+        { FEATURES_KEY => feature_additional_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 additional_metrics` to regenerate it and try again."
+      rescue Psych::SyntaxError => e
+        raise FileContentError, "Invalid YAML content found at #{path}. Error: #{e.message} Use `bin/featuremap additional_metrics` to generate it and try again."
+      rescue Errno::ENOENT
+        raise FileContentError, "No feature metrics file found at #{path}. Use `bin/featuremap additional_metrics` to generate it and try again."
+      end
+
+      sig { params(collection: T::Array[T.any(Integer, Float)], score: T.any(Integer, Float)).returns({ 'percentile' => Float, 'percent_of_max' => Integer, 'score' => T.any(Integer, Float) }) }
+      def self.calculate(collection, score)
+        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
+
+      sig { params(arr: T::Array[T.any(Integer, Float)], val: T.any(Integer, Float)).returns(Float) }
+      def self.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
+
+      sig { params(awardable_points: Integer, score: T.any(Float, Integer), score_threshold: Integer, percent_of_max: T.nilable(T.any(Integer, Float)), percent_of_max_threshold: T.nilable(T.any(Integer, Float))).returns({ 'awardable_points' => Integer, 'health_score' => T.any(Float, Integer), 'close_to_maximum_score' => T::Boolean, 'exceeds_score_threshold' => T::Boolean }) }
+      def self.health_score_component(awardable_points, score, score_threshold, percent_of_max = 0, percent_of_max_threshold = 100)
+        close_to_maximum_score = T.must(percent_of_max) >= T.must(percent_of_max_threshold)
+        exceeds_score_threshold = score >= score_threshold
+
+        if close_to_maximum_score || exceeds_score_threshold
+          { 'awardable_points' => awardable_points, 'health_score' => awardable_points, 'close_to_maximum_score' => close_to_maximum_score, 'exceeds_score_threshold' => exceeds_score_threshold }
+        else
+          { 'awardable_points' => awardable_points, 'health_score' => (score.to_f / score_threshold) * awardable_points, 'close_to_maximum_score' => close_to_maximum_score, 'exceeds_score_threshold' => exceeds_score_threshold }
+        end
+      end
+
+      sig {
+        params(
+          encapsulation: T::Hash[String, T.any(Integer, Float)],
+          cyclomatic_complexity: T::Hash[String, T.any(Integer, Float)],
+          test_coverage: T::Hash[String, T.any(Integer, Float)],
+          health_config: T::Hash[String, T.untyped]
+        ).returns(T::Hash[String, T.untyped])
+      }
+      def self.health_score_for(encapsulation, cyclomatic_complexity, test_coverage, health_config)
+        cyclomatic_complexity_config = health_config['components']['cyclomatic_complexity']
+        encapsulation_config = health_config['components']['encapsulation']
+        test_coverage_config = health_config['components']['test_coverage']
+
+        test_coverage_component = health_score_component(test_coverage_config['weight'], T.must(test_coverage['score']), test_coverage_config['score_threshold'])
+        cyclomatic_complexity_component = health_score_component(cyclomatic_complexity_config['weight'], T.must(cyclomatic_complexity['percentile']), cyclomatic_complexity_config['score_threshold'], cyclomatic_complexity['percent_of_max'], 100 - cyclomatic_complexity_config['minimum_variance'])
+        encapsulation_component = health_score_component(encapsulation_config['weight'], T.must(encapsulation['percentile']), encapsulation_config['score_threshold'], encapsulation['percent_of_max'], 100 - encapsulation_config['minimum_variance'])
+
+        overall = test_coverage_component['health_score'] + cyclomatic_complexity_component['health_score'] + encapsulation_component['health_score']
+
+        { 'test_coverage_component' => test_coverage_component, 'cyclomatic_complexity_component' => cyclomatic_complexity_component, 'encapsulation_component' => encapsulation_component, 'overall' => overall }
+      end
+    end
+  end
+end