rspec-documentation 0.0.1 → 0.0.3

data/lib/rspec_documentation/html_element.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Receives a spec manifest and generates a `Kramdown::Document` contaning an HTML node with a
+  # tabbed view displaying the example's code, its output and, if format is `:html`, the rendered
+  # HTML of the output. Injected into the parsed `Kramdown::Document` for the root Markdown file,
+  # replacing the code block it was produced from.
+  class HtmlElement
+    def initialize(spec:)
+      @spec = spec
+    end
+
+    def element
+      Kramdown::Document.new(tabbed_spec, input: 'html').root
+    end
+
+    def code_source
+      formatter = Rouge::Formatters::HTML.new
+      lexer = Rouge::Lexers::Ruby.new
+      Formatters.with_translated_html_entities(formatter.format(lexer.lex(spec.source)))
+    end
+
+    def prettified_output
+      Formatters.with_translated_html_entities(formatter.prettified_output)
+    end
+
+    def rendered_output
+      return formatter.rendered_output if render_raw?
+
+      Formatters.with_translated_html_entities(formatter.rendered_output)
+    end
+
+    def render_raw?
+      formatter.render_raw?
+    end
+
+    def element_id
+      @element_id ||= SecureRandom.uuid
+    end
+
+    private
+
+    attr_reader :spec
+
+    def formatter
+      @formatter ||= {
+        html: Formatters::Html,
+        ansi: Formatters::Ansi,
+        json: Formatters::Json,
+        yaml: Formatters::Yaml
+      }.fetch(spec.format, Formatters::Ruby).new(subject: spec.subject)
+    end
+
+    def tabbed_spec
+      RSpecDocumentation.template('tabbed_spec').result(binding)
+    end
+  end
+end

data/lib/rspec_documentation/javascript_bundle.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Compiles Javascript assets into a single file.
+  class JavascriptBundle
+    def flush
+      Util.bundle_dir.join('assets').mkpath
+      javascript_bundle_path.write(RSpecDocumentation.template(:layout, :js).result(binding))
+    end
+
+    private
+
+    def javascript_bundle_path
+      Util.bundle_dir.join('assets/bundle.js')
+    end
+  end
+end

data/lib/rspec_documentation/markdown_renderer.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  class MarkdownRenderer < Redcarpet::Render::HTML
+    include Rouge::Plugins::Redcarpet
+  end
+end

data/lib/rspec_documentation/page_collection.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Builds content for a collection of page paths, collates failures from embedded examples.
+  # Writes the final structure to disk.
+  class PageCollection
+    attr_reader :failures, :page_paths
+
+    def initialize(page_paths:)
+      @page_paths = page_paths.sort
+      @buffer = {}
+      @failures = []
+    end
+
+    def generate
+      page_paths.zip(documents).each do |path, document|
+        buffer[bundle_path_for(path)] = document.render
+        failures.concat(document.failures)
+      end
+    end
+
+    def documents
+      @documents ||= page_paths.map do |path|
+        Document.new(document: path.read, path: path, page_tree: page_tree(path: path))
+      end
+    end
+
+    def flush
+      Util.bundle_dir.rmtree if Util.bundle_dir.directory?
+      Util.bundle_dir.mkpath
+
+      buffer.each do |path, content|
+        path.dirname.mkpath
+        Util.bundle_path(path).write(content)
+      end
+      write_index unless buffer.empty?
+    end
+
+    def examples_count
+      documents.map(&:specs).flatten.size
+    end
+
+    private
+
+    attr_reader :buffer
+
+    def write_index
+      _path, content = buffer.first
+      Util.bundle_index_path.write(content)
+    end
+
+    def page_tree(path:)
+      PageTree.new(page_paths: page_paths, current_path: path)
+    end
+
+    def bundle_path_for(path)
+      Util.bundle_path(path)
+    end
+
+    def root_path
+      Pathname.new(Dir.pwd).join('rspec-documentation')
+    end
+  end
+end

