rundoc 4.1.3 → 5.0.0

data/lib/rundoc/code_command/website/screenshot.rb

@@ -1,9 +1,23 @@
+# frozen_string_literal: true
+
 class Rundoc::CodeCommand::Website
-  class Screenshot < Rundoc::CodeCommand
+  class ScreenshotArgs
+    attr_reader :name, :upload
+
     def initialize(name:, upload: false)
       @name = name
       @upload = upload
+    end
+  end
+
+  class ScreenshotRunner
+    attr_reader :io
+
+    def initialize(user_args:, render_command:, render_result:, io:, contents: nil)
+      @name = user_args.name
+      @upload = user_args.upload
       @driver = nil
+      @io = io
     end
 
     def driver
@@ -15,7 +29,7 @@ class Rundoc::CodeCommand::Website
     end
 
     def call(env = {})
-      puts "Taking screenshot: #{driver.current_url}"
+      io.puts "Taking screenshot: #{driver.current_url}"
       filename = driver.screenshot(
         upload: @upload,
         screenshots_dir: env[:context].screenshots_dir
@@ -25,14 +39,6 @@ class Rundoc::CodeCommand::Website
       env[:before] << "![Screenshot of #{driver.current_url}](#{relative_filename})"
       ""
     end
-
-    # def hidden?
-    #   true
-    # end
-
-    # def not_hidden?
-    #   !hidden?
-    # end
   end
 end
-Rundoc.register_code_command(:"website.screenshot", Rundoc::CodeCommand::Website::Screenshot)
+Rundoc.register_code_command(keyword: :"website.screenshot", args_klass: Rundoc::CodeCommand::Website::ScreenshotArgs, runner_klass: Rundoc::CodeCommand::Website::ScreenshotRunner)

data/lib/rundoc/code_command/website/visit.rb

@@ -1,14 +1,33 @@
 # frozen_string_literal: true
 
 class Rundoc::CodeCommand::Website
-  class Visit < Rundoc::CodeCommand
-    def initialize(name:, url: nil, scroll: nil, height: 720, width: 1024, visible: false)
+  class VisitArgs
+    attr_reader :name, :url, :scroll, :height, :width, :visible, :max_attempts
+
+    def initialize(name:, url: nil, scroll: nil, height: 720, width: 1024, visible: false, max_attempts: 3)
       @name = name
       @url = url
       @scroll = scroll
       @height = height
       @width = width
       @visible = visible
+      @max_attempts = max_attempts
+    end
+  end
+
+  class VisitRunner
+    attr_reader :io, :contents
+
+    def initialize(user_args:, render_command:, render_result:, io:, contents: nil)
+      @name = user_args.name
+      @url = user_args.url
+      @scroll = user_args.scroll
+      @height = user_args.height
+      @width = user_args.width
+      @visible = user_args.visible
+      @max_attempts = user_args.max_attempts
+      @io = io
+      @contents = contents.dup if contents && !contents.empty?
     end
 
     def driver
@@ -17,7 +36,8 @@ class Rundoc::CodeCommand::Website
         url: @url,
         height: @height,
         width: @width,
-        visible: @visible
+        visible: @visible,
+        io: io
       ).tap do |driver|
         Driver.add(@name, driver)
       end
@@ -31,9 +51,9 @@ class Rundoc::CodeCommand::Website
       message = "Visting: #{@url}"
       message << "and executing:\n#{contents}" unless contents.nil? || contents.empty?
 
-      puts message
+      io.puts message
 
-      driver.visit(@url) if @url
+      driver.visit(@url, max_attempts: @max_attempts) if @url
       driver.scroll(@scroll) if @scroll
 
       return "" if contents.nil? || contents.empty?
@@ -41,15 +61,7 @@ class Rundoc::CodeCommand::Website
 
       ""
     end
-
-    def hidden?
-      true
-    end
-
-    def not_hidden?
-      !hidden?
-    end
   end
 end
 
