rspec-usecases 0.0.12 → 0.0.37

data/docs/test.md

@@ -0,0 +1,39 @@
+# markdown title
+
+markdown description
+
+## valid level 1 usecase #1
+
+first encountered usecases
+
+### SomeClass.some_method
+
+Calls some_method on SomeClass
+
+- this outcome has a title
+- this outcome has a note
+  outcome note
+
+---
+
+- this outcome has an hr
+
+#### this is some unknown code
+
+```
+# Source code goes here
+```
+
+#### this is some ruby code
+
+```
+# Source code goes here
+```
+
+## valid level 2 usecase #1.1
+
+override the summary
+
+## valid level 2 usecase #1.2
+
+## valid level 1 usecase #2

data/lib/rspec/usecases.rb

@@ -1,10 +1,26 @@
 # frozen_string_literal: true
 
 require 'rspec/usecases/version'
-require 'rspec/usecases/usecase'
-require 'rspec/usecases/content'
-require 'rspec/usecases/content_code'
-require 'rspec/usecases/content_outcome'
+require 'rspec/usecases/configure'
+require 'rspec/usecases/contents/base_content'
+require 'rspec/usecases/contents/code'
+require 'rspec/usecases/contents/outcome'
+require 'rspec/usecases/groups/base_group'
+require 'rspec/usecases/groups/group'
+require 'rspec/usecases/groups/usecase'
+require 'rspec/usecases/document'
+require 'rspec/usecases/documentor'
+require 'rspec/usecases/generator/base_generator'
+require 'rspec/usecases/generator/json_generator'
+require 'rspec/usecases/generator/debug_generator'
+require 'rspec/usecases/generator/markdown_generator'
+require 'rspec/usecases/helpers/uc_file_as_markdown_content'
+require 'rspec/usecases/helpers/uc_grab_lines'
+require 'rspec/usecases/options/dynamic_options'
+require 'rspec/usecases/options/document_options'
+require 'rspec/usecases/options/debug_options'
+require 'rspec/usecases/options/markdown_options'
+require 'rspec/usecases/options/json_options'
 
 module Rspec
   module Usecases

data/lib/rspec/usecases/configure.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Rspec
+  # Usecases
+  module Usecases
+    # Configure can be called to setup rspec example and
+    # example_group names that make sense for documentation
+    # rubocop:disable Layout/ExtraSpacing
+    def self.configure(config)
+      # Feels wrong, as this is overriding context which could effect other libraries
+      # it would be nice to get a handle on context and update it, rather then just
+      # overriding it.
+      #
+      # or maybe I have to stop using context in deep hierarchies and use a different
+      # example group name such as group
+      config.alias_example_group_to :context  , usecase: false
+      config.alias_example_group_to :describe , usecase: false
+
+      config.alias_example_group_to :usecase  , usecase: true  , group_type: :usecase
+      config.alias_example_group_to :xusecase , usecase: false , group_type: :usecase
+
+      config.alias_example_group_to :group    , usecase: true  , group_type: :group
+      config.alias_example_group_to :xgroup   , usecase: false , group_type: :group
+
+      config.alias_example_to :code       , content_type: :code
+      config.alias_example_to :ruby       , content_type: :code, code_type: :ruby
+      config.alias_example_to :fruby      , content_type: :code, code_type: :ruby       , focus: true
+      config.alias_example_to :css        , content_type: :code, code_type: :css
+      config.alias_example_to :js         , content_type: :code, code_type: :javascript
+      config.alias_example_to :javascript , content_type: :code, code_type: :javascript
+
+      # This may need to be it's own type
+      config.alias_example_to :content    , content_type: :content
+      config.alias_example_to :outcome    , content_type: :outcome
+
+      config.extend Rspec::Usecases::Helpers
+    end
+    # rubocop:enable Layout/ExtraSpacing
+  end
+end

