feature_map 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f1243d054f38c9a5520a3790190ad36cf49a447c4e931d7e5cc85cd1a958eb20
+  data.tar.gz: 275ed70329b4df76a18412719ee004c8626cb53f708905f5ff3413846fab34e2
+SHA512:
+  metadata.gz: 62100534249d7ccc2ec67849ca92bcaf38dc55bd6d22a3d1aefb673b6a6222c16cddbb742af38f895832d758de85ffe75c6f93fccf2b4d6c292d344566b04089
+  data.tar.gz: e055eaa7af6fe4a6e27c9f29a38e1c2d1a687cbf0f5ba500541a0b2b21cbec9a78b29cc23c95128995eb81142b98cbeee3d01e4dc454084e956f8a748f0b8e95

data/README.md

@@ -0,0 +1,269 @@
+# 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.
+
+## Getting started
+
+To get started there's a few things you should do.
+
+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`.
+
+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.
+
+        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.
+
+## Usage: Assigning Features
+
+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
+
+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
+
+Contributions are welcome and appreciated. Here's how to get started:
+
+- clone repo: `$ git clone git@github.com:Beyond-Finance/feature_map.git`
+- install dependencies: `$ bundle install`
+- run tests: `$ bundle exec rspec`
+- run Rubocop: `$ bundle exec rubocop`
+- run Sorbet: `$ bundle exec srb tc`
+
+That's it! Assuming you can complete all of these steps without any error or issues, you should be good to go.
+
+#### Publication
+
+When a new version of the gem is ready to be published, please follow these steps:
+
+* Update `spec.version` value in the (feature_map.gemspec)[feature_map.gemspec] file.
+    * Assign a version to this release in accordance with [Semantic Versioning](https://semver.org/) based on the changes contained in this release.
+* Create a new release tag in Github ([link](https://github.com/Beyond-Finance/feature_map/releases)) with a value that matches the new Gemspec version.
+* Checkout the release tag in your local environment.
+* Publish the new version of the gem to RubyGems ([docs](https://guides.rubygems.org/publishing/#publishing-to-rubygemsorg)), which largely consists of running the following commands:
+   * 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`

data/bin/featuremap

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# typed: strict
+
+require 'feature_map'
+FeatureMap::Cli.run!(ARGV)

data/lib/feature_map/cli.rb