-Rundoc.register_code_command(:"website.visit", Rundoc::CodeCommand::Website::Visit)
+Rundoc.register_code_command(keyword: :"website.visit", args_klass: Rundoc::CodeCommand::Website::VisitArgs, runner_klass: Rundoc::CodeCommand::Website::VisitRunner)

data/lib/rundoc/code_command/website.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Rundoc::CodeCommand::Website
 end
 

data/lib/rundoc/code_command/write.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module Rundoc
-  class CodeCommand
+  module CodeCommand
     module FileUtil
       def filename
         files = Dir.glob(@filename)
@@ -15,16 +17,42 @@ module Rundoc
       end
     end
 
-    class Write < Rundoc::CodeCommand
-      include FileUtil
+    class WriteArgs
+      attr_reader :path
+
+      def initialize(path)
+        @path = Pathname(path)
+      end
+    end
+
+    class WriteRunner
+      NEWLINE = Object.new
+      def NEWLINE.to_s
+        ""
+      end
+
+      def NEWLINE.empty?
+        false
+      end
+
+      include Rundoc::CodeCommand::FileUtil
+
+      attr_reader :io, :contents
+
+      def initialize(user_args:, render_command:, render_result:, io:, contents: nil)
+        @filename = user_args.path.to_s
+        @io = io
+        @render_command = render_command
+        @contents = contents.dup if contents && !contents.empty?
+      end
 
-      def initialize(filename)
-        @filename = filename
+      def render_command?
+        @render_command
       end
 
       def to_md(env)
         if render_command?
-          if env[:commands].any? { |c| c[:object].not_hidden? }
+          if env[:commands].any? { |c| c[:visibility].not_hidden? }
             raise "must call write in its own code section"
           end
           env[:before] << "In file `#{filename}` write:"
@@ -34,7 +62,7 @@ module Rundoc
       end
 
       def call(env = {})
-        puts "Writing to: '#{filename}'"
+        io.puts "Writing to: '#{filename}'"
         mkdir_p
         File.write(filename, contents)
         contents
@@ -43,8 +71,8 @@ module Rundoc
   end
 end
 
-Rundoc.register_code_command(:write, Rundoc::CodeCommand::Write)
-Rundoc.register_code_command(:"file.write", Rundoc::CodeCommand::Write)
+Rundoc.register_code_command(keyword: :write, args_klass: Rundoc::CodeCommand::WriteArgs, runner_klass: Rundoc::CodeCommand::WriteRunner)
+Rundoc.register_code_command(keyword: :"file.write", args_klass: Rundoc::CodeCommand::WriteArgs, runner_klass: Rundoc::CodeCommand::WriteRunner)
 
 require "rundoc/code_command/file_command/append"
 require "rundoc/code_command/file_command/remove"

data/lib/rundoc/code_command.rb

@@ -1,55 +1,11 @@
-module Rundoc
-  # Generic CodeCommand class to be inherited
-  #
-  class CodeCommand
-    # Newlines are stripped and re-added, this tells the project that
-    # we're intentionally wanting an extra newline
-    NEWLINE = Object.new
-    def NEWLINE.to_s
-      ""
-    end
-
-    def NEWLINE.empty?
-      false
-    end
-
-    attr_accessor :render_result, :render_command,
-      :command, :contents, :keyword,
-      :original_args
-
-    alias_method :render_result?, :render_result
-    alias_method :render_command?, :render_command
-
-    def initialize(*args)
-    end
+# frozen_string_literal: true
 
-    def hidden?
-      !render_command? && !render_result?
-    end
-
-    def not_hidden?
-      !hidden?
-    end
-
-    def push(contents)
-      @contents ||= ""
-      @contents << contents
-    end
-    alias_method :<<, :push
-
-    # Executes command to build project
-    # Is expected to return the result of the command
-    def call(env = {})
-      raise "not implemented on #{inspect}"
-    end
-
-    # the output of the command, i.e. `$ cat foo.txt`
-    def to_md(env = {})
-      raise "not implemented on #{inspect}"
-    end
+module Rundoc
+  module CodeCommand
   end
 end
 
+require "rundoc/code_command/deferred"
 require "rundoc/code_command/bash"
 require "rundoc/code_command/pipe"
 require "rundoc/code_command/write"