data/lib/rspec/usecases/contents/base_content.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+# require 'rspec/usecases/content'
+
+module Rspec
+  module Usecases
+    module Contents
+      # BaseContent
+      class BaseContent
+        METHOD_NAMES = %w[outcome code ruby css js javascript].join('|').freeze
+        EXTRACT_CONTENT_REX = /
+          (?<bos>^)                             # beginning of string
+          (?<indent>\s*)                        # find the indent before the method
+          (?<method_type>#{METHOD_NAMES})\s     # grab the method name from predefined list
+          (?<method_signature>.*?)              # grab the method signature which is every thing up to the first do
+          (?<method_open>do)                    # code comes after the first do
+          (?<content>.*)                        # content is what we want
+          (?<method_closure>end)\z              # the end keyword at the end of string is where the content finishes
+        /xm.freeze
+
+        # title
+        attr_accessor :title
+
+        # :type
+        attr_accessor :type
+
+        # metadata
+        attr_accessor :metadata
+
+        # source
+        attr_accessor :source
+
+        # is_hr
+        attr_accessor :is_hr
+
+        def self.parse(example)
+          # return nil if example.description.nil?# || example.description.strip.length.zero?
+          return nil if example.metadata[:content_type].nil?
+
+          result = get_instance(example)
+
+          result&.parse_block_source(example)
+
+          result
+        end
+
+        def self.get_instance(example)
+          type = example.metadata[:content_type].to_s
+
+          begin
+            klass = Module.const_get("Rspec::Usecases::Contents::#{type.capitalize}")
+            klass.new(type, example)
+          rescue NameError
+            # TODO: Logging
+            puts "UNKNOWN CONTENT TYPE: #{type}"
+            nil
+          rescue StandardError => e
+            # TODO: Logging
+            puts e
+            nil
+          end
+        end
+
+        def initialize(type, example)
+          title = example.description.strip
+          @title = title.start_with?('example at .') ? '' : title
+          @type = type
+
+          # May want to delegate this to an OpenStruct called options
+          @is_hr = !!example.metadata[:hr]
+        end
+
+        # Source code for rspec is living on the metadata[:block].source location
+        # Have not written a test for this yet
+        def parse_block_source(example)
+          unless example.metadata[:source_override].nil?
+            @source = example.metadata[:source_override]
+            return
+          end
+
+          source = get_source(example)
+
+          # NOTE: Need to investigate how RSpec deals with code, see:
+          # https://github.com/rspec/rspec-core/blob/fe3084758857f0714f05ada44a18f1dfe9bf7a7e/spec/rspec/core/formatters/snippet_extractor_spec.rb
+          # https://github.com/rspec/rspec-core/blob/fe3084758857f0714f05ada44a18f1dfe9bf7a7e/lib/rspec/core/formatters/html_formatter.rb
+          segments = source.match(EXTRACT_CONTENT_REX)
+
+          unless defined?(segments) && defined?(segments[:content])
+            @source = ''
+            return
+          end
+          @source = remove_wasted_indentation(segments[:content])
+          @source
+        rescue StandardError => e
+          puts 'Could not parse source'
+          puts example.metadata
+          puts e
+        end
+
+        def get_source(example)
+          if defined?(example.metadata) && defined?(example.metadata[:block]) && defined?(example.metadata[:block].source)
+            example.metadata[:block].source.strip
+          else
+            ''
+          end
+        end
+
+        def remove_wasted_indentation(content)
+          lines = content.lines
+
+          whitespace = /^\s*/
+
+          # find the small whitespace sequence
+          # at beginning of line that is not \n or blank
+          # and grab the smallest value
+          indent = lines
+                   .map    { |l| l.match(whitespace).to_s }
+                   .reject { |s| ["\n", ''].include?(s) }
+                   .min_by(&:length)
+
+          # remove the smallest indentation from beginning
+          # of all lines, this is the wasted indentation
+          rex_indent = /^#{indent}/
+
+          lines.each { |l| l.gsub!(rex_indent, '') }
+
+          # convert back to a content string
+          lines.join.strip
+        end
+
+        def to_h
+          {
+            title: title,
+            type: type,
+            source: source,
+            is_hr: is_hr
+            # options: [
+            #   is_hr: is_hr
+            # ]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rspec/usecases/contents/code.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Rspec
+  module Usecases
+    module Contents
+      # Code
+      class Code < Rspec::Usecases::Contents::BaseContent
+        # # Source code
+        # attr_accessor :code
+
+        # Type of code, ruby, javascript, css etc.
+        attr_accessor :code_type
+
+        # Note
+        attr_accessor :note
+
+        def initialize(type, example)
+          super(type, example)
+
+          @code_type = example.metadata[:code_type].to_s
+          @note = example.metadata[:note].to_s
+        end
+
+        def to_h
+          {
+            code_type: code_type,
+            note: note
+          }.merge(super.to_h)
+        end
+      end
+    end
+  end
+end

data/lib/rspec/usecases/contents/outcome.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Rspec
+  module Usecases
+    module Contents
+      # Content Outcome
+      class Outcome < Rspec::Usecases::Contents::BaseContent
+        # Note, similar to summary on usecase, but due to
+        # metadata inheritance, I needed to use a different
+        # property name
+        attr_accessor :note
+
+        def initialize(type, example)
+          super(type, example)
+
+          @note = example.metadata[:note].to_s
+        end
+
+        def to_h
+          {
+            note: note
+          }.merge(super.to_h)
+        end
+      end
+    end
+  end
+end

data/lib/rspec/usecases/document.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Rspec
+  module Usecases
+    # A document represents a list of groups, the main group type being usecases
+    #
+    # A document can have a title, description and a list of groups
+    # A group is just an Rspec context or describe block with the
+    # attribute usecase set to true - usecase: true
+    #
+    # The list of groups can have their own child list of
+    # groups that can go down to any practical depth.
+    class Document
+      attr_reader :title
+      attr_reader :description
+      attr_reader :groups
+      attr_reader :options
+
+      def initialize(root_example_group, **options)
+        @root = root_example_group
+        @options = if options.nil? || options.empty?
+                     Rspec::Usecases::Options::DocumentOptions.new(@root.metadata)
+                   else
+                     Rspec::Usecases::Options::DocumentOptions.new(options)
+                   end
+
+        parse_title_description
+        build_groups
+      end
+
+      def json?
+        options.json.active?
+      end
+
+      def debug?
+        options.debug.active?
+      end
+
+      def markdown?
+        options.markdown.active?
+      end
+
+      def skip_render?
+        @skip_render
+      end
+
+      def to_h
+        {
+          settings: {
+            json: json?,
+            debug: debug?,
+            markdown: markdown?,
+            markdown_file: markdown_file,
+            markdown_prettier: markdown_prettier?,
+            markdown_open: markdown_open?,
+            skip_render: skip_render?
+          },
+          title: title,
+          description: description,
+          groups: groups.map(&:to_h)
+        }
+      end
+
+      private
+
+      # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/AbcSize
+      def value_to_type(value, default_value: :detail, fail_value: :skip)
+        if value.nil?
+          [fail_value]
+        elsif !!value == value
+          value ? [default_value] : [fail_value]
+        elsif value.is_a?(String)
+          [value.to_sym]
+        elsif value.is_a?(Symbol)
+          [value]
+        elsif value.is_a?(Array)
+          value.map do |v|
+            case value
+            when Symbol
+              v
+            when String
+              v.to_sym
+            when !!value
+              value ? default_value : fail_value
+            else
+              raise Rspec::Usecases::Error, 'Unknown option paramater'
+            end
+          end
+        else
+          raise Rspec::Usecases::Error, 'Unknown option paramater'
+        end
+      end
+      # rubocop:enable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/AbcSize
+
+      def extract_meta_options
+        {
+          json: @root.metadata[:json],
+          debug: @root.metadata[:debug],
+          markdown: @root.metadata[:markdown],
+          document_title: @root.metadata[:document_title],
+          document_description: @root.metadata[:document_description]
+
+        }
+      end
+
+      def parse_title_description
+        @skip_render = !!@root.metadata[:skip_render] && @root.metadata[:skip_render] == true
+
+        # # Document data
+        @title = @root.metadata[:document_title] || ''
+        @description = @root.metadata[:document_description] || ''
+      end
+
+      def build_groups
+        @groups = []
+
+        # This is a documentor setting
+        return unless @root.metadata[:usecases]
+
+        # Get a list of describe or context blocks with the :usecase
+        # metadata flag, or use `usecase 'xyz' do end` in your code.
+        @groups = flatten_group_hierarchy(@root, 1)
+
+        # debug
+      end
+
+      # rubocop:disable Metrics/AbcSize
+      def flatten_group_hierarchy(example_group, level)
+        # puts "name            : #{example_group.name}"
+        # puts "entering level  : #{level}"
+        # if example_group.metadata[:usecase] == true
+        #   group = Rspec::Usecases::Groups::Usecase.parse(example_group.name, example_group)
+        #   return [group]
+        # end
+
+        # { name: example_group.name, is_group: example_group.metadata[:group], child_count: example_group.children.length }
+        # { name: child_example_group.name, is_group: child_example_group.metadata[:group], child_count: child_example_group.children.length }
+        level_groups = []
+
+        example_group.children.each do |child_example_group|
+          if child_example_group.metadata[:usecase] == true
+            raise(Rspec::Usecases::Error, 'Group required') if child_example_group.metadata[:group_type].nil?
+
+            group = Rspec::Usecases::Groups::BaseGroup.parse(child_example_group.name, child_example_group)
+
+            child_groups = flatten_group_hierarchy(child_example_group, level + 1)
+
+            group.groups = child_groups
+
+            groups.push group
+
+            level_groups.push group
+          else
+            # puts 'keep looking'
+            sibling_groups = flatten_group_hierarchy(child_example_group, level)
+
+            # puts "level            : #{level}"
+            # puts "level_groups   : #{level_groups.length}"
+            # puts "sibling_groups : #{sibling_groups.length}"
+
+            level_groups += sibling_groups
+          end
+        end
+
+        # puts "leaving level   : #{level}"
+        # puts "count for level : #{level_groups.length}"
+
+        level_groups
+      end
+      # rubocop:enable Metrics/AbcSize
+    end
+  end
+end