@@ -0,0 +1,243 @@
+# typed: true
+
+require 'optparse'
+require 'pathname'
+require 'fileutils'
+require 'feature_map/output_color'
+
+module FeatureMap
+  class Cli
+    def self.run!(argv)
+      command = argv.shift
+      if command == 'validate'
+        validate!(argv)
+      elsif command == 'docs'
+        docs!(argv)
+      elsif command == 'test_coverage'
+        test_coverage!(argv)
+      elsif command == 'test_pyramid'
+        test_pyramid!(argv)
+      elsif command == 'for_file'
+        for_file(argv)
+      elsif command == 'for_feature'
+        for_feature(argv)
+      elsif [nil, 'help'].include?(command)
+        puts <<~USAGE
+          Usage: bin/featuremap <subcommand>
+
+          Subcommands:
+            validate - run all validations
+            docs - generates feature documentation
+            test_coverage - generates per-feature test coverage statistics
+            test_pyramid - generates per-feature test pyramid (unit, integration, regression) statistics
+            for_file - find feature assignment for a single file
+            for_feature - find assignment information for a feature
+            help  - display help information about feature_map
+        USAGE
+      else
+        puts "'#{command}' is not a feature_map command. See `bin/featuremap help`."
+      end
+    end
+
+    def self.validate!(argv)
+      options = {}
+
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: bin/featuremap validate [options]'
+
+        opts.on('--skip-autocorrect', 'Skip automatically correcting any errors, such as the .feature_map/assignments.yml file') do
+          options[:skip_autocorrect] = true
+        end
+
+        opts.on('-d', '--diff', 'Only run validations with staged files') do
+          options[:diff] = true
+        end
+
+        opts.on('-s', '--skip-stage', 'Skips staging the .feature_map/assignments.yml file') do
+          options[:skip_stage] = true
+        end
+
+        opts.on('--help', 'Shows this prompt') do
+          puts opts
+          exit
+        end
+      end
+      args = parser.order!(argv)
+      parser.parse!(args)
+
+      files = if options[:diff]
+                ENV.fetch('FEATUREMAP_GIT_STAGED_FILES') { `git diff --staged --name-only` }.split("\n").select do |file|
+                  File.exist?(file)
+                end
+              else
+                nil
+              end
+
+      FeatureMap.validate!(
+        files: files,
+        autocorrect: !options[:skip_autocorrect],
+        stage_changes: !options[:skip_stage]
+      )
+
+      puts OutputColor.green('FeatureMap validation complete.')
+    end
+
+    def self.docs!(argv)
+      options = {}
+
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: bin/featuremap docs [options] [target_commit_sha]'
+
+        opts.on('-s', '--skip-stage', 'Skips staging the .feature_map/assignments.yml file') do
+          options[:skip_stage] = true
+        end
+
+        opts.on('--skip-validate', 'Skip the execution of the validate command, using the existing feature output files') do
+          options[:skip_validate] = true
+        end
+
+        opts.on('--help', 'Shows this prompt') do
+          puts opts
+          exit
+        end
+      end
+      args = parser.order!(argv)
+      parser.parse!(args)
+
+      non_flag_args = argv.reject { |arg| arg.start_with?('--') }
+      custom_git_ref = non_flag_args[0]
+
+      FeatureMap.validate!(stage_changes: !options[:skip_stage]) unless options[:skip_validate]
+
+      FeatureMap.generate_docs!(custom_git_ref)
+
+      puts OutputColor.green('FeatureMap documentaiton site generated.')
+      puts 'Open .feature_map/docs/index.html in a browser to view the documentation site.'
+    end
+
+    def self.test_coverage!(argv)
+      parser = OptionParser.new do |opts|
+        opts.banner = <<~MSG
+          Usage: bin/featuremap test_coverage [options] [code_cov_commit_sha].
+          Note:  Requires environment variable `CODECOV_API_TOKEN`.
+        MSG
+
+        opts.on('--help', 'Shows this prompt') do
+          puts opts
+          exit
+        end
+      end
+      args = parser.order!(argv)
+      parser.parse!(args)
+      non_flag_args = argv.reject { |arg| arg.start_with?('--') }
+      custom_commit_sha = non_flag_args[0]
+
+      code_cov_token = ENV.fetch('CODECOV_API_TOKEN', '')
+      raise 'Please specify a CodeCov API token in your environment as `CODECOV_API_TOKEN`' if code_cov_token.empty?
+
+      # If no commit SHA was providid in the CLI command args, use the most recent commit of the main branch in the upstream remote.
+      commit_sha = custom_commit_sha || `git log -1 --format=%H origin/main`.chomp
+      puts "Pulling test coverage statistics for commit #{commit_sha}"
+
+      FeatureMap.gather_test_coverage!(commit_sha, code_cov_token)
+
+      puts OutputColor.green('FeatureMap test coverage statistics collected.')
+      puts 'View the resulting test coverage for each feature in .feature_map/test-coverage.yml'
+    end
+
+    def self.test_pyramid!(argv)
+      parser = OptionParser.new do |opts|
+        opts.banner = <<~MSG
+          Usage: bin/featuremap test_pyramid [unit_path] [integration_path] [regression_path] [regression_assignments_path].
+          Paths should point to files containing json-formatted rspec test summaries.
+          These can be generated via rspec's `-f j` flag.
+        MSG
+
+        opts.on('--help', 'Shows this prompt') do
+          puts opts
+          exit
+        end
+      end
+      args = parser.order!(argv)
+      parser.parse!(args)
+      non_flag_args = argv.reject { |arg| arg.start_with?('--') }
+
+      file_paths = non_flag_args.first(4)
+      raise 'Please specify all of [unit_path] [integration_path] [regression_path] [regression_assignments_path]' if file_paths.compact.size != 4
+
+      unit_path, integration_path, regression_path, regression_assignments_path = file_paths
+      FeatureMap.generate_test_pyramid!(unit_path, integration_path, regression_path, regression_assignments_path)
+    end
+
+    # For now, this just returns feature assignment
+    # Later, this could also return feature assignment errors about that file.
+    def self.for_file(argv)
+      options = {}
+
+      # Long-term, we probably want to use something like `thor` so we don't have to implement logic
+      # like this. In the short-term, this is a simple way for us to use the built-in OptionParser
+      # while having an ergonomic CLI.
+      files = argv.reject { |arg| arg.start_with?('--') }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: bin/featuremap for_file [options]'
+
+        opts.on('--json', 'Output as JSON') do
+          options[:json] = true
+        end
+
+        opts.on('--help', 'Shows this prompt') do
+          puts opts
+          exit
+        end
+      end
+      args = parser.order!(argv)
+      parser.parse!(args)
+
+      if files.count != 1
+        raise 'Please pass in one file. Use `bin/featuremap for_file --help` for more info'
+      end
+
+      feature = FeatureMap.for_file(files.first)
+
+      feature_name = feature&.name || 'Unassigned'
+      feature_yml = feature&.config_yml || 'Unassigned'
+
+      if options[:json]
+        json = {
+          feature_name: feature_name,
+          feature_yml: feature_yml
+        }
+
+        puts json.to_json
+      else
+        puts <<~MSG
+          Feature: #{feature_name}
+          Feature YML: #{feature_yml}
+        MSG
+      end
+    end
+
+    def self.for_feature(argv)
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: bin/featuremap for_feature \'Onboarding\''
+
+        opts.on('--help', 'Shows this prompt') do
+          puts opts
+          exit
+        end
+      end
+      features = argv.reject { |arg| arg.start_with?('--') }
+      args = parser.order!(argv)
+      parser.parse!(args)
+
+      if features.count != 1
+        raise 'Please pass in one feature. Use `bin/featuremap for_feature --help` for more info'
+      end
+
+      puts FeatureMap.for_feature(features.first)
+    end
+
+    private_class_method :validate!
+  end
+end