@@ -61,3 +17,4 @@ require "rundoc/code_command/website"
 require "rundoc/code_command/print/text"
 require "rundoc/code_command/print/erb"
 require "rundoc/code_command/pre/erb"
+require "rundoc/code_command/comment"

data/lib/rundoc/context/after_build.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rundoc
   module Context
     # Public interface for the `Rundoc.after_build` proc

data/lib/rundoc/context/execution.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rundoc
   module Context
     # Holds configuration for the currently executing script

data/lib/rundoc/document.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rundoc
   # Represents a single rundoc file on disk,
   #
@@ -11,7 +13,8 @@ module Rundoc
 
     attr_reader :contents, :stack, :context
 
-    def initialize(contents, context:)
+    def initialize(contents, context:, io: $stdout)
+      @io = io
       @context = context
       @contents = contents
       @original = contents.dup
@@ -59,7 +62,8 @@ module Rundoc
             fence: match[:fence],
             lang: match[:lang],
             code: match[:contents],
-            context: context
+            context: context,
+            io: @io
           )
         end
         @contents = tail

data/lib/rundoc/fenced_code_block.rb

@@ -15,7 +15,7 @@ module Rundoc
     def executed_commands
       raise "Nothing executed" unless @env[:commands].any?
 
-      @env[:commands].map { |c| c[:object] }
+      @env[:commands].map { |c| c[:visibility] }
     end
 
     # @param fence [String] the fence used to start the code block like "```".
@@ -24,7 +24,8 @@ module Rundoc
     # @param code [String] the code block contents inside the fence.
     # @param context [Context::Execution] The details about where
     #        the code block came from.
-    def initialize(fence:, lang:, code:, context:)
+    def initialize(fence:, lang:, code:, context:, io: $stdout)
+      @io = io
       @fence = fence
       @lang = lang
       @code = code
@@ -54,12 +55,13 @@ module Rundoc
       env[:after] = []
       env[:context] = @context
       env[:stack] = @stack
+      while (item = @stack.pop)
+        code_command = item.build(io: @io)
 
-      while (code_command = @stack.pop)
         code_output = code_command.call(env) || ""
         code_line = code_command.to_md(env) || ""
-        result << code_line if code_command.render_command?
-        result << code_output if code_command.render_result?
+        result << code_line if item.render_command?
+        result << code_output if item.render_result?
 
         PARTIAL_RESULT.replace(result)
         PARTIAL_ENV.replace(env)
@@ -67,11 +69,12 @@ module Rundoc
         env[:commands] << {
           object: code_command,
           output: code_output,
-          command: code_line
+          command: code_line,
+          visibility: item
         }
       end
 
-      if env[:commands].any? { |c| c[:object].not_hidden? }
+      if env[:commands].any? { |c| c[:visibility].not_hidden? }
         @rendered = self.class.to_doc(result: result, env: env)
       end
       self

data/lib/rundoc/peg_parser.rb

@@ -1,9 +1,12 @@
+# frozen_string_literal: true
+
 require "parslet"
 
 module Rundoc
   class PegParser < Parslet::Parser
     rule(:spaces) { match('\s').repeat(1) }
     rule(:spaces?) { spaces.maybe }
+    rule(:horizontal_spaces) { match('[ \t]').repeat(1) }
     rule(:comma) { spaces? >> str(",") >> spaces? }
     rule(:digit) { match("[0-9]") }
     rule(:lparen) { str("(") >> spaces? }
@@ -87,7 +90,7 @@ module Rundoc
     }
 
     rule(:seattle_method) {
-      funcall >> spaces >>
+      funcall >> horizontal_spaces >>
         args.as(:args)
     }
 
@@ -242,8 +245,8 @@ module Rundoc
         raise TransformError.new(message: message, line_and_column: line_and_column)
       end
       Visability.new(
-        command: command.to_s == ">".freeze,
-        result: result.to_s == ">".freeze
+        command: command.to_s == ">",
+        result: result.to_s == ">"
       )
     }
 