data/lib/rspec_documentation/page_tree.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # A hierarchical structure of all pages in the documentation tree. Used for rendering a navigation section.
+  class PageTree
+    def initialize(page_paths:, current_path:)
+      @page_paths = page_paths
+      @current_path = current_path
+      @structure = {}
+      @nodes = []
+    end
+
+    def elements
+      build_nodes(
+        root: tree['rspec-documentation']['pages'],
+        path: root_path.join('rspec-documentation/pages')
+      )
+      nodes.flatten.compact
+    end
+
+    private
+
+    attr_reader :page_paths, :structure, :nodes, :current_path
+
+    def tree
+      @tree ||= begin
+        build_tree
+        structure
+      end
+    end
+
+    def build_nodes(root:, path:)
+      root[:children].sort.each do |child|
+        node = page_tree_node(path: path, child: child)
+        next nil if node.nil?
+
+        li_open, *li_body, li_close = node
+        nodes.push(li_open)
+        nodes.concat(li_body)
+        push_children(root: root, path: path, child: child)
+        nodes.push(li_close)
+      end
+    end
+
+    def push_children(root:, path:, child:)
+      nodes.push('<ol>')
+      build_nodes(root: root[child], path: path.join(child)) unless root[child].nil?
+      nodes.last == '<ol>' ? nodes.pop : nodes.push('</ol>')
+    end
+
+    def build_tree(branch: structure, depth: 0)
+      normalized_paths.each do |path|
+        first, second, *rest = path_segments(path: path, depth: depth)
+        next if second.nil?
+
+        branch[first] ||= {}
+        branch[first][:children] ||= Set.new
+        branch[first][:children].add(second)
+        build_tree(branch: branch[first], depth: depth + 1)
+      end
+    end
+
+    def path_segments(path:, depth:)
+      path.to_s.split('/')[depth..]
+    end
+
+    def root_path
+      @root_path ||= Pathname.new(Dir.pwd)
+    end
+
+    def normalized_paths
+      @normalized_paths ||= page_paths.sort.map do |path|
+        path.relative_path_from(root_path)
+      end
+    end
+
+    def page_tree_node(path:, child:)
+      PageTreeElement.new(path: path, child: child, current_path: current_path).node
+    end
+  end
+end

data/lib/rspec_documentation/page_tree_element.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # An element in a page tree, generates a single entry as a list item, linked to the relevant
+  # document (or just a text entry if no document exists, i.e. if it is a directory without an
+  # index file).
+  class PageTreeElement
+    def initialize(path:, child:, current_path:)
+      @path = path
+      @child = child
+      @current_path = current_path
+      @nodes = []
+      raise MissingFileError, "Missing file: #{entry_path.relative_path_from(Util.base_dir)}" unless entry?
+    end
+
+    def node
+      return nil if entry_and_directory?
+
+      nodes.push(li_open)
+      nodes.push(link)
+      nodes.push('</li>')
+      nodes
+    end
+
+    private
+
+    attr_reader :path, :child, :current_path, :nodes
+
+    def entry_and_directory?
+      return false unless path.join(child).sub_ext('.md').file?
+      return false unless path.join(child).sub_ext('').directory?
+      return false unless path.join(child).file?
+
+      true
+    end
+
+    def entry_path
+      path.join(child).sub_ext('.md')
+    end
+
+    def entry?
+      entry_path.file?
+    end
+
+    def li_open
+      "<li id='#{Util.path_id(path.join(child))}' #{active_class} data-list-item-id='##{path_id}' " \
+        "data-parent-id='##{parent_path_id}'>"
+    end
+
+    def link
+      "<a #{active_class} href='#{href}'>#{title}</a>"
+    end
+
+    def path_id
+      @path_id ||= Util.path_id(path.join(child))
+    end
+
+    def parent_path_id
+      @parent_path_id ||= Util.path_id(path)
+    end
+
+    def active_class
+      active? ? 'class="active"' : nil
+    end
+
+    def href
+      Util.href(path.join(child))
+    end
+
+    def active?
+      Util.href(current_path) == href
+    end
+
+    def title
+      Util.label(child)
+    end
+  end
+end

