Merge branch 'introduce-feature-flag-definition' into 'master'

Introduce feature flag definition (RUN AS-IF-FOSS)

Closes #221053

See merge request gitlab-org/gitlab!34269

bin/feature-flag

+#!/usr/bin/env ruby
+#
+# Generate a feature flag entry file in the correct location.
+#
+# Automatically stages the file and amends the previous commit if the `--amend`
+# argument is used.
+
+require 'optparse'
+require 'yaml'
+require 'fileutils'
+require 'cgi'
+
+require_relative '../lib/feature/shared' unless defined?(Feature::Shared)
+
+Options = Struct.new(
+  :name,
+  :type,
+  :group,
+  :ee,
+  :amend,
+  :dry_run,
+  :force,
+  :introduced_by_url,
+  :rollout_issue_url
+)
+
+module FeatureFlagHelpers
+  Abort = Class.new(StandardError)
+  Done = Class.new(StandardError)
+
+  def capture_stdout(cmd)
+    output = IO.popen(cmd, &:read)
+    fail_with "command failed: #{cmd.join(' ')}" unless $?.success?
+    output
+  end
+
+  def fail_with(message)
+    raise Abort, "\e[31merror\e[0m #{message}"
+  end
+end
+
+class FeatureFlagOptionParser
+  extend FeatureFlagHelpers
+  extend ::Feature::Shared
+
+  class << self
+    def parse(argv)
+      options = Options.new
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: #{__FILE__} [options] <feature-flag>\n\n"
+
+        # Note: We do not provide a shorthand for this in order to match the `git
+        # commit` interface
+        opts.on('--amend', 'Amend the previous commit') do |value|
+          options.amend = value
+        end
+
+        opts.on('-f', '--force', 'Overwrite an existing entry') do |value|
+          options.force = value
+        end
+
+        opts.on('-m', '--introduced-by-url [string]', String, 'URL to Merge Request introducing Feature Flag') do |value|
+          options.introduced_by_url = value
+        end
+
+        opts.on('-i', '--rollout-issue-url [string]', String, 'URL to Issue rolling out Feature Flag') do |value|
+          options.rollout_issue_url = value
+        end
+
+        opts.on('-n', '--dry-run', "Don't actually write anything, just print") do |value|
+          options.dry_run = value
+        end
+
+        opts.on('-g', '--group [string]', String, "The group introducing a feature flag, like: `group::apm`") do |value|
+          options.group = value if value.start_with?('group::')
+        end
+
+        opts.on('-t', '--type [string]', String, "The category of the feature flag, valid options are: #{TYPES.keys.map(&:to_s).join(', ')}") do |value|
+          options.type = value.to_sym if TYPES[value.to_sym]
+        end
+
+        opts.on('-e', '--ee', 'Generate a feature flag entry for GitLab EE') do |value|
+          options.ee = value
+        end
+
+        opts.on('-h', '--help', 'Print help message') do
+          $stdout.puts opts
+          raise Done.new
+        end
+      end
+
+      parser.parse!(argv)
+
+      unless argv.one?
+        $stdout.puts parser.help
+        $stdout.puts
+        raise Abort, 'Feature flag name is required'
+      end
+
+      # Name is a first name
+      options.name = argv.first
+
+      options
+    end
+
+    def read_group
+      $stdout.puts ">> Please specify the group introducing feature flag, like `group::apm`:"
+
+      loop do
+        $stdout.print "\n?> "
+        group = $stdin.gets.strip
+        group = nil if group.empty?
+        return group if group.nil? || group.start_with?('group::')
+
+        $stderr.puts "Group needs to include `group::`"
+      end
+    end
+
+    def read_type
+      $stdout.puts ">> Please specify the type of your feature flag:"
+      $stdout.puts
+      TYPES.each do |type, data|
+        $stdout.puts "#{type.to_s.rjust(15)}#{' '*6}#{data[:description]}"
+      end
+
+      loop do
+        $stdout.print "\n?> "
+
+        type = $stdin.gets.strip.to_sym
+        return type if TYPES[type]
+
+        $stderr.puts "Invalid type specified '#{type}'"
+      end
+    end
+
+    def read_issue_url(options)
+      return unless TYPES.dig(options.type, :rollout_issue)
+
+      url = "https://gitlab.com/gitlab-org/gitlab/-/issues/new"
+      title = "[Feature flag] Rollout of `#{options.name}`"
+      description = File.read('.gitlab/issue_templates/Feature Flag Roll Out.md')
+      description.sub!(':feature_name', options.name)
+
+      issue_new_url = url + "?" +
+        "issue[title]=" + CGI.escape(title) + "&"
+        # TODO: We should be able to pick `issueable_template`
+        # + "issue[description]=" + CGI.escape(description)
+
+      $stdout.puts ">> Open this URL and fill the rest of details:"
+      $stdout.puts issue_new_url
+      $stdout.puts
+
+      $stdout.puts ">> Paste URL here, or enter to skip:"
+
+      loop do
+        $stdout.print "\n?> "
+        created_url = $stdin.gets.strip
+        created_url = nil if created_url.empty?
+        return created_url if created_url.nil? || created_url.start_with?('https://')
+
+        $stderr.puts "URL needs to start with https://"
+      end
+    end
+  end
+end
+
+class FeatureFlagCreator
+  include FeatureFlagHelpers
+
+  attr_reader :options
+
+  def initialize(options)
+    @options = options
+  end
+
+  def execute
+    assert_feature_branch!
+    assert_name!
+    assert_existing_feature_flag!
+
+    # Read type from $stdin unless is already set
+    options.type ||= FeatureFlagOptionParser.read_type
+    options.group ||= FeatureFlagOptionParser.read_group
+    options.rollout_issue_url ||= FeatureFlagOptionParser.read_issue_url(options)
+
+    $stdout.puts "\e[32mcreate\e[0m #{file_path}"
+    $stdout.puts contents
+
+    unless options.dry_run
+      write
+      amend_commit if options.amend
+    end
+
+    if editor
+      system("#{editor} '#{file_path}'")
+    end
+  end
+
+  private
+
+  def contents
+    YAML.dump(
+      'name'              => options.name,
+      'introduced_by_url' => options.introduced_by_url,
+      'rollout_issue_url' => options.rollout_issue_url,
+      'group'             => options.group.to_s,
+      'type'              => options.type.to_s,
+      'default_enabled'   => false
+    ).strip
+  end
+
+  def write
+    FileUtils.mkdir_p(File.dirname(file_path))
+    File.write(file_path, contents)
+  end
+
+  def editor
+    ENV['EDITOR']
+  end
+
+  def amend_commit
+    fail_with "git add failed" unless system(*%W[git add #{file_path}])
+
+    Kernel.exec(*%w[git commit --amend])
+  end
+
+  def assert_feature_branch!
+    return unless branch_name == 'master'
+
+    fail_with "Create a branch first!"
+  end
+
+  def assert_existing_feature_flag!
+    existing_path = all_feature_flag_names[options.name]
+    return unless existing_path
+    return if options.force
+
+    fail_with "#{existing_path} already exists! Use `--force` to overwrite."
+  end
+
+  def assert_name!
+    return if options.name.match(/\A[a-z0-9_-]+\Z/)
+
+    fail_with "Provide a name for the feature flag that is [a-z0-9_-]"
+  end
+
+  def file_path
+    feature_flags_paths.last
+      .sub('**', options.type.to_s)
+      .sub('*.yml', options.name + '.yml')
+  end
+
+  def all_feature_flag_names
+    @all_feature_flag_names ||=
+      feature_flags_paths.map do |glob_path|
+        Dir.glob(glob_path).map do |path|
+          [File.basename(path, '.yml'), path]
+        end
+      end.flatten(1).to_h
+  end
+
+  def feature_flags_paths
+    paths = []
+    paths << File.join('config', 'feature_flags', '**', '*.yml')
+    paths << File.join('ee', 'config', 'feature_flags', '**', '*.yml') if ee?
+    paths
+  end
+
+  def ee?
+    options.ee
+  end
+
+  def branch_name
+    @branch_name ||= capture_stdout(%w[git symbolic-ref --short HEAD]).strip
+  end
+end
+
+if $0 == __FILE__
+  begin
+    options = FeatureFlagOptionParser.parse(ARGV)
+    FeatureFlagCreator.new(options).execute
+  rescue FeatureFlagHelpers::Abort => ex
+    $stderr.puts ex.message
+    exit 1
+  rescue FeatureFlagHelpers::Done
+    exit
+  end
+end
+
+# vim: ft=ruby

config/initializers/0_inject_feature_flags.rb

+# This needs to be loaded after
+# config/initializers/0_inject_enterprise_edition_module.rb
+
+Feature.register_feature_groups
+Feature.register_definitions

config/initializers/flipper.rb

-Feature.register_feature_groups

ee/lib/ee/feature/definition.rb

+# frozen_string_literal: true
+
+module EE
+  module Feature
+    module Definition
+      module ClassMethods
+        extend ::Gitlab::Utils::Override
+
+        override :paths
+        def paths
+          @ee_paths ||= [Rails.root.join('ee', 'config', 'feature_flags', '**', '*.yml')] + super
+        end
+      end
+
+      def self.prepended(base)
+        base.singleton_class.prepend ClassMethods
+      end
+    end
+  end
+end

lib/feature.rb

@@ -54,12 +54,14 @@ class Feature
     # unless set explicitly.  The default is `disabled`
     # TODO: remove the `default_enabled:` and read it from the `defintion_yaml`
     # check: https://gitlab.com/gitlab-org/gitlab/-/issues/30228
-    def enabled?(key, thing = nil, default_enabled: false)
+    def enabled?(key, thing = nil, type: :development, default_enabled: false)
       if check_feature_flags_definition?
         if thing && !thing.respond_to?(:flipper_id)
           raise InvalidFeatureFlagError,
             "The thing '#{thing.class.name}' for feature flag '#{key}' needs to include `FeatureGate` or implement `flipper_id`"
         end
+
+        Feature::Definition.valid_usage!(key, type: type, default_enabled: default_enabled)
       end
 
       # During setup the database does not exist yet. So we haven't stored a value
@@ -75,9 +77,9 @@ class Feature
       !default_enabled || Feature.persisted_name?(feature.name) ? feature.enabled?(thing) : true
     end
 
-    def disabled?(key, thing = nil, default_enabled: false)
+    def disabled?(key, thing = nil, type: :development, default_enabled: false)
       # we need to make different method calls to make it easy to mock / define expectations in test mode
-      thing.nil? ? !enabled?(key, default_enabled: default_enabled) : !enabled?(key, thing, default_enabled: default_enabled)
+      thing.nil? ? !enabled?(key, type: type, default_enabled: default_enabled) : !enabled?(key, thing, type: type, default_enabled: default_enabled)
     end
 
     def enable(key, thing = true)
@@ -129,6 +131,12 @@ class Feature
     def register_feature_groups
     end
 
+    def register_definitions
+      return unless check_feature_flags_definition?
+
+      Feature::Definition.load_all!
+    end
+
     private
 
     def flipper

lib/feature/definition.rb

+# frozen_string_literal: true
+
+class Feature
+  class Definition
+    include ::Feature::Shared
+
+    attr_reader :path
+    attr_reader :attributes
+
+    PARAMS.each do |param|
+      define_method(param) do
+        attributes[param]
+      end
+    end
+
+    def initialize(path, opts = {})
+      @path = path
+      @attributes = {}
+
+      # assign nil, for all unknown opts
+      PARAMS.each do |param|
+        @attributes[param] = opts[param]
+      end
+    end
+
+    def key
+      name.to_sym
+    end
+
+    def validate!
+      unless name.present?
+        raise Feature::InvalidFeatureFlagError, "Feature flag is missing name"
+      end
+
+      unless path.present?
+        raise Feature::InvalidFeatureFlagError, "Feature flag '#{name}' is missing path"
+      end
+
+      unless type.present?
+        raise Feature::InvalidFeatureFlagError, "Feature flag '#{name}' is missing type. Ensure to update #{path}"
+      end
+
+      unless Definition::TYPES.include?(type.to_sym)
+        raise Feature::InvalidFeatureFlagError, "Feature flag '#{name}' type '#{type}' is invalid. Ensure to update #{path}"
+      end
+
+      unless File.basename(path, ".yml") == name
+        raise Feature::InvalidFeatureFlagError, "Feature flag '#{name}' has an invalid path: '#{path}'. Ensure to update #{path}"
+      end
+
+      unless File.basename(File.dirname(path)) == type
+        raise Feature::InvalidFeatureFlagError, "Feature flag '#{name}' has an invalid type: '#{path}'. Ensure to update #{path}"
+      end
+
+      if default_enabled.nil?
+        raise Feature::InvalidFeatureFlagError, "Feature flag '#{name}' is missing default_enabled. Ensure to update #{path}"
+      end
+    end
+
+    def valid_usage!(type_in_code:, default_enabled_in_code:)
+      unless Array(type).include?(type_in_code.to_s)
+        # Raise exception in test and dev
+        raise Feature::InvalidFeatureFlagError, "The `type:` of `#{key}` is not equal to config: " \
+          "#{type_in_code} vs #{type}. Ensure to use valid type in #{path} or ensure that you use " \
+          "a valid syntax: #{TYPES.dig(type, :example)}"
+      end
+
+      # We accept an array of defaults as some features are undefined
+      # and have `default_enabled: true/false`
+      unless Array(default_enabled).include?(default_enabled_in_code)
+        # Raise exception in test and dev
+        raise Feature::InvalidFeatureFlagError, "The `default_enabled:` of `#{key}` is not equal to config: " \
+          "#{default_enabled_in_code} vs #{default_enabled}. Ensure to update #{path}"
+      end
+    end
+
+    def to_h
+      attributes
+    end
+
+    class << self
+      def paths
+        @paths ||= [Rails.root.join('config', 'feature_flags', '**', '*.yml')]
+      end
+
+      def definitions
+        @definitions ||= {}
+      end
+
+      def load_all!
+        definitions.clear
+
+        paths.each do |glob_path|
+          load_all_from_path!(glob_path)
+        end
+
+        definitions
+      end
+
+      def valid_usage!(key, type:, default_enabled:)
+        if definition = definitions[key.to_sym]
+          definition.valid_usage!(type_in_code: type, default_enabled_in_code: default_enabled)
+        elsif type_definition = self::TYPES[type]
+          raise InvalidFeatureFlagError, "Missing feature definition for `#{key}`" unless type_definition[:optional]
+        else
+          raise InvalidFeatureFlagError, "Unknown feature flag type used: `#{type}`"
+        end
+      end
+
+      private
+
+      def load_from_file(path)
+        definition = File.read(path)
+        definition = YAML.safe_load(definition)
+        definition.deep_symbolize_keys!
+
+        self.new(path, definition).tap(&:validate!)
+      rescue => e
+        raise Feature::InvalidFeatureFlagError, "Invalid definition for `#{path}`: #{e.message}"
+      end
+
+      def load_all_from_path!(glob_path)
+        Dir.glob(glob_path).each do |path|
+          definition = load_from_file(path)
+
+          if previous = definitions[definition.key]
+            raise InvalidFeatureFlagError, "Feature flag '#{definition.key}' is already defined in '#{previous.path}'"
+          end
+
+          definitions[definition.key] = definition
+        end
+      end
+    end
+  end
+end
+
+Feature::Definition.prepend_if_ee('EE::Feature::Definition')

lib/feature/shared.rb

+# frozen_string_literal: true
+
+# This file can contain only simple constructs as it is shared between:
+# 1. `Pure Ruby`: `bin/feature-flag`
+# 2. `GitLab Rails`: `lib/feature/definition.rb`
+
+class Feature
+  module Shared
+    # optional: defines if a on-disk definition is required for this feature flag type
+    # rollout_issue: defines if `bin/feature-flag` asks for rollout issue
+    # example: usage being shown when exception is raised
+    TYPES = {
+      development: {
+        description: 'Short lived, used to enable unfinished code to be deployed',
+        optional: true,
+        rollout_issue: true,
+        example: <<-EOS
+          Feature.enabled?(:my_feature_flag)
+          Feature.enabled?(:my_feature_flag, type: :development)
+        EOS
+      }
+    }.freeze
+
+    PARAMS = %i[
+      name
+      default_enabled
+      type
+      introduced_by_url
+      rollout_issue_url
+      group
+    ].freeze
+  end
+end

spec/bin/feature_flag_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+load File.expand_path('../../bin/feature-flag', __dir__)
+
+RSpec.describe 'bin/feature-flag' do
+  using RSpec::Parameterized::TableSyntax
+
+  describe FeatureFlagCreator do
+    let(:argv) { %w[feature-flag-name -t development -g group::memory -i https://url] }
+    let(:options) { FeatureFlagOptionParser.parse(argv) }
+    let(:creator) { described_class.new(options) }
+    let(:existing_flag) { File.join('config', 'feature_flags', 'development', 'existing-feature-flag.yml') }
+
+    before do
+      # create a dummy feature flag
+      FileUtils.mkdir_p(File.dirname(existing_flag))
+      File.write(existing_flag, '{}')
+
+      # ignore writes
+      allow(File).to receive(:write).and_return(true)
+
+      # ignore stdin
+      allow($stdin).to receive(:gets).and_raise('EOF')
+
+      # ignore Git commands
+      allow(creator).to receive(:branch_name) { 'feature-branch' }
+    end
+
+    after do
+      FileUtils.rm_f(existing_flag)
+    end
+
+    subject { creator.execute }
+
+    it 'properly creates a feature flag' do
+      expect(File).to receive(:write).with(
+        File.join('config', 'feature_flags', 'development', 'feature-flag-name.yml'),
+        anything)
+
+      expect do
+        subject
+      end.to output(/name: feature-flag-name/).to_stdout
+    end
+
+    context 'when running on master' do
+      it 'requires feature branch' do
+        expect(creator).to receive(:branch_name) { 'master' }
+
+        expect { subject }.to raise_error(FeatureFlagHelpers::Abort, /Create a branch first/)
+      end
+    end
+
+    context 'validates feature flag name' do
+      where(:argv, :ex) do
+        %w[.invalid.feature.flag] | /Provide a name for the feature flag that is/
+        %w[existing-feature-flag] | /already exists!/
+      end
+
+      with_them do
+        it do
+          expect { subject }.to raise_error(ex)
+        end
+      end
+    end
+  end
+
+  describe FeatureFlagOptionParser do
+    describe '.parse' do
+      where(:param, :argv, :result) do
+        :name              | %w[foo]                                 | 'foo'
+        :amend             | %w[foo --amend]                         | true
+        :force             | %w[foo -f]                              | true
+        :force             | %w[foo --force]                         | true
+        :ee                | %w[foo -e]                              | true
+        :ee                | %w[foo --ee]                            | true
+        :introduced_by_url | %w[foo -m https://url]                  | 'https://url'
+        :introduced_by_url | %w[foo --introduced-by-url https://url] | 'https://url'
+        :rollout_issue_url | %w[foo -i https://url]                  | 'https://url'
+        :rollout_issue_url | %w[foo --rollout-issue-url https://url] | 'https://url'
+        :dry_run           | %w[foo -n]                              | true
+        :dry_run           | %w[foo --dry-run]                       | true
+        :type              | %w[foo -t development]                  | :development
+        :type              | %w[foo --type development]              | :development
+        :type              | %w[foo -t invalid]                      | nil
+        :type              | %w[foo --type invalid]                  | nil
+        :group             | %w[foo -g group::memory]                | 'group::memory'
+        :group             | %w[foo --group group::memory]           | 'group::memory'
+        :group             | %w[foo -g invalid]                      | nil
+        :group             | %w[foo --group invalid]                 | nil
+      end
+
+      with_them do
+        it do
+          options = described_class.parse(Array(argv))
+
+          expect(options.public_send(param)).to eq(result)
+        end
+      end
+
+      it 'missing feature flag name' do
+        expect do
+          expect { described_class.parse(%w[--amend]) }.to output(/Feature flag name is required/).to_stdout
+        end.to raise_error(FeatureFlagHelpers::Abort)
+      end
+
+      it 'parses -h' do
+        expect do
+          expect { described_class.parse(%w[foo -h]) }.to output(/Usage:/).to_stdout
+        end.to raise_error(FeatureFlagHelpers::Done)
+      end
+    end
+
+    describe '.read_type' do
+      let(:type) { 'development' }
+
+      it 'reads type from $stdin' do
+        expect($stdin).to receive(:gets).and_return(type)
+        expect do
+          expect(described_class.read_type).to eq(:development)
+        end.to output(/specify the type/).to_stdout
+      end
+
+      context 'invalid type given' do
+        let(:type) { 'invalid' }
+
+        it 'shows error message and retries' do
+          expect($stdin).to receive(:gets).and_return(type)
+          expect($stdin).to receive(:gets).and_raise('EOF')
+
+          expect do
+            expect { described_class.read_type }.to raise_error(/EOF/)
+          end.to output(/specify the type/).to_stdout
+            .and output(/Invalid type specified/).to_stderr
+        end
+      end
+    end
+
+    describe '.read_group' do
+      let(:group) { 'group::memory' }
+
+      it 'reads type from $stdin' do
+        expect($stdin).to receive(:gets).and_return(group)
+        expect do
+          expect(described_class.read_group).to eq('group::memory')
+        end.to output(/specify the group/).to_stdout
+      end
+
+      context 'invalid group given' do
+        let(:type) { 'invalid' }
+
+        it 'shows error message and retries' do
+          expect($stdin).to receive(:gets).and_return(type)
+          expect($stdin).to receive(:gets).and_raise('EOF')
+
+          expect do
+            expect { described_class.read_group }.to raise_error(/EOF/)
+          end.to output(/specify the group/).to_stdout
+            .and output(/Group needs to include/).to_stderr
+        end
+      end
+    end
+
+    describe '.rollout_issue_url' do
+      let(:options) { OpenStruct.new(name: 'foo', type: :development) }
+      let(:url) { 'https://issue' }
+
+      it 'reads type from $stdin' do
+        expect($stdin).to receive(:gets).and_return(url)
+        expect do
+          expect(described_class.read_issue_url(options)).to eq('https://issue')
+        end.to output(/Paste URL here/).to_stdout
+      end
+
+      context 'invalid URL given' do
+        let(:type) { 'invalid' }
+
+        it 'shows error message and retries' do
+          expect($stdin).to receive(:gets).and_return(type)
+          expect($stdin).to receive(:gets).and_raise('EOF')
+
+          expect do
+            expect { described_class.read_issue_url(options) }.to raise_error(/EOF/)
+          end.to output(/Paste URL here/).to_stdout
+            .and output(/URL needs to start/).to_stderr
+        end
+      end
+    end
+  end
+end

spec/lib/feature/definition_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Feature::Definition do
+  let(:attributes) do
+    { name: 'feature_flag',
+      type: 'development',
+      default_enabled: true }
+  end
+
+  let(:path) { File.join('development', 'feature_flag.yml') }
+  let(:definition) { described_class.new(path, attributes) }
+  let(:yaml_content) { attributes.deep_stringify_keys.to_yaml }
+
+  describe '#key' do
+    subject { definition.key }
+
+    it 'returns a symbol from name' do
+      is_expected.to eq(:feature_flag)
+    end
+  end
+
+  describe '#validate!' do
+    using RSpec::Parameterized::TableSyntax
+
+    where(:param, :value, :result) do
+      :name            | nil                        | /Feature flag is missing name/
+      :path            | nil                        | /Feature flag 'feature_flag' is missing path/
+      :type            | nil                        | /Feature flag 'feature_flag' is missing type/
+      :type            | 'invalid'                  | /Feature flag 'feature_flag' type 'invalid' is invalid/
+      :path            | 'development/invalid.yml'  | /Feature flag 'feature_flag' has an invalid path/
+      :path            | 'invalid/feature_flag.yml' | /Feature flag 'feature_flag' has an invalid type/
+      :default_enabled | nil                        | /Feature flag 'feature_flag' is missing default_enabled/
+    end
+
+    with_them do
+      let(:params) { attributes.merge(path: path) }
+
+      before do
+        params[param] = value
+      end
+
+      it do
+        expect do
+          described_class.new(
+            params[:path], params.except(:path)
+          ).validate!
+        end.to raise_error(result)
+      end
+    end
+  end
+
+  describe '#valid_usage!' do
+    context 'validates type' do
+      it 'raises exception for invalid type' do
+        expect { definition.valid_usage!(type_in_code: :invalid, default_enabled_in_code: false) }
+          .to raise_error(/The `type:` of `feature_flag` is not equal to config/)
+      end
+    end
+
+    context 'validates default enabled' do
+      it 'raises exception for different value' do
+        expect { definition.valid_usage!(type_in_code: :development, default_enabled_in_code: false) }
+          .to raise_error(/The `default_enabled:` of `feature_flag` is not equal to config/)
+      end
+    end
+  end
+
+  describe '.paths' do
+    it 'returns at least one path' do
+      expect(described_class.paths).not_to be_empty
+    end
+  end
+
+  describe '.load_from_file' do
+    it 'properly loads a definition from file' do
+      expect(File).to receive(:read).with(path) { yaml_content }
+
+      expect(described_class.send(:load_from_file, path).attributes)
+        .to eq(definition.attributes)
+    end
+
+    context 'for missing file' do
+      let(:path) { 'missing/feature-flag/file.yml' }
+
+      it 'raises exception' do
+        expect do
+          described_class.send(:load_from_file, path)
+        end.to raise_error(/Invalid definition for/)
+      end
+    end
+
+    context 'for invalid definition' do
+      it 'raises exception' do
+        expect(File).to receive(:read).with(path) { '{}' }
+
+        expect do
+          described_class.send(:load_from_file, path)
+        end.to raise_error(/Feature flag is missing name/)
+      end
+    end
+  end
+
+  describe '.load_all!' do
+    let(:store1) { Dir.mktmpdir('path1') }
+    let(:store2) { Dir.mktmpdir('path2') }
+
+    before do
+      allow(described_class).to receive(:paths).and_return(
+        [
+          File.join(store1, '**', '*.yml'),
+          File.join(store2, '**', '*.yml')
+        ]
+      )
+    end
+
+    it "when there's no feature flags a list of definitions is empty" do
+      expect(described_class.load_all!).to be_empty
+    end
+
+    it "when there's a single feature flag it properly loads them" do
+      write_feature_flag(store1, path, yaml_content)
+
+      expect(described_class.load_all!).to be_one
+    end
+
+    it "when the same feature flag is stored multiple times raises exception" do
+      write_feature_flag(store1, path, yaml_content)
+      write_feature_flag(store2, path, yaml_content)
+
+      expect { described_class.load_all! }
+        .to raise_error(/Feature flag 'feature_flag' is already defined/)
+    end
+
+    it "when one of the YAMLs is invalid it does raise exception" do
+      write_feature_flag(store1, path, '{}')
+
+      expect { described_class.load_all! }
+        .to raise_error(/Feature flag is missing name/)
+    end
+
+    after do
+      FileUtils.rm_rf(store1)
+      FileUtils.rm_rf(store2)
+    end
+
+    def write_feature_flag(store, path, content)
+      path = File.join(store, path)
+      dir = File.dirname(path)
+      FileUtils.mkdir_p(dir)
+      File.write(path, content)
+    end
+  end
+
+  describe '.valid_usage!' do
+    before do
+      allow(described_class).to receive(:definitions) do
+        { definition.key => definition }
+      end
+    end
+
+    context 'when a known feature flag is used' do
+      it 'validates it usage' do
+        expect(definition).to receive(:valid_usage!)
+
+        described_class.valid_usage!(:feature_flag, type: :development, default_enabled: false)
+      end
+    end
+
+    context 'when an unknown feature flag is used' do
+      context 'for a type that is required to have all feature flags registered' do
+        before do
+          stub_const('Feature::Shared::TYPES', {
+            development: { optional: false }
+          })
+        end
+
+        it 'raises exception' do
+          expect do
+            described_class.valid_usage!(:unknown_feature_flag, type: :development, default_enabled: false)
+          end.to raise_error(/Missing feature definition for `unknown_feature_flag`/)
+        end
+      end
+
+      context 'for a type that is optional' do
+        before do
+          stub_const('Feature::Shared::TYPES', {
+            development: { optional: true }
+          })
+        end
+
+        it 'does not raise exception' do
+          expect do
+            described_class.valid_usage!(:unknown_feature_flag, type: :development, default_enabled: false)
+          end.not_to raise_error
+        end
+      end
+
+      context 'for an unknown type' do
+        it 'raises exception' do
+          expect do
+            described_class.valid_usage!(:unknown_feature_flag, type: :unknown_type, default_enabled: false)
+          end.to raise_error(/Unknown feature flag type used: `unknown_type`/)
+        end
+      end
+    end
+  end
+end

spec/lib/feature_spec.rb

@@ -242,6 +242,36 @@ RSpec.describe Feature, stub_feature_flags: false do
         end
       end
     end
+
+    context 'validates usage of feature flag with YAML definition' do
+      let(:definition) do
+        Feature::Definition.new('development/my_feature_flag.yml',
+          name: 'my_feature_flag',
+          type: 'development',
+          default_enabled: false
+        ).tap(&:validate!)
+      end
+
+      before do
+        allow(Feature::Definition).to receive(:definitions) do
+          { definition.key => definition }
+        end
+      end
+
+      it 'when usage is correct' do
+        expect { described_class.enabled?(:my_feature_flag) }.not_to raise_error
+      end
+
+      it 'when invalid type is used' do
+        expect { described_class.enabled?(:my_feature_flag, type: :licensed) }
+          .to raise_error(/The `type:` of/)
+      end
+
+      it 'when invalid default_enabled is used' do
+        expect { described_class.enabled?(:my_feature_flag, default_enabled: true) }
+          .to raise_error(/The `default_enabled:` of/)
+      end
+    end
   end
 
   describe '.disable?' do

spec/spec_helper.rb

@@ -155,6 +155,9 @@ RSpec.configure do |config|
   config.before(:suite) do
     Timecop.safe_mode = true
     TestEnv.init
+
+    # Reload all feature flags definitions
+    Feature.register_definitions
   end
 
   config.after(:all) do