rspec-rfc-helper 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 77bf0b42fa2165a6521a2929936cb1a1b58ab359cb19bbe19681ff7e2767d75f
+  data.tar.gz: 42e537f5b31324440b1cf98ac49a23ae1aea884cfe734e660943441ee88acafa
+SHA512:
+  metadata.gz: ca6a4cd4d10c244b4d2ab310d17a4e51f831c3c2e3bb97abd984996913f19d76621de9e93bde197dfc005616a73be1684351d4c1867f6cf958502d70f4317400
+  data.tar.gz: de7b0bc373efa3875b961354733c8ce5a9fc2405447d7d98d61c336fc7380bbdf8215eb8c7228c1b7a4076b2d77f80caa7c2811b6c4486695767deb4fdf48ca2

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,32 @@
+---
+require:
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  # Do not lint generated files
+  Exclude:
+    - coverage/**/*
+    - vendor/**/*
+  TargetRubyVersion: 3.1.2
+  NewCops: enable
+
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Layout/LineLength:
+  Max: 130
+
+Style/HashSyntax:
+  EnforcedShorthandSyntax: never
+
+Style/SymbolArray:
+  EnforcedStyle: brackets
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma

data/.ruby-version

@@ -0,0 +1 @@
+3.1.2

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!--
+Quick remainder of the possible sections:
+-----------------------------------------
+### Added
+  for new features.
+### Changed
+  for changes in existing functionality.
+### Deprecated
+  for soon-to-be removed features.
+### Removed
+  for now removed features.
+### Fixed
+  for any bug fixes.
+### Security
+  in case of vulnerabilities.
+### Maintenance
+  in case of rework, dependencies change
+
+Please, keep them in this order when updating.
+-->
+
+## [Unreleased]
+
+## [0.1.0] - 2023-11-07 - Initial release
+
+Initial release
+

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Experiments Labs / Experimentations
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,175 @@
+# RSpec::RfcHelper
+
+RSpec RFC Helper is a RSpec module to help tracking implementation of big specifications, when having only comments in
+code or tests becomes too tedious to maintain and follow.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```rb
+gem 'rspec-rfc-helper'
+```
+
+## Usage
+
+1. Write the specs: read the RFC/specifications that needs to be implemented and extract everything that has to be implemented. This is tedious.
+2. Use the gem in Rspec
+3. Sprinkle your tests to reference the specs
+4. Run the tests
+5. Open the report
+
+### Writing specs 
+
+#### ...in a YAML file
+Specs in a YAML file can be loaded easily when integrated in RSpec; the format is simple:
+
+```yaml
+# Optional, the specification/RFC name
+name: 
+# Optional, the URL to the RFC/specification
+url:
+# Here we are
+specs:
+  # You should at least have one section in the file
+  #
+  # Required. Section/chapter... It's converted to a string when imported
+  - section: 1
+    # Required. Unique section identifier. IDs of the specs in this section will be prefixed by it. Converted to symbol
+    # so only the character class used for symbols should be used.
+    id:
+    # Optional: URL to the section
+    url:
+    specs:
+      # Optional. A spec without an ID will appear with an "unknown" status in the report. It allows you to fill the
+      # specs list without thinking right now how you will identify it.
+      # Spec IDS must be unique across all the specs, but are automatically prefixed with the section's ID, which allows
+      # definition of two specs with the same ID over different sections.
+      - id:
+        # Required. Text must be unique across specs. Imperative verbs have to be bracketed, so you can use the same paragraph
+        # in multiple specs, targeting something different without losing context.
+        text: It [[MUST]] work
+```
+
+For more example, there is a fixture in `spec/fixtures/rfc.yaml`, and the example spec file in `spec/rfc.yaml`.
+
+#### ...programmatically
+
+Declaring specs programmatically can be interesting if you manage somehow to process the original specification
+automatically.
+
+```rb
+# Create an instance of the Specs class: it holds the specs. "name" and "url" are optional
+specs = RSpec::RfcHelper::Specs.new name: 'The easy thing RFC', url: 'https://somewhere'
+
+# Create a section
+spec.add_section number: '1.1', title: 'Implementation', id: :implementation
+
+# Add a spec:
+# ID is optional. A spec without an ID will appear with an "unknown" status in the report. It allows you to fill the
+# specs list without thinking right now how you will identify it.
+# Spec IDS must be unique across all the specs, but are automatically prefixed with the section's ID, which allows
+# definition of two specs with the same ID over different sections.
+#
+# Here, spec ID will be :implementation__do_something
+spec.add section: '1.1', text: 'It [[MUST]] do something', id: :do_something
+
+# For long texts, use heredocs:
+spec.add section: '1.1', text: <<~TXT, id: :do_something
+  Some long text, but the context is important to understand
+  what you [[MUST]] implement, how you SHOULD do it
+  and what you MAY do if you feel like it
+TXT
+```
+
+### Usage in RSpec
+
+#### ...with the spec file: use the module 
+
+```rb
+# spec_helper.rb
+
+require 'rspec-rfc-helper'
+
+RSpec.configure do |config|
+  config.before(:suite) do
+    RSpec::RfcHelper.start_from_file 'path/to/your/spec.yaml'
+  end
+  
+  config.after do |example|
+    RSpec::RfcHelper.add_example example
+  end
+  
+  config.after( :suite) do
+    RSpec::RfcHelper.save_markdown_report 'path/to/report.md'
+  end
+end
+```
+
+#### ...programmatically: use the classes
+
+```rb
+# spec_helper.rb
+
+require 'rspec-rfc-helper'
+
+RSpec.configure do |config|
+  # Putting all the specs in the spec_helper.rb is not a good idea, but as you go programmatically, i'll let you find
+  # a way to organize yourself better.
+  # The main point here is to use the same instance for the definitions and the usages in the RSpec hooks
+  rfc_helper = RSpec::RfcHelper::Spec.new name: 'Plumbus management', url: 'https://somewhere'
+  rfc_helper.add_section #...
+  rfc_helper.add #...
+  # Alternatively, you can still load a file
+  rfc_helper = RSpec::RfcHelper::Spec.new_from_file 'path_to_file'
+  
+  config.after do |example|
+    rfc_helper.add_example example
+  end
+
+  config.after( :suite) do
+    rfc_helper.save_markdown_report 'path/to/report.md'
+  end
+end
+```
+
+### Reference the specs in your suite
+
+RFC Helper uses the RSpec tagging system to track and assign examples to _specs_.
+
+```rb
+RSpec.describe 'Something' do
+  # references spec "spec_id" in section "section1"
+  it 'works', rfc: :section1__spec_id do
+    # ...
+  end
+
+  # references spec "spec_id" in section "section1", and "other_spec_id" in "other_section"
+  it 'works', rfc: [:section1__spec_id, :other_section__other_spec_id] do
+    # ...
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rspec` to run the tests. 
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the 
+version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, 
+push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+### Tools
+
+Well, we use RSpec for testing.
+
+Also, we use Rubocop for code style.
+
+## Contributing
+
+All contributions, ideas and discussions are welcome. Feel free to open issues and feature requests on the 
+[bug tracker](https://gitlab.com/experimentslabs/rspec-rfc-helper/-/issues).
+
+You also can join the ExperimentsLabs [Matrix chatroom](https://matrix.to/#/!qpmxpfSIevwoRUgrxm:matrix.org?via=matrix.org)
+to discuss of the project.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: [:spec, :standard]

data/lib/rspec/rfc_helper/markdown_renderer.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module RSpec
+  module RfcHelper
+    ##
+    # Markdown renderer for specs
+    class MarkdownRenderer
+      STATUS_COLORS = {
+        # Status from Spec class
+        failing:     'red',
+        pass:        'green',
+        has_pending: 'orange',
+        unknown:     'gray',
+
+        # Statuses from RSpec::Core::Example
+        'failed'  => 'red',
+        'pending' => 'orange',
+        'passed'  => 'green',
+      }.freeze
+
+      ##
+      # @param specs [RSpec::RfcHelper::Specs]
+      def initialize(specs)
+        @specs = specs
+      end
+
+      ##
+      # Generates a report in Markdown format.
+      #
+      # @return [String]
+      def render
+        main_table_lines = []
+        detailed_spec_report_blocks = []
+
+        @specs.each do |spec|
+          main_table_lines << main_table_row(spec)
+          detailed_spec_report_blocks << detailed_spec_report_block(spec)
+        end
+
+        <<~MD.chomp
+          #{header}
+
+          #{main_table(main_table_lines)}
+
+          #{detailed_spec_report_blocks.join("\n")}
+        MD
+      end
+
+      ##
+      # Generates the report header
+      #
+      # @return [String]
+      def header
+        title = 'Compliance status'
+        title = "#{title}: #{@specs.name}" if @specs.name
+        url = @specs.specs_url ? "[#{@specs.specs_url}](#{@specs.specs_url})" : '~'
+
+        <<~MD.chomp
+          # #{title}
+
+          Report generated on #{Time.now}
+
+          Source specification: #{url}
+        MD
+      end
+
+      ##
+      # Generates a colored HTML string to represent the spec status
+      #
+      # @param value  [String, Symbol] Status
+      # @param string [String?]        Custom text replacement
+      #
+      # @return [String]
+      def status(value, string = nil)
+        "<span style='color: #{STATUS_COLORS[value]}'>#{string || value}</span>"
+      end
+
+      ##
+      # Makes some replacement in a text
+      #
+      # @param string [String]
+      #
+      # @return [String]
+      def paragraph(string)
+        string.gsub("\n", ' <br> ')
+              .gsub(/\[\[([^\]]*)\]\]/, '<mark>\1</mark>')
+      end
+
+      ##
+      # Generates a spec report block (header and examples table)
+      #
+      # @param spec [RSpec::RfcHelper::Spec]
+      #
+      # @return [String]
+      def detailed_spec_report_block(spec)
+        <<~MD.chomp
+          #{detailed_spec_report_header(spec)}
+
+          #{detailed_spec_report_examples(spec)}
+        MD
+      end
+
+      ##
+      # Generates header for a spec report
+      #
+      # @param spec [RSpec::RfcHelper::Spec]
+      #
+      # @return [String]
+      def detailed_spec_report_header(spec) # rubocop:disable Metrics/AbcSize
+        section = "#{spec.section} - #{@specs.sections[spec.section][:title]}"
+        spec_link = if @specs.sections[spec.section][:url]
+                      "[#{section}](#{@specs.sections[spec.section][:url]})"
+                    else
+                      section
+                    end
+        <<~MD.chomp
+          ## #{status(spec.status, '○')} `#{spec.verb.upcase}` #{spec.id}
+
+          **Specification:** #{spec_link}
+
+          > #{paragraph(spec.text)}
+        MD
+      end
+
+      ##
+      # Generates the example table of a spec report
+      #
+      # @param spec [RSpec::RfcHelper::Spec]
+      #
+      # @return [String]
+      def detailed_spec_report_examples(spec) # rubocop:disable Metrics/MethodLength
+        lines = []
+        spec.examples.each do |example|
+          meta = example.metadata
+          lines << "| #{status(meta[:last_run_status])} | `#{meta[:type]}`: `#{meta[:location]}` |"
+        end
+
+        return "**No related examples**\n" if lines.empty?
+
+        <<~MD.chomp
+          **Examples:**
+
+          | Status | Reference |
+          |:------:|-----------|
+          #{lines.join("\n")}
+
+        MD
+      end
+
+      ##
+      # Generates a row for the main table
+      #
+      # @param spec [RSpec::RfcHelper::Spec]
+      #
+      # @return [String]
+      def main_table_row(spec)
+        id = spec.id ? "`#{spec.id}`" : ''
+        section = @specs.sections[spec.section]
+        section_link = section[:url] ? "[#{spec.section}](#{section[:url]})" : spec.section
+        "| #{status(spec.status)} | #{id} | #{section_link} | #{spec.verb} | #{paragraph(spec.text)} |"
+      end
+
+      ##
+      # Generates the main table
+      #
+      # @param lines [Array<String>] Table rows
+      #
+      # @return [String]
+      def main_table(lines)
+        <<~MD.chomp
+          | status | id | section | verb | text |
+          |-------:|---:|---------|------|------|
+          #{lines.join("\n")}
+        MD
+      end
+    end
+  end
+end

data/lib/rspec/rfc_helper/spec.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RSpec
+  module RfcHelper
+    ##
+    # Represents one spec
+    class Spec
+      attr_reader :id, :section, :verb, :text, :examples
+
+      ##
+      # Initializes a new Spec
+      #
+      # @param section [String]           Section number
+      # @param text    [String]           Paragraph from the RFC.
+      # @param id      [Symbol, NilClass] Unique identifier
+      #
+      # +text+ should have one _verb_ surrounded by brackets, representing what this Spec expects:
+      #
+      #   bad: It [[MUST]] work with a missing user but [[MAY]] log a warning
+      #
+      # Use two Specs instead:
+      #   It [[MUST]] work with a missing user but MAY log a warning
+      #   It MUST work with a missing user but [[MAY]] log a warning
+      #
+      # When nothing is highlighted, spec will appear as a "note".
+      def initialize(section:, text:, id: nil)
+        raise "Missing text ({section: #{section}, text: #{text}, id: #{id})" unless text.is_a?(String) && !text.empty?
+        raise "Missing section ({section: #{section}, text: #{text}, id: #{id})" unless section.is_a?(String) && !section.empty?
+
+        @id       = id
+        @section  = section.to_s
+        @text     = text
+        @examples = []
+        set_verb
+      end
+
+      ##
+      # Determines status from RSpec examples
+      #
+      # @return [:unknown|:pass|:has_pending|:failing] Spec state from all examples
+      #
+      # Statuses:
+      #   unknown: No test currently covers this spec
+      #   failing: At least one example failed
+      #   has_pending: Some examples are pending, other passed
+      #   pass: All examples passed
+      def status
+        value = :unknown
+        @examples.each do |example|
+          return :failing if example.metadata[:last_run_status] == 'failed'
+          return :has_pending if example.metadata[:last_run_status] == 'pending'
+
+          value = :pass
+        end
+
+        value
+      end
+
+      ##
+      # Adds an RSpec example
+      #
+      # @param example [RSpec::Core::Example] RSpec example
+      def add_example(example)
+        @examples << example
+      end
+
+      private
+
+      ##
+      # Determines the verb of interest in the given text; falls back to +:note+
+      #
+      # The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT are to be interpreted as described in RFC2119:
+      # @see https://www.w3.org/TR/activitypub/#bib-RFC2119
+      def set_verb
+        occurrences = @text.scan(/\[\[((?:MUST|SHOULD)(?: NOT)?|MAY)\]\]/)
+        case occurrences.size
+        when 0
+          @verb = :note
+        when 1
+          @verb = occurrences.first.first.downcase.tr(' ', '_').to_sym
+        else
+          raise 'Too much verbs in paragraph' if occurrences.size > 1
+        end
+      end
+    end
+  end
+end

data/lib/rspec/rfc_helper/specs.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+require_relative 'spec'
+
+module RSpec
+  module RfcHelper
+    ##
+    # Spec collection
+    class Specs
+      attr_reader :name, :specs_url, :sections
+
+      ##
+      # Instantiates a Spec collection from a YAML file.
+      #
+      # Note: String keys are expected.
+      #
+      # @param file [String] Path to the specs file
+      #
+      # @return [RSpec::RfcHelper::Specs]
+      def self.new_from_file(file) # rubocop:disable Metrics/AbcSize
+        specs = YAML.load_file(file)
+
+        instance = new name: specs['name'], specs_url: specs['url']
+
+        specs['specs'].each do |section|
+          section_number = section['section'].to_s
+
+          instance.add_section id: section['id'].to_sym, number: section_number, title: section['title'], url: section['url']
+
+          section['specs'].each do |spec|
+            instance.add section: section_number, text: spec['text'], id: spec['id']&.to_sym
+          end
+        end
+
+        instance
+      end
+
+      ##
+      # Instantiate a new list of specs
+      #
+      # @param name      [String?] Specification name
+      # @param specs_url [String?] URL to the full specification
+      def initialize(name: nil, specs_url: nil)
+        @name      = name
+        @specs_url = specs_url
+        @sections  = {}
+        @specs     = []
+      end
+
+      ##
+      # Adds a spec section
+      #
+      # @param number [String]  Section number
+      # @param title  [String]  Section title
+      # @param id     [Symbol]  Unique identifier
+      # @param url    [String?] URL to this section
+      def add_section(number:, title:, id:, url: nil)
+        if @sections.key?(number) || @sections.find { |_number, section| section[:id] == id }
+          raise "Section number #{number} already exists"
+        end
+
+        @sections[number] = { title: title, id: id, url: url }
+      end
+
+      ##
+      # Finds an example by id
+      #
+      # @param id [Symbol] Spec identifier
+      #
+      # @return [RSpec::RfcHelper::Spec]
+      def find(id)
+        @specs.find { |spec| spec.id == id } || raise("Spec not found with id #{id}")
+      end
+
+      ##
+      # Adds a spec to the list
+      #
+      # It will prefix the spec ID with relevant section ID
+      #
+      # @param section [String]  Section number
+      # @param text    [String]  Content
+      # @param id      [Symbol?] Unique section identifier
+      def add(section:, text:, id: nil)
+        if id.is_a? Symbol
+          id = "#{section_id(section)}__#{id}".to_sym
+          raise "Duplicated id #{id}" if ids.include? id
+        end
+
+        @specs << Spec.new(section: section, text: text, id: id)
+      end
+
+      ##
+      # Adds an RSpec example to all the relevant specs
+      #
+      # @param example [RSpec::Core::Example]
+      def add_example(example)
+        ids = example.metadata[:rfc]
+        return if ids.nil? || ids.empty?
+
+        ids = [ids] if ids.is_a? Symbol
+        ids.each do |id|
+          find(id).add_example example
+        end
+      end
+
+      def ids
+        @specs.map(&:id)
+      end
+
+      ##
+      # Delegation
+      def each(&)
+        @specs.each(&)
+      end
+
+      ##
+      # Saves the report in Markdown
+      #
+      # @param file [String] Output file path
+      def save_markdown_report(file)
+        File.write file, RSpec::RfcHelper::MarkdownRenderer.new(self).render
+      end
+
+      private
+
+      ##
+      # @param number [String] Section number
+      #
+      # @return [Symbol] Section ID from its number
+      def section_id(number)
+        section = @sections[number] || raise("Section not found with number #{number}")
+        section[:id]
+      end
+    end
+  end
+end

data/lib/rspec/rfc_helper/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Rspec
+  module RfcHelper
+    VERSION = '0.1.0'
+  end
+end

data/lib/rspec/rfc_helper.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'rfc_helper/version'
+require_relative 'rfc_helper/specs'
+
+module RSpec
+  ##
+  # RSpec module to track specifications with more context
+  module RfcHelper
+    class Error < StandardError; end
+
+    ##
+    # Delegation when using the module as a starting point
+    def self.add_example(example)
+      raise 'Did you start?' unless @specs
+
+      @specs.add_example(example)
+    end
+
+    ##
+    # Delegation when using the module as a starting point
+    def self.start_from_file(file)
+      raise 'Already started' if @specs
+
+      @specs = Specs.new_from_file file
+    end
+
+    def self.save_markdown_report(file)
+      raise 'Did you start?' unless @specs
+
+      @specs.save_markdown_report file
+    end
+  end
+end

data/report.md

@@ -0,0 +1,204 @@
+# Compliance status: RSpec RFC Helper
+
+Report generated on 2023-11-07 22:11:05 +0100
+
+Source specification: [https://gitlab.com/experimentslabs/rspec-rfc-helper/-/blob/main/specification_example.md](https://gitlab.com/experimentslabs/rspec-rfc-helper/-/blob/main/specification_example.md)
+
+| status | id | section | verb | text |
+|-------:|---:|---------|------|------|
+| <span style='color: green'>pass</span> | `features__have_version` | 2.1 | must | The RFC Helper <mark>MUST</mark> have a version number |
+| <span style='color: green'>pass</span> | `features__can_define_spec` | 2.1 | must | The RFC Helper <mark>MUST</mark> have methods to define specs that needs to be enforced and tracked. |
+| <span style='color: gray'>unknown</span> | `features__wrap_verbs` | 2.1 | must | To tackle this issue, the text used in a spec defined for the RFC Helper <mark>MUST</mark> wrap the right verb in the relevant  <br> paragraph into double square brackets, like, for example `<mark>VERB</mark>`. The same paragraph MAY be used in multiple specs, <br> with everytime a different verb wrapper. <br>  |
+| <span style='color: gray'>unknown</span> | `features__use_same_paragraph_twice` | 2.1 | may | To tackle this issue, the text used in a spec defined for the RFC Helper MUST wrap the right verb in the relevant  <br> paragraph into double square brackets, like, for example `<mark>VERB</mark>`. The same paragraph <mark>MAY</mark> be used in multiple specs, <br> with everytime a different verb wrapper. <br>  |
+| <span style='color: green'>pass</span> | `features__identify_specs_with_id` | 2.1 | must | Defined specs also need to be identifiable, so a unique ID <mark>MUST</mark> be assigned to them. |
+| <span style='color: gray'>unknown</span> | `features__no_verb_means_note` | 2.1 | note | When a portion of text is interesting but has no imperative verb in it, it still can be added, and the RFC Helper will <br> give it a status of "note". <br>  |
+| <span style='color: green'>pass</span> | `reporting__rfc_tag` | 2.2 | must | Once the RFC helper is configured in a RSpec suite, it <mark>MUST</mark> handle examples tagged with the `rfc` tag. |
+| <span style='color: green'>pass</span> | `reporting__rfc_with_single_id_or_list` | 2.2 | must | The RFC helper <mark>MUST</mark> handle a single ID, as well as an array of IDs. |
+| <span style='color: green'>pass</span> | `reporting__export_method` | 2.2 | must | The RFC Helper <mark>MUST</mark> have at least one method to export the generated report in a file. |
+| <span style='color: gray'>unknown</span> | `reporting__export_date` | 2.2 | must | The report <mark>MUST</mark> contain the generation date. |
+| <span style='color: gray'>unknown</span> | `usage__two_ways` | 3 | should | To have some flexibility, the helper <mark>SHOULD</mark> be useable in two ways: using the module `RSpec::RfcHelper`, or the classes. <br>  |
+| <span style='color: gray'>unknown</span> | `usage_module__start_method` | 3.1 | must | The `RSpec::RfcHelper` <mark>MUST</mark> have a method to "start" the helper |
+| <span style='color: gray'>unknown</span> | `usage_module__handle_examples` | 3.1 | must | It <mark>MUST</mark> have a method to add examples to specs once they are evaluated |
+| <span style='color: gray'>unknown</span> | `usage_module__export_method` | 3.1 | must | it <mark>MUST</mark> have a method to save the report |
+| <span style='color: gray'>unknown</span> |  | 3.2 | note | The RFC Helper SHOULD be used directly by instantiating a class. |
+| <span style='color: gray'>unknown</span> |  | 3.2 | note | The instance MUST provide methods to add sections |
+| <span style='color: gray'>unknown</span> |  | 3.2 | note | The instance MUST provide methods to define the specs |
+| <span style='color: gray'>unknown</span> |  | 3.2 | note | The instance MUST provide methods to generate the report |
+| <span style='color: gray'>unknown</span> |  | 3.2 | note | The instance MAY provide methods to load sections and specs from a file |
+
+## <span style='color: green'>○</span> `MUST` features__have_version
+
+**Specification:** 2.1 - Features
+
+> The RFC Helper <mark>MUST</mark> have a version number
+
+**Examples:**
+
+| Status | Reference |
+|:------:|-----------|
+| <span style='color: green'>passed</span> | ``: `./spec/rspec/rfc_helper_spec.rb:4` |
+
+## <span style='color: green'>○</span> `MUST` features__can_define_spec
+
+**Specification:** 2.1 - Features
+
+> The RFC Helper <mark>MUST</mark> have methods to define specs that needs to be enforced and tracked.
+
+**Examples:**
+
+| Status | Reference |
+|:------:|-----------|
+| <span style='color: green'>passed</span> | ``: `./spec/rspec/rfc_helper/spec_spec.rb:10` |
+| <span style='color: green'>passed</span> | ``: `./spec/rspec/rfc_helper/specs_spec.rb:64` |
+
+## <span style='color: gray'>○</span> `MUST` features__wrap_verbs
+
+**Specification:** 2.1 - Features
+
+> To tackle this issue, the text used in a spec defined for the RFC Helper <mark>MUST</mark> wrap the right verb in the relevant  <br> paragraph into double square brackets, like, for example `<mark>VERB</mark>`. The same paragraph MAY be used in multiple specs, <br> with everytime a different verb wrapper. <br> 
+
+**No related examples**
+
+## <span style='color: gray'>○</span> `MAY` features__use_same_paragraph_twice
+
+**Specification:** 2.1 - Features
+
+> To tackle this issue, the text used in a spec defined for the RFC Helper MUST wrap the right verb in the relevant  <br> paragraph into double square brackets, like, for example `<mark>VERB</mark>`. The same paragraph <mark>MAY</mark> be used in multiple specs, <br> with everytime a different verb wrapper. <br> 
+
+**No related examples**
+
+## <span style='color: green'>○</span> `MUST` features__identify_specs_with_id
+
+**Specification:** 2.1 - Features
+
+> Defined specs also need to be identifiable, so a unique ID <mark>MUST</mark> be assigned to them.
+
+**Examples:**
+
+| Status | Reference |
+|:------:|-----------|
+| <span style='color: green'>passed</span> | ``: `./spec/rspec/rfc_helper/specs_spec.rb:75` |
+
+## <span style='color: gray'>○</span> `NOTE` features__no_verb_means_note
+
+**Specification:** 2.1 - Features
+
+> When a portion of text is interesting but has no imperative verb in it, it still can be added, and the RFC Helper will <br> give it a status of "note". <br> 
+
+**No related examples**
+
+## <span style='color: green'>○</span> `MUST` reporting__rfc_tag
+
+**Specification:** 2.2 - Reporting
+
+> Once the RFC helper is configured in a RSpec suite, it <mark>MUST</mark> handle examples tagged with the `rfc` tag.
+
+**Examples:**
+
+| Status | Reference |
+|:------:|-----------|
+| <span style='color: green'>passed</span> | ``: `./spec/rspec/rfc_helper/specs_spec.rb:91` |
+
+## <span style='color: green'>○</span> `MUST` reporting__rfc_with_single_id_or_list
+
+**Specification:** 2.2 - Reporting
+
+> The RFC helper <mark>MUST</mark> handle a single ID, as well as an array of IDs.
+
+**Examples:**
+
+| Status | Reference |
+|:------:|-----------|
+| <span style='color: green'>passed</span> | ``: `./spec/rspec/rfc_helper/specs_spec.rb:91` |
+
+## <span style='color: green'>○</span> `MUST` reporting__export_method
+
+**Specification:** 2.2 - Reporting
+
+> The RFC Helper <mark>MUST</mark> have at least one method to export the generated report in a file.
+
+**Examples:**
+
+| Status | Reference |
+|:------:|-----------|
+| <span style='color: green'>passed</span> | ``: `./spec/rspec/rfc_helper/specs_spec.rb:103` |
+
+## <span style='color: gray'>○</span> `MUST` reporting__export_date
+
+**Specification:** 2.2 - Reporting
+
+> The report <mark>MUST</mark> contain the generation date.
+
+**No related examples**
+
+## <span style='color: gray'>○</span> `SHOULD` usage__two_ways
+
+**Specification:** 3 - Usage
+
+> To have some flexibility, the helper <mark>SHOULD</mark> be useable in two ways: using the module `RSpec::RfcHelper`, or the classes. <br> 
+
+**No related examples**
+
+## <span style='color: gray'>○</span> `MUST` usage_module__start_method
+
+**Specification:** 3.1 - Using the module
+
+> The `RSpec::RfcHelper` <mark>MUST</mark> have a method to "start" the helper
+
+**No related examples**
+
+## <span style='color: gray'>○</span> `MUST` usage_module__handle_examples
+
+**Specification:** 3.1 - Using the module
+
+> It <mark>MUST</mark> have a method to add examples to specs once they are evaluated
+
+**No related examples**
+
+## <span style='color: gray'>○</span> `MUST` usage_module__export_method
+
+**Specification:** 3.1 - Using the module
+
+> it <mark>MUST</mark> have a method to save the report
+
+**No related examples**
+
+## <span style='color: gray'>○</span> `NOTE` 
+
+**Specification:** 3.2 - Using the classes
+
+> The RFC Helper SHOULD be used directly by instantiating a class.
+
+**No related examples**
+
+## <span style='color: gray'>○</span> `NOTE` 
+
+**Specification:** 3.2 - Using the classes
+
+> The instance MUST provide methods to add sections
+
+**No related examples**
+
+## <span style='color: gray'>○</span> `NOTE` 
+
+**Specification:** 3.2 - Using the classes
+
+> The instance MUST provide methods to define the specs
+
+**No related examples**
+
+## <span style='color: gray'>○</span> `NOTE` 
+
+**Specification:** 3.2 - Using the classes
+
+> The instance MUST provide methods to generate the report
+
+**No related examples**
+
+## <span style='color: gray'>○</span> `NOTE` 
+
+**Specification:** 3.2 - Using the classes
+
+> The instance MAY provide methods to load sections and specs from a file
+
+**No related examples**

data/sig/rspec/rfc_helper/markdown_renderer.rbs

@@ -0,0 +1,27 @@
+module RSpec
+  module RfcHelper
+    class MarkdownRenderer
+      STATUS_COLORS: Hash[String|Symbol, String]
+
+      @specs: Specs
+
+      def detailed_spec_report_block: -> String
+
+      def detailed_spec_report_examples: -> String
+
+      def detailed_spec_report_header: -> String
+
+      def header: -> String
+
+      def main_table: -> String
+
+      def main_table_row: -> String
+
+      def paragraph: -> String
+
+      def render: -> String
+
+      def status: -> String
+    end
+  end
+end

data/sig/rspec/rfc_helper/spec.rbs

@@ -0,0 +1,19 @@
+module RSpec
+  module RfcHelper
+    class Spec
+      attr_reader id: Symbol?
+      attr_reader section: String
+      attr_reader text: String
+      attr_reader verb: Symbol
+      attr_reader examples: Array[RSpec::Core::Example]
+
+      def add_example: -> void
+
+      def status: -> Symbol
+
+      private
+
+      def set_verb: -> void
+    end
+  end
+end

data/sig/rspec/rfc_helper/specs.rbs

@@ -0,0 +1,25 @@
+module RSpec
+  module RfcHelper
+    class Specs
+      @name: String?
+      @sections: Hash[String, {id: Symbol, title: String, url: String? }]
+      @specs: Array[Spec]
+      @specs_url: String?
+
+      def self.new_from_file: -> Specs
+
+      attr_reader name: String?
+      attr_reader sections: Hash[String, {id: Symbol, title: String, url: String? }]
+      attr_reader specs_url: String?
+
+      def add: -> void
+      def add_example: -> void
+      def add_section: -> void
+      def each: -> void
+      def find: -> Spec
+      def ids: -> Array[Symbol]
+      def save_markdown_report: -> void
+      def section_id: -> Symbol
+    end
+  end
+end

data/sig/rspec/rfc_helper.rbs

@@ -0,0 +1,12 @@
+module RSpec
+  module RfcHelper
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+    @specs: ::RSpec::RfcHelper::Specs
+
+    def self.add_example: -> void
+    def self.load_specs: -> void
+    def self.start_from_file: -> void
+  end
+end

data/specification_example.md

@@ -0,0 +1,74 @@
+# RSpec RFC Helper Specification
+
+Well... kind of, it's for the example.
+
+This is the specification on how `rspec-rfc-helper` must behave and should be used in a test suite.
+
+They somehow lack of substance, as I'm not a spec writer...
+
+### 1 - Overview
+
+RSpec RFC Helper (_RFC Helper_) is a RSpec module to help implement complicated specs: it is often hard to keep track of
+the external specifications and their implementation; leaving comments in the code is not ideal to understand the state
+of the overall implementation.
+
+### 2 - Features
+
+#### 2.1 Spec definition
+
+The RFC Helper MUST have a version number
+
+The RFC Helper MUST have methods to define specs that needs to be enforced and tracked.
+
+Sometimes, in RFC and other formal documents, the same paragraph can have multiple imperative verbs as `MUST`, `SHOULD`,
+..., making it complicated to break down and summarize.
+To tackle this issue, the text used in a spec defined for the RFC Helper MUST wrap the right verb in the relevant
+paragraph into double square brackets, like, for example `[[VERB]]`. The same paragraph MAY be used in multiple specs,
+with everytime a different verb wrapper.
+
+Defined specs also need to be identifiable, so a unique ID MUST be assigned to them.
+
+When a portion of text is interesting but has no imperative verb in it, it still can be added, and the RFC Helper will
+give it a status of "note".
+
+Specifications are often separated in multiple sections. These sections SHOULD be used to group the specs together.
+
+#### 2.2 Reporting
+
+Once the RFC helper is configured in a RSpec suite, it MUST handle examples tagged with the `rfc` tag.
+
+As a value, developers needs to specify one or many spec IDs targeted by the example. The RFC helper MUST handle a
+single ID, as well as an array of IDs.
+
+The RFC Helper MUST have at least one method to export the generated report in a file.
+
+The report MUST contain the generation date.
+
+### 3 - Usage
+
+To have some flexibility, the helper SHOULD be useable in two ways : using the module `RSpec::RfcHelper`, or the classes.
+
+#### 3.1 Using the module
+
+The `RSpec::RfcHelper` MUST have a method to "start" the helper, reading a file with sections and specs. It MUST have a
+method to add examples to specs once they are evaluated, and it MUST have a method to save the report.
+
+Using the module is similar to using a singleton. It has its goods and bad sides.
+
+#### 3.2 Using the classes
+
+The RFC Helper SHOULD be used directly by instantiating a class.
+
+The instance MUST provide methods to add sections
+
+The instance MUST provide methods to define the specs
+
+The instance MUST provide methods to generate the report
+
+The instance MAY provide methods to load sections and specs from a file
+
+Using the classes is a bit more complex but allows more flexibility.
+
+### 3 - Final words
+
+Yeah! that's some specification!

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: rspec-rfc-helper
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Manuel Tancoigne
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-11-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Helps keeping track of specifications with more context than just RSpec
+  examples
+email:
+- manu@experimentslabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/rspec/rfc_helper.rb
+- lib/rspec/rfc_helper/markdown_renderer.rb
+- lib/rspec/rfc_helper/spec.rb
+- lib/rspec/rfc_helper/specs.rb
+- lib/rspec/rfc_helper/version.rb
+- report.md
+- sig/rspec/rfc_helper.rbs
+- sig/rspec/rfc_helper/markdown_renderer.rbs
+- sig/rspec/rfc_helper/spec.rbs
+- sig/rspec/rfc_helper/specs.rbs
+- specification_example.md
+homepage: https://gitlab.com/experimentslabs/rspec-rfc-helper
+licenses: []
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://gitlab.com/experimentslabs/rspec-rfc-helper
+  source_code_uri: https://gitlab.com/experimentslabs/rspec-rfc-helper
+  changelog_uri: https://gitlab.com/experimentslabs/rspec-rfc-helper/-/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.15
+signing_key:
+specification_version: 4
+summary: RSpec plugin to track RFC compliance
+test_files: []