data/lib/rspec_documentation/parsed_document.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # A parsed Markdown file, provides matched RSpec examples from the document and their location.
+  class ParsedDocument
+    attr_reader :failures
+
+    def initialize(document, path:)
+      @document = Kramdown::Document.new(document, input: 'GFM', syntax_highlighter: 'rouge')
+      @path = path
+      @failures = []
+    end
+
+    def html
+      document.to_html
+    end
+
+    def execute_and_substitute_examples!
+      specs.each do |spec|
+        spec.run
+        break failures << spec.failure unless spec.failure.nil?
+
+        spec.parent.children[spec.index] = spec_element(spec)
+      end
+    end
+
+    def specs
+      @specs ||= recursive_specs
+    end
+
+    private
+
+    attr_reader :document, :path
+
+    def recursive_specs(element: document.root)
+      element.children.each.with_index.map do |child, index|
+        next recursive_specs(element: child) unless child.children.empty?
+        next nil unless rspec_codeblock?(child)
+
+        spec_for(element: child, parent: element, index: index)
+      end.flatten.compact
+    end
+
+    def rspec_codeblock?(element)
+      return false unless element.type == :codeblock
+      return false unless element.options.key?(:lang)
+
+      element.options[:lang] == 'rspec' || element.options[:lang].start_with?('rspec:')
+    end
+
+    def spec_for(element:, parent:, index:)
+      Spec.new(
+        spec: element.value,
+        format: element.options[:lang].partition(':').last,
+        parent: parent,
+        index: index,
+        path: path,
+        location: element.options[:location]
+      )
+    end
+
+    def spec_element(spec)
+      Kramdown::Element.new(:html_element, 'div', { location: spec.location }).tap do |element|
+        element.children = HtmlElement.new(spec: spec).element.children
+      end
+    end
+
+    def report_error(spec)
+      $stderr.write(spec.failure.message)
+    end
+  end
+end

data/lib/rspec_documentation/project_initialization.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Initializes a new project if `rspec-documentation/` directory is empty.
+  class ProjectInitialization
+    include Paintbrush
+
+    def flush
+      print_welcome
+      create_base_dir
+      create_sample_files
+      print_initialization_complete
+    end
+
+    private
+
+    def print_welcome
+      warn(paintbrush { blue "\nWelcome to #{cyan 'RSpec Documentation'}. A new project is being initialized.\n" })
+      warn(paintbrush { blue "If you want undo at any point, simply delete #{cyan 'rspec-documentation/'}.\n" })
+    end
+
+    def create_base_dir
+      Util.base_dir.mkpath
+      print_created(Util.base_dir)
+    end
+
+    def create_sample_files
+      sample_files.each do |sample_file|
+        Util.base_dir.join(sample_file).sub_ext('.md').write(RSpecDocumentation.template(sample_file, :md).result)
+        print_created(Util.base_dir.join(sample_file).sub_ext('.md'))
+      end
+    end
+
+    def print_created(path)
+      warn(paintbrush { "   #{green_b 'create'} #{cyan path.relative_path_from(pwd)}" })
+    end
+
+    def print_initialization_complete
+      warn(paintbrush do
+        blue "\nYour documentation project has been #{green 'initialized'} wlth smoe example pages."
+      end)
+    end
+
+    def pwd
+      Pathname.new(Dir.pwd)
+    end
+
+    def sample_files
+      %w[000-Introduction 010-Usage 500-License]
+    end
+  end
+end