@@ -265,16 +268,21 @@ module Rundoc
       code_command
     }
 
-    # The lines before a CodeCommand are rendered
-    # without running any code
     rule(raw_code: simple(:raw_code)) {
-      CodeCommand::Raw.new(raw_code)
+      deferred = CodeCommand::Deferred.new(args_instance: nil, runner_klass: CodeCommand::Raw)
+      deferred.render_command = false
+      deferred.render_result = true
+      deferred.push(raw_code.to_s)
+      deferred
     }
 
-    # Sometimes
     rule(raw_code: sequence(:raw_code)) {
-      hidden = raw_code.nil? || raw_code.empty?
-      CodeCommand::Raw.new(raw_code, visible: !hidden)
+      visible = !raw_code.nil? && !raw_code.empty?
+      deferred = CodeCommand::Deferred.new(args_instance: nil, runner_klass: CodeCommand::Raw)
+      deferred.render_command = false
+      deferred.render_result = visible
+      deferred.push(raw_code.map(&:to_s).join)
+      deferred
     }
   end
 end

data/lib/rundoc/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rundoc
-  VERSION = "4.1.3"
+  VERSION = "5.0.0"
 end

data/lib/rundoc.rb

@@ -5,43 +5,78 @@ require "rundoc/version"
 module Rundoc
   extend self
 
+  class UnknownCommand < StandardError; end
+
   def code_command_from_keyword(keyword, args)
-    klass = code_command(keyword.to_sym) || Rundoc::CodeCommand::NoSuchCommand
-    original_args = args.dup
-    if args.is_a?(Array) && args.last.is_a?(Hash)
-      kwargs = args.pop
-      cc = klass.new(*args, **kwargs)
-    elsif args.is_a?(Hash)
-      cc = klass.new(**args)
+    args_klass = code_command(keyword.to_sym)
+    original_args = args&.dup
+
+    if args_klass
+      runner_klass = user_args_runner[keyword]
+
+      if args.is_a?(Array) && args.last.is_a?(Hash)
+        kwargs = args.pop
+        user_args = args_klass.new(*args, **kwargs)
+      elsif args.is_a?(Hash)
+        user_args = args_klass.new(**args)
+      else
+        user_args = args_klass.new(*args)
+      end
+    elsif keyword.start_with?("#")
+      args_klass = Rundoc::CodeCommand::CommentArgs
+      runner_klass = Rundoc::CodeCommand::CommentRunner
+      remainder = keyword.to_s.delete_prefix("#")
+      comment_text = [remainder, args].compact.join(" ").strip
+      user_args = args_klass.new(comment_text.empty? ? nil : comment_text)
     else
-      cc = klass.new(*args)
+      runner_klass = Rundoc::CodeCommand::NoSuchCommand
+      user_args = nil
     end
 
-    cc.original_args = original_args
-    cc.keyword = keyword
-    cc
+    deferred = CodeCommand::Deferred.new(
+      args_instance: user_args,
+      runner_klass: runner_klass,
+      always_hidden: always_hidden_commands[keyword] || keyword.start_with?("#")
+    )
+    deferred.original_args = original_args
+    deferred.keyword = keyword
+    deferred
   rescue ArgumentError => e
     raise ArgumentError, "Wrong method signature for #{keyword} with arguments: #{original_args.inspect}, error:\n #{e.message}"
   end
 
+  def user_code_runner_klass
+    @user_code_runner_klass ||= {}
+  end
+
   def parser_options
     @parser_options ||= {}
   end
 
-  def code_lookup
-    @code_lookup ||= {}
+  def user_args_runner
+    @user_args_runner ||= {}
+  end
+
+  def user_args
+    @user_args ||= {}
   end
 
   def code_command(keyword)
-    code_lookup[:"#{keyword}"]
+    user_args[:"#{keyword}"]
   end
 
   def known_commands
-    code_lookup.keys
+    user_args.keys
+  end
+
+  def register_code_command(keyword:, args_klass:, runner_klass:, always_hidden: false)
+    user_args[keyword] = args_klass
+    user_args_runner[keyword] = runner_klass
+    always_hidden_commands[keyword] = always_hidden
   end
 