data/lib/feature_map/code_features/plugin.rb

@@ -0,0 +1,79 @@
+# typed: strict
+
+module FeatureMap
+  module CodeFeatures
+    # Plugins allow a client to add validation on custom keys in the feature YML.
+    # For now, only a single plugin is allowed to manage validation on a top-level key.
+    # In the future we can think of allowing plugins to be gracefully merged with each other.
+    class Plugin
+      extend T::Helpers
+      extend T::Sig
+
+      abstract!
+
+      sig { params(feature: Feature).void }
+      def initialize(feature)
+        @feature = feature
+      end
+
+      sig { params(base: T.untyped).void }
+      def self.inherited(base) # rubocop:disable Lint/MissingSuper
+        all_plugins << T.cast(base, T.class_of(Plugin))
+      end
+
+      sig { returns(T::Array[T.class_of(Plugin)]) }
+      def self.all_plugins
+        @all_plugins ||= T.let(@all_plugins, T.nilable(T::Array[T.class_of(Plugin)]))
+        @all_plugins ||= []
+        @all_plugins
+      end
+
+      sig { params(features: T::Array[Feature]).returns(T::Array[String]) }
+      def self.validation_errors(features)
+        []
+      end
+
+      sig { params(feature: Feature).returns(T.attached_class) }
+      def self.for(feature)
+        register_feature(feature)
+      end
+
+      sig { params(feature: Feature, key: String).returns(String) }
+      def self.missing_key_error_message(feature, key)
+        "#{feature.name} is missing required key `#{key}`"
+      end
+
+      sig { returns(T::Hash[T.nilable(String), T::Hash[T.class_of(Plugin), Plugin]]) }
+      def self.registry
+        @registry ||= T.let(@registry, T.nilable(T::Hash[String, T::Hash[T.class_of(Plugin), Plugin]]))
+        @registry ||= {}
+        @registry
+      end
+
+      sig { params(feature: Feature).returns(T.attached_class) }
+      def self.register_feature(feature)
+        # We pull from the hash since `feature.name` uses the registry
+        feature_name = feature.raw_hash['name']
+
+        registry[feature_name] ||= {}
+        registry_for_feature = registry[feature_name] || {}
+        registry[feature_name] ||= {}
+        registry_for_feature[self] ||= new(feature)
+        T.unsafe(registry_for_feature[self])
+      end
+
+      sig { void }
+      def self.bust_caches!
+        all_plugins.each(&:clear_feature_registry!)
+      end
+
+      sig { void }
+      def self.clear_feature_registry!
+        @registry = nil
+      end
+
+      private_class_method :registry
+      private_class_method :register_feature
+    end
+  end
+end

data/lib/feature_map/code_features/plugins/identity.rb

@@ -0,0 +1,39 @@
+# typed: true
+
+module FeatureMap
+  module CodeFeatures
+    module Plugins
+      class Identity < Plugin
+        extend T::Sig
+        extend T::Helpers
+
+        IdentityStruct = Struct.new(:name)
+
+        sig { returns(IdentityStruct) }
+        def identity
+          IdentityStruct.new(
+            @feature.raw_hash['name']
+          )
+        end
+
+        sig { override.params(features: T::Array[CodeFeatures::Feature]).returns(T::Array[String]) }
+        def self.validation_errors(features)
+          errors = T.let([], T::Array[String])
+
+          uniq_set = Set.new
+          features.each do |feature|
+            for_feature = self.for(feature)
+
+            if !uniq_set.add?(for_feature.identity.name)
+              errors << "More than 1 definition for #{for_feature.identity.name} found"
+            end
+
+            errors << missing_key_error_message(feature, 'name') if for_feature.identity.name.nil?
+          end
+
+          errors
+        end
+      end
+    end
+  end
+end