data/lib/rspec_documentation/rspec/failure.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  module RSpec
+    # Stores information about a failed RSpec example. Thin wrapper around `RSpec::Failure`.
+    class Failure
+      include Paintbrush
+
+      attr_reader :spec
+
+      def initialize(cause:, spec:)
+        @cause = cause
+        @spec = spec
+      end
+
+      def message
+        "\n#{formatted_header}\n\n#{formatted_source}\n\n#{formatted_cause}\n\n"
+      end
+
+      private
+
+      attr_reader :cause
+
+      def formatted_header
+        paintbrush { cyan indented("# #{path}:#{spec.location}") }
+      end
+
+      def path
+        spec.path.relative_path_from(Pathname.new(Dir.pwd))
+      end
+
+      def formatted_source
+        paintbrush { white indented(spec.source) }
+      end
+
+      def formatted_cause
+        paintbrush { red indented(without_anonymous_group_text(cause.message)) }
+      end
+
+      def indented(text)
+        text.split("\n").map { |line| "    #{line}" }.join("\n")
+      end
+
+      # If an error occurs outside of a test, RSpec will provide an error to the Reporter
+      # referring to an anonymous group due to the way specs are evaluated. This does not help
+      # with debugging so we remove it. TODO: Find a better way ?
+      def without_anonymous_group_text(text)
+        text&.gsub(/ for #<RSpec::ExampleGroups::Anonymous.*$/, '')
+      end
+    end
+  end
+end

data/lib/rspec_documentation/rspec.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'rspec/failure'
+
+module RSpecDocumentation
+  # Provides various classes that wrap or interface RSpec internals.
+  module RSpec
+    def self.with_failure_notifier(callable, &block)
+      ::RSpec::Support.with_failure_notifier(callable, &block)
+    end
+  end
+end

data/lib/rspec_documentation/spec.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Executes specs from a Markdown code block and provides the outcome in the appropriate format.
+  class Spec
+    attr_reader :parent, :location, :index, :format, :path
+
+    @durations = []
+
+    class << self
+      attr_accessor :subjects, :durations
+    end
+
+    def initialize(spec:, format:, parent:, location:, path:, index:) # rubocop:disable Metrics/ParameterLists
+      @spec = spec
+      @format = format.empty? ? :plaintext : format.to_sym
+      @parent = parent
+      @location = location
+      @path = path
+      @index = index
+      @failures = []
+    end
+
+    def subject
+      raise Error, "Code block did not define an example (e.g. with `it`).\n#{spec}" if examples.empty?
+      raise Error, "Code block did not define a subject:\n#{spec}" if subjects.empty?
+      raise Error, "Cannot define more than one example per code block:\n#{spec}" if subjects.size > 1
+
+      subjects.last
+    end
+
+    def source
+      spec
+    end
+
+    def failure
+      failures.first
+    end
+
+    def reporter
+      @reporter ||= ::RSpec::Core::Reporter.new(::RSpec::Core::Configuration.new)
+    end
+
+    def run
+      self.class.subjects = []
+      RSpec.with_failure_notifier(failure_notifier) do
+        succeeded = example_group.run(reporter)
+        durations << run_time if run_time
+        next succeeded if succeeded
+
+        notify_failure(reported_failure)
+        succeeded
+      end
+    end
+
+    private
+
+    attr_reader :spec, :failures
+
+    def subjects
+      self.class.subjects
+    end
+
+    def durations
+      self.class.durations
+    end
+
+    def examples
+      @examples ||= example_group.examples
+    end
+
+    def example_group
+      # rubocop:disable Style/DocumentDynamicEvalDefinition, Security/Eval
+      @example_group ||= binding.eval(
+        <<-SPEC, __FILE__, __LINE__.to_i
+          ::RSpec::Core::ExampleGroup.describe do
+            after { RSpecDocumentation::Spec.subjects << subject }
+            include_context '__rspec_documentation' do
+              #{spec}
+            end
+          end
+        SPEC
+      )
+      # rubocop:enable Style/DocumentDynamicEvalDefinition, Security/Eval
+    end
+
+    def run_time
+      return nil unless reporter&.examples&.first
+
+      @run_time ||= reporter.examples.first.execution_result.run_time
+    end
+
+    def notify_failure(failure)
+      failures << RSpec::Failure.new(cause: failure, spec: self)
+    end
+
+    def reported_failure
+      exception = reporter.failed_examples.first.exception
+      return exception unless exception.is_a?(::RSpec::Core::MultipleExceptionError)
+
+      exception.all_exceptions.first
+    end
+
+    def failure_notifier
+      proc { |failure| notify_failure(failure) }
+    end
+  end
+end

data/lib/rspec_documentation/stylesheet_bundle.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Compiles CSS assets into a single file.
+  class StylesheetBundle
+    def flush
+      Util.bundle_dir.join('assets').mkpath
+      stylesheet_bundle_path.write(RSpecDocumentation.template(:layout, :css).result(binding))
+    end
+
+    private
+
+    def stylesheet_bundle_path
+      Util.bundle_dir.join('assets/bundle.css')
+    end
+  end
+end