-  def register_code_command(keyword, klass)
-    code_lookup[keyword] = klass
+  def always_hidden_commands
+    @always_hidden_commands ||= {}
   end
 
   def configure(&block)

data/rundoc.gemspec

@@ -16,6 +16,8 @@ Gem::Specification.new do |gem|
   gem.executables = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
   gem.require_paths = ["lib"]
 
+  gem.required_ruby_version = ">= 3.2"
+
   gem.add_dependency "thor"
   gem.add_dependency "parslet", "~> 2"
   gem.add_dependency "capybara", "~> 3"

data/test/integration/background_stdin_test.rb

@@ -6,21 +6,7 @@ class BackgroundStdinTest < Minitest::Test
       Dir.chdir(dir) do
         dir = Pathname(dir)
         script = dir.join("script.rb")
-        script.write <<~'EOF'
-          $stdout.sync = true
-
-          print "> "
-          while line = gets
-            puts line
-            if line.strip == "exit"
-              puts "Bye"
-              return
-            else
-              puts "You said: #{line}"
-            end
-            print "> "
-          end
-        EOF
+        script.write loop_script
 
         source_path = dir.join("RUNDOC.md")
         source_path.write <<~EOF
@@ -54,4 +40,68 @@ class BackgroundStdinTest < Minitest::Test
       end
     end
   end
+
+  def test_print_output_on_exit
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        script = dir.join("script.rb")
+        script.write loop_script
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- background.start("ruby #{script}",
+            name: "background_ungraceful_exit",
+            wait: ">",
+            timeout: 15
+          )
+          :::-- background.stdin_write("hello", name: "background_ungraceful_exit", wait: "hello")
+          ```
+        EOF
+
+        io = StringIO.new
+        Rundoc::CLI.new(
+          io: io,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        logs = io.string
+
+        match_after = partition_match_after(actual: logs, include_str: "Warning background task is still running, cleaning up: `background_ungraceful_exit`")
+        match_after = partition_match_after(actual: match_after, include_str: "Log contents for `/usr/bin/env bash -c")
+        partition_match_after(actual: match_after, include_str: "> hello")
+      end
+    end
+  end
+
+  # Finds the include_str if it exists or raises an error
+  # Returns the contents of that string and everything after it
+  #
+  # Used to handle the case where output might be in the logs twice and we want to verify the order
+  def partition_match_after(actual:, include_str:)
+    _before, match, after = actual.partition(include_str)
+    found = match && !match.empty?
+    assert found, "Expected to find `#{include_str}` in output, but did not. Output:\n#{actual}"
+    [match, after].join
+  end
+
+  def loop_script
+    <<~'EOF'
+      $stdout.sync = true
+
+      print "> "
+      while line = gets
+        puts line
+        if line.strip == "exit"
+          puts "Bye"
+          return
+        else
+          puts "You said: #{line}"
+        end
+        print "> "
+      end
+    EOF
+  end
 end

data/test/integration/website_test.rb

@@ -34,4 +34,23 @@ class IntegrationWebsiteTest < Minitest::Test
       end
     end
   end
+
+  def test_retry_client_closed_early
+    tcp_unexpected_exit do |port|
+      io = StringIO.new
+      driver = Rundoc::CodeCommand::Website::Driver.new(name: SecureRandom.hex, url: nil, read_timeout: 0.1, io: io)
+      assert_raises(Net::ReadTimeout) do
+        driver.visit("http://localhost:#{port}", max_attempts: 3, delay: 0)
+      end
+
+      logs = io.string
+      assert_logs_include(logs: logs, include_str: "Error visiting url (1/3)")
+      assert_logs_include(logs: logs, include_str: "Error visiting url (2/3)")
+      assert_logs_include(logs: logs, include_str: "Error visiting url (3/3)")
+    end
+  end
+
+  def assert_logs_include(logs:, include_str:)
+    assert logs.include?(include_str), "Expected logs to include #{include_str} but they didnt. Logs:\n#{logs}"
+  